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

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'

BASE_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon')

DATABASE_URL: Final[str] = 'sqlite:////home/runner/work/babylon/babylon/docs/data/babylon.db'

DATA_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon/data')

DEBUG: Final[bool] = False

EXTERNAL_DATA_DIR: Final[Path] = PosixPath('/home/runner/work/babylon/babylon/data/external')

LOG_DIR: Final[Path] = PosixPath('logs')

LOG_FORMAT: Final[str] = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

LOG_LEVEL: Final[str] = 'INFO'

METRICS_ENABLED: Final[bool] = True

METRICS_INTERVAL: Final[int] = 60

TESTING: Final[bool] = False

VERSION: Final[str] = '0.2.0'

classmethod ensure_directories()

Ensure all required directories exist.

The material preconditions for operation must be established.

Return type:

None

classmethod get_database_url()

Get the database URL, resolving any path variables.

Return type:

str

class babylon.config.ChromaDBConfig

Bases: object

Configuration for ChromaDB vector database.

The Archive persists embeddings locally using DuckDB+Parquet. No external servers required - fully embedded, fully materialist.

BASE_DIR: Final[Path] = PosixPath('chromadb')

BATCH_SIZE: Final[int] = 100

DISTANCE_THRESHOLD: Final[float] = 0.4

ENTITIES_COLLECTION: Final[str] = 'entity_embeddings'

HISTORY_COLLECTION: Final[str] = 'game_history'

SEARCH_LIMIT: Final[int] = 10

THEORY_COLLECTION: Final[str] = 'marxist_theory'

classmethod get_persist_directory()

Get the persistence directory as a string.

Return type:

str

classmethod get_settings()

Get ChromaDB Settings object for client initialization.

Uses the new ChromaDB 1.x API. Note: persist_directory is no longer passed here - it’s passed directly to PersistentClient(path=…).

Return type:

Settings

class babylon.config.GameDefines(**data)

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)

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.

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 SOLIDARITY_SCALING: float

Multiplier for graph edge weights affecting Organization.

property SUPERWAGE_IMPACT: float

How much 1 unit of imperial extraction increases Core wealth.

classmethod default_yaml_path()

Return the default path to defines.yaml.

Return type:

Path

Returns:

Path to src/babylon/data/defines.yaml

classmethod load_default()

Load GameDefines from the default YAML location.

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

Return type:

GameDefines

Returns:

GameDefines instance

classmethod load_from_yaml(path)

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

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

class babylon.config.LLMConfig

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_BASE: Final[str] = 'https://api.deepseek.com'

API_KEY: Final[str] = ''

BATCH_SIZE: Final[int] = 8

CHAT_MODEL: Final[str] = 'deepseek-chat'

EMBEDDING_API_BASE: Final[str] = 'http://localhost:11434'

EMBEDDING_MODEL: Final[str] = 'embeddinggemma:latest'

EMBEDDING_PROVIDER: Final[str] = 'ollama'

MAX_RETRIES: Final[int] = 3

ORGANIZATION_ID: Final[str] = ''

RATE_LIMIT_RPM: Final[int] = 60

REQUEST_TIMEOUT: Final[float] = 30.0

RETRY_DELAY: Final[float] = 1.0

classmethod get_embedding_headers()

Get HTTP headers for Embedding API requests.

Ollama doesn’t need auth headers; OpenAI does.

Return type:

dict[str, str]

classmethod get_embedding_url()

Get the embedding API URL based on provider.

Return type:

str

classmethod get_headers()

Get HTTP headers for Chat API requests.

Return type:

dict[str, str]

classmethod get_model_dimensions()

Get the embedding dimensions for the configured model.

Return type:

int

Returns:

Number of dimensions for the embedding model

classmethod is_configured()

Check if Chat LLM API is properly configured.

Return type:

bool

classmethod is_ollama_embeddings()

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

Return type:

bool

classmethod validate()

Validate the Chat LLM configuration.

Raises:

ValueError – If required configuration is missing

Return type:

None

classmethod validate_embeddings()

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

babylon.config.OpenAIConfig

alias of LLMConfig

class babylon.config.TestingConfig

Bases: object

Configuration for test environments.

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

CHROMADB_PERSIST_DIR: Final[str] = '/tmp/babylon_test_chroma'

DATABASE_URL: Final[str] = 'sqlite:///:memory:'

DB_MAX_OVERFLOW: Final[int] = 0

DB_POOL_SIZE: Final[int] = 1

DEBUG: Final[bool] = True

LOG_DIR: Final[Path] = PosixPath('/tmp/babylon_test_logs')

LOG_LEVEL: Final[str] = 'DEBUG'

METRICS_ENABLED: Final[bool] = True

TESTING: Final[bool] = True

babylon.config.setup_logging(config_path=None, default_level=None, pyproject_path=None)

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.
chromadb_config	ChromaDB configuration for the Archive layer.
defines	Game defines for centralized coefficient configuration.
llm_config	LLM API configuration for text generation and embeddings.
logging_config	Logging configuration for Babylon/Babylon.
testing	Testing configuration for Babylon/Babylon.