CAS Studio

복잡적응시스템(CAS)을 에이전트 기반 모델로 설계하고 시뮬레이션하기 위한 스튜디오입니다. 에이전트 유형(상태 + 로컬 규칙)을 정의하고, 에이전트를 방향성 있는 부호화 상호작용 그래프로 연결하고, 소스와 싱크가 있는 개방 환경을 시스템에 부여한 다음, 결정적이고 시드 기반이며 동기화된 시뮬레이션 엔진으로 실행합니다. 일곱 가지 표준 CAS 속성은 일급 객체로 계측된 기능입니다. 각 속성은 명시적인 모델 구성 요소 그리고 분석 엔드포인트를 가지며, 단순한 문서화에 그치지 않습니다.

순수 Python + numpy 코어. REST API 및 영속성을 위한 FastAPI + SQLAlchemy + Alembic. 바닐라 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개 에이전트로, 혁신가, 조기 다수, 지각 채택자, 두 명의 회의론자(균형 루프), 두 명의 적응형 가격 공급업체, 그리고 환경에 information 소스가 있습니다. 인접한 두 개의 시드 채택자는 S-곡선 채택 폭포(평균 채택률 0.12 → 약 11단계에 걸쳐 0.95)를 촉발하며, 이륙 시점에 플래그가 지정된 창발 이벤트가 발생합니다. 단일 시드로 줄이면 실패합니다.

테스트 실행:

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

Related MCP server: COMSOL MCP Server

일곱 가지 CAS 속성

1. 창발성(Emergence)

미시적 상호작용에서 거시적 패턴이 발생합니다. 엔진은 매 단계마다 거시 지표를 기록합니다: 모든 상태 변수의 평균장(mean field), 모집단 분산, 활성 클러스터 수(무방향 상호작용 그래프에서 "활성" 에이전트 — 기본 변수 ≥ 0.5 — 의 연결 성분), 질서 파라미터 |2·활성 비율 − 1|, 그리고 Moran's-I 유사 이웃 상관관계. GET /api/runs/{id}/emergence는 시리즈와 함께 플래그가 지정된 창발 이벤트를 반환합니다: 외생 입력이 일정했을 때(주입 없음) 거시 지표의 단계별 델타 z-점수가 3을 초과하는 단계입니다. 정직한 경고: 짧은 시리즈에 대한 z-점수는 둔감한 탐지기입니다 — 이벤트를 증명이 아닌 검사용 플래그로 취급하십시오.

2. 비선형성(Nonlinearity)

POST /api/systems/{id}/sensitivity에 {"param", "deltas": [...], "steps", "seed"}를 보내면 param을 각 델타만큼 교란하여 시뮬레이션을 재실행하고 응답 비율 |Δ결과/Δparam|(결과 = 기본 변수의 최종 평균장)을 보고합니다. nonlinear(비율이 크기 간 10배 이상 변동 — 초선형 영역), threshold(일부 교란은 응답을 생성하고 다른 교란은 없음), sign_flip을 플래그로 표시합니다. 파라미터 주소 지정:

시드 데모에는 seed_count:innovator:adopted에 실제 임계값이 있습니다: 시드 1개는 실패(채택률 0.075), 인접한 시드 2개는 폭포(0.95).

3. 분산성(Decentralization)

에이전트는 로컬 정보에만 기반하여 행동합니다: 자신의 상태, 직접적인 인-이웃 상태의 가중 평균, 그리고 플럭스를 통한 환경 변수. 규칙 DSL의 조건 어휘는 폐쇄적입니다 — 전역 상태는 구조적으로 표현 불가능합니다("모든 에이전트" 집계도, 전역 조회도 없음). 자기 조직화는 모든 실행 시리즈의 Moran's-I 유사 이웃 상태 상관관계로 추적됩니다.

4. 피드백 루프(Feedback loops)

GET /api/systems/{id}/loops는 방향성 상호작용 그래프의 기본 사이클을 열거합니다(Johnson 스타일 DFS, 각 사이클은 가장 작은 노드에서 한 번만 보고됨; max_len과 1000사이클 상한이 열거를 제한하고 truncated를 보고). 각 루프는 강화형(음의 커플링 짝수 개) 또는 균형형(홀수 개)으로 분류되며 루프 이득 = 에지 가중치의 곱입니다. 실행 요약에는 루프별 활동도가 포함됩니다: 실행 중 해당 루프의 에지를 통해 흐른 에지 플럭스. 여기서 단계별 에지 플럭스 = |소스의 기본 변수 Δ| × |가중치|("이 에지를 따라 얼마나 많은 변화가 전파되었는지"에 대한 휴리스틱이며, 물리적 양이 아닙니다).

5. 적응(Adaptation)

에이전트 유형은 "adaptation": {"target_var", "target_value", "rate"}를 선언할 수 있습니다. 매 단계 에이전트는 target_var에 경계가 있는 바이어스를 추가합니다. 단계 후 바이어스는 그래디언트 없는 강화로 업데이트됩니다: 단계가 변수를 target_value에 더 가깝게 이동시켰다면 바이어스를 유지하고 증폭(×1.25, |1.0| 상한), 그렇지 않으면 반전하고 감쇠(×−0.5). 시드가 주어지면 결정적입니다. 시드 데모의 공급업체는 이 방식으로 price를 0.7을 향해 언덕 오르기합니다.

6. 개방 경계(Open boundaries)

모든 시스템에는 환경이 있습니다: 명명된 부동소수점 변수와 소스/싱크 — {"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. 중첩 계층(Nested hierarchy)

System은 parent_id를 가질 수 있습니다. 하위 시스템은 자체 에이전트, 규칙 및 실행을 가진 완전한 시스템입니다. GET /api/systems/{id}/rollup은 각 하위 시스템의 최신 실행 거시 지표를 상위 보고서에 집계합니다(하위 시스템의 기본 평균장의 에이전트 수 가중 평균).

규칙 DSL

에이전트 유형은 state(부동소수점 변수의 dict)와 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]} — 실행의 시드 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(일곱 속성 가이드 + 규칙 DSL).

AI 에이전트

UI의 AI 에이전트 탭은 로컬 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_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가 다운되면 모델 엔드포인트는 정상적으로 저하되고 작업은 명확한 오류로 종료됩니다.

POST /api/agent/generate {description, name?, model?, system_id?, temperature?, max_rounds?}는 평범한 영어를 실행 중인 CAS 모델로 변환합니다. LLM(Ollama JSON 모드)은 컴팩트한 DSL 참조, 퓨샷 예제, 시스템 엔지니어링 설계 규칙(유형 분해, 최소 하나의 강화 루프와 하나의 균형 루프, 보존 수량에 대한 개방 경계 흐름, 시스템 오브 시스템스를 위한 중첩)에 따라 시스템 사양을 초안합니다. 에이전트 유형(규칙 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/ 참조).

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.