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

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 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 to extract structured JSON from each resume section.
• GitHub enrichment: The github.py module provides fetch_github_profile() to look up candidate repositories and select relevant projects.
• Evaluation: The evaluator.py module implements ResumeEvaluator, which applies fairness-aware scoring rules and produces detailed evaluations.
• Provider abstraction: The 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 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 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 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.

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:

# 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: 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: Queries GitHub API, normalizes profile data, and selects projects via fetch_github_profile().
• evaluator.py: Implements fairness-aware scoring logic in ResumeEvaluator.evaluate_resume().
• score.py: CLI orchestrator demonstrating how to serialize results to CSV.
• models.py: Pydantic schemas and LLMProvider protocol for provider-agnostic integrations.
• 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, ResumeEvaluator in evaluator.py, and the data classes JSONResume and EvaluationData in models.py.
• The LLM provider abstraction in 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 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 entirely and feed your extracted text directly into the LLM parsing step. The PDFHandler class in 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, 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, or direct database insertion in your HR system.

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