Public API Reference

Status: Alpha
Audience: ABMForge users, contributors, reviewers, and downstream research projects.

This page documents the main public API exported by the root abmforge package and the most important user-facing subpackages.

ABMForge is still alpha-stage software. Most documented APIs should be treated as provisional until the project reaches beta or 1.0.

For compatibility expectations, see the API stability policy.

Import Convention

Most user-facing projects should start with root imports:

from abmforge import Agent, Experiment, Model, Scenario

Use subpackage imports when you need a specific scheduler, space, storage helper, or method module.

Stability Legend

Label	Meaning
Stable	Intended to remain compatible within a major release line. Very limited during alpha.
Provisional	Intended for normal users, but may change before beta or 1.0.
Experimental	Useful for exploration; may change more quickly.
Internal	Not part of the documented public contract.

Core Modelling API

Agent

Status: Provisional
Import: from abmforge import Agent

Base class for individual agents.

Use it when defining agent-level state and behavior.

Typical responsibilities:

• hold agent attributes;
• implement step();
• interact with other agents;
• read model parameters;
• use model-level random number generation;
• request spawn/remove behavior through the model or collection API.

Model

Status: Provisional
Import: from abmforge import Model

Base class for simulation models.

Typical responsibilities:

• initialize agents and spaces in setup();
• advance the model in step();
• own model parameters;
• own the model-level random number generator;
• configure recorders;
• manage simulation time and status.

See Model Lifecycle for execution statuses, terminal-state invariants, continuation rules, and restart restrictions.

Minimal shape:

from abmforge import Agent, Model


class Person(Agent):
    def step(self) -> None:
        self.wealth += 1


class WealthModel(Model):
    def setup(self) -> None:
        self.agents.create(Person, n=10, wealth=0)

    def step(self) -> None:
        self.agents.do("step")

AgentCollection

Status: Provisional
Import: from abmforge import AgentCollection

Container and helper API for model agents.

Common uses:

• create agents;
• iterate over agents;
• apply methods to all agents;
• shuffle activation;
• filter or aggregate agent attributes;
• query by type or state.

Experiment API

Scenario

Status: Provisional
Import: from abmforge import Scenario

A single model run configuration.

A scenario usually combines:

• model class;
• parameters;
• seed;
• number of steps;
• optional name;
• optional stop condition.

Example:

from abmforge import Scenario

scenario = Scenario(
    model=WealthModel,
    parameters={"population": 10},
    seed=42,
    steps=5,
    name="baseline",
)

result = scenario.run()

Scenario YAML schema API

Status: Provisional

Import: from abmforge.experiment import SCENARIO_SCHEMA_VERSION, ScenarioSchemaV1, ScenarioValidationError, StopConditionV1

ScenarioSchemaV1 is the strict validator and normalized representation for abmforge.scenario.v1 YAML documents.

ScenarioValidationError is the field-oriented validation exception used by Python and CLI workflows.

StopConditionV1 represents the safe declarative run.stop contract. It supports scalar comparisons without evaluating arbitrary Python expressions.

ScenarioSchemaV1 also supports the optional inputs mapping with inputs.root and inputs.artifacts. Scenario.from_yaml(...) resolves these portable paths relative to the Scenario YAML file and passes them to the runtime Scenario as input_root and input_artifacts. The declared files therefore participate in DeclaredInputIdentityV1 and ExecutionFingerprintV3.

Programmatic Scenario(...) construction remains available and does not require a YAML schema declaration. schema_version identifies the serialized YAML contract.

Experiment

Status: Provisional
Import: from abmforge import Experiment

A multi-run experiment configuration.

Use it for:

• parameter sweeps;
• multiple seeds;
• stochastic replicates;
• comparative scenarios.

ExperimentExecutionError

Status: Stable Alpha Import: from abmforge import ExperimentExecutionError

Raised when fail-fast experiment execution stops after a failed run.

The exception preserves:

• result: the partial ExperimentResult, including completed runs and the failed run;
• failed_result: the RunResult that caused execution to stop;
• the original exception through __cause__.

Runs that were not reached are not added to the partial result.

from abmforge import ExperimentExecutionError

try:
    result = experiment.run()
except ExperimentExecutionError as exc:
    partial_result = exc.result
    failed_run = exc.failed_result

ExperimentResult

Status: Provisional
Import: from abmforge import ExperimentResult

Container for multi-run experiment results.

Typical uses:

• summarize runs;
• write CSV tables;
• collect model records;
• collect agent records;
• inspect failed runs.

RunResult

Status: Provisional
Import: from abmforge import RunResult

Container for one run result.

Typical fields include:

• run status;
• number of completed steps;
• dataset;
• stop reason;
• error information when a run fails.

ParameterGrid

Status: Provisional
Import: from abmforge import ParameterGrid

Helper for expanding parameter combinations.

ExperimentArchive

Status: Provisional
Import: from abmforge import ExperimentArchive

Directory-based experiment archive API.

Use it to:

• create archive roots;
• write scenario or experiment configuration files;
• write dataset tables;
• write schema and manifest files;
• validate archives;
• read run indexes.

ExperimentRegistry

Status: Experimental
Import: from abmforge import ExperimentRegistry

Registry helper for tracking experiment archive components and runs.

This API may evolve as archive migration and resumable experiments mature.

Data and Recording API

Dataset

Status: Provisional
Import: from abmforge import Dataset

Structured simulation output container.

Standard logical tables include:

• runs;
• model_records;
• agent_records;
• event_records;
• lifecycle_records;
• errors.

ExperimentDataset

Status: Provisional Import: from abmforge.data import ExperimentDataset

DuckDB-backed SQL query interface for ABMForge Parquet archives.

The input path may reference either the archive root or its data/ directory. query(...) returns a pandas DataFrame.

Install the required optional dependencies with:

pip install "abmforge[data]"

ExperimentDatasetError

Status: Provisional Import: from abmforge.data import ExperimentDatasetError

Base exception for experiment dataset query failures.

ExperimentDatasetDependencyError

Status: Provisional Import: from abmforge.data import ExperimentDatasetDependencyError

Raised when DuckDB is unavailable.

ExperimentDatasetTableNotFoundError

Status: Provisional Import: from abmforge.data import ExperimentDatasetTableNotFoundError

Raised when a required Parquet table is absent. This exception is also a FileNotFoundError.

ExperimentDatasetTableError

Status: Provisional Import: from abmforge.data import ExperimentDatasetTableError

Raised when a present Parquet table cannot be registered or read.

ExperimentDatasetQueryError

Status: Provisional Import: from abmforge.data import ExperimentDatasetQueryError

Raised when SQL parsing, binding, or execution fails.

Recorder

Status: Provisional
Import: from abmforge import Recorder

Model-attached recording helper.

Use it to record:

• model-level metrics;
• agent-level attributes;
• lifecycle events;
• event records;
• error records.

DatasetSchemaV1

Status: Provisional
Import: from abmforge import DatasetSchemaV1

Dataset schema validator and contract helper.

DATASET_SCHEMA_VERSION

Status: Provisional
Import: from abmforge import DATASET_SCHEMA_VERSION

Current dataset schema version identifier.

SchemaValidationError

Status: Provisional
Import: from abmforge import SchemaValidationError

Raised for dataset schema validation failures.

Scheduling API

Scheduler

Status: Provisional
Import: from abmforge import Scheduler

Base scheduler abstraction.

SequentialActivation

Status: Provisional
Import: from abmforge import SequentialActivation

Activates agents in collection order.

RandomActivation

Status: Provisional
Import: from abmforge import RandomActivation

Activates agents in random order using the model-level random generator.

SimultaneousActivation

Status: Provisional
Import: from abmforge import SimultaneousActivation

Supports staged simultaneous-style activation.

StagedActivation

Status: Provisional
Import: from abmforge import StagedActivation

Runs named activation stages in order.

Time and Event API

Event

Status: Provisional
Import: from abmforge import Event

Scheduled event object.

EventQueue

Status: Provisional
Import: from abmforge import EventQueue

Priority queue for scheduled events.

The built-in fixed-step execution profile accepts only finite, integer-valued event ticks. schedule_at(...) rejects fractional or past ticks, while schedule_after(...) rejects fractional or negative delays. Boolean values, strings, and objects accepted only through implicit numeric coercion are rejected.

Integer-valued floats such as 1.0 are accepted. Advanced same-tick phase behavior, hybrid or continuous-time execution, and executable event replay remain provisional.

Space API

GridWorld

Status: Provisional
Import: from abmforge import GridWorld

Grid-based space.

NetworkSpace

Status: Provisional
Import: from abmforge import NetworkSpace

Network-based space.

ContinuousSpace

Status: Provisional
Import: from abmforge import ContinuousSpace

Continuous coordinate space.

GISSpace

Status: Experimental
Import: from abmforge import GISSpace

Lightweight GIS-oriented space.

GIS support is intentionally limited during alpha.

ODD and Methods API

ODDDocument

Status: Provisional
Import: from abmforge import ODDDocument

Structured ODD-style model documentation helper.

Generated ODD files are skeleton documents and require manual scientific review.

Sensitivity Analysis API

SALibProblem

Status: Experimental
Import: from abmforge import SALibProblem

Problem specification helper for SALib-style sensitivity analysis.

SensitivityAnalysis

Status: Experimental
Import: from abmforge import SensitivityAnalysis

Sensitivity analysis helper.

sample_sobol

Status: Experimental
Import: from abmforge import sample_sobol

Generate Sobol samples.

analyze_sobol

Status: Experimental
Import: from abmforge import analyze_sobol

Analyze Sobol outputs.

sample_morris

Status: Experimental
Import: from abmforge import sample_morris

Generate Morris samples.

analyze_morris

Status: Experimental
Import: from abmforge import analyze_morris

Analyze Morris outputs.

Reproducibility API

ExecutionFingerprintV3

Status: Provisional

Import: from abmforge.repro import ExecutionFingerprintV3

Current integrity-checked execution identity used by safe experiment recovery. V3 binds the planned execution to model-source identity, canonical parameters, the ABMForge framework version and package-tree SHA-256, and the canonical declared-input-identity-v1 for explicitly declared input files.

Scenario.execution_fingerprint() produces V3 fingerprints. Automatic recovery trusts matching V3 fingerprints and fails closed for legacy V1/V2 identities, malformed fingerprints, changed framework source, changed model source, or changed declared input bytes.

ExecutionFingerprintV2

Status: Provisional Import: from abmforge.repro import ExecutionFingerprintV2

Previous framework-aware execution-identity schema. V2 remains available for reading, validating, and testing historical identity payloads, but current Scenario executions produce V3 and the V3 recovery planner does not automatically reuse archived V2 fingerprints.

ExecutionFingerprintV1 remains available as a legacy schema for reading and validating older identity payloads, but V1 fingerprints are not automatically reusable by the V2 recovery planner.

ReproducibilityManifest

Status: Provisional
Import: from abmforge import ReproducibilityManifest

Manifest helper for reproducibility metadata. from_run_result() can record model-source repository provenance and explicitly declared external input files:

manifest = ReproducibilityManifest.from_run_result(
    result,
    input_artifacts=["study/data/observations.csv"],
    input_root="study",
)

Use from_run_result() rather than from_dataset() when the manifest must identify the executed model's defining repository.

SourceRepositoryProvenanceV1

Status: Provisional

Import: from abmforge.repro import SourceRepositoryProvenanceV1

Collects source-repository-provenance-v1 metadata from a model class or instance. Git discovery starts from the defining source file, and the record includes a source-file SHA-256 even when the source is outside Git.

InputArtifactProvenanceV1

Status: Provisional

Import: from abmforge.repro import InputArtifactProvenanceV1

Creates one input-artifact-v1 record containing a portable path, file size, role, and SHA-256 digest. With root=..., resolved files must remain inside the root; path traversal and symlink escape are rejected.

Replay and Snapshot API

Replay is currently experimental.

write_snapshot

Status: Experimental
Import: from abmforge import write_snapshot

Write a model snapshot.

read_snapshot

Status: Experimental
Import: from abmforge import read_snapshot

Read a model snapshot.

snapshot_hash

Status: Experimental
Import: from abmforge import snapshot_hash

Compute a deterministic hash from the canonical snapshot representation.

With include_metadata=False, framework provenance and structural type metadata are excluded while user-controlled parameters, model state, and agent state remain part of the hash.

attach_snapshot_hash

Status: Experimental
Import: from abmforge import attach_snapshot_hash

Attach a hash to snapshot metadata.

link_snapshot

Status: Experimental
Import: from abmforge import link_snapshot

Link snapshot metadata to a run or archive.

validate_replay

Status: Experimental Import: from abmforge import validate_replay

Compare original and replayed snapshots using the same canonical normalization for hashing and structural difference analysis.

By default, framework-managed metadata is ignored. Pass include_metadata=True to compare it explicitly.

ReplayValidationReport

Status: Experimental Import: from abmforge import ReplayValidationReport

Report object for replay validation.

A report with valid=False contains at least one explanatory entry in differences. Difference entries identify normalized paths such as $.model_state.population or $.agents[0].state.wealth.

Visualization API

Visualization helpers are optional convenience APIs.

plot_timeseries

Status: Experimental
Import: from abmforge import plot_timeseries

Plot a time series.

plot_multiple_runs

Status: Experimental
Import: from abmforge import plot_multiple_runs

Plot multiple run outputs.

plot_grid

Status: Experimental
Import: from abmforge import plot_grid

Plot a grid model state.

Version API

__version__

Status: Provisional
Import: from abmforge import __version__

Current ABMForge package version.

Full Public Export Checklist

The following names are exported from the root abmforge package and should remain documented while they are part of abmforge.__all__:

• Agent
• AgentCollection
• ContinuousSpace
• Recorder
• Dataset
• DATASET_SCHEMA_VERSION
• DatasetSchemaV1
• Event
• EventQueue
• Experiment
• ExperimentArchive
• ExperimentRegistry
• ExperimentResult
• GISSpace
• GridWorld
• Model
• NetworkSpace
• ODDDocument
• ParameterGrid
• RandomActivation
• ReplayValidationReport
• ReproducibilityManifest
• RunResult
• SALibProblem
• Scenario
• Scheduler
• SchemaValidationError
• SensitivityAnalysis
• SequentialActivation
• SimultaneousActivation
• StagedActivation
• __version__
• analyze_morris
• analyze_sobol
• attach_snapshot_hash
• link_snapshot
• plot_grid
• plot_multiple_runs
• plot_timeseries
• read_snapshot
• sample_morris
• sample_sobol
• snapshot_hash
• validate_replay
• write_snapshot

Internal APIs

The following should generally be treated as internal unless documented elsewhere:

• underscore-prefixed modules, classes, functions, or variables;
• implementation helpers;
• test fixtures;
• private archive helpers;
• storage implementation details not listed in the public docs;
• experimental plugin prototypes.

Documentation Contract

When a new symbol is added to abmforge.__all__, this page should be updated. When a public symbol is removed or renamed, the API stability policy and changelog should be updated as appropriate.

Typed-agent protocols

These provisional protocol helpers provide a backward-compatible typed-agent layer without replacing the dynamic base Agent class.

• AgentID
• AgentLike
• SteppableAgent
• AdvanceableAgent
• StatefulAgent