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

> Build the InterviewStreet Hiring-Agent from source. Follow this guide to clone the repo, install dependencies, configure your environment, and run Python score.py for resume evaluation.

- Repository: [HackerRank/hiring-agent](https://github.com/interviewstreet/hiring-agent)
- Tags: how-to-guide
- Published: 2026-07-18

---

**Clone the repository, install Python 3.11+ dependencies from [`requirements.txt`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/config.py), while the orchestration entry point is [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py).

## Prerequisites and Repository Setup

### Clone the Repository

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

```bash
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

```bash
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

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

```

The [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) | Converts PDF pages to Markdown-like text using `PDFRag` class |
| **Section Parsing** | [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) | Uses `PDFHandler` with Jinja templates (`prompts/templates/*.jinja`) to generate JSON Resume objects via LLM |
| **GitHub Enrichment** | [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) | `GitHubClient` fetches candidate profiles, classifies repositories, and selects top 7 relevant projects |
| **Scoring** | [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) | `Evaluator` applies fairness-constrained rules and generates explanations |
| **Orchestration** | [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) module manages template loading and LLM interaction, ensuring consistent JSON output schemas.

### Fetch GitHub Repositories

Retrieve and analyze candidate GitHub data manually:

```python
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`](https://github.com/interviewstreet/hiring-agent/blob/main/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:

```python
from evaluator import Evaluator

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

```

The [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py), [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py), [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py), or [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) implements `OllamaProvider` and `GeminiProvider`, the architecture uses an abstract provider pattern. You can extend the base class in [`models.py`](https://github.com/interviewstreet/hiring-agent/blob/main/models.py) to add OpenAI, Anthropic, or other providers, then update [`config.py`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/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`](https://github.com/interviewstreet/hiring-agent/blob/main/pymupdf_rag.py) for text extraction, `PDFHandler` from [`pdf.py`](https://github.com/interviewstreet/hiring-agent/blob/main/pdf.py) for LLM parsing, `GitHubClient` from [`github.py`](https://github.com/interviewstreet/hiring-agent/blob/main/github.py) for repository analysis, or `Evaluator` from [`evaluator.py`](https://github.com/interviewstreet/hiring-agent/blob/main/evaluator.py) for scoring. Each class initializes independently without requiring the full [`score.py`](https://github.com/interviewstreet/hiring-agent/blob/main/score.py) orchestration.