# How to Run the Hiring Agent Locally on Your Machine

> Easily run the Hiring Agent locally. Clone the repository, install dependencies, configure your environment, and score resumes with cached results. Get started today.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-06-28

---

**Clone the interviewstreet/hiring-agent repository, install dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configure your `.env` file with `LLM_PROVIDER` and API keys, and execute `python score.py path/to/resume.pdf` to generate a scored evaluation with cached intermediate results.**

The **Hiring Agent** is an open-source Python pipeline that transforms resume PDFs into structured, explainable evaluations using local or hosted LLMs. According to the interviewstreet/hiring-agent source code, the system extracts text, parses sections with Jinja templates, enriches data via GitHub APIs, and applies a fairness-aware scoring rubric. Running the Hiring Agent locally lets you evaluate candidates without sending sensitive data to external services, provided you have a compatible LLM backend such as Ollama.

## Prerequisites and Local Setup

### Clone the Repository and Create a Virtual Environment

Start by cloning the repository and setting up an isolated Python environment to avoid dependency conflicts with other projects.

### Install Python Dependencies

Install the required packages listed in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) to ensure all PDF processing, LLM client, and data validation libraries are available.

```bash
git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv
source .venv/bin/activate  # Use .venv\Scripts\activate on Windows

pip install -r requirements.txt

```

## Configure the LLM Provider

The Hiring Agent supports multiple LLM backends through a common abstraction layer defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py). Configuration is handled via environment variables stored in a `.env` file at the project root.

### Using Ollama for Local Inference

For fully local execution without external API calls, install Ollama and pull a compatible model such as `gemma3:4b`. Set `LLM_PROVIDER=ollama` in your `.env` file to route all inference through your local instance.

### Using Gemini for Cloud Inference

To use Google's Gemini API, obtain an API key and set `LLM_PROVIDER=gemini` along with `GEMINI_API_KEY` in your `.env` file. You may also set `DEFAULT_MODEL` to specify which Gemini model variant to use.

```bash

# Copy the example configuration

cp .env.example .env

# Edit .env to set your preferred provider and credentials

# LLM_PROVIDER=ollama

# DEFAULT_MODEL=gemma3:4b

# GITHUB_TOKEN=your_github_token_here

```

## Running the End-to-End Pipeline

Once configured, execute the main entry point [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) with a path to a resume PDF. The pipeline orchestrates five distinct stages that transform raw PDF data into a structured evaluation:

1. **PDF extraction** – [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) reads the PDF using PyMuPDF and converts it to Markdown-like text.
2. **Section parsing** – [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) sends parsed sections (Basics, Work, Education) to the LLM using Jinja templates from `prompts/templates/`, returning JSON-Resume structures defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).
3. **GitHub enrichment** – [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) extracts usernames from the resume, pulls profile and repository data via the GitHub API, and uses the LLM to select the top 7 repositories for scoring.
4. **Evaluation** – [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) applies the scoring rubric via additional Jinja templates, assessing open-source contributions, production experience, technical skills, and fairness metrics.
5. **Output** – [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) prints a human-readable summary and, when `DEVELOPMENT_MODE=True` (the default in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), writes a CSV row to `resume_evaluations.csv` and caches JSON files under `cache/`.

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

```

## Understanding the Pipeline Architecture

All stages share utility functions from [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) that normalize LLM responses and instantiate either `OllamaProvider` or `GeminiProvider` based on your `LLM_PROVIDER` setting. The [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) file manages global settings including the `DEVELOPMENT_MODE` flag.

Key files involved in local execution include:
- [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) – CLI entry point that orchestrates the workflow.
- [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) – Handles PDF-to-Markdown conversion and per-section LLM calls.
- [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) – Low-level text extraction using PyMuPDF.
- [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) – GitHub profile enrichment and repository classification.
- [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) – Fairness-aware scoring logic.
- [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) – Pydantic schemas and LLM provider interfaces.
- `prompts/templates/` – Jinja templates for extraction and evaluation prompts.

## Summary

- Clone the **interviewstreet/hiring-agent** repository and install dependencies via `pip install -r requirements.txt`.
- Configure your `.env` file with `LLM_PROVIDER` (set to `ollama` or `gemini`), `DEFAULT_MODEL`, and required API keys.
- Run the complete pipeline with `python score.py <resume.pdf>` to generate scored evaluations.
- The system caches intermediate results in `cache/` and appends evaluations to `resume_evaluations.csv` when `DEVELOPMENT_MODE=True`.
- Core orchestration happens in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), with PDF processing in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) and [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), and scoring logic implemented in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

## Frequently Asked Questions

### Do I need a GPU to run the Hiring Agent locally?

No. If you use **Ollama** with a small model like `gemma3:4b`, the pipeline runs on CPU-only machines, though inference will be slower. For faster performance or larger models, a GPU is recommended. Alternatively, set `GEMINI_API_KEY` to offload LLM inference to Google's cloud servers.

### Where does the Hiring Agent store intermediate results?

When `DEVELOPMENT_MODE=True` (the default set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the pipeline writes cached JSON files to the `cache/` directory and appends evaluation results to `resume_evaluations.csv` in the project root. This allows you to inspect the parsed resume structure and GitHub data without re-running expensive LLM calls.

### Can I use a different LLM provider than Ollama or Gemini?

The current implementation in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) defines `OllamaProvider` and `GeminiProvider` classes. To add a new provider, you would need to implement a compatible provider class following the abstraction pattern used in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and update [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) to instantiate your new class based on the `LLM_PROVIDER` environment variable.

### Why does the pipeline require a GitHub token?

The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module extracts GitHub usernames from resumes and queries the GitHub API to retrieve profile metadata, repository statistics, and project classifications. A `GITHUB_TOKEN` is required to avoid rate limits and access detailed repository information. Without it, the GitHub enrichment stage may fail or return incomplete data.