# How to Integrate the Hiring Agent with Existing HR Tools: A Complete Technical Guide

> Integrate the Hiring Agent with your HR tools and ATS using its modular Python functions. This complete technical guide shows you how to seamlessly connect your application stack for efficient hiring.

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

---

**Yes, you can integrate the Hiring Agent with any existing HR tool, applicant tracking system (ATS), or talent management platform by importing its modular Python functions directly into your application stack.**

The interviewstreet/hiring-agent repository is architected as a loosely-coupled pipeline that converts resume PDFs into structured JSON evaluations. Because each processing stage—from PDF extraction to LLM scoring—is exposed as a standard Python function rather than a monolithic service, you can embed specific capabilities or the entire workflow into your existing infrastructure without architectural overhaul.

## Understanding the Modular Architecture

The Hiring Agent pipeline consists of discrete components that communicate through plain Python objects. This design allows you to cherry-pick specific functionality or orchestrate the complete workflow.

According to the source code, the core components include:

- **`pdf.PDFHandler`** ([`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)): Parses PDFs using PyMuPDF and returns `JSONResume` objects
- **`github.fetch_and_display_github_info`** ([`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)): Retrieves and normalizes GitHub profile data
- **`models.OllamaProvider` / `models.GeminiProvider`** ([`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)): Abstracts LLM interactions behind a unified interface
- **`evaluator.ResumeEvaluator`** ([`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)): Scores resumes and returns typed `EvaluationData`
- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**: CLI orchestrator that executes the full pipeline with caching and CSV export

Because these components return standard Python objects (`JSONResume`, `dict`, `EvaluationData`), your HR system can consume the output directly without proprietary data transformations.

## Core Integration Points and APIs

### PDF Extraction via `pdf.PDFHandler`

The `PDFHandler` class in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) provides the entry point for resume processing. It extracts structured data from PDF files and returns a Pydantic `JSONResume` model.

```python
from pdf import PDFHandler

handler = PDFHandler()
resume_json = handler.extract_json_from_pdf("/path/to/candidate.pdf")

# Access structured resume data

print(resume_json.basics.name)
print(resume_json.work_experience)

```

### GitHub Profile Enrichment via `github.fetch_and_display_github_info`

When resumes contain GitHub URLs, the [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module fetches repository statistics and profile metadata. This function returns a dictionary containing normalized GitHub data.

```python
from github import fetch_and_display_github_info

github_data = fetch_and_display_github_info("https://github.com/janedoe")

# Returns dict with profile stats and repository information

```

### LLM Provider Abstraction via `llm_utils.initialize_llm_provider`

The [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) module provides `initialize_llm_provider()`, which instantiates either `OllamaProvider` or `GeminiProvider` based on environment configuration. This abstraction allows your HR tool to switch between local and cloud LLMs without code changes.

```python
from llm_utils import initialize_llm_provider

provider = initialize_llm_provider("gemma3:4b")
response = provider.chat("Evaluate this candidate...")

```

### Resume Evaluation via `evaluator.ResumeEvaluator`

The `ResumeEvaluator` class in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) combines resume text with LLM prompts to generate structured assessments. It returns an `EvaluationData` object containing numerical scores and qualitative feedback.

```python
from evaluator import ResumeEvaluator
from prompt import DEFAULT_MODEL, MODEL_PARAMETERS

evaluator = ResumeEvaluator(
    model_name=DEFAULT_MODEL,
    model_params=MODEL_PARAMETERS.get(DEFAULT_MODEL)
)
result = evaluator.evaluate_resume(resume_text)

# Returns EvaluationData with scores.open_source, scores.technical_skills, etc.

```

## Step-by-Step Integration Workflow

To embed the Hiring Agent into your HR platform, implement the following sequence:

1. **Receive the candidate resume** through your existing upload mechanism (file path or binary stream)
2. **Extract structured data** by calling `PDFHandler().extract_json_from_pdf()`
3. **Enrich with external profiles** by detecting GitHub URLs in the resume and invoking `fetch_and_display_github_info()`
4. **Compose the evaluation prompt** using helper functions from [`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py) (`convert_json_resume_to_text()`, `convert_github_data_to_text()`)
5. **Generate the evaluation** by instantiating `ResumeEvaluator` and calling `evaluate_resume()`
6. **Persist the results** by storing the returned `EvaluationData` in your HRIS database or ATS candidate record

## Practical Integration Examples

### Embedding in a Flask Web Service

For real-time resume evaluation within a web application, import the pipeline components directly into your route handlers:

```python

# app.py

import os
from flask import Flask, request, jsonify
from pdf import PDFHandler
from github import fetch_and_display_github_info
from transform import (
    convert_json_resume_to_text,
    convert_github_data_to_text,
)
from evaluator import ResumeEvaluator
from llm_utils import initialize_llm_provider
from prompt import DEFAULT_MODEL, MODEL_PARAMETERS

app = Flask(__name__)

@app.route("/evaluate", methods=["POST"])
def evaluate():
    resume_file = request.files["resume"]
    resume_path = f"/tmp/{resume_file.filename}"
    resume_file.save(resume_path)

    # Extract résumé JSON

    resume_json = PDFHandler().extract_json_from_pdf(resume_path)

    # Enrich with GitHub if present

    github_data = {}
    if resume_json.basics and resume_json.basics.profiles:
        for profile in resume_json.basics.profiles:
            if profile.network and profile.network.lower() == "github":
                github_data = fetch_and_display_github_info(profile.url)
                break

    # Build prompt text

    text = convert_json_resume_to_text(resume_json)
    if github_data:
        text += convert_github_data_to_text(github_data)

    # Evaluate

    model_params = MODEL_PARAMETERS.get(DEFAULT_MODEL)
    evaluator = ResumeEvaluator(
        model_name=DEFAULT_MODEL, 
        model_params=model_params
    )
    result = evaluator.evaluate_resume(text)

    return jsonify(result.model_dump())

if __name__ == "__main__":
    from dotenv import load_dotenv
    load_dotenv()
    app.run(host="0.0.0.0", port=8080)

```

### Programmatic CLI Usage from Python Scripts

You can invoke the complete pipeline programmatically by importing the main entry point from [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

```python

# integration.py

import os
from score import main as run_hiring_agent

os.environ["LLM_PROVIDER"] = "ollama"
os.environ["DEFAULT_MODEL"] = "gemma3:4b"

pdf_path = "/data/candidates/jane_doe_resume.pdf"
evaluation = run_hiring_agent(pdf_path)

# Access structured scoring data

total_score = (
    evaluation.scores.open_source.score +
    evaluation.scores.self_projects.score +
    evaluation.scores.production.score +
    evaluation.scores.technical_skills.score
)
print(f"Candidate total score: {total_score}")

```

### Direct HRIS Database Integration

For batch processing or data synchronization with existing HRIS systems, call individual components without the full pipeline:

```python
from github import fetch_and_display_github_info

def sync_github_to_hris(candidate_github_url, hr_candidate_id):
    profile_data = fetch_and_display_github_info(candidate_github_url)
    
    # Store in your HRIS database

    store_in_hris(
        candidate_id=hr_candidate_id,
        github_stats=profile_data.get("stats"),
        top_repositories=profile_data.get("projects")
    )

```

## Environment Configuration for Multi-Tool Deployments

The Hiring Agent uses environment variables to select LLM providers, allowing you to switch between local Ollama instances and Google Gemini without modifying integration code. Configure these variables in your deployment environment or `.env` file:

- **`LLM_PROVIDER`**: Set to `"ollama"` or `"gemini"`
- **`DEFAULT_MODEL`**: Model identifier (e.g., `"gemma3:4b"` or `"gemini-1.5-pro"`)
- **`GEMINI_API_KEY`**: Required when using Google Gemini
- **`OLLAMA_HOST`**: Optional; defaults to `http://localhost:11434`

This configuration approach means you can deploy the same integration code across development (local Ollama) and production (cloud Gemini) environments without rebuilding your application.

## Summary

- **Modular Python API**: The Hiring Agent exposes each pipeline stage as importable functions in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), and [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), enabling granular integration with existing HR tools.
- **Standard Data Models**: Components return Pydantic models (`JSONResume`, `EvaluationData`) and dictionaries that integrate directly with modern web frameworks and databases.
- **Provider Agnostic**: Switch between Ollama and Gemini LLMs via environment variables (`LLM_PROVIDER`, `DEFAULT_MODEL`) without code changes.
- **Flexible Deployment**: Embed in Flask/FastAPI endpoints, run as batch jobs via `score.main()`, or import specific modules like `PDFHandler` into existing HRIS workflows.

## Frequently Asked Questions

### Can I integrate the Hiring Agent with my existing ATS or HRIS?

Yes. Because the repository exposes standard Python functions that return JSON-serializable Pydantic models, you can import `PDFHandler`, `ResumeEvaluator`, and other components directly into your ATS backend. The `EvaluationData` object returned by `evaluator.evaluate_resume()` contains all scoring data in a structured format suitable for storage in any SQL or NoSQL database.

### What data format does the evaluation engine return?

The `ResumeEvaluator.evaluate_resume()` method returns an `EvaluationData` object (defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)) containing typed fields for overall assessment, section-specific scores (open_source, self_projects, production, technical_skills), and detailed feedback text. You can serialize this to JSON using `evaluation.model_dump()` for HTTP APIs or store it directly as structured data in your HR platform.

### Do I need to modify code to switch between Ollama and Gemini?

No. The LLM provider is selected entirely through environment variables. Set `LLM_PROVIDER=ollama` or `LLM_PROVIDER=gemini` in your environment, along with the appropriate `GEMINI_API_KEY` if using Google, and `initialize_llm_provider()` in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) will instantiate the correct class (`OllamaProvider` or `GeminiProvider`) without requiring changes to your integration code.

### Can I use only specific components, such as just the PDF parser or GitHub enricher?

Yes. The architecture is intentionally decoupled. You can import `PDFHandler` from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) to extract resume data without invoking the LLM, or use `fetch_and_display_github_info` from [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) independently to enrich candidate profiles in your existing database. Each module functions as a standalone utility that does not require the full pipeline to be executed.