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

> Explore Hiring-Agent use cases. This pipeline transforms resume PDFs into structured JSON, enriches data with GitHub insights, and generates fairness-aware LLM scores for efficient hiring.

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

---

**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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py). This workflow orchestrates the entire pipeline—PDF extraction, GitHub enrichment, and fairness-aware evaluation—in a single command.

```bash
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)) and caches the result to `cache/resumecache_*.json`
2. **Pulls GitHub data** via `fetch_and_display_github_info` (from [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)) if a profile is detected, caching to `cache/githubcache_*.json`
3. **Evaluates** the candidate using `ResumeEvaluator.evaluate_resume` (from [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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.

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to avoid redundant API calls.

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)** → [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) — Handles PDF-to-Markdown conversion and section parsing using Jinja templates to produce a `JSONResume`
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** — Detects GitHub profiles, fetches repository data, and selects the top 7 most relevant projects for enrichment
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** — Applies fairness-aware scoring criteria (open-source contributions, self-projects, production experience, technical skills) plus bonuses and deductions
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) and iterate over a directory of PDFs. This reuses the built-in caching logic in [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) and [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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.