unsprawl.core

Core engine contracts.

This package contains the deterministic, globally valid building blocks of Unsprawl.

Anti-circular protocol

The core MUST NOT import from unsprawl.adapters, unsprawl.providers, or unsprawl.loaders.

Submodules

• unsprawl.core.constants
• unsprawl.core.regions
• unsprawl.core.schemas

Attributes

Region

Classes

Agent	A dynamic actor (Commuter, Bus, Car).
Asset	A static economic unit (Building, Park, Transit Station).
Entity	Universal base class for the Unsprawl simulation.

Package Contents

Region

class Agent(/, **data)

Bases: Entity

A dynamic actor (Commuter, Bus, Car).

Agents flow through the city graph / continuous space depending on the simulation backend.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

velocity: tuple[float, float] = (0.0, 0.0)

goal: LatLon

state: Literal['idle', 'moving', 'stuck'] = 'idle'

class Asset(/, **data)

Bases: Entity

A static economic unit (Building, Park, Transit Station).

This replaces the legacy Singapore-specific concept of “HDB Flat” with a generic container that can represent any asset class across any region.

The physics engine treats local_metadata as an opaque payload.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

asset_type: Literal['residential', 'commercial', 'transport']

floor_area_sqm: float

lease_remaining_years: float

valuation_currency: str = 'USD'

predicted_valuation: float = 0.0

local_metadata: dict[str, Any] = None

class Entity(/, **data)

Bases: pydantic.BaseModel

Universal base class for the Unsprawl simulation.

Everything in the simulation (static or moving) is an Entity.

Notes

Coordinate ordering is strictly (lat, lon) across the entire platform. Adapters must normalize any source data into this convention at the boundary.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

id: str

location: LatLon

classmethod _validate_location_lat_lon(value)

Validate that location is (lat, lon) in sane numeric ranges.

This validator is not meant to be geo-precise; it is a defensive check that: - enforces the ordering contract at runtime - catches common adapter mistakes early (swapped lon/lat)