Serving & APIs

6.1 Serving & APIs

REST API

The SDK provides a production-grade REST API built on FastAPI with automatic Swagger UI documentation. The API enables programmatic model submission, run management, parameter sweeps, and live streaming --- making it possible to embed ABM simulations in larger enterprise workflows without requiring Python client code.

Starting the server:

abm-lab serve --model examples/models/gai_kapadia/model.py --port 8080
# Swagger UI: http://localhost:8080/docs

The API exposes 11 endpoints:

Method	Path	Description
GET	/api/v1/health	Health check: status, version, models discovered
GET	/api/v1/models	List all available models with metadata and parameter descriptions
POST	/api/v1/models/{name}/run	Start a simulation run with config overrides, step count, and seed
GET	/api/v1/models/{name}/status	Poll run status (pending, running, completed, failed) with progress
GET	/api/v1/models/{name}/results	Retrieve completed run results: accumulators, agent counts, config
POST	/api/v1/models/{name}/stop	Stop a running simulation gracefully
POST	/api/v1/sweep	Execute a parameter sweep (grid, random, or Sobol strategy)
GET	/api/v1/models/{name}/source	Retrieve model source code
GET	/api/v1/models/{name}/config	Retrieve parsed config.json
GET	/api/v1/models/{name}/architecture	Model architecture: agent types, link types, accumulators, mechanisms
WS	/api/v1/models/{name}/stream	WebSocket: live step-by-step data streaming

The run endpoint accepts a JSON body:

{
  "config_overrides": {"num_banks": 200, "cash_buffer": 0.08},
  "num_steps": 100,
  "seed": 42
}

And returns a run ID that can be used to poll status and retrieve results. The sweep endpoint accepts parameter ranges and a strategy, fans out into multiple runs, and returns a sweep ID with all associated run IDs.

WebSocket Streaming

The SimulationStreamer provides real-time step-by-step data to connected WebSocket clients. It supports five message types:

Type	Content	Use Case
step	Tick number, accumulator values, events	Live dashboard time series
agent	Agent ID, state snapshot, tick	Individual agent monitoring
event	Event type, details, tick	Alerts (defaults, violations)
space2d	Agent positions, field layer data, markers	Continuous space visualisation
complete	Final tick, summary statistics	Run completion notification

The streamer is thread-safe (broadcast() can be called from any thread) and supports background mode (start_background() / stop_background()) for integration with the simulation runtime. The MockStreamer captures all messages in a list for testing.

from simudyne.engine.streaming import SimulationStreamer

streamer = SimulationStreamer(host="localhost", port=8765)
streamer.start_background()
model.set_streamer(streamer)
# Run simulation... clients receive live updates
streamer.stop_background()

Web Dashboard

The Dashboard class provides a browser-based monitoring interface built on FastAPI with Chart.js for live visualisation. It connects to the REST API and WebSocket streaming endpoints to provide a unified view of model execution.

from simudyne.engine.dashboard import Dashboard

dashboard = Dashboard(api_url="http://localhost:8000", port=8050)
dashboard.run()
# Dashboard available at http://localhost:8050

Dashboard pages:

• Home: Lists all discovered models with descriptions and parameter metadata
• Run: Auto-generated parameter forms from Input descriptors, start/stop controls, live progress charts via WebSocket
• Results: Browse completed runs, view accumulator time series, download results as JSON
• Monitor: System health metrics (models discovered, active runs, total runs, error rates)

---