interviewstreet / hiring-agent

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

Hiring Agent 是一个“简历转评分”流水线，它能从 PDF 中提取结构化数据，通过 GitHub 信号进行增强，并输出公平且可解释的评估结果。

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.

概述、架构、安装与设置、先决条件、使用 pip 快速安装、Ollama 模型、配置、工作原理、命令行使用、目录结构、提供商详情、贡献指南、许可证。

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.

概述

Hiring Agent 将 PDF 简历解析为 Markdown 格式，利用本地或托管的大语言模型（LLM）提取分段的 JSON 数据，通过 GitHub 个人资料和仓库信号增强数据，最终生成包含类别评分、证据、加分项和扣分项的客观评估报告。你可以使用 Ollama 完全在本地运行，也可以使用 Google Gemini。

Architecture

• pymupdf_rag.py: converts PDF pages to Markdown-like text.
• pdf.py: calls the LLM per section using Jinja templates under prompts/templates.
• github.py: fetches profile and repos, classifies projects, and asks the LLM to select the top 7.
• evaluator.py: runs a strict-scored evaluation with fairness constraints.
• score.py: orchestrates everything end to end and writes CSV when development mode is on.

架构

• pymupdf_rag.py：将 PDF 页面转换为类 Markdown 文本。
• pdf.py：使用 prompts/templates 下的 Jinja 模板，按章节调用 LLM。
• github.py：获取个人资料和仓库，对项目进行分类，并要求 LLM 选出前 7 个项目。
• evaluator.py：在公平性约束下进行严格的评分评估。
• score.py：统筹整个端到端流程，并在开发模式开启时写入 CSV 文件。

Key modules

• models.py: Pydantic schemas and LLM provider interfaces.
• llm_utils.py: Provider initialization and response cleanup.
• transform.py: Normalization from loose LLM JSON to JSON Resume style.
• prompts/: All Jinja templates for extraction and scoring.

核心模块

• models.py：Pydantic 模式定义和 LLM 提供商接口。
• llm_utils.py：提供商初始化和响应清理。
• transform.py：将松散的 LLM JSON 转换为 JSON Resume 标准格式。
• prompts/：用于提取和评分的所有 Jinja 模板。

Installation and Setup

Prerequisites

• Python 3.11+ (The repository pins .python-version to 3.11.13).
• One LLM backend:
  • 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.

安装与设置

先决条件

• Python 3.11+（仓库已将 .python-version 固定为 3.11.13）。
• 一个 LLM 后端：
  • Ollama（用于本地模型）：从官网安装，然后运行 ollama serve。
  • Google Gemini：如果你有 API 密钥，可从此处获取。

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

使用 pip 快速安装

$ git clone https://github.com/interviewstreet/hiring-agent
$ cd hiring-agent
$ python -m venv .venv
# Linux 或 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

Ollama 模型

拉取你想要使用的模型。例如： $ ollama pull gemma3:4b 如果你想要不同的结果，可以拉取其他模型，例如： # 针对更高系统配置 $ ollama pull gemma3:12b # 针对更低系统配置 $ ollama pull gemma3:1b

Configuration

Copy the template and set your environment variables. $ cp .env.example .env

Variable	Values	Description
LLM_PROVIDER	ollama or gemini	Chooses provider. Defaults to Ollama.
DEFAULT_MODEL	e.g., gemma3:4b	Model name passed to the provider.
GEMINI_API_KEY	string	Required when LLM_PROVIDER=gemini.
GITHUB_TOKEN	optional	Improves GitHub API rate limits.

配置

复制模板并设置环境变量。 $ cp .env.example .env

变量	值	描述
LLM_PROVIDER	ollama 或 gemini	选择提供商。默认为 Ollama。
DEFAULT_MODEL	例如 gemma3:4b	传递给提供商的模型名称。
GEMINI_API_KEY	字符串	当 LLM_PROVIDER=gemini 时必需。
GITHUB_TOKEN	可选	提高 GitHub API 速率限制。

How it works

1. PDF extraction: pymupdf_rag.py and pdf.py read the PDF using PyMuPDF and convert pages to Markdown-like text.
2. Section parsing: prompts/templates/*.jinja define strict instructions for each section. pdf.PDFHandler calls the LLM per section and assembles a JSONResume object.
3. GitHub enrichment: github.py extracts a username, fetches profile and repos, and asks the LLM to select exactly 7 unique projects.
4. Evaluation: evaluator.py uses templates that encode fairness and scoring rules.
5. Output: score.py prints a summary to stdout. When DEVELOPMENT_MODE=True, it creates/appends resume_evaluations.csv and caches intermediate JSON.

工作原理

1. PDF 提取：pymupdf_rag.py 和 pdf.py 使用 PyMuPDF 读取 PDF 并将其转换为类 Markdown 文本。
2. 章节解析：prompts/templates/*.jinja 为每个章节定义了严格的指令。pdf.PDFHandler 按章节调用 LLM 并组装成 JSONResume 对象。
3. GitHub 增强：github.py 提取用户名，获取个人资料和仓库，并要求 LLM 精确选出 7 个独特的项目。
4. 评估：evaluator.py 使用编码了公平性和评分规则的模板。
5. 输出：score.py 将摘要打印到标准输出。当 DEVELOPMENT_MODE=True 时，它会创建或追加到 resume_evaluations.csv，并缓存中间 JSON 数据。

CLI usage

End to end scoring: $ python score.py /path/to/resume.pdf

命令行使用

端到端评分： $ python score.py /path/to/resume.pdf

Provider details

• Ollama: Set LLM_PROVIDER=ollama, DEFAULT_MODEL to any pulled model.
• Gemini: Set LLM_PROVIDER=gemini, DEFAULT_MODEL to a supported model (e.g., gemini-2.0-flash), and provide GEMINI_API_KEY.

提供商详情

• Ollama：设置 LLM_PROVIDER=ollama，并将 DEFAULT_MODEL 设置为任何已拉取的模型。
• Gemini：设置 LLM_PROVIDER=gemini，将 DEFAULT_MODEL 设置为支持的模型（例如 gemini-2.0-flash），并提供 GEMINI_API_KEY。

Contributing

Please read the CONTRIBUTING.md for detailed guidelines. Key principles:

• Keep prompts declarative and provider-agnostic.
• Validate changes with real resumes.
• Add unit-free smoke tests.

贡献指南

请阅读 CONTRIBUTING.md 获取详细指南。核心原则：

• 保持提示词（Prompts）的声明式和提供商无关性。
• 使用真实简历验证更改。
• 添加无单元测试的冒烟测试。

License

MIT © HackerRank

许可证

MIT © HackerRank