# How to Install and Run Interviewstreet Hiring Agent Locally

> Learn how to install and run Interviewstreet Hiring Agent locally. Clone the repo, set up Python dependencies, configure your environment, and process résumés with a simple command.

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

---

**Clone the repository, install Python 3.11+ dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configure your `.env` file for Ollama or Gemini, and execute `python score.py /path/to/resume.pdf` to process résumés.**

The Interviewstreet Hiring Agent is an open-source Python pipeline that automates résumé evaluation using LLMs and fairness-aware scoring rules. This guide explains the complete local installation and execution workflow based on the `interviewstreet/hiring-agent` source code, covering both local Ollama inference and Google Gemini cloud setups.

## Prerequisites

### Python Environment

You need **Python 3.11 or higher** to run the Hiring Agent. The repository pins the version to `3.11.13` in the `.python-version` file, ensuring compatibility with the Pydantic schemas and async features used throughout the codebase.

### LLM Backend

Choose one of two inference options:

- **Ollama** – Run models locally (recommended for privacy).
- **Google Gemini** – Use the cloud API (requires an API key).

## Installation and Setup

### Clone and Install Dependencies

Run the following 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 Ollama for Local Inference

If you selected Ollama, pull a compatible model before running evaluations:

```bash
ollama pull gemma3:4b

```

Alternative models include `gemma3:12b` and `gemma3:1b`, depending on your hardware constraints.

### Environment Variables

Copy the example configuration and edit the required variables:

```bash
cp .env.example .env

```

Edit `.env` to set:

- `LLM_PROVIDER` – `ollama` (default) or `gemini`
- `DEFAULT_MODEL` – e.g., `gemma3:4b` or `gemini-2.5-pro`
- `GEMINI_API_KEY` – Required only when `LLM_PROVIDER=gemini`
- `GITHUB_TOKEN` – Optional, but increases GitHub API rate limits for profile enrichment

## Running the Hiring Agent

### Execute the CLI

The entry point is [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py). Pass a path to a résumé PDF to start the evaluation:

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

```

### Pipeline Execution Flow

When you run the command, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestrates the following sequence:

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) invokes LLM calls with strict Jinja templates from `prompts/templates/` to populate the JSON-Resume 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) fetches candidate repositories and selects top projects.
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` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system appends a CSV row to `resume_evaluations.csv` and caches intermediate JSON in `cache/`.

## Programmatic Example

Automate the setup and execution in Python:

```python
import subprocess
import os

# Clone and install

subprocess.run(["git", "clone", "https://github.com/interviewstreet/hiring-agent"])
os.chdir("hiring-agent")
subprocess.run(["python", "-m", "venv", ".venv"])

# Activate and install dependencies (Linux/Mac example)

subprocess.run(["bash", "-c", "source .venv/bin/activate && pip install -r requirements.txt"])

# Configure environment

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

# Run evaluation

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

```

Replace `sample_resume.pdf` with your actual file path.

## Summary

- **Python 3.11+** is required to run the Hiring Agent locally.
- Install dependencies via `pip install -r requirements.txt` after cloning the repository.
- Configure `.env` to choose between **Ollama** (local) or **Gemini** (cloud) inference providers.
- Execute `python score.py <pdf_path>` to trigger the full pipeline from extraction to fairness-aware scoring.
- Enable `DEVELOPMENT_MODE` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to persist results to CSV and cache intermediate JSON files.

## Frequently Asked Questions

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

The codebase requires **Python 3.11 or higher**, with the repository specifically pinning version `3.11.13` in the `.python-version` file to ensure compatibility with the Pydantic models and async patterns used in modules like [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py).

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

Yes, if you use **Ollama** as your `LLM_PROVIDER` with a locally cached model such as `gemma3:4b`. However, the [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) enrichment step requires internet access to fetch candidate repositories, and Gemini mode obviously requires an API connection.

### Where are the evaluation results saved?

By default, results print to **stdout** only. When `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the pipeline additionally appends a CSV row to `resume_evaluations.csv` and stores intermediate JSON artifacts in the `cache/` directory for debugging.

### Which source file orchestrates the entire pipeline?

The **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** file serves as the CLI driver and orchestrator. It coordinates [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) for text extraction, [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for section parsing, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) for profile enrichment, and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) for final scoring.