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

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	PDFHandler().extract_json_from_pdf(path)	JSONResume
GitHub Enrichment	github.py	fetch_and_display_github_info(url)	dict
LLM Abstraction	models.py / llm_utils.py	initialize_llm_provider(model_name)	OllamaProvider or GeminiProvider
Evaluation Engine	evaluator.py	ResumeEvaluator.evaluate_resume(text)	EvaluationData
Orchestration	score.py	main(pdf_path)	EvaluationData

All data models are defined in 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:

# 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 orchestrator directly from your Python code:

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

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:

# .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, 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.
3. Enrich with external profiles by calling fetch_and_display_github_info() from github.py if URLs are present.
4. Compose the evaluation prompt using helpers in transform.py (convert_json_resume_to_text, convert_github_data_to_text).
5. Generate scores by instantiating ResumeEvaluator from 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.

Summary

• Hiring-Agent exposes its pipeline as importable Python modules in pdf.py, github.py, and 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 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) 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 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.

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