Metadata-Version: 2.4
Name: trace-inquest
Version: 0.1.0
Summary: Trace-level evaluation, evidence-driven failure attribution and regression gating for LLM agents
License: MIT
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: SQLAlchemy<3,>=2.0
Requires-Dist: alembic>=1.13
Requires-Dist: fastapi>=0.119
Requires-Dist: uvicorn>=0.37
Requires-Dist: httpx>=0.28
Requires-Dist: python-multipart>=0.0.20
Requires-Dist: Jinja2>=3.1
Requires-Dist: PyYAML>=6.0
Requires-Dist: jsonschema>=4.23
Requires-Dist: rich>=13.9
Requires-Dist: opentelemetry-api<2,>=1.36
Requires-Dist: opentelemetry-sdk<2,>=1.36
Requires-Dist: opentelemetry-proto<2,>=1.36
Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.36
Requires-Dist: opentelemetry-semantic-conventions>=0.57b
Requires-Dist: openinference-semantic-conventions==0.1.41
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: hypothesis>=6.112; extra == "dev"
Requires-Dist: ruff>=0.16; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: opentelemetry-util-genai==1.2b0; extra == "dev"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
Provides-Extra: live
Requires-Dist: openai>=2.32; extra == "live"
Requires-Dist: ollama; extra == "live"
Dynamic: license-file

# TraceInquest

**面向 LLM Agent 轨迹的评估可信度工具**：确定性规则 + 因果消融为主干，把"这个分数能不能信"
变成一个可度量、可门禁的对象。发行名 `trace-inquest`，导入包 `traceinquest`，CLI `inquest`/`inq`，
数据目录 `.inquest/`，环境变量前缀 `INQUEST_`，schema `tk-1.0.0`。

**A trustworthiness tool for LLM-agent traces**: deterministic rules plus causal ablation make
"can this score be trusted" a measurable, gateable object instead of a footnote.

| 项 | 值 |
|---|---|
| 与 **THUDM/AgentBench**（ICLR 2024 榜单）的关系 | **无关**。仓库目录名可能是 `AgentBench`，对外一律用 TraceInquest |
| 与 PyPI 项目 **`agentautopsy 2.4.0`** 的关系 | **无关**，不是同名项目的实现或分叉 |
| 当前状态 | 设计文档 + W1–W25 实现与证据已落盘（W25 用户裁决 A：停止追 G2-9AI）；**已推送 Draft PR #5（双平台 CI 绿：run 40283425112 @ 29a3e5a，未合并）**；**GATE1 / GATE2 / P0 Freeze 均未抬格**（W14 起为 Human / AI-Review 双轨呈现）；**未发布到 PyPI**，也从未声称已发布 |
| 依赖口径 | 完整包依赖 FastAPI/SQLAlchemy/alembic/httpx/pydantic/typer 等（见 `pyproject.toml`）；`trace-inquest-core` 的第三方依赖只有 pydantic。**两个包都**不**声称"零第三方依赖"** |
| 数字口径 | 精度类数字凡未实测一律 `待实测`；性能与体积数字自 2026-10-17 起有实测出处（`docs/BASELINES.json.perf`、`reports/stats/`）；LLM judge 默认关闭，其输出**永不**当作 ground truth |
| 许可证 | **MIT**（OPEN-07 裁决：2026-10-29 用户选择；全文见根 [`LICENSE`](LICENSE)，上游合规索引见 [`docs/LICENSES.md`](docs/LICENSES.md)，许可矩阵唯一定义处 `docs/TECH_STACK.md §7`） |

---

## 1. 十分钟跑通（operator quick start）

前置：Python 3.12（`>=3.12,<3.13`，τ² 的约束）、Node 18+（只有看 Dashboard 时才需要）。

> Windows 现实：PATH 上的 `python` 常是 Microsoft Store 占位程序，因此下面每条命令都写全解释器
> 路径；把 `D:/Anaconda/python.exe` 换成你自己的 3.12 解释器即可。CLI 的入口是安装出来的脚本
> `.venv/Scripts/inquest`，**不是** `python -m inquest`（后者没有 `__main__` 可执行入口）。
> 本机 pip 配置只有 `trusted-host` 没有 `index-url` ⇒ 装包必须显式 `-i <镜像>`。

```bash
# ① 装（editable：alembic 迁移需要仓库根，见 §5）
D:/Anaconda/python.exe -m venv .venv
.venv/Scripts/python -m pip install -i https://mirrors.aliyun.com/pypi/simple -e ".[dev]"

# ② 建库（幂等；重复执行只会打印"已升级到 head"）
.venv/Scripts/inquest init

# ③ 零 key、零网络、零容器的离线闭环
.venv/Scripts/inquest demo --offline

# ④ 重放基准任务集并跑判定与归因（产出 trace + evaluations + diagnoses）
.venv/Scripts/inquest run

# ⑤ 自包含静态报告（HTML/CSV/JSON，无 JS 也可读）
.venv/Scripts/inquest report --run <RUN_ID>

# ⑥ 可复现统计链：分层表 + 族内 Holm–Bonferroni + 成本 + 限制清单
.venv/Scripts/inquest report --run <RUN_ID_A> --candidate <RUN_ID_B> --stats

# ⑦ 环境侧性能实测（不含模型推理），写 .inquest/bench/<date>.json
.venv/Scripts/inquest bench --env-only --repeat 5 --warmup 1

# ⑦b 只读校验 TaskSpec：逐文件报有效/无效与出处，不重放、不建 run、不写库、不调模型
#     退出码 0=全部有效；3=存在无效文件 / 没有待校验文件 / 路径不对（五种结局看 outcome）
.venv/Scripts/inquest bench --validate-only

# ⑧ 门禁：退出码 0=pass、1=fail、2=inconclusive、3=输入问题、4=读库失败
.venv/Scripts/inquest gate --base <RUN_ID_A> --candidate <RUN_ID_B>

# ⑨ 服务与 Dashboard
.venv/Scripts/inquest serve                      # 默认只监听 127.0.0.1
cd dashboard && npm ci && npm run codegen && npm run build && npm run preview
```

§1 的每条命令都在 2026-10-17 于本机（Windows 11 22631 / Python 3.12）真跑过，不是在描述意图。
实测到的量：`run` 一次产出 24 任务 / 24 trace / 86 次工具调用、写出 576 行 evaluations 与 10 行
diagnoses；`bench --env-only` 的 24×k=3 整批墙钟 p50=0.719s、p95=3.156s（monotonic 时钟、
5 计时轮 + 1 热身轮；机器规格随产物一起落盘）；`bench --validate-only` 扫到 24 份 TaskSpec、
24 份通过装载侧校验、退出码 0（同一天 W13 的 `tests/integration/test_cli_w12_paths.py` 把
"改坏一份 ⇒ 退出码 3 且点名到文件"也变成了可执行判据）。

### English (same steps, condensed)

```bash
python3.12 -m venv .venv && .venv/bin/python -m pip install -e ".[dev]"
.venv/bin/inquest init          # idempotent
.venv/bin/inquest demo --offline   # zero keys, zero network, zero containers
.venv/bin/inquest run           # replay 24 tasks → evaluations + diagnoses
.venv/bin/inquest report --run <RUN_ID> [--stats --candidate <OTHER>]
.venv/bin/inquest bench --env-only --repeat 5 --warmup 1
.venv/bin/inquest bench --validate-only        # read-only TaskSpec check; 0 all valid / 3 otherwise
.venv/bin/inquest gate --base <A> --candidate <B>     # 0 pass / 1 fail / 2 inconclusive
.venv/bin/inquest serve && cd dashboard && npm ci && npm run build && npm run preview
```

On non-Windows the interpreters live in `.venv/bin/`; nothing else changes. The CLI reads
credentials from the process environment only (`.env.example` lists the variables); no key ever
travels through a request body, a trace, an artifact, a log line or the Dashboard.

## 2. 从一条 trace 读起（what to look at）

```bash
.venv/Scripts/inquest demo --offline -v        # 打印 run_id 与逐指标行（含 not_applicable 的原因）
.venv/Scripts/inquest report --run <RUN_ID> -v # 报告产物路径
```

产物里每个指标行都带 `validity`（`full` / `degraded` / `not_applicable`）与 `denominator`。
缺失**不写成 0**：`cost_usd=null` 必然与 `cost_unknown_reason`（如 `price_table_missing`）成对出现，
失败轨迹上的 `planning_efficiency` 一定是 `not_applicable`。这是判据，不是排版偏好。

## 3. 两个发行包

| 发行名 | 内容 | 第三方依赖 | 可导入 |
|---|---|---|---|
| `trace-inquest` | 全部：normalizer / store / api / dashboard / CLI / diagnosis / metrics | 见 `pyproject.toml` | `traceinquest.*` |
| `trace-inquest-core` | 判定切片：`core/` + `analyzers/` + `evaluators/` | **只有 `pydantic>=2.11,<3`** | `traceinquest.core` / `.analyzers` / `.evaluators` |

`trace-inquest-core` **不声称"零第三方依赖"**：它不需要 FastAPI/SQLAlchemy/HTTP 客户端/数据库，
但 `core.models` 就是 pydantic 模型，所以依赖元数据里如实声明 pydantic（"无数据库依赖"、
"无框架依赖"、"零第三方"是三件不同的事，只有前两件成立）。

两个包都提供 `traceinquest` 这个顶层包名，因此按**分别安装**设计与验证：不要把
`trace-inquest-core` 与完整发行装进同一个环境并期待互不干扰 —— 同名子包的归属由安装顺序决定，
pip 不会为共享文件做版本仲裁。需要同时使用时只装完整发行包。

```bash
.venv/Scripts/python -m build                                  # 完整包 → dist/
.venv/Scripts/python -m tests.tools.build_core_dist --build    # core → dist-core/（wheel + sdist）
.venv/Scripts/python -m pip install --no-deps --target /tmp/core-check dist-core/trace_inquest_core-*.whl
```

`build_core_dist` 会把判定切片按字节物化进 gitignore 的 `.build/core/` 再构建。这一步不是装饰：
`package-dir` 指向项目目录之外时 wheel 是对的，但 sdist 里**一个 `.py` 都没有**（实测 5 个条目），
装出来是个空命名空间。清单与哈希由 `tests/e2e/test_core_distribution_e2e.py` 逐文件比对。

## 4. 判据地图（数字从哪里来）

| 你要的东西 | 唯一出处 |
|---|---|
| 受控词表（20 个失败码、指标 id、origin/validity/verdict…） | `docs/TRACE_SCHEMA.md` |
| 指标公式与三态判定 | `docs/EVALUATION_DESIGN.md` ＋ `src/traceinquest/evaluators/<metric_id>.py` |
| 失败码谓词与因果消融 | `docs/FAILURE_DIAGNOSIS.md` ＋ `src/traceinquest/diagnosis/detectors/<code>.py` |
| 端点契约（含 `origin=live` 的三条通道） | `docs/API_DESIGN.md` ＋ `openapi.json`（`python -m tests.tools.export_openapi` 生成） |
| 视图与图表形状 | `docs/DASHBOARD_DESIGN.md` §5.2 ＋ `dashboard/src/lib/chartContracts.ts` |
| 实测性能与统计报告 | `docs/BASELINES.json.perf`、`reports/stats/`、`.inquest/bench/<date>.json` |
| 矛盾与裁决 | `docs/CONSISTENCY-REVIEW.md`（DEF 台账，只增不删） |

## 5. 已知限制（read this before quoting any number）

1. **精度未验证**。诊断精度的 macro-F1 / 严格 step 命中率 / κ 需要 ≥60 条独立人工标注；
   仓库当前是 **0/60 人工** ⇒ 这些格子是 `待实测`，任何"精度已验证"的说法都是错的。
   W14 起另有 60 条 **AI 评审**产出的参考标签（`label_source=ai_reference`，59 闭合 + 1 显式 unresolved），
   它的名字是 `reference_type=ai_adjudicated`：**不进人工分母、不是 human ground truth**。
2. **GATE1 / GATE2 / P0 Freeze 未抬格**，`docs/BASELINES.json` 的 `measured=false` 如实保留。
   验收采用 **Gate Version 双轨制**（`docs/ACCEPTANCE.md §6.3`）：`G1-6`/`G2-9` 是
   *Legacy Human Gate*（判据文字与状态未改写，仍"未达成"），新开的 `G1-6AI`/`G2-9AI` 是
   *AI Review Gate v1*——**AI 格成立不等于人工格成立**，两者必须并列呈现。
   `G1-6AI` 为 `Verified`；**`G2-9AI` 在 W25 冻结为 `Work Completed / Gate Not Met`**
   （28 met / 10 deficit / 1 blocked；用户 2026-10-24 裁决 A：停止投入，不做人工标注）。
   AI–AI 一致性一律叫 `ai_ai_kappa`（`agreement_scope=ai_ai`），不得读成 inter-rater 可靠性。
3. **未发布**。`trace-inquest` 与 `trace-inquest-core` 都不在 PyPI 上，本文不声称相反；
   PR #5 是 Draft 且未合并，CI 绿只表示离线门禁通过，不等于发布或 GATE 通过；
   许可证已按 OPEN-07 裁决定为 MIT（2026-10-29；根 `LICENSE` + `docs/LICENSES.md`），
   发布动作本身仍未发生。
4. **性能数字是环境侧的**：`bench --env-only` 走重放通路（`mock-llm-v1` 不做推断），
   不含模型推理，因此不是端到端延迟，也不得与 live run 的墙钟混读。
5. **`pricing.yaml` 载 GLM-5.3-Flash 名义牌价**（OPEN-01 裁决：智谱官方页 2026-10-21，
   USD 按 Fed H.10 2026-10-26 汇率换算，出处写在文件 `source` 字段）：表内模型的
   `cost_usd` = **"若按牌价计费"的名义成本**，不是实付——实际现金另计（免费包抵扣时
   实付为 0，两套口径不得混写）；不在表内的模型仍 `null` + `price_table_missing`。
   单价绝不按模型名猜，CNY 报价与 USD 换算也不是同一件事。
6. **live 模型实验未做**：GLM-5.3 通道的真实 smoke 停在 `NOT RUN`（缺密钥/额度/明确授权），
   离线路径与回放数据不能替代它。
7. **alembic 迁移需要仓库根**：以 editable 方式安装（`pip install -e .`）。非 editable 安装下
   `inquest init` 会明确报"找不到 alembic.ini"，而不是抛一个二级错误。
8. **策略覆盖 ≠ 真实风险**：`policy_clean` 度量"声明的策略被遵守"，不是攻击面评估。
9. **多 Agent 归因基于单一构造样本**，外部效度未建立。
10. MAST / TRAIL 只按论文（arXiv 2503.13657 等）重实现与引用，**未复制其仓库代码**；
    OpenInference / OTel semconv 只 pin spec 文本（`semconv/PINNED.txt`；OpenInference 依赖精确
    pin `==0.1.41`）；Phoenix 服务端代码（Elastic License 2.0）未取用。映射表里出现的他人发表
    数字均标注"非本项目结果"。
11. **远端浏览器层未验证**：PR #5 的 Ubuntu / Windows CI 各跳过 **46 条**真实浏览器 E2E
    （CI 未安装 playwright；本机 46 passed 是本机结果）；远端 skip 不得读成通过。

## 6. 设计文档与执行纪律

单一事实来源在 `docs/`（索引见 `docs/README.md`）：`TRACE_SCHEMA.md`、`EVALUATION_DESIGN.md`、
`FAILURE_DIAGNOSIS.md`、`DATABASE_DESIGN.md`、`API_DESIGN.md`、`DASHBOARD_DESIGN.md`、
`BENCHMARK.md`、`ARCHITECTURE.md`、`TECH_STACK.md`、`TESTING.md`、`REQUIREMENTS.md`、`PLAN.md`、
`ACCEPTANCE.md`、`PROGRESS.md`、`CONSISTENCY-REVIEW.md`。执行纪律在 `AGENTS.md`。
