babylon.models.snapshots

Snapshot types for the MVP simulation engine.

These are immutable representations of simulation state at a point in time. They are designed for the GUI interface and differ from internal simulation entities which may be mutable.

Available types: - HexState: Immutable geographic cell (H3 index only for MVP) - EdgeState: Relationship snapshot (source, target, type, weight) - TerritoryState: Territory state at a specific tick - SimulationSnapshot: Complete simulation state container

All types are Pydantic models with validation.

See also

• data-model.md: Entity definitions and validation rules

• contracts/simulation_state.py: Protocol that returns these types

Classes

EdgeState(**data)	Relationship snapshot between entities at a specific tick.
HexState(**data)	Immutable geographic cell snapshot.
SimulationSnapshot(**data)	Complete simulation state at a specific tick.
SnapshotEdgeType(*values)	Edge types for simulation snapshots.
TerritoryState(**data)	Territory state snapshot at a specific tick.

class babylon.models.snapshots.HexState(**data)

Bases: BaseModel

Immutable geographic cell snapshot.

Hexes are the invariant substrate - they don’t change during simulation. For MVP, HexState contains only the H3 index. Future versions may add physical properties (terrain, resources).

Parameters:

h3_index (str)

h3_index

H3 cell index (15-char hex string, resolution 5).

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

h3_index: str

classmethod validate_h3_index(v)

Validate H3 index is 15-char lowercase hex.

Return type:

str

Parameters:

v (str)

class babylon.models.snapshots.EdgeState(**data)

Bases: BaseModel

Relationship snapshot between entities at a specific tick.

Parameters:

• source_id (str)

• target_id (str)

• edge_type (SnapshotEdgeType)

• weight (Annotated[float, Ge(ge=0)])

source_id

ID of the source entity.

target_id

ID of the target entity.

edge_type

Relationship type.

weight

Edge weight (default 1.0).

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

source_id: str

target_id: str

edge_type: SnapshotEdgeType

weight: float

class babylon.models.snapshots.TerritoryState(**data)

Bases: BaseModel

Territory state snapshot at a specific tick.

This is the GUI-facing representation of a territory.

Parameters:

• territory_id (str)

• controlling_polity (str)

• hex_claims (frozenset[str])

• tick (Annotated[int, Ge(ge=0)])

• profit_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

• equilibrium_r (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

• tensor_year (Annotated[int | None, Ge(ge=1900)])

territory_id

Unique identifier (FIPS code for counties).

controlling_polity

Current controller (equals territory_id for MVP).

hex_claims

Set of H3 indices this territory claims.

tick

Tick number when this snapshot was taken.

profit_rate

Current profit rate, range [0.0, 1.0].

equilibrium_r

Territory-specific equilibrium (= initial_r at hydration).

model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

territory_id: str

controlling_polity: str

hex_claims: frozenset[str]

tick: int

profit_rate: float

equilibrium_r: float

tensor_year: int | None

classmethod validate_territory_id(v)

Validate territory_id is a 5-digit FIPS code.

Return type:

str

Parameters:

v (str)

classmethod convert_hex_claims(v)

Convert hex_claims to frozenset for immutability.

Return type:

frozenset[str]

Parameters:

v (set[str] | frozenset[str] | list[str])

validate_hex_claims_patterns()

Validate all H3 indices in hex_claims match pattern.

Return type:

TerritoryState

classmethod with_clamped_profit_rate(territory_id, controlling_polity, hex_claims, tick, profit_rate, equilibrium_r, tensor_year=None)

Create TerritoryState with profit_rate clamped to [0.0, 1.0].

If profit_rate is outside valid range, it is clamped and a warning is logged.

Parameters:

• territory_id (str) – FIPS code.

• controlling_polity (str) – Controller ID.

• hex_claims (set[str] | frozenset[str]) – Set of H3 indices.

• tick (int) – Current tick.

• profit_rate (float) – Computed profit rate (may be out of range).

• equilibrium_r (float) – Territory-specific equilibrium.

• tensor_year (int | None) – Year for tensor lookup (may differ from tick). None if no tensor data.

Return type:

TerritoryState

Returns:

TerritoryState with clamped profit_rate.

class babylon.models.snapshots.SimulationSnapshot(**data)

Bases: BaseModel

Complete simulation state at a specific tick.

This is the top-level container returned by get_snapshot().

Parameters:

• tick (Annotated[int, Ge(ge=0)])

• territories (dict[str, TerritoryState])

• hexes (dict[str, HexState])

• edges (list[EdgeState])

• tensor_registry (Any)

tick

Current tick number.

territories

Map of territory_id to TerritoryState.

hexes

Map of h3_index to HexState (invariant substrate).

edges

List of EdgeState relationships (empty for MVP).

tensor_registry

Optional reference to TensorRegistry for cached tensor data access without database queries.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tick: int

territories: dict[str, TerritoryState]

hexes: dict[str, HexState]

edges: list[EdgeState]

tensor_registry: Any

validate_hex_references()

Validate all hex_claims reference existing hexes.

Return type:

SimulationSnapshot

class babylon.models.snapshots.SnapshotEdgeType(*values)

Bases: str, Enum

Edge types for simulation snapshots.

Maps to constitution I.6 edge modes.

ADJACENCY = 'ADJACENCY'

EXTRACTION = 'EXTRACTION'

SOLIDARITY = 'SOLIDARITY'

ANTAGONISTIC = 'ANTAGONISTIC'