How to Set Up the Interviewstreet Hiring Agent Locally: Complete Installation Guide

Clone the repository, create a Python 3.11+ virtual environment, install dependencies from requirements.txt, configure your .env file with LLM_PROVIDER and model details, then run python score.py /path/to/resume.pdf to evaluate candidates locally.

The Interviewstreet Hiring Agent is an open-source Python pipeline that automates résumé evaluation by extracting PDF content, parsing sections with LLM-powered Jinja templates, enriching profiles with GitHub data, and applying fairness-aware scoring rules. This guide covers how to set up the Interviewstreet Hiring Agent locally using either a local Ollama instance or the Google Gemini API, based on the official repository structure and source code.

Prerequisites

Before installation, ensure your system meets the following requirements defined in the repository configuration.

Python Version Requirements

The Hiring Agent requires Python 3.11 or higher. The repository pins the version to 3.11.13 in the .python-version file. Verify your installation with:

python --version

LLM Backend Options

You must configure one of two LLM providers:

• Ollama (local inference): Requires a running Ollama server with a pulled model (e.g., gemma3:4b, gemma3:12b, or gemma3:1b)
• Google Gemini (cloud API): Requires a valid GEMINI_API_KEY

Step-by-Step Installation

Clone the Repository and Create a Virtual Environment

Start by cloning the repository and setting up an isolated Python environment:

git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv

Activate the virtual environment:

# macOS/Linux

source .venv/bin/activate

# Windows

.venv\Scripts\activate

Install Dependencies

With the environment activated, install the required packages:

pip install -r requirements.txt

Set Up Local LLM (Optional)

If using Ollama for local inference, pull your preferred model before running evaluations:

ollama pull gemma3:4b

Replace gemma3:4b with gemma3:12b or gemma3:1b depending on your hardware constraints.

Configuration

The Hiring Agent uses environment variables for provider selection and API authentication.

Environment Variables

Copy the example configuration file:

cp .env.example .env

Edit .env to set the following variables:

• LLM_PROVIDER: Set to ollama (default) or gemini
• DEFAULT_MODEL: Specify gemma3:4b for Ollama or gemini-2.5-pro for Gemini
• GEMINI_API_KEY: Required only when LLM_PROVIDER=gemini
• GITHUB_TOKEN: Optional, but recommended to avoid GitHub API rate limits

Provider-Specific Settings

For Ollama, ensure your local server is running at the default port (typically 11434) before executing the pipeline.

For Gemini, verify your API key has sufficient quota for multi-step résumé parsing and evaluation calls.

Running the Hiring Agent

The CLI entry point is score.py, which orchestrates the entire evaluation pipeline.

CLI Usage

Execute the agent by providing a path to a candidate's résumé PDF:

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

Understanding the Pipeline

When you run score.py, the agent executes the following flow as implemented in the source code:

1. PDF Extraction: pymupdf_rag.py converts PDF pages to Markdown-like text using PyMuPDF
2. Section Parsing: pdf.py processes the text with strict Jinja templates from prompts/templates/*.jinja to produce structured JSON-Resume data models defined in models.py
3. GitHub Enrichment: github.py retrieves candidate repositories and selects top projects for signal analysis
4. Fair Evaluation: evaluator.py applies fairness-aware scoring rules to the enriched profile
5. Output Generation: Results print to stdout; intermediate JSON caches to the cache/ directory

Development Mode Output

When DEVELOPMENT_MODE=True (set in config.py or via environment variable), the agent appends a CSV row to resume_evaluations.csv and preserves intermediate processing artifacts in the cache/ folder for debugging.

Key Source Files and Architecture

Understanding the codebase structure helps with customization and debugging:

• score.py: CLI driver and orchestration layer
• pdf.py: Handles PDF-to-Markdown conversion and LLM-powered section parsing
• pymupdf_rag.py: Low-level PDF text extraction using PyMuPDF
• models.py: Pydantic schemas and provider-agnostic LLM interfaces
• llm_utils.py: Provider initialization (Ollama/Gemini) and response cleaning utilities
• github.py: GitHub profile retrieval and repository prioritization logic
• evaluator.py: Fairness-aware scoring engine
• prompts/templates/: Jinja templates defining strict LLM prompts for each résumé section (experience, education, skills)
• config.py: Development-mode flags and global configuration

Summary

• The Interviewstreet Hiring Agent requires Python 3.11+ and either an Ollama server or Gemini API key
• Install by cloning the repository, creating a virtual environment, and running pip install -r requirements.txt
• Configure via the .env file using variables from .env.example, setting LLM_PROVIDER and model-specific options
• Execute evaluations with python score.py /path/to/resume.pdf, which chains together PDF extraction, LLM parsing, GitHub enrichment, and fair scoring
• Enable DEVELOPMENT_MODE=True to generate CSV exports in resume_evaluations.csv and cached intermediate JSON files

Frequently Asked Questions

What Python version is required for the Hiring Agent?

The codebase requires Python 3.11 or higher, with the repository specifically tested against Python 3.11.13 as specified in the .python-version file. Using older Python versions will likely cause dependency conflicts with the async LLM libraries and Pydantic validation used in models.py.

Can I run the Hiring Agent without an internet connection?

Partially. If you configure LLM_PROVIDER=ollama and use a locally running Ollama instance with a pulled model (e.g., gemma3:4b), the core résumé parsing and evaluation work offline. However, the GitHub enrichment feature in github.py requires internet access to fetch candidate repositories and contribution data.

Where are the evaluation results stored?

By default, results print to stdout as human-readable reports. When DEVELOPMENT_MODE=True (configured in config.py or via environment variable), the system appends structured data to resume_evaluations.csv in the project root and caches intermediate JSON processing artifacts in the cache/ directory for pipeline debugging.

How do I switch between Ollama and Google Gemini?

Change the LLM_PROVIDER environment variable in your .env file to either ollama or gemini, and update DEFAULT_MODEL accordingly (e.g., gemma3:4b for Ollama, gemini-2.5-pro for Gemini). When using Gemini, you must also provide a valid GEMINI_API_KEY. The provider initialization logic in llm_utils.py handles the underlying client configuration automatically based on these variables.

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