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

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): Parses PDFs using PyMuPDF and returns JSONResume objects
• github.fetch_and_display_github_info (github.py): Retrieves and normalizes GitHub profile data
• models.OllamaProvider / models.GeminiProvider (models.py): Abstracts LLM interactions behind a unified interface
• evaluator.ResumeEvaluator (evaluator.py): Scores resumes and returns typed EvaluationData
• 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 provides the entry point for resume processing. It extracts structured data from PDF files and returns a Pydantic JSONResume model.

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 module fetches repository statistics and profile metadata. This function returns a dictionary containing normalized GitHub data.

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 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.

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 combines resume text with LLM prompts to generate structured assessments. It returns an EvaluationData object containing numerical scores and qualitative feedback.

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 (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:

# 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:

# 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:

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, github.py, evaluator.py, and 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) 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 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 to extract resume data without invoking the LLM, or use fetch_and_display_github_info from 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.

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