What Are the Dependencies for Running the Hiring Agent?

The Hiring Agent requires Python 3.11 or newer, nine pinned Python packages (including PyMuPDF, Ollama, and Pydantic), and properly configured environment variables to execute the resume scoring pipeline.

The Hiring Agent from the interviewstreet/hiring-agent repository is a pure Python application that orchestrates PDF resume parsing, GitHub profile enrichment, and LLM-based evaluation. Understanding the dependencies for running the Hiring Agent is essential before executing the end-to-end scoring workflow on local infrastructure.

Core Runtime Requirements

The foundation of the Hiring Agent is a modern Python interpreter. According to the .python-version file in the repository root, the project targets Python 3.11 or newer. This version requirement ensures compatibility with the type hinting and async features used throughout the codebase, particularly in models.py and the LLM provider abstractions.

All dependencies are strictly pinned in requirements.txt to ensure reproducible behavior across different environments.

Python Package Dependencies

The Hiring Agent relies on nine production dependencies and one development tool, each serving a specific function in the pipeline:

PDF Processing and Extraction

• PyMuPDF (1.26.3) — Handles PDF file I/O and extracts raw text/structure from resume documents.
• pymupdf4llm (0.0.27) — Converts extracted PDF content into Markdown-formatted prompts suitable for LLM consumption, as implemented in pymupdf_rag.py.

LLM Integration and AI Services

• ollama (0.5.1) — Client library for communicating with a local Ollama LLM server, enabling on-premise inference without external API calls.
• google-generativeai (0.4.0) — Official Google client for Gemini integration, providing an optional cloud-based LLM backend alternative to Ollama.

Data Validation and HTTP Communication

• pydantic (2.11.7) — Powers the JSON-Resume data models and schema validation defined in models.py, ensuring type safety across the extraction and enrichment stages.
• requests (2.32.4) — Standard HTTP client used by github.py to fetch candidate repository data and by LLM wrapper classes for API communication.

Template Rendering and Configuration

• Jinja2 (3.1.6) — Renders dynamic prompt templates stored in prompts/templates/, allowing parameterized system prompts for different evaluation criteria.
• python-dotenv (1.0.1) — Loads runtime configuration from .env files, managing secrets like GEMINI_API_KEY and GITHUB_TOKEN outside the source code.

Development Tools

• black (25.9.0) — Code formatter included for development convenience to maintain consistent style across the codebase.

Environment Configuration Dependencies

Beyond Python packages, the Hiring Agent requires specific environment variables defined in a .env file. The repository provides .env.example as a template containing:

• LLM_PROVIDER — Set to ollama or gemini to select the backend.
• DEFAULT_MODEL — Specifies the model name (e.g., gemma3:4b for Ollama).
• GEMINI_API_KEY — Required when using the Google Gemini backend.
• GITHUB_TOKEN — Personal access token for GitHub API rate limits and private repository access.

Installation and Verification

To satisfy all dependencies for running the Hiring Agent, execute the following steps:

# Clone the repository and create an isolated environment

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

# Install the pinned dependency tree

pip install -r requirements.txt

# Configure environment variables

cp .env.example .env

# Edit .env to set LLM_PROVIDER, DEFAULT_MODEL, and API keys

# Verify installation by running the scoring pipeline

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

Key Source Files and Dependency Mapping

Understanding which source files rely on specific dependencies helps debug installation issues:

• requirements.txt — The single source of truth for all pinned package versions.
• pymupdf_rag.py — Imports fitz (PyMuPDF) and pymupdf4llm for PDF-to-Markdown conversion.
• github.py — Depends on requests for HTTP operations against the GitHub API.
• models.py — Uses pydantic for schema definitions and google.generativeai for Gemini model interactions.
• prompts/templates/ — Relies on jinja2 for template inheritance and variable substitution.
• score.py — The CLI entry point that orchestrates all dependencies into the evaluation workflow.

Summary

• Python 3.11+ is mandatory for running the Hiring Agent pipeline.
• Nine production packages are pinned in requirements.txt, including PyMuPDF for PDF processing, Ollama for local LLM inference, and Pydantic for data validation.
• Environment variables defined in .env control LLM provider selection and API authentication.
• Jinja2 templates in prompts/templates/ drive the prompt engineering layer.
• The Black formatter is included as a development convenience but is not required for runtime execution.

Frequently Asked Questions

Is the Hiring Agent compatible with Python 3.10 or older versions?

No. The repository explicitly requires Python 3.11 or newer as specified in the .python-version file. The codebase utilizes modern Python features for type safety and async operations that are not available in earlier versions.

Can I run the Hiring Agent without installing Ollama?

Yes, but you must configure the Google Gemini backend instead. Set LLM_PROVIDER=gemini and provide a valid GEMINI_API_KEY in your .env file. However, you still need to install the ollama Python package (0.5.1) as it remains a declared dependency in requirements.txt even if unused at runtime.

Why does the project require both PyMuPDF and pymupdf4llm?

PyMuPDF provides low-level PDF parsing and text extraction capabilities, while pymupdf4llm (version 0.0.27) offers high-level utilities specifically designed to convert PDF content into LLM-optimized Markdown prompts. The pymupdf_rag.py module uses both libraries to bridge raw document extraction and prompt engineering.

Are the dependencies for GitHub integration mandatory?

Yes, if you want to enrich candidate profiles with repository data. The github.py module depends on requests (2.32.4) to fetch public and private repository information. Without a valid GITHUB_TOKEN set in your environment, the GitHub enrichment stage will fail or operate under strict rate limits.

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