<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/interviewstreet/hiring-agent) · [上游 README](https://github.com/interviewstreet/hiring-agent/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# Hiring Agent

<p align="center"><strong>简历转评分流水线（Resume-to-Score pipeline）</strong>，可从 PDF 提取结构化数据，结合 GitHub 信号进行增强，并输出公平、可解释的评价结果。</p>

<p align="center">
  <a href="https://www.python.org/downloads/release/python-3110/">
    <img alt="Python" src="https://img.shields.io/badge/python-3.11%2B-blue.svg">
  </a>
  <a href="https://github.com/interviewstreet/hiring-agent/blob/master/LICENSE">
    <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-yellow.svg">
  </a>
  <a href="https://github.com/psf/black">
    <img alt="Code style: Black" src="https://img.shields.io/badge/code%20style-Black-000000.svg">
  </a>
</p>

---

## 目录

- [概述](#overview)
- [架构](#architecture)
- [安装与配置](#installation-and-setup)
  - [前置要求](#prerequisites)
  - [使用 pip 快速安装](#quick-setup-with-pip)
  - [Ollama 模型](#ollama-models)
- [配置](#configuration)
- [工作原理](#how-it-works)
- [CLI 用法](#cli-usage)
- [目录结构](#directory-layout)
- [提供商详情](#provider-details)
- [贡献](#contributing)
- [许可证](#license)

---

## 概述

Hiring Agent 将简历 PDF 解析为 Markdown，使用本地或托管 LLM 提取分节 JSON，并用 GitHub 个人资料与仓库信号增强数据，最终生成客观评价，包含分类得分、证据、加分项与扣分项。你可以通过 Ollama 完全在本地运行，或使用 Google Gemini。

---

## 架构

<table>
<tr>
<td>

**流程**

1. `pymupdf_rag.py` 将 PDF 页面转换为类 Markdown 文本。
2. `pdf.py` 使用 `prompts/templates` 下的 Jinja 模板，按章节调用 LLM。
3. `github.py` 获取个人资料与仓库，对项目进行分类，并让 LLM 选出前 7 个。
4. `evaluator.py` 在公平性约束下执行严格评分评价。
5. `score.py` 端到端编排整个流程，并在开发模式开启时写入 CSV。

</td>
<td>

**核心模块**

- `models.py`
  Pydantic 模式（schema）与 LLM 提供商接口。

- `llm_utils.py`
  提供商初始化与响应清理。

- `transform.py`
  将松散的 LLM JSON 规范化为 JSON Resume 风格。

- `prompts/`
  用于提取与评分的全部 Jinja 模板。

</td>
</tr>
</table>

---

## 安装与配置

### 前置要求

- **Python 3.11+**

  本仓库将 `.python-version` 固定为 3.11.13。

- **一个 LLM 后端**（二选一）

  - **Ollama** 用于本地模型
    从[官方网站](https://ollama.com/), 安装，然后运行 `ollama serve`。
  - **Google Gemini**：如果你有 API 密钥，可从[此处](https://aistudio.google.com/api-keys). 获取。

### 使用 pip 快速安装

```bash
$ 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 模型

拉取你想使用的模型。例如：

```bash
$ ollama pull gemma3:4b
```

如果想要不同结果，可以拉取其他模型，例如：

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

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

---

## 配置

复制模板并设置环境变量。

```bash
$ cp .env.example .env
```

**环境变量**

| Variable         | Values                                      | Description                                                            |
| ---------------- | ------------------------------------------- | ---------------------------------------------------------------------- |
| `LLM_PROVIDER`   | `ollama` or `gemini`                        | 选择提供商。默认为 Ollama。                                  |
| `DEFAULT_MODEL`  | for example `gemma3:4b` or `gemini-2.5-pro` | 传递给提供商的模型名称。                                     |
| `GEMINI_API_KEY` | string                                      | 当 `LLM_PROVIDER=gemini` 时为必填项。                                   |
| `GITHUB_TOKEN`   | optional                                    | 继承自 shell 环境，可改善 GitHub API 速率限制。 |

提供商映射位于 `prompt.py` 与 `models.py`。`config.py` 文件包含一个标志：

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

迭代期间可保持开启。详见下一节。

---

## 工作原理

<details>
<summary><b>1) PDF 提取</b></summary>

- `pymupdf_rag.py` 与 `pdf.py` 使用 PyMuPDF 读取 PDF，并将页面转换为类 Markdown 文本。
- `to_markdown` 例程处理标题、链接、表格及基本格式。

</details>

<details>
<summary><b>2) 基于模板的章节解析</b></summary>

- `prompts/templates/*.jinja` 为各章节定义严格指令
  Basics、Work、Education、Skills、Projects、Awards。
- `pdf.PDFHandler` 按章节调用 LLM，并组装 `JSONResume` 对象（见 `models.py`）。

</details>

<details>
<summary><b>3) GitHub 增强</b></summary>

- `github.py` 从简历 profiles 中提取用户名，获取个人资料与仓库，并对每个项目进行分类。
- 它让 LLM 恰好选出 7 个不重复的项目，要求达到最低作者提交阈值，并优先选择有意义的贡献。

</details>

<details>
<summary><b>4) 评价</b></summary>

- `evaluator.py` 使用编码了公平性与评分规则的模板。
- 得分包括 `open_source`、`self_projects`、`production` 与 `technical_skills`，以及加分与扣分，随后为证据提供说明。

</details>

<details>
<summary><b>5) 输出与 CSV 导出</b></summary>

- `score.py` 向 stdout 打印可读摘要。
- 当 `DEVELOPMENT_MODE=True` 时，会创建或追加 `resume_evaluations.csv`（包含关键字段），并在 `cache/` 下缓存中间 JSON。

</details>

---

## CLI 用法

### 端到端评分

提供简历 PDF 的路径。

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

执行过程：

1. 若开发模式开启，PDF 提取结果会缓存到 `cache/resumecache_<basename>.json`。
2. 若在简历中找到 GitHub 个人资料，会获取仓库并缓存到 `cache/githubcache_<basename>.json`。
3. 评价器打印报告；在开发模式下，会向 `resume_evaluations.csv` 追加一行 CSV。

---

## 目录结构

```text
.
├── .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
```

---

## 提供商详情

### Ollama

- 设置 `LLM_PROVIDER=ollama`
- 将 `DEFAULT_MODEL` 设为任意已拉取的模型，例如 `gemma3:4b`
- `models.OllamaProvider` 中的提供商封装会调用 `ollama.chat`

### Gemini

- 设置 `LLM_PROVIDER=gemini`
- 将 `DEFAULT_MODEL` 设为受支持的 Gemini 模型，例如 `gemini-2.0-flash`
- 提供 `GEMINI_API_KEY`
- `models.GeminiProvider` 中的封装会将响应适配为统一格式

---

## 贡献

请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)，了解提交 issue、提出变更与提交 pull request 的详细指南。核心原则包括：

- 保持 prompt 声明式且与提供商无关。
- 在不同提供商下用几份真实简历验证变更。
- 添加或调整无单元测试的冒烟测试（smoke test），以最小输入调用各阶段。

---


## 许可证

[MIT](https://github.com/interviewstreet/hiring-agent/blob/master/LICENSE) © HackerRank