interviewstreet/hiring-agent

Source: https://github.com/interviewstreet/hiring-agent

Hiring Agent

Resume-to-Score pipeline that extracts structured data from PDFs, enriches with GitHub signals, and outputs a fair, explainable evaluation.

Contents

• Overview
• Architecture
• Installation and Setup
  • Prerequisites
  • Quick setup with pip
  • Ollama models
• Configuration
• How it works
• CLI usage
• Directory layout
• Provider details
• Contributing
• License

Overview

Hiring Agent parses a resume PDF to Markdown, extracts sectioned JSON using a local or hosted LLM, augments the data with GitHub profile and repository signals, then produces an objective evaluation with category scores, evidence, bonus points, and deductions. You can run fully local with Ollama or use Google Gemini.

Architecture

Installation and Setup

Prerequisites

• Python 3.11+

  The repository pins .python-version to 3.11.13.

• One LLM backend (either of them)

  • Ollama for local models Install from the official site, then run ollama serve.
  • Google Gemini if you have an API key, get it from here.

Quick setup with pip

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

$ python -m venv .venv
# Linux or macOS
$ source .venv/bin/activate
# Windows
# .venv\Scripts\activate

$ pip install -r requirements.txt

Ollama Models

Pull the model you want to use. For example:

$ ollama pull gemma3:4b

If you want different results, you can pull other models such as:

# For higher system configuration
$ ollama pull gemma3:12b

# For lower system configuration
$ ollama pull gemma3:1b

Configuration

Copy the template and set your environment variables.

$ cp .env.example .env

Environment variables

Provider mapping lives in prompt.py and models.py. The config.py file has a single flag:

# config.py
DEVELOPMENT_MODE = True  # enables caching and CSV export

You can leave it on during iteration. See the next section for details.

How it works

CLI usage

End to end scoring

Provide a path to a resume PDF.

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

What happens:

1. If development mode is on, the PDF extraction result is cached to cache/resumecache_<basename>.json.
2. If a GitHub profile is found in the resume, repositories are fetched and cached to cache/githubcache_<basename>.json.
3. The evaluator prints a report and, in development mode, appends a CSV row to resume_evaluations.csv.

Directory layout

.
├── .env.example
├── .python-version
├── config.py
├── evaluator.py
├── github.py
├── llm_utils.py
├── models.py
├── pdf.py
├── prompt.py
├── prompts/
│   ├── template_manager.py
│   └── templates/
│       ├── awards.jinja
│       ├── basics.jinja
│       ├── education.jinja
│       ├── github_project_selection.jinja
│       ├── projects.jinja
│       ├── resume_evaluation_criteria.jinja
│       ├── resume_evaluation_system_message.jinja
│       ├── skills.jinja
│       ├── system_message.jinja
│       └── work.jinja
├── pymupdf_rag.py
├── requirements.txt
├── score.py
└── transform.py

Provider details

Ollama

• Set LLM_PROVIDER=ollama
• Set DEFAULT_MODEL to any pulled model, for example gemma3:4b
• The provider wrapper in models.OllamaProvider calls ollama.chat

Gemini

• Set LLM_PROVIDER=gemini
• Set DEFAULT_MODEL to a supported Gemini model, for example gemini-2.0-flash
• Provide GEMINI_API_KEY
• The wrapper in models.GeminiProvider adapts responses to a unified format

Contributing

Please read the CONTRIBUTING.md for detailed guidelines on filing issues, proposing changes, and submitting pull requests. Key principles include:

• Keep prompts declarative and provider-agnostic.
• Validate changes with a couple of real resumes under different providers.
• Add or adjust unit-free smoke tests that call each stage with minimal inputs.

License

MIT © HackerRank