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

You can set up the Hiring Agent locally by cloning the interviewstreet/hiring-agent repository, installing dependencies from requirements.txt, configuring environment variables in .env, and running python score.py path/to/resume.pdf to generate AI-powered resume evaluations.

The Hiring Agent is an open-source Python pipeline developed by Interview Street that converts resume PDFs into structured, explainable evaluations using large language models. Setting up the hiring-agent locally enables you to process candidate resumes through a five-stage pipeline—PDF extraction, section parsing, GitHub enrichment, fairness-aware scoring, and structured output—without requiring external API dependencies if using a local LLM.

Prerequisites

Before installing the Hiring Agent, ensure you have the following tools installed on your machine:

• Python 3.x and pip for dependency management
• Git for cloning the repository
• Ollama (optional) if you plan to run local LLM inference instead of using Google's Gemini API

Step-by-Step Installation

Follow these steps to install and configure the hiring-agent locally.

Clone the Repository

First, clone the repository from GitHub and navigate into the project directory:

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

Create a Virtual Environment

Create an isolated Python environment to avoid dependency conflicts:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install Dependencies

Install the required Python packages specified in requirements.txt:

pip install -r requirements.txt

Configure Environment Variables and LLM Providers

The Hiring Agent uses environment variables defined in a .env file to select LLM providers and authentication tokens. Copy the example configuration file and customize it for your setup:

cp .env.example .env

Edit .env to set the following variables:

• LLM_PROVIDER: Set to ollama for local inference or gemini for Google Gemini
• DEFAULT_MODEL: The model name (e.g., gemma3:4b for Ollama or gemini-1.5-flash for Gemini)
• GEMINI_API_KEY: Your Google AI API key (required only for Gemini)
• GITHUB_TOKEN: Personal access token for GitHub API rate limits (optional but recommended)

Local Ollama Setup

To use a local LLM without external API calls, install Ollama and pull your preferred model. According to the source code in models.py, the system supports the OllamaProvider class for local inference:

ollama pull gemma3:4b

When LLM_PROVIDER=ollama, the pipeline instantiates OllamaProvider via utility functions in llm_utils.py, which normalizes LLM responses for downstream processing.

Google Gemini Configuration

For cloud-based inference, set LLM_PROVIDER=gemini and provide a valid GEMINI_API_KEY. The GeminiProvider class in models.py handles API communication, offering an alternative to local Ollama deployment when you need hosted model capabilities.

Understanding the Pipeline Architecture

The hiring-agent processes resumes through five distinct stages, each implemented in specific source files:

1. PDF Extraction: pymupdf_rag.py uses PyMuPDF to read PDF files and convert them to Markdown-like text.
2. Section Parsing: pdf.py sends resume sections (Basics, Work, Education, etc.) to the LLM using Jinja templates stored in prompts/templates/. The LLM returns structured JSON-Resume formats defined in models.py.
3. GitHub Enrichment: github.py extracts GitHub usernames from the resume, retrieves profile and repository data, classifies projects, and prompts the LLM to select the top 7 repositories for scoring.
4. Evaluation: evaluator.py applies a strict, fairness-aware scoring rubric—evaluating open-source contributions, self-projects, production code, and technical skills—using additional Jinja templates for structured assessment.
5. Output Generation: score.py serves as the CLI entry point that orchestrates the entire pipeline. When DEVELOPMENT_MODE=True (the default setting in config.py), the pipeline caches intermediate JSON files under cache/ and appends results to resume_evaluations.csv.

The models.py file defines Pydantic schemas for data validation and provides the abstraction layer for both OllamaProvider and GeminiProvider, while llm_utils.py contains shared utilities for instantiating the selected provider and normalizing responses.

Run Your First Resume Evaluation

Execute the end-to-end pipeline by passing a resume PDF to score.py:

python score.py path/to/resume.pdf

The command generates a human-readable evaluation summary in the terminal. With DEVELOPMENT_MODE enabled (as configured in config.py), the system also writes intermediate processing files to the cache/ directory and records the final scores in resume_evaluations.csv for batch analysis.

Summary

• Clone the interviewstreet/hiring-agent repository and install dependencies via pip install -r requirements.txt.
• Configure the .env file with LLM_PROVIDER, DEFAULT_MODEL, and optional API keys for your chosen backend.
• Select between local inference using OllamaProvider (Ollama) or cloud inference using GeminiProvider (Google Gemini) as defined in models.py.
• Execute python score.py path/to/resume.pdf to run the pipeline, which extracts text via pymupdf_rag.py, parses sections via pdf.py, enriches GitHub data via github.py, and evaluates via evaluator.py.
• Access cached intermediate results in cache/ and CSV output in resume_evaluations.csv when running in development mode.

Frequently Asked Questions

Do I need an internet connection to run the Hiring Agent locally?

No, if you configure LLM_PROVIDER=ollama in your .env file and use a locally downloaded model (e.g., gemma3:4b), the pipeline runs entirely offline. However, the optional GitHub enrichment stage in github.py requires internet connectivity to fetch profile and repository data, and the Gemini provider requires an active connection to Google's API.

What file serves as the main entry point for the CLI?

score.py functions as the primary orchestrator and CLI entry point. It coordinates the five-stage pipeline—invoking pymupdf_rag.py for extraction, pdf.py for parsing, github.py for enrichment, and evaluator.py for scoring—before printing the final human-readable summary.

Where does the pipeline store intermediate processing data?

When DEVELOPMENT_MODE is set to True in config.py, the system caches intermediate JSON files under the cache/ directory and appends evaluation results to resume_evaluations.csv. This allows for debugging and batch analysis of candidate evaluations without re-running the LLM-intensive stages.

How do I switch between different LLM providers?

Modify the LLM_PROVIDER environment variable in your .env file to either ollama or gemini. The llm_utils.py module instantiates the appropriate provider class (OllamaProvider or GeminiProvider) from models.py based on this setting, automatically handling the different API interfaces and response formats.

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