Hiring-Agent Use Cases: From Resume PDF to Structured Evaluation

Hiring-Agent is a modular pipeline that converts résumé PDFs into structured JSON, enriches them with GitHub data, and produces fairness-aware scores via an LLM-driven evaluator.

The interviewstreet/hiring-agent repository provides a self-contained toolkit for automated résumé evaluation. Whether you need to score a single candidate or integrate résumé parsing into a larger hiring platform, hiring-agent use cases range from quick CLI commands to deep programmatic integration. Each stage of the pipeline is exposed as a standalone Python module, allowing you to mix and match components as needed.

End-to-End CLI Scoring

The most common entry point is the command-line interface defined in score.py. This workflow orchestrates the entire pipeline—PDF extraction, GitHub enrichment, and fairness-aware evaluation—in a single command.

python score.py /path/to/resume.pdf

When executed, the script performs the following:

1. Extracts the résumé using PDFHandler (defined in pdf.py) and caches the result to cache/resumecache_*.json
2. Pulls GitHub data via fetch_and_display_github_info (from github.py) if a profile is detected, caching to cache/githubcache_*.json
3. Evaluates the candidate using ResumeEvaluator.evaluate_resume (from evaluator.py) and prints a detailed report via print_evaluation_results

Set DEVELOPMENT_MODE=True to enable CSV export and enhanced debug output.

Programmatic Integration

For production systems, import the components directly rather than shelling out to the CLI. This approach gives you fine-grained control over the JSONResume and EvaluationData objects.

from pdf import PDFHandler
from github import fetch_and_display_github_info
from evaluator import ResumeEvaluator
from models import JSONResume, EvaluationData
from prompt import DEFAULT_MODEL, MODEL_PARAMETERS
from transform import convert_json_resume_to_text, convert_github_data_to_text

# 1. Extract structured resume data

pdf_path = "resume.pdf"
pdf_handler = PDFHandler()
resume: JSONResume = pdf_handler.extract_json_from_pdf(pdf_path)

# 2. Enrich with GitHub (optional)

github_profile_url = resume.basics.profiles[0].url  # assuming a Github entry

github_data = fetch_and_display_github_info(github_profile_url)

# 3. Build the text the evaluator expects

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

# 4. Run the evaluation

model_params = MODEL_PARAMETERS.get(DEFAULT_MODEL)
evaluator = ResumeEvaluator(model_name=DEFAULT_MODEL, model_params=model_params)
evaluation: EvaluationData = evaluator.evaluate_resume(text)

# 5. Inspect the result

print(evaluation)

The helper functions convert_json_resume_to_text and convert_github_data_to_text reside in transform.py. They serialize the structured Pydantic models into plain text optimized for the LLM evaluator.

Batch Processing Workflows

Process entire directories of résumés by reusing the CLI logic programmatically. This pattern leverages the caching mechanism built into score.py to avoid redundant API calls.

import glob
from pathlib import Path
from score import main as evaluate_resume

pdf_files = Path("resumes/").glob("*.pdf")
for pdf in pdf_files:
    evaluate_resume(str(pdf))

This loop automatically handles caching for both PDF extraction and GitHub lookups, making it efficient for high-volume screening.

Pipeline Architecture and Key Components

Understanding the module layout helps you select the right integration strategy:

• pymupdf_rag.py → pdf.py — Handles PDF-to-Markdown conversion and section parsing using Jinja templates to produce a JSONResume
• github.py — Detects GitHub profiles, fetches repository data, and selects the top 7 most relevant projects for enrichment
• evaluator.py — Applies fairness-aware scoring criteria (open-source contributions, self-projects, production experience, technical skills) plus bonuses and deductions
• models.py — Defines Pydantic schemas for JSONResume, EvaluationData, and LLM provider abstractions
• prompts/ — Contains Jinja templates that drive LLM extraction and scoring prompts

Because each stage is decoupled, you can substitute your own PDF extraction logic, use a custom GitHub client, or replace the evaluator with your own scoring engine while retaining the data models.

Summary

• Hiring-Agent turns unstructured résumé PDFs into structured JSONResume objects via PDFHandler in pdf.py.
• GitHub enrichment automatically fetches and ranks up to 7 repositories when a profile is present, using fetch_and_display_github_info.
• Fairness-aware scoring is handled by ResumeEvaluator in evaluator.py, which applies transparent criteria and bonus/deduction logic.
• Flexible integration supports both one-off CLI usage (python score.py <file>) and library-style imports for custom hiring workflows.
• Caching at both the PDF and GitHub layers minimizes redundant LLM calls and API requests during batch processing.

Frequently Asked Questions

How do I process multiple résumés at once?

Import the main function from score.py and iterate over a directory of PDFs. This reuses the built-in caching logic in pymupdf_rag.py and github.py, ensuring you only pay for LLM tokens and API calls on the first run.

Can I use Hiring-Agent without the GitHub integration?

Yes. The GitHub enrichment step in fetch_and_display_github_info is optional. If the JSONResume contains no GitHub profile, or if you choose not to call the GitHub module, the evaluator in evaluator.py still functions using only the résumé text converted via convert_json_resume_to_text.

Where is the evaluation criteria defined?

The scoring logic lives in evaluator.py, which instantiates ResumeEvaluator with fairness-aware criteria including open-source contributions, self-directed projects, production experience, and technical skills. The criteria weights and bonus/deduction rules are applied within the evaluate_resume method before returning an EvaluationData object.

What format does the structured résumé use?

The pipeline outputs a JSONResume Pydantic model defined in models.py. This schema includes sections for basics, work experience, education, skills, and profiles, making it compatible with standardized résumé formats while allowing easy extension for custom fields.

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