# Dependencies for Running the Hiring-Agent: Complete Setup Guide

> Discover the essential dependencies needed to run the interviewstreet/hiring-agent. Learn about Python 3.11+, Pydantic, LLM inference tools, and more for a smooth setup.

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

---

**To run the Hiring-Agent from interviewstreet/hiring-agent, you need Python 3.11+ and nine pinned dependencies listed in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt), including PyMuPDF for PDF parsing, Ollama or Google Generative AI for LLM inference, and Pydantic for data validation.**

The Hiring-Agent is a pure Python application designed for automated resume scoring and candidate evaluation. According to the interviewstreet/hiring-agent source code, the project relies on a tightly pinned set of Python packages to handle PDF extraction, LLM orchestration, and data serialization. Understanding these dependencies is essential for running the pipeline locally without version conflicts.

## Python Runtime Requirement

The foundation requirement is **Python 3.11 or newer**, as specified in the repository's `.python-version` file. This version ensures compatibility with the modern type hints and Pydantic v2 models used throughout the codebase, particularly in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) where JSON-Resume schemas are defined.

## Core Python Package Dependencies

All production dependencies are pinned to specific versions in [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt) to guarantee reproducible builds. The following eight packages are required for runtime:

- **PyMuPDF (1.26.3)**: Handles PDF ingestion and text extraction in [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py)
- **pymupdf4llm (0.0.27)**: Provides helper utilities that convert PDF content into LLM-ready prompts
- **ollama (0.5.1)**: Client library for connecting to local Ollama LLM servers
- **google-generativeai (0.4.0)**: Official SDK for Google Gemini API integration (optional alternative to Ollama)
- **pydantic (2.11.7)**: Powers data validation and schema definitions in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py)
- **requests (2.32.4)**: HTTP client used by [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) for GitHub API interactions and LLM wrappers
- **Jinja2 (3.1.6)**: Template engine for rendering prompts stored in `prompts/templates/`
- **python-dotenv (1.0.1)**: Loads configuration variables from `.env` files at startup

Additionally, **black (25.9.0)** is included as a development convenience for code formatting.

## Step-by-Step Installation Guide

Install the Hiring-Agent dependencies by following these commands in a clean virtual environment:

1. Clone the repository and create a virtual environment:

```bash
git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

2. Install the pinned dependencies:

```bash
pip install -r requirements.txt

```

3. Configure required environment variables:

```bash
cp .env.example .env

# Edit .env to set LLM_PROVIDER=ollama (or gemini) and DEFAULT_MODEL=gemma3:4b

```

4. Run the end-to-end scoring pipeline:

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

```

## External Service Requirements

Beyond Python packages, the application requires active credentials for external services based on your chosen LLM provider. When using **Ollama**, you must have a local Ollama server accessible. When configured for **Gemini**, the pipeline requires a valid `GEMINI_API_KEY` environment variable. The GitHub enrichment feature in [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) additionally requires a `GITHUB_TOKEN` to avoid API rate limits when fetching candidate repositories.

## Summary

- **Python 3.11+** is mandatory as specified in the `.python-version` file
- Install **eight runtime dependencies** via [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/requirements.txt): PyMuPDF, ollama, pydantic, requests, pymupdf4llm, Jinja2, google-generativeai, and python-dotenv
- **black** is included for development formatting but is not required for production
- **Ollama** or **Google Generative AI** provide the LLM backend capabilities
- Copy `.env.example` to `.env` and configure provider-specific variables before executing [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py)
- The entry point [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestrates the full pipeline from PDF extraction via [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) to final candidate evaluation

## Frequently Asked Questions

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

The project requires **Python 3.11 or newer**, as defined in the `.python-version` file at the repository root. This ensures compatibility with the Pydantic v2 schemas and modern type hints used in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py).

### Can I run the Hiring-Agent without installing Ollama locally?

Yes, but you must configure an alternative LLM provider. The code supports **Google Gemini** via the `google-generativeai` package (version 0.4.0). Set `LLM_PROVIDER=gemini` in your `.env` file and provide a valid `GEMINI_API_KEY` to bypass the Ollama requirement.

### Why are dependency versions strictly pinned in requirements.txt?

The versions are pinned to ensure deterministic builds and prevent breaking changes from upstream API modifications. For example, **PyMuPDF 1.26.3** and **pymupdf4llm 0.0.27** must align exactly to guarantee proper PDF-to-Markdown conversion in the [`pymupdf_rag.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) module.

### Is the black code formatter required for production deployments?

No, **black 25.9.0** is listed as a development convenience for code formatting. The production runtime only requires the eight non-formatter packages to execute [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) successfully.