How to Build InterviewStreet Hiring-Agent from Source: Complete Setup Guide

Clone the repository, install Python 3.11+ dependencies from requirements.txt, configure your .env file with an LLM provider (Ollama or Gemini), and run python score.py resume.pdf to execute the full resume evaluation pipeline.

The InterviewStreet Hiring-Agent is an open-source Python pipeline that transforms resume PDFs into structured, bias-aware evaluations using LLM parsing and GitHub enrichment. This guide walks you through building the interviewstreet/hiring-agent project from source, from initial setup to running your first evaluation. All configuration logic resides in config.py, while the orchestration entry point is score.py.

Prerequisites and Repository Setup

Clone the Repository

Start by cloning the official repository and navigating into the project directory:

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

The repository contains the complete source code, Jinja templates for LLM prompts, and example environment configuration.

Set Up Python 3.11+ Environment

The project requires Python 3.11 or newer (specified in .python-version). Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS

# .venv\Scripts\activate   # Windows

Using a virtual environment prevents conflicts with system packages and ensures reproducible builds.

Install Dependencies

Install all required packages using the provided requirements file:

pip install -r requirements.txt

Key dependencies include pymupdf for PDF processing, pydantic for data validation, and jinja2 for template rendering.

Configure the Environment

Environment Variables

Copy the example configuration file and edit it with your specific settings:

cp .env.example .env

Configure the following variables in .env:

• LLM_PROVIDER: Set to ollama for local inference or gemini for Google Cloud
• DEFAULT_MODEL: Model identifier (e.g., gemma3:4b for Ollama, gemini-2.5-pro for Gemini)
• GEMINI_API_KEY: Required only when using Gemini provider
• GITHUB_TOKEN: Optional GitHub personal access token to increase API rate limits

The config.py module handles all environment variable loading and validation, exposing these settings to the rest of the application.

Choose an LLM Backend

Ollama (Local): Install Ollama, start the server with ollama serve, and pull your chosen model:

ollama pull gemma3:4b

Google Gemini (Cloud): Obtain an API key from Google AI Studio and set it in GEMINI_API_KEY. No local GPU resources required.

Provider implementations are located in models.py, which defines OllamaProvider and GeminiProvider classes with unified interfaces for text generation.

Run the Evaluation Pipeline

Execute the end-to-end scoring workflow with a single command:

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

The score.py script orchestrates the entire pipeline: PDF extraction, section parsing, GitHub enrichment, and fairness-aware scoring. When DEVELOPMENT_MODE=True (the default in config.py), intermediate JSON results cache to the cache/ directory and evaluation data appends to resume_evaluations.csv.

Understanding the Architecture

The pipeline consists of discrete stages you can inspect or extend individually:

Stage	Module	Function
PDF Extraction	pymupdf_rag.py	Converts PDF pages to Markdown-like text using PDFRag class
Section Parsing	pdf.py	Uses PDFHandler with Jinja templates (prompts/templates/*.jinja) to generate JSON Resume objects via LLM
GitHub Enrichment	github.py	GitHubClient fetches candidate profiles, classifies repositories, and selects top 7 relevant projects
Scoring	evaluator.py	Evaluator applies fairness-constrained rules and generates explanations
Orchestration	score.py	Links all components and handles caching/CSV export

Each module operates independently, allowing you to substitute components (such as using a different PDF parser or custom scoring rules) without modifying the core pipeline.

Practical Code Examples

Extract PDF Text Standalone

Use the PDFRag class directly for PDF-to-Markdown conversion:

from pymupdf_rag import PDFRag

rag = PDFRag()
markdown = rag.to_markdown("resume.pdf")
print(markdown[:500])  # Preview first 500 characters

This utility lives in pymupdf_rag.py and handles complex layout preservation during text extraction.

Parse Specific Resume Sections

Call the LLM directly for individual resume sections using PDFHandler:

from pdf import PDFHandler
from prompts.template_manager import TemplateManager

handler = PDFHandler()
section_json = handler.extract_section(
    markdown_text,
    template_name="basics.jinja",
)
print(section_json)

The pdf.py module manages template loading and LLM interaction, ensuring consistent JSON output schemas.

Fetch GitHub Repositories

Retrieve and analyze candidate GitHub data manually:

from github import GitHubClient

client = GitHubClient(username="octocat")
repos = client.fetch_user_repos()
print([r["name"] for r in repos][:5])

Implemented in github.py, this client handles pagination, repository classification, and intelligent project selection based on relevance heuristics.

Run the Evaluator Manually

Execute scoring logic independently for testing or customization:

from evaluator import Evaluator

evaluator = Evaluator()
scores = evaluator.evaluate(resume_json, enriched_github_data)
print(scores)

The evaluator.py module contains the fairness-aware scoring algorithms and explanation generation logic.

Summary

• Clone the interviewstreet/hiring-agent repository and create a Python 3.11+ virtual environment
• Install dependencies via pip install -r requirements.txt
• Configure the .env file with your chosen LLM provider (ollama or gemini) and model settings
• Run the full pipeline using python score.py path/to/resume.pdf
• Extend individual components by importing classes from pymupdf_rag.py, pdf.py, github.py, or evaluator.py

Frequently Asked Questions

What Python version is required for InterviewStreet Hiring-Agent?

The project requires Python 3.11 or newer, as specified in the .python-version file at the repository root. This version ensures compatibility with the Pydantic v2 models defined in models.py and modern async syntax used throughout the codebase.

Can I use a different LLM provider than Ollama or Gemini?

While the default models.py implements OllamaProvider and GeminiProvider, the architecture uses an abstract provider pattern. You can extend the base class in models.py to add OpenAI, Anthropic, or other providers, then update config.py to recognize your new LLM_PROVIDER environment variable value.

Where does the pipeline store intermediate results?

When DEVELOPMENT_MODE=True in config.py, the pipeline caches intermediate JSON representations in the cache/ directory and appends evaluation records to resume_evaluations.csv in the project root. Disable development mode in production to prevent disk I/O overhead and logging of candidate data.

How do I run individual components without the full pipeline?

Import the specific module classes directly: use PDFRag from pymupdf_rag.py for text extraction, PDFHandler from pdf.py for LLM parsing, GitHubClient from github.py for repository analysis, or Evaluator from evaluator.py for scoring. Each class initializes independently without requiring the full score.py orchestration.

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