# Requirements to Run Hiring Agent: Complete Setup and Installation Guide

> Discover the requirements to run Hiring Agent. Install Python 3.11+, dependencies, and configure Ollama or Gemini API for seamless setup. Get the complete guide now.

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

---

**To run Hiring Agent, you need Python 3.11+, dependencies installed from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), and either a local Ollama instance with a pulled model or a Google Gemini API key configured via environment variables.**

Hiring Agent from the `interviewstreet/hiring-agent` repository is a Python-based resume-to-score pipeline that evaluates candidates using large language models. Understanding the requirements to run Hiring Agent ensures you can process PDF resumes locally without encountering dependency or configuration errors. This guide covers the essential prerequisites, LLM backend options, and environment setup needed to execute the scoring pipeline.

## System Prerequisites

### Python 3.11 or Higher

The project requires **Python 3.11+** as specified in the `.python-version` file and noted in the README. This version is mandatory because the codebase uses modern Python features and type hints that are not backward compatible with earlier releases.

### Supported LLM Backends

You must configure one of two supported large language model providers:

- **Ollama** – A local model server that runs entirely on your machine
- **Google Gemini** – A cloud-based API requiring an authentication key

## Installation Steps

### Python Dependencies

Install all required packages listed in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) using pip. This file includes essential libraries such as `pymupdf` for PDF processing, `pydantic` for data validation, `jinja2` for templating, and the LLM client wrappers.

```bash
pip install -r requirements.txt

```

### Environment Configuration

Copy the template environment file and configure your variables:

```bash
cp .env.example .env

```

Edit `.env` to set these critical variables:

- `LLM_PROVIDER` – Set to `ollama` or `gemini` (defaults to `ollama`)
- `DEFAULT_MODEL` – The model name (e.g., `gemma3:4b` for Ollama or `gemini-2.5-pro` for Gemini)
- `GEMINI_API_KEY` – Required when using the Gemini provider
- `GITHUB_TOKEN` – Optional but recommended to improve GitHub API rate limits

## Configuring the LLM Provider

### Ollama Local Setup

For local execution, install Ollama separately from the official website, then start the server:

```bash
ollama serve

```

Pull a compatible model before running the pipeline. The repository recommends lightweight models like `gemma3:4b`:

```bash
ollama pull gemma3:4b

```

### Google Gemini Setup

If using Gemini instead of Ollama, obtain an API key from Google AI Studio and set it in your `.env` file:

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

```

## Running the Pipeline

Once dependencies and environment variables are configured, execute the main entry point in [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py):

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

```

The pipeline orchestrates several steps defined across the codebase: [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) handles PDF-to-Markdown conversion, [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) calls the LLM using Jinja templates from `prompts/templates/`, [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) fetches repository data, and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) applies the fairness-aware scoring rubric.

### Development Mode

The [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) file defines `DEVELOPMENT_MODE = True`. When enabled, the pipeline caches intermediate JSON outputs and writes CSV summaries, which is useful for debugging during initial setup.

## Key Source Files

Understanding these core files helps troubleshoot setup issues:

- [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) – Lists all third-party Python dependencies
- [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) – Main orchestration script that runs the full pipeline
- [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) – Defines Pydantic schemas and provider-specific wrappers for Ollama and Gemini
- [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) – Contains global flags including `DEVELOPMENT_MODE`
- `.env.example` – Template showing required environment variables

## Summary

- **Python 3.11+** is mandatory as specified in `.python-version`
- Install dependencies via `pip install -r requirements.txt`
- Choose between **Ollama** (local) or **Google Gemini** (cloud API) as your LLM provider
- Configure environment variables in `.env` copied from `.env.example`
- For Ollama, run `ollama pull` to download models like `gemma3:4b` before execution
- Run the pipeline with `python score.py <resume.pdf>`

## Frequently Asked Questions

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

Yes, but only if you use the **Ollama** backend with locally pulled models. The `ollama serve` command runs entirely offline once models are downloaded. However, if you enable GitHub enrichment or use the Gemini provider, an internet connection is required for API calls.

### What Python packages are installed from requirements.txt?

The [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) installs several critical packages including `pymupdf` for PDF text extraction, `pydantic` for data validation, `jinja2` for template rendering, and various LLM client libraries. These dependencies support the pipeline stages defined in [`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), and [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py).

### Is the Gemini API key required for all installations?

No, the **Gemini API key** is only required when you set `LLM_PROVIDER=gemini` in your `.env` file. If you use the default Ollama backend, you do not need a Gemini key or any cloud API credentials, though you must have Ollama installed and running locally.

### How do I switch between Ollama and Gemini after initial setup?

Simply modify the `LLM_PROVIDER` and `DEFAULT_MODEL` variables in your `.env` file. For Ollama, ensure the model is pulled locally using `ollama pull <model-name>`. For Gemini, ensure `GEMINI_API_KEY` is set. The [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) file handles the provider-specific logic automatically based on these environment variables.