# Hiring Agent

> An open-source resume-to-score pipeline that extracts structured data from PDFs, enriches it with GitHub signals, and outputs a fair, explainable candidate evaluation.

Hiring Agent is an open-source Python tool built by HackerRank (under the `interviewstreet` GitHub organization) that automates resume evaluation using local or hosted LLMs. It parses resume PDFs, extracts structured JSON data section by section, enriches the result with live GitHub profile and repository signals, and produces a scored, evidence-backed candidate report. The project is licensed under MIT and runs fully locally with Ollama or via Google Gemini.

## What It Is

Hiring Agent is a CLI-driven resume scoring pipeline designed for technical hiring workflows. It takes a resume PDF as input and outputs a structured evaluation with category scores, bonus points, deductions, and human-readable evidence. The tool is positioned as a fair and explainable alternative to black-box screening, with scoring rules encoded in declarative Jinja templates that can be audited and modified.

## Architecture and Pipeline

The pipeline runs in five sequential stages:

- **PDF extraction** — `pymupdf_rag.py` and `pdf.py` convert PDF pages to Markdown-like text using PyMuPDF, handling headings, links, tables, and formatting.
- **Section parsing** — Jinja templates under `prompts/templates/` define strict extraction instructions for Basics, Work, Education, Skills, Projects, and Awards. The LLM is called once per section and results are assembled into a `JSONResume` object.
- **GitHub enrichment** — `github.py` extracts a GitHub username from the resume, fetches profile and repository data, classifies projects, and asks the LLM to select the top 7 unique projects based on meaningful author commit thresholds.
- **Evaluation** — `evaluator.py` applies fairness constraints and produces scores across `open_source`, `self_projects`, `production`, and `technical_skills` dimensions, plus bonus and deduction fields.
- **Output** — `score.py` orchestrates the full run, prints a readable report to stdout, and in development mode appends a row to `resume_evaluations.csv` and caches intermediate JSON under `cache/`.

## LLM Provider Support

Hiring Agent supports two LLM backends, configured via environment variables:

- **Ollama** (default) — runs fully locally; supports any pulled model such as `gemma3:1b`, `gemma3:4b`, or `gemma3:12b` depending on system resources.
- **Google Gemini** — cloud-hosted; requires a `GEMINI_API_KEY` and supports models like `gemini-2.0-flash` or `gemini-2.5-pro`.

Provider logic is abstracted through `OllamaProvider` and `GeminiProvider` classes in `models.py`, with a unified response format so prompts remain provider-agnostic.

## Setup Path

The tool requires Python 3.11+ (the repo pins 3.11.13) and is installed via pip from a cloned repository. Setup involves cloning the repo, creating a virtual environment, installing `requirements.txt`, copying `.env.example` to `.env`, and configuring `LLM_PROVIDER`, `DEFAULT_MODEL`, and optionally `GEMINI_API_KEY` and `GITHUB_TOKEN`. A single CLI command — `python score.py /path/to/resume.pdf` — runs the full pipeline.

## Why It Got Attention

The repository was created in July 2025 by HackerRank and accumulated over 4,000 GitHub stars and 791 forks relatively quickly, according to the project's GitHub metadata. With 260 open issues, the project shows active community engagement. Its combination of local-first LLM support, transparent scoring templates, and GitHub signal enrichment addresses a practical gap in automated technical hiring tooling.

## Features
- Resume PDF to structured JSON extraction
- Section-by-section LLM parsing with Jinja templates
- GitHub profile and repository enrichment
- Top-7 project selection with commit threshold filtering
- Scored evaluation with open_source, self_projects, production, and technical_skills dimensions
- Bonus points and deductions in scoring
- Evidence-backed, explainable evaluation output
- Fully local inference via Ollama
- Google Gemini cloud backend support
- Development mode with CSV export and JSON caching
- Fairness constraints in evaluation templates
- CLI-driven end-to-end pipeline

## Integrations
Ollama, Google Gemini, PyMuPDF, GitHub API, Pydantic, Jinja2

## Platforms
WINDOWS, MACOS, LINUX, API, CLI

## Pricing
Open Source

## Links
- Website: https://github.com/interviewstreet/hiring-agent
- Documentation: https://github.com/interviewstreet/hiring-agent#readme
- Repository: https://github.com/interviewstreet/hiring-agent
- EveryDev.ai: https://www.everydev.ai/tools/hiring-agent