# How to Install the Hiring-Agent: Complete Setup Guide for the InterviewStreet Pipeline

> Learn how to install the hiring-agent with this complete setup guide. Follow simple steps to clone the repository, configure dependencies, and integrate your LLM backend for seamless interview automation.

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

---

**You can install the hiring-agent by cloning the repository, creating a Python 3.11+ virtual environment, installing dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), setting up an LLM backend (Ollama or Google Gemini), and configuring environment variables in `.env`.**

The **hiring-agent** repository from InterviewStreet is a Python 3.11+ project that transforms résumé PDFs into structured JSON-Resume format, enriches them with GitHub signals, and generates fair, explainable candidate scores. To install the hiring-agent locally, you need to configure a Python environment, install runtime dependencies, and connect either a local Ollama instance or the Google Gemini API for LLM processing.

## Prerequisites

Before you install the hiring-agent, ensure you have:

- **Python 3.11 or higher** installed on your system
- **Git** for cloning the repository
- An **LLM backend**:
  - **Ollama** (recommended for local deployment) – download from ollama.com
  - **Google Gemini** – requires an API key from Google AI Studio

## Step-by-Step Installation Guide

### 1. Clone the Repository and Create a Virtual Environment

Start by cloning the source code and creating an isolated Python environment to avoid conflicts with system packages.

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

```

Activate the virtual environment:

- **Linux/macOS**: `source .venv/bin/activate`
- **Windows**: `.venv\Scripts\activate`

### 2. Install Python Dependencies

With the environment activated, install all required packages specified in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt):

```bash
pip install -r requirements.txt

```

This installs runtime dependencies including **PyMuPDF** (for PDF processing), **Pydantic** (for data validation), and **Jinja2** (for LLM prompt templating).

### 3. Set Up the LLM Backend

Choose and configure one of the supported LLM providers:

**Option A: Local Ollama Setup**

Install Ollama from the official website, then start the server and pull a compatible model:

```bash
ollama serve &
ollama pull gemma3:4b

```

The repository documentation recommends `gemma3:4b` or similar models for parsing résumés and evaluating candidates.

**Option B: Google Gemini Setup**

If using Google Gemini instead of Ollama, obtain an API key from Google AI Studio. You will configure this key in the next step.

### 4. Configure Environment Variables

Copy the example environment file and customize it for your setup:

```bash
cp .env.example .env

```

Edit `.env` to set the required variables:

- `LLM_PROVIDER=ollama` (or `gemini`)
- `DEFAULT_MODEL=gemma3:4b` (or the specific Gemini model name)
- `GEMINI_API_KEY=your-key` (required only if using Gemini)

Additional configuration flags like `DEVELOPMENT_MODE` can be set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) or via environment variables to control whether the pipeline appends results to a CSV file.

## Verify the Installation

Test your installation by running the end-to-end scoring pipeline on a sample résumé:

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

```

When executed, [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestrates the full pipeline:

1. Converts the PDF to markdown using [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)
2. Calls the LLM per section using Jinja templates defined in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)
3. Enriches the data with GitHub signals via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)
4. Applies fairness-aware scoring rules in [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)
5. Prints a human-readable report and optionally writes a CSV entry if `DEVELOPMENT_MODE=True`

## Key Source Files in the Pipeline

Understanding these core files helps troubleshoot installation issues:

- **[`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt)** – Lists all Python dependencies (PyMuPDF, Pydantic, etc.)
- **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** – Main entry point that wires together the entire pipeline
- **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** – Handles PDF-to-markdown conversion and LLM section calls
- **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** – Fetches and processes GitHub profile and repository data
- **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** – Implements fairness-aware scoring using LLM templates
- **`prompts/templates/`** – Contains Jinja templates for extraction and scoring prompts
- **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)** – Houses global configuration flags including `DEVELOPMENT_MODE`

## Summary

- **Clone** the repository from `https://github.com/interviewstreet/hiring-agent` and create a Python 3.11+ virtual environment.
- **Install dependencies** using `pip install -r requirements.txt` to get PyMuPDF, Pydantic, and Jinja2.
- **Configure an LLM backend** by either running `ollama serve` with a local model like `gemma3:4b` or setting up a Google Gemini API key.
- **Set environment variables** in `.env` to specify `LLM_PROVIDER`, `DEFAULT_MODEL`, and optional `GEMINI_API_KEY`.
- **Validate** the installation by running `python score.py` against a sample PDF to ensure the pipeline executes correctly.

## Frequently Asked Questions

### What version of Python is required to install the hiring-agent?

The hiring-agent requires **Python 3.11 or higher**. This version requirement ensures compatibility with the type hints and async features used in [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

### Can I use a different LLM model with Ollama?

Yes. While the documentation recommends `gemma3:4b`, you can substitute any Ollama-compatible model by changing the `DEFAULT_MODEL` variable in your `.env` file. Ensure the model supports JSON output for reliable parsing of résumé sections.

### Where do I configure the DEVELOPMENT_MODE setting?

The `DEVELOPMENT_MODE` flag is defined in **[`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)** but can be overridden via environment variables. When set to `True`, the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) script appends scoring results to a CSV file in addition to printing the report.

### Why does the installation require both PyMuPDF and an LLM backend?

**PyMuPDF** (imported in [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)) handles the initial PDF-to-markdown conversion, while the **LLM backend** (configured via `LLM_PROVIDER`) performs the semantic extraction of structured data, GitHub signal enrichment, and fairness-aware evaluation. The pipeline relies on both components to transform raw PDFs into scored candidate profiles.