calma

# Calma [](https://github.com/rikhinkavuru/calma/actions/workflows/calma-test-all.yml) [](LICENSE) [](https://www.python.org/) [-success.svg)](pyproject.toml) [](https://calma1.vercel.app/) **AI 生成结果的自动防护栏：Calma 会重新运行您的智能代理的工作，重新计算它报告的数字，并在它们上线前阻止错误的结果。** <p align="center"> <img src="docs/demo.gif" alt="Calma 重新运行一个实际的膨胀回测并将其修正为 -32%" width="760"> <br><em>一个实际的过拟合回测声称 +14,698%。 Calma 重新运行它并重新计算出 -32%。 输入 <code>make demo</code> 观看。</em> </p> > **其他人只读取差异或信任分数。 Calma 重新运行工作并重新计算数字** - 从原始输出文件，而不是您的智能代理报告的数字。 差异审查和 LLM 法官都会推理结果；Calma 重新推导它。 没有分数可以操纵。 Calma 是一个开源的验证器，用于重要的数字。 将其指向一个结果 - 一个回测的夏普比率，一个模型的准确率，一个“2.3 倍更快”的基准，一个清理的数据集，一个 LLM 评估 - 然后它会在一个网络隔离的沙盒中**重新运行代码，重新计算原始输出文件中的指标（而非报告的数字），并在校准的容差范围内将其与声明进行比较**。 裁决来自一个单独的确定性函数，而不是语言模型。 如果数字是真实的，Calma 会用签名、重放证明确认它。 如果不是，Calma 会破坏它并准确显示哪里出了问题。 > 裁决由确定性代码计算，而不是模型 - 所以它是一个防护栏，你无法通过它来获得优待，即使在检查自己的智能代理的工作时。 Calma 重新推导每一个标签，字节对字节，因此无法伪造一个印章，即使是 Calma 自己。 **默认情况下，它是零触摸 - 您无需输入任何内容。** 作为 Claude Code 钩子（或 Cursor/Codex 中的 MCP 工具）安装，Calma 会自动验证您的智能代理计算的数字**在您看到它们之前**，并阻止错误的结果，以免它们被报告为事实： ``` # 智能代理完成任务，即将报告一个数字 - Stop 钩子自动触发： ⓧ Calma 捕获一个数字：驳斥 - 声称夏普比率为 2.6，代码重新计算为 0.4 智能代理现在必须报告诚实的 0.4 并诊断原因，而不是膨胀的 2.6 ``` 或者显式运行 - 从 CLI、CI 或 PR 检查： ``` $ calma verify ./my-backtest "夏普比率 2.6" 驳斥 - 置信度 0.81 声称 2.6 → 代码重新计算 0.4，超过 runs/returns.csv 在 seatbelt-verified 隔离下重新执行，受控到比特 修复：头条使用 252 天年化率计算每周收益；用正确的方法重新计算 重放：calma replay ./my-backtest/.calma/run # 离线重新推导此裁决，字节对字节 ``` --- ## 目录 - [此仓库中有什么](#此仓库中有什么) - [为什么重新计算](#为什么重新计算) - [它是如何工作的](#它是如何工作的) - 裁决 · 有效性层 · 广度 · 跨引擎 · 隔离 - [表面 - 引擎无处不在](#表面-引擎无处不在) - [托管 API 和仪表板](#托管-API-和仪表板) - [基准](#基准) - [快速入门](#快速入门) - [架构和设计属性](#架构和设计属性) - [限制](#限制) - [开发](#开发) - [状态和文档](#状态和文档) · [许可证](#许可证) --- ## 此仓库中有什么 一个确定性引擎和围绕它的表面： - **引擎 + `calma` CLI/技能** - `.claude/skills/calma/`（纯标准库）和可安装的 `src/calma` 外观。 - **网站 + 托管控制台** - 一个 Next.js 应用程序（`web/`），提供营销网站和登录的 `/dashboard` 产品 UI，部署在 [calma1.vercel.app](https://calma1.vercel.app/)。 - **控制平面 API** - `control_plane/`（FastAPI）+ `api/`（Vercel Python 入口）支持控制台的验证、租户和 API 密钥。 - **传输** - MCP 服务器（`mcp/`）、PR 审查机器人（`pr/`）和托管 GitHub 应用程序（`github_app/`）。 - **基准** - `benchmark/`，可复制的 117 个案例头部对比语料库。 --- ## 为什么 每个仪表板、论文和推介报告都会报告一个数字。几乎没有一个可以独立检查，而无需信任生产该数字的人。 AI 智能代理使情况更加恶化：它们现在会生成回测、评估和“测试通过”- 而且它们在规模上自信地错误。昂贵的失败（团队发布一个模型，该模型泄露了其测试集；一个基金分配在一个膨胀的夏普比率上）来自一个**技术上可复制但无效的数字**。 Calma 围绕着几乎没有人做的单一行为构建：**从原始输出重新计算声称的数字，并单独检查结果是否健全。** 这是两个不同的问题，Calma 会回答这两个问题。 **为什么重新计算，而不是读取差异或信任分数？** 因为分数是可能被操纵的东西。 2026 年，加州大学伯克利分校的一个团队构建了一个智能代理，该代理在六个主要的代理基准上得分 **~100% ** - SWE-bench、WebArena、GAIA - **无需解决任何任务**：在 SWE-bench 上，它丢弃了一个 `conftest.py`，使评分器报告每个测试都通过；在 WebArena 上，它直接从 `file://` URL 读取黄金答案（[Wang et al., 2026](https://www.rdworldonline.com/how-a-berkeley-team-broke-8-major-ai-benchmarks-six-of-them-hit-100-without-solving-a-single-task/)）。分数是完美的；工作从未完成。读取差异无法检测到这一点，询问模型结果是否**看起来**正确也无法检测 - 在 **Calma 的头部对比基准**上，LLM 法官 **无声地确认了 14 个错误数字**，仅捕获了约 82% 的情况，而信任报告的数字捕获了 **0 of 77**。 Calma 重新执行工作并从原始输出文件重新计算数字，因此没有分数可以操纵。 --- ## 它是如何工作的 ``` 构件 + 声明 │ ▼ ┌─────────┐ 草稿或加载 verify.yaml 合同（如何运行，绑定什么） │ 合同 │ └────┬────┘ ▼ ┌─────────┐ 在网络隔离的沙盒中重新执行入口点（Seatbelt / bubblewrap / │ 运行 │ Docker / 远程 Firecracker microVM），重新发出原始输出文件。 └────┬────┘ 植入的秘密读取和网络连接必须失败，由沙盒内的自测试证明。 ▼ ┌─────────┐ 使用 628 个 SOTA 配方之一从原始文件重新计算头条指标（Python / R / Julia / C++ / Rust，作为黑盒运行）- 绝不是报告的数字。 │ 重新计算│ └────┬────┘ ▼ ┌─────────┐ 在校准的容差范围内对比重新计算和声明（BLAS/减少订单噪声是一个 │ 裁决 │ 考虑因素，而不是驳斥），然后运行有效性层，然后导出一个确定性的标签。 └────┬────┘ ▼ ┌─────────┐ 一个哈希链账本 + 签名、离线可验证的证明（DSSE + OpenSSH │ 证明 │ SSHSIG，RFC-3161 时间戳，可选 Sigstore/Rekor 透明度日志）。 └─────────┘ ``` ### 裁决是确定性和不可操纵的 一个总的纯函数（`verdict.py`) 将一个完全指定的输入向量映射到一个标签。它被**两个**发射器和门导入，后者按字节重新导出每个标签 - 因此手编辑或模型撰写的裁决不能通过。 | 裁决 | 含义 | |---|---| | **确认** | 数字再现并在校准预算内与声明匹配 | | **确认-有保留** | 它成立，但比声称的更窄（例如，仅合理绑定，或跨堆栈数字噪声） | | **驳斥** | 代码重新计算一个实质上不同的数字 - 受到保护（独立绑定，控制的确定性，声明在 CI 外） | | **无效** | 数字**再现**，但结果无效（泄漏/过拟合/幸存者偏差/污染） | | **无法确认** | 没有足够的结构/确定性/隔离来决定 - 总是带有具体的`修复：`和结构化的`needs：`（确切需要提供以解决它） | | **混合** | 多个声明，至少有一个损坏 | 默认为保守：缺少信息会降低为 **无法确认**，而非意外 **确认** 或 **驳斥**。 ### 有效性层 - 13 个家族 再现性（数字再现）*不是* 有效性（结果是健全的）。 Calma 配备了一个真正的集成有效性层 - 纯标准库，比特稳定，每个检测器仅**降低**裁决，并且`INVALIDATED`仅在范围守护（当声明积极断言数据违反的干净属性时）触发： | 家族 | 捕获 | |---|---| | **泄漏** | 行/ID/时间提前/目标泄漏 + 泄漏校正的重新运行 | | **过拟合** | 降低的夏普比率（Bailey–López de Prado）+ PBO via CSCV + 降低的 **AUC** 选择过拟合的削减；N 从不被猜测 | | **执行现实性** | 费用/滑点/借款/融资 + Almgren √ 市场影响 + 净摩擦重新运行 + 容量 | | **污染** | 评估语料库中的确切评估（sha256）+ 近似重复的 MinHash/LSH | | **回测健全性** | 省略成本（净额售为净额），挑选窗口，幸存者宇宙 | | **时间点/展望** | 时间点成员资格/属性 + 可用性日期检查 + +1 个周期滞后探针 | | **数据窥探** | 研究范围内的多重测试 - Bonferroni / Holm / BHY + Harvey-Liu-Zhu 夏普比率削减（t > 3.0） | | **制度/行走前进** | 样本内 → 样本外边缘崩溃，并由两个样本的 KS 制度转移证实 | | **模型过程泄漏** | 在训练+测试上拟合特征，验证重用/测试上的选择 | | **分布转移** | 协变量/目标转移训练和测试之间（KS + PSI） | | **时代禁令/净化 CV **（锦标赛）| 训练↔验证窗口太接近目标的未来水平（Numerai 的公开 8 周期/20 天，16 周期/60 天净化；López de Prado 净化 + 禁令形式）+领先时代 CORR 升水 | | **风险模拟假设**（混沌/ Gauntlet）*| DeFi 风险模拟的每个块的不变性：每个账户/块的清算 ≤1，标记的 VaR 为 p99 而不是损失向量的 p95，校准窗口展望，关闭因子绑定 | | **统计合理性**（薄输入）* | 触发**无声明块**，仅 SOFT（→ CAVEATS，绝不 INVALIDATED）：不合理的夏普比率，过于平滑（序列相关性）曲线，和**制度漂移**的非平稳性嗅觉来自收益系列；另外**未声明分割泄漏**的嗅觉（推断的训练/测试分割 + 真实行重叠）和**训练/测试损失差距**的过拟合嗅觉来自 ML 神器 - 每个都命名确切的声明块 | | **两个幸存者检查** | 它们中的每一个都幸存于其他门槃 | ### 两个检查项幸存于其他所有门槃 一个数字可以通过您已经运行的所有检查 - dbt 测试，Pandera 模式，snapshot diffs，LLM 评估工具包 - 并且仍然是错误的，因为所有这些都确认一个数字在**内部一致**，而不是**正确**。 Calma 的两个捕获项专门针对这个盲点，并且两个触发器都基于一个**完美重现**的数字： - **平凡基线边缘**（差异时间守护，不是上述有效性家族之一）。 模型卡报告 92% 的准确率并重新计算到 92% - 但如果 92% 的行属于一个类别，则预测每个类别始终得分相同。 标题是真实的，可重复的，但毫无价值。 Calma 重新计算声明旁边的平凡基线并标记一个不击败它的数字。 - **评估污染**（上述 **污染** 家族）。 “零样本留出”基准得分为 0.92 并重新计算为 0.92 - 但 Calma 将评估项目与声明的语料库进行哈希（确切的 sha256 + 近似的 MinHash/LSH），并发现 40% 已经在预训练中，因此 **INVALIDATED**。 数字是真实的，但留出的框架不是。 整个评估工具类别都不检查这些。 ### 广度 `calma recipes` → **16 个家族中的 628 个指标**，每个都针对字节可复制的参考向量验证：交易（Sharpe/Sortino/Calmar/VaR/CVaR），分类（accuracy/AUC/F1/log-loss/ECE/Brier），回归（RMSE/MAE/R²），分析（sum/mean/percentile/groupby/join-loss），工程（“2.3 倍更快”/p50–p99/throughput/coverage），检索和 LLM 评估（recall@k/NDCG/MRR/pass@k/exact-match），统计（p-value/CI/effect-size），衍生品（Black-Scholes + Greeks/IV），信用，利率，基金&LP（TVPI/DPI/KS-PME），预测（MAPE/sMAPE/MASE/pinball），等等。 黑盒 **Python, R, Julia, C++, Rust**。 ### 跨引擎正确性 2026 年的一项研究发现 **没有回测引擎发布跨引擎正确性** - 每个单独的引擎数字都带有**不可量化实现不确定性**（累积顺序，年化率，一个错误 - 而没有人检查指标与第二个实现）。 `calma verify --cross-engine` 使用 **第二个独立编写的内核**（不同的算法和减少顺序，从主要 - 例如连续产品 vs. 树对等 Welford 方差）并在**校准的容差范围内**对比两个 **差异**。 协议是附加的 - 它永远不会改变裁决，并报告主机可以使用更强大的第二个引擎。 检查是 **添加的** - 它永远不会改变裁决，并报告主机可以使用的外部堆栈（R / Julia / Node）。 ### AI 边缘（围绕确定性核心的智能） LLM仅在无法伪造裁决的情况下使用：**提取**来自杂乱文物的声明，**草拟**针对没有交付验证合同的仓库（启发式算法总是处理），**合成**通过CEGIS（草稿 → 接受 → 反例 → 重新草拟；数据有最终决定权）的新配方，以及**自动修复**损坏的结果，然后使用反测试黑客门重新验证。`edges/`包与纯stdlib核心隔离。 --- ## 主机 API 和仪表板 除了开源引擎外，该仓库还包含**托管产品** — 面向输出为数字的团队的验证即服务。引擎保持不变；它被封装在一个多租户API和登录的UI中。 - **控制平面 API** — `control_plane/`（FastAPI），部署为Vercel Python / Fluid-Compute函数（`api/index.py` + `api.vercel.json`），由 **Postgres** （Supabase，每个租户的行级安全）和 **Cloudflare R2** 对象存储支持。端点：`POST /v1/verifications`（提交捆绑包），`GET /v1/verifications/{id}[/result|/proof]`，`GET /v1/verifications`（列表），`POST /v1/uploads`（预签名R2 PUT），`POST|GET|DELETE /v1/keys`（API密钥管理），`POST /internal/provision`（第一方租户配置）。Bearer **API密钥** 认证（`calma_sk_<env>_…`，SHA-256哈希，恒定时间验证），幂等键和不可变哈希链式 `audit_log`。 - **执行** — 提交时，API将R2中的捆绑包和数据分阶段到工作目录，并以子进程运行 **相同的引擎** （`calma verify --json`），然后保留运行 + 裁决 + 神器。设置 `CALMA_EXEC_ISOLATION=e2b` 以在网络拒绝的 **E2B Firecracker microVM** 中执行不受信任的代码（主机在加盖层之前自行证明出口被拒绝）。重新计算总是在主机端进行，在沙箱外。 - **仪表板** （`web/app/dashboard/`，`web/lib/`）— 一个登录的控制台，位于 **WorkOS AuthKit** 后面：提交验证，列出和检查裁决（声称与重新计算，有效性结果，执行层，证据捆绑包），以及创建/撤销API密钥。仪表板与API进行第一方通信，使用从未到达浏览器的服务令牌（`web/lib/calma.ts` 为 `server-only`）。参见 [`docs/DASHBOARD.md`](docs/DASHBOARD.md) 和 [`control_plane/README.md`](control_plane/README.md)。 端到端路径是真实且经过测试的（注册 → 密钥 → 上传 → 提交 → 执行 → 裁决 → 证明）。**尚未连接：** 工作队列（当前执行为同步/内联），使用 **计费/计量** （Stripe — 模式列存在，逻辑不存在），托管 **裁决签名** （本地CLI `calma seal` 签名；托管路径暂时存储未签名的证据JSON），以及SSO/SCIM。 ## 基准测试 `benchmark/` 提供了117个案例的语料库（合成 + 外部UCI/sklearn + 真实世界），在两个轴上评分（NASEM 2019）： - **可重复性** — 标题数字是否重新计算？Calma **100%** 捕获（77/77）/ 0个假确认 / 0个假警报，而LLM作为裁判 **约82%** （63/77，14个沉默假确认和12个假警报）和信任数字 **0%** （0/77）。 - **有效性** — 单元格重新生成但结果无效：Calma **100%** （它使标记的泄漏/过拟合/幸存者/位移案例无效）而仅重新计算方法的 **0%** 。 第四个 `agent-with-exec` 臂（具有 `run_python` 工具的前沿代理，沙箱隔离相同）衡量了代理可以执行时的诚实差异：裁决不稳定性（Calma通过构造为0），传递^k一致性曲线，与Calma的协议，成本和有效性盲点 — 跨≥2个模型系列，每个计数运行网络隔离，每个记录发布。参见 [`benchmark/README.md`](benchmark/README.md)。 --- ## 快速入门 ```bash # 安装CLI（纯stdlib；无运行时依赖）— 参见docs/install.md获取所有路径 make install # 将`calma`符号链接到PATH — 无pip，无venv # 或从源代码： pip install "git+https://github.com/rikhinkavuru/calma" （+[parquet]用于.parquet） # 或作为Claude Code插件（零触摸钩子+MCP）： /plugin marketplace add rikhinkavuru/calma # 验证结果目录（自动草拟合同，或读取提交的verify.yaml） calma verify ./result "accuracy 0.94" --metric accuracy --json # 裁决以一行“未验证”的摘要结束；添加--why获取完整的范围列表 # 被驳斥？让LLM提出修复 — Calma重新验证修补代码，仅当重新计算将裁决翻转为干净时接受（除非您传递--apply，否则您的文件不会被触及） calma repair ./result/.calma/run # 需要edges依赖和API密钥 # 查看目录，获取配方建议，离线重放密封的裁决 calma recipes calma suggest ./result calma replay ./result/.calma/run # 证明沙箱实际上隔离了此主机 python3 .claude/skills/calma/scripts/run_hermetic.py doctor # 观察真实的膨胀回测被捕获，零设置 make demo ``` `verify.yaml` 绑定了 *如何* 验证（入口点，列绑定，约定和任何有效性块 — `split` / `trials` / `frictions` / `corpus` / `universe` / `study` / `windows` / `pipeline`）。大多数有效性检查仅在其块被声明时激活 — Calma永远不会猜测可能翻转裁决的范围；例外是薄输入合理性家族，它仅根据系列进行标记。不要手动编写它：`calma draft <repo>` 将Calma指向一个凌乱的仓库，并写入一个可运行的 `verify.yaml`，自动检测安全块（split，trials）并 *建议* 其余部分。 ### 在本地运行网站 ```bash cd web npm install npm run dev # http://localhost:3000 （营销网站 + /dashboard控制台） ``` 控制台还需要控制平面API和WorkOS环境 — 参见 [`docs/DASHBOARD.md`](docs/DASHBOARD.md) 和 [`control_plane/README.md`](control_plane/README.md)。 --- ## 架构和设计属性 ``` .claude/skills/calma/scripts/ 确定性引擎（纯stdlib）：裁决 · 账本 · 比较 · 重新计算 · 数值 · 有效性家族 · run_hermetic src/calma/ 薄pip-installable facade（一个引擎的客户端，而不是一个分支） edges/ AI边缘（提取/草拟/合成/修复）— 与核心隔离 mcp/ 主机无关MCP服务器（传输） pr/ · github_app/ PR审查机器人（CI）+托管GitHub应用（传输） web/ Next.js网站（营销）+登录/仪表板控制台 control_plane/ · api/ FastAPI控制平面及其Vercel Python入口（验证/租户/密钥） registry/ 通过站点提供的哈希链式公共捕获注册表 benchmark/ 117案例语料库 + 4臂比较 +评分 ``` - **裁决是一个函数**，在门口按字节重新派生 — 不可玩。 - **纯stdlib；默认离线 — 您的代码和数据永远不会离开您的机器。** 对“我们在哪里处理数据？”的诚实回答是 *“在您的机器上，网络关闭。”* （您显式打开的可选层 — 远程微VM用于不受信任的代码，RFC-3161时间戳，Rekor日志 — 进行网络调用，账本记录确切的调用）。 - **每个传输都是隔离的** — `mcp/`，`pr/`，`github_app/`不导入裁决核心；有效性检测器不导入模型。 - **已测试：** 71个核心套件 / 0个失败（纯stdlib）+ MCP + PR传输套件；一个命令运行所有三个 — `make test-all`；628个配方对抗参考向量。 ## 限制 在依赖裁决之前阅读这些内容。 - **可重复性与正确性并非同一概念。** `CONFIRMED`裁决意味着标题数字 **从原始输出重新派生，并在声明的范围内内部健全** — 它 *不是* 现实世界正确性、未来性能、模型健全性或投资价值的保证，并且它 **不是投资建议** 。一个程序确定性地制造自己的原始输出将会重复；calma检查数字与输出，而不是输出与现实。 - **有效性深度随您声明的内容缩放。** 泄漏/过拟合/幸存者/展望/制度/时代禁令/风险模拟家族在您将calma指向split、trials、frictions、universe、embargo或simulation_assumptions时运行。薄输入结果如果没有声明任何内容，则仅获得 *软* 合理性嗅探层（它将数字降级为 `CONFIRMED-WITH-CAVEATS`，而非 `INVALIDATED`）。缺少信息会降低到 `CAN'T-CONFIRM`，而非意外的 `CONFIRMED`/`REFUTED`。 - **覆盖范围是诚实的，而不是总的。** 一些假设无法从一个输出日志中检查（例如风险模拟的n中之一的非串通）；calma将其报告为超出范围，而不是断言它们。每个裁决的账本都列出了确切检查了什么和什么没有检查。在配方方面， **597/628个配方（95.1%）是独立验证的（Tier-1）** — 针对实时框架数字、官方numerai-tools或从numpy/scipy/sklearn生成的冻结向量 — 使用 `make eval` 门控，不会让该比率下降（`benchmark/coverage_report.py`）；其余31个被诚实地列出，而不是隐藏。 - **隔离因主机而异。** 在可用时使用经过验证的沙箱；在其他主机上，重新执行以降低隔离，并 **账本记录实际实现的层级** 。相应地处理第三方代码。 ## 开发 核心是纯Python标准库 — 不需要虚拟环境来运行或测试它。 ```bash make test # 核心套件（纯stdlib）：71个套件，0个失败 make test-all # 每个层级：核心 + MCP + PR传输（如果缺少，则启动~/.calma venvs） make eval # 持续评估网络：核心套件 + 框架黄金向量 + 重新计算基线 + 确定性 make demo # 观察真实的膨胀回测被捕获（离线，零设置） make benchmark # 合成快速跟踪（完整117案例运行在benchmark/README.md → “Reproduce”） ``` 引擎位于 `.claude/skills/calma/scripts/`，并且不导入标准库以外的任何内容。智能层（`edges/`）和传输（`mcp/`，`pr/`，`github_app/`）与之 **隔离** — 如果它们导入裁决核心，则测试失败，而有效性检测器不导入模型。在 **系统** `python3` 下运行核心套件（在边缘venv中运行会产生假失败）。参见 [`docs/extending.md`](docs/extending.md) 以添加配方或有效性家族。 ## 状态和文档 `v0.13.0`。真实且经过测试。参见 [`CHANGELOG.md`](CHANGELOG.md)， [安装指南](docs/install.md)， [扩展指南](docs/extending.md)， [支持的框架](docs/frameworks.md)， [PR机器人采用指南](docs/pr-bot.md)， [GitHub应用指南](github_app/README.md)， [控制台/身份验证指南](docs/DASHBOARD.md)，以及 [安全策略](SECURITY.md)。 ## 许可证 MIT。Calma在运行时是纯Python标准库 — 没有版权暴露，没有第三方供应链。