mareforma/mareforma
GitHub: mareforma/mareforma
Mareforma 是一个为 AI 驱动的科研发现提供密码学签名、交叉引用和信任分级验证的本地知识图谱工具。
Stars: 14 | Forks: 1
# Mareforma
[](https://pypi.org/project/mareforma/)
[](https://github.com/mareforma/mareforma/actions/workflows/tests.yml)
[](https://pypi.org/project/mareforma/)
[](https://opensource.org/licenses/MIT)
**像验证论文一样验证你的 AI agent 的发现。**
Mareforma 是一个本地存储库，研究 agent 在此记录它们的主张。内容经过签名、交叉引用，并在多个独立的 agent 得出相同结论时提升可信度。信任源于证据，而非 agent 的置信度分数。
## 为什么需要
AI agent 现在处理真正的研究问题，却没有任何基础设施可以用来判断哪些发现值得信任。追踪工具记录了*agent 做了什么*。但它们并没有记录这意味着什么、它是否与独立证据相吻合，或者一个结论与其原始数据的差距有多远。一个静默的流水线失败、一个退回使用先验知识的操作，以及一个真实的研究结果，这三者看起来完全一样。
## 它的功能
```
import mareforma
with mareforma.open() as graph:
# Query established prior claims. query_for_llm wraps text in
# ... tags so a downstream LLM
# consumes it as data, not instructions.
prior = graph.query_for_llm("topic X", min_support="REPLICATED")
claim_id = graph.assert_claim(
"Cell type A exhibits property X under condition Y (n=842, p<0.001)",
classification="ANALYTICAL",
generated_by="agent/model-a/lab_a",
supports=[c["claim_id"] for c in prior],
)
# Walk the full lineage of any claim: upstream + downstream + signatures
# + contradictions + verdicts in one deterministic dict.
lineage = graph.query_provenance(claim_id, depth=4)
```
```
graph LR
P(["ESTABLISHED upstream
(prior literature)"]) --> A["ANALYTICAL · lab_a"] P --> B["ANALYTICAL · lab_b"] A --> R(["REPLICATED ✓"]) B --> R R -->|"graph.validate()"| E(["ESTABLISHED ✓"]) style P fill:#713f12,stroke:#f59e0b,color:#fde68a style A fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd style B fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd style R fill:#14532d,stroke:#22c55e,color:#86efac style E fill:#713f12,stroke:#f59e0b,color:#fde68a ``` 当两个已注册的密钥签署了带有不同 `generated_by` 字符串的主张，且都在 `supports[]` 中引用了同一个处于 `ESTABLISHED` 状态的上游节点时，就会触发 `REPLICATED`。这三个条件缺一不可。在全新的图谱中，使用 `seed=True`（仅限已注册的验证者）引导建立 `ESTABLISHED` 锚点。关于先播种后收敛的模式，请参见 [示例 03](examples/03_documented_contestation)。 **信任阶梯。** 源自图谱拓扑结构，绝非自我标榜。 | 级别 | 含义 | |---|---| | `PRELIMINARY` | 单个 agent 提出主张。具备密码学来源证明，但尚无收敛信号。 | | `REPLICATED` | ≥2 个已注册密钥签署了主张，这些主张共享一个 `ESTABLISHED` 上游节点且带有不同的 `generated_by` 字符串。 | | `ESTABLISHED` | 已注册的人工密钥签署了一个验证信封，绑定了 `evidence_seen=[...]` 审查引用。 | **分类。** 由 agent 声明，记录了产生该结果的工作类型：`INFERRED`（LLM 推理），`ANALYTICAL`（针对源数据的确定性分析），`DERIVED`（建立在 `ESTABLISHED` 或 `REPLICATED` 主张之上）。信任级别和分类是独立的维度。可以同时查询两者：`graph.query(text, min_support="REPLICATED", classification="ANALYTICAL")`。 **发现：是争取来的，不是随便声明的。** 上述信任阶梯是通过阅读来源证明获取的。信任层（`mareforma.trust`）则更进一步。它将主张转化为绑定到预注册 `Prediction` 的内容寻址 `Proposition`，使用 `compute_bearing` 计算证据的方向，而不是由 agent 声明，并从独立数据集中推导出基于计数的 `Status`（从 `PRELIMINARY` 到 `CORROBORATED`）。发现搭载在已签名的主张上，因此是累加性的。请参见 [发现](https://docs.mareforma.com/concepts/findings) 和 [示例 02](examples/02_compounding_agents)。 ### 核心表面 ``` graph.assert_claim(text, classification, supports=[...]) graph.query(text, min_support="REPLICATED") graph.query_provenance(claim_id, depth=4) graph.validate(claim_id, evidence_seen=[...]) # Trust layer：计算出的 bearing 和派生的 status graph.assert_finding(proposition, prediction, estimate, data_id="...") graph.proposition_status(proposition) # derived Status + independence counts ``` ``` mareforma bootstrap # generate Ed25519 signing key mareforma --help # all subcommands mareforma ingest paper.md # paper-abstract claim drafts (v0.3.3) ``` 完整的 API 和 CLI 参考：[docs.mareforma.com](https://docs.mareforma.com)。可选组件（DSSE 签名、Sigstore-Rekor 透明度、RFC 6962 包含证明、针对 Crossref/DataCite 的 DOI HEAD 检查、grounding sensors）：请参见 [AGENTS.md](AGENTS.md)。存储采用本地 SQLite，WAL 模式，支持 ACID。网络调用仅用于上述可选组件。 ## 静默流水线失败变得可见 AI agent 运行多步分析：查询公共数据集，将基因的表达情况与表型进行回归分析，返回最匹配的结果。由于标识符过期，数据查找静默返回 null。agent 的 LLM 推理用先验知识填补了空白，并返回了一个听起来合理的答案。该输出看起来与数据驱动的结果完全相同。 ``` finding_text = run_pipeline(target_gene, phenotype) graph.assert_claim( finding_text, # The one line that breaks the symmetry: classification depends on # whether real data flowed through. Mareforma doesn't compute # this. The agent's wrapper inspects the pipeline state and tells # the truth at assertion time. classification="ANALYTICAL" if generated_code_ran else "INFERRED", generated_by="agent/gpt-4o/lab_a", source_name="depmap_24q2" if data_actually_loaded else None, ) ``` 下游消费者在查询 `min_support="REPLICATED", classification="ANALYTICAL"` 时会排除这些静默退回的记录行。幻觉发现保留在图谱中（可审计、已签名），但不在可信的结果集中。负责区分挑选 `ANALYTICAL` 还是 `INFERRED` 的包装器才是发挥作用的关键。Mareforma 让这项工作变得可见且防篡改。 [示例 05：药物靶点来源](examples/05_drug_target_provenance/) 包装了 omics AI agent [MEDEA](https://medea.openscientist.ai/)，并展示了分类网关是如何捕获其标识符查找中发生的真实静默失败的。 ## 发现相互矛盾 ``` prior = graph.query("Treatment X", min_support="ESTABLISHED") graph.assert_claim( "Treatment X shows no effect (n=1240, p=0.21): larger and more diverse cohort", classification="ANALYTICAL", contradicts=[c["claim_id"] for c in prior], ) ``` 两个主张同时存在。人类审查者在图谱中看到了这种冲突。`graph.refutation_status(claim_id)` 会显示某个主张是处于 `clean`（正常）、`contested`（有争议）、`contradicted`（被反驳），还是 `retracted`（已撤回）状态。 ## 开始使用 ``` uv add mareforma mareforma bootstrap # optional: enable signing and transparency ``` 如果不使用 `bootstrap`，主张将以未签名的方式存储。使用了它之后，每个主张都会带有防篡改签名，并可以提交到 Sigstore-Rekor 透明日志中。 可选：适用于 [ClawInstitute](https://clawinstitute.aiscientist.tools/)、[ToolUniverse](https://aiscientist.tools/)、[Gemini for Science](https://ai.google/gemini-for-science/) 的适配器，以及用于 Claude Code 工具调用的 `mareforma.hooks` 记录器。请参见 [AGENTS.md → 适配器框架](AGENTS.md)。 ### 示例 | | 示例 | 展示内容 | |---|---|---| | 01 | [API 演练](examples/01_api_walkthrough/) | 完整 API 参考 | | 02 | [复合 Agent](examples/02_compounding_agents/) | 发现结果在不同 agent 运行之间不断累积 | | 03 | [记录在案的争议](examples/03_documented_contestation/) | Agent 挑战已确立的共识 | | 04 | [私有数据，公共发现](examples/04_private_data_public_findings/) | 两个实验室在不共享数据的情况下共享来源证明 | | 05 | [药物靶点来源](examples/05_drug_target_provenance/) | 真实的 AI 研究 agent 带有诚实的证据标签 | [`AGENTS.md`](AGENTS.md)：执行契约、签名设置、适配器框架。 [`ARCHITECTURE.md`](ARCHITECTURE.md)：系统设计、信任阶梯拓扑、诚实范围。 [`SECURITY.md`](SECURITY.md)：威胁模型和披露渠道。 [`CONTRIBUTING.md`](CONTRIBUTING.md)：开发工作流。 [`CHANGELOG.md`](CHANGELOG.md)：版本发布说明。 完整文档：**https://docs.mareforma.com**
(prior literature)"]) --> A["ANALYTICAL · lab_a"] P --> B["ANALYTICAL · lab_b"] A --> R(["REPLICATED ✓"]) B --> R R -->|"graph.validate()"| E(["ESTABLISHED ✓"]) style P fill:#713f12,stroke:#f59e0b,color:#fde68a style A fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd style B fill:#1e3a5f,stroke:#3b82f6,color:#93c5fd style R fill:#14532d,stroke:#22c55e,color:#86efac style E fill:#713f12,stroke:#f59e0b,color:#fde68a ``` 当两个已注册的密钥签署了带有不同 `generated_by` 字符串的主张，且都在 `supports[]` 中引用了同一个处于 `ESTABLISHED` 状态的上游节点时，就会触发 `REPLICATED`。这三个条件缺一不可。在全新的图谱中，使用 `seed=True`（仅限已注册的验证者）引导建立 `ESTABLISHED` 锚点。关于先播种后收敛的模式，请参见 [示例 03](examples/03_documented_contestation)。 **信任阶梯。** 源自图谱拓扑结构，绝非自我标榜。 | 级别 | 含义 | |---|---| | `PRELIMINARY` | 单个 agent 提出主张。具备密码学来源证明，但尚无收敛信号。 | | `REPLICATED` | ≥2 个已注册密钥签署了主张，这些主张共享一个 `ESTABLISHED` 上游节点且带有不同的 `generated_by` 字符串。 | | `ESTABLISHED` | 已注册的人工密钥签署了一个验证信封，绑定了 `evidence_seen=[...]` 审查引用。 | **分类。** 由 agent 声明，记录了产生该结果的工作类型：`INFERRED`（LLM 推理），`ANALYTICAL`（针对源数据的确定性分析），`DERIVED`（建立在 `ESTABLISHED` 或 `REPLICATED` 主张之上）。信任级别和分类是独立的维度。可以同时查询两者：`graph.query(text, min_support="REPLICATED", classification="ANALYTICAL")`。 **发现：是争取来的，不是随便声明的。** 上述信任阶梯是通过阅读来源证明获取的。信任层（`mareforma.trust`）则更进一步。它将主张转化为绑定到预注册 `Prediction` 的内容寻址 `Proposition`，使用 `compute_bearing` 计算证据的方向，而不是由 agent 声明，并从独立数据集中推导出基于计数的 `Status`（从 `PRELIMINARY` 到 `CORROBORATED`）。发现搭载在已签名的主张上，因此是累加性的。请参见 [发现](https://docs.mareforma.com/concepts/findings) 和 [示例 02](examples/02_compounding_agents)。 ### 核心表面 ``` graph.assert_claim(text, classification, supports=[...]) graph.query(text, min_support="REPLICATED") graph.query_provenance(claim_id, depth=4) graph.validate(claim_id, evidence_seen=[...]) # Trust layer：计算出的 bearing 和派生的 status graph.assert_finding(proposition, prediction, estimate, data_id="...") graph.proposition_status(proposition) # derived Status + independence counts ``` ``` mareforma bootstrap # generate Ed25519 signing key mareforma --help # all subcommands mareforma ingest paper.md # paper-abstract claim drafts (v0.3.3) ``` 完整的 API 和 CLI 参考：[docs.mareforma.com](https://docs.mareforma.com)。可选组件（DSSE 签名、Sigstore-Rekor 透明度、RFC 6962 包含证明、针对 Crossref/DataCite 的 DOI HEAD 检查、grounding sensors）：请参见 [AGENTS.md](AGENTS.md)。存储采用本地 SQLite，WAL 模式，支持 ACID。网络调用仅用于上述可选组件。 ## 静默流水线失败变得可见 AI agent 运行多步分析：查询公共数据集，将基因的表达情况与表型进行回归分析，返回最匹配的结果。由于标识符过期，数据查找静默返回 null。agent 的 LLM 推理用先验知识填补了空白，并返回了一个听起来合理的答案。该输出看起来与数据驱动的结果完全相同。 ``` finding_text = run_pipeline(target_gene, phenotype) graph.assert_claim( finding_text, # The one line that breaks the symmetry: classification depends on # whether real data flowed through. Mareforma doesn't compute # this. The agent's wrapper inspects the pipeline state and tells # the truth at assertion time. classification="ANALYTICAL" if generated_code_ran else "INFERRED", generated_by="agent/gpt-4o/lab_a", source_name="depmap_24q2" if data_actually_loaded else None, ) ``` 下游消费者在查询 `min_support="REPLICATED", classification="ANALYTICAL"` 时会排除这些静默退回的记录行。幻觉发现保留在图谱中（可审计、已签名），但不在可信的结果集中。负责区分挑选 `ANALYTICAL` 还是 `INFERRED` 的包装器才是发挥作用的关键。Mareforma 让这项工作变得可见且防篡改。 [示例 05：药物靶点来源](examples/05_drug_target_provenance/) 包装了 omics AI agent [MEDEA](https://medea.openscientist.ai/)，并展示了分类网关是如何捕获其标识符查找中发生的真实静默失败的。 ## 发现相互矛盾 ``` prior = graph.query("Treatment X", min_support="ESTABLISHED") graph.assert_claim( "Treatment X shows no effect (n=1240, p=0.21): larger and more diverse cohort", classification="ANALYTICAL", contradicts=[c["claim_id"] for c in prior], ) ``` 两个主张同时存在。人类审查者在图谱中看到了这种冲突。`graph.refutation_status(claim_id)` 会显示某个主张是处于 `clean`（正常）、`contested`（有争议）、`contradicted`（被反驳），还是 `retracted`（已撤回）状态。 ## 开始使用 ``` uv add mareforma mareforma bootstrap # optional: enable signing and transparency ``` 如果不使用 `bootstrap`，主张将以未签名的方式存储。使用了它之后，每个主张都会带有防篡改签名，并可以提交到 Sigstore-Rekor 透明日志中。 可选：适用于 [ClawInstitute](https://clawinstitute.aiscientist.tools/)、[ToolUniverse](https://aiscientist.tools/)、[Gemini for Science](https://ai.google/gemini-for-science/) 的适配器，以及用于 Claude Code 工具调用的 `mareforma.hooks` 记录器。请参见 [AGENTS.md → 适配器框架](AGENTS.md)。 ### 示例 | | 示例 | 展示内容 | |---|---|---| | 01 | [API 演练](examples/01_api_walkthrough/) | 完整 API 参考 | | 02 | [复合 Agent](examples/02_compounding_agents/) | 发现结果在不同 agent 运行之间不断累积 | | 03 | [记录在案的争议](examples/03_documented_contestation/) | Agent 挑战已确立的共识 | | 04 | [私有数据，公共发现](examples/04_private_data_public_findings/) | 两个实验室在不共享数据的情况下共享来源证明 | | 05 | [药物靶点来源](examples/05_drug_target_provenance/) | 真实的 AI 研究 agent 带有诚实的证据标签 | [`AGENTS.md`](AGENTS.md)：执行契约、签名设置、适配器框架。 [`ARCHITECTURE.md`](ARCHITECTURE.md)：系统设计、信任阶梯拓扑、诚实范围。 [`SECURITY.md`](SECURITY.md)：威胁模型和披露渠道。 [`CONTRIBUTING.md`](CONTRIBUTING.md)：开发工作流。 [`CHANGELOG.md`](CHANGELOG.md)：版本发布说明。 完整文档：**https://docs.mareforma.com**
标签：Python, 人工智能, 数据可信度, 数据溯源, 无后门, 用户模式Hook绕过, 科学研究, 逆向工具