How to Install and Run Interviewstreet Hiring Agent Locally

Clone the repository, install Python 3.11+ dependencies from requirements.txt, configure your .env file for Ollama or Gemini, and execute python score.py /path/to/resume.pdf to process résumés.

The Interviewstreet Hiring Agent is an open-source Python pipeline that automates résumé evaluation using LLMs and fairness-aware scoring rules. This guide explains the complete local installation and execution workflow based on the interviewstreet/hiring-agent source code, covering both local Ollama inference and Google Gemini cloud setups.

Prerequisites

Python Environment

You need Python 3.11 or higher to run the Hiring Agent. The repository pins the version to 3.11.13 in the .python-version file, ensuring compatibility with the Pydantic schemas and async features used throughout the codebase.

LLM Backend

Choose one of two inference options:

• Ollama – Run models locally (recommended for privacy).
• Google Gemini – Use the cloud API (requires an API key).

Installation and Setup

Clone and Install Dependencies

Run the following 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 Ollama for Local Inference

If you selected Ollama, pull a compatible model before running evaluations:

ollama pull gemma3:4b

Alternative models include gemma3:12b and gemma3:1b, depending on your hardware constraints.

Environment Variables

Copy the example configuration and edit the required variables:

cp .env.example .env

Edit .env to set:

• LLM_PROVIDER – ollama (default) or gemini
• DEFAULT_MODEL – e.g., gemma3:4b or gemini-2.5-pro
• GEMINI_API_KEY – Required only when LLM_PROVIDER=gemini
• GITHUB_TOKEN – Optional, but increases GitHub API rate limits for profile enrichment

Running the Hiring Agent

Execute the CLI

The entry point is score.py. Pass a path to a résumé PDF to start the evaluation:

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

Pipeline Execution Flow

When you run the command, score.py orchestrates the following sequence:

1. Extraction – pymupdf_rag.py converts PDF pages to Markdown-like text using PyMuPDF.
2. Parsing – pdf.py invokes LLM calls with strict Jinja templates from prompts/templates/ to populate the JSON-Resume model defined in models.py.
3. Enrichment – github.py fetches candidate repositories and selects top projects.
4. Evaluation – evaluator.py applies fairness-aware scoring rules to generate the final assessment.
5. Output – Results print to stdout. When DEVELOPMENT_MODE=True in config.py, the system appends a CSV row to resume_evaluations.csv and caches intermediate JSON in cache/.

Programmatic Example

Automate the setup and execution in Python:

import subprocess
import os

# Clone and install

subprocess.run(["git", "clone", "https://github.com/interviewstreet/hiring-agent"])
os.chdir("hiring-agent")
subprocess.run(["python", "-m", "venv", ".venv"])

# Activate and install dependencies (Linux/Mac example)

subprocess.run(["bash", "-c", "source .venv/bin/activate && pip install -r requirements.txt"])

# Configure environment

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

# Run evaluation

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

Replace sample_resume.pdf with your actual file path.

Summary

• Python 3.11+ is required to run the Hiring Agent locally.
• Install dependencies via pip install -r requirements.txt after cloning the repository.
• Configure .env to choose between Ollama (local) or Gemini (cloud) inference providers.
• Execute python score.py <pdf_path> to trigger the full pipeline from extraction to fairness-aware scoring.
• Enable DEVELOPMENT_MODE in config.py to persist results to CSV and cache intermediate JSON files.

Frequently Asked Questions

What Python version is required for Interviewstreet Hiring Agent?

The codebase requires Python 3.11 or higher, with the repository specifically pinning version 3.11.13 in the .python-version file to ensure compatibility with the Pydantic models and async patterns used in modules like models.py and llm_utils.py.

Can I run the Hiring Agent without an internet connection?

Yes, if you use Ollama as your LLM_PROVIDER with a locally cached model such as gemma3:4b. However, the github.py enrichment step requires internet access to fetch candidate repositories, and Gemini mode obviously requires an API connection.

Where are the evaluation results saved?

By default, results print to stdout only. When DEVELOPMENT_MODE is set to True in config.py, the pipeline additionally appends a CSV row to resume_evaluations.csv and stores intermediate JSON artifacts in the cache/ directory for debugging.

Which source file orchestrates the entire pipeline?

The score.py file serves as the CLI driver and orchestrator. It coordinates pymupdf_rag.py for text extraction, pdf.py for section parsing, github.py for profile enrichment, and evaluator.py for final scoring.

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