Requirements to Run Hiring Agent: Complete Setup and Installation Guide

To run Hiring Agent, you need Python 3.11+, dependencies installed from 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 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.

pip install -r requirements.txt

Environment Configuration

Copy the template environment file and configure your variables:

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:

ollama serve

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

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:

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:

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

The pipeline orchestrates several steps defined across the codebase: pymupdf_rag.py handles PDF-to-Markdown conversion, pdf.py calls the LLM using Jinja templates from prompts/templates/, github.py fetches repository data, and evaluator.py applies the fairness-aware scoring rubric.

Development Mode

The 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 – Lists all third-party Python dependencies
• score.py – Main orchestration script that runs the full pipeline
• models.py – Defines Pydantic schemas and provider-specific wrappers for Ollama and Gemini
• 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 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, pdf.py, and 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 file handles the provider-specific logic automatically based on these environment variables.

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