What Is the interviewstreet/hiring-agent Repository? Resume-to-Score Pipeline Explained

The interviewstreet/hiring-agent repository implements an end-to-end "Resume-to-Score" pipeline that automatically parses résumé PDFs, extracts structured data using large language models, enriches candidate profiles with GitHub data, and produces quantified, explainable hiring evaluations.

This open-source tool from InterviewStreet transforms unstructured résumé documents into objective hiring scores. The interviewstreet/hiring-agent repository provides a self-contained system that combines PDF parsing, LLM-driven information extraction, and fairness-aware scoring rules to streamline technical candidate evaluation.

Resume-to-Score Pipeline Architecture

PDF Parsing and LLM-Driven Extraction

The pipeline begins in pdf.py, which converts résumé PDFs to Markdown format using PyMuPDF. It then employs Jinja-based prompt templates stored in the prompts/ directory to drive LLM extraction of structured résumé sections. The PDFHandler class manages this conversion, supporting local models like gemma3:4b via Ollama or hosted Google Gemini APIs.

GitHub Profile Enrichment

After parsing, the GitHubEnricher class in github.py retrieves candidate repository data and profile metadata. This component selects the most relevant projects to augment the résumé data, providing concrete evidence of coding activity and open-source contributions that inform the final evaluation.

Fairness-Aware Evaluation and Scoring

The evaluator.py module applies structured scoring rules to generate category-specific scores, evidence citations, bonus points, and deductions. The orchestration logic in score.py coordinates the entire workflow, optionally exporting results to CSV when DEVELOPMENT_MODE is enabled in config.py.

Key Source Files and Responsibilities

• score.py: CLI entry point and pipeline orchestration that coordinates PDF extraction, enrichment, and evaluation.
• pdf.py: Handles PDF-to-Markdown conversion and LLM-driven section parsing using the PDFHandler class.
• github.py: Implements GitHubEnricher for fetching profile data and selecting top repositories.
• evaluator.py: Applies fairness-aware scoring algorithms and builds the final evaluation object.
• models.py: Defines Pydantic schemas for the JSON-Resume format and LLM provider abstractions.
• config.py: Contains configuration flags including DEVELOPMENT_MODE and LLM provider settings.
• prompts/: Directory containing Jinja templates that guide LLM extraction and scoring decisions.

Running the Hiring Agent Pipeline

Command-Line Interface

Execute the full pipeline from the terminal:

# Activate virtual environment

source .venv/bin/activate

# Score a résumé PDF with development mode enabled (default)

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

This command runs the complete sequence: PDF parsing → LLM extraction → GitHub enrichment → scoring → summary output with optional CSV export.

Programmatic Integration

Import the core orchestration function for custom workflows:

from score import run_score
from config import DEVELOPMENT_MODE

# Disable CSV export for one-off runs

DEVELOPMENT_MODE = False

# Execute pipeline

run_score("samples/sample_resume.pdf")

Direct Component Access

Extract résumé data independently using the PDF handler:

from pdf import PDFHandler

handler = PDFHandler(model="gemma3:4b")
json_resume = handler.process("samples/sample_resume.pdf")
print(json_resume)

Fetch GitHub data separately:

from github import GitHubEnricher

enricher = GitHubEnricher()
profile, projects = enricher.enrich(json_resume)
print(profile.username, len(projects))

Summary

• The interviewstreet/hiring-agent repository automates the conversion of résumé PDFs into structured, scored evaluations using local or hosted LLMs.
• PDF extraction occurs in pdf.py using PDFHandler with LLM-powered Markdown conversion and Jinja prompt templates.
• GitHub enrichment via github.py adds real-world coding evidence from candidate repositories to supplement résumé claims.
• Fairness-aware scoring in evaluator.py produces explainable category scores, evidence citations, and deductions.
• The system supports both CLI execution via score.py and programmatic integration through modular Python imports.

Frequently Asked Questions

What LLM providers does interviewstreet/hiring-agent support?

The repository supports both local LLMs via Ollama (such as gemma3:4b) and hosted models through Google Gemini. Configuration occurs in config.py, allowing teams to choose between on-premise inference for data privacy or cloud APIs for performance. The PDFHandler class accepts model names as parameters during initialization.

How does the GitHub enrichment improve hiring decisions?

The GitHubEnricher class in github.py retrieves actual repository metadata, contribution histories, and primary programming languages, selecting the most relevant projects to verify skills claimed in the résumé. This data provides concrete evidence of coding patterns, project complexity, and open-source engagement that raw résumé text cannot convey, enabling evidence-based scoring.

Can I export evaluation results for bulk analysis?

Yes. When DEVELOPMENT_MODE is set to True in config.py, the score.py orchestrator automatically appends evaluation results to a CSV file. This enables quantitative analysis of candidate pools, tracking of scoring trends across multiple applicants, and integration with existing HR information systems.

Is the scoring methodology transparent and explainable?

According to the source code in evaluator.py, the system generates detailed evaluations that include specific evidence citations, bonus point justifications, and deduction reasons alongside numerical category scores. This structured output ensures hiring decisions are auditable and free from black-box algorithmic bias, fulfilling fairness requirements in automated hiring tools.

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