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

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:

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:

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:

cp .env.example .env

Edit the .env file to include these exact values:

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 with the path to a candidate's resume PDF:

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, 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 (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, github.py, or evaluator.py.

Understanding the Pipeline Architecture

Hiring Agent processes resumes through a five-stage pipeline entirely orchestrated by score.py:

1. PDF Extraction (pymupdf_rag.py → 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): 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): 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): 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): 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 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 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}