Available API Endpoints for Hiring-Agent: Python Library Reference

Hiring-Agent does not expose HTTP API endpoints; instead, it provides a Python library interface through modules like score.py, pdf.py, and evaluator.py that you import and call programmatically.

The interviewstreet/hiring-agent repository is an LLM-powered resume evaluation toolkit designed as a self-contained command-line application. While developers frequently search for available API endpoints to integrate with the tool, the architecture intentionally omits a network server layer in favor of direct Python module imports. All programmatic interactions happen through the Python API classes and functions defined across the core source files.

Why There Are No HTTP REST Endpoints

Hiring-Agent is built as a command-line application rather than a web service. According to the source code in interviewstreet/hiring-agent, the repository contains no HTTP server, router, or controller logic that would typically define REST or GraphQL endpoints. Instead, the "API" consists of public Python functions and classes that orchestrate PDF parsing, GitHub enrichment, and LLM-based evaluation. This design keeps the tool lightweight and avoids the operational complexity of managing a persistent network service.

Available Python API Entry Points

The public programmatic interface exposes several key entry points across specific modules. Each function follows type-annotated signatures returning structured Pydantic models.

The Main Orchestrator: score.main()

The primary entry point for running the full evaluation pipeline is located in score.py at line 14. The function signature is:

score.main(pdf_path: str) -> EvaluationData

This function orchestrates the complete workflow: PDF parsing, optional caching, GitHub profile enrichment, LLM evaluation, and structured result generation. When invoked directly, it performs the same operations as the CLI command python score.py <resume-pdf>.

PDF Processing with PDFHandler

For lower-level resume extraction, pdf.py (line 39) exposes the PDFHandler class. Its key method extracts structured data from PDF files:

PDFHandler.extract_json_from_pdf(pdf_path: str) -> JSONResume

Located at line 199 in pdf.py, this method parses the PDF using PyMuPDF, converts pages to markdown, and extracts resume sections by prompting the LLM. It returns a JSONResume Pydantic model containing standardized candidate data.

GitHub Profile Enrichment

To augment resumes with GitHub data, github.py (line 459) provides the standalone function:

fetch_and_display_github_info(github_url: str) -> dict

This utility fetches profile details, repository lists, and contribution statistics, returning a plain dictionary ready for the evaluator. It handles API authentication and caching internally.

Resume Evaluation Engine

The core scoring logic resides in evaluator.py (line 25) within the ResumeEvaluator class:

ResumeEvaluator.evaluate_resume(resume_text: str) -> EvaluationData

This method sends the assembled resume text (including any GitHub enrichment) to the configured LLM provider and parses the response into a structured EvaluationData object containing category scores and assessments.

Data Transformation Utilities

Located in transform.py (line 6), helper functions convert raw LLM JSON responses into the unified JSONResume schema and transform evaluation results into CSV-compatible formats. These utilities follow the naming convention transform_* and standardize data exchange between pipeline stages.

Working Code Examples

You can interact with Hiring-Agent either through the high-level orchestrator or by composing the low-level building blocks manually.

Running the full pipeline from a script:

from score import main as run_hiring_agent

# Path to a local resume PDF

pdf_path = "my_resume.pdf"

# Execute the pipeline; returns an EvaluationData object

evaluation = run_hiring_agent(pdf_path)

# Access structured scores directly

print(evaluation.scores.open_source.score)

Using low-level components for granular control:

from pdf import PDFHandler
from github import fetch_and_display_github_info
from evaluator import ResumeEvaluator
from models import JSONResume
from transform import convert_json_resume_to_text, convert_github_data_to_text

# 1️⃣ Parse the PDF

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

# 2️⃣ (Optional) Enrich with GitHub data

github_url = next(
    (p.url for p in resume.basics.profiles or [] if p.network.lower() == "github"),
    None,
)
github_data = fetch_and_display_github_info(github_url) if github_url else {}

# 3️⃣ Assemble the textual resume for the LLM

resume_text = convert_json_resume_to_text(resume)
if github_data:
    resume_text += convert_github_data_to_text(github_data)

# 4️⃣ Evaluate

evaluator = ResumeEvaluator()
result = evaluator.evaluate_resume(resume_text)

print(f"Overall score: {result.scores.open_source.score}")

Key Source Files and Their Roles

Understanding the module structure helps identify which file to import for specific functionality:

• score.py — CLI driver that orchestrates caching, PDF parsing, GitHub enrichment, and final report printing
• pdf.py — PDF-to-markdown conversion and section extraction via LLM prompts
• github.py — GitHub API wrapper for profile and repository fetching with built-in caching
• evaluator.py — LLM-based scoring logic and fairness constraint enforcement
• models.py — Pydantic schemas defining JSONResume and EvaluationData structures
• transform.py — Helpers that normalize LLM output and prepare CSV export rows
• prompt.py — Centralizes LLM provider selection (OLLAMA or GEMINI)
• config.py — Configuration flags including DEVELOPMENT_MODE settings

Summary

• Hiring-Agent has no HTTP endpoints — it is a CLI tool and Python library, not a web service.
• Primary entry point — score.main(pdf_path: str) in score.py runs the complete evaluation pipeline.
• Modular components — PDFHandler, fetch_and_display_github_info, and ResumeEvaluator allow custom workflows.
• Type-safe returns — All functions return Pydantic models (JSONResume, EvaluationData) defined in models.py.
• Self-contained architecture — All processing happens locally through Python imports; no external API specification exists.

Frequently Asked Questions

Does Hiring-Agent provide REST API endpoints?

No, Hiring-Agent does not expose REST, GraphQL, or any HTTP endpoints. According to the interviewstreet/hiring-agent source code, the tool is architected as a local command-line application that processes resume PDFs without starting a network server.

How do I programmatically interact with Hiring-Agent?

You import the Python modules directly into your application codebase. The primary interface is score.main() function in score.py, though you may also compose lower-level components like PDFHandler for parsing and ResumeEvaluator for scoring individual resumes.

What data format does the evaluation return?

The evaluation pipeline returns structured Pydantic models defined in models.py. Specifically, score.main() and ResumeEvaluator.evaluate_resume() return an EvaluationData object containing scored categories, while PDFHandler.extract_json_from_pdf() returns a standardized JSONResume model.

Can I run Hiring-Agent as a web service?

While the repository contains no built-in web server, you could wrap the Python API in a FastAPI or Flask application to expose HTTP endpoints. This would require implementing your own routing layer around functions like score.main() and securely managing LLM provider credentials.

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