entropy

entropy-mcp

Entropy 为 Agent 提供它们自身无法生成的随机性，以及证明它们没有操纵随机性的证据。

证据

大模型无法生成统计上可靠的随机性。这是经过测量的事实，并非推测：

• arXiv:2601.05414 — 测试了 11 个前沿模型和 15 种分布：批处理模式下的中位通过率为 7%；无状态模式下，11 个模型中有 10 个对任何分布都未通过。
• arXiv:2604.06543 — 知行差距：模型能够描述正确的采样方法，却仍无法正确执行。要求模型生成自己的种子，会重现同样的偏差。
• arXiv:2606.06622 — UnpredictaBench：在本应随机的情况下，模型的可预测性有可测量的表现。

无状态场景

Agent 恰好运行在模型最容易失败的场景中：独立、无状态的调用，且不记得先前的抽样。Agent 每次根据自身权重回答“选一个随机数”，得到的都是来自有偏且可预测来源的一次抽样。Entropy 将抽样从模型中移出，交由 OS CSPRNG 完成；提交-揭示链则证明实际发生的抽样就是所报告的抽样。

安装

pip install entropy-mcp          # stdio core + stamp-mcp dependency
pip install entropy-mcp[http]    # adds the aiohttp HTTP transport

快速入门

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"commitment","arguments":{
  "operation":"draw",
  "draw_spec":{"operation":"shuffle","params":{"items":["alice","bob","carol","dave"]}},
  "description":"who goes first"}}}

一次调用会返回打乱后的列表，以及一条提交记录、一条揭示记录和一个验证区块——第三方可通过 commitment operation:"verify" 检查完整链路。

命令参考

共有四种工具。operation 用于选择原语；params 用于传递参数；seed 可让任意抽样结果可复现。

工具	操作
random	bytes（CSPRNG，hex/base64） · int（通过拒绝采样实现无偏的 [min,max]） · shuffle（Fisher-Yates + 排列） · choose（加权/不加权、有放回/无放回） · sample（均匀、正态、对数正态、指数、三角、beta） · constrained（按属性独立采样 + 卡方符合性证明）
commitment	commit（对种子进行哈希、绑定抽样规范并证明） · reveal（验证种子、重新执行并证明结果） · draw（一次调用完成提交 + 执行 + 揭示） · verify（纯第三方验证，不依赖本地状态） · list（本地提交日志）
test	统计测试组：频率、卡方、游程、最长游程、串行、Shannon、KS、间隔
explore	Bandit 选择：epsilon_greedy、thompson、ucb1（无状态）

给定输入和种子时，所有带种子的命令都是确定性的——在不同进程、机器和 Python 版本之间都能得到逐字节相同的结果。只有原始 OS 熵路径是非确定性的，并且会明确说明。

提交-揭示的工作原理

1. commit 生成（或接收）一个 32 字节种子，只存储 sha256(seed)，通过规范化哈希将其绑定到抽样规范，使用 Stamp 的 NTP 添加时间戳，可选择锚定到某个 drand 轮次，并为整条记录提供证明。种子会交给你，绝不会存储在服务端。
2. reveal 接收你传回的种子，验证其哈希是否与已提交的 seed_hash 一致，以确定性方式重新执行抽样，并为结果提供证明。
3. verify_chain 独立于任何服务端状态执行检查：

检查项	证明内容
seed_produces_commitment_hash	揭示的种子就是提交时使用的种子
commitment_attestation_valid	提交记录完整且已获得证明
reveal_attestation_valid	揭示记录完整且已获得证明
commitment_precedes_reveal	提交发生在揭示之前
outcome_reproducible	所报告的结果确实由该种子生成
params_hash_matches	抽样规范在提交后未被篡改
beacon_anchor_valid	提交发生在 drand 轮次发布之前（使用锚定时）

本工具不是什么

• 不是统计软件包——摘要块和测试套件只是便捷功能，不是分析套件。
• 不是仿真引擎——不支持 Monte Carlo、敏感性分析或拟合。
• 不是随机数信标——drand 锚定是可选的强化措施，并非熵源。
• 未获 NIST 认证——测试套件的设计参考了 SP 800-22，并遵循其理念。

配置

环境变量	默认值	用途
ENTROPY_COMMITMENT_LOG	~/.entropy/commitments.jsonl	承诺日志路径（权限为 0600，最多存储 10k 条记录）
ENTROPY_STAMP_URL	https://stamp-mcp.terradev.cloud	远程 Stamp 端点（优先使用本地 stamp_mcp 导入）
ENTROPY_BEACON_URL	https://api.drand.sh	drand API 基础地址
ENTROPY_HOST / ENTROPY_PORT	127.0.0.1 / 8001	HTTP 传输绑定地址

威胁模型

请参阅 THREAT_MODEL.md。坦诚地说：Entropy 可以证明抽取结果未被篡改，但无法证明某次抽取未被丢弃。

许可证

Apache 2.0。