# How to Set Up the Interviewstreet Hiring Agent Locally: Complete Installation Guide

> Set up the Interviewstreet Hiring Agent locally with our complete installation guide. Clone the repo, create an environment, install dependencies, and configure your .env file for local candidate evaluation.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: getting-started
- Published: 2026-07-24

---

**Clone the repository, create a Python 3.11+ virtual environment, install dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configure your `.env` file with `LLM_PROVIDER` and model details, then run `python score.py /path/to/resume.pdf` to evaluate candidates locally.**

The Interviewstreet Hiring Agent is an open-source Python pipeline that automates résumé evaluation by extracting PDF content, parsing sections with LLM-powered Jinja templates, enriching profiles with GitHub data, and applying fairness-aware scoring rules. This guide covers how to set up the Interviewstreet Hiring Agent locally using either a local Ollama instance or the Google Gemini API, based on the official repository structure and source code.

## Prerequisites

Before installation, ensure your system meets the following requirements defined in the repository configuration.

### Python Version Requirements

The Hiring Agent requires **Python 3.11 or higher**. The repository pins the version to 3.11.13 in the `.python-version` file. Verify your installation with:

```bash
python --version

```

### LLM Backend Options

You must configure one of two LLM providers:

- **Ollama** (local inference): Requires a running Ollama server with a pulled model (e.g., `gemma3:4b`, `gemma3:12b`, or `gemma3:1b`)
- **Google Gemini** (cloud API): Requires a valid `GEMINI_API_KEY`

## Step-by-Step Installation

### Clone the Repository and Create a Virtual Environment

Start by cloning the repository and setting up an isolated Python environment:

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

```

Activate the virtual environment:

```bash

# macOS/Linux

source .venv/bin/activate

# Windows

.venv\Scripts\activate

```

### Install Dependencies

With the environment activated, install the required packages:

```bash
pip install -r requirements.txt

```

### Set Up Local LLM (Optional)

If using Ollama for local inference, pull your preferred model before running evaluations:

```bash
ollama pull gemma3:4b

```

Replace `gemma3:4b` with `gemma3:12b` or `gemma3:1b` depending on your hardware constraints.

## Configuration

The Hiring Agent uses environment variables for provider selection and API authentication.

### Environment Variables

Copy the example configuration file:

```bash
cp .env.example .env

```

Edit `.env` to set the following variables:

- `LLM_PROVIDER`: Set to `ollama` (default) or `gemini`
- `DEFAULT_MODEL`: Specify `gemma3:4b` for Ollama or `gemini-2.5-pro` for Gemini
- `GEMINI_API_KEY`: Required only when `LLM_PROVIDER=gemini`
- `GITHUB_TOKEN`: Optional, but recommended to avoid GitHub API rate limits

### Provider-Specific Settings

For **Ollama**, ensure your local server is running at the default port (typically `11434`) before executing the pipeline.

For **Gemini**, verify your API key has sufficient quota for multi-step résumé parsing and evaluation calls.

## Running the Hiring Agent

The CLI entry point is [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), which orchestrates the entire evaluation pipeline.

### CLI Usage

Execute the agent by providing a path to a candidate's résumé PDF:

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

```

### Understanding the Pipeline

When you run [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), the agent executes the following flow as implemented in the source code:

1. **PDF Extraction**: [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) converts PDF pages to Markdown-like text using PyMuPDF
2. **Section Parsing**: [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) processes the text with strict Jinja templates from `prompts/templates/*.jinja` to produce structured JSON-Resume data models 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) retrieves candidate repositories and selects top projects for signal analysis
4. **Fair Evaluation**: [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) applies fairness-aware scoring rules to the enriched profile
5. **Output Generation**: Results print to stdout; intermediate JSON caches to the `cache/` directory

### Development Mode Output

When `DEVELOPMENT_MODE=True` (set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) or via environment variable), the agent appends a CSV row to `resume_evaluations.csv` and preserves intermediate processing artifacts in the `cache/` folder for debugging.

## Key Source Files and Architecture

Understanding the codebase structure helps with customization and debugging:

- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)**: CLI driver and orchestration layer
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)**: Handles PDF-to-Markdown conversion and LLM-powered section parsing
- **[`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)**: Low-level PDF text extraction using PyMuPDF
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)**: Pydantic schemas and provider-agnostic LLM interfaces
- **[`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py)**: Provider initialization (Ollama/Gemini) and response cleaning utilities
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)**: GitHub profile retrieval and repository prioritization logic
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)**: Fairness-aware scoring engine
- **`prompts/templates/`**: Jinja templates defining strict LLM prompts for each résumé section (experience, education, skills)
- **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)**: Development-mode flags and global configuration

## Summary

- The Interviewstreet Hiring Agent requires **Python 3.11+** and either an **Ollama server** or **Gemini API key**
- Install by cloning the repository, creating a virtual environment, and running `pip install -r requirements.txt`
- Configure via the `.env` file using variables from `.env.example`, setting `LLM_PROVIDER` and model-specific options
- Execute evaluations with `python score.py /path/to/resume.pdf`, which chains together PDF extraction, LLM parsing, GitHub enrichment, and fair scoring
- Enable `DEVELOPMENT_MODE=True` to generate CSV exports in `resume_evaluations.csv` and cached intermediate JSON files

## Frequently Asked Questions

### What Python version is required for the Hiring Agent?

The codebase requires **Python 3.11 or higher**, with the repository specifically tested against Python 3.11.13 as specified in the `.python-version` file. Using older Python versions will likely cause dependency conflicts with the async LLM libraries and Pydantic validation used in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

### Can I run the Hiring Agent without an internet connection?

Partially. If you configure `LLM_PROVIDER=ollama` and use a locally running Ollama instance with a pulled model (e.g., `gemma3:4b`), the core résumé parsing and evaluation work offline. However, the **GitHub enrichment feature** in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) requires internet access to fetch candidate repositories and contribution data.

### Where are the evaluation results stored?

By default, results print to **stdout** as human-readable reports. When `DEVELOPMENT_MODE=True` (configured in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) or via environment variable), the system appends structured data to `resume_evaluations.csv` in the project root and caches intermediate JSON processing artifacts in the `cache/` directory for pipeline debugging.

### How do I switch between Ollama and Google Gemini?

Change the `LLM_PROVIDER` environment variable in your `.env` file to either `ollama` or `gemini`, and update `DEFAULT_MODEL` accordingly (e.g., `gemma3:4b` for Ollama, `gemini-2.5-pro` for Gemini). When using Gemini, you must also provide a valid `GEMINI_API_KEY`. The provider initialization logic in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) handles the underlying client configuration automatically based on these variables.