# Hiring Agent API Documentation: Complete Reference for InterviewStreet's Hiring Agent

> Access complete InterviewStreet Hiring Agent API documentation within the repository. Explore the README and Python modules for essential details and integration guidance.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: api-reference
- Published: 2026-07-24

---

**The InterviewStreet hiring-agent repository contains comprehensive API documentation embedded directly in the source code, with the [`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md) providing high-level architecture details and Python modules like [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) defining the complete programmatic interface for resume extraction and scoring.**

Unlike traditional API documentation hosted on external sites, the `interviewstreet/hiring-agent` project treats its source files as the authoritative hiring agent API documentation. All essential schemas, entry points, and usage patterns are documented within the repository's README and implementation files, making the codebase itself the definitive reference for integrating with or extending the hiring agent's capabilities.

## Where to Find the Hiring Agent API Documentation

The hiring agent API documentation is distributed across several key files in the repository root, each serving a specific documentation purpose.

- **[`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md)** provides the high-level architecture overview, installation instructions, and CLI usage examples for scoring resumes from the command line.
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** documents the core extraction pipeline, including the `PDFHandler` class and the `extract_json_from_pdf` function that serves as the primary programmatic entry point.
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** contains the complete Pydantic schema definitions for all JSON-Resume-compatible data structures returned by the API.
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** and **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** detail the evaluation logic and GitHub enrichment capabilities, respectively.
- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** acts as the CLI wrapper that orchestrates the full pipeline.

Together, these files constitute the self-contained hiring agent API documentation.

## Core API Components

### PDF Processing Pipeline ([`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py))

The **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** module implements the end-to-end extraction pipeline and exposes the primary programmatic interface through the `PDFHandler` class.

The **`extract_json_from_pdf`** function converts resume PDFs into structured JSON by first transforming the document to Markdown, then using LLM-based section parsing to identify standard resume fields. This function returns a `JSONResume` object (defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)) containing parsed data including work history, projects, and skills.

### Data Schema Definitions ([`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py))

All API responses conform to the JSON-Resume standard as implemented in **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)**. This module defines Pydantic models for every resume section:

- **`Basics`**: Contact information and personal details
- **`Work`**: Employment history entries
- **`Project`**: Personal or professional projects
- **`Education`**, **`Skills`**, **`Languages`**, and **`References`**: Additional standard sections

These schemas serve as both the data validation layer and the API contract documentation, specifying exactly which fields the hiring agent API returns and their expected types.

### Evaluation Engine ([`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py))

The **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** module contains the **`Evaluator`** class, which implements fairness-aware scoring logic and template rendering. When you need to run the full scoring pipeline programmatically, this class evaluates the structured resume data and generates human-readable assessment reports.

### GitHub Enrichment ([`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py))

The **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** module provides utilities for fetching and enriching resume data with GitHub profile information. When the pipeline detects a GitHub profile in the resume, it automatically invokes this module to append repository statistics and contribution data to the candidate profile.

## Programmatic Usage Examples

To use the hiring agent API programmatically, import the core components from their respective modules and follow the extraction-to-evaluation workflow:

```python

# Example: programmatic use of the Hiring Agent API

from pdf import PDFHandler               # main extraction pipeline

from evaluator import Evaluator          # scoring / fairness evaluator

from models import JSONResume            # pydantic schema for the result

# 1️⃣ Extract structured data from a resume PDF

handler = PDFHandler()
resume: JSONResume = handler.extract_json_from_pdf("sample_resume.pdf")

# 2️⃣ (Optional) Enrich with GitHub data – done automatically inside

#    the pipeline if a GitHub profile is detected.

# 3️⃣ Evaluate the resume and obtain a scored report

evaluator = Evaluator()
evaluation = evaluator.evaluate_resume(resume.json())

print(evaluation)        # human‑readable summary

```

The `extract_json_from_pdf` method handles the complex pipeline of PDF-to-Markdown conversion, LLM prompting, and schema validation, returning a fully typed `JSONResume` object ready for evaluation or further processing.

## Command Line Interface

For command-line usage, the **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** file provides a CLI wrapper that orchestrates the same pipeline:

```bash

# Example: CLI usage (the same steps as above)

$ python score.py path/to/resume.pdf

```

This command instantiates `PDFHandler` to extract the resume data, runs the automatic GitHub enrichment if applicable, and outputs the evaluation report directly to the terminal.

## Summary

- The **hiring agent API documentation** resides entirely within the `interviewstreet/hiring-agent` repository, with no external documentation site required.
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** contains the main entry point `extract_json_from_pdf` and the `PDFHandler` class for PDF-to-JSON conversion.
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** defines the JSON-Resume-compatible Pydantic schemas that specify the API response structure.
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** provides the `Evaluator` class for programmatic scoring and fairness evaluation.
- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** offers a convenient CLI interface for end-to-end resume processing without writing Python code.
- The **`prompts/`** directory and **[`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py)** file contain supporting templates and normalization logic used throughout the extraction pipeline.

## Frequently Asked Questions

### Where is the official hiring agent API documentation hosted?

According to the InterviewStreet hiring-agent source code, the official documentation is self-contained within the repository itself. The [`README.md`](https://github.com/interviewstreet/hiring-agent/blob/main/README.md) covers high-level usage and CLI commands, while Python files like [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) serve as the detailed API reference through their implementations, type hints, and docstrings.

### What data format does the hiring agent API return?

The API returns JSON-Resume-compatible data structures defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py). Specifically, the `JSONResume` Pydantic model encapsulates standard sections including `Basics` (contact info), `Work` (employment history), `Project` (portfolio items), `Education`, and `Skills`, ensuring consistent schema validation across all extraction operations.

### How do I extract data from a PDF using the hiring agent API?

Import `PDFHandler` from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and call the `extract_json_from_pdf` method with the file path as an argument. This function orchestrates the complete pipeline including PDF parsing, Markdown conversion, LLM-based section extraction, and schema validation, returning a fully populated `JSONResume` object.

### Is there a command-line interface for the hiring agent?

Yes. The repository includes **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**, a CLI wrapper that executes the full pipeline. Run `python score.py path/to/resume.pdf` to extract, enrich, and evaluate a resume without writing any Python code, producing the same results as the programmatic API.