# Available API Endpoints for Hiring-Agent: Python Library Reference

> Explore the Hiring-Agent Python library reference for available API endpoints. Learn how to programmatically use modules like score.py, pdf.py, and evaluator.py for your hiring needs.

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

---

**Hiring-Agent does not expose HTTP API endpoints; instead, it provides a Python library interface through modules like [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) at line 14. The function signature is:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) (line 39) exposes the `PDFHandler` class. Its key method extracts structured data from PDF files:

```python
PDFHandler.extract_json_from_pdf(pdf_path: str) -> JSONResume

```

Located at line 199 in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) (line 459) provides the standalone function:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) (line 25) within the `ResumeEvaluator` class:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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:**

```python
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:**

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** — CLI driver that orchestrates caching, PDF parsing, GitHub enrichment, and final report printing
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** — PDF-to-markdown conversion and section extraction via LLM prompts
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** — GitHub API wrapper for profile and repository fetching with built-in caching
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** — LLM-based scoring logic and fairness constraint enforcement
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** — Pydantic schemas defining `JSONResume` and `EvaluationData` structures
- **[`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py)** — Helpers that normalize LLM output and prepare CSV export rows
- **[`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py)** — Centralizes LLM provider selection (OLLAMA or GEMINI)
- **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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.