How to Install the Hiring-Agent: Complete Setup Guide for the InterviewStreet Pipeline

You can install the hiring-agent by cloning the repository, creating a Python 3.11+ virtual environment, installing dependencies from requirements.txt, setting up an LLM backend (Ollama or Google Gemini), and configuring environment variables in .env.

The hiring-agent repository from InterviewStreet is a Python 3.11+ project that transforms résumé PDFs into structured JSON-Resume format, enriches them with GitHub signals, and generates fair, explainable candidate scores. To install the hiring-agent locally, you need to configure a Python environment, install runtime dependencies, and connect either a local Ollama instance or the Google Gemini API for LLM processing.

Prerequisites

Before you install the hiring-agent, ensure you have:

• Python 3.11 or higher installed on your system
• Git for cloning the repository
• An LLM backend:
  • Ollama (recommended for local deployment) – download from ollama.com
  • Google Gemini – requires an API key from Google AI Studio

Step-by-Step Installation Guide

1. Clone the Repository and Create a Virtual Environment

Start by cloning the source code and creating an isolated Python environment to avoid conflicts with system packages.

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

Activate the virtual environment:

• Linux/macOS: source .venv/bin/activate
• Windows: .venv\Scripts\activate

2. Install Python Dependencies

With the environment activated, install all required packages specified in requirements.txt:

pip install -r requirements.txt

This installs runtime dependencies including PyMuPDF (for PDF processing), Pydantic (for data validation), and Jinja2 (for LLM prompt templating).

3. Set Up the LLM Backend

Choose and configure one of the supported LLM providers:

Option A: Local Ollama Setup

Install Ollama from the official website, then start the server and pull a compatible model:

ollama serve &
ollama pull gemma3:4b

The repository documentation recommends gemma3:4b or similar models for parsing résumés and evaluating candidates.

Option B: Google Gemini Setup

If using Google Gemini instead of Ollama, obtain an API key from Google AI Studio. You will configure this key in the next step.

4. Configure Environment Variables

Copy the example environment file and customize it for your setup:

cp .env.example .env

Edit .env to set the required variables:

• LLM_PROVIDER=ollama (or gemini)
• DEFAULT_MODEL=gemma3:4b (or the specific Gemini model name)
• GEMINI_API_KEY=your-key (required only if using Gemini)

Additional configuration flags like DEVELOPMENT_MODE can be set in config.py or via environment variables to control whether the pipeline appends results to a CSV file.

Verify the Installation

Test your installation by running the end-to-end scoring pipeline on a sample résumé:

python score.py path/to/example_resume.pdf

When executed, score.py orchestrates the full pipeline:

1. Converts the PDF to markdown using pymupdf_rag.py
2. Calls the LLM per section using Jinja templates defined in pdf.py
3. Enriches the data with GitHub signals via github.py
4. Applies fairness-aware scoring rules in evaluator.py
5. Prints a human-readable report and optionally writes a CSV entry if DEVELOPMENT_MODE=True

Key Source Files in the Pipeline

Understanding these core files helps troubleshoot installation issues:

• requirements.txt – Lists all Python dependencies (PyMuPDF, Pydantic, etc.)
• score.py – Main entry point that wires together the entire pipeline
• pdf.py – Handles PDF-to-markdown conversion and LLM section calls
• github.py – Fetches and processes GitHub profile and repository data
• evaluator.py – Implements fairness-aware scoring using LLM templates
• prompts/templates/ – Contains Jinja templates for extraction and scoring prompts
• config.py – Houses global configuration flags including DEVELOPMENT_MODE

Summary

• Clone the repository from https://github.com/interviewstreet/hiring-agent and create a Python 3.11+ virtual environment.
• Install dependencies using pip install -r requirements.txt to get PyMuPDF, Pydantic, and Jinja2.
• Configure an LLM backend by either running ollama serve with a local model like gemma3:4b or setting up a Google Gemini API key.
• Set environment variables in .env to specify LLM_PROVIDER, DEFAULT_MODEL, and optional GEMINI_API_KEY.
• Validate the installation by running python score.py against a sample PDF to ensure the pipeline executes correctly.

Frequently Asked Questions

What version of Python is required to install the hiring-agent?

The hiring-agent requires Python 3.11 or higher. This version requirement ensures compatibility with the type hints and async features used in pdf.py, github.py, and evaluator.py.

Can I use a different LLM model with Ollama?

Yes. While the documentation recommends gemma3:4b, you can substitute any Ollama-compatible model by changing the DEFAULT_MODEL variable in your .env file. Ensure the model supports JSON output for reliable parsing of résumé sections.

Where do I configure the DEVELOPMENT_MODE setting?

The DEVELOPMENT_MODE flag is defined in config.py but can be overridden via environment variables. When set to True, the score.py script appends scoring results to a CSV file in addition to printing the report.

Why does the installation require both PyMuPDF and an LLM backend?

PyMuPDF (imported in pymupdf_rag.py) handles the initial PDF-to-markdown conversion, while the LLM backend (configured via LLM_PROVIDER) performs the semantic extraction of structured data, GitHub signal enrichment, and fairness-aware evaluation. The pipeline relies on both components to transform raw PDFs into scored candidate profiles.

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