CAS Studio

複雑適応系（CAS）をエージェントベースモデルとして設計・シミュレーションするためのスタジオです。エージェントタイプ（状態＋ローカルルール）を定義し、エージェントを有向・符号付き相互作用グラフに配線し、システムにソースとシンクを備えたオープンな環境を与え、決定論的でシード付きの同期シミュレーションエンジンを実行します。7つの標準的なCAS特性は、第一級の計装された機能であり、それぞれに明示的なモデル構造と分析エンドポイントがあります。単なるドキュメントではありません。

純粋なPython + numpyコア。REST APIと永続化にはFastAPI + SQLAlchemy + Alembic。Vanilla-JSキャンバスUI。重い依存関係なし、ネットワーク呼び出しなし、外部データなし。

クイックスタート

./run.sh                      # venv + deps (via uv), alembic upgrade, uvicorn
# HOST=127.0.0.1 PORT=8002 ./run.sh   to override

次に http://localhost:8000/ を開きます。空のデータベースに対する初回起動時には、シードデモが読み込まれ（監査ログに記録されます）：市場におけるイノベーション普及 — スモールワールドリング格子上の40エージェントで、革新者、初期多数派、遅延採用者、2人の懐疑者（バランスループ）、2人の適応価格ベンダー、そして環境内のinformationソースが含まれます。隣接する2つのシード採用者がS字カーブの採用カスケード（平均採用率0.12→0.95、約11ステップ）を引き起こし、離陸時に創発イベントがフラグ付けされます。シードを1つに減らすと失敗します。

テストを実行：

.venv/bin/python -m pytest tests/ -q

Related MCP server: COMSOL MCP Server

7つのCAS特性

1. 創発

マクロパターンはミクロな相互作用から生じます。エンジンは毎ステップ、マクロメトリクスを記録します：すべての状態変数の平均場、母集団の分散、アクティブクラスター数（無向相互作用グラフ上の「アクティブ」エージェント（主変数≥0.5）の連結成分）、秩序パラメータ |2·active_fraction − 1|、およびモランIに似た近傍相関。GET /api/runs/{id}/emergence は、系列とフラグ付きの創発イベントを返します：外生入力が一定（注入なし）の間に、マクロ指標のステップ間デルタのzスコアが3を超えるステップ。正直な注意： 短い系列に対するzスコアは鈍感な検出器です — イベントは検査のためのフラグとして扱い、証明として扱わないでください。

2. 非線形性

POST /api/systems/{id}/sensitivity に {"param", "deltas": [...], "steps", "seed"} を指定すると、param を各デルタで摂動させてシミュレーションを再実行し、応答比 |Δoutcome/Δparam|（outcome = 主変数の最終平均場）を報告します。nonlinear（比が大きさの桁で10倍以上変化 — 超線形領域）、threshold（一部の摂動は応答を生じ、他は生じない）、sign_flip をフラグ付けします。パラメータ指定：

シードデモには seed_count:innovator:adopted に真の閾値があります：シード1つでは失敗（採用率0.075）、隣接する2つのシードではカスケード（0.95）。

3. 分散化

エージェントはローカル情報のみに基づいて行動します：自身の状態、直接の入近傍の状態の重み付き平均、およびフラックスを介した環境変数。ルールDSLの条件語彙は閉じており、グローバル状態は構造上表現不可能です（「全エージェント」の集約も、グローバルな参照もありません）。自己組織化は、各実行の系列におけるモランIに似た近傍状態相関によって追跡されます。

4. フィードバックループ

GET /api/systems/{id}/loops は、有向相互作用グラフの基本サイクルを列挙します（JohnsonスタイルのDFS、各サイクルは最小ノードから一度だけ報告されます。max_len と1000サイクルの上限が列挙を制限し、truncated を報告します）。各ループは、強化（負の結合が偶数個）またはバランス（奇数個）に分類され、ループゲイン = エッジ重みの積です。実行サマリーには、ループごとのアクティビティが含まれます：実行中に各ループのエッジを流れたエッジフラックス。ここで、エッジフラックス（1ステップあたり）= |ソースの主変数のΔ| × |重み|（「このエッジに沿ってどれだけの変化が伝播したか」のヒューリスティックであり、物理量ではありません）。

5. 適応

エージェントタイプは "adaptation": {"target_var", "target_value", "rate"} を宣言できます。各ステップで、エージェントは target_var に有界なバイアスを加えます。ステップ後、バイアスは勾配なしの強化によって更新されます：ステップが変数を target_value に近づけた場合はバイアスを維持・増幅し（×1.25、|1.0|で上限）、そうでない場合は反転・減衰させます（×−0.5）。シードが与えられれば決定論的です。シードデモのベンダーはこの方法で price を0.7に向けてヒルクライムします。

6. オープンな境界

すべてのシステムには環境があります：名前付きの浮動小数点変数とソース/シンク — {"var": "information", "inflow": 1.0, "outflow_rate": 0.05} は毎ステップ v += inflow − outflow_rate·v を適用します。エージェントは保存フラックス効果を通じて環境と交換します：{"flux": "information", "by": 0.02} は0.02単位を環境からエージェント（同名の状態変数）に移動します。環境はエージェントが得た分だけ正確に失います（テストで検証済み）。POST /api/runs/{id}/inject に {"step", "var", "amount"} を指定すると、外生パルスをスケジュールします：基本実行のシステム/シード/ステップを、そのステップで環境にパルスを加えて再実行し、新しい実行と結果のデルタを返します。

7. 入れ子階層

System は parent_id を持つことができます。サブシステムは、独自のエージェント、ルール、実行を持つ完全なシステムです。GET /api/systems/{id}/rollup は、各子システムの最新実行のマクロメトリクスを親のレポートに集約します（子の主平均場のエージェント数加重平均）。

ルールDSL

エージェントタイプは state（浮動小数点変数のdict）と rules — {"if": <condition>, "then": [<effect>, ...]} のリストを持ちます。最初に一致したルールが発火し、そのステップでは後続のルールは無視されます（"then": [] のルールは吸収状態ガードです）。

条件：

"always"
{"var": "adopted", "op": ">=", "value": 0.5}                 // own state
{"neighbor_mean": {"var": "adopted"}, "op": ">=", "value": 0.35}  // in-neighbors

op ∈ > < >= <= ==。neighbor_mean は、その変数を持つ入近傍にわたる重み付き平均 Σ wᵢxᵢ / Σ|wᵢ| です。したがって、負の重み（懐疑者）の近傍は平均を薄めます。

効果：

{"set": "adopted", "value": 1.0}        // set own var
{"adjust": "energy", "by": -0.1}        // add to own var
{"flux": "information", "by": 0.02}     // conserve quantity with the environment

個々のエージェントは state_override を持つことができます：浮動小数点数、または {"uniform": [lo, hi]}。これは実行のシード付きRNG（np.random.default_rng(seed)）から実行ごとに一度サンプリングされます — これが実行シードを意味あるものにします。同じモデル＋同じシード → 同一のメトリクス系列（テスト済み）。

エンジンは同期的にステップします：すべてのエージェントは同じスナップショットから次の状態を計算します — 更新順序によるアーティファクトはありません（振動する2エージェントモデルでテスト済み）。

REST API

すべての変更は監査ログに記録されます（GET /api/audit）。

MCP統合

CAS StudioにはMCP（Model Context Protocol）stdioサーバーが同梱されており、AIホスト（Cursor、Claude Desktopなど）がシステムを直接設計・シミュレーションできます。REST APIをHTTP経由で前面に提供します — CAS_API_URL（デフォルト http://127.0.0.1:8000）で任意の実行中インスタンスを指定します。

ホストのMCP設定に登録します（mcp-config.example.jsonを参照）：

{
  "mcpServers": {
    "cas-studio": {
      "command": "/path/to/cas-studio/.venv/bin/python",
      "args": ["-m", "app.mcp_server"],
      "cwd": "/path/to/cas-studio",
      "env": {"CAS_API_URL": "http://127.0.0.1:8000"}
    }
  }
}

公開されるツール（それぞれ上記の対応するRESTエンドポイントをプロキシします）：list_systems、get_system、list_agent_types、create_agent_type、create_agents（バッチ）、add_interaction、set_environment_flow、run_simulation、get_run_series、get_emergence_events、list_feedback_loops、run_sensitivity、inject_pulse、get_rollup、およびdescribe_cas_properties（7特性ガイド＋ルールDSL）。

AIエージェント

UIのAIエージェントタブは、ローカルのOllama LLMを通じてスタジオを操作する組み込みのチャットエージェントです — APIキーは不要で、マシンの外に何も送信されません。

要件：Ollamaが実行中（ollama serve）で、少なくとも1つのモデルがあること。例：

ollama pull qwen3:8b   # the default; supports tool calling and thinking

モデルドロップダウンには、Ollamaがインストール済みとして報告するモデルが一覧表示され、デフォルトはqwen3:8b、次に任意のgemma3*、次にllama3.1:8b、次に最初のモデル（GET /api/agent/models）になります。OLLAMA_URL（デフォルト http://127.0.0.1:11434）でエージェントを別のOllamaホストに向けます。

POST /api/agent/chat と POST /api/agent/generate はバックグラウンドジョブとして実行されるため（HTTP 202 {job_id}）、低速なローカルLLMでもリクエストがハングすることはありません。GET /api/agent/jobs/{id} をポーリングして {status: pending|running|done|error, progress: [...], result|error} を取得します。ループの実行中に進捗エントリが表示され（「round 2: calling run_simulation…」「attempt 2: validation failed: …」）、すべての失敗は具体的で人間が読めるエラーで終了します。LLM呼び出しはOllamaのネイティブ /api/chat を think: false で使用します（qwen3の思考モードはCPUバウンドのOllamaでは約10倍遅く、ツール呼び出しには何ももたらしません）。デフォルトのラウンド上限は5です。

POST /api/agent/chat {messages, model?, system_id?, temperature?, max_rounds?} は、Ollamaの /api/chat に対してツール呼び出しループを実行します。モデルがツールを選択し、サーバーがそれを実行し（MCPサーバーと同じツールレジストリ app/tools.py を通じて）、結果を追加して、モデルが最終回答を書くまで max_rounds まで繰り返します。ジョブ結果は {reply, model, tool_trace, rounds} です。tool_trace は各呼び出しの引数とトリミングされた結果を一覧表示し、UIは各返信の下に折りたたみ可能なブロックとしてレンダリングします。チェーン・オブ・ソート（qwen3の thinking ブロック）は返信から除去されます。選択したモデルがツール呼び出しをサポートしていない場合、エージェントは注記付きのワンショットのツールなし回答にフォールバックします。Ollamaがダウンしている場合、modelsエンドポイントはグレースフルに劣化し、ジョブは明確なエラーで終了します。

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?} は、平易な英語を実行可能なCASモデルに変換します。LLM（Ollama JSONモード）は、コンパクトなDSLリファレンス、数発の例、およびシステム工学の設計ルール（類型分解、少なくとも1つの強化ループと1つのバランスループ、保存量のための開放境界フロー、システム・オブ・システムズのためのネスト）に導かれて、システム仕様（ルールDSL動作を持つエージェントタイプ、エージェント数、相互作用トポロジ（ring_lattice / random / small_world）、ソースタイプ別の符号付きエッジ重み、ソース/シンクを持つ環境変数、オプションのネストされた子システム）をドラフトします。サーバーは仕様を厳密に検証します（スキーマ、完全なルールDSLバリデーター、トポロジの具体化）。失敗した場合、検証エラーはモデルにフィードバックされ、最大 max_rounds 回（デフォルト3）試行され、その後ジョブは収集されたメッセージとともにエラーで終了します。成功すると、すべてがリポジトリを通じて作成され（ai-agent によって generate_system として監査ログに記録）、結果には新しいシステムID、要約、および生の仕様が含まれます。同じ機能はMCPホストには generate_system_from_description ツールとして公開され（ジョブを送信して待機します）、UIではAI AgentタブのGenerate systemモードとして公開されます（ライブ進捗付き）。

LLM設定

AI Agentタブの歯車ボタンで設定が開きます。temperature（デフォルト0.2）とmax tool rounds（デフォルト8）は、/api/agent/chat と /api/agent/generate の両方にリクエストごとに temperature / max_rounds として送信されます。さらに、アクティブなOllama URLと ollama pull のヒントも含まれます。モデル、温度、ラウンドの選択はlocalStorageに永続化されます。

編集、例、ガイド付きUX

キャンバスには手動モデル構築用の編集ツールバー（Select / Add agent / Connect / Delete）があります。ノードまたはエッジをクリックすると、詳細パネルにエディターが開きます（名前、状態オーバーライド、エッジ重み）。Structureタブでは、エージェントタイプ（状態スキーマ + インライン検証エラー付きルールDSL）と環境（変数 + ソース/シンクフロー）を編集します。新しいエンドポイント: PUT /api/agents/{id}、PUT /api/interactions/{id}、PUT /api/agent-types/{id}（すべて検証され監査ログに記録されます）。Examplesタブでは、キュレーションされたシステムをワンクリックで読み込みます（GET /api/examples、POST /api/examples/{name}）。イノベーション市場カスケード、捕食者–被捕食者の牧草地、2層サプライネットワーク（ネスト階層）— それぞれに注目ポイントの説明が付いています。初回実行時のヘルプオーバーレイ、タブごとの説明バー、空状態のヒントが新規ユーザーをガイドします。創発パネルは、イベントが発生しない場合に最も強い閾値未満のシフト（GET /api/runs/{id}/emergence の near_misses）を表示します。

グラフキャンバス

システムグラフは完全にインタラクティブです。空きスペースをドラッグしてパン、マウスホイールでズーム（カーソル位置を基準に、ズームインジケーターとFitボタン付き）、ノードをドラッグして再配置できます。位置はサーバー側に永続化され（pos_x/pos_y、ドラッグ終了時に保存）、自動レイアウトは保存された位置のないノードのみを埋めます。エッジは方向矢印、正/負の結合に対して緑の実線/赤の破線、符号を超えた情報を持つ場合は重みラベルを表示します。ノードには名前と

• 実行後の主要な状態値がラベル付けされ、ホバーすると完全なエージェント状態のツールチップが表示されます。タイプ凡例はコーナーにあります。純粋なジオメトリ/レイアウトヘルパーは app/static/graph.js にあり、node --test でユニットテストされています（tests/js/ を参照）。

レイアウト

app/
  main.py        FastAPI app, REST API, static UI
  tools.py       shared tool registry (names/schemas/execution) for MCP + agent
  mcp_server.py  MCP stdio server fronting the REST API (CAS_API_URL)
  agent.py       in-app AI agent: Ollama tool-calling loop (OLLAMA_URL)
  jobs.py        in-process background jobs for slow LLM work (submit/poll)
  generate.py    natural-language -> validated CAS system spec -> repository
  examples.py    curated one-click example systems
  db.py          engine + session factory (DATABASE_URL, default sqlite:///./cas_studio.db)
  repository.py  SQLAlchemy models + Repository (single DB access point)
  rules.py       rule DSL validation + evaluation (pure functions)
  engine.py      deterministic seeded synchronous simulation engine
  analysis.py    emergence events, loops, sensitivity, Moran's I
  seed.py        the innovation-diffusion demo model
  static/index.html  canvas UI (graph, run controls, chart, loops/sensitivity/inject panels, AI agent)
  static/graph.js    pure canvas helpers (view transform, force layout, edge geometry)
alembic/         schema migrations
tests/           pytest, one file per concern

ライセンス

MIT — © 2026 Vector Stream Systems LLC.