CAS Studio

Un estudio para diseñar y simular sistemas adaptativos complejos (CAS) como modelos basados en agentes. Tú defines los tipos de agente (estado + reglas locales), conectas los agentes en un grafo de interacción dirigido y con signo, das al sistema un entorno abierto con fuentes y sumideros, y ejecutas un motor de simulación determinista, con semilla y síncrono. Las siete propiedades canónicas de los CAS son características de primera clase e instrumentadas — cada una tiene constructos de modelo explícitos y endpoints de análisis, no solo documentación.

Núcleo en Python puro + numpy. FastAPI + SQLAlchemy + Alembic para la API REST y la persistencia. Interfaz de canvas en JavaScript puro. Sin dependencias pesadas, sin llamadas de red, sin datos externos.

Inicio rápido

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

Luego abre http://localhost:8000/ — en el primer arranque con una base de datos vacía se carga la demo de semilla (y se registra en auditoría): difusión de innovación en un mercado — 40 agentes en un anillo de mundo pequeño con innovadores, mayoría temprana y adoptantes rezagados, dos escépticos (bucles de equilibrio), dos vendedores con precio adaptativo y una fuente de information en el entorno. Dos adoptantes adyacentes con semilla desencadenan una cascada de adopción en curva S (adopción media 0.12 → 0.95 en ~11 pasos) con eventos de emergencia marcados en el despegue; reducir a una sola semilla hace que se desvanezca.

Ejecuta las pruebas:

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

Related MCP server: COMSOL MCP Server

Las siete propiedades de los CAS

1. Emergencia

Los patrones macro surgen de interacciones micro. En cada paso, el motor registra métricas macro: el campo medio de cada variable de estado, la varianza de la población, el recuento de clústeres activos (componentes conexos de agentes "activos" — variable primaria ≥ 0.5 — sobre el grafo de interacción no dirigido), un parámetro de orden |2·active_fraction − 1| y una correlación de vecinos tipo Moran's-I. GET /api/runs/{id}/emergence devuelve la serie más los eventos de emergencia marcados: pasos donde el z-score del delta paso a paso de un indicador macro supera 3 mientras las entradas exógenas eran constantes (sin inyecciones). Advertencia honesta: un z-score sobre una serie corta es un detector burdo — trata los eventos como indicadores para inspección, no como prueba.

2. No linealidad

POST /api/systems/{id}/sensitivity con {"param", "deltas": [...], "steps", "seed"} vuelve a ejecutar la simulación con param perturbado por cada delta e informa los ratios de respuesta |Δoutcome/Δparam| (outcome = campo medio final de la variable primaria). Marca nonlinear (los ratios varían >10× entre magnitudes — régimen superlineal), threshold (algunas perturbaciones producen respuesta, otras ninguna) y sign_flip. Direccionamiento de parámetros:

La demo de semilla tiene un umbral real en seed_count:innovator:adopted: una semilla se desvanece (adopción 0.075), dos semillas adyacentes cascada (0.95).

3. Descentralización

Los agentes actúan solo con información local: su propio estado, medias ponderadas del estado de sus vecinos entrantes directos y variables del entorno mediante flujo. El vocabulario de condiciones del DSL de reglas es cerrado — el estado global es irrepresentable por construcción (no hay agregado de "todos los agentes", no hay búsqueda global). La autoorganización se rastrea mediante la correlación de estado de vecinos tipo Moran's-I en la serie de cada ejecución.

4. Bucles de retroalimentación

GET /api/systems/{id}/loops enumera los ciclos elementales del grafo de interacción dirigido (DFS estilo Johnson, cada ciclo se informa una vez desde su nodo más pequeño; max_len y un límite de 1000 ciclos acotan la enumeración e informan truncated). Cada bucle se clasifica como reforzador (número par de acoplamientos negativos) o equilibrador (número impar) con ganancia de bucle = producto de los pesos de las aristas. Los resúmenes de ejecución incluyen actividad por bucle: el flujo de arista que circuló por las aristas de cada bucle durante la ejecución, donde el flujo de arista por paso = |Δ variable primaria de la fuente| × |peso| (una heurística para "cuánto cambio se propagó a lo largo de esta arista", no una cantidad física).

5. Adaptación

Los tipos de agente pueden declarar "adaptation": {"target_var", "target_value", "rate"}. En cada paso, el agente añade un sesgo acotado a target_var; después del paso, el sesgo se actualiza mediante refuerzo sin gradiente: si el paso acercó la variable a target_value, se mantiene y amplifica el sesgo (×1.25, con tope en |1.0|); si no, se invierte y se atenúa (×−0.5). Determinista dada la semilla. Los vendedores de la demo de semilla escalan price hacia 0.7 de esta manera.

6. Fronteras abiertas

Todo sistema tiene un entorno: variables flotantes con nombre más fuentes/sumideros — {"var": "information", "inflow": 1.0, "outflow_rate": 0.05} aplica v += inflow − outflow_rate·v por paso. Los agentes intercambian con el entorno mediante efectos de flujo conservativo: {"flux": "information", "by": 0.02} mueve 0.02 unidades del entorno al agente (una variable de estado del mismo nombre); el entorno pierde exactamente lo que los agentes ganan (verificado por prueba). POST /api/runs/{id}/inject con {"step", "var", "amount"} programa un pulso exógeno: vuelve a ejecutar el sistema/semilla/pasos de la ejecución base con el pulso añadido al entorno en ese paso, y devuelve la nueva ejecución más el delta de resultado.

7. Jerarquía anidada

Un System puede tener un parent_id; los subsistemas son sistemas completos con sus propios agentes, reglas y ejecuciones. GET /api/systems/{id}/rollup agrega las métricas macro de la última ejecución de cada sistema hijo en el informe del padre (media ponderada por número de agentes de los campos medios primarios de los hijos).

DSL de reglas

Un tipo de agente tiene state (dict de variables flotantes) y rules — una lista de {"if": <condition>, "then": [<effect>, ...]}. La primera regla que coincida se dispara; las reglas posteriores se ignoran en ese paso (una regla con "then": [] es una guarda de estado absorbente).

Condiciones:

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

op ∈ > < >= <= ==. neighbor_mean es la media ponderada Σ wᵢxᵢ / Σ|wᵢ| sobre los vecinos entrantes que tienen la variable — así, los vecinos con peso negativo (escépticos) diluyen la media.

Efectos:

{"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

Los agentes individuales pueden llevar un state_override: flotantes, o {"uniform": [lo, hi]} que se muestrea una vez por ejecución desde el RNG con semilla de la ejecución (np.random.default_rng(seed)) — esto es lo que hace que la semilla de ejecución sea significativa. Mismo modelo + misma semilla → series de métricas idénticas (probado).

El motor avanza síncronamente: cada agente calcula su siguiente estado a partir de la misma instantánea — sin artefactos de orden de actualización (probado con un modelo oscilante de dos agentes).

API REST

Todas las mutaciones se registran en auditoría (GET /api/audit).

Integración MCP

CAS Studio incluye un servidor stdio MCP (Model Context Protocol) para que los hosts de IA (Cursor, Claude Desktop, …) puedan diseñar y simular sistemas directamente. Actúa como fachada de la API REST sobre HTTP — apúntalo a cualquier instancia en ejecución con CAS_API_URL (por defecto http://127.0.0.1:8000).

Regístralo en la configuración MCP de tu host (ver 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"}
    }
  }
}

Herramientas expuestas (cada una hace de proxy del endpoint REST correspondiente de arriba): list_systems, get_system, list_agent_types, create_agent_type, create_agents (lote), add_interaction, set_environment_flow, run_simulation, get_run_series, get_emergence_events, list_feedback_loops, run_sensitivity, inject_pulse, get_rollup y describe_cas_properties (la guía de las siete propiedades + DSL de reglas).

Agente de IA

La pestaña AI Agent de la UI es un agente de chat integrado que maneja el estudio mediante un LLM local Ollama — sin claves de API, nada sale de la máquina.

Requisitos: Ollama en ejecución (ollama serve) y al menos un modelo, por ejemplo:

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

El desplegable de modelos lista lo que Ollama reporta como instalado y usa por defecto qwen3:8b, luego cualquier gemma3*, luego llama3.1:8b, y luego el primer modelo (GET /api/agent/models). Apunta el agente a otro host de Ollama con OLLAMA_URL (por defecto http://127.0.0.1:11434).

POST /api/agent/chat y POST /api/agent/generate se ejecutan como trabajos en segundo plano (HTTP 202 {job_id}) para que los LLM locales lentos nunca bloqueen una solicitud: consulta GET /api/agent/jobs/{id} para obtener {status: pending|running|done|error, progress: [...], result|error} — las entradas de progreso aparecen mientras se ejecuta el bucle ("ronda 2: llamando a run_simulation…", "intento 2: validación fallida: …") y cada fallo termina en un error específico legible por humanos. Las llamadas al LLM usan el /api/chat nativo de Ollama con think: false (el modo de pensamiento de qwen3 es ~10× más lento en Ollama limitado por CPU y no aporta nada a las llamadas de herramientas) y el límite de rondas por defecto es 5.

POST /api/agent/chat {messages, model?, system_id?, temperature?, max_rounds?} ejecuta un bucle de llamada a herramientas contra el /api/chat de Ollama: el modelo elige una herramienta, el servidor la ejecuta (a través del mismo registro de herramientas que usa el servidor MCP, app/tools.py), añade el resultado y repite — hasta max_rounds — hasta que el modelo escribe una respuesta final. El resultado del trabajo es {reply, model, tool_trace, rounds}; tool_trace lista cada llamada con sus argumentos y un resultado recortado, y la interfaz lo muestra como un bloque plegable debajo de cada respuesta. El razonamiento encadenado (bloques thinking de qwen3) se elimina de las respuestas. Si el modelo seleccionado no admite llamadas a herramientas, el agente recurre a una respuesta de un solo disparo sin herramientas con una nota; si Ollama está caído, el endpoint de modelos se degrada con elegancia y los trabajos terminan con un error claro.

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?} convierte el inglés sencillo en un modelo CAS en ejecución. El LLM (modo JSON de Ollama) redacta una especificación del sistema — tipos de agente con comportamiento de regla-DSL, recuentos de agentes, una topología de interacción (ring_lattice / random / small_world), pesos de aristas con signo por tipo de fuente, variables de entorno con fuentes/sumideros y sistemas hijos anidados opcionales — guiado por una referencia DSL compacta, un ejemplo de pocas muestras y reglas de diseño de ingeniería de sistemas (descomposición tipológica, al menos un bucle de refuerzo y uno de equilibrio, flujos de frontera abierta para cantidades conservadas, anidamiento para sistemas de sistemas). El servidor valida la especificación de forma estricta (esquema, el validador DSL de reglas completo, materialización de topología); en caso de fallo, los errores de validación se devuelven al modelo, hasta max_rounds intentos (por defecto 3), tras lo cual el trabajo termina en error con los mensajes recopilados. En caso de éxito, todo se crea a través del repositorio (registrado en auditoría como generate_system por ai-agent) y el resultado lleva el nuevo id del sistema, un resumen y la especificación en bruto. La misma capacidad se expone a los hosts MCP como la herramienta generate_system_from_description (envía el trabajo y espera), y en la interfaz como el modo Generate system de la pestaña AI Agent (con progreso en vivo).

Configuración del LLM

El botón de engranaje en la pestaña AI Agent abre la configuración: temperature (por defecto 0.2) y max tool rounds (por defecto 8) — enviados por solicitud como temperature / max_rounds tanto a /api/agent/chat como a /api/agent/generate — además de la URL activa de Ollama y sugerencias de ollama pull. Las elecciones de modelo, temperatura y rondas se guardan en localStorage.

Edición, ejemplos y UX guiada

El lienzo tiene una barra de herramientas de edición (Select / Add agent / Connect / Delete) para la construcción manual de modelos: al hacer clic en un nodo o arista se abre un editor en el panel de detalles (nombre, anulación de estado, peso de arista). La pestaña Structure edita los tipos de agente (esquema de estado + DSL de reglas con errores de validación en línea) y el entorno (variables + flujos de fuente/sumidero). Nuevos endpoints: PUT /api/agents/{id}, PUT /api/interactions/{id}, PUT /api/agent-types/{id} (todos validados y registrados en auditoría). La pestaña Examples carga sistemas seleccionados con un clic (GET /api/examples, POST /api/examples/{name}): la cascada de mercado de innovación, un prado depredador–presa y una red de suministro de dos niveles (jerarquía anidada) — cada uno con una descripción de qué observar. Una superposición de ayuda para la primera ejecución, barras explicativas por pestaña y sugerencias de estado vacío guían a los nuevos usuarios; el panel de emergencia muestra los cambios sub-umbral más fuertes (near_misses en GET /api/runs/{id}/emergence) cuando no se disparan eventos.

Lienzo del grafo

El grafo del sistema es totalmente interactivo: arrastra el espacio vacío para panorámica, la rueda del ratón para zoom (anclado en el cursor, con un indicador de zoom y un botón Fit), arrastra los nodos para reorganizarlos — las posiciones persisten en el servidor (pos_x/pos_y, guardadas al final del arrastre) y el auto-diseño solo rellena los nodos sin una posición guardada. Las aristas muestran flechas de dirección, verde sólido / rojo discontinuo para acoplamiento positivo / negativo, y etiquetas de peso donde llevan información más allá del signo. Los nodos se etiquetan con el nombre

• valor de estado primario después de una ejecución; al pasar el cursor se muestra un tooltip con el estado completo del agente; una leyenda de tipos se encuentra en la esquina. Los ayudantes de geometría/diseño puro viven en app/static/graph.js y se prueban unitariamente con node --test (ver 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.