banditkeep

banditkeep

エージェントの群れに、意思決定のためのメモリを提供します。banditkeep は、BanditDB サーバー用の小さなクライアントです。BanditDB は、キャンペーンごとに、どのコンテキストでどのアクションが効果を発揮しやすいかを学習するコンテキストバンディットデータベースです。エージェントが選ぶべきアームを尋ね、回答に基づいて行動し、それがうまくいったかどうかを報告すると、同じサーバーを参照する後続のエージェントは、再学習の手順なしにその結果の恩恵をすぐに受けられます。

キャンペーンを支える探索アルゴリズムは、次の2つです。 決定論的で、alpha による調整が可能な LinUCB と、ベイズ的に自然な探索を行い、調整が不要なトンプソン・サンプリングです。また、キャンペーンには、限られたリソースを消費するアクション向けの予算を設定できます。これにより、初日に予算を使い果たすのではなく、一定期間にわたって支出を配分できます。

設定

次の3つの環境変数でクライアントを制御します。

• 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 — アームごとの学習状態（シータのノルム、 予測数、報酬率、エントロピーの健全性）を調べます。キャンペーンが 学習していないように見える場合や、特定のアームが優勢な場合に 使用してください。
• campaign_report — ビジネス向けの収束レポートを返します。 キャンペーンが統計的に収束したかどうかと、信頼区間を含む 勝者のアームを示します。
• get_intuition — 指定した context（特徴名から数値へのオブジェクト、 または数値の配列）に対して、選ぶべきアームを尋ねます。任意の eligible_arms／exclude_arms を指定すると、このリクエストに限り 選択肢を絞り込めます。保存用のアームと interaction_id を返します。
• batch_get_intuition — 複数のキャンペーンについて、1回の往復で 意思決定を取得します。predictions に {campaign_id, context} 辞書のリストを渡します。1回の呼び出しにつき 最大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 ドキュメントには、12 個のツール、その引数、上記の設定、意思決定ループのセマンティクスが記載されていますが、これらの資料には HTTP API が公開されていません。以下のリクエストパスは再構成したものであり、その旨を明記しています。

• create_campaign で使用する、引数を JSON 本文として送信する POST <base>/campaigns。
• list_campaigns で使用する GET <base>/campaigns。
• campaign_diagnostics で使用する GET <base>/campaigns/{campaign_id}/diagnostics。
• campaign_report で使用する GET <base>/campaigns/{campaign_id}/report。
• campaign_budget で使用する GET <base>/campaigns/{campaign_id}/pacing（SDK メソッド名は pacing です）。
• get_intuition で使用する、本文 {"campaign_id": ..., "context": ...} を送信する POST <base>/predict。
• batch_get_intuition で使用する、本文 {"predictions": [...]} を送信する POST <base>/predict/batch。
• record_outcome で使用する、本文 {"interaction_id": ..., "reward": ...} を送信する POST <base>/reward。
• archive_campaign で使用する、本文 {} を送信する POST <base>/campaigns/{campaign_id}/archive。
• restore_campaign で使用する、本文 {} を送信する POST <base>/campaigns/{campaign_id}/restore。
• add_arm で使用する、本文 {"arm_id": ...} を送信する POST <base>/campaigns/{campaign_id}/arms。
• set_arm_status で使用する、本文 {"status": ...} を送信する POST <base>/campaigns/{campaign_id}/arms/{arm_id}/status。

パスの各セグメントはそのまま送信されます。知っておくべき相違点が 1 つあります。ベンダーの MCP ドキュメントページには 12 個のツールのうち 9 個しか記載されていません（campaign_budget、add_arm、set_arm_status が省略されています）。一方、パッケージ独自の MCP テーブルには 12 個すべてが記載されており、この再構築ではパッケージのテーブルに従っています。

CLI

各ツールは、1 つの 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 — Copyright (c) 2026 Rene Turcios