Prerequisites for Setting Up the Hiring Agent: Complete Setup Guide

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.

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 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:

$ 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:

$ 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:

$ cp .env.example .env

Edit .env to configure your provider:

# 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 (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:

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

Optional: GitHub Token

The 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:

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

The 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 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 file manages runtime flags like DEVELOPMENT_MODE, while the .env file controls provider selection and API credentials.

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