babylon.models

Pydantic models for the Babylon simulation engine.

This package contains the type system foundation: - enums: Categorical types (SocialRole, EdgeType, etc.) - types: Constrained value types (Probability, Currency, etc.) - entities: Game objects (Effect, Contradiction, Trigger, etc.) - components: Entity-Component system (Material, Vitality, Spatial, etc.)

All game state flows through these validated types.

class babylon.models.SocialRole(*values)[source]

Bases: StrEnum

Class position in the world system.

Based on Marxist-Leninist-Maoist Third Worldist (MLM-TW) theory, classes are defined by their relationship to production AND their position in the imperial hierarchy.

Values:: CORE_BOURGEOISIE: Owns means of production in imperial core PERIPHERY_PROLETARIAT: Sells labor in exploited periphery LABOR_ARISTOCRACY: Core workers benefiting from imperial rent PETTY_BOURGEOISIE: Small owners, professionals, shopkeepers LUMPENPROLETARIAT: Outside formal economy, precarious existence COMPRADOR_BOURGEOISIE: Intermediary class in periphery, collaborates with imperial core INTERNAL_PROLETARIAT: Core workers outside LA (precariat, unemployed, incarcerated) CARCERAL_ENFORCER: Guards, cops, prison staff (repressive apparatus)
Terminal Crisis Dynamics (ai-docs/terminal-crisis-dynamics.md):: When peripheral extraction fails and super-wages deplete, the Labor Aristocracy decomposes into CARCERAL_ENFORCER (30%) and INTERNAL_PROLETARIAT (70%). This models the carceral turn from productive to coercive labor.

CORE_BOURGEOISIE = 'core_bourgeoisie'

PERIPHERY_PROLETARIAT = 'periphery_proletariat'

LABOR_ARISTOCRACY = 'labor_aristocracy'

PETTY_BOURGEOISIE = 'petty_bourgeoisie'

LUMPENPROLETARIAT = 'lumpenproletariat'

COMPRADOR_BOURGEOISIE = 'comprador_bourgeoisie'

INTERNAL_PROLETARIAT = 'internal_proletariat'

CARCERAL_ENFORCER = 'carceral_enforcer'

class babylon.models.EdgeType(*values)[source]

Bases: StrEnum

Nature of relationships between entities.

These are the fundamental relationship types that form edges in the simulation’s NetworkX graph.

Values:: EXPLOITATION: Value extraction (imperial rent flows along these edges) SOLIDARITY: Mutual support and class consciousness REPRESSION: State violence directed at a class COMPETITION: Market rivalry between entities TRIBUTE: Value flow from periphery comprador to core (comprador keeps cut) WAGES: Core bourgeoisie paying core workers (super-wages from imperial rent) CLIENT_STATE: Imperial subsidy to maintain client state stability TENANCY: Occupant -> Territory relationship (Sprint 3.5.1) ADJACENCY: Territory -> Territory spatial connectivity (Sprint 3.5.1) TRANSACTIONAL: Service-for-support exchange (org-community, Feature 032) SOLIDARISTIC: Deep mutual commitment (org-community, Feature 032) ANTAGONISTIC: Manufactured conflict between orgs (Feature 039)

EXPLOITATION = 'exploitation'

SOLIDARITY = 'solidarity'

REPRESSION = 'repression'

COMPETITION = 'competition'

TRIBUTE = 'tribute'

WAGES = 'wages'

CLIENT_STATE = 'client_state'

TENANCY = 'tenancy'

ADJACENCY = 'adjacency'

MEMBERSHIP = 'membership'

RECRUITMENT = 'recruitment'

EMPLOYMENT = 'employment'

COMMAND = 'command'

PRESENCE = 'presence'

TRANSACTIONAL = 'transactional'

SOLIDARISTIC = 'solidaristic'

ANTAGONISTIC = 'antagonistic'

TARGETS = 'targets'

OWNED_BY = 'owned_by'

JURISDICTION = 'jurisdiction'

HOUSES = 'houses'

class babylon.models.IntensityLevel(*values)[source]

Bases: StrEnum

Intensity scale for contradictions and tensions.

Contradictions exist on a spectrum from dormant (latent potential) to critical (imminent rupture). This enum provides discrete levels for game mechanics while the underlying simulation may use continuous float values.

Values:: DORMANT: Contradiction exists but not yet manifest LOW: Minor tensions, easily managed MEDIUM: Noticeable conflict, requires attention HIGH: Serious crisis, intervention needed CRITICAL: Rupture imminent, phase transition likely

DORMANT = 'dormant'

LOW = 'low'

MEDIUM = 'medium'

HIGH = 'high'

CRITICAL = 'critical'

class babylon.models.ResolutionType(*values)[source]

Bases: StrEnum

How contradictions can resolve.

Based on dialectical materialism, contradictions resolve through one of three mechanisms. The resolution type determines what happens to the system after a contradiction reaches critical intensity.

Values:: SYNTHESIS: Dialectical resolution - opposites unite at higher level RUPTURE: Revolutionary break - system undergoes fundamental change SUPPRESSION: Forced dormancy - contradiction remains but is contained

SYNTHESIS = 'synthesis'

RUPTURE = 'rupture'

SUPPRESSION = 'suppression'

class babylon.models.SimulationConfig(**data)[source]

Bases: BaseModel

Global configuration for the simulation engine.

All formula coefficients and world parameters are stored here. The config is immutable (frozen) to ensure determinism during simulation runs.

Parameters:

extraction_efficiency (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
consciousness_sensitivity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
consciousness_decay_lambda (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Positive float value (> 0)', metadata=[Gt(gt=0.0)])])
subsistence_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
survival_steepness (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Positive float value (> 0)', metadata=[Gt(gt=0.0)])])
repression_level (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
initial_worker_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
initial_owner_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
loss_aversion_lambda (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Positive float value (> 0)', metadata=[Gt(gt=0.0)])])
tension_accumulation_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
comprador_cut (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
super_wage_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
subsidy_conversion_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
subsidy_trigger_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
solidarity_activation_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
mass_awakening_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
heat_decay_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
high_profile_heat_gain (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
eviction_heat_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
rent_spike_multiplier (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Positive float value (> 0)', metadata=[Gt(gt=0.0)])])
displacement_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
heat_spillover_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
clarity_profile_coefficient (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
initial_rent_pool (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
pool_high_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
pool_low_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
pool_critical_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
min_wage_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
max_wage_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
superwage_ppp_impact (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
concentration_camp_decay_rate (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
displacement_priority_mode (DisplacementPriorityMode)
elimination_rent_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
elimination_tension_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
containment_rent_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
containment_tension_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

extraction_efficiency: Alpha (α) in imperial rent formula. Controls how efficiently the core extracts value from periphery. Range: [0, 1], Default: 0.8

consciousness_sensitivity: k in consciousness drift formula. Controls how quickly consciousness responds to material conditions. Range: [0, 1], Default: 0.5

subsistence_threshold: Poverty line for acquiescence calculation. Below this wealth level, survival through compliance becomes impossible. Range: [0, inf), Default: 0.3

survival_steepness: Controls sigmoid sharpness in acquiescence probability. Higher values mean sharper transition around subsistence threshold. Range: (0, inf), Default: 10.0

repression_level: State capacity for violence. Reduces revolution probability in P(S|R) = cohesion / repression. Range: [0, 1], Default: 0.5

initial_worker_wealth: Starting wealth for periphery worker entities. Range: [0, inf), Default: 0.5

initial_owner_wealth: Starting wealth for core owner entities. Range: [0, inf), Default: 0.5

loss_aversion_lambda: Kahneman-Tversky loss aversion coefficient. Humans feel losses ~2.25x more strongly than equivalent gains. Range: (0, inf), Default: 2.25

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

extraction_efficiency: Annotated[float]

consciousness_sensitivity: Annotated[float]

consciousness_decay_lambda: Annotated[float]

subsistence_threshold: Annotated[float]

survival_steepness: Annotated[float]

repression_level: Annotated[float]

initial_worker_wealth: Annotated[float]

initial_owner_wealth: Annotated[float]

loss_aversion_lambda: Annotated[float]

tension_accumulation_rate: Annotated[float]

comprador_cut: Annotated[float]

super_wage_rate: Annotated[float]

subsidy_conversion_rate: Annotated[float]

subsidy_trigger_threshold: Annotated[float]

solidarity_activation_threshold: Annotated[float]

mass_awakening_threshold: Annotated[float]

heat_decay_rate: Annotated[float]

high_profile_heat_gain: Annotated[float]

eviction_heat_threshold: Annotated[float]

rent_spike_multiplier: Annotated[float]

displacement_rate: Annotated[float]

heat_spillover_rate: Annotated[float]

clarity_profile_coefficient: Annotated[float]

initial_rent_pool: Annotated[float]

pool_high_threshold: Annotated[float]

pool_low_threshold: Annotated[float]

pool_critical_threshold: Annotated[float]

min_wage_rate: Annotated[float]

max_wage_rate: Annotated[float]

superwage_ppp_impact: Annotated[float]

concentration_camp_decay_rate: Annotated[float]

displacement_priority_mode: DisplacementPriorityMode

elimination_rent_threshold: Annotated[float]

elimination_tension_threshold: Annotated[float]

containment_rent_threshold: Annotated[float]

containment_tension_threshold: Annotated[float]

class babylon.models.ScenarioConfig(**data)[source]

Bases: BaseModel

Configuration for multiverse scenario injection.

ScenarioConfig defines modifiers that transform a base WorldState and SimulationConfig into a specific counterfactual scenario. This enables deterministic exploration of parameter space without random sampling.

The model is frozen (immutable) to ensure scenarios remain constant throughout simulation runs.

Parameters:

name (str)
superwage_multiplier (float)
solidarity_index (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
repression_capacity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

name: Human-readable scenario identifier, must be unique within a multiverse run. Format: “{SWLevel}_{SolidarityLevel}_{RepressionLevel}”

superwage_multiplier: Multiplier for extraction_efficiency in SimulationConfig. Default 1.0 (no change). Range: [0, inf). - 0.3 = Low superwage (periphery retains more value) - 1.5 = High superwage (aggressive extraction) Theory: “Superwage” refers to core worker wages above value produced, subsidized by imperial rent extraction.

solidarity_index: Base strength for SOLIDARITY edges in topology. Default 0.5. Constrained to [0, 1] via Coefficient type. - 0.2 = Low solidarity (atomized workers) - 0.8 = High solidarity (strong worker networks)

repression_capacity: State violence capacity modifier. Updates repression_faced on entities and repression_level in config. Default 0.5. Constrained to [0, 1] via Coefficient type. - 0.2 = Low repression (weak state) - 0.8 = High repression (police state)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str

superwage_multiplier: float

solidarity_index: Coefficient

repression_capacity: Coefficient

class babylon.models.WorldState(**data)[source]

Bases: BaseModel

Immutable snapshot of the simulation at a specific tick.

WorldState follows the Data/Logic separation principle: - State holds WHAT exists (pure data) - Engine determines HOW it transforms (pure logic)

This enables: - Determinism: Same state + same engine = same output - Replayability: Save initial state, replay entire history - Counterfactuals: Modify a parameter, run forward, compare - Testability: Feed state in, assert on state out

Parameters:

tick (int)
entities (dict[str, SocialClass])
territories (dict[str, Territory])
relationships (list[Relationship])
event_log (list[str])
events (list[SimulationEvent])
economy (GlobalEconomy)
state_finances (dict[str, StateFinance])
contradiction_frames (dict[str, ContradictionFrame])
organizations (dict[str, Annotated[StateApparatus | Business | PoliticalFaction | CivilSocietyOrg, FieldInfo(annotation=NoneType, required=True, discriminator='org_type')]])
key_figures (dict[str, KeyFigure])
institutions (dict[str, Institution])
institution_relations (list[InstitutionOrgRelation])
industries (dict[str, IndustryHyperedge])

tick: Current turn number (0-indexed)

entities: Map of entity ID to SocialClass (the nodes)

territories: Map of territory ID to Territory (Layer 0 nodes)

relationships: List of Relationship edges (the edges)

event_log: Recent events for narrative/debugging (string format)

events: Structured simulation events for analysis (Sprint 3.1)

economy: Global economic state for dynamic balance (Sprint 3.4.4)

add_entity(entity)[source]

Return new state with entity added.

Parameters:: entity (SocialClass) – SocialClass to add
Return type:: WorldState
Returns:: New WorldState with the entity included.

Example

new_state = state.add_entity(worker)

add_event(event)[source]

Return new state with event appended to log.

Parameters:: event (str) – Event description string
Return type:: WorldState
Returns:: New WorldState with event in log.

Example

new_state = state.add_event(“Worker crossed poverty threshold”)

add_relationship(relationship)[source]

Return new state with relationship added.

Parameters:: relationship (Relationship) – Relationship edge to add
Return type:: WorldState
Returns:: New WorldState with the relationship included.

Example

new_state = state.add_relationship(exploitation_edge)

add_territory(territory)[source]

Return new state with territory added.

Parameters:: territory (Territory) – Territory to add (Layer 0 node)
Return type:: WorldState
Returns:: New WorldState with the territory included.

Example

new_state = state.add_territory(university_district)

classmethod from_graph(G, tick, event_log=None, events=None)[source]

Reconstruct WorldState from NetworkX DiGraph.

Parameters:

G – NetworkX DiGraph with node/edge data
tick – The tick number for the new state
event_log – Optional event log to preserve (backward compatibility)
events – Optional structured events to include (Sprint 3.1)

Returns:

New WorldState with entities, territories, and relationships from graph.

Return type:

WorldState

Example

G = state.to_graph() # … modify graph … new_state = WorldState.from_graph(G, tick=state.tick + 1)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property overshoot_ratio: float: Global ecological overshoot ratio.

to_graph()[source]

Convert state to NetworkX DiGraph for formula application.

Nodes are entity/territory IDs with all fields as attributes. A _node_type marker distinguishes between node types: - _node_type=’social_class’ for SocialClass nodes - _node_type=’territory’ for Territory nodes

Edges are relationships with all Relationship fields as attributes.

Graph metadata (G.graph) contains: - economy: GlobalEconomy state (Sprint 3.4.4)

Returns:: NetworkX DiGraph with nodes and edges from this state.
Return type:: nx.DiGraph[str]

Example:

G = state.to_graph()
for node_id, data in G.nodes(data=True):
    if data["_node_type"] == "social_class":
        data["wealth"] += 10  # Modify entity
new_state = WorldState.from_graph(G, tick=state.tick + 1)

property total_biocapacity: Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=quantize)]: Global sum of territory biocapacity.

property total_consumption: Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=quantize)]: Global sum of consumption needs.

tick: int

entities: dict[str, SocialClass]

territories: dict[str, Territory]

relationships: list[Relationship]

event_log: list[str]

events: list[SimulationEvent]

economy: GlobalEconomy

state_finances: dict[str, StateFinance]

contradiction_frames: dict[str, ContradictionFrame]

organizations: dict[str, OrganizationType]

key_figures: dict[str, KeyFigure]

institutions: dict[str, Institution]

institution_relations: list[InstitutionOrgRelation]

industries: dict[str, IndustryHyperedge]

class babylon.models.SocialClass(**data)[source]

Bases: BaseModel

A social class in the world system.

The fundamental unit of the simulation. Classes are defined by their relationship to production and their position in the imperial hierarchy.

This model uses Sprint 1 constrained types for automatic validation: - Currency: [0, inf) for wealth, subsistence_threshold - IdeologicalProfile: Multi-dimensional consciousness model (Sprint 3.4.3) - Probability: [0, 1] for survival probabilities and organization/repression

Parameters:

id (str)
name (str)
role (SocialRole)
description (str)
wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
ideology (IdeologicalProfile)
p_acquiescence (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
p_revolution (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
subsistence_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
organization (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
repression_faced (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
effective_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
unearned_increment (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
ppp_multiplier (float)
active (bool)
s_bio (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
s_class (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
subsistence_multiplier (float)
population (int)
inequality (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Gini coefficient measuring intra-class inequality', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
community_memberships (list[Any])
community_cost_modifier (float)

id: Unique identifier matching pattern ^C[0-9]{3}$

name: Human-readable name for the class

role: Position in the world system (SocialRole enum)

description: Optional detailed description

wealth: Economic resources (Currency, default 10.0)

ideology: Multi-dimensional ideological profile (IdeologicalProfile)

p_acquiescence: P(S|A) - survival probability through acquiescence (Probability)

p_revolution: P(S|R) - survival probability through revolution (Probability)

subsistence_threshold: Minimum wealth for survival (Currency, default 5.0)

organization: Collective cohesion/class consciousness (Probability, default 0.1)

repression_faced: State violence directed at this class (Probability, default 0.5)

Legacy Compatibility:: If a float value is passed for ideology, it will be automatically converted to an IdeologicalProfile using from_legacy_ideology().

property consumption_needs: Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=quantize)]: Total consumption required per tick (Wealth-independent demand).

property economic: EconomicComponent: Return economic component view (computed, not live).

property material_conditions: MaterialConditionsComponent: Return material conditions component view (computed, not live).

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property survival: SurvivalComponent: Return survival component view (computed, not live).

classmethod unpack_components_and_convert_legacy(data)[source]

Unpack component objects and convert legacy ideology to IdeologicalProfile.

Return type:: Any
Parameters:: data (Any)

id: str

name: str

role: SocialRole

description: str

wealth: Annotated[float]

ideology: IdeologicalProfile

p_acquiescence: Annotated[float]

p_revolution: Annotated[float]

subsistence_threshold: Annotated[float]

organization: Annotated[float]

repression_faced: Annotated[float]

effective_wealth: Annotated[float]

unearned_increment: Annotated[float]

ppp_multiplier: float

active: bool

s_bio: Annotated[float]

s_class: Annotated[float]

subsistence_multiplier: float

population: int

inequality: Annotated[float]

community_memberships: list[Any]

community_cost_modifier: float

class babylon.models.Relationship(**data)[source]

Bases: BaseModel

A directed edge between two entities.

Represents flows of value, solidarity, or repression between classes. In Phase 1, the primary relationship is exploitation: value flows from the periphery worker (source) to the core owner (target).

This model uses Sprint 1 constrained types for automatic validation: - Currency: [0, inf) for value_flow - Intensity: [0, 1] for tension

Parameters:

source_id (str)
target_id (str)
edge_type (EdgeType)
value_flow (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
tension (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Contradiction intensity from dormant (0) to rupture (1)', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
description (str)
subsidy_cap (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
solidarity_strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

source_id: Origin entity ID (value/action flows FROM here)

target_id: Destination entity ID (value/action flows TO here)

edge_type: Nature of the relationship (EdgeType enum)

value_flow: Imperial rent or value transfer amount (Currency, default 0.0)

tension: Dialectical tension/contradiction intensity (Intensity, default 0.0)

description: Optional description of the relationship

property edge_data: dict[str, object]

Return edge attributes dict for NetworkX, excluding IDs.

Usage:

G.add_edge(*relationship.edge_tuple, **relationship.edge_data)

property edge_tuple: tuple[str, str]

Return (source_id, target_id) tuple for NetworkX edge creation.

Usage:

G.add_edge(*relationship.edge_tuple, **relationship.edge_data)

property flow: FlowComponent: Return flow component view (computed, not live).

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'str_strip_whitespace': True, 'validate_assignment': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod unpack_flow_component(data)[source]

Unpack flow component into flat fields if provided.

Return type:: Any
Parameters:: data (Any)

validate_no_self_loop()[source]

Ensure entities cannot have a relationship with themselves.

Return type:: Relationship

source_id: str

target_id: str

edge_type: EdgeType

value_flow: Annotated[float]

tension: Annotated[float]

description: str

subsidy_cap: Annotated[float]

solidarity_strength: Annotated[float]

class babylon.models.IdeologicalProfile(**data)[source]

Bases: BaseModel

Multi-dimensional ideological state of a social class.

Sprint 3.4.3 (George Jackson Refactor): This model replaces the scalar ideology field with a multi-dimensional consciousness model.

The key insight: “Fascism is the defensive form of capitalism.” - Agitation + Solidarity -> Class Consciousness (Revolutionary Path) - Agitation + No Solidarity -> National Identity (Fascist Path)

Parameters:

class_consciousness (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Relationship to Capital: 0=False Consciousness, 1=Revolutionary', metadata=[Ge(ge=0.0), Le(le=1.0)])])
national_identity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Relationship to State/Tribe: 0=Internationalist, 1=Nativist/Fascist', metadata=[Ge(ge=0.0), Le(le=1.0)])])
agitation (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Raw political energy from crisis (falling wages)', metadata=[Ge(ge=0.0)])])

class_consciousness: Relationship to Capital [0.0=False, 1.0=Revolutionary] How clearly the class understands its position relative to capital.

national_identity: Relationship to State/Tribe [0.0=Internationalist, 1.0=Fascist] How strongly the class identifies with nation/race over class.

agitation: Raw political energy from crisis [0.0, inf) Accumulated energy from falling wages, crisis conditions. Routes to either axis based on solidarity_pressure.

classmethod from_legacy_ideology(ideology_value)[source]

Convert legacy scalar ideology [-1, 1] to IdeologicalProfile.

Legacy mapping: - ideology=-1 (revolutionary) -> class_consciousness=1.0, national_identity=0.0 - ideology=0 (neutral) -> class_consciousness=0.5, national_identity=0.5 - ideology=+1 (reactionary) -> class_consciousness=0.0, national_identity=1.0

Parameters:: ideology_value (float) – Legacy ideology scalar in range [-1.0, 1.0]
Return type:: IdeologicalProfile
Returns:: IdeologicalProfile with mapped values

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_legacy_ideology()[source]

Convert IdeologicalProfile back to legacy scalar ideology [-1, 1].

This provides backward compatibility for systems still using the scalar ideology representation.

Return type:: float
Returns:: Legacy ideology scalar in range [-1.0, 1.0]

class_consciousness: Annotated[float]

national_identity: Annotated[float]

agitation: Annotated[float]

class babylon.models.GlobalEconomy(**data)[source]

Bases: BaseModel

System-wide economic state for dynamic balance mechanics.

The GlobalEconomy model tracks the “Gas Tank” (imperial rent pool) and the “Driver” parameters (wage rate, repression level) that the bourgeoisie can adjust based on pool levels and tension.

Parameters:

imperial_rent_pool (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
super_wage_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0), AfterValidator(func=~babylon.utils.math.quantize)])
repression_level (Annotated[float, Ge(ge=0.0), Le(le=1.0), AfterValidator(func=~babylon.utils.math.quantize)])

imperial_rent_pool: Accumulated imperial rent available for redistribution. Fed by TRIBUTE inflows, depleted by WAGES and CLIENT_STATE outflows. Default: 100.0 Currency.

current_super_wage_rate: Dynamic wage rate for WAGES edges. Adjusts based on pool level and tension via decision heuristics. Range: [0.05, 0.35]. Default: 0.20 (20%).

current_repression_level: System-wide repression modifier. Blended with per-class repression_faced values. Increases during austerity/crisis periods. Range: [0.0, 1.0]. Default: 0.5.

Pool Flow Logic:: inflow = sum(tribute reaching Core Bourgeoisie after comprador cut) outflow = wages_paid + subsidy_paid delta = inflow - outflow new_pool = old_pool + delta
Decision Thresholds (Aggressive):: pool_ratio >= 0.7: PROSPERITY (can increase wages) pool_ratio < 0.3: AUSTERITY (cut wages or increase repression) pool_ratio < 0.1: CRISIS (emergency measures, emit event)

model_config: ClassVar[ConfigDict] = {'frozen': True, 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

imperial_rent_pool: Annotated[float]

current_super_wage_rate: Annotated[float]

current_repression_level: Annotated[float]

class babylon.models.Effect(**data)[source]

Bases: BaseModel

A modification to game state.

Effects are the atoms of change - they modify single attributes on single targets by specific amounts. Every state change in the simulation should be expressible as one or more Effects.

Parameters:

target_id (str)
attribute (str)
operation (Literal['increase', 'decrease', 'set', 'multiply'])
magnitude (float)
description (str)

target_id: ID of the entity to modify

attribute: Name of the attribute to change

operation: How to modify the value

magnitude: Amount of change (interpretation depends on operation)

description: Human-readable explanation of why this effect occurs

apply_to(current_value)[source]

Calculate the new value after applying this effect.

Parameters:: current_value (float) – The current value of the attribute
Return type:: float
Returns:: The new value after the effect is applied

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

target_id: str

attribute: str

operation: Literal['increase', 'decrease', 'set', 'multiply']

magnitude: float

description: str

class babylon.models.ContradictionFrame(**data)[source]

Bases: BaseModel

The 2x2 contradiction matrix at a given scale and moment.

Models the principal and secondary contradictions for a specific scope.

Parameters:

principal (Contradiction)
secondary (Contradiction)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

principal: Contradiction

secondary: Contradiction

class babylon.models.Contradiction(**data)[source]

Bases: BaseModel

A structural contradiction at a specific scale.

Instead of hardcoding the fractal, this uses a dynamic aspect mapping.

Parameters:

id (str)
type (ContradictionType)
aspect_a (str)
aspect_b (str)
principal_aspect (Literal['a', 'b'])
identity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Contradiction intensity from dormant (0) to rupture (1)', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
intensity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Contradiction intensity from dormant (0) to rupture (1)', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
aspect_balance (float)
form_of_struggle (EdgeMode)
is_antagonistic (bool)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

type: ContradictionType

aspect_a: str

aspect_b: str

principal_aspect: Literal['a', 'b']

identity: Annotated[float]

intensity: Annotated[float]

aspect_balance: float

form_of_struggle: EdgeMode

is_antagonistic: bool

class babylon.models.Trigger(**data)[source]

Bases: BaseModel

A condition that can trigger game events.

Triggers define when events should occur based on game state. They can have multiple conditions that must all be met (AND logic) or any one met (OR logic).

Parameters:

id (str)
description (str)
trigger_type (str | None)
conditions (list[TriggerCondition])
logic (Literal['all', 'any'])
parameters (dict[str, Any])
cooldown_turns (int)
last_triggered_turn (int | None)

id: Unique identifier

description: Human-readable description

trigger_type: Category of trigger (economic, political, social, etc.)

conditions: List of conditions to evaluate

logic: How to combine conditions (all must pass or any must pass)

parameters: Optional parameters for condition evaluation

cooldown_turns: Minimum turns between activations (0 = no cooldown)

last_triggered_turn: Turn when this was last triggered

evaluate(game_state, current_turn=0)[source]

Evaluate if the trigger condition is met.

Parameters:

game_state (dict[str, Any]) – The current game state to evaluate against
current_turn (int) – The current turn number (for cooldown checking)

Return type:

bool

Returns:

True if the trigger condition is met, False otherwise

mark_triggered(current_turn)[source]

Mark this trigger as having been triggered.

Parameters:: current_turn (int) – The current turn number
Return type:: None

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

id: str

description: str

trigger_type: str | None

conditions: list[TriggerCondition]

logic: Literal['all', 'any']

parameters: dict[str, Any]

cooldown_turns: int

last_triggered_turn: int | None

class babylon.models.TriggerCondition(**data)[source]

Bases: BaseModel

A single condition that can be evaluated against game state.

Conditions specify what to check, how to compare, and what threshold to use. Multiple conditions can be combined in a Trigger.

Parameters:

path (str)
operator (Literal['>=', '<=', '>', '<', '==', '!='])
threshold (float)
description (str)

path: Dot-notation path to the value in game state (e.g., “economy.gini_coefficient”)

operator: Comparison operator

threshold: Value to compare against

description: Human-readable explanation

evaluate(game_state)[source]

Evaluate this condition against the game state.

Parameters:: game_state (dict[str, Any]) – The current game state dictionary
Return type:: bool
Returns:: True if the condition is met, False otherwise

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str

operator: Literal['>=', '<=', '>', '<', '==', '!=']

threshold: float

description: str

class babylon.models.Component(*args, **kwargs)[source]

Bases: Protocol

Protocol defining the interface for all component types.

All components in the Babylon simulation must implement this protocol. The protocol requires a component_type property that returns a string identifier for the component type.

This protocol is runtime-checkable, meaning you can use isinstance() to verify that an object implements the Component interface.

Example

>>> class MyComponent(BaseModel):
...     model_config = ConfigDict(frozen=True)
...     @property
...     def component_type(self) -> str:
...         return "my_component"
...
>>> instance = MyComponent()
>>> isinstance(instance, Component)
True

__init__(*args, **kwargs)

property component_type: str

Return the component type identifier.

Returns:: A string identifying the type of this component. For example: “material”, “vitality”, “spatial”, etc.

class babylon.models.MaterialComponent(**data)[source]

Bases: BaseModel

Material conditions of an entity.

Tracks the economic and material state of an entity including: - Accumulated wealth (Currency) - Available resources (Currency) - Control over means of production (Probability)

All values use constrained types for automatic validation: - wealth, resources: Currency [0, inf) - means_of_production: Probability [0, 1]

This component is immutable (frozen) to ensure state integrity.

Parameters:

wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
resources (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
means_of_production (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

wealth: Accumulated economic resources (default: 10.0)

resources: Available material resources (default: 0.0)

means_of_production: Control over productive apparatus [0, 1] (default: 0.0)

property component_type: str

Return the component type identifier.

Returns:: The string ‘material’ identifying this component type.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

wealth: Annotated[float]

resources: Annotated[float]

means_of_production: Annotated[float]

class babylon.models.VitalityComponent(**data)[source]

Bases: BaseModel

Population and survival needs of an entity.

Tracks the demographic and subsistence state of an entity: - Population size (Currency) - Minimum resources required for survival (Currency)

All values use constrained types for automatic validation: - population, subsistence_needs: Currency [0, inf)

This component is immutable (frozen) to ensure state integrity.

Parameters:

population (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
subsistence_needs (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

population: Size of the population (default: 1.0)

subsistence_needs: Resources needed for survival (default: 5.0)

property component_type: str

Return the component type identifier.

Returns:: The string ‘vitality’ identifying this component type.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

population: Annotated[float]

subsistence_needs: Annotated[float]

class babylon.models.SpatialComponent(**data)[source]

Bases: BaseModel

Location and mobility of an entity.

Tracks the spatial state of an entity: - Geographic/topological location identifier (string) - Ability to relocate (Probability)

All numeric values use constrained types for automatic validation: - mobility: Probability [0, 1]

This component is immutable (frozen) to ensure state integrity.

Parameters:

location_id (str)
mobility (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

location_id: Geographic or topological location identifier (default: “”)

mobility: Ability to relocate [0=immobile, 1=fully mobile] (default: 0.5)

property component_type: str

Return the component type identifier.

Returns:: The string ‘spatial’ identifying this component type.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

location_id: str

mobility: Annotated[float]

class babylon.models.OrganizationComponent(**data)[source]

Bases: BaseModel

Organizational capacity of an entity.

Tracks the organizational state of an entity: - Internal unity and coordination (Probability) - Quality of organizational leadership (Probability)

All values use constrained types for automatic validation: - cohesion: Probability [0, 1] - cadre_level: Probability [0, 1]

This component is immutable (frozen) to ensure state integrity.

Parameters:

cohesion (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
cadre_level (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

cohesion: Internal unity and coordination [0=atomized, 1=unified] (default: 0.1)

cadre_level: Quality of organizational leadership [0=none, 1=elite] (default: 0.0)

property component_type: str

Return the component type identifier.

Returns:: The string ‘organization’ identifying this component type.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

cohesion: Annotated[float]

cadre_level: Annotated[float]

class babylon.models.TopologySnapshot(**data)[source]

Bases: BaseModel

Metrics snapshot of the solidarity subgraph at a specific tick.

Captures the topological state of SOLIDARITY edges in the social graph, enabling detection of phase transitions from atomized (gaseous) to condensed (liquid) movement states.

Parameters:

tick (int)
num_components (int)
max_component_size (int)
total_nodes (int)
percolation_ratio (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
potential_liquidity (int)
actual_liquidity (int)
cadre_density (float)
is_resilient (bool | None)

tick: Simulation tick when snapshot was taken

num_components: Number of disconnected subgraphs (solidarity cells)

max_component_size: Size of the largest connected component (L_max)

total_nodes: Total number of social_class nodes (N)

percolation_ratio: L_max / N, measures giant component dominance

potential_liquidity: Count of SOLIDARITY edges > 0.1 (sympathizers)

actual_liquidity: Count of SOLIDARITY edges > 0.5 (cadre)

is_resilient: Whether movement survives 20% purge (optional)

Interpretation (4-Phase Model):

percolation_ratio < 0.1: Gaseous (atomized, no coordination)
0.1 <= percolation_ratio < 0.5: Transitional (emerging structure)
percolation_ratio >= 0.5 AND cadre_density < 0.5: Liquid (mass movement)
percolation_ratio >= 0.5 AND cadre_density >= 0.5: Solid (vanguard party)
potential >> actual: Broad but brittle (lacks cadre discipline)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tick: int

num_components: int

max_component_size: int

total_nodes: int

percolation_ratio: Probability

potential_liquidity: int

actual_liquidity: int

cadre_density: float

is_resilient: bool | None

class babylon.models.ResilienceResult(**data)[source]

Bases: BaseModel

Result of purge simulation (Sword of Damocles test).

Tests whether the solidarity network survives targeted removal of a percentage of nodes. A resilient network maintains its giant component after losing key members.

Parameters:

is_resilient (bool)
original_max_component (int)
post_purge_max_component (int)
removal_rate (float)
survival_threshold (float)
seed (int | None)

is_resilient: True if post-purge L_max > threshold of original L_max

original_max_component: Size of L_max before purge

post_purge_max_component: Size of L_max after purge

removal_rate: Fraction of nodes removed (e.g., 0.2 = 20%)

survival_threshold: Required fraction of original L_max to survive

seed: RNG seed for reproducibility (None if random)

Interpretation:

is_resilient=True: Network can survive targeted repression
is_resilient=False: “Sword of Damocles” - purge would destroy movement

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

is_resilient: bool

original_max_component: int

post_purge_max_component: int

removal_rate: float

survival_threshold: float

seed: int | None

class babylon.models.EntityMetrics(**data)[source]

Bases: BaseModel

Metrics snapshot for a single entity at a specific tick.

Captures wealth, consciousness, and survival probabilities for analysis and visualization.

Parameters:

wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
consciousness (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
national_identity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
agitation (float)
p_acquiescence (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
p_revolution (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
organization (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
population (int)

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

wealth: Currency

consciousness: Probability

national_identity: Probability

agitation: float

p_acquiescence: Probability

p_revolution: Probability

organization: Probability

population: int

class babylon.models.EdgeMetrics(**data)[source]

Bases: BaseModel

Metrics snapshot for relationship edges at a specific tick.

Captures tension, value flows, and solidarity strength for analysis and visualization.

Parameters:

exploitation_tension (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
exploitation_rent (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
tribute_flow (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
wages_paid (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
solidarity_strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exploitation_tension: Probability

exploitation_rent: Currency

tribute_flow: Currency

wages_paid: Currency

solidarity_strength: Probability

class babylon.models.TickMetrics(**data)[source]

Bases: BaseModel

Complete metrics snapshot for a single simulation tick.

Aggregates entity and edge metrics for comprehensive tick analysis.

Parameters:

tick (int)
p_w (EntityMetrics | None)
p_c (EntityMetrics | None)
c_b (EntityMetrics | None)
c_w (EntityMetrics | None)
edges (EdgeMetrics)
imperial_rent_pool (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
global_tension (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
current_super_wage_rate (float)
current_repression_level (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
pool_ratio (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
topology (TopologySummary | None)
consciousness_gap (float)
wealth_gap (float)
overshoot_ratio (float)
total_biocapacity (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
total_consumption (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tick: int

p_w: EntityMetrics | None

p_c: EntityMetrics | None

c_b: EntityMetrics | None

c_w: EntityMetrics | None

edges: EdgeMetrics

imperial_rent_pool: Currency

global_tension: Probability

current_super_wage_rate: float

current_repression_level: Probability

pool_ratio: Probability

topology: TopologySummary | None

consciousness_gap: float

wealth_gap: float

overshoot_ratio: float

total_biocapacity: Currency

total_consumption: Currency

class babylon.models.SweepSummary(**data)[source]

Bases: BaseModel

Summary statistics for a completed simulation run.

Aggregates metrics across all ticks for parameter sweep analysis.

Parameters:

ticks_survived (int)
outcome (Literal['SURVIVED', 'DIED', 'ERROR'])
final_p_w_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
final_p_c_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
final_c_b_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
final_c_w_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
max_tension (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
crossover_tick (int | None)
cumulative_rent (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
peak_p_w_consciousness (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])
peak_c_w_consciousness (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ticks_survived: int

outcome: Literal['SURVIVED', 'DIED', 'ERROR']

final_p_w_wealth: Currency

final_p_c_wealth: Currency

final_c_b_wealth: Currency

final_c_w_wealth: Currency

max_tension: Probability

crossover_tick: int | None

cumulative_rent: Currency

peak_p_w_consciousness: Probability

peak_c_w_consciousness: Probability

class babylon.models.GraphNode(**data)[source]

Bases: BaseModel

Type-safe graph node representation.

Frozen Pydantic model for node data at the protocol boundary. Adapters convert to/from their internal representation.

Parameters:

id (str)
node_type (str)
attributes (dict[str, Any])

id: Unique node identifier.

node_type: Discriminator for polymorphism (e.g., ‘social_class’, ‘territory’).

attributes: Type-specific attributes stored as dict.

Example

>>> node = GraphNode(id="C001", node_type="social_class", attributes={"wealth": 100.0})
>>> node.wealth
100.0

get_attr(key, default=None)[source]

Get attribute with default.

Parameters:

key (str) – Attribute name to retrieve.
default (Any) – Value to return if attribute not present.

Return type:

Any

Returns:

The attribute value or default.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property wealth: float

Convenience accessor for wealth attribute.

Returns:: Wealth value or 0.0 if not present.

id: str

node_type: str

attributes: dict[str, Any]

class babylon.models.GraphEdge(**data)[source]

Bases: BaseModel

Type-safe graph edge representation.

Frozen Pydantic model for edge data at the protocol boundary. Adapters convert to/from their internal representation.

Parameters:

source_id (str)
target_id (str)
edge_type (str)
weight (float)
attributes (dict[str, Any])

source_id: Origin node ID.

target_id: Destination node ID.

edge_type: Edge category (e.g., ‘SOLIDARITY’, ‘EXPLOITATION’).

weight: Generic weight (default 1.0).

attributes: Type-specific attributes stored as dict.

Example

>>> edge = GraphEdge(source_id="C001", target_id="C002", edge_type="SOLIDARITY")
>>> edge.weight
1.0

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property tension: float

Convenience accessor for tension attribute.

Returns:: Tension value or 0.0 if not present.

property value_flow: float

Convenience accessor for value_flow attribute.

Returns:: Value flow or 0.0 if not present.

source_id: str

target_id: str

edge_type: str

weight: float

attributes: dict[str, Any]

class babylon.models.EdgeFilter(**data)[source]

Bases: BaseModel

Filter specification for edge traversal.

Used to select which edges to traverse during graph operations. All fields are optional - None means no filter (match all).

Parameters:

edge_types (set[str] | None)
min_weight (float | None)
max_weight (float | None)

edge_types: Set of edge types to include (None = all types).

min_weight: Minimum weight threshold (inclusive).

max_weight: Maximum weight threshold (inclusive).

Example

>>> f = EdgeFilter(edge_types={"SOLIDARITY"}, min_weight=0.5)
>>> f.edge_types
{'SOLIDARITY'}

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

edge_types: set[str] | None

min_weight: float | None

max_weight: float | None

class babylon.models.NodeFilter(**data)[source]

Bases: BaseModel

Filter specification for node inclusion.

Used to select which nodes to include during graph operations. All fields are optional - None means no filter (match all).

Parameters:

node_types (set[str] | None)
attribute_predicates (dict[str, Any] | None)

node_types: Set of node types to include (None = all types).

attribute_predicates: Dict of attribute equality filters.

Example

>>> f = NodeFilter(node_types={"social_class"})
>>> f.node_types
{'social_class'}

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

node_types: set[str] | None

attribute_predicates: dict[str, Any] | None

class babylon.models.TraversalQuery(**data)[source]

Bases: BaseModel

Generic traversal query specification.

Specifies what traversal to execute and what to collect. This is the generic hook for complex operations like percolation analysis, pathfinding, and component detection.

Parameters:

query_type (Literal['bfs', 'dfs', 'shortest_path', 'connected_components', 'percolation', 'reachability'])
start_nodes (list[str] | None)
target_nodes (list[str] | None)
edge_filter (EdgeFilter | None)
node_filter (NodeFilter | None)
max_depth (int | None)
collect (list[str])

query_type: Type of traversal algorithm to use.

start_nodes: Starting node IDs (None = all nodes).

target_nodes: Target node IDs (for shortest_path, reachability).

edge_filter: Filter which edges to traverse.

node_filter: Filter which nodes to include.

max_depth: Maximum traversal depth.

collect: What to include in result.

Example

>>> query = TraversalQuery(query_type="bfs", start_nodes=["C001"])
>>> query.query_type
'bfs'

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

query_type: Literal['bfs', 'dfs', 'shortest_path', 'connected_components', 'percolation', 'reachability']

start_nodes: list[str] | None

target_nodes: list[str] | None

edge_filter: EdgeFilter | None

node_filter: NodeFilter | None

max_depth: int | None

collect: list[str]

class babylon.models.TraversalResult(**data)[source]

Bases: BaseModel

Result of traversal query execution.

Contains all data collected during traversal based on query.collect.

Parameters:

nodes (list[str])
edges (list[tuple[str, str, str]])
paths (list[list[str]])
components (list[list[str]])
component_sizes (list[int])
metadata (dict[str, Any])

nodes: Node IDs in traversal result.

edges: Edge tuples (source, target, type) in result.

paths: Paths found (for shortest_path queries).

components: Connected components (for component queries).

component_sizes: Sizes of connected components (sorted descending).

metadata: Query-specific metadata.

Example

>>> result = TraversalResult(component_sizes=[10, 5, 3])
>>> result.largest_component_size
10

property largest_component_size: int

Size of the largest (giant) component.

Returns:: Size of first component or 0 if no components.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

property percolation_ratio: float

Fraction of nodes in the largest component.

This is the key metric for phase transition detection. A ratio near 1.0 indicates full percolation (connectivity).

Returns:: Ratio of largest_component_size to total nodes, or 0.0 if empty.

nodes: list[str]

edges: list[tuple[str, str, str]]

paths: list[list[str]]

components: list[list[str]]

component_sizes: list[int]

metadata: dict[str, Any]

babylon.models.role_to_entity_id(role)[source]

Convert a SocialRole enum to its canonical entity ID.

Parameters:: role (SocialRole) – SocialRole enum value
Return type:: str
Returns:: Entity ID string (e.g., “C001”)
Raises:: KeyError – If the role has no entity ID mapping (e.g., LUMPENPROLETARIAT)

Example

>>> role_to_entity_id(SocialRole.PERIPHERY_PROLETARIAT)
'C001'

babylon.models.entity_id_to_role(entity_id)[source]

Convert an entity ID to its SocialRole enum.

Parameters:: entity_id (str) – Entity ID string (e.g., “C001”)
Return type:: SocialRole
Returns:: SocialRole enum value
Raises:: KeyError – If the entity ID is not recognized

Example

>>> entity_id_to_role("C001")
<SocialRole.PERIPHERY_PROLETARIAT: 'periphery_proletariat'>

babylon.models.get_slot_name(entity_id)[source]

Get the short slot name for an entity ID.

Slot names are used for CSV column prefixes and metrics keys.

Parameters:: entity_id (str) – Entity ID string (e.g., “C001”)
Return type:: str
Returns:: Short slot name (e.g., “p_w”)
Raises:: KeyError – If the entity ID is not recognized

Example

>>> get_slot_name("C001")
'p_w'

class babylon.models.HexState(**data)[source]

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].

classmethod validate_h3_index(v)[source]

Validate H3 index is 15-char lowercase hex.

Return type:: str
Parameters:: v (str)

h3_index: str

class babylon.models.EdgeState(**data)[source]

Bases: BaseModel

Relationship snapshot between entities at a specific tick.

Parameters:

source_id (str)
target_id (str)
edge_type (SnapshotEdgeType)
weight (float)

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.TerritoryState(**data)[source]

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 (int)
profit_rate (float)
equilibrium_r (float)
tensor_year (int | None)

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).

classmethod convert_hex_claims(v)[source]

Convert hex_claims to frozenset for immutability.

Return type:: frozenset[str]
Parameters:: v (set[str] | frozenset[str] | list[str])

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

validate_hex_claims_patterns()[source]

Validate all H3 indices in hex_claims match pattern.

Return type:: TerritoryState

classmethod validate_territory_id(v)[source]

Validate territory_id is a 5-digit FIPS code.

Return type:: str
Parameters:: v (str)

classmethod with_clamped_profit_rate(territory_id, controlling_polity, hex_claims, tick, profit_rate, equilibrium_r, tensor_year=None)[source]

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.

territory_id: str

controlling_polity: str

hex_claims: frozenset[str]

tick: int

profit_rate: float

equilibrium_r: float

tensor_year: int | None

class babylon.models.SimulationSnapshot(**data)[source]

Bases: BaseModel

Complete simulation state at a specific tick.

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

Parameters:

tick (int)
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].

validate_hex_references()[source]

Validate all hex_claims reference existing hexes.

Return type:: SimulationSnapshot

tick: int

territories: dict[str, TerritoryState]

hexes: dict[str, HexState]

edges: list[EdgeState]

tensor_registry: Any

class babylon.models.SnapshotEdgeType(*values)[source]

Bases: str, Enum

Edge types for simulation snapshots.

Maps to constitution I.6 edge modes.

ADJACENCY = 'ADJACENCY'

EXTRACTION = 'EXTRACTION'

SOLIDARITY = 'SOLIDARITY'

ANTAGONISTIC = 'ANTAGONISTIC'

class babylon.models.CommunityType(*values)[source]

Bases: StrEnum

Community types for hypergraph membership (Constitution II.7).

Three structurally distinct categories — NOT a spectrum.

Category 1 — Contradiction Pairs (both sides real hyperedges):: SETTLER: Settler nation (hegemonic). Institutions: HOAs, police unions, border militias. NEW_AFRIKAN: New Afrikan / Black internal nation (marginalized) FIRST_NATIONS: Indigenous / First Nations peoples (marginalized) CHICANO: Chicano / Mexican-American nation (marginalized) PATRIARCHAL: Patriarchal order (hegemonic). Institutions: gendered wage systems, family structure. WOMEN: Women — reproductive labor allocation (marginalized) TRANS: Transgender / gender non-conforming (marginalized)
Category 2 — Institutional Exclusion (only marginalized side):: DISABLED: Disabled community. Built environment assumes able-bodiedness. QUEER: Queer / LGBQ. Institutional heteronormativity. UNDOCUMENTED: Undocumented. Legal exclusion from protections. INCARCERATED: Incarcerated. Carceral system, civil death.
Category 3 — Lifecycle Phases (D-P-D’ Circuit):: YOUTH: D phase. Pre-productive, dependent, receives socialization. ADULT: P phase. Sells labor-power. Where C-M-C and M-C-M’ operate. ELDER: D’ phase. Post-productive. Legitimation bargain (pensions, Social Security).

SETTLER = 'settler'

PATRIARCHAL = 'patriarchal'

NEW_AFRIKAN = 'new_afrikan'

FIRST_NATIONS = 'first_nations'

CHICANO = 'chicano'

WOMEN = 'women'

TRANS = 'trans'

DISABLED = 'disabled'

QUEER = 'queer'

UNDOCUMENTED = 'undocumented'

INCARCERATED = 'incarcerated'

YOUTH = 'youth'

ADULT = 'adult'

ELDER = 'elder'

class babylon.models.LegalStatus(*values)[source]

Bases: StrEnum

Legal designation status for community-level state repression.

Hypergraph Community Layer (Feature 022): Escalation is strictly one-way for state action. De-escalation requires political struggle (player action). Each level increases the threat multiplier applied to community members.

Values:: LEGAL: Normal status, minimal state attention (multiplier 0.1) SURVEILLED: Active monitoring (multiplier 0.5) DESIGNATED_EXTREMIST: Formal extremist designation (multiplier 1.0) DESIGNATED_TERRORIST: Formal terrorist designation (multiplier 2.0) CRIMINALIZED: Membership itself criminalized (multiplier 3.0)

LEGAL = 'legal'

SURVEILLED = 'surveilled'

DESIGNATED_EXTREMIST = 'designated_extremist'

DESIGNATED_TERRORIST = 'designated_terrorist'

CRIMINALIZED = 'criminalized'

class babylon.models.MembershipRole(*values)[source]

Bases: StrEnum

Agent integration level within a community.

Hypergraph Community Layer (Feature 022): Determines membership strength weight and visibility profile for threat score computation.

Values:: CORE_ORGANIZER: Infrastructure maintainers, visible leaders (weight 1.0) ACTIVE: Regular participants, known within community (weight 0.7) PARTICIPANT: Occasional engagement (weight 0.4) PERIPHERAL: Marginal connection (weight 0.2) SYMPATHIZER: External ally, not legible as member (weight 0.1)

CORE_ORGANIZER = 'core_organizer'

ACTIVE = 'active'

PARTICIPANT = 'participant'

PERIPHERAL = 'peripheral'

SYMPATHIZER = 'sympathizer'

class babylon.models.CommunityState(**data)[source]

Bases: BaseModel

State of a community, independent of its members.

Each community has collective attributes tracking state attention, internal cohesion, organizational infrastructure, and material modifiers applied to all members.

Parameters:

community_type (CommunityType) – Identity of this community.
heat (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – State attention/surveillance intensity [0, 1].
legal_status (LegalStatus) – Current legal designation (one-way escalation).
cohesion (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Internal trust and mutual aid effectiveness [0, 1].
infrastructure (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Organizational capacity (meeting spaces, comms) [0, 1].
visibility (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Community legibility to state surveillance [0, 1].
reproduction_cost_modifier (float) – Multiplier on V_reproduction for members.
rent_access_modifier (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Multiplier on imperial rent received by members.
category (HyperedgeCategory)
consciousness (TernaryConsciousness)
education_pressure (float)

property infiltration_resistance: float

Community resistance to state infiltration.

Formula: CI * 0.6 + cohesion * 0.3 + CI * cohesion * 0.1

Returns:: Resistance score in [0.0, 1.0].

property is_cross_class_bridge: bool

Whether this community can span contradiction axes.

Only INSTITUTIONAL_EXCLUSION communities bridge across axes because their members can come from both hegemonic and marginalized sides.

Returns:: True if the community is an institutional exclusion type.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

community_type: CommunityType

category: HyperedgeCategory

heat: Probability

legal_status: LegalStatus

cohesion: Probability

infrastructure: Probability

visibility: Probability

reproduction_cost_modifier: float

rent_access_modifier: Coefficient

consciousness: CommunityConsciousness

education_pressure: float

class babylon.models.CommunityMembership(**data)[source]

Bases: BaseModel

An agent’s membership in a community.

Represents the relationship between an individual agent and a community hyperedge. Each membership has a role determining integration level and a visibility determining legibility to state.

Parameters:

agent_id (str) – Identifier of the member agent.
community_type (CommunityType) – Which community this membership is in.
role (MembershipRole) – Integration level within the community.
strength (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Formula parameter in range [0, 1]', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Membership weight [0, 1], derived from role default.
visibility (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Base legibility to state [0, 1].
overt (bool) – Publicly identified — overrides visibility to 1.0.

property effective_visibility: float

Effective visibility accounting for overt flag.

Returns:: 1.0 if overt, otherwise the base visibility value.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

agent_id: str

community_type: CommunityType

role: MembershipRole

strength: Coefficient

visibility: Probability

overt: bool

class babylon.models.HyperedgeCategory(*values)[source]

Bases: StrEnum

Structural category for community hyperedges (Feature 029, Constitution II.7).

Three qualitatively distinct categories with different material bases, relationships to oppression, and modeling requirements.

Values:

CONTRADICTION_PAIR: Both hegemonic and marginalized sides exist as real: hyperedges with extraction flows between them.
INSTITUTIONAL_EXCLUSION: Only marginalized side exists. Oppression flows: through institutional defaults, not a paired oppressor community.
LIFECYCLE_PHASE: Temporal positions in D-P-D’ intergenerational lifecycle.: Universal, temporally permeable, defined by relationship to production.
ECONOMIC_SECTOR: Industry sectors represented by 2-digit NAICS codes. Used: for tracking economic metabolism, business coordination, and profit equalization.

CONTRADICTION_PAIR = 'contradiction_pair'

INSTITUTIONAL_EXCLUSION = 'institutional_exclusion'

LIFECYCLE_PHASE = 'lifecycle_phase'

ECONOMIC_SECTOR = 'economic_sector'

class babylon.models.ConsciousnessTendency(*values)[source]

Bases: StrEnum

Dominant ideological tendency within a community (Feature 029).

Represents the prevailing direction of collective consciousness — the default drift without active organizing.

Values:

LIBERAL: Seeks inclusion in existing institutions without transforming: them. Organizational vehicle: liberal CSOs, Democratic Party.
FASCIST: Collaboration with hegemonic order for individual escape.: Strategy: shrink the marginalized definition, exclude the most marginal.
REVOLUTIONARY: Oppositional collective identity, independent power.: The contradiction is material, not a misunderstanding.

LIBERAL = 'liberal'

FASCIST = 'fascist'

REVOLUTIONARY = 'revolutionary'

babylon.models.CommunityConsciousness: alias of TernaryConsciousness

class babylon.models.ContradictionType(*values)[source]

Bases: StrEnum

Main axes of structural contradiction (Constitutional Framework).

Moving away from hardcoded models towards a dynamic Maoist contradiction framework. Defines the principal and secondary axes at a given scale.

NATIONAL = 'national'

CLASS = 'class'

GENDER = 'gender'

IMPERIAL = 'imperial'

ECOLOGICAL = 'ecological'

class babylon.models.TernaryConsciousness(**data)[source]

Bases: BaseModel

A point in the 2-simplex representing community consciousness.

Three components (r, l, f) sum to 1.0: - r: Revolutionary consciousness (distance from assimilation). - l: Liberal consciousness (reform within existing order). - f: Fascist consciousness (exclusionary reaction).

Supports two construction paths: 1. Native: TernaryConsciousness(r=0.5, l=0.3, f=0.2) 2. Legacy: ``TernaryConsciousness(collective_identity=0.5,

dominant_tendency=LIBERAL, ideological_contestation=0.4)``

Both produce valid simplex points with backward-compatible properties.

Parameters:

r (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Revolutionary component [0, 1].
l (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Liberal component [0, 1].
f (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Fascist component [0, 1].
contestation_stored (float | None) – Preserved legacy contestation value, or None for natively constructed instances (uses Shannon entropy).

property assimilation_ratio: float

f / (l + f).

Measures how much of the non-revolutionary consciousness is fascist. When l + f is near zero (fully revolutionary), returns 0.5 (neutral).

Returns:: Ratio in [0, 1]. 0 = pure liberal, 1 = pure fascist.
Type:: Position along the liberal-fascist base

property collective_identity: float

Oppositional consciousness [0, 1]. Equals r component.

Returns:: The revolutionary component, semantically identical to the old CommunityConsciousness.collective_identity.

property dominant_tendency: ConsciousnessTendency

Prevailing ideological direction (argmax of r, l, f).

Ties are broken in favor of liberal (structural advantage of the status quo — you have to actively organize to leave liberalism).

Returns:: ConsciousnessTendency corresponding to the largest component.

property ideological_contestation: float

Active debate between tendencies [0, 1].

If contestation_stored is set (legacy construction), returns that value for backward compatibility. Otherwise computes normalized Shannon entropy of (r, l, f): H(r,l,f) / log(3).

Returns:: Contestation level. 0 = monopoly, 1 = maximum contestation.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

r: Probability

l: Probability

f: Probability

contestation_stored: float | None

class babylon.models.SubstrateFloor(**data)[source]

Bases: BaseModel

Per-community-type minimum revolutionary consciousness with provenance.

The substrate floor is consciousness that persists even when all organizations are destroyed — the grandmother teaching not to talk to cops, survival knowledge transmitted through socialization.

Parameters:

community_type (CommunityType) – Which community this floor applies to.
floor_value (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Minimum r regardless of org landscape [0, 1].
confidence (ProvenanceLevel) – Data quality indicator.
data_sources (list[str]) – Named data sources used.
computation_method (str) – How floor was derived from proxies.

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

community_type: CommunityType

floor_value: Probability

confidence: ProvenanceLevel

data_sources: list[str]

computation_method: str

class babylon.models.ProvenanceLevel(*values)[source]

Bases: StrEnum

Data quality indicator for substrate floor computation.

Values:: HIGH: Derived from 2+ independent proxy data sources. MEDIUM: Derived from 1 proxy data source. LOW: Estimated from related data, not direct proxy. SYNTHETIC: Stipulated placeholder with no data path.

HIGH = 'high'

MEDIUM = 'medium'

LOW = 'low'

SYNTHETIC = 'synthetic'

class babylon.models.OrgContribution(**data)[source]

Bases: BaseModel

An organization’s weighted contribution to community consciousness.

Used as input to the compute_ternary_consciousness function.

Parameters:

tendency (ConsciousnessTendency) – Which vertex this org pulls toward.
membership_density (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Members in community / community population [0, 1].
cadre_level (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Organizational development level [0, 1].
cohesion (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Value in range [0.0, 1.0] representing likelihood', metadata=[Ge(ge=0.0), Le(le=1.0)]), AfterValidator(func=~babylon.utils.math.quantize)]) – Internal organizational cohesion [0, 1].

model_config: ClassVar[ConfigDict] = {'frozen': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

tendency: ConsciousnessTendency

membership_density: Probability

cadre_level: Probability

cohesion: Probability

Modules

`components`	Component system for the Babylon Entity-Component architecture.
`config`	Simulation configuration for the Babylon engine.
`entities`	Entity models for the Babylon simulation.
`entity_registry`	Entity ID registry - single source of truth for entity ID mappings.
`enums`	Enumeration types for the Babylon simulation.
`events`	Pydantic event models for structured simulation events.
`graph`	Graph abstraction layer data models.
`metrics`	Metrics data models for simulation observation and analysis.
`scenario`	Scenario configuration for multiverse simulation injection.
`snapshots`	Snapshot types for the MVP simulation engine.
`topology_metrics`	Topology metrics data models for the Condensation Monitor (Sprint 3.1).
`types`	Constrained value types for the Babylon simulation.
`vanguard_resources`	Vanguard Economy resource model (Wayne County MVP).
`world_state`	WorldState model for the Babylon simulation.