Where to Find the Hiring-Agent API Documentation: Complete Guide to InterviewStreet's Repository

The complete hiring-agent API documentation is embedded directly in the InterviewStreet repository's source code, with the primary programmatic interface documented in pdf.py, data schemas in models.py, and usage examples in README.md.

The interviewstreet/hiring-agent repository provides a self-contained resume processing system without external documentation portals. Instead of traditional API reference sites, this project embeds its hiring-agent API documentation within the codebase itself, making the source files the definitive specification for integration and usage.

Primary Documentation Locations in the Repository

README.md Overview

The README.md file at the repository root serves as the landing page for the hiring-agent API documentation. It contains high-level architecture descriptions, installation instructions, and the essential "CLI usage" section that demonstrates how to invoke the scoring pipeline from the command line.

Core Source Files as API Documentation

The actual API contract is defined through Python type hints and docstrings in specific modules. The models.py file contains the Pydantic schemas that define the JSON-Resume-compatible data structures, while pdf.py implements the extraction pipeline. Together, these files constitute the complete programmatic interface specification.

Essential API Components and Entry Points

PDF Extraction Pipeline (pdf.py)

The pdf.py module provides the primary programmatic entry point for the hiring-agent API. The PDFHandler class implements the end-to-end extraction pipeline, exposing the extract_json_from_pdf function. This function converts PDF resume files into structured JSON data according to the schema defined in models.py.

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. Evaluate the resume and obtain a scored report

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

print(evaluation)        # Human-readable summary

Data Schema Definitions (models.py)

Located at the repository root, models.py defines the JSON-Resume-compatible data structures that the API returns. Key models include Basics, Work, Project, and Education, all wrapped in the JSONResume Pydantic model. These classes serve as the formal API contract, specifying exact field names, types, and validation rules.

Evaluation and Scoring Engine (evaluator.py)

For resume scoring functionality, the evaluator.py module contains the Evaluator class. This component implements fairness-aware scoring logic and template rendering. When running the full pipeline programmatically, this module works in conjunction with github.py for GitHub profile enrichment, which occurs automatically when GitHub URLs are detected in the resume.

Command Line Interface Reference

The score.py file serves as the CLI wrapper that orchestrates the full pipeline. According to the hiring-agent API documentation in the README, you can process resumes directly from the terminal:

python score.py path/to/resume.pdf

This command executes the same extraction and evaluation logic available programmatically, making it accessible for shell scripts and automation workflows.

Summary

• The hiring-agent API documentation is embedded directly in the interviewstreet/hiring-agent repository source code
• pdf.py contains the primary extraction entry point via PDFHandler.extract_json_from_pdf()
• models.py defines the JSON-Resume schema used for all API responses, including Basics, Work, and Project structures
• evaluator.py provides the scoring functionality with fairness-aware algorithms
• The CLI interface in score.py offers a command-line alternative to programmatic access

Frequently Asked Questions

Where is the hiring-agent API documentation hosted?

The documentation is not hosted on a separate documentation site. Instead, it exists as inline documentation within the Python source files—specifically README.md for high-level usage, pdf.py for extraction APIs, and models.py for data schemas—in the interviewstreet/hiring-agent repository.

What data format does the hiring-agent API return?

The API returns JSON-Resume-compatible structured data. The exact schema is defined by Pydantic models in models.py, including sections for Basics (contact info), Work experience, Education, and Projects, providing a standardized, machine-readable resume format that conforms to the JSON Resume standard.

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

Import the PDFHandler class from pdf.py and call the extract_json_from_pdf() method with the file path. This function handles PDF-to-markdown conversion, LLM-powered section parsing, and returns a JSONResume object containing the structured data, as implemented in the pdf.py source file.

Is there a REST endpoint for the hiring-agent API?

The repository does not expose a REST endpoint by default. It is designed as a Python library with a CLI interface. However, the PDFHandler and Evaluator classes in pdf.py and evaluator.py provide the core functionality that could be wrapped in a web framework to create REST endpoints if needed for your specific deployment.

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