babylon.config.defines

Game defines for centralized coefficient configuration.

This module provides the GameDefines model which extracts hardcoded values from systems into a single, configurable location. This enables: 1. Easier calibration of game balance 2. Scenario-specific coefficient overrides 3. Clear documentation of magic numbers

Sprint: Paradox Refactor Phase 1

Classes

`BehavioralDefines`(**data)	Behavioral economics coefficients.
`ConsciousnessDefines`(**data)	Consciousness drift coefficients.
`EconomyDefines`(**data)	Economic system coefficients.
`GameDefines`(**data)	Centralized game coefficients extracted from hardcoded values.
`InitialDefines`(**data)	Initial condition coefficients.
`MetabolismDefines`(**data)	Metabolic rift coefficients (Slice 1.4 - Ecological Limits).
`SolidarityDefines`(**data)	Solidarity and consciousness transmission coefficients.
`StruggleDefines`(**data)	Struggle dynamics coefficients (Agency Layer - "George Floyd" Dynamic).
`SurvivalDefines`(**data)	Survival calculus coefficients.
`TensionDefines`(**data)	Tension dynamics coefficients.
`TerritoryDefines`(**data)	Territory dynamics coefficients.
`TopologyDefines`(**data)	Phase transition coefficients for solidarity network analysis.

class babylon.config.defines.EconomyDefines(**data)[source]

Bases: BaseModel

Economic system coefficients.

Parameters:

extraction_efficiency (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
comprador_cut (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
super_wage_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
superwage_multiplier (Annotated[float, Ge(ge=0)])
superwage_ppp_impact (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
initial_rent_pool (Annotated[float, Ge(ge=0)])
pool_high_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
pool_low_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
pool_critical_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
min_wage_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
max_wage_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
subsidy_conversion_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
subsidy_trigger_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
negligible_rent (Annotated[float, Ge(ge=0)])
negligible_subsidy (Annotated[float, Ge(ge=0)])

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

extraction_efficiency: float

comprador_cut: float

super_wage_rate: float

superwage_multiplier: float

superwage_ppp_impact: float

initial_rent_pool: float

pool_high_threshold: float

pool_low_threshold: float

pool_critical_threshold: float

min_wage_rate: float

max_wage_rate: float

subsidy_conversion_rate: float

subsidy_trigger_threshold: float

negligible_rent: float

negligible_subsidy: float

class babylon.config.defines.SurvivalDefines(**data)[source]

Bases: BaseModel

Survival calculus coefficients.

Parameters:

steepness_k (Annotated[float, Gt(gt=0)])
default_subsistence (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
default_organization (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
default_repression (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
revolution_threshold (Annotated[float, Gt(gt=0)])
repression_base (Annotated[float, 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].

steepness_k: float

default_subsistence: float

default_organization: float

default_repression: float

revolution_threshold: float

repression_base: float

class babylon.config.defines.SolidarityDefines(**data)[source]

Bases: BaseModel

Solidarity and consciousness transmission coefficients.

Parameters:

scaling_factor (Annotated[float, Ge(ge=0.0), Le(le=2.0)])
activation_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
mass_awakening_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
negligible_transmission (Annotated[float, Ge(ge=0)])
superwage_impact (Annotated[float, Ge(ge=0)])

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

scaling_factor: float

activation_threshold: float

mass_awakening_threshold: float

negligible_transmission: float

superwage_impact: float

class babylon.config.defines.BehavioralDefines(**data)[source]

Bases: BaseModel

Behavioral economics coefficients.

Parameters:: loss_aversion_lambda (Annotated[float, Gt(gt=0)])

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

loss_aversion_lambda: float

class babylon.config.defines.TensionDefines(**data)[source]

Bases: BaseModel

Tension dynamics coefficients.

Parameters:: accumulation_rate (Annotated[float, 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].

accumulation_rate: float

class babylon.config.defines.ConsciousnessDefines(**data)[source]

Bases: BaseModel

Consciousness drift coefficients.

Parameters:

sensitivity (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
decay_lambda (Annotated[float, Gt(gt=0)])

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

sensitivity: float

decay_lambda: float

class babylon.config.defines.TerritoryDefines(**data)[source]

Bases: BaseModel

Territory dynamics coefficients.

Parameters:

heat_decay_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
high_profile_heat_gain (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
eviction_heat_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
rent_spike_multiplier (Annotated[float, Gt(gt=0)])
displacement_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
heat_spillover_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
clarity_profile_coefficient (Annotated[float, 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].

heat_decay_rate: float

high_profile_heat_gain: float

eviction_heat_threshold: float

rent_spike_multiplier: float

displacement_rate: float

heat_spillover_rate: float

clarity_profile_coefficient: float

class babylon.config.defines.TopologyDefines(**data)[source]

Bases: BaseModel

Phase transition coefficients for solidarity network analysis.

The topology system tracks phase transitions in class solidarity: - Gaseous: Atomized, no collective action capacity - Transitional: Solidarity building, weak ties forming - Liquid: Mass movement (percolation but low cadre density) - Solid: Vanguard party (percolation with high cadre density)

Parameters:

gaseous_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
condensation_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
vanguard_density_threshold (Annotated[float, 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].

gaseous_threshold: float

condensation_threshold: float

vanguard_density_threshold: float

class babylon.config.defines.MetabolismDefines(**data)[source]

Bases: BaseModel

Metabolic rift coefficients (Slice 1.4 - Ecological Limits).

The Metabolism System tracks the widening rift between extraction and regeneration: - Biocapacity regeneration and depletion - ECOLOGICAL_OVERSHOOT event when consumption exceeds biocapacity

Parameters:

entropy_factor (Annotated[float, Gt(gt=1.0), Le(le=3.0)])
overshoot_threshold (Annotated[float, Gt(gt=0.0), Le(le=2.0)])
max_overshoot_ratio (Annotated[float, Gt(gt=0)])

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

entropy_factor: float

overshoot_threshold: float

max_overshoot_ratio: float

class babylon.config.defines.StruggleDefines(**data)[source]

Bases: BaseModel

Struggle dynamics coefficients (Agency Layer - “George Floyd” Dynamic).

The Struggle System gives political agency to oppressed classes by modeling: - The Spark: State violence (EXCESSIVE_FORCE) triggers insurrection - The Combustion: Spark + High Agitation + Low P(S|A) = UPRISING - The Result: Uprisings destroy wealth but build solidarity infrastructure

Parameters:

spark_probability_scale (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
resistance_threshold (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
wealth_destruction_rate (Annotated[float, Ge(ge=0.0), Le(le=1.0)])
solidarity_gain_per_uprising (Annotated[float, 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].

spark_probability_scale: float

resistance_threshold: float

wealth_destruction_rate: float

solidarity_gain_per_uprising: float

class babylon.config.defines.InitialDefines(**data)[source]

Bases: BaseModel

Initial condition coefficients.

Parameters:

worker_wealth (Annotated[float, Ge(ge=0)])
owner_wealth (Annotated[float, Ge(ge=0)])

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

worker_wealth: float

owner_wealth: float

class babylon.config.defines.GameDefines(**data)[source]

Bases: BaseModel

Centralized game coefficients extracted from hardcoded values.

GameDefines collects numerical constants that were previously scattered across system implementations. By centralizing them here, we can: - Document their purpose and valid ranges - Override them per-scenario for calibration - Test the sensitivity of outcomes to coefficient changes

The model is frozen (immutable) to ensure defines remain constant throughout a simulation run.

Structure follows the YAML file organization: - economy: Imperial rent extraction and value flow - survival: P(S|A) and P(S|R) survival calculus - solidarity: Consciousness transmission - behavioral: Behavioral economics (loss aversion) - tension: Tension dynamics - consciousness: Consciousness drift - territory: Territory dynamics - topology: Phase transition thresholds (gaseous/liquid/solid) - metabolism: Metabolic rift (ecological limits) - struggle: Struggle dynamics (Agency Layer) - initial: Initial conditions

Parameters:

economy (EconomyDefines)
survival (SurvivalDefines)
solidarity (SolidarityDefines)
behavioral (BehavioralDefines)
tension (TensionDefines)
consciousness (ConsciousnessDefines)
territory (TerritoryDefines)
topology (TopologyDefines)
metabolism (MetabolismDefines)
struggle (StruggleDefines)
initial (InitialDefines)

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

economy: EconomyDefines

survival: SurvivalDefines

solidarity: SolidarityDefines

behavioral: BehavioralDefines

tension: TensionDefines

consciousness: ConsciousnessDefines

territory: TerritoryDefines

topology: TopologyDefines

metabolism: MetabolismDefines

struggle: StruggleDefines

initial: InitialDefines

property SUPERWAGE_IMPACT: float: How much 1 unit of imperial extraction increases Core wealth.

property SOLIDARITY_SCALING: float: Multiplier for graph edge weights affecting Organization.

property REPRESSION_BASE: float: Base resistance to revolution in P(S|R) denominator.

property REVOLUTION_THRESHOLD: float: The tipping point for P(S|R) formula.

property DEFAULT_ORGANIZATION: float: Fallback organization value when not specified on entity.

property DEFAULT_REPRESSION_FACED: float: Fallback repression value when not specified on entity.

property DEFAULT_SUBSISTENCE: float: Fallback subsistence threshold when not specified on entity.

property NEGLIGIBLE_TRANSMISSION: float: Threshold below which transmissions are skipped as noise.

classmethod load_from_yaml(path)[source]

Load GameDefines from a YAML file.

Parameters:

path (str | Path) – Path to the YAML file (absolute or relative)

Return type:

GameDefines

Returns:

GameDefines instance populated from YAML

Raises:

FileNotFoundError – If the YAML file doesn’t exist
yaml.YAMLError – If the YAML is malformed
pydantic.ValidationError – If values fail validation

classmethod default_yaml_path()[source]

Return the default path to defines.yaml.

Return type:: Path
Returns:: Path to src/babylon/data/defines.yaml

classmethod load_default()[source]

Load GameDefines from the default YAML location.

Falls back to default values if file doesn’t exist.

Return type:: GameDefines
Returns:: GameDefines instance