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

Clone the repository, install Python 3.11+ dependencies, configure your LLM provider (Ollama or Gemini), and run python score.py /path/to/resume.pdf to evaluate résumés locally.

The interviewstreet hiring-agent is a Python 3.11+ pipeline that extracts, parses, and evaluates résumés using LLM-powered analysis and fairness-aware scoring. This guide covers the complete interviewstreet hiring-agent setup process, from repository cloning to executing your first local candidate evaluation using the modular architecture defined in score.py, pdf.py, and evaluator.py.

Prerequisites

Before installing, ensure your environment meets these requirements:

• Python 3.11+ — The repository pins .python-version to 3.11.13, and all modules in models.py and evaluator.py require this version or newer.
• LLM Backend — Either a local Ollama server or a Google Gemini API key. The llm_utils.py module initializes providers based on your configuration.

Step-by-Step Installation

Clone and Install Dependencies

Run these commands to set up the project environment:

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

# .venv\Scripts\activate       # Windows

pip install -r requirements.txt

Configure a Local LLM with Ollama (Optional)

For fully local inference without API calls, install Ollama and pull a compatible model:

ollama pull gemma3:4b          # Also available: gemma3:12b, gemma3:1b

The llm_utils.py file handles provider initialization for both Ollama and Gemini backends.

Environment Configuration

Copy the example environment file and configure your variables:

cp .env.example .env

Edit .env to set these critical variables:

• LLM_PROVIDER — Set to ollama (default) or gemini
• DEFAULT_MODEL — Specify the model name, e.g., gemma3:4b for Ollama or gemini-2.5-pro for Gemini
• GEMINI_API_KEY — Required only when using Google Gemini
• GITHUB_TOKEN — Optional but recommended to improve GitHub API rate limits for the github.py enrichment module

Running the Hiring Agent Locally

The CLI entry point is score.py. Execute a résumé evaluation with:

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

This command orchestrates the full pipeline:

1. Extraction — pymupdf_rag.py converts PDF pages to Markdown-like text using PyMuPDF.
2. Parsing — pdf.py processes sections using strict Jinja templates from prompts/templates/ to generate a JSON-Resume data model defined in models.py.
3. Enrichment — github.py retrieves GitHub profile signals and selects top projects for candidate context.
4. Evaluation — evaluator.py applies fairness-aware scoring rules to generate the final assessment.
5. Output — Results print to stdout. When DEVELOPMENT_MODE=True (set in config.py), the agent appends a CSV row to resume_evaluations.csv and caches intermediate JSON in the cache/ directory.

Understanding the Pipeline Architecture

The hiring-agent consists of specialized modules that process résumés sequentially:

• score.py — CLI driver that orchestrates the entire evaluation flow.
• pymupdf_rag.py and pdf.py — Handle PDF-to-Markdown conversion and LLM-based section parsing.
• models.py — Defines Pydantic schemas and provider-agnostic LLM interfaces.
• github.py — Enriches candidate profiles with GitHub repository data.
• evaluator.py — Implements the fairness-aware scoring logic.
• prompts/templates/ — Contains Jinja templates that enforce strict output formats for each résumé section.

Complete Local Setup Example

This Python script demonstrates the full setup and execution programmatically:

import subprocess, os

# 1️⃣ Clone and set up environment

subprocess.run(["git", "clone", "https://github.com/interviewstreet/hiring-agent"])
os.chdir("hiring-agent")
subprocess.run(["python", "-m", "venv", ".venv"])
subprocess.run([".venv/bin/activate"], shell=True)   # Use .venv\Scripts\activate on Windows

subprocess.run(["pip", "install", "-r", "requirements.txt"])

# 2️⃣ Configure environment

os.environ["LLM_PROVIDER"] = "ollama"
os.environ["DEFAULT_MODEL"] = "gemma3:4b"

# 3️⃣ Execute evaluation

result = subprocess.run(
    ["python", "score.py", "sample_resume.pdf"],
    capture_output=True,
    text=True
)
print(result.stdout)

Replace sample_resume.pdf with an actual résumé file path to generate evaluations.

Summary

• The interviewstreet hiring-agent requires Python 3.11+ and either a local Ollama instance or Gemini API access.
• Install dependencies via pip install -r requirements.txt after cloning the repository.
• Configure the .env file with LLM_PROVIDER, DEFAULT_MODEL, and authentication tokens.
• Run python score.py <resume.pdf> to execute the extraction-parsing-enrichment-evaluation pipeline.
• Enable DEVELOPMENT_MODE=True in config.py to generate CSV reports (resume_evaluations.csv) and JSON caches in cache/.

Frequently Asked Questions

What Python version is required for interviewstreet hiring-agent?

Python 3.11 or newer is required. The repository specifically pins version 3.11.13 in the .python-version file, and dependencies in requirements.txt expect this version range.

Can I run the hiring agent without an internet connection?

Yes, if you configure LLM_PROVIDER=ollama and use a locally pulled model like gemma3:4b. However, the GitHub enrichment feature in github.py requires internet connectivity, and using Google Gemini necessitates an active API connection.

Where does the hiring agent store evaluation results?

By default, results output to stdout only. When DEVELOPMENT_MODE is set to True in config.py, the system appends evaluation records to resume_evaluations.csv and stores intermediate processing data as JSON in the cache/ directory.

How do I switch between Ollama and Gemini providers?

Modify the LLM_PROVIDER variable in your .env file to either ollama or gemini, update DEFAULT_MODEL to match your chosen backend (e.g., gemma3:4b or gemini-2.5-pro), and ensure GEMINI_API_KEY is set when using the Gemini provider. The llm_utils.py module automatically handles provider initialization based on these settings.

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