Architecture
2.1 Architecture
The engine is organised into seven functional layers. Each layer depends only on layers below it, enforcing a clean dependency hierarchy that prevents circular imports and makes it possible to use lower layers without pulling in higher-level concerns.
Layer 1 --- Core Primitives provides the fundamental building blocks: Agent, Message, Link, Action, Sequence, Split, ABMModel, GlobalState, Accumulator, SeedManager, GridSpace, NetworkSpace, Space2D, Environment, and partitioning strategies. These modules have no dependencies beyond NumPy and the standard library. Every model in the SDK is built from these primitives.
Layer 2 --- Infrastructure provides the machinery that runs models: eight pluggable ExecutionBackend implementations (LocalBackend, ThreadPoolBackend, ProcessPoolBackend, MCPBackend, EmulatorBackend, AsyncBackend, PregelBackend, DaskBackend), the ABMSettings configuration loader, the Input/Variable/Constant parameter descriptor system, the OutputRecorder and SimulationRecorder for time series output, OutputSQL for database sinks, and State for snapshots.
Layer 3 --- Evaluation & Intelligence provides tools for running and assessing models: MCRunner and ProcessPoolMCRunner for Monte Carlo evaluation, ExperimentRunner for parameter sweeps (grid, Latin hypercube, Sobol), 27 standard statistical metrics (21 core + 6 generic aliases), DeterminismChecker for reproducibility verification, LLMAgent and HybridAgent for AI-powered decisions, RLAgent for reinforcement learning, ActivityScheduler for multi-phase steps, CheckpointManager for state persistence, and WebSocket streaming for live output.
Layer 4 --- Analytical provides the scientific validation and calibration framework: the generic Feature/FeatureSet protocol with three domain-specific feature libraries (financial, supply chain, epidemiology), the statistics module with two-sample tests and distribution distances, ABCSMCCalibrator for Bayesian calibration, AblationRunner for mechanism testing, and NestedMCRunner with nested ANOVA for LLM-ABM variance decomposition.
Layer 5 --- Observability & Safety provides runtime instrumentation: HookRegistry with 11 lifecycle events, GuardrailRegistry with four built-in guardrail types, OpenTelemetry integration (5 span types, 7 Prometheus metrics), AgentMemory for persistent agent state, AuditTrail for decision logging, and InvocationState for execution tracking.
Layer 6 --- Distribution provides multi-process and multi-machine execution: MCPServer (FastAPI partition servers), MCPOrchestrator (distributed step coordination), A2ARouter (cross-partition agent-to-agent routing), EmulatorBackend (in-process distributed testing), ModelRegistry for model discovery, GraphBuilder for declarative model topology construction, and RunStore for persistent run metadata.
Layer 7 --- Applications provides user-facing interfaces: the abm-lab CLI, the FastAPI REST API (8 endpoints + WebSocket), the web dashboard, TestKit utilities, Validator for model validation, Chat for conversational model interaction, Scenario for named parameter presets, and two visualisation backends (Matplotlib with 15 chart types, Plotly with interactive charts).
The engine totals 61 modules across these seven layers.