AutoSwarm‑Shadow‑Adapter

概要 – AutoSwarm AIエージェントオーケストレーションフレームワーク用のプラグインで、DAGベースのワークフローが、ステップが人間のレビュアー（「Carbon」従業員）または外部GPUワーカー（「Silicon」BYOCワーカー）を必要とする場合に、非ブロッキングで一時停止できるようにします。一時停止は、保留中のタスクを独立したSQLite WALデータベースに格納し、直ちにAWAITING_HUMAN状態を返す軽量なShadowModeAdapterによって処理されるため、並列DAGの残りは実行を継続します。

主な機能

機能	説明
非ブロッキングインターセプト	タスクを50ミリ秒未満でキャプチャし、`shadow_tasks.db`に格納して、エンジンスレッドを解放します。
人間およびリモートワーカーポータル	FastAPIベースのREST API + React 19 + Tailwind UI（`http://localhost:8800`）で、人間がタスクをクレームし、マークダウンブリーフを表示し、最大5ファイル（合計≤50MB）をアップロードできます。
BYOCコンピュート	リモートノードは`shadow-worker`デーモンを実行し、JWTで認証し、タスクを取得し、ローカルモデル（Ollama、Anthropic、OpenAIなど）を実行して結果をプッシュバックします。
監査対応の永続化	すべての提出物はタイムスタンプ、属性、不変に保存されます。SQLite WALはクラッシュ耐性と状態回復を保証します。
コア変更なし	アダプターはAutoSwarmの`ADAPTER_CLASSES["shadow"]`レジストリに自己登録します。メインのAutoSwarmコードベースへの変更は不要です。
企業成果物レジストリ	アップロードされた成果物はSHA-256ハッシュとともに`CorporateArtifacts`に保存され、下流のエージェントが検索可能になります。

動作の仕組み（高レベルフロー）

AutoSwarmが作業アイテムを作成し、ロールに対してpreferred_external_agent: shadowを確認します。
ShadowModeAdapterがタスクをインターセプトし、マークダウンブリーフを作成し、shadow_tasks.dbにレコードを書き込み、AWAITING_HUMANを返します。
人間またはシリコンワーカーがReactポータルにログイン（またはshadow-workerを実行）して、保留中のタスクをクレームします。
ワーカーはコンテキストを確認し、解決ノートを書き、オプションでファイルをアップロードします。
アダプターはAutoSwarmのネイティブstore.db（WALモード）にPhase.APPROVEDを書き込み、ネイティブのDAGフックをトリガーします。
下流ノードは自動的に再開し、新しくアップロードされた成果物を入力の一部として受け取ります。

クイックスタート（Python 3.10+）

# 1️⃣ PyPIからパッケージをインストール
pip install AutoSwarm-shadow-adapter

# 2️⃣ AutoSwarmエントリポイントにアダプターを登録
#    （例：AutoSwarmアプリケーションのmain.py）
from opc.layer3_agent.adapters.registry import ADAPTER_CLASSES
from shadow_adapter import ShadowModeAdapter, start_server_in_thread

ADAPTER_CLASSES["shadow"] = ShadowModeAdapter   # プラグイン登録
start_server_in_thread(port=8800)               # FastAPI + React UIを起動

# 3️⃣ 通常のAutoSwarm DAGを通常どおり実行します。

別プロセスを希望する場合は、サイドカーサーバーを実行するだけです: shadow-serve --port 8800。

リモートシリコンワーカー（BYOC）

# 例: Ollamaを使用するリモートGPUワークステーション
export OLLAMA_HOST="http://localhost:11434"
shadow-worker \
  --server-url http://192.168.1.100:8800 \
  --username dev_node_1 \
  --password secret123 \
  --role senior_developer \
  --provider ollama \
  --model llama3.3:70b

デーモンはAPIを継続的にポーリングし、roleに一致するタスクをクレームし、指定されたモデルをローカルで実行し、結果をポストバックします。

設定（環境変数 / .env）

変数	必須?	デフォルト	意味
`SHADOW_JWT_SECRET`	はい	–	JWTトークンの署名用シークレット（≥32文字）。
`SHADOW_DB_PATH`	いいえ	`./shadow_tasks.db`	分離されたSQLite WAL DBのパス。
`SHADOW_OPC_STORE_PATH`	いいえ	`.opc/projects/default/store.db`	AutoSwarmのメインストアDBのパス（アダプターが再開フェーズを書き込む場所）。
`SHADOW_UPLOAD_DIR`	いいえ	`./shadow_uploads`	アップロードされたファイルが保存されるディレクトリ。
`SHADOW_MAX_FILES_PER_SUBMISSION`	いいえ	`5`	タスクあたりの最大ファイル数。
`SHADOW_MAX_FILE_SIZE_MB`	いいえ	`10`	ファイルあたりの最大サイズ。
`SHADOW_MAX_TOTAL_UPLOAD_SIZE_MB`	いいえ	`50`	提出あたりの最大ペイロード合計。
`SHADOW_API_PORT`	いいえ	`8800`	FastAPIサーバーとReact SPAのポート。

誰がこれを使うべきか?

フリーランサーまたは個人創業者 – 重い処理をリモートGPUノードにアウトソーシングしつつ、最終的な人間の承認を保持したい人。
企業 – 並列AI作業を停止させずに、監査グレードのヒューマン・イン・ザ・ループチェックポイント（SOC 2、ISO 27001、GDPR）を必要とする企業。
チーム – 複数のクライアント契約を同時に実行し、キュー方式の「ヒューマン・アズ・ア・サービス」レイヤーを必要とするチーム。

制限と考慮事項

アダプターはAutoSwarm（対象とする特定のDAGエンジン）でのみ動作します。他のフレームワーク用の汎用HITLレイヤーではありません。
人間のタスクは別のSQLite WALに保存されます。長期的な保持が必要な場合は、shadow_tasks.dbをバックアップする必要があります。
ファイルアップロードは5×10MB（設定可能）に制限されています – 大きなバイナリアセットには外部ストレージが必要です。
セキュリティはJWT + bcryptに依存しています。SHADOW_JWT_SECRETを保護し、本番環境ではポータルをTLSの背後で実行する必要があります。

開発とテスト

# カバレッジ付きのフルテストスイート（55テスト）を実行
pytest tests/ -v --cov=shadow_adapter --cov-report=term-missing

# クイックデモ用にAutoSwarmエンジンをシミュレート
python tests/mock_AutoSwarm_engine.py

リポジトリには、型チェック済みコード、プロパティベースのファズテスト、エンジン再起動や同時タスク負荷をアダプターが乗り切ることを検証する統合テストが含まれています。

リンク

GitHub: https://github.com/AhmadHassan-BTed/AutoSwarm-shadow-adapter
PyPI: https://pypi.org/project/AutoSwarm-shadow-adapter/
AutoSwarmコアリポジトリ: https://github.com/HKUDS/AutoSwarm

AutoSwarmコミュニティのために構築されました – AIエージェントと実際の人間が、ワークフローをデッドロックさせることなく協力できるようにする、非侵襲的なヒューマン・イン・ザ・ループブリッジです。

AhmadHassan-BTed/AutoSwarm-Shadow-Adapter