# Prerequisites for Setting Up the Hiring Agent: Complete Setup Guide

> Set up the Hiring Agent easily. Discover the essential prerequisites including Python 3.11+, LLM backends, and environment configuration for a smooth installation.

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

---

**Setting up the Hiring Agent requires Python 3.11+, an LLM backend (Ollama or Gemini), a configured `.env` file, and installed dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt).**

The Hiring Agent from the `interviewstreet/hiring-agent` repository automates resume parsing and candidate evaluation through a PDF-to-JSON pipeline. Before running the scoring logic, you must configure a specific environment that supports async LLM wrappers, Pydantic models, and optional GitHub enrichment. The following prerequisites ensure the [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) script executes without dependency or runtime errors.

## Python 3.11+ Runtime Environment

The codebase relies on modern Python features including advanced type hints, f-strings, and typing extensions that stabilize only in Python 3.11. The repository pins this requirement in the `.python-version` file and documents it in the README at lines 84-87.

This version guarantees compatibility with `pydantic` models, `PyMuPDF`, and the async LLM wrappers used throughout the pipeline.

Verify your installation and create an isolated environment:

```bash
$ python --version
Python 3.11.13

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

# .venv\Scripts\activate     # Windows

```

## LLM Backend Configuration

The pipeline requires an LLM to parse resume sections and evaluate projects. You must choose either a local Ollama server or Google Gemini, as documented in the README at lines 88-93.

### Option 1: Ollama (Local)

Ollama runs models locally without API keys. Install the binary from the official site, start the server, and pull a compatible model such as `gemma3:4b`:

```bash
$ ollama serve
$ ollama pull gemma3:4b

```

### Option 2: Google Gemini (Cloud)

For cloud-based inference, obtain an API key from Google AI Studio. Set `LLM_PROVIDER=gemini` and configure your credentials in the environment file.

## Environment Variables Setup

Centralized configuration resides in a `.env` file. The repository provides a template at `.env.example` (referenced in README.md lines 31-35). Copy this template and edit values to match your chosen LLM backend:

```bash
$ cp .env.example .env

```

Edit `.env` to configure your provider:

```dotenv

# For Ollama

LLM_PROVIDER=ollama
DEFAULT_MODEL=gemma3:4b

# For Gemini

# LLM_PROVIDER=gemini

# GEMINI_API_KEY=your-key-here

# Optional

# GITHUB_TOKEN=your-token-here

```

The application reads these variables via `os.getenv` calls throughout the codebase.

## Dependency Installation

Required packages are locked in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) (README.md lines 95-107). These include specific versions of `pymupdf` for PDF processing, `pydantic` for data validation, and `jinja2` for templating.

After activating your virtual environment, install all dependencies:

```bash
(.venv) $ pip install -r requirements.txt

```

## Optional: GitHub Token

The [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module enriches candidate profiles by fetching public repositories. While optional, a `GITHUB_TOKEN` increases rate limits above unauthenticated thresholds. Configure this in your `.env` file or export it directly in your shell, as noted in the environment variables table at lines 39-44 of the README.

## Verification

Once prerequisites are satisfied, execute the scoring pipeline:

```bash
(.venv) $ python score.py path/to/resume.pdf

```

The [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) file contains a `DEVELOPMENT_MODE` flag that influences caching behavior and CSV export formatting during execution.

## Summary

- **Python 3.11+** is mandatory for type hint compatibility and is enforced via the `.python-version` file.
- **LLM Backend** must be either a local Ollama server or Google Gemini API.
- **Environment Configuration** requires copying `.env.example` to `.env` and setting `LLM_PROVIDER` and model variables.
- **Dependencies** install via `pip install -r requirements.txt` and include `pymupdf`, `pydantic`, and `jinja2`.
- **GitHub Token** is optional but recommended to avoid rate limits during repository enrichment.

## Frequently Asked Questions

### Can I use Python 3.10 or earlier to run the Hiring Agent?

No. The source code utilizes typing extensions and syntax features that are only stable in Python 3.11+. Attempting to run on earlier versions will cause import errors with Pydantic models and async wrapper functions.

### Is Ollama required if I use Google Gemini?

No. You can choose either backend exclusively. Set `LLM_PROVIDER=gemini` in your `.env` file and provide a valid `GEMINI_API_KEY`. Ollama is only required if you prefer local inference without external API calls.

### Do I need a GitHub token to process resumes?

No. The GitHub token is optional. Without it, the [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) module operates with unauthenticated rate limits, which may throttle requests when fetching candidate repositories. For production evaluations with many candidates, a token is recommended.

### Where are the LLM provider settings validated?

The application reads configuration through `os.getenv` calls and validates settings during initialization. The [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py) file manages runtime flags like `DEVELOPMENT_MODE`, while the `.env` file controls provider selection and API credentials.