Metadata-Version: 2.4
Name: ChatLabel
Version: 0.1.3
Summary: ChatLabel: structured annotation tasks with auditable workbook workflows
Author-email: ChatArch <1073853456@qq.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ChatArch/ChatLabel
Project-URL: Repository, https://github.com/ChatArch/ChatLabel
Project-URL: Documentation, https://arch.gh.wzhecnu.cn/ChatLabel/
Keywords: chatlabel,chatarch,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9.0,>=8.0
Requires-Dist: chatstyle<0.3.0,>=0.2.0
Requires-Dist: chatenv<0.3.0,>=0.2.10
Requires-Dist: fastapi<1.0,>=0.110
Requires-Dist: httpx<1.0,>=0.26
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: python-multipart<1.0,>=0.0.9
Requires-Dist: uvicorn<1.0,>=0.27
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0,>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10.0,>=9.5; extra == "docs"
Requires-Dist: mkdocs-static-i18n<2.0,>=1.2; extra == "docs"
Requires-Dist: mike<3.0,>=2.0; extra == "docs"
Dynamic: license-file

<div align="center">
    <a href="https://pypi.python.org/pypi/ChatLabel"><img src="https://img.shields.io/pypi/v/ChatLabel.svg" alt="PyPI 版本" /></a>
    <a href="https://github.com/ChatArch/ChatLabel/actions/workflows/ci.yml"><img src="https://github.com/ChatArch/ChatLabel/actions/workflows/ci.yml/badge.svg" alt="测试状态" /></a>
    <a href="https://arch.gh.wzhecnu.cn/ChatLabel/"><img src="https://img.shields.io/badge/docs-mkdocs-blue.svg" alt="项目文档" /></a>
</div>

<div align="center">

[英文版](README.en.md) | [简体中文](README.md)
</div>

# ChatLabel

ChatLabel 是一个任务中立、可审计的结构化标注网站。任务 manifest 定义输入字段、允许标签、示例、适配器和完成闸门；同一任务既可处理单条 Case，也可完成 Excel 上传、解析、模型建议、人工校对、校验和导出闭环。首个内置任务是印尼线路产品分类。

当前版本优先完善分类内核：从人工确认表构建可追溯 ground truth、提取 WPS 图片证据、通过 `gpt-5.6-sol` / `xhigh` 调用流式 Responses API，并运行无产品组泄漏的交叉验证和固定留出验收。

> 自动输出是建议结果。完成图片逐项复核、高风险审计和一致性校验前，不应作为最终业务分类。

文档入口：<https://arch.gh.wzhecnu.cn/ChatLabel/>

## 安装与运行

```bash
pip install ChatLabel
chatlabel --version
chatlabel --tree
chatlabel serve
```

默认页面：<http://127.0.0.1:8765/>。正式入口为 <https://label.public.wzhecnu.cn/>；目标机本地入口为 <https://label.local.wzhecnu.cn/>。公网入口由现有 wildcard DNS、共享证书和自动转发层接入，不创建逐服务 DNS 记录。

## 配置

ChatLabel 从 ChatEnv 读取名为 `apple` 的既有 OpenAI profile，也可通过环境变量调整：

| 变量 | 默认值 | 作用 |
| --- | --- | --- |
| `CHATLABEL_DATA_DIR` | `.chatlabel-data` | SQLite、上传文件、图片证据与导出产物目录 |
| `CHATLABEL_CLASSIFIER` | `openai-responses` | 正式网站使用 `openai-responses`；`rules` 仅供离线开发测试 |
| `CHATLABEL_OPENAI_PROFILE` | `apple` | 要读取的 OpenAI profile |
| `CHATLABEL_OPENAI_MODEL` | `gpt-5.6-sol` | Responses API 模型 |
| `CHATLABEL_REASONING_EFFORT` | `xhigh` | 推理强度 |
| `CHATLABEL_MAX_OUTPUT_TOKENS` | `2400` | 单条 proposal 最大输出 token |
| `CHATLABEL_MAX_UPLOAD_BYTES` | `134217728` | 单个上传文件大小上限 |
| `CHATLABEL_MAX_UNCOMPRESSED_BYTES` | `536870912` | XLSX 解压后大小上限 |
| `CHATLABEL_PROPOSAL_WORKERS` | `2` | 单实例 proposal 并发数 |

进程级 `OPENAI_*` 会覆盖 profile 值。模型请求只接受 API Key，不把 key 写入任务或评测结果。网页配置接口只显示模型、API 地址和“是否有 API Key”，不会返回凭据内容。

## 数据与评测

```bash
chatlabel dataset-build \
  --data-root /path/to/data \
  --fixtures /path/to/example-cases.json \
  --output-dir /path/to/ground-truth

chatlabel cross-validate \
  --dataset-dir /path/to/ground-truth \
  --output-dir /path/to/cv-results \
  --folds 5 --limit-per-fold 8 --concurrency 2

chatlabel evaluate \
  --dataset-dir /path/to/ground-truth \
  --output-dir /path/to/validation-results \
  --split validation --concurrency 2
```

`evaluate` 默认断点续跑：相同 prompt 的成功记录直接复用，失败或未完成记录重试，并在每条完成后原子更新 `results.jsonl`。使用 `--no-resume` 可强制重跑所选 split。
独立 challenge set 可通过 `--example-dataset-dir` 显式使用生产批准的 `example/train` 检索池；目标集仍保持独立、不可进入示例池。

ground truth 同时保存来源工作簿、sheet、行号、文件哈希、原始标签、规范化标签、图片哈希和 policy override。旧式 `慢线`、无当前依据的历史拒收、缺图、条件性结论和冲突记录进入 review queue，不进入准确率 gold。

## HTTP API

- `GET /healthz`：进程健康检查。
- `GET /readyz`：SQLite、task registry、运行目录和模型配置就绪检查。
- `GET /api/v1/model`：模型、推理强度、prompt 版本和 API Key 可用状态。
- `GET /api/v1/task-types`：读取版本化任务定义。
- `GET /api/v1/task-types/{task_id}/examples`：读取随任务版本发布的已校对示例。
- `POST /api/v1/cases`：通过 Responses API 创建并持久化单条 Case 建议。
- `GET /api/v1/cases/{case_id}`：读取 Case、模型元数据、人工结果和事件记录。
- `GET /api/v1/cases/{case_id}/image`：在人工复核页回看该 Case 的图片证据。
- `PATCH /api/v1/cases/{case_id}/review`：接受、纠正或标记单条 Case 为 unresolved。
- `POST /api/v1/jobs`：multipart 上传任务类型与 Excel。
- `GET /api/v1/jobs/{job_id}/events`：读取上传、解析、模型、复核、校验和导出事件。
- `GET /api/v1/jobs/{job_id}/records`：分页读取规范化记录、proposal 和 review。
- `POST /api/v1/jobs/{job_id}/proposals`：运行该工作簿的 proposal 阶段。
- `PATCH /api/v1/jobs/{job_id}/records/{record_id}/review`：接受、纠正或 unresolved。
- `POST /api/v1/jobs/{job_id}/validate`：运行覆盖率、备注、冲突、源文件和 WPS 闸门。
- `POST /api/v1/jobs/{job_id}/export`：仅在闸门通过后生成 Excel、JSONL 和报告。
- `GET /api/v1/jobs/{job_id}/artifacts/{artifact_id}`：下载持久化产物。

proposal 响应保留 Responses API 的 response id、模型、状态、延迟、token 用量和检索示例摘要，并始终返回 `final=false`。SQLite 使用 WAL；服务重启后仍可读取 case、job、record、proposal、review、validation、artifact 和审计事件。旧式无持久化 `/api/v1/proposals` 与 `/api/tasks` 已返回 `410 Gone`。

## 开发验证

```bash
python -m pip install -e ".[dev,docs]"
python -m pytest -q
chatlabel --help
chatlabel --tree
python -m build
mkdocs build --strict
```

进一步查看：[CLI 树](docs/cli-tree.md)、[能力地图](docs/capability-map.md)、[Python 接口树](docs/interface-tree.md)。
