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

CORE_BOURGEOISIE = 'core_bourgeoisie'

PERIPHERY_PROLETARIAT = 'periphery_proletariat'

LABOR_ARISTOCRACY = 'labor_aristocracy'

PETTY_BOURGEOISIE = 'petty_bourgeoisie'

LUMPENPROLETARIAT = 'lumpenproletariat'

COMPRADOR_BOURGEOISIE = 'comprador_bourgeoisie'

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)

EXPLOITATION = 'exploitation'

SOLIDARITY = 'solidarity'

REPRESSION = 'repression'

COMPETITION = 'competition'

TRIBUTE = 'tribute'

WAGES = 'wages'

CLIENT_STATE = 'client_state'

TENANCY = 'tenancy'

ADJACENCY = 'adjacency'

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)])])
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)])])
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)])])
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)])])
initial_worker_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
initial_owner_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])
initial_rent_pool (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
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)])])
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)])])
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)])])
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)])])
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)])])
superwage_multiplier (float)
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)])])
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)])])
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)])])
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)])])
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)])])
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)])])

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_multiplier: 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)])])
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)])])

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

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)])]: 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)])]: 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]

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)])])
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)])])
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)])])
subsistence_threshold (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
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)])])
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)])])
effective_wealth (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
unearned_increment (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
ppp_multiplier (float)
s_bio (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
s_class (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])

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)])]: Total consumption required per tick (Wealth-independent demand).

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

property ideological: IdeologicalComponent: Return ideological 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

s_bio: Annotated[float]

s_class: Annotated[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)])])
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)])])
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)])])
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)])])

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)])])
super_wage_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
repression_level (Annotated[float, Ge(ge=0.0), Le(le=1.0)])

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

Bases: BaseModel

The current state of a dialectical contradiction.

A contradiction is a structural tension between two forces that cannot both be satisfied within the current system. This is the primary model for tracking contradictions.

Parameters:

id (str)
name (str)
description (str)
thesis (str)
antithesis (str)
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)])])
momentum (float)
is_principal (bool)
resolved (bool)

id: Unique identifier (flexible format for runtime use)

name: Human-readable name

description: Detailed explanation

thesis: The dominant position

antithesis: The opposing position

tension: Current tension level [0, 1]

momentum: Rate of change [-1, 1]

is_principal: Is this the principal contradiction?

resolved: Has this been resolved?

property intensity_level: IntensityLevel: Convert continuous tension to discrete IntensityLevel.

property is_critical: bool: Check if tension is at critical level (rupture imminent).

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

id: str

name: str

description: str

thesis: str

antithesis: str

tension: Annotated[float]

momentum: float

is_principal: bool

resolved: bool

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

Bases: BaseModel

The result of a contradiction reaching resolution.

When a contradiction resolves (tension reaches 0 or 1), this model captures what happened and the consequences.

Parameters:

contradiction_id (str)
resolution_type (ResolutionType)
new_contradictions (list[str])
system_changes (dict[str, float])

contradiction_id: ID of the resolved contradiction

resolution_type: How it resolved (synthesis, rupture, suppression)

new_contradictions: IDs of contradictions spawned by resolution

system_changes: Metric deltas caused by resolution

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

contradiction_id: str

resolution_type: ResolutionType

new_contradictions: list[str]

system_changes: dict[str, float]

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

Bases: BaseModel

Full contradiction model with entities and resolution methods.

This is a more detailed model for contradictions that includes references to entities and resolution mechanics. Used for game content definition.

Parameters:

id (Annotated[str, _PydanticGeneralMetadata(pattern='^CON[0-9]{3}$')])
name (str)
description (str)
entity_ids (list[str])
principal_aspect_id (str | None)
secondary_aspect_id (str | None)
principal_contradiction_id (str | None)
universality (Annotated[str, _PydanticGeneralMetadata(pattern='^(Universal|Particular)$')])
particularity (str)
antagonism (Annotated[str, _PydanticGeneralMetadata(pattern='^(Primary|Secondary)$')])
intensity (IntensityLevel)
state (Annotated[str, _PydanticGeneralMetadata(pattern='^(Active|Resolved|Latent)$')])
potential_for_transformation (IntensityLevel)
conditions_for_transformation (list[str])
resolution_methods (dict[str, list[Effect]])
intensity_history (list[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)])]])

id: Unique identifier

name: Human-readable name

description: Detailed explanation

entity_ids: IDs of entities involved in this contradiction

universality: Universal or Particular

particularity: Domain (Economic, Political, etc.)

principal_contradiction_id: ID of the principal contradiction (if this is secondary)

principal_aspect_id: ID of the entity representing the principal aspect

secondary_aspect_id: ID of the entity representing the secondary aspect

antagonism: Primary or Secondary antagonism

intensity: Current intensity level

state: Active, Resolved, or Latent

potential_for_transformation: How likely to transform

conditions_for_transformation: What conditions must be met

resolution_methods: Mapping of method names to Effects

property intensity_value: float: Get numerical value for intensity.

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

record_intensity()[source]

Record current intensity in history.

Return type:: None

id: str

name: str

description: str

entity_ids: list[str]

principal_aspect_id: str | None

secondary_aspect_id: str | None

principal_contradiction_id: str | None

universality: str

particularity: str

antagonism: str

intensity: IntensityLevel

state: str

potential_for_transformation: IntensityLevel

conditions_for_transformation: list[str]

resolution_methods: dict[str, list[Effect]]

intensity_history: list[Annotated[float]]

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 (Annotated[int, Ge(ge=0)])
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)])])
resources (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
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)])])

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)])])
subsistence_needs (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])

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

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

Bases: BaseModel

Multi-dimensional ideological state (George Jackson Model).

Tracks the ideological state of an entity using three axes: - Relationship to Capital (class consciousness) - Relationship to State/Tribe (national identity) - Accumulated political energy (agitation)

The bifurcation mechanism: - When wages fall, agitation accumulates - If solidarity edges exist: agitation routes to class_consciousness - If no solidarity edges: agitation routes to national_identity

All values use constrained floats for automatic validation: - class_consciousness: [0, 1] (0=False Consciousness, 1=Revolutionary) - national_identity: [0, 1] (0=Internationalist, 1=Fascist) - agitation: [0, inf) (no upper bound - accumulates during crises)

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

Parameters:

class_consciousness (float)
national_identity (float)
agitation (float)

class_consciousness: Relationship to Capital [0=False, 1=Revolutionary] (default: 0.0)

national_identity: Relationship to State [0=Internationalist, 1=Fascist] (default: 0.5)

agitation: Raw political energy from wage crises [0, inf) (default: 0.0)

property component_type: str

Return the component type identifier.

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

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

class_consciousness: float

national_identity: float

agitation: 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)])])
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)])])

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)])])
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)])])
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)])])
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)])])
agitation (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)])])
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)])])
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)])])
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)])])

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: Probability

p_acquiescence: Probability

p_revolution: Probability

organization: Probability

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)])])
exploitation_rent (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
tribute_flow (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
wages_paid (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])
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)])])

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)])])
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)])])
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)])])
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)])])
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)])])
total_consumption (Annotated[float, FieldInfo(annotation=NoneType, required=True, description='Non-negative economic value (wealth, wages, rent, GDP)', metadata=[Ge(ge=0.0)])])

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

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

Modules

`components`	Component system for the Babylon Entity-Component architecture.
`config`	Simulation configuration for the Babylon engine.
`entities`	Entity models for the Babylon simulation.
`enums`	Enumeration types for the Babylon simulation.
`events`	Pydantic event models for structured simulation events.
`metrics`	Metrics data models for simulation observation and analysis.
`scenario`	Scenario configuration for multiverse simulation injection.
`topology_metrics`	Topology metrics data models for the Condensation Monitor (Sprint 3.1).
`types`	Constrained value types for the Babylon simulation.
`world_state`	WorldState model for the Babylon simulation.