unsprawl.core.schemas¶

unsprawl.core.schemas.

This module defines the Universal Modular Design (UMD) schema layer for Unsprawl.

These Pydantic models are the language of the deterministic core engine: - They are global (no country/city-specific assumptions). - They are stable contracts between messy local datasets (adapters) and the core simulation.

Anti-circular protocol¶

unsprawl.core MUST NOT import from adapters/providers/loaders.

Attributes¶

LatLon

Classes¶

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

Module Contents¶

LatLon¶

class Entity(/, **data)[source]¶

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)[source]¶

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)

class Asset(/, **data)[source]¶

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 Agent(/, **data)[source]¶

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'¶