# How to Integrate the Hiring-Agent with Other HR Systems: A Complete Technical Guide

> Integrate the hiring-agent with HR systems using its Python architecture. Discover methods like web APIs, CSV output, or component replacement in this technical guide.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-04

---

**The hiring-agent can be integrated with other HR systems through its modular Python architecture, either by importing its functions directly, wrapping it in a web API, consuming CSV output, or replacing individual components like the PDF parser or LLM provider.**

The interviewstreet/hiring-agent is a modular Python library designed for automated resume evaluation and candidate scoring. Because it separates concerns into distinct layers—from PDF ingestion to LLM parsing and fairness-aware evaluation—you can integrate the hiring-agent with other HR systems using several flexible approaches that preserve the pipeline's integrity while adapting to your existing infrastructure.

## Modular Architecture Enables Flexible Integration

The codebase organizes functionality into distinct layers, each exposing importable functions and data classes that facilitate external integration.

### Pipeline Layers

- **PDF ingestion**: The [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) module contains `PDFHandler`, which reads resumes and converts pages to Markdown-like text.
- **LLM parsing**: Jinja templates in `prompts/templates/*.jinja` work with [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) to extract structured JSON from each resume section.
- **GitHub enrichment**: The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module provides `fetch_github_profile()` to look up candidate repositories and select relevant projects.
- **Evaluation**: The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module implements `ResumeEvaluator`, which applies fairness-aware scoring rules and produces detailed evaluations.
- **Provider abstraction**: The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file defines the `LLMProvider` protocol and Pydantic schemas (`JSONResume`, `EvaluationData`), allowing you to swap Ollama, Gemini, or future providers without modifying pipeline logic.

## Four Methods to Integrate the Hiring-Agent

Because each stage is exposed as importable functions and data classes, you can embed the pipeline into any existing HR workflow using these four approaches.

### 1. Direct Library Integration

Import the high-level `score.evaluate_resume` function or lower-level components directly into your Python service. The `JSONResume` and `EvaluationData` classes in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) ensure type-safe data exchange between your HR system and the evaluation engine.

### 2. Web API Wrapper

Expose a thin HTTP layer using FastAPI or similar frameworks. This approach accepts a PDF file, runs the pipeline, and returns evaluation JSON, creating a language-agnostic interface for non-Python HR systems.

### 3. CSV Output Consumption

The CLI orchestrator in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) writes results to `resume_evaluations.csv`. Applicant tracking systems can ingest this file directly or process the generated dictionary for downstream workflows.

### 4. Component Replacement

If your HR system already provides a PDF parser, bypass [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) entirely and feed extracted text straight into the LLM parsing step. Disable GitHub enrichment by omitting the `github_data` argument when calling `_evaluate_resume`.

## Implementation Guide: FastAPI Integration

Deploy the hiring-agent as a standalone web service to integrate with any HR platform capable of making HTTP requests.

```python
from fastapi import FastAPI, UploadFile
from pdf import PDFHandler
from evaluator import ResumeEvaluator
from prompt import DEFAULT_MODEL, MODEL_PARAMETERS
from utils import convert_json_resume_to_text   # (see transform.py)

app = FastAPI()
evaluator = ResumeEvaluator(
    model_name=DEFAULT_MODEL,
    model_params=MODEL_PARAMETERS.get(DEFAULT_MODEL),
)

@app.post("/evaluate")
async def evaluate_resume(file: UploadFile):
    # Store the uploaded PDF temporarily

    path = f"/tmp/{file.filename}"
    with open(path, "wb") as f:
        f.write(await file.read())

    # Run the Hiring Agent pipeline

    pdf_handler = PDFHandler(pdf_path=path)
    json_resume = pdf_handler.process()
    resume_text = convert_json_resume_to_text(json_resume)
    eval_data = evaluator.evaluate_resume(resume_text)

    # Return JSON that any HR platform can consume

    return eval_data.model_dump()

```

Deploy this service alongside your HR platform and call `/evaluate` with a candidate's resume PDF. The response contains the same detailed scoring structure used by the CLI, including scores, bonuses, and deductions.

## Step-by-Step Integration Flow

For Python-based HR systems, embed the pipeline directly using this sequence:

```python

# 1️⃣ Load the PDF (or receive raw text from your HR system)

from pdf import PDFHandler
pdf_handler = PDFHandler(pdf_path="candidate_resume.pdf")
json_resume = pdf_handler.process()          # → JSONResume

# 2️⃣ (Optional) Enrich with GitHub data – you can skip this if not needed

from github import fetch_github_profile, fetch_and_display_github_info
github_info = fetch_github_profile(json_resume.basics.profiles[0].url)  # example

# 3️⃣ Run the evaluation

from evaluator import ResumeEvaluator
from prompt import DEFAULT_MODEL, MODEL_PARAMETERS
evaluator = ResumeEvaluator(
    model_name=DEFAULT_MODEL,
    model_params=MODEL_PARAMETERS.get(DEFAULT_MODEL),
)
evaluation = evaluator.evaluate_resume(
    convert_json_resume_to_text(json_resume) +
    convert_github_data_to_text(github_info)   # ➜ only if you have GitHub data

)

# 4️⃣ Return a plain dict that any HR system can ingest

result = evaluation.model_dump()   # → dict with scores, bonuses, deductions, etc.

```

This pattern allows you to intercept data at any stage. For example, you can replace the PDF loading step with your own text extraction and still leverage the `ResumeEvaluator` for consistent scoring.

## Key Integration Points

Understanding these core files helps you customize the integration:

- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)**: Handles PDF to Markdown conversion and LLM section calls. Entry point: `PDFHandler`.
- **`prompts/templates/*.jinja`**: Jinja templates defining how each resume section is parsed.
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)**: Queries GitHub API, normalizes profile data, and selects projects via `fetch_github_profile()`.
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)**: Implements fairness-aware scoring logic in `ResumeEvaluator.evaluate_resume()`.
- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**: CLI orchestrator demonstrating how to serialize results to CSV.
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)**: Pydantic schemas and `LLMProvider` protocol for provider-agnostic integrations.
- **[`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py)**: Helpers like `convert_json_resume_to_text()` for preparing LLM prompts.

## Summary

- The hiring-agent's modular architecture separates PDF ingestion, LLM parsing, GitHub enrichment, and evaluation into distinct layers you can import individually.
- You can integrate the hiring-agent with other HR systems by importing Python functions directly, wrapping them in a FastAPI service, consuming CSV output, or replacing specific components.
- Key entry points include `PDFHandler` in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), `ResumeEvaluator` in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), and the data classes `JSONResume` and `EvaluationData` in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).
- The LLM provider abstraction in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) allows swapping AI backends without touching evaluation logic, making the system provider-agnostic.
- GitHub enrichment is optional; omit the `github_data` argument to disable it.

## Frequently Asked Questions

### Can I integrate the hiring-agent with non-Python HR systems?

Yes. Wrap the pipeline in a FastAPI web service as shown in the implementation guide above. The `/evaluate` endpoint accepts PDF files via HTTP and returns JSON output, allowing any HR system capable of making REST API calls to utilize the evaluation engine regardless of programming language.

### How do I disable GitHub profile enrichment?

Simply omit the `github_data` argument when calling the evaluation function. The `ResumeEvaluator.evaluate_resume()` method in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) accepts text input without requiring GitHub data, making the enrichment step optional for integrations where social profile lookup is unnecessary or restricted.

### Can I replace the built-in PDF parser with my own extraction logic?

Yes. Bypass [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) entirely and feed your extracted text directly into the LLM parsing step. The `PDFHandler` class in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) is the default entry point, but you can provide pre-extracted text to `convert_json_resume_to_text()` or directly to the evaluator, allowing integration with enterprise PDF parsers or OCR systems already deployed in your HR infrastructure.

### What format does the evaluation output use?

The evaluation output uses Pydantic models defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), specifically `EvaluationData`. When you call `model_dump()` on the evaluation result, it returns a plain Python dictionary containing scores, bonuses, deductions, and structured feedback. This format is compatible with JSON serialization for APIs, CSV export via [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), or direct database insertion in your HR system.