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

> Learn to set up Interviewstreet Hiring-Agent locally with our quick guide. Install dependencies, configure LLMs like Ollama or Gemini, and start evaluating resumes instantly.

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

---

**Clone the repository, install Python 3.11+ dependencies, configure your LLM provider (Ollama or Gemini), and run `python score.py /path/to/resume.pdf` to evaluate résumés locally.**

The interviewstreet hiring-agent is a Python 3.11+ pipeline that extracts, parses, and evaluates résumés using LLM-powered analysis and fairness-aware scoring. This guide covers the complete interviewstreet hiring-agent setup process, from repository cloning to executing your first local candidate evaluation using the modular architecture defined in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py), [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

## Prerequisites

Before installing, ensure your environment meets these requirements:

- **Python 3.11+** — The repository pins `.python-version` to 3.11.13, and all modules in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) require this version or newer.
- **LLM Backend** — Either a local Ollama server or a Google Gemini API key. The [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) module initializes providers based on your configuration.

## Step-by-Step Installation

### Clone and Install Dependencies

Run these commands to set up the project environment:

```bash
git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv
source .venv/bin/activate      # macOS/Linux

# .venv\Scripts\activate       # Windows

pip install -r requirements.txt

```

### Configure a Local LLM with Ollama (Optional)

For fully local inference without API calls, install Ollama and pull a compatible model:

```bash
ollama pull gemma3:4b          # Also available: gemma3:12b, gemma3:1b

```

The [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) file handles provider initialization for both Ollama and Gemini backends.

## Environment Configuration

Copy the example environment file and configure your variables:

```bash
cp .env.example .env

```

Edit `.env` to set these critical variables:

- **`LLM_PROVIDER`** — Set to `ollama` (default) or `gemini`
- **`DEFAULT_MODEL`** — Specify the model name, e.g., `gemma3:4b` for Ollama or `gemini-2.5-pro` for Gemini
- **`GEMINI_API_KEY`** — Required only when using Google Gemini
- **`GITHUB_TOKEN`** — Optional but recommended to improve GitHub API rate limits for the [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) enrichment module

## Running the Hiring Agent Locally

The CLI entry point is [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py). Execute a résumé evaluation with:

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

```

This command orchestrates the full pipeline:

1. **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. **Parsing** — [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) processes sections using strict Jinja templates from `prompts/templates/` to generate a JSON-Resume data model defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).
3. **Enrichment** — [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) retrieves GitHub profile signals and selects top projects for candidate context.
4. **Evaluation** — [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) applies fairness-aware scoring rules to generate the final assessment.
5. **Output** — Results print to stdout. When `DEVELOPMENT_MODE=True` (set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the agent appends a CSV row to `resume_evaluations.csv` and caches intermediate JSON in the `cache/` directory.

## Understanding the Pipeline Architecture

The hiring-agent consists of specialized modules that process résumés sequentially:

- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** — CLI driver that orchestrates the entire evaluation flow.
- **[`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)** and **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** — Handle PDF-to-Markdown conversion and LLM-based section parsing.
- **[`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)** — Defines Pydantic schemas and provider-agnostic LLM interfaces.
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** — Enriches candidate profiles with GitHub repository data.
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** — Implements the fairness-aware scoring logic.
- **`prompts/templates/`** — Contains Jinja templates that enforce strict output formats for each résumé section.

## Complete Local Setup Example

This Python script demonstrates the full setup and execution programmatically:

```python
import subprocess, os

# 1️⃣ Clone and set up environment

subprocess.run(["git", "clone", "https://github.com/interviewstreet/hiring-agent"])
os.chdir("hiring-agent")
subprocess.run(["python", "-m", "venv", ".venv"])
subprocess.run([".venv/bin/activate"], shell=True)   # Use .venv\Scripts\activate on Windows

subprocess.run(["pip", "install", "-r", "requirements.txt"])

# 2️⃣ Configure environment

os.environ["LLM_PROVIDER"] = "ollama"
os.environ["DEFAULT_MODEL"] = "gemma3:4b"

# 3️⃣ Execute evaluation

result = subprocess.run(
    ["python", "score.py", "sample_resume.pdf"],
    capture_output=True,
    text=True
)
print(result.stdout)

```

Replace `sample_resume.pdf` with an actual résumé file path to generate evaluations.

## Summary

- The interviewstreet hiring-agent requires **Python 3.11+** and either a local Ollama instance or Gemini API access.
- Install dependencies via `pip install -r requirements.txt` after cloning the repository.
- Configure the `.env` file with `LLM_PROVIDER`, `DEFAULT_MODEL`, and authentication tokens.
- Run `python score.py <resume.pdf>` to execute the extraction-parsing-enrichment-evaluation pipeline.
- Enable `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to generate CSV reports (`resume_evaluations.csv`) and JSON caches in `cache/`.

## Frequently Asked Questions

### What Python version is required for interviewstreet hiring-agent?

Python 3.11 or newer is required. The repository specifically pins version 3.11.13 in the `.python-version` file, and dependencies in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) expect this version range.

### Can I run the hiring agent without an internet connection?

Yes, if you configure `LLM_PROVIDER=ollama` and use a locally pulled model like `gemma3:4b`. However, the GitHub enrichment feature in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) requires internet connectivity, and using Google Gemini necessitates an active API connection.

### Where does the hiring agent store evaluation results?

By default, results output to stdout only. When `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system appends evaluation records to `resume_evaluations.csv` and stores intermediate processing data as JSON in the `cache/` directory.

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

Modify the `LLM_PROVIDER` variable in your `.env` file to either `ollama` or `gemini`, update `DEFAULT_MODEL` to match your chosen backend (e.g., `gemma3:4b` or `gemini-2.5-pro`), and ensure `GEMINI_API_KEY` is set when using the Gemini provider. The [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) module automatically handles provider initialization based on these settings.