# How to Set Up a Development Environment for Hiring‑Agent: A Complete Guide

> Easily set up your development environment for Hiring-Agent. Clone the repo, install dependencies, configure LLM inference, and start scoring résumés with this complete guide.

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

---

**To set up a development environment for Hiring‑Agent, clone the repository, create a Python 3.11+ virtual environment, install dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configure your `.env` file for either local Ollama or cloud Gemini inference, and run `python score.py` on a résumé PDF.**

Hiring‑Agent is an open‑source Python pipeline from the `interviewstreet/hiring-agent` repository that extracts structured data from résumé PDFs, enriches it with GitHub signals, and generates fair, explainable evaluations using large language models (LLMs). The codebase is designed to run entirely offline with local models or connect to cloud APIs, making it flexible for different development workflows.

## Prerequisites and System Requirements

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

- **Python 3.11 or higher** – The codebase uses modern Python features and type hinting.
- **Git** – For cloning the repository.
- **Ollama** (optional) – Required only if you plan to run models locally rather than using Google Gemini.

The repository supports both **local inference** via Ollama and **remote inference** via the Gemini API, selectable through environment configuration.

## Step‑by‑Step Installation

Follow these seven steps to configure your local development environment:

```bash

# 1️⃣ Clone the repository

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

# 2️⃣ Create and activate a Python 3.11+ virtual environment

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

# .venv\Scripts\activate    # Windows

# 3️⃣ Install Python dependencies

pip install -r requirements.txt

# 4️⃣ Set up environment variables

cp .env.example .env

# Edit .env to configure your LLM provider and model

# 5️⃣ (Optional) Install and start Ollama for local inference

ollama serve                # Starts the Ollama daemon

# 6️⃣ Pull your desired local model

ollama pull gemma3:4b

# 7️⃣ Run the scoring pipeline on a résumé PDF

python score.py path/to/resume.pdf

```

The [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) file pins critical dependencies including **PyMuPDF** for PDF processing, **ollama** for local LLM communication, and **pydantic** for data validation.

## Configuring LLM Providers

Hiring‑Agent abstracts LLM access through the [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) module, which provides provider‑agnostic wrappers for **Ollama** and **Google Gemini**.

### Local Development with Ollama

For offline development or cost‑free experimentation, configure your `.env` file:

```bash
LLM_PROVIDER=ollama
DEFAULT_MODEL=gemma3:4b

```

Ensure the Ollama daemon is running (`ollama serve`) and the specified model is downloaded. The wrapper in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) translates requests to `ollama.chat` calls.

### Cloud Development with Gemini

For production‑grade inference without local GPU resources, use Google Gemini:

```bash
LLM_PROVIDER=gemini
GEMINI_API_KEY=your_api_key_here
DEFAULT_MODEL=gemini-1.5-pro

```

The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) implementation routes these requests through `google.generativeai` when `LLM_PROVIDER` is set to `gemini`.

## Understanding the Architecture

The repository consists of specialized modules that form a cohesive data pipeline:

| Component | Source Files | Purpose |
|-----------|--------------|---------|
| **PDF Extraction** | [`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) | Converts PDF pages to Markdown‑like text using PyMuPDF and calls the LLM per section. |
| **LLM Orchestration** | [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py), [`llm_utils.py`](https://github.com/interviewstreet/hiring-agent/blob/main/llm_utils.py), [`prompt.py`](https://github.com/interviewstreet/hiring-agent/blob/main/prompt.py) | Loads Jinja templates from the `prompts/` directory and manages provider‑specific API calls. |
| **GitHub Enrichment** | [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | Detects GitHub URLs in résumés, fetches profile and repository data, and uses the LLM to identify top contributions. |
| **Evaluation Engine** | [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | Applies fairness‑aware scoring rules (open‑source contributions, production experience, technical skills) and calculates bonus/deduction totals. |
| **CLI Entry Point** | [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) | Orchestrates the full pipeline, handles caching, and outputs human‑readable summaries. |
| **Configuration** | [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), `.env.example` | Global settings including `DEVELOPMENT_MODE` and LLM provider selection. |

The [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) script serves as the primary interface, importing logic from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for text extraction, [`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 final scoring.

## Development Mode and Caching

Enable `DEVELOPMENT_MODE` in your `.env` or [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to accelerate iterative development:

```python

# In config.py or .env

DEVELOPMENT_MODE=True

```

When enabled, the pipeline caches intermediate JSON results in the `cache/` directory. Specifically:

- [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) checks for cached JSON under `cache/` before re‑processing a PDF.
- [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) stores fetched profile data as `cache/githubcache_<basename>.json`.

This caching mechanism prevents redundant LLM calls and GitHub API requests during debugging and feature development. Additionally, `DEVELOPMENT_MODE` activates CSV export functionality for batch processing results.

## Summary

- **Clone** the `interviewstreet/hiring-agent` repository and create a Python 3.11+ virtual environment.
- **Install** dependencies via `pip install -r requirements.txt`.
- **Configure** your `.env` file to select between **Ollama** (local) or **Gemini** (cloud) providers using the `LLM_PROVIDER` variable.
- **Execute** the pipeline with `python score.py <pdf_path>` after optionally starting the Ollama daemon.
- **Enable** `DEVELOPMENT_MODE` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to cache intermediate JSON results and enable CSV exports for rapid iteration.
- **Extend** functionality by modifying specialized modules like [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py), or the Jinja templates in `prompts/`.

## Frequently Asked Questions

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

Hiring‑Agent requires **Python 3.11 or higher**. The codebase leverages modern type hinting and syntax features introduced in recent Python versions, and the [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) is tested against Python 3.11+ environments.

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

Yes, by setting `LLM_PROVIDER=ollama` in your `.env` file and running a local model like `gemma3:4b`. You will need internet connectivity only for the initial Ollama installation and model download; subsequent inferences run entirely offline. However, GitHub enrichment features in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) require internet access to fetch repository data unless cached results already exist.

### Where does Hiring‑Agent cache intermediate results?

The pipeline stores cached data in a `cache/` directory at the repository root. [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) caches processed résumé JSON, while [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) stores GitHub profile data as `cache/githubcache_<basename>.json`. These caches are only utilized when `DEVELOPMENT_MODE` is set to `True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py).

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

Modify the `LLM_PROVIDER` environment variable in your `.env` file. Set it to `ollama` for local inference (requires the Ollama daemon running) or `gemini` for cloud inference (requires `GEMINI_API_KEY`). The abstraction layer in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) handles the translation to provider‑specific SDK calls automatically.