Dependencies for Running the Hiring-Agent: Complete Setup Guide

To run the Hiring-Agent from interviewstreet/hiring-agent, you need Python 3.11+ and nine pinned dependencies listed in 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 where JSON-Resume schemas are defined.

Core Python Package Dependencies

All production dependencies are pinned to specific versions in 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
• 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
• requests (2.32.4): HTTP client used by 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:

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:

pip install -r requirements.txt

3. Configure required environment variables:

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:

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 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: 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
• The entry point score.py orchestrates the full pipeline from PDF extraction via 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.

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 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 successfully.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}