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

The InterviewStreet hiring-agent repository contains comprehensive API documentation embedded directly in the source code, with the README.md providing high-level architecture details and Python modules like pdf.py, models.py, and 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 provides the high-level architecture overview, installation instructions, and CLI usage examples for scoring resumes from the command line.
• 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 contains the complete Pydantic schema definitions for all JSON-Resume-compatible data structures returned by the API.
• evaluator.py and github.py detail the evaluation logic and GitHub enrichment capabilities, respectively.
• 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)

The 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) containing parsed data including work history, projects, and skills.

Data Schema Definitions (models.py)

All API responses conform to the JSON-Resume standard as implemented in 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)

The 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)

The 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:

# 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 file provides a CLI wrapper that orchestrates the same pipeline:

# 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 contains the main entry point extract_json_from_pdf and the PDFHandler class for PDF-to-JSON conversion.
• models.py defines the JSON-Resume-compatible Pydantic schemas that specify the API response structure.
• evaluator.py provides the Evaluator class for programmatic scoring and fairness evaluation.
• score.py offers a convenient CLI interface for end-to-end resume processing without writing Python code.
• The prompts/ directory and 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 covers high-level usage and CLI commands, while Python files like pdf.py, models.py, and 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. 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}