How to Run the Hiring Agent Locally on Your Machine

Clone the interviewstreet/hiring-agent repository, install dependencies from requirements.txt, configure your .env file with LLM_PROVIDER and API keys, and execute python score.py path/to/resume.pdf to generate a scored evaluation with cached intermediate results.

The Hiring Agent is an open-source Python pipeline that transforms resume PDFs into structured, explainable evaluations using local or hosted LLMs. According to the interviewstreet/hiring-agent source code, the system extracts text, parses sections with Jinja templates, enriches data via GitHub APIs, and applies a fairness-aware scoring rubric. Running the Hiring Agent locally lets you evaluate candidates without sending sensitive data to external services, provided you have a compatible LLM backend such as Ollama.

Prerequisites and Local Setup

Clone the Repository and Create a Virtual Environment

Start by cloning the repository and setting up an isolated Python environment to avoid dependency conflicts with other projects.

Install Python Dependencies

Install the required packages listed in requirements.txt to ensure all PDF processing, LLM client, and data validation libraries are available.

git clone https://github.com/interviewstreet/hiring-agent
cd hiring-agent
python -m venv .venv
source .venv/bin/activate  # Use .venv\Scripts\activate on Windows

pip install -r requirements.txt

Configure the LLM Provider

The Hiring Agent supports multiple LLM backends through a common abstraction layer defined in models.py. Configuration is handled via environment variables stored in a .env file at the project root.

Using Ollama for Local Inference

For fully local execution without external API calls, install Ollama and pull a compatible model such as gemma3:4b. Set LLM_PROVIDER=ollama in your .env file to route all inference through your local instance.

Using Gemini for Cloud Inference

To use Google's Gemini API, obtain an API key and set LLM_PROVIDER=gemini along with GEMINI_API_KEY in your .env file. You may also set DEFAULT_MODEL to specify which Gemini model variant to use.

# Copy the example configuration

cp .env.example .env

# Edit .env to set your preferred provider and credentials

# LLM_PROVIDER=ollama

# DEFAULT_MODEL=gemma3:4b

# GITHUB_TOKEN=your_github_token_here

Running the End-to-End Pipeline

Once configured, execute the main entry point score.py with a path to a resume PDF. The pipeline orchestrates five distinct stages that transform raw PDF data into a structured evaluation:

1. PDF extraction – pymupdf_rag.py reads the PDF using PyMuPDF and converts it to Markdown-like text.
2. Section parsing – pdf.py sends parsed sections (Basics, Work, Education) to the LLM using Jinja templates from prompts/templates/, returning JSON-Resume structures defined in models.py.
3. GitHub enrichment – github.py extracts usernames from the resume, pulls profile and repository data via the GitHub API, and uses the LLM to select the top 7 repositories for scoring.
4. Evaluation – evaluator.py applies the scoring rubric via additional Jinja templates, assessing open-source contributions, production experience, technical skills, and fairness metrics.
5. Output – score.py prints a human-readable summary and, when DEVELOPMENT_MODE=True (the default in config.py), writes a CSV row to resume_evaluations.csv and caches JSON files under cache/.

python score.py path/to/resume.pdf

Understanding the Pipeline Architecture

All stages share utility functions from llm_utils.py that normalize LLM responses and instantiate either OllamaProvider or GeminiProvider based on your LLM_PROVIDER setting. The config.py file manages global settings including the DEVELOPMENT_MODE flag.

Key files involved in local execution include:

• score.py – CLI entry point that orchestrates the workflow.
• pdf.py – Handles PDF-to-Markdown conversion and per-section LLM calls.
• pymupdf_rag.py – Low-level text extraction using PyMuPDF.
• github.py – GitHub profile enrichment and repository classification.
• evaluator.py – Fairness-aware scoring logic.
• models.py – Pydantic schemas and LLM provider interfaces.
• prompts/templates/ – Jinja templates for extraction and evaluation prompts.

Summary

• Clone the interviewstreet/hiring-agent repository and install dependencies via pip install -r requirements.txt.
• Configure your .env file with LLM_PROVIDER (set to ollama or gemini), DEFAULT_MODEL, and required API keys.
• Run the complete pipeline with python score.py <resume.pdf> to generate scored evaluations.
• The system caches intermediate results in cache/ and appends evaluations to resume_evaluations.csv when DEVELOPMENT_MODE=True.
• Core orchestration happens in score.py, with PDF processing in pdf.py and pymupdf_rag.py, and scoring logic implemented in evaluator.py.

Frequently Asked Questions

Do I need a GPU to run the Hiring Agent locally?

No. If you use Ollama with a small model like gemma3:4b, the pipeline runs on CPU-only machines, though inference will be slower. For faster performance or larger models, a GPU is recommended. Alternatively, set GEMINI_API_KEY to offload LLM inference to Google's cloud servers.

Where does the Hiring Agent store intermediate results?

When DEVELOPMENT_MODE=True (the default set in config.py), the pipeline writes cached JSON files to the cache/ directory and appends evaluation results to resume_evaluations.csv in the project root. This allows you to inspect the parsed resume structure and GitHub data without re-running expensive LLM calls.

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

The current implementation in models.py defines OllamaProvider and GeminiProvider classes. To add a new provider, you would need to implement a compatible provider class following the abstraction pattern used in models.py and update llm_utils.py to instantiate your new class based on the LLM_PROVIDER environment variable.

Why does the pipeline require a GitHub token?

The github.py module extracts GitHub usernames from resumes and queries the GitHub API to retrieve profile metadata, repository statistics, and project classifications. A GITHUB_TOKEN is required to avoid rate limits and access detailed repository information. Without it, the GitHub enrichment stage may fail or return incomplete data.

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