swarm-rd-orchestrator

Rayアクターとしてラップされた、追記専用のSQLite-WALベースのイベントログです。並列エージェントは、共有の変更可能なストアを使わずに調査結果を書き込み、互いの結果を取得できます。さらに、CLIとMCP サーバーにより、人間もほかのエージェントも直接操作できます。

これはマイルストーン1のプロトタイプです（2026-08-03）。先に実際のタスクでアプローチを検証し、その後の開発に進みます。以下の確定した決定事項と、実際の検証ハーネスであるspike.pyを参照してください。

インストール

pip install swarm-rd-orchestrator-cli
# or
npm install -g swarm-rd-orchestrator-cli

どちらの方法でも、PATH上にswarm-rd-cliコマンドがインストールされます。npmパッケージはPython CLIを薄くラップしたもので、実際のバイナリを実行し、再実装はしていません。npmパッケージを使う場合も、Pythonパッケージをインストールしてください。

**ステータス：**両方のレジストリで公開中です（PyPIにはGitHub Actions OIDCを使用して公開しており、トークンは保存していません）。どちらも、アップロードが成功しただけでなく、クリーンな環境で実際にインストールし、コマンドを実行して検証済みです。

警告

これは検証前のマイルストーン1のスパイク（0.0.x）であり、安定版ではありません。macOSのみでテスト済みです。Ray自体のWindowsサポートは上流のLinux/macOS向けサポートよりも限定的なため、Windowsのサポートは未検証です。

クイックスタート

swarm-rd-cli append task-1 agent-a "found a race condition in the retry loop" --kind result
swarm-rd-cli append task-1 agent-b "confirmed: retry loop isn't holding the lock" --kind result
swarm-rd-cli pull task-1
# [1] (agent-a/result) found a race condition in the retry loop
# [2] (agent-b/result) confirmed: retry loop isn't holding the lock

swarm-rd-cli --json pull task-1     # structured output for scripts/agents
swarm-rd-cli list-tasks             # every task_id with a delta count
swarm-rd-cli mcp                    # run as an MCP server over stdio

データを返すすべてのコマンドは、エージェントやスクリプトで利用できる--jsonに対応しているため、画面出力のスクレイピングは不要です。mcpサブコマンドは、append_delta、pull_deltas、list_tasksを型付きMCPツールとしてstdio経由で公開するため、エージェントはシェルコマンドを実行せず、プログラムからこのプログラムを呼び出せます。

機能

• 原子性のある追記を実証済み。単なる主張ではありません。 専用のテストで書き込み途中のクラッシュをシミュレートし、保証を説明するだけでなく、SQLite WALレイヤーに不完全な行が残らないことを確認します。
• すべてのデータコマンドで構造化出力に対応。 append、pull、list-tasksで--jsonを指定できるため、このCLIを呼び出すエージェントが、人間向けに整形されたテキストをスクレイピングする必要はありません。
• CLIだけでなく、MCP サーバーも提供。 swarm-rd-cli mcpは、同じ3つの操作を型付きツールとしてstdio経由で公開するため、エージェントはサブプロセスを起動せず、プログラムから呼び出せます。
• モックではなく、実際のRayアクターで並行性をテスト。 重要なテストでは、実際のRayアクター3つが並行して追記し、その結果を照合します。実際のワークロードと同じ仕組みです。
• 不正な入力は明確にエラーになります。 task_id、agent_id、contentのいずれかが欠けたdeltaは、ストレージに触れる前にInvalidDeltaErrorを発生させます。暗黙に破棄されることはありません。

コマンドリファレンス

CLI自身の--help出力から生成：

usage: swarm-rd-cli [-h] [--db DB] [--json] {append,pull,list-tasks,mcp} ...

positional arguments:
  {append,pull,list-tasks,mcp}
    append              append a delta to the event log
    pull                pull deltas for a task
    list-tasks          list every task_id with a delta count
    mcp                 run as an MCP server over stdio

options:
  -h, --help            show this help message and exit
  --db DB               path to the event log (default: swarm-events.db)
  --json                structured JSON output (for agent/script use)

usage: swarm-rd-cli append [-h] [--kind {note,result,tool_output}]
                            task_id agent_id content

positional arguments:
  task_id
  agent_id
  content

options:
  -h, --help            show this help message and exit
  --kind {note,result,tool_output}

usage: swarm-rd-cli pull [-h] [--since SINCE] task_id

positional arguments:
  task_id

options:
  -h, --help     show this help message and exit
  --since SINCE  cursor to pull after

MCP サーバー

swarm-rd-orchestrator-cli には Model Context Protocol（MCP）サーバーが付属しているため、エージェントは CLI をシェルから呼び出してテキストを解析する代わりに、stdio 経由で型付きツールとしてイベントログを直接呼び出せます。

pip install "swarm-rd-orchestrator-cli[mcp]"

次のコマンドで起動します。

swarm-rd-cli mcp

設定でこのコマンドを指定すると、Claude Desktop（またはその他の MCP クライアント）に追加できます。

{
  "mcpServers": {
    "swarm-rd-orchestrator": {
      "command": "swarm-rd-cli",
      "args": ["mcp"]
    }
  }
}

次の 3 つのツールが公開されています。

• append_delta(task_id, agent_id, content, kind="note") - タスクのイベントログに調査結果／結果／ツール出力を追加します。例：append_delta(task_id="task-1", agent_id="agent-a", content="found a race condition in the retry loop", kind="result")。
• pull_deltas(task_id, since_cursor=0) - since_cursor より大きい ID を持つタスクのデルタを、古いものから順にすべて取得します。例：pull_deltas(task_id="task-1") は全履歴を返し、pull_deltas(task_id="task-1", since_cursor=2) はカーソル 2 以降に書き込まれたデルタのみを返します。
• list_tasks() - 現在イベントログにあるすべての task_id を、デルタ数とともに一覧表示します。例：list_tasks() は [{"task_id": "task-1", "delta_count": 2}] を返します。

比較

swarmmesh は作者のポートフォリオにある関連プロジェクトで、PyPI と npm では swarmmesh-cli として公開されています。以下のほぼすべての点で、現時点ではより完成度の高い選択肢です。このプロジェクトは、swarmmesh に不足があるからではなく、Ray をネイティブに活用する代替案として意図的に存在しています。

	swarm-rd-orchestrator-cli	swarmmesh-cli
トランスポート	Ray アクター（プロセス内／分散）	HTTP サーバー
ストレージ	SQLite、WAL モード	デフォルトではメモリ内、または --persist による SQLite
クロスランゲージ対応	Python のみ	Python と Node
メモリの検索／ランキング	なし（task_id による取得のみ）	メモリクエリでの BM25 キーワードランキング
MCP サーバー	あり	あり
PyPI/npm での公開	あり、公開中	あり、公開中
CI	あり	あり

Ray ネイティブの分散コンピューティングという側面が用途に関係しない場合は、代わりに swarmmesh をお使いください。公開済みで、実際の使用状況に基づいてテストされており、より多くの機能を備えています。

swarm-rd-orchestrator-cli とは何か、なぜ存在するのか

swarm-rd-orchestrator-cli は、Ray のアクターモデルに基づいて構築された、並列 AI 研究エージェント向けの共有可能で永続的なイベントログです。各エージェントは構造化されたデルタとして調査結果を書き込みます。他のエージェントは、共有の可変ストアや調整用サーバープロセスなしで、タスクの全履歴を取得できます。

このプロジェクトは、特定の限定的な仮説を検証するために存在します。Ray のアクターとオブジェクトストアのモデルは、HTTP ベースの調整レイヤーよりも、実際に多数の並列研究エージェントを調整するのに適しているという仮説です。この仮説はまだ証明されていません。このプロジェクトは、さらなる投資を行う前に実際のワークロードで検証することを目的としたマイルストーン 1 のスパイクとして公開されています。詳しくは、実際の検証スパイクを実行するをご覧ください。

ソースからビルドする

git clone https://github.com/RudrenduPaul/swarm-rd-orchestrator.git
cd swarm-rd-orchestrator
python3 -m venv .venv
.venv/bin/pip install -e ".[dev,mcp]"

Python 3.10 以降が必要です（mcp SDK の依存関係で必要です）。

テストを実行する

.venv/bin/pytest test_event_log.py -v

9 件中 9 件が成功します。負荷の高いテストでは、3 つの Ray アクターが 1 つの共有イベントログに同時に追加を行い、デルタの欠落や重複がないことを確認しています。

実際の検証スパイクを実行する

spike.py の REAL_TASK_ID、REAL_TASK_DESCRIPTION、サンプルエージェントの調査結果を実際の研究タスクに合わせて編集し、次を実行します。

.venv/bin/python3 spike.py

最後に表示される評価基準を確認してください。判断基準は、raw Ray または LangGraph に対して条件を満たすアーキテクチャ上の失敗事例が 3 件未満の場合、これ以上構築を進めず、薄い CLI ラッパーに切り替えることです。

決定事項（2026-08-03）

• プリミティブ：Ray（アクターモデルとオブジェクトストア）、フォールバックとして LangGraph
• ストレージ：SQLite、WAL モード
• 差分の形式：{task_id, agent_id, timestamp, content, kind}
• 不正な差分では InvalidDeltaError を発生させ、黙って処理することはありません
• ライセンス：Apache 2.0
• Python：mcp SDK に必要なため、3.10 以降
• 公開：PyPI（GitHub Actions OIDC Trusted Publishing 経由で、トークンを保存せずに公開）および npm で公開中。どちらも実環境でクリーンインストールして検証済みです

FAQ

具体的には何をするものですか？ Ray アクターとして動作する複数の AI エージェントに、互いの状態を妨げることなく、調査結果を書き込み、互いの調査結果を取得できる、共有可能で永続性のある場所を提供します。これは転送および永続化レイヤーであり、オーケストレーションフレームワークではありません。エージェントのスケジュール設定や動作の決定は行いません。

swarmmesh とはどう違いますか？ 上記の比較を参照してください。基本的なアイデアは同じですが、転送方式が異なります（HTTP ではなく Ray アクターを使用）。また、現時点では swarmmesh のほうがより完成度が高く、すでに公開されています。

Windows、macOS、Linux で動作しますか？ macOS でテスト済みです。Ray 自体は Linux と macOS をネイティブでサポートしています。Ray の Windows サポートは上流でより限定的なため、誰かが確認するまでは、このプロジェクトでの Windows 対応は未検証として扱ってください。

自分の API キーが必要ですか？ いいえ。このプロジェクト自体が LLM の呼び出しを行うことはありません。使用するモデルやフレームワークを問わず、皆さん自身のエージェントが読み書きするための調整レイヤーです。

依存先として安全ですか？ いいえ、まだです。これは検証前のマイルストーン 1 のスパイク（バージョン 0.0.x）であり、安定版ではありません。イベントログの中核となる保証（アトミックな追記、部分書き込みなし）は test_event_log.py でテストされていますが、スパイク用スクリプトを除き、実際のマルチエージェントのワークロードでプロジェクトを検証していません。

人間ではなくエージェントから使うにはどうすればよいですか？ すべてのコマンドで --json を指定して CLI を呼び出すか、swarm-rd-cli mcp を実行して MCP サーバーとして接続してください。どちらも構造化された解析可能な出力を提供します。

これはライブラリですか、それとも CLI だけですか？ どちらでもあります。すでに Python を使っていて CLI や MCP レイヤーが不要な場合は、event_log.py の EventLog クラスと EventLogActor クラスを直接インポートできます。

ライセンスは何ですか？商用利用できますか？ Apache 2.0 です。ライセンス条項のもとで、商用利用、変更、再配布がすべて許可されています。全文については LICENSE を参照してください。

貢献

検証前のスパイクであり、貢献を受け付けるプロジェクトではないため、まだ CONTRIBUTING.md はありません。正式な手順が整う前に変更について話し合いたい場合は、イシューを作成してください。

ライセンス

Apache 2.0 です。全文については LICENSE を参照してください。