babylon.config

Configuration package for Babylon/Babylon.

The configuration hierarchy: 1. Environment variables (.env file) 2. Default values (defined in each config class)

All configs are immutable after initialization.

class babylon.config.BaseConfig[source]

Bases: object

Base configuration singleton.

All values are class attributes for direct access without instantiation. This mirrors the material reality: configuration exists whether you acknowledge it or not.

APP_NAME: Final[str] = 'Babylon'
VERSION: Final[str] = '0.2.0'
DEBUG: Final[bool] = False
TESTING: Final[bool] = False
DATABASE_URL: Final[str] = 'sqlite:////home/runner/work/babylon/babylon/docs/data/sqlite/babylon.sqlite'
LOG_LEVEL: Final[str] = 'INFO'
LOG_FORMAT: Final[str] = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
LOG_DIR: Final[Path] = PosixPath('logs')
METRICS_ENABLED: Final[bool] = True
METRICS_INTERVAL: Final[int] = 60
BASE_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon')
DATA_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon/data')
EXTERNAL_DATA_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon/data/external')
classmethod get_database_url()[source]

Get the database URL, resolving any path variables.

Return type:

str

classmethod ensure_directories()[source]

Ensure all required directories exist.

The material preconditions for operation must be established.

Return type:

None

class babylon.config.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: - crisis: Crisis detection and devaluation mechanics (Feature 018) - 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) - carceral: Carceral equilibrium (Terminal Crisis Dynamics) - endgame: Endgame detection thresholds - initial: Initial conditions - contradiction_field: Dialectical field topology (Feature 002) - reserve_army: Reserve army of labor coefficients (Feature 021) - dispossession: Dispossession event intensity weights (Feature 021) - working_day: Working day characterization thresholds (Feature 021) - community: Hypergraph community layer coefficients (Feature 022) - class_dynamics: Class wealth flow dynamics (Feature 016, FRED DFA-derived) - edge_transition: Edge mode transition thresholds (Feature 002) - organization: Organization system coefficients (Feature 031) - ooda: OODA loop system coefficients (Feature 032) - class_system: Unified class system coefficients (Feature 038) - bifurcation: Bifurcation topology analysis coefficients (Feature 033) - infra_terrain: Terrain classification and biocapacity coefficients (Feature 036) - infrastructure: Infrastructure capacity and internet coefficients (Feature 036)

Parameters:
model_config: ClassVar[ConfigDict] = {'frozen': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

crisis: CrisisDefines
mobilize: MobilizeDefines
economy: EconomyDefines
survival: SurvivalDefines
vitality: VitalityDefines
solidarity: SolidarityDefines
behavioral: BehavioralDefines
tension: TensionDefines
consciousness: ConsciousnessDefines
territory: TerritoryDefines
topology: TopologyDefines
metabolism: MetabolismDefines
struggle: StruggleDefines
carceral: CarceralDefines
endgame: EndgameDefines
initial: InitialDefines
precision: PrecisionDefines
timescale: TimescaleDefines
external_data: ExternalDataDefines
contradiction_field: ContradictionFieldDefines
reserve_army: ReserveArmyDefines
dispossession: DispossessionDefines
working_day: WorkingDayDefines
community: CommunityDefines
class_dynamics: ClassDynamicsDefines
edge_transition: EdgeTransitionDefines
lifecycle: LifecycleDefines
organization: OrganizationDefines
ooda: OODADefines
bifurcation: BifurcationDefines
infra_terrain: InfraTerrainDefines
infrastructure: InfrastructureDefines
rent_circuit: RentCircuitDefines
class_system: ClassSystemDefines
state_ai: StateApparatusAIDefines
institution: InstitutionDefines
move: MoveDefines
negotiate: NegotiateDefines
reactionary: ReactionaryDefines
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 conventional path for an optional defines.yaml override.

The repository does not ship a defines.yaml (the file was removed in commit 4ce7c96a when the data layer was extracted). Callers may drop a YAML at this path to override the dataclass defaults compiled into GameDefines; if the file is absent, load_default() returns the dataclass defaults unchanged.

Return type:

Path

Returns:

Path pointing at src/babylon/data/defines.yaml (which may or may not exist on disk).

classmethod load_default()[source]

Load GameDefines, preferring the optional YAML override.

If src/babylon/data/defines.yaml exists, it is loaded as a full override of the dataclass defaults. Otherwise the dataclass defaults are returned. The repository ships without the YAML, so the dataclass defaults are the canonical values today.

Return type:

GameDefines

Returns:

GameDefines instance — YAML-loaded if present, otherwise the dataclass defaults.

class babylon.config.LLMConfig[source]

Bases: object

Configuration for LLM API integration.

Supports hybrid setup: - Chat: DeepSeek (primary) / OpenAI (fallback) - Embeddings: Ollama (local, default) / OpenAI (cloud)

The bourgeois cloud API is a transitional tool until local compute infrastructure is fully established.

API_KEY: Final[str] = ''
API_BASE: Final[str] = 'https://api.deepseek.com'
ORGANIZATION_ID: Final[str] = ''
CHAT_MODEL: Final[str] = 'deepseek-chat'
EMBEDDING_PROVIDER: Final[str] = 'ollama'
EMBEDDING_API_BASE: Final[str] = 'http://localhost:11434'
EMBEDDING_MODEL: Final[str] = 'embeddinggemma:latest'
MAX_RETRIES: Final[int] = 3
RETRY_DELAY: Final[float] = 1.0
RATE_LIMIT_RPM: Final[int] = 60
BATCH_SIZE: Final[int] = 8
REQUEST_TIMEOUT: Final[float] = 30.0
classmethod is_configured()[source]

Check if Chat LLM API is properly configured.

Return type:

bool

classmethod is_ollama_embeddings()[source]

Check if using Ollama for embeddings (local, no API key needed).

Return type:

bool

classmethod get_headers()[source]

Get HTTP headers for Chat API requests.

Return type:

dict[str, str]

classmethod get_embedding_headers()[source]

Get HTTP headers for Embedding API requests.

Ollama doesn’t need auth headers; OpenAI does.

Return type:

dict[str, str]

classmethod get_embedding_url()[source]

Get the embedding API URL based on provider.

Return type:

str

classmethod validate()[source]

Validate the Chat LLM configuration.

Raises:

ValueError – If required configuration is missing

Return type:

None

classmethod validate_embeddings()[source]

Validate embedding configuration.

For Ollama: Just check the base URL is set. For OpenAI: Check API key is available.

Raises:

ValueError – If required configuration is missing

Return type:

None

classmethod get_model_dimensions()[source]

Get the embedding dimensions for the configured model.

Return type:

int

Returns:

Number of dimensions for the embedding model

babylon.config.OpenAIConfig

alias of LLMConfig

class babylon.config.TestingConfig[source]

Bases: object

Configuration for test environments.

Uses in-memory SQLite and temporary directories to ensure test isolation and reproducibility.

DATABASE_URL: Final[str] = 'sqlite:///:memory:'
DB_POOL_SIZE: Final[int] = 1
DB_MAX_OVERFLOW: Final[int] = 0
LOG_LEVEL: Final[str] = 'DEBUG'
LOG_DIR: Final[Path] = PosixPath('/tmp/babylon_test_logs')
METRICS_ENABLED: Final[bool] = True
TESTING: Final[bool] = True
DEBUG: Final[bool] = True
babylon.config.setup_logging(config_path=None, default_level=None, pyproject_path=None)[source]

Initialize the logging system.

Parameters:

  • config_path (Path | None) – Path to a YAML logging configuration file. If None, uses pyproject.toml or default configuration.

  • default_level (str | None) – Override for the default log level.

  • pyproject_path (Path | None) – Path to pyproject.toml (optional, auto-detected).

Return type:

None

Configuration is loaded in this order (highest precedence first): 1. LOG_LEVEL environment variable 2. default_level parameter 3. pyproject.toml [tool.babylon.logging] section 4. logging.yaml file (if config_path provided) 5. Default values

The logging system is deterministic - given the same inputs, it produces the same outputs. No probabilistic behavior.

Handler hierarchy: - Console: Human-readable, INFO level (or configured level) - Main file (RotatingFileHandler): JSON Lines, DEBUG level, 10MB rotation - Error file (RotatingFileHandler): JSON Lines, ERROR only, 5MB rotation

Modules

base

Base configuration for the Babylon/Babylon engine.

defines

Game defines for centralized coefficient configuration.

h3_splitter

Canonical H3 disaggregation rules — spec 060 FR-011 exception.

llm_config

LLM API configuration for text generation and embeddings.

logging_config

Logging configuration for Babylon/Babylon.

testing

Testing configuration for Babylon/Babylon.