How to Set Up a Development Environment for Hiring‑Agent: A Complete Guide

To set up a development environment for Hiring‑Agent, clone the repository, create a Python 3.11+ virtual environment, install dependencies from requirements.txt, configure your .env file for either local Ollama or cloud Gemini inference, and run python score.py on a résumé PDF.

Hiring‑Agent is an open‑source Python pipeline from the interviewstreet/hiring-agent repository that extracts structured data from résumé PDFs, enriches it with GitHub signals, and generates fair, explainable evaluations using large language models (LLMs). The codebase is designed to run entirely offline with local models or connect to cloud APIs, making it flexible for different development workflows.

Prerequisites and System Requirements

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

• Python 3.11 or higher – The codebase uses modern Python features and type hinting.
• Git – For cloning the repository.
• Ollama (optional) – Required only if you plan to run models locally rather than using Google Gemini.

The repository supports both local inference via Ollama and remote inference via the Gemini API, selectable through environment configuration.

Step‑by‑Step Installation

Follow these seven steps to configure your local development environment:

# 1️⃣ Clone the repository

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

# 2️⃣ Create and activate a Python 3.11+ virtual environment

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

# .venv\Scripts\activate    # Windows

# 3️⃣ Install Python dependencies

pip install -r requirements.txt

# 4️⃣ Set up environment variables

cp .env.example .env

# Edit .env to configure your LLM provider and model

# 5️⃣ (Optional) Install and start Ollama for local inference

ollama serve                # Starts the Ollama daemon

# 6️⃣ Pull your desired local model

ollama pull gemma3:4b

# 7️⃣ Run the scoring pipeline on a résumé PDF

python score.py path/to/resume.pdf

The requirements.txt file pins critical dependencies including PyMuPDF for PDF processing, ollama for local LLM communication, and pydantic for data validation.

Configuring LLM Providers

Hiring‑Agent abstracts LLM access through the models.py module, which provides provider‑agnostic wrappers for Ollama and Google Gemini.

Local Development with Ollama

For offline development or cost‑free experimentation, configure your .env file:

LLM_PROVIDER=ollama
DEFAULT_MODEL=gemma3:4b

Ensure the Ollama daemon is running (ollama serve) and the specified model is downloaded. The wrapper in models.py translates requests to ollama.chat calls.

Cloud Development with Gemini

For production‑grade inference without local GPU resources, use Google Gemini:

LLM_PROVIDER=gemini
GEMINI_API_KEY=your_api_key_here
DEFAULT_MODEL=gemini-1.5-pro

The models.py implementation routes these requests through google.generativeai when LLM_PROVIDER is set to gemini.

Understanding the Architecture

The repository consists of specialized modules that form a cohesive data pipeline:

Component	Source Files	Purpose
PDF Extraction	pymupdf_rag.py, pdf.py	Converts PDF pages to Markdown‑like text using PyMuPDF and calls the LLM per section.
LLM Orchestration	models.py, llm_utils.py, prompt.py	Loads Jinja templates from the prompts/ directory and manages provider‑specific API calls.
GitHub Enrichment	github.py	Detects GitHub URLs in résumés, fetches profile and repository data, and uses the LLM to identify top contributions.
Evaluation Engine	evaluator.py	Applies fairness‑aware scoring rules (open‑source contributions, production experience, technical skills) and calculates bonus/deduction totals.
CLI Entry Point	score.py	Orchestrates the full pipeline, handles caching, and outputs human‑readable summaries.
Configuration	config.py, .env.example	Global settings including DEVELOPMENT_MODE and LLM provider selection.

The score.py script serves as the primary interface, importing logic from pdf.py for text extraction, github.py for enrichment, and evaluator.py for final scoring.

Development Mode and Caching

Enable DEVELOPMENT_MODE in your .env or config.py to accelerate iterative development:

# In config.py or .env

DEVELOPMENT_MODE=True

When enabled, the pipeline caches intermediate JSON results in the cache/ directory. Specifically:

• score.py checks for cached JSON under cache/ before re‑processing a PDF.
• github.py stores fetched profile data as cache/githubcache_<basename>.json.

This caching mechanism prevents redundant LLM calls and GitHub API requests during debugging and feature development. Additionally, DEVELOPMENT_MODE activates CSV export functionality for batch processing results.

Summary

• Clone the interviewstreet/hiring-agent repository and create a Python 3.11+ virtual environment.
• Install dependencies via pip install -r requirements.txt.
• Configure your .env file to select between Ollama (local) or Gemini (cloud) providers using the LLM_PROVIDER variable.
• Execute the pipeline with python score.py <pdf_path> after optionally starting the Ollama daemon.
• Enable DEVELOPMENT_MODE in config.py to cache intermediate JSON results and enable CSV exports for rapid iteration.
• Extend functionality by modifying specialized modules like github.py, evaluator.py, or the Jinja templates in prompts/.

Frequently Asked Questions

What Python version is required for Hiring‑Agent?

Hiring‑Agent requires Python 3.11 or higher. The codebase leverages modern type hinting and syntax features introduced in recent Python versions, and the requirements.txt is tested against Python 3.11+ environments.

Can I run Hiring‑Agent without an internet connection?

Yes, by setting LLM_PROVIDER=ollama in your .env file and running a local model like gemma3:4b. You will need internet connectivity only for the initial Ollama installation and model download; subsequent inferences run entirely offline. However, GitHub enrichment features in github.py require internet access to fetch repository data unless cached results already exist.

Where does Hiring‑Agent cache intermediate results?

The pipeline stores cached data in a cache/ directory at the repository root. score.py caches processed résumé JSON, while github.py stores GitHub profile data as cache/githubcache_<basename>.json. These caches are only utilized when DEVELOPMENT_MODE is set to True in config.py.

How do I switch between Ollama and Gemini providers?

Modify the LLM_PROVIDER environment variable in your .env file. Set it to ollama for local inference (requires the Ollama daemon running) or gemini for cloud inference (requires GEMINI_API_KEY). The abstraction layer in models.py handles the translation to provider‑specific SDK calls automatically.

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