CAS Studio

Ein Studio zum Entwerfen und Simulieren komplexer adaptiver Systeme (CAS) als agentenbasierte Modelle. Sie definieren Agententypen (Zustand + lokale Regeln), verdrahten Agenten zu einem gerichteten, signierten Interaktionsgraphen, geben dem System eine offene Umgebung mit Quellen und Senken und führen eine deterministische, geseedete, synchrone Simulationsengine dagegen aus. Die sieben kanonischen CAS-Eigenschaften sind erstklassige, instrumentierte Features – jede hat explizite Modellkonstrukte und Analyse-Endpunkte, nicht nur Dokumentation.

Reines Python + numpy-Kern. FastAPI + SQLAlchemy + Alembic für die REST-API und Persistenz. Vanilla-JS-Canvas-UI. Keine schweren Abhängigkeiten, keine Netzwerkaufrufe, keine externen Daten.

Schnellstart

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

Öffnen Sie dann http://localhost:8000/ – beim ersten Start gegen eine leere Datenbank wird die Seed-Demo geladen (und audit-logged): Innovationsdiffusion in einem Markt – 40 Agenten auf einem Small-World-Ringgitter mit Innovatoren, früher Mehrheit und Nachzüglern, zwei Skeptikern (Balancing-Loops), zwei adaptiven Preis-Verkäufern und einer information-Quelle in der Umgebung. Zwei benachbarte geseedete Adopter lösen eine S-förmige Adoptionskaskade aus (mittlere Adoption 0,12 → 0,95 über ~11 Schritte) mit markierten Emergenz-Ereignissen am Takeoff; wenn nur ein Seed gesetzt wird, verpufft sie.

Führen Sie die Tests aus:

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

Related MCP server: COMSOL MCP Server

Die sieben CAS-Eigenschaften

1. Emergenz

Makromuster entstehen aus Mikrointeraktionen. Jeder Schritt zeichnet die Engine Makro-Metriken auf: das Mittelfeld jeder Zustandsvariable, Populationsvarianz, aktive-Cluster-Anzahl (zusammenhängende Komponenten von „aktiven“ Agenten – primäre Variable ≥ 0,5 – über den ungerichteten Interaktionsgraphen), einen Ordnungsparameter |2·active_fraction − 1| und eine Moran-I-ähnliche Nachbarkorrelation. GET /api/runs/{id}/emergence liefert die Serie plus markierte Emergenz-Ereignisse: Schritte, in denen der z-Score der Schritt-zu-Schritt-Delta einer Makro-Indikatorvariable 3 überschreitet, während exogene Eingaben konstant waren (keine Injektionen). Ehrlicher Hinweis: Ein z-Score über eine kurze Serie ist ein stumpfer Detektor – behandeln Sie Ereignisse als Hinweise zur Inspektion, nicht als Beweis.

2. Nichtlinearität

POST /api/systems/{id}/sensitivity mit {"param", "deltas": [...], "steps", "seed"} führt die Simulation erneut aus, wobei param um jedes Delta gestört wird, und meldet Antwortverhältnisse |Δoutcome/Δparam| (outcome = finales Mittelfeld der primären Variable). Es kennzeichnet nonlinear (Verhältnisse variieren um >10× über Größenordnungen – superlinearer Bereich), threshold (einige Störungen erzeugen eine Antwort, andere keine) und sign_flip. Parameteradressierung:

Die Seed-Demo hat eine echte Schwelle bei seed_count:innovator:adopted: Ein Seed verpufft (Adoption 0,075), zwei benachbarte Seeds kaskadieren (0,95).

3. Dezentralisierung

Agenten handeln nur auf Basis lokaler Informationen: ihrem eigenen Zustand, gewichteten Mittelwerten der Zustände ihrer direkten In-Nachbarn und Umgebungsvariablen über Flüsse. Das Bedingungsvokabular der Regel-DSL ist abgeschlossen – globaler Zustand ist konstruktionsbedingt nicht darstellbar (es gibt kein „alle Agenten“-Aggregat, keine globale Suche). Selbstorganisation wird durch die Moran-I-ähnliche Nachbarzustandskorrelation in jeder Laufserie verfolgt.

4. Rückkopplungsschleifen

GET /api/systems/{id}/loops zählt elementare Zyklen des gerichteten Interaktionsgraphen auf (Johnson-artige DFS, jeder Zyklus einmal von seinem kleinsten Knoten aus gemeldet; max_len und ein 1000-Zyklen-Limit begrenzen die Aufzählung und melden truncated). Jede Schleife wird als verstärkend (gerade Anzahl negativer Kopplungen) oder balancierend (ungerade Anzahl) klassifiziert, mit Schleifenverstärkung = Produkt der Kantengewichte. Laufzusammenfassungen enthalten pro Schleife Aktivität: den Kantenfluss, der während des Laufs durch die Kanten der Schleife floss, wobei Kantenfluss pro Schritt = |Δ primäre Variable der Quelle| × |Gewicht| (eine Heuristik für „wie viel Änderung entlang dieser Kante propagierte“, keine physikalische Größe).

5. Adaptation

Agententypen können "adaptation": {"target_var", "target_value", "rate"} deklarieren. Jeden Schritt fügt der Agent eine begrenzte Bias zu target_var hinzu; nach dem Schritt wird die Bias durch gradientenfreie Verstärkung aktualisiert: Wenn der Schritt die Variable näher an target_value brachte, behalte und verstärke die Bias (×1,25, begrenzt auf |1,0|), sonst kehre um und dämpfe (×−0,5). Deterministisch gegeben den Seed. Die Verkäufer der Seed-Demo hill-climben price auf diese Weise in Richtung 0,7.

6. Offene Grenzen

Jedes System hat eine Umgebung: benannte Float-Variablen plus Quellen/Senken – {"var": "information", "inflow": 1.0, "outflow_rate": 0.05} wendet v += inflow − outflow_rate·v pro Schritt an. Agenten tauschen mit der Umgebung durch erhaltende Flusseffekte: {"flux": "information", "by": 0.02} bewegt 0,02 Einheiten von der Umgebung in den Agenten (eine Zustandsvariable gleichen Namens); die Umgebung verliert genau das, was Agenten gewinnen (per Test verifiziert). POST /api/runs/{id}/inject mit {"step", "var", "amount"} plant einen exogenen Puls: Es führt das System/Seed/Schritte des Basislaufs erneut aus, wobei der Puls zu diesem Schritt zur Umgebung hinzugefügt wird, und gibt den neuen Lauf plus das Ergebnis-Delta zurück.

7. Verschachtelte Hierarchie

Ein System kann eine parent_id haben; Subsysteme sind vollwertige Systeme mit eigenen Agenten, Regeln und Läufen. GET /api/systems/{id}/rollup aggregiert die Makro-Metriken des letzten Laufs jedes Kindsystems in den Bericht des Elternsystems (agentenanzahlgewichteter Mittelwert der primären Mittelfelder der Kinder).

Regel-DSL

Ein Agententyp hat state (Dict aus Float-Variablen) und rules – eine Liste von {"if": <condition>, "then": [<effect>, ...]}. Die erste passende Regel feuert; spätere Regeln werden in diesem Schritt ignoriert (eine Regel mit "then": [] ist eine absorbierende Zustands-Wache).

Bedingungen:

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

op ∈ > < >= <= ==. neighbor_mean ist der gewichtete Mittelwert Σ wᵢxᵢ / Σ|wᵢ| über In-Nachbarn, die die Variable tragen – also verdünnen negative Gewichte (Skeptiker) den Mittelwert.

Effekte:

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

Einzelne Agenten können eine state_override tragen: Floats oder {"uniform": [lo, hi]}, das einmal pro Lauf aus dem geseedeten RNG des Laufs gesampelt wird (np.random.default_rng(seed)) – das macht den Lauf-Seed aussagekräftig. Gleiches Modell + gleicher Seed → identische Metrikserie (getestet).

Die Engine schreitet synchron voran: Jeder Agent berechnet seinen nächsten Zustand aus demselben Snapshot – keine Update-Reihenfolge-Artefakte (getestet mit einem oszillierenden Zwei-Agenten-Modell).

REST-API

Alle Mutationen werden audit-logged (GET /api/audit).

MCP-Integration

CAS Studio liefert einen MCP (Model Context Protocol) stdio-Server mit, damit KI-Hosts (Cursor, Claude Desktop, …) Systeme direkt entwerfen und simulieren können. Er frontet die REST-API über HTTP – zeigen Sie mit CAS_API_URL auf eine beliebige laufende Instanz (Standard http://127.0.0.1:8000).

Registrieren Sie ihn in der MCP-Konfiguration Ihres Hosts (siehe 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"}
    }
  }
}

Exponierte Werkzeuge (jedes proxyt den passenden REST-Endpunkt oben): list_systems, get_system, list_agent_types, create_agent_type, create_agents (Batch), add_interaction, set_environment_flow, run_simulation, get_run_series, get_emergence_events, list_feedback_loops, run_sensitivity, inject_pulse, get_rollup und describe_cas_properties (der Sieben-Eigenschaften-Leitfaden + Regel-DSL).

KI-Agent

Der KI-Agent-Tab der UI ist ein eingebauter Chat-Agent, der das Studio über ein lokales Ollama-LLM steuert – keine API-Schlüssel, nichts verlässt die Maschine.

Anforderungen: Ollama läuft (ollama serve) und mindestens ein Modell ist installiert, z. B.:

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

Das Modell-Dropdown listet auf, was Ollama als installiert meldet, und wählt standardmäßig qwen3:8b, dann jedes gemma3*, dann llama3.1:8b, dann das erste Modell (GET /api/agent/models). Zeigen Sie den Agenten mit OLLAMA_URL auf einen anderen Ollama-Host (Standard http://127.0.0.1:11434).

POST /api/agent/chat und POST /api/agent/generate laufen als Hintergrundjobs (HTTP 202 {job_id}), sodass langsame lokale LLMs niemals eine Anfrage aufhängen: Pollen Sie GET /api/agent/jobs/{id} auf {status: pending|running|done|error, progress: [...], result|error} — Fortschrittseinträge erscheinen, während die Schleife läuft („round 2: calling run_simulation…", „attempt 2: validation failed: …") und jeder Fehler endet in einem spezifischen, menschenlesbaren Fehler. LLM-Aufrufe verwenden OLLamas natives /api/chat mit think: false (qwen3s Denkmodus ist auf CPU-gebundenem Ollama ~10× langsamer und bringt nichts für Tool-Aufrufe) und die Standard-Rundenbegrenzung ist 5.

POST /api/agent/chat {messages, model?, system_id?, temperature?, max_rounds?} führt eine Tool-Aufruf-Schleife gegen OLLamas /api/chat aus: Das Modell wählt ein Tool, der Server führt es aus (über die gleiche Tool-Registry, die auch der MCP-Server verwendet, app/tools.py), hängt das Ergebnis an und wiederholt — bis zu max_rounds — bis das Modell eine endgültige Antwort schreibt. Das Job-Ergebnis ist {reply, model, tool_trace, rounds}; tool_trace listet jeden Aufruf mit seinen Argumenten und einem gekürzten Ergebnis auf, und die UI rendert es als aufklappbaren Block unter jeder Antwort. Chain-of-Thought ( thinking-Blöcke von qwen3) wird aus Antworten entfernt. Wenn das ausgewählte Modell keine Tool-Aufrufe unterstützt, fällt der Agent auf eine einmalige Antwort ohne Tools mit einem Hinweis zurück; wenn Ollama nicht erreichbar ist, degradiert der Modelle-Endpunkt anmutig und Jobs enden mit einem klaren Fehler.

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?} verwandelt einfaches Englisch in ein laufendes CAS-Modell. Das LLM (Ollama-JSON-Modus) entwirft eine Systemspezifikation — Agententypen mit Regel-DSL-Verhalten, Agentenanzahlen, eine Interaktionstopologie (ring_lattice / random / small_world), signierte Kantengewichte nach Quelltyp, Umgebungsvariablen mit Quellen/Senken und optionale verschachtelte Teilsysteme — geleitet von einer kompakten DSL-Referenz, einem Few-Shot-Beispiel und System-Engineering-Designregeln (Typologie-Zerlegung, mindestens eine verstärkende und eine ausgleichende Schleife, offene Grenzflüsse für erhaltene Größen, Verschachtelung für Systeme von Systemen). Der Server validiert die Spezifikation streng (Schema, der vollständige Regel-DSL-Validator, Topologie-Materialisierung); bei Fehlern werden die Validierungsfehler an das Modell zurückgegeben, bis zu max_rounds Versuche (Standard 3), danach endet der Job mit einem Fehler und den gesammelten Meldungen. Bei Erfolg wird alles über das Repository erstellt (audit-logged als generate_system von ai-agent) und das Ergebnis enthält die neue System-ID, eine Zusammenfassung und die rohe Spezifikation. Dieselbe Fähigkeit wird MCP-Hosts als generate_system_from_description-Tool bereitgestellt (es übermittelt den Job und wartet) und in der UI als Generate system-Modus des AI-Agent-Tabs (mit Live-Fortschritt).

LLM-Einstellungen

Das Zahnrad-Symbol im AI-Agent-Tab öffnet die Einstellungen: temperature (Standard 0.2) und max tool rounds (Standard 8) — pro Anfrage als temperature / max_rounds an sowohl /api/agent/chat als auch /api/agent/generate gesendet — plus die aktive Ollama-URL und ollama pull-Hinweise. Modell-, Temperatur- und Rundenauswahl werden in localStorage gespeichert.

Bearbeiten, Beispiele und geführte UX

Die Leinwand hat eine Bearbeitungssymbolleiste (Select / Add agent / Connect / Delete) für den manuellen Modellaufbau — ein Klick auf einen Knoten oder eine Kante öffnet einen Editor im Detailbereich (Name, Zustandsüberschreibung, Kantengewicht). Der Structure-Tab bearbeitet Agententypen (Zustandsschema + Regel-DSL mit Inline-Validierungsfehlern) und die Umgebung (Variablen + Quellen/Senken-Flüsse). Neue Endpunkte: PUT /api/agents/{id}, PUT /api/interactions/{id}, PUT /api/agent-types/{id} (alle validiert und audit-logged). Der Examples-Tab lädt kuratierte Systeme mit einem Klick (GET /api/examples, POST /api/examples/{name}): die Innovationsmarkt-Kaskade, eine Räuber-Beute-Wiese und ein zweistufiges Liefernetzwerk (verschachtelte Hierarchie) — jeweils mit einem Kurztext, worauf man achten sollte. Ein Erste-Schritte-Hilfe-Overlay, Erklärleisten pro Tab und Hinweise für leere Zustände führen neue Benutzer; das Emergenz-Panel zeigt die stärksten Unterschwellen-Verschiebungen (near_misses auf GET /api/runs/{id}/emergence), wenn keine Ereignisse ausgelöst werden.

Graph-Leinwand

Der Systemgraph ist vollständig interaktiv: Ziehen Sie leeren Raum, um zu schwenken, Mausrad zum Zoomen (am Cursor verankert, mit Zoom-Indikator und einem Fit-Button), ziehen Sie Knoten, um sie neu anzuordnen — Positionen bleiben serverseitig erhalten (pos_x/pos_y, beim Ziehen-Ende gespeichert) und das automatische Layout füllt nur Knoten ohne gespeicherte Position. Kanten zeigen Richtungspfeile, grün durchgezogen / rot gestrichelt für positive / negative Kopplung, und Gewichtsbeschriftungen, wo sie Informationen über das Vorzeichen hinaus tragen. Knoten sind mit Name

• primärem Zustandswert nach einem Lauf beschriftet; beim Überfahren zeigt ein Tooltip den vollständigen Agentenzustand; eine Typenlegende sitzt in der Ecke. Die reinen Geometrie-/Layout-Helfer befinden sich in app/static/graph.js und werden mit node --test unit-getestet (siehe 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

Lizenz

MIT — © 2026 Vector Stream Systems LLC.