内容
<div align="center">
<p align="center">
<img src="assets/banner.png" alt="实验审计 Banner" width="100%">
</p>
**一个用于机器学习实验的科学推理引擎。**
输入主张和证据 — 它会检查缺失的支持，限定证据的范围，
发现矛盾，评估置信度，并生成结构化的科学报告。
就像一个仔细的顾问在整理结果之前会给出的评审意见一样。
[](https://pypi.org/project/experiment-audit/)
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/SreeDharshan-GJ/experiment-audit/actions)
[](https://github.com/jlowin/fastmcp)
[](CHANGELOG.md)
由 **[Sree Dharshan G J](https://github.com/SreeDharshan-GJ)** 创建和维护。
</div>
<br>
> 大多数实验跟踪工具都会显示数字。`experiment-audit` 检查这些数字背后的主张是否成立 — 缺失的证据、超出范围的比较、与先前结果的矛盾，以及未经假设的置信度。
<br>
## 安装
```bash
pip install experiment-audit
```
需要 Python 3.11+。参见下面的[快速入门](#快速入门-30-秒) 或跳转到 [Claude Code 集成](#claude-code-兼容).
<br>
## 快速入门（30 秒）
```python
from experiment_audit.reasoning import (
ScientificReasoningPipeline, ScientificReport,
Claim, ClaimCategory, Scope,
)
claim = Claim(
id="c1",
subject="model-x",
statement="model-x 在 CIFAR-10 上实现了 95% 的准确率",
category=ClaimCategory.PERFORMANCE,
scope=Scope(dataset="cifar-10"),
)
pipeline = ScientificReasoningPipeline()
context = pipeline.build_initial_context(claims=[claim], evidence=[])
report = ScientificReport.from_pipeline_report(pipeline.execute(context))
print(report.to_markdown())
```
**主张 → 证据 → 推理 → 科学报告。** 输出中的每个发现都可以追溯到特定的证据 — 引擎不会断言它无法指出的任何内容。
更喜欢命令行吗？
```bash
experiment-audit reasoning schema > claims.json # 查看预期的输入格式
experiment-audit reasoning run --input claims.json --format markdown
```
<br>
## Claude Code 兼容
该项目背后的推理学科 — 如何表达发现、权衡矛盾的证据以及编写结构化的评审意见 — 作为一个 [Claude Code](https://docs.claude.com/claude-code) 技能提供，具有八种 MCP 审计工具，在设置 `WANDB_API_KEY` 的地方自动可用。
<sub>**◆ Claude Code** — 在此仓库中运行</sub>
```bash
/plugin marketplace add ./dev/experiment-audit-plugin
/plugin install experiment-audit@experiment-audit
```
它会自动触发类似的提示：
- *"这个消融实验是否混淆了？"*
- *"为什么我的损失崩溃了？"*
- *"审查这篇论文的结果主张。)*
- *"比较这些消融研究。)*
- *"为此撰写评审意见。*
参见 [快速入门：MCP 服务器](#快速入门-mcp服务器-wb-审计工具) 以进行手动 MCP 设置，或
[插件的 README](dev/experiment-audit-plugin/README.md) 以获取完整详细信息。
<br>
## 为什么是 experiment-audit？
传统的实验跟踪器擅长于一件事：显示指标。它们会愉快地告诉你运行的最终准确率、损失曲线或配置差异。它们没有检查的是关于这些数字的*句子*是否实际上得到了支持。
`experiment-audit` 以谨慎的评审者对待结果的方式进行处理：
- 这个主张背后有证据吗，还是一个偷偷混进来的假设？
- 证据是否与所声称的内容相符 — 相同的 dataset、相同的硬件、相同的评估协议 — 或者它被用来证明的不仅仅是它所证明的？
- 您测量的其他内容是否与此相矛盾？
- 声明中的置信度是否与证据成比例，还是借鉴了结果*给人的感觉*？
这在可重复性、消融实验和容易因截止日期压力而夸大的论文写作主张（即研究声明验证在那里悄悄失效的地方）最为重要。
<br>
## 适用人群
| | |
|---|---|
| **机器学习工程师** | 在报告或 PR 描述中发货前对结果进行合理性检查 |
| **AI 研究人员** | 在提交前捕获混淆的消融实验和超出范围的比较 |
| **研究生** | 在导师审核结果部分之前获得类似评审者的反馈 |
| **研究实验室** | 团队实验的共享、确定的科学主张检查 |
| **学术/开源项目** | 结构化、证据追踪的科学报告，而不是临时拼凑的报告 |
<br>
## 推理引擎的作用
给定一组**主张**（ *"model-x 在 CIFAR-10 上实现了 95% 的准确率"* ）和支持它们**证据**（指标、配置、日志、先前的运行），引擎会运行六个规则，并生成一个`ScientificReport`：
| # | 规则 | 检查内容 |
|---|------|-----------------|
| 1 | **缺失证据** | 该主张是否有任何支持证据轨迹？ |
| 2 | **范围** | 证据是否与主张的声明范围（相同的 dataset、相同的硬件、相同的评估协议）相符？ |
| 3 | **矛盾** | 是否有其他主张或证据项与此相冲突？ |
| 4 | **置信度** | 计算出的分数，而不是猜测 — 基于证据质量/数量、发现的矛盾和缺失的内容。 |
| 5 | **判断** | 结论（支持 / 部分支持 / 不支持）及其背后的推理。 |
| 6 | **建议** | 关于它的处理方法 — 收集更多证据、缩小主张的范围、撤回它。 |
每个发现都可以追溯到特定的证据。报告中的任何内容都不是未经支持的断言 — 那将破坏重点。
> 这是包中的两个推理管道之一。第二个、更低级的管道（`ScientificReasoningEngine` — 证据 → 观察 → 假设 → 置信度 → 判断 → 建议）是一个更通用、更可扩展的框架，用于注入自定义假设和置信度逻辑。大多数人应该从上面的六规则管道开始。参见 `src/experiment_audit/reasoning/__init__.py` 以获取两者。
<br>
## 功能
**推理引擎（核心）**
- 主张和证据建模（`Claim`、`EvidenceItem`、`Scope`）具有结构化类别
- 端到端的六规则科学推理管道，或逐规则运行
- 跨主张和证据的矛盾检测
- 置信度评分由证据质量/数量驱动，而不是固定的启发式方法
- 结构化 `ScientificReport` — Markdown、JSON 或纯文本
- 零网络调用；完全在您提供的数据上运行
**引擎周围的接口**
- **Python API** — `experiment_audit.reasoning`，用于在您自己的工具中嵌入管道
- **CLI** — `experiment-audit reasoning run|schema`
- **Claude Code 技能** — 推理学科作为可安装的技能，带有工作示例
- **MCP 服务器** — 八种用于直接从代理审计 Weights & Biases 运行的工具
- **Weights & Biases 后端** — MCP 工具后面的只读运行/扫描/指标访问
<br>
## 快速入门：MCP 服务器（W&B 审计工具）
原始的 W&B `experiment-audit` 工具仍然在这里，不变，作为 MCP 集成。设置只读的 W&B API 密钥：
```bash
export WANDB_API_KEY="your-read-only-key"
export WANDB_ENTITY="your-team-or-username" # 可选
```
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"experiment-audit": {
"command": "experiment-audit-mcp",
"env": {
"WANDB_API_KEY": "your-read-only-key"
}
}
}
}
```
**Claude Code:**
<sub>**◆ Claude Code**</sub>
```bash
claude mcp add -e WANDB_API_KEY=your-read-only-key experiment-audit -- experiment-audit-mcp
```
> `-e` 必须在服务器名称之前使用，而不是之后 — 在某些 Claude Code 版本中，将其放在名称后面会导致“无效环境变量格式”错误。
然后询问您的代理类似这样的问题：
> "我是否搞砸了我的内存消融实验？比较 `mamfac-baseline` 和 `mamfac-no-memory` 在 `mamfac` 项目中，并检查唯一的真正区别是否是 `use_memory`。"
代理调用 `audit_ablation`，它返回一个结论
（`clean` / `confounded` / `uncertain`）、置信度级别和它所依据的完整配置差异。
完整的工具参考（所有八种工具、确切的模式、方法论）位于
[`docs/design-spec-v1.md`](docs/design-spec-v1.md) 和
[`docs/audit-methods.md`](docs/audit-methods.md) — 与 v1.0.0 版本保持不变。
<br>
## 架构
```
experiment_audit/
├── reasoning/ # 科学推理引擎
│ ├── claims.py # Claim, ClaimSet, Scope
│ ├── evidence.py # Evidence, EvidenceItem（被两个管道共享）
│ ├── contradictions.py # Contradiction, ContradictionSet
│ ├── scientific_rules/ # 六个具体规则
│ │ ├── missing_evidence_rule.py
│ │ ├── scope_rule.py
│ │ ├── contradiction_rule.py
│ │ ├── confidence_rule.py
│ │ ├── judgment_rule.py
│ │ └── recommendation_rule.py
│ ├── rules.py # RuleContext, ScientificRule 基础
│ ├── pipeline.py # ScientificReasoningPipeline：按顺序运行六个规则
│ ├── scientific_report.py # ScientificReport：to_markdown/to_json/to_text
│ ├── observations.py # 通用管道：证据模式检测
│ ├── hypotheses.py # 通用管道：候选解释
│ ├── confidence.py # 通用管道：置信度评分
│ ├── judgment.py # 通用管道：判决渲染
│ ├── recommendation.py # 通用管道：建议
│ └── engine.py # ScientificReasoningEngine：通用管道的编排器
├── cli.py # `experiment-audit reasoning run|schema`
├── models.py # RunRef, Run, MetricPoint, MetricHistory, Sweep, Page[T]
├── errors.py # ToolError + 冻结的 error_type 分类法
├── server.py # FastMCP 入口；注册 8 个 W&B 审计工具
├── backends/
│ ├── base.py # ExperimentBackend ABC, BackendCapability
│ ├── fake_backend.py # 内存测试双端
│ └── wandb_backend.py # 真实的 W&B 实现
└── analysis/ # W&B 审计工具的纯启发式方法
├── comparison.py
├── divergence.py
├── confound.py
└── sensitivity.py
```
推理引擎和 MCP/W&B 层是独立的 — 推理引擎直接接受 `Claim` 和 `EvidenceItem`，不依赖于 W&B、FastMCP 或任何后端。通过 [路线图](#路线图) 将 W&B 运行数据作为主张/证据输入到推理引擎中（而不是手动构建它们，就像上面的快速入门示例一样）。
有关推理引擎的设计原理，请参见
[`research/07_reasoning_engine/`](research/07_reasoning_engine/)
（`reasoning-engine.md`, `reasoning-rules.md`, `confidence-system.md`, `evidence-model.md`,
`scientific-reviewer.md`）。有关 MCP/W&B 层的冻结合同，请参见
[`docs/design-spec-v1.md`](docs/design-spec-v1.md)。
<br>
## 数据处理
- 除调用您自己的 W&B 端点（仅 MCP 层 — 推理引擎本身完全不进行网络调用）之外，数据永远不会离开您的机器。
- 凭证一次从环境变量中读取，在服务器启动时快速验证失败，并从未记录。
- 使用 **只读** W&B API 密钥 — 此服务器没有写入路径。
<br>
## 已知缺陷（诚实状态）
- 目前没有将 W&B 运行直接转换为 `Claim`/`EvidenceItem` 的适配器 — 您自己构造它们（CLI 模式或 Python），或编写自己的提取步骤。这是 [路线图](#路线图) 中的首要事项。
- 通用管道 (`ScientificReasoningEngine`) 默认其规则引擎阶段为 no-op，除非您注入一个 — 它是一个可扩展性点，而不是第二个完整的管道。
- 274 个测试通过 (`pytest tests/ -q`); 这是管道机制的实际覆盖，而不是您所在研究领域的六个规则阈值的替代审查。
- MCP/W&B 层目前仅支持 W&B（MLflow 已在接口层面原型化，但未实现），而 `audit_sweep` 的相关性排名仅检测线性关系。
完整的详细信息，包括因构建环境缺乏实时凭证而被阻止的内容，位于 [`docs/design-spec-v1.md`](docs/design-spec-v1.md) 和
[CHANGELOG](CHANGELOG.md)。
<br>
## 开发
```bash
git clone https://github.com/SreeDharshan-GJ/experiment-audit.git
cd experiment-audit
pip install -e ".[dev]"
pytest tests/ -q # 274 个测试
ruff check src/ tests/ # lint
```
推理引擎的测试不需要网络访问或凭证 — 它们完全在内存 `Claim`/`Evidence` 夹具上运行。MCP/W&B 层的测试针对 `FakeBackend` 运行，这是一个可以注入设计规范中命名的每个对抗状态的内存测试替身。
<br>
## 贡献
欢迎贡献 — 请先阅读 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
MCP/W&B 层的 v1 设计 (`docs/design-spec-v1.md`) 是**冻结的**：对其工具模式、模型字段或后端接口的更改需要明确的、记录的设计决策，而不是静默的 PR。推理引擎的六个规则及其阈值是更新的，更开放讨论 — 如果您提出更改规则逻辑（而不是线路）的建议，请解释您正在进行的推理质量权衡，而不是仅仅代码更改。
<br>
## 路线图
- **近期** — 将 W&B 运行转换为主张/证据适配器，以便 MCP 审计工具可以直接将它们的发现交给推理引擎，而不是需要手工构建 `Claim`/`EvidenceItem` 对象。
- **v2** — MCP 层的 MLflow 后端、版本化 API 兼容性矩阵、第一个来自真实项目的公开案例研究。
- **v3** — RL 特定病理信号、适当的种子间统计测试、Optuna/Ray Tune 扫描支持、对外部 `audit_*` 和推理规则贡献开放。
<br>
## 引用此项目
如果 `experiment-audit` 对您的研究或工作流程有帮助，请给予引用或链接：
```bibtex
@software{experiment_audit,
author = {Sree Dharshan G J},
title = {experiment-audit: 机器学习实验的科学研究推理引擎},
year = {2026},
url = {https://github.com/SreeDharshan-GJ/experiment-audit}
}
```
<br>
## 作者
由 **Sree Dharshan G J** 构建和维护。
[](https://github.com/SreeDharshan-GJ)
如果这个项目对您有帮助，仓库上加个星标是最容易的支持方式，也能帮助其他人发现它。
<br>
## 许可证
MIT — 参见 [`LICENSE`](LICENSE)。
