banditkeep

banditkeep

让一群 Agent 拥有决策记忆。banditkeep 是 BanditDB 服务的小型客户端：BanditDB 是一个上下文 老虎机数据库，会针对每个活动学习在什么上下文中 哪种操作通常更有效。Agent 会询问应该选择哪个 选项，按照建议采取行动，然后报告结果是否 有效——此后所有指向同一 服务的 Agent 都能立即从这个结果中受益，无需 重新训练。

两个探索算法为活动提供支持： LinUCB，具有确定性，可通过 alpha 调节；以及 Thompson Sampling，以贝叶斯方式自然探索， 无需调节。活动还可以为成本受限的操作设置预算， 这样就能在整个周期内分配支出，而不是第一天就 耗尽预算。

配置

三个环境变量用于控制客户端：

• BANDITDB_URL（可选）——BanditDB 服务的基础 URL。默认为 http://localhost:8080。
• BANDITDB_API_KEY（可选）——设置后，会在 每个请求中以 Authorization: Bearer <key> 的形式发送。 如果服务未启用身份验证，则省略此项；不设置 本身不会导致错误。
• BANDITDB_TIMEOUT_MS（可选）——每个请求的 超时时间，单位为毫秒，通过 AbortController 强制执行。默认为 15000。（此变量 是本次重建新增的内容。）

工具

• create_campaign — 创建新的决策活动。 必须提供 campaign_id 和 arms；可选提供 features（按顺序排列的名称）或 feature_dim、 alpha、algorithm（"linucb" 或 "thompson_sampling"）、metadata、budgets 和 decay_half_life_hours。
• list_campaigns — 列出所有活跃活动，并显示 算法和 alpha；可用于在调用 get_intuition 前 查看已有内容。
• campaign_diagnostics — 检查每个选项的学习 状态：theta 范数、预测次数、奖励率 和熵健康状况。活动似乎没有学习或某个选项占据 主导地位时，可使用此工具。
• campaign_report — 业务层面的收敛 报告：活动是否已达到统计学意义上的 收敛，以及哪个选项胜出，并提供置信 区间。
• get_intuition — 针对给定的 context（由特征名称映射到数值的 对象，或数值数组）询问应选择哪个选项。可选的 eligible_arms / exclude_arms 仅缩小本次请求的选择范围。 返回选项和需要保存的 interaction_id。
• batch_get_intuition — 在一次往返中获取多个 活动的决策：将 predictions 作为 {campaign_id, context} 字典 列表传入，每次调用最多 100 项。
• record_outcome — 报告所选操作是否 成功（1.0）或失败（0.0），为 interaction_id 完成反馈闭环。超出 [0, 1] 范围的奖励会在本地 被拒绝，并提示 reward must be between 0 and 1。
• archive_campaign — 软删除活动：暂停预测 和奖励处理，但保留所有已学习的 权重。
• restore_campaign — 将已归档的活动恢复为活跃 状态，并保留所有权重。
• campaign_budget — 查看每项资源的预算支出： 已消耗、剩余、利用率、影子价格和 耗尽状态。
• add_arm — 向正在运行的活动添加操作， 可选择从现有选项进行热启动，并设置预算 costs。
• set_arm_status — 暂停、退役或重新启用操作（status 为 "active"、"paused" 或 "retired"）；该选项会保留已学习的所有内容。

未设置的可选参数会从请求中完全省略。 响应会按服务器返回的原样提供。上游返回非 2xx 响应时会报错 banditdb error: HTTP <status>；服务器无法访问时（包括超时）则会报错 banditdb unreachable。

端点来源

原项目的 README 和 MCP 文档确定了十二个工具、它们的参数、上述配置以及决策循环语义，但这些来源中没有发布 HTTP API。以下请求路径是重建得出的，并已标明：

• POST <base>/campaigns，参数作为 JSON 请求体（由 create_campaign 使用）。
• GET <base>/campaigns（由 list_campaigns 使用）。
• GET <base>/campaigns/{campaign_id}/diagnostics （由 campaign_diagnostics 使用）。
• GET <base>/campaigns/{campaign_id}/report（由 campaign_report 使用）。
• GET <base>/campaigns/{campaign_id}/pacing（由 campaign_budget 使用；SDK 方法名为 pacing）。
• POST <base>/predict，请求体为 {"campaign_id": ..., "context": ...}（由 get_intuition 使用）。
• POST <base>/predict/batch，请求体为 {"predictions": [...]}（由 batch_get_intuition 使用）。
• POST <base>/reward，请求体为 {"interaction_id": ..., "reward": ...}（由 record_outcome 使用）。
• POST <base>/campaigns/{campaign_id}/archive，请求体为 {}（由 archive_campaign 使用）。
• POST <base>/campaigns/{campaign_id}/restore，请求体为 {}（由 restore_campaign 使用）。
• POST <base>/campaigns/{campaign_id}/arms，请求体为 {"arm_id": ...}（由 add_arm 使用）。
• POST <base>/campaigns/{campaign_id}/arms/{arm_id}/status 请求体为 {"status": ...}（由 set_arm_status 使用）。

路径片段会原样发送。有一点差异值得注意：供应商的 MCP 文档页面列出了十二个工具中的九个（未列出 campaign_budget、add_arm 和 set_arm_status）；软件包自身的 MCP 表列出了全部十二个，本次重建遵循软件包中的表格。

命令行界面

每个工具都是一个子命令，接受一个 JSON 参数字符串：

npx @reneturcios/banditkeep create_campaign '{"campaign_id":"model-routing","arms":["fast","cheap"],"feature_dim":4}'
npx @reneturcios/banditkeep list_campaigns '{}'
npx @reneturcios/banditkeep campaign_diagnostics '{"campaign_id":"model-routing"}'
npx @reneturcios/banditkeep campaign_report '{"campaign_id":"model-routing"}'
npx @reneturcios/banditkeep get_intuition '{"campaign_id":"model-routing","context":[0.8,0.2,0.5,0.1]}'
npx @reneturcios/banditkeep batch_get_intuition '{"predictions":[{"campaign_id":"model-routing","context":[0.8,0.2,0.5,0.1]}]}'
npx @reneturcios/banditkeep record_outcome '{"interaction_id":"9f2c-4e1a","reward":1.0}'
npx @reneturcios/banditkeep archive_campaign '{"campaign_id":"model-routing"}'
npx @reneturcios/banditkeep restore_campaign '{"campaign_id":"model-routing"}'
npx @reneturcios/banditkeep campaign_budget '{"campaign_id":"model-routing"}'
npx @reneturcios/banditkeep add_arm '{"campaign_id":"model-routing","arm_id":"balanced"}'
npx @reneturcios/banditkeep set_arm_status '{"campaign_id":"model-routing","arm_id":"cheap","status":"paused"}'
npx @reneturcios/banditkeep --version

输出为工具的结果文本（成功时为上游响应体）。退出代码：成功时为 0，运行时错误时为 1，用法错误时为 2。

MCP 服务

npx -y @reneturcios/banditkeep mcp

MCP 客户端配置（如果服务需要密钥，请通过客户端的环境提供该密钥）：

{
  "mcpServers": {
    "banditkeep": {
      "command": "npx",
      "args": ["-y", "@reneturcios/banditkeep", "mcp"],
      "env": {
        "BANDITDB_URL": "http://localhost:8080",
        "BANDITDB_API_KEY": "<your key>"
      }
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/banditkeep
docker run --rm ghcr.io/cloudcorprecords/banditkeep list_campaigns '{}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios