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

> Install the InterviewStreet Hiring Agent quickly with our step-by-step guide. Learn to set up your environment, configure settings, and evaluate resumes using LLMs.

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

---

**TLDR:** Clone the repository, set up a Python 3.11+ virtual environment, install dependencies via `pip install -r requirements.txt`, configure your `.env` file with `LLM_PROVIDER` and `DEFAULT_MODEL`, and execute `python score.py /path/to/resume.pdf` to evaluate resumes using either local Ollama models or Google Gemini.

The InterviewStreet Hiring-Agent is a Python-based pipeline that parses resume PDFs, enriches them with GitHub signals, and produces fair, explainable evaluations. Installing this tool from the interviewstreet/hiring-agent repository involves setting up the environment, installing core dependencies, and configuring one of two supported LLM backends to power the extraction and scoring modules.

## Prerequisites

Before installing the InterviewStreet Hiring-Agent, ensure your system meets the following requirements:

- **Python 3.11+** — The repository pins `.python-version` to 3.11.13, and all dependencies in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) are compatible with Python 3.11 and above.
- **Git** — Required to clone the repository from GitHub.
- **LLM Backend** — Either Ollama for local model serving or a Google Gemini API key for cloud-based inference.

## Installation Steps

### Clone the Repository

First, clone the hiring-agent repository and navigate into the project directory:

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

```

### Create a Virtual Environment

Create and activate a Python virtual environment to isolate dependencies:

```bash
python -m venv .venv
source .venv/bin/activate  # macOS/Linux

# .venv\Scripts\activate   # Windows

```

### Install Python Dependencies

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 the core libraries needed by modules including [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), [`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).

### Configure Environment Variables

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

```bash
cp .env.example .env

```

Edit `.env` to set your preferred LLM provider and model:

- `LLM_PROVIDER` — Set to `ollama` for local inference or `gemini` for Google Gemini.
- `DEFAULT_MODEL` — Specify the model name (e.g., `gemma3:4b` for Ollama or a Gemini model identifier).
- `GEMINI_API_KEY` — Required only if using the Gemini provider.
- `GITHUB_TOKEN` — Optional, but recommended to improve API rate limits when fetching GitHub data.

### Set Up the LLM Backend

**For Ollama (Local):**
Pull your desired model before running evaluations:

```bash
ollama pull gemma3:4b    # lightweight option

# or

ollama pull gemma3:12b   # larger model

```

Ensure the Ollama server is running (`ollama serve`) before executing the pipeline.

**For Google Gemini (Cloud):**
No additional local setup is required beyond setting the `GEMINI_API_KEY` in your `.env` file.

## Running the Pipeline

Once installation is complete, run a resume through the scoring pipeline using the entry point in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

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

```

The [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestrator will:

- Convert the PDF to Markdown-like text using [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) and cache it in `cache/resumecache_*.json`.
- Extract structured sections via [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) using Jinja templates from `prompts/templates/`.
- Detect and enrich GitHub profiles using [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), caching results in `cache/githubcache_*.json`.
- Run fairness-aware evaluation through [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).
- Print a readable summary and, when `DEVELOPMENT_MODE=True` (set in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py)), append results to `resume_evaluations.csv`.

## Core Architecture and Key Files

Understanding the main components helps troubleshoot installation issues:

| File | Purpose |
|------|---------|
| [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) | Main entry point that wires extraction, enrichment, evaluation, and reporting. |
| [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) | Handles PDF-to-Markdown conversion and section-wise LLM calls. |
| [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | Fetches GitHub profiles and classifies repositories. |
| [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | Implements strict-scored evaluation with fairness constraints. |
| [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) | Defines Pydantic schemas and LLM provider abstractions (`OllamaProvider`, `GeminiProvider`). |
| [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py) | Manages provider initialization and request handling. |
| [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) | Contains the `DEVELOPMENT_MODE` flag controlling caching behavior. |
| [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) | Lists all Python dependencies for installation. |
| `.env.example` | Template for environment configuration. |

## Summary

To successfully install the InterviewStreet Hiring-Agent:

- **Use Python 3.11+** and create a virtual environment before installing dependencies.
- **Install via `pip install -r requirements.txt`** to get all required libraries.
- **Configure `.env`** with `LLM_PROVIDER` and `DEFAULT_MODEL` to select between Ollama and Google Gemini.
- **Run `python score.py <resume.pdf>`** to execute the full pipeline from PDF parsing to fair evaluation.

## Frequently Asked Questions

### What Python version is required for InterviewStreet Hiring-Agent?

The repository requires **Python 3.11 or higher**, with the codebase specifically pinned to version 3.11.13 in `.python-version`. All dependencies in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) are tested against Python 3.11+.

### Can I run InterviewStreet Hiring-Agent without an internet connection?

**Yes, but only with Ollama.** If you set `LLM_PROVIDER=ollama` in your `.env` file and run a local model like `gemma3:4b`, the pipeline operates entirely offline (except for optional GitHub profile enrichment, which requires internet access). Using `LLM_PROVIDER=gemini` requires an active internet connection and API key.

### Where does the pipeline store cached data?

The Hiring-Agent stores intermediate results in a `cache/` directory: `resumecache_*.json` for PDF text extraction and `githubcache_*.json` for GitHub API responses. When `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), final evaluations are also appended to `resume_evaluations.csv` in the project root.

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

Edit the `.env` file and change `LLM_PROVIDER` to either `ollama` or `gemini`, then update `DEFAULT_MODEL` to match your chosen backend (e.g., `gemma3:4b` for Ollama or a Gemini model name). If switching to Gemini, ensure `GEMINI_API_KEY` is set. No reinstallation of Python dependencies is required to switch providers.