How to Install InterviewStreet Hiring-Agent: Complete Setup Guide

TLDR: Clone the repository, set up a Python 3.11+ virtual environment, install dependencies via pip install -r requirements.txt, configure your .env file with LLM_PROVIDER and DEFAULT_MODEL, and execute python score.py /path/to/resume.pdf to evaluate resumes using either local Ollama models or Google Gemini.

The InterviewStreet Hiring-Agent is a Python-based pipeline that parses resume PDFs, enriches them with GitHub signals, and produces fair, explainable evaluations. Installing this tool from the interviewstreet/hiring-agent repository involves setting up the environment, installing core dependencies, and configuring one of two supported LLM backends to power the extraction and scoring modules.

Prerequisites

Before installing the InterviewStreet Hiring-Agent, ensure your system meets the following requirements:

• Python 3.11+ — The repository pins .python-version to 3.11.13, and all dependencies in requirements.txt are compatible with Python 3.11 and above.
• Git — Required to clone the repository from GitHub.
• LLM Backend — Either Ollama for local model serving or a Google Gemini API key for cloud-based inference.

Installation Steps

Clone the Repository

First, clone the hiring-agent repository and navigate into the project directory:

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

Create a Virtual Environment

Create and activate a Python virtual environment to isolate dependencies:

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

# .venv\Scripts\activate   # Windows

Install Python Dependencies

Install all required packages specified in requirements.txt:

pip install -r requirements.txt

This installs the core libraries needed by modules including pymupdf_rag.py, pdf.py, github.py, and evaluator.py.

Configure Environment Variables

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

cp .env.example .env

Edit .env to set your preferred LLM provider and model:

• LLM_PROVIDER — Set to ollama for local inference or gemini for Google Gemini.
• DEFAULT_MODEL — Specify the model name (e.g., gemma3:4b for Ollama or a Gemini model identifier).
• GEMINI_API_KEY — Required only if using the Gemini provider.
• GITHUB_TOKEN — Optional, but recommended to improve API rate limits when fetching GitHub data.

Set Up the LLM Backend

For Ollama (Local): Pull your desired model before running evaluations:

ollama pull gemma3:4b    # lightweight option

# or

ollama pull gemma3:12b   # larger model

Ensure the Ollama server is running (ollama serve) before executing the pipeline.

For Google Gemini (Cloud): No additional local setup is required beyond setting the GEMINI_API_KEY in your .env file.

Running the Pipeline

Once installation is complete, run a resume through the scoring pipeline using the entry point in score.py:

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

The score.py orchestrator will:

• Convert the PDF to Markdown-like text using pymupdf_rag.py and cache it in cache/resumecache_*.json.
• Extract structured sections via pdf.py using Jinja templates from prompts/templates/.
• Detect and enrich GitHub profiles using github.py, caching results in cache/githubcache_*.json.
• Run fairness-aware evaluation through evaluator.py.
• Print a readable summary and, when DEVELOPMENT_MODE=True (set in config.py), append results to resume_evaluations.csv.

Core Architecture and Key Files

Understanding the main components helps troubleshoot installation issues:

File	Purpose
score.py	Main entry point that wires extraction, enrichment, evaluation, and reporting.
pdf.py	Handles PDF-to-Markdown conversion and section-wise LLM calls.
github.py	Fetches GitHub profiles and classifies repositories.
evaluator.py	Implements strict-scored evaluation with fairness constraints.
models.py	Defines Pydantic schemas and LLM provider abstractions (OllamaProvider, GeminiProvider).
llm_utils.py	Manages provider initialization and request handling.
config.py	Contains the DEVELOPMENT_MODE flag controlling caching behavior.
requirements.txt	Lists all Python dependencies for installation.
.env.example	Template for environment configuration.

Summary

To successfully install the InterviewStreet Hiring-Agent:

• Use Python 3.11+ and create a virtual environment before installing dependencies.
• Install via pip install -r requirements.txt to get all required libraries.
• Configure .env with LLM_PROVIDER and DEFAULT_MODEL to select between Ollama and Google Gemini.
• Run python score.py <resume.pdf> to execute the full pipeline from PDF parsing to fair evaluation.

Frequently Asked Questions

What Python version is required for InterviewStreet Hiring-Agent?

The repository requires Python 3.11 or higher, with the codebase specifically pinned to version 3.11.13 in .python-version. All dependencies in requirements.txt are tested against Python 3.11+.

Can I run InterviewStreet Hiring-Agent without an internet connection?

Yes, but only with Ollama. If you set LLM_PROVIDER=ollama in your .env file and run a local model like gemma3:4b, the pipeline operates entirely offline (except for optional GitHub profile enrichment, which requires internet access). Using LLM_PROVIDER=gemini requires an active internet connection and API key.

Where does the pipeline store cached data?

The Hiring-Agent stores intermediate results in a cache/ directory: resumecache_*.json for PDF text extraction and githubcache_*.json for GitHub API responses. When DEVELOPMENT_MODE=True in config.py, final evaluations are also appended to resume_evaluations.csv in the project root.

How do I switch between Ollama and Google Gemini after installation?

Edit the .env file and change LLM_PROVIDER to either ollama or gemini, then update DEFAULT_MODEL to match your chosen backend (e.g., gemma3:4b for Ollama or a Gemini model name). If switching to Gemini, ensure GEMINI_API_KEY is set. No reinstallation of Python dependencies is required to switch providers.

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