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

> Set up the Hiring Agent locally easily. Clone the repo, install dependencies, configure env variables, and run Python script for AI-powered resume scoring. Get started now.

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

---

**You can set up the Hiring Agent locally by cloning the interviewstreet/hiring-agent repository, installing dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configuring environment variables in `.env`, and running `python score.py path/to/resume.pdf` to generate AI-powered resume evaluations.**

The **Hiring Agent** is an open-source Python pipeline developed by Interview Street that converts resume PDFs into structured, explainable evaluations using large language models. Setting up the hiring-agent locally enables you to process candidate resumes through a five-stage pipeline—PDF extraction, section parsing, GitHub enrichment, fairness-aware scoring, and structured output—without requiring external API dependencies if using a local LLM.

## Prerequisites

Before installing the Hiring Agent, ensure you have the following tools installed on your machine:

- **Python 3.x** and `pip` for dependency management
- **Git** for cloning the repository
- **Ollama** (optional) if you plan to run local LLM inference instead of using Google's Gemini API

## Step-by-Step Installation

Follow these steps to install and configure the hiring-agent locally.

### Clone the Repository

First, clone the repository from GitHub and navigate into the project directory:

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

```

### Create a Virtual Environment

Create an isolated Python environment to avoid dependency conflicts:

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

### Install Dependencies

Install the required Python packages specified in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt):

```bash
pip install -r requirements.txt

```

## Configure Environment Variables and LLM Providers

The Hiring Agent uses environment variables defined in a `.env` file to select LLM providers and authentication tokens. Copy the example configuration file and customize it for your setup:

```bash
cp .env.example .env

```

Edit `.env` to set the following variables:

- `LLM_PROVIDER`: Set to `ollama` for local inference or `gemini` for Google Gemini
- `DEFAULT_MODEL`: The model name (e.g., `gemma3:4b` for Ollama or `gemini-1.5-flash` for Gemini)
- `GEMINI_API_KEY`: Your Google AI API key (required only for Gemini)
- `GITHUB_TOKEN`: Personal access token for GitHub API rate limits (optional but recommended)

### Local Ollama Setup

To use a local LLM without external API calls, install Ollama and pull your preferred model. According to the source code in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), the system supports the `OllamaProvider` class for local inference:

```bash
ollama pull gemma3:4b

```

When `LLM_PROVIDER=ollama`, the pipeline instantiates `OllamaProvider` via utility functions in [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py), which normalizes LLM responses for downstream processing.

### Google Gemini Configuration

For cloud-based inference, set `LLM_PROVIDER=gemini` and provide a valid `GEMINI_API_KEY`. The `GeminiProvider` class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) handles API communication, offering an alternative to local Ollama deployment when you need hosted model capabilities.

## Understanding the Pipeline Architecture

The hiring-agent processes resumes through five distinct stages, each implemented in specific source files:

1. **PDF Extraction**: [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) uses PyMuPDF to read PDF files and convert them to Markdown-like text.
2. **Section Parsing**: [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) sends resume sections (Basics, Work, Education, etc.) to the LLM using Jinja templates stored in `prompts/templates/`. The LLM returns structured JSON-Resume formats 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) extracts GitHub usernames from the resume, retrieves profile and repository data, classifies projects, and prompts the LLM to select the top 7 repositories for scoring.
4. **Evaluation**: [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) applies a strict, fairness-aware scoring rubric—evaluating open-source contributions, self-projects, production code, and technical skills—using additional Jinja templates for structured assessment.
5. **Output Generation**: [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) serves as the CLI entry point that orchestrates the entire pipeline. When `DEVELOPMENT_MODE=True` (the default setting in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the pipeline caches intermediate JSON files under `cache/` and appends results to `resume_evaluations.csv`.

The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file defines Pydantic schemas for data validation and provides the abstraction layer for both `OllamaProvider` and `GeminiProvider`, while [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) contains shared utilities for instantiating the selected provider and normalizing responses.

## Run Your First Resume Evaluation

Execute the end-to-end pipeline by passing a resume PDF to [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

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

```

The command generates a human-readable evaluation summary in the terminal. With `DEVELOPMENT_MODE` enabled (as configured in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), the system also writes intermediate processing files to the `cache/` directory and records the final scores in `resume_evaluations.csv` for batch analysis.

## Summary

- **Clone** the interviewstreet/hiring-agent repository and install dependencies via `pip install -r requirements.txt`.
- **Configure** the `.env` file with `LLM_PROVIDER`, `DEFAULT_MODEL`, and optional API keys for your chosen backend.
- **Select** between local inference using `OllamaProvider` (Ollama) or cloud inference using `GeminiProvider` (Google Gemini) as defined in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).
- **Execute** `python score.py path/to/resume.pdf` to run the pipeline, which extracts text via [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), parses sections via [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), enriches GitHub data via [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), and evaluates via [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).
- **Access** cached intermediate results in `cache/` and CSV output in `resume_evaluations.csv` when running in development mode.

## Frequently Asked Questions

### Do I need an internet connection to run the Hiring Agent locally?

No, if you configure `LLM_PROVIDER=ollama` in your `.env` file and use a locally downloaded model (e.g., `gemma3:4b`), the pipeline runs entirely offline. However, the optional GitHub enrichment stage in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) requires internet connectivity to fetch profile and repository data, and the Gemini provider requires an active connection to Google's API.

### What file serves as the main entry point for the CLI?

[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) functions as the primary orchestrator and CLI entry point. It coordinates the five-stage pipeline—invoking [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) for extraction, [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for parsing, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) for enrichment, and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) for scoring—before printing the final human-readable summary.

### Where does the pipeline store intermediate processing data?

When `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the system caches intermediate JSON files under the `cache/` directory and appends evaluation results to `resume_evaluations.csv`. This allows for debugging and batch analysis of candidate evaluations without re-running the LLM-intensive stages.

### How do I switch between different LLM providers?

Modify the `LLM_PROVIDER` environment variable in your `.env` file to either `ollama` or `gemini`. The [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) module instantiates the appropriate provider class (`OllamaProvider` or `GeminiProvider`) from [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) based on this setting, automatically handling the different API interfaces and response formats.