# How to Set Up the Hiring-Agent Environment for Development

> Quickly set up your hiring agent development environment. Clone the repo, install dependencies, configure your LLM, and run the scoring script for résumés.

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

---

**You can set up the hiring-agent development environment by cloning the repository, installing Python 3.11+ dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), configuring your `.env` file for either local Ollama or cloud Gemini LLM providers, and running `python score.py` on a résumé PDF.**

Hiring-agent is an open-source Python pipeline from InterviewStreet that extracts résumé data from PDFs, enriches it with GitHub signals, and generates fair, explainable evaluations using large language models. To set up the hiring-agent environment for development, you need Python 3.11+, the dependencies listed in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), and either a local Ollama instance or Google Gemini API credentials.

## Prerequisites

Before installing the hiring-agent pipeline, ensure your system meets these requirements:

- **Python 3.11 or higher** (required for Pydantic and modern async features used in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py))
- **Git** for cloning the repository
- **Ollama** (optional) for local LLM inference, or a **Google Gemini API key** for cloud-based inference

## Step 1: Clone the Repository and Install Dependencies

Start by cloning the interviewstreet/hiring-agent repository and creating an isolated Python 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

```

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

## Step 2: Configure Environment Variables

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

```bash
cp .env.example .env

```

Edit `.env` to set the following variables as defined in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py):

- **`DEVELOPMENT_MODE`**: Set to `True` to enable JSON caching and CSV export for rapid iteration
- **`LLM_PROVIDER`**: Choose `ollama` for local development or `gemini` for cloud API access
- **`DEFAULT_MODEL`**: Specify the model name (e.g., `gemma3:4b` for Ollama or `gemini-pro` for Gemini)
- **`GEMINI_API_KEY`**: Required only if using the Gemini provider

## Step 3: Set Up Your LLM Provider

The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file provides provider-agnostic wrappers that translate requests to either `ollama.chat` or `google.generativeai` based on your configuration.

### Local Development with Ollama

For fully offline development, install and start Ollama:

```bash

# Install Ollama from https://ollama.com/ first

ollama serve        # Starts the Ollama daemon

ollama pull gemma3:4b

```

Set your `.env` file to:

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

```

### Cloud Development with Gemini

For cloud-based inference without local GPU requirements:

1. Obtain a Gemini API key from Google AI Studio
2. Set your `.env` file to:

```bash
LLM_PROVIDER=gemini
DEFAULT_MODEL=gemini-pro
GEMINI_API_KEY=your_key_here
DEVELOPMENT_MODE=True

```

## Step 4: Run the End-to-End Pipeline

Execute the orchestration script [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) to process a résumé PDF:

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

```

The pipeline executes the following sequence implemented across the source files:

1. **[`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py)** and **[`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)** extract text from PDF pages using PyMuPDF and convert them to Markdown-like text for LLM processing
2. **[`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py)** detects GitHub profile URLs in the résumé, fetches profile and repository data, and caches results as `cache/githubcache_<basename>.json`
3. **[`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py)** applies fairness-aware scoring rules evaluating open-source contributions, self-projects, production experience, and technical skills
4. **[`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)** aggregates results, prints a human-readable summary, and writes a CSV row when `DEVELOPMENT_MODE` is enabled

## Development Mode Features

When `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the pipeline activates several developer-friendly features:

- **JSON Caching**: Intermediate extraction results are stored under `cache/` to avoid re-processing PDFs during iterative development
- **GitHub Data Caching**: Profile and repository data fetched by [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) persists locally to respect API rate limits
- **CSV Export**: Evaluation results append to a CSV file for easy analysis and comparison across multiple résumés

## Summary

- **Clone** the interviewstreet/hiring-agent repository and install Python 3.11+ dependencies via `pip install -r requirements.txt`
- **Configure** your `.env` file by copying `.env.example` and setting `LLM_PROVIDER`, `DEFAULT_MODEL`, and optional `GEMINI_API_KEY`
- **Select** either local Ollama inference (offline) or cloud Gemini API (remote) in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) via the provider configuration
- **Enable** `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) to activate JSON caching and CSV exports while iterating on the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) pipeline
- **Execute** `python score.py path/to/resume.pdf` to run the full résumé extraction, GitHub enrichment, and fairness-aware evaluation pipeline

## Frequently Asked Questions

### What Python version is required for hiring-agent?

Hiring-agent requires **Python 3.11 or higher** to support the Pydantic schemas and type hints used in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) and the async patterns in the LLM orchestration layer. Earlier versions may fail when validating the data models that structure résumé sections and GitHub repository metadata.

### Can I run hiring-agent without an internet connection?

Yes, you can run the pipeline entirely offline by configuring **Ollama** as your LLM provider in `.env` with `LLM_PROVIDER=ollama`. However, the **GitHub enrichment** feature in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) requires internet access to fetch profile and repository data. If offline, the pipeline will skip GitHub analysis and proceed with PDF-based evaluation only.

### Where does hiring-agent store cached data during development?

When `DEVELOPMENT_MODE=True` in [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), the pipeline stores intermediate JSON files in a `cache/` directory at the project root. Specifically, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) saves profile data as `cache/githubcache_<basename>.json`, while processed résumé sections are cached to avoid redundant LLM calls during iterative testing of [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

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

Edit the `.env` file and change the `LLM_PROVIDER` value to either `ollama` or `gemini`. The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file dynamically imports the appropriate client library based on this setting, translating your prompts to either `ollama.chat()` for local models or `google.generativeai` for cloud APIs. Ensure you have the corresponding API key or local daemon running before executing [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).