CAS Studio

Студия для проектирования и симуляции сложных адаптивных систем (САС) как агентных моделей. Вы определяете типы агентов (состояние + локальные правила), связываете агентов в направленный, знаковый граф взаимодействий, задаёте системе открытую среду с источниками и стоками, и запускаете детерминированный, сидированный, синхронный движок симуляции. Семь канонических свойств САС являются первоклассными, инструментированными функциями — каждое имеет явные конструкты модели и аналитические конечные точки, а не только документацию.

Чистый Python + numpy ядро. FastAPI + SQLAlchemy + Alembic для REST API и персистентности. Ванильный JS canvas 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 агентов на кольцевой решётке малого мира с новаторами, ранним большинством и отстающими, два скептика (балансирующие петли), два вендора с адаптивной ценой и источник information в среде. Два соседних сидированных новатора запускают S-образный каскад принятия (среднее принятие 0.12 → 0.95 за ~11 шагов) с помеченными событиями эмерджентности на взлёте; при одном сиде каскад затухает.

Запустите тесты:

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

Related MCP server: COMSOL MCP Server

Семь свойств САС

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| (исход = финальное среднее поле первичной переменной). Он помечает nonlinear (коэффициенты варьируются более чем в 10 раз по величинам — сверхлинейный режим), threshold (некоторые возмущения дают отклик, другие — нет) и sign_flip. Адресация параметров:

Демо-пример имеет настоящий порог на seed_count:innovator:adopted: один сид затухает (принятие 0.075), два соседних сида запускают каскад (0.95).

3. Децентрализация

Агенты действуют только на основе локальной информации: собственное состояние, взвешенные средние состояния прямых входящих соседей и переменные среды через потоки. Словарь условий DSL замкнут — глобальное состояние непредставимо по построению (нет агрегата «все агенты», нет глобального поиска). Самоорганизация отслеживается через корреляцию состояний соседей, подобную индексу Морана I, в ряду каждого прогона.

4. Петли обратной связи

GET /api/systems/{id}/loops перечисляет элементарные циклы направленного графа взаимодействий (DFS в стиле Джонсона, каждый цикл сообщается один раз от его наименьшего узла; max_len и ограничение в 1000 циклов ограничивают перечисление и сообщают truncated). Каждая петля классифицируется как усиливающая (чётное количество отрицательных связей) или балансирующая (нечётное количество) с усилением петли = произведению весов рёбер. Сводки прогонов включают активность каждой петли: поток по рёбрам, прошедший через рёбра петли во время прогона, где поток по ребру за шаг = |Δ первичной переменной источника| × |вес| (эвристика для «сколько изменения распространилось по этому ребру», а не физическая величина).

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 (словарь переменных с плавающей точкой) и rules — список {"if": <условие>, "then": [<эффект>, ...]}. Срабатывает первое подходящее правило; остальные правила игнорируются на этом шаге (правило с "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]}, которое сэмплируется один раз за прогон из сидированного ГПСЧ прогона (np.random.default_rng(seed)) — именно это делает сид прогона значимым. Та же модель + тот же сид → идентичный ряд метрик (проверено).

Движок шагает синхронно: каждый агент вычисляет своё следующее состояние из одного и того же снимка — без артефактов порядка обновления (проверено на осциллирующей модели из двух агентов).

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 (руководство по семи свойствам + DSL правил).

AI-агент

Вкладка AI Agent в UI — это встроенный чат-агент, который управляет студией через локальную Ollama LLM — без API-ключей, ничего не покидает машину.

Требования: запущенный Ollama (ollama serve) и хотя бы одна модель, например:

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

Выпадающий список моделей показывает то, что Ollama сообщает как установленное, и по умолчанию выбирает qwen3:8b, затем любую gemma3*, затем llama3.1:8b, затем первую модель (GET /api/agent/models). Укажите агенту другой хост Ollama с помощью OLLAMA_URL (по умолчанию http://127.0.0.1:11434).

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 используют нативный /api/chat Ollama с think: false (режим мышления qwen3 примерно в 10 раз медленнее на CPU-bound Ollama и ничего не добавляет к вызовам инструментов), а лимит раундов по умолчанию — 5.

POST /api/agent/chat {messages, model?, system_id?, temperature?, max_rounds?} запускает цикл вызова инструментов через /api/chat Ollama: модель выбирает инструмент, сервер выполняет его (через тот же реестр инструментов, который использует MCP-сервер, app/tools.py), добавляет результат и повторяет — до max_rounds — пока модель не напишет финальный ответ. Результат задания — {reply, model, tool_trace, rounds}; tool_trace перечисляет каждый вызов с его аргументами и усечённым результатом, а UI отображает его как сворачиваемый блок под каждым ответом. Цепочка рассуждений (блоки thinking от qwen3) удаляется из ответов. Если выбранная модель не поддерживает вызов инструментов, агент переключается на одноразовый ответ без инструментов с примечанием; если Ollama недоступна, конечная точка моделей деградирует корректно, а задания завершаются с понятной ошибкой.

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?} превращает простой английский текст в работающую модель CAS. LLM (JSON-режим Ollama) составляет спецификацию системы — типы агентов с поведением на rule-DSL, количество агентов, топологию взаимодействий (ring_lattice / random / small_world), знаковые веса рёбер по типу источника, переменные окружения с источниками/стоками и опциональные вложенные дочерние системы — на основе компактного справочника по DSL, примера с несколькими показами и инженерных правил системного проектирования (декомпозиция типологии, как минимум один усиливающий и один балансирующий контур, потоки с открытыми границами для сохраняющихся величин, вложенность для систем систем). Сервер выполняет строгую проверку спецификации (схема, полный валидатор rule-DSL, материализация топологии); при сбое ошибки валидации возвращаются модели, до max_rounds попыток (по умолчанию 3), после чего задание завершается ошибкой с собранными сообщениями. При успехе всё создаётся через репозиторий (аудит-логируется как generate_system от ai-agent), а результат содержит новый идентификатор системы, сводку и исходную спецификацию. Та же возможность доступна MCP-хостам как инструмент generate_system_from_description (он отправляет задание и ждёт), а в UI — как режим Generate system вкладки AI Agent (с живым прогрессом).

Настройки LLM

Кнопка с шестерёнкой на вкладке AI Agent открывает настройки: temperature (по умолчанию 0.2) и max tool rounds (по умолчанию 8) — отправляются в каждом запросе как temperature / max_rounds в оба эндпоинта /api/agent/chat и /api/agent/generate — плюс активный URL Ollama и подсказки ollama pull. Выбор модели, температуры и количества раундов сохраняется в localStorage.

Редактирование, примеры и направляемый UX

На холсте есть панель редактирования (Select / Add agent / Connect / Delete) для ручного построения модели — клик по узлу или ребру открывает редактор в панели деталей (имя, переопределение состояния, вес ребра). Вкладка Structure редактирует типы агентов (схема состояния + rule DSL с встроенными ошибками валидации) и окружение (переменные + потоки источников/стоков). Новые эндпоинты: PUT /api/agents/{id}, PUT /api/interactions/{id}, PUT /api/agent-types/{id} (все проверяются и аудит-логируются). Вкладка Examples загружает курируемые системы в один клик (GET /api/examples, POST /api/examples/{name}): каскад инновационного рынка, луг «хищник–жертва» и двухуровневая сеть поставок (вложенная иерархия) — каждая с пояснением, на что обратить внимание. Оверлей помощи при первом запуске, пояснительные панели на каждой вкладке и подсказки в пустых состояниях направляют новых пользователей; панель эмерджентности показывает самые сильные сдвиги ниже порога (near_misses на GET /api/runs/{id}/emergence), когда события не срабатывают.

Графический холст

Граф системы полностью интерактивен: перетаскивание пустого пространства — панорамирование, колесо мыши — масштабирование (с привязкой к курсору, индикатором масштаба и кнопкой Fit), перетаскивание узлов — их перемещение; позиции сохраняются на сервере (pos_x/pos_y, сохраняются при завершении перетаскивания), а автоматическая раскладка заполняет только узлы без сохранённой позиции. Рёбра показывают стрелки направления, зелёные сплошные / красные пунктирные для положительной / отрицательной связи и подписи весов там, где они несут информацию помимо знака. Узлы подписаны именем

• основным значением состояния после запуска; при наведении появляется подсказка с полным состоянием агента; в углу — легенда типов. Чистые помощники геометрии/раскладки находятся в app/static/graph.js и покрыты юнит-тестами с помощью node --test (см. tests/js/).

Layout

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

License

MIT — © 2026 Vector Stream Systems LLC.