# How to Integrate Hiring-Agent with Other HR Tools: A Complete Developer Guide

> Integrate Hiring-Agent with your HR tools using Python modules, CLI commands, or REST API endpoints. This developer guide shows you how to connect Hiring-Agent seamlessly.

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

---

**You can integrate Hiring-Agent with your existing HR tools by importing its modular Python components directly into your application, invoking the CLI programmatically, or embedding the pipeline within REST API endpoints.**

The **Hiring-Agent** repository from InterviewStreet is architected as a collection of loosely-coupled Python modules designed to transform resume PDFs into structured evaluations using LLM scoring. Because each processing stage is exposed as a standard Python function rather than a monolithic service, you can embed specific capabilities—such as PDF extraction, GitHub enrichment, or LLM evaluation—into any applicant tracking system (ATS), talent management platform, or custom HR dashboard.

## Understanding the Modular Architecture

The repository separates concerns into distinct files that return plain Python objects (`JSONResume`, `EvaluationData`, dictionaries), making them ideal for integration.

### Core Components and Entry Points

| Component | Source File | Primary Function | Return Type |
|-----------|-------------|------------------|-------------|
| **PDF Extraction** | [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) | `PDFHandler().extract_json_from_pdf(path)` | `JSONResume` |
| **GitHub Enrichment** | [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | `fetch_and_display_github_info(url)` | `dict` |
| **LLM Abstraction** | [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) / [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) | `initialize_llm_provider(model_name)` | `OllamaProvider` or `GeminiProvider` |
| **Evaluation Engine** | [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | `ResumeEvaluator.evaluate_resume(text)` | `EvaluationData` |
| **Orchestration** | [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) | `main(pdf_path)` | `EvaluationData` |

All data models are defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) using Pydantic, ensuring type-safe serialization when passing data between your HR system and the Hiring-Agent pipeline.

## Integration Method 1: Direct Python Module Integration

The most flexible approach is importing specific classes into your existing Python application. This method gives you granular control over the pipeline while maintaining the ability to process candidates programmatically.

### Flask REST API Example

You can wrap the evaluation pipeline in a web endpoint to accept resumes from your ATS:

```python

# app.py - Flask integration example

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():
    # Receive PDF from your HR tool

    resume_file = request.files["resume"]
    resume_path = f"/tmp/{resume_file.filename}"
    resume_file.save(resume_path)

    # 1. Extract structured résumé data

    resume_json = PDFHandler().extract_json_from_pdf(resume_path)

    # 2. Enrich with GitHub if profile exists

    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

    # 3. Transform to LLM prompt format

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

    # 4. Evaluate with configured provider

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

    # 5. Return structured evaluation to your HR system

    return jsonify(result.model_dump())

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

```

This endpoint accepts a multipart form upload, processes the resume through the full pipeline, and returns a JSON-serialized `EvaluationData` object that your ATS can store in its candidate database.

## Integration Method 2: CLI Programmatic Invocation

For simpler integrations where you do not need granular control over intermediate steps, invoke the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestrator directly from your Python code:

```python

# integration.py

import os
from score import main as run_hiring_agent

# Configure environment before import

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 scores

total_score = (
    evaluation.scores.open_source.score +
    evaluation.scores.self_projects.score +
    evaluation.scores.production.score +
    evaluation.scores.technical_skills.score
)

```

This approach caches intermediate results and handles CSV export automatically, making it ideal for batch processing jobs triggered by your HR platform.

## Integration Method 3: Individual Component Integration

You can integrate specific modules without running the full pipeline. For example, to add GitHub profile analysis to an existing HRIS:

```python
from github import fetch_and_display_github_info

# Extract from candidate profile in your HR database

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

# Store structured data for analytics

# profile_data contains repository statistics and normalized profile information

```

This modular approach allows you to enrich candidate records incrementally without modifying your existing evaluation workflows.

## Configuration and Environment Variables

The LLM provider is selected via environment variables, enabling you to switch between local and cloud models without code changes:

```bash

# .env configuration

LLM_PROVIDER=ollama  # or 'gemini'

DEFAULT_MODEL=gemma3:4b
GEMINI_API_KEY=your_key_here  # Only required for Gemini provider

```

According to the source code in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py), the `initialize_llm_provider` function reads these variables to instantiate the correct provider class (`OllamaProvider` or `GeminiProvider`), ensuring your integration remains provider-agnostic.

## Data Flow for HR System Integration

When integrating Hiring-Agent with other HR tools, follow this typical workflow:

1. **Ingest the candidate resume** from your ATS or file storage system.
2. **Extract structured data** using `PDFHandler().extract_json_from_pdf()` in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py).
3. **Enrich with external profiles** by calling `fetch_and_display_github_info()` from [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) if URLs are present.
4. **Compose the evaluation prompt** using helpers in [`transform.py`](https://github.com/interviewstreet/hiring-agent/blob/main/transform.py) (`convert_json_resume_to_text`, `convert_github_data_to_text`).
5. **Generate scores** by instantiating `ResumeEvaluator` from [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) and calling `evaluate_resume()`.
6. **Persist results** by storing the returned `EvaluationData` in your HR platform's database or exporting via the CSV logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

## Summary

- **Hiring-Agent** exposes its pipeline as importable Python modules 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), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), enabling seamless integration with existing HR infrastructure.
- **Two primary integration patterns** exist: direct module import for custom workflows (Flask/Django/FastAPI) and programmatic CLI invocation using `score.main()`.
- **Provider-agnostic architecture** allows you to switch between Ollama and Google Gemini via environment variables without modifying integration code.
- **Typed data models** (`JSONResume`, `EvaluationData`) ensure safe data exchange between the Hiring-Agent pipeline and your HR system's database.

## Frequently Asked Questions

### Can I integrate Hiring-Agent with my existing ATS?

Yes. Because the repository returns standard Pydantic models and accepts file paths or binary streams, you can embed the `PDFHandler` and `ResumeEvaluator` classes into ATS webhooks, background job processors, or API endpoints. The `EvaluationData` object serializes to JSON for easy storage in any candidate database schema.

### How do I switch between Ollama and Google Gemini?

Set the `LLM_PROVIDER` environment variable to either `"ollama"` or `"gemini"` before importing the modules. The `initialize_llm_provider` function in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) automatically instantiates the correct provider class. For Gemini, you must also provide `GEMINI_API_KEY` in your environment.

### What data format does the evaluator 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 structured scores for open-source contributions, self-projects, production experience, and technical skills. This object includes `.model_dump()` for JSON serialization and `.scores` attributes for direct attribute access.

### Is it possible to integrate only the GitHub enrichment module?

Yes. The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module is fully independent. Import `fetch_and_display_github_info` to retrieve and normalize GitHub profile data without triggering PDF extraction or LLM evaluation. This is useful for incrementally enriching candidate profiles in existing HRIS systems.