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

> Discover the interviewstreet/hiring-agent repository and its Resume-to-Score pipeline. Learn how it automates candidate evaluation by parsing résumés, extracting data with LLMs, and enriching profiles for clear hiring insights.

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

---

**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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) module applies structured scoring rules to generate category-specific scores, evidence citations, bonus points, and deductions. The orchestration logic in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) coordinates the entire workflow, optionally exporting results to CSV when `DEVELOPMENT_MODE` is enabled in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py).

## Key Source Files and Responsibilities

- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**: CLI entry point and pipeline orchestration that coordinates PDF extraction, enrichment, and evaluation.
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)**: Handles PDF-to-Markdown conversion and LLM-driven section parsing using the `PDFHandler` class.
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)**: Implements `GitHubEnricher` for fetching profile data and selecting top repositories.
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)**: Applies fairness-aware scoring algorithms and builds the final evaluation object.
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)**: Defines Pydantic schemas for the JSON-Resume format and LLM provider abstractions.
- **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

```bash

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

```python
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:

```python
from pdf import PDFHandler

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

```

Fetch GitHub data separately:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) using `PDFHandler` with LLM-powered Markdown conversion and Jinja prompt templates.
- **GitHub enrichment** via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) adds real-world coding evidence from candidate repositories to supplement résumé claims.
- **Fairness-aware scoring** in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) produces explainable category scores, evidence citations, and deductions.
- The system supports both CLI execution via [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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.