# How to Run Hiring Agent Locally with Ollama: Complete Setup Guide

> Learn how to run Hiring Agent locally with Ollama. Set up your environment, start the Ollama server, and process resumes offline. Get complete setup instructions now.

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

---

**To run Hiring Agent locally with Ollama, set `LLM_PROVIDER=ollama` and `DEFAULT_MODEL=gemma3:4b` in your `.env` file, start the Ollama server on localhost:11434, and execute `python score.py /path/to/resume.pdf` to process resumes entirely offline without external API keys.**

Hiring Agent is an open-source Python 3.11+ application from interviewstreet that automates resume evaluation by parsing PDFs, enriching candidate data with GitHub signals, and generating fair, explainable scores. When you configure the tool to use **Ollama** as the LLM backend, all inference runs locally through the `OllamaProvider` class, keeping sensitive resume data on your machine while still producing structured JSON evaluations and detailed scoring rubrics.

## Prerequisites

Before installing Hiring Agent, ensure your environment meets these requirements:

- **Python 3.11** or newer
- **Ollama** installed and available in your system PATH
- **Git** for cloning the repository
- **GitHub Token** (optional) to avoid rate limits during GitHub profile enrichment

## Step-by-Step Local Setup

### 1. Clone the Repository and Install Dependencies

Create a dedicated virtual environment and install the required packages:

```bash
git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

```

### 2. Start Ollama and Pull a Model

Launch the Ollama daemon and download a compatible model. The repository recommends models like Gemma 3 4B for their balance of speed and quality:

```bash
ollama serve

# In a separate terminal window

ollama pull gemma3:4b

```

The Ollama server runs on `localhost:11434` by default and must remain active while processing resumes.

### 3. Configure Environment Variables

Copy the example configuration file and modify it to point to your local Ollama instance:

```bash
cp .env.example .env

```

Edit the `.env` file to include these exact values:

```bash
LLM_PROVIDER=ollama
DEFAULT_MODEL=gemma3:4b

# GITHUB_TOKEN=ghp_xxx  # Optional: helps avoid GitHub API rate limits

```

Unlike cloud-based providers, you do not need to set `GEMINI_API_KEY` or other external API credentials when running in local mode.

### 4. Execute the Evaluation Pipeline

Run the main orchestration script [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) with the path to a candidate's resume PDF:

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

```

**Expected output:** The console displays a human-readable evaluation report including section-by-section scores and fairness analysis. If `DEVELOPMENT_MODE=True` is set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system also writes a `resume_evaluations.csv` file and caches intermediate JSON structures under the `cache/` directory.

## How the Ollama Integration Works

The local LLM integration is handled by the `OllamaProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) (lines 71-96), which implements a provider-agnostic interface used throughout the pipeline.

When `LLM_PROVIDER=ollama` is detected, the provider:

- **Sets a 32 KB context window** via `num_ctx = 32768` to accommodate large resume sections and GitHub data without truncation
- **Disables streaming** since the current implementation requires complete responses for JSON parsing
- **Constructs HTTP requests** compatible with the Ollama API format, sending prompts built from Jinja templates stored in `prompts/templates/`

This architecture ensures that switching between Ollama and cloud providers (like Gemini) requires only changing the two environment variables above, with no modifications needed to [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), or [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

## Understanding the Pipeline Architecture

Hiring Agent processes resumes through a five-stage pipeline entirely orchestrated by [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

1. **PDF Extraction** ([`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)): Converts PDF pages to Markdown-like text using PyMuPDF and splits documents into semantic sections (Experience, Education, Projects, etc.).

2. **Section Parsing** ([`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)): Sends each section to the LLM via the `OllamaProvider`, using strict Jinja templates to enforce JSON-Resume compatible output structures.

3. **GitHub Enrichment** ([`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)): Detects GitHub usernames in the parsed content, fetches repository statistics via the GitHub API, and uses the LLM to classify and rank the top 7 most relevant projects.

4. **Fairness Evaluation** ([`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)): Applies the open-source scoring rubric, evaluating categories like production experience, technical skills, and self-initiated projects while applying bonus and deduction logic.

5. **Output Generation** ([`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)): Aggregates all signals into a final score and generates the human-readable report and CSV outputs.

## Summary

- Hiring Agent requires **Python 3.11+** and runs entirely offline when configured with Ollama.
- Set **`LLM_PROVIDER=ollama`** and **`DEFAULT_MODEL=gemma3:4b`** in `.env` to enable local inference.
- The **`OllamaProvider`** class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) handles API communication with a fixed 32 KB context window and streaming disabled.
- Execute **`python score.py <pdf_path>`** to trigger the end-to-end pipeline from PDF parsing to final evaluation.
- Enable **`DEVELOPMENT_MODE=True`** in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to generate CSV reports and cached JSON intermediates.

## Frequently Asked Questions

### Do I need a GPU to run Hiring Agent with Ollama?

No, a GPU is not strictly required, though it significantly improves inference speed. Ollama supports CPU-only execution for smaller models like `gemma3:4b`, making it feasible to run the evaluation pipeline on modest hardware or laptops, albeit with longer processing times for large resumes.

### Can I use a different model than Gemma 3?

Yes, any Ollama-supported model will work as long as it follows the chat completion API format. Update the `DEFAULT_MODEL` variable in your `.env` file (e.g., `llama3:8b` or `mistral:7b`). Ensure your hardware has sufficient RAM to load the chosen model, as Hiring Agent maintains a 32 KB context window that increases memory usage.

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

By default, results print to the console only. When `DEVELOPMENT_MODE=True` is configured in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system writes a `resume_evaluations.csv` file in the project root and stores cached intermediate JSON files under the `cache/` directory, preserving structured data from each pipeline stage.

### Is a GitHub token required for local runs?

No, the GitHub token is optional. However, without authentication in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), you may encounter GitHub API rate limits (60 requests per hour for unauthenticated users). Setting `GITHUB_TOKEN` in your `.env` file increases this limit to 5,000 requests per hour, which is recommended when processing batches of resumes that include GitHub profile links.