mud_server.config ================= .. py:module:: mud_server.config .. autoapi-nested-parse:: Server configuration management. This module handles loading and accessing server configuration from multiple sources with a clear priority order: 1. Environment variables (highest priority) - for containerized deployments 2. Config file (config/server.ini) - for static deployments 3. Built-in defaults (lowest priority) - sensible fallbacks Configuration is loaded once at module import time and cached. The ServerConfig dataclass provides typed access to all settings. Usage: from mud_server.config import config # Access settings print(config.server.host) print(config.security.cors_origins) print(config.is_production) Environment Variable Mapping: MUD_HOST -> server.host MUD_PORT -> server.port MUD_PRODUCTION -> security.production MUD_CORS_ORIGINS -> security.cors_origins MUD_DB_PATH -> database.path MUD_LOG_LEVEL -> logging.level MUD_SESSION_TTL_MINUTES -> session.ttl_minutes MUD_SESSION_SLIDING_EXPIRATION -> session.sliding_expiration MUD_SESSION_ALLOW_MULTIPLE -> session.allow_multiple_sessions MUD_SESSION_ACTIVE_WINDOW_MINUTES -> session.active_window_minutes MUD_CHAR_DEFAULT_SLOTS -> characters.default_slots MUD_CHAR_MAX_SLOTS -> characters.max_slots MUD_ENTITY_STATE_ENABLED -> integrations.entity_state_enabled MUD_ENTITY_STATE_BASE_URL -> integrations.entity_state_base_url MUD_ENTITY_STATE_TIMEOUT_SECONDS -> integrations.entity_state_timeout_seconds MUD_ENTITY_STATE_INCLUDE_PROMPTS -> integrations.entity_state_include_prompts MUD_NAMEGEN_ENABLED -> integrations.namegen_enabled MUD_NAMEGEN_BASE_URL -> integrations.namegen_base_url MUD_NAMEGEN_TIMEOUT_SECONDS -> integrations.namegen_timeout_seconds MUD_REGISTRATION_MODE -> registration.account_registration_mode MUD_GUEST_REGISTRATION_ENABLED -> registration.guest_registration_enabled MUD_PLAYER_SELF_CREATE_ENABLED -> character_creation.player_self_create_enabled MUD_CHAR_CREATE_DEFAULT_MODE -> character_creation.default_creation_mode MUD_CHAR_CREATE_DEFAULT_NAMING -> character_creation.default_naming_mode MUD_CHAR_CREATE_DEFAULT_SLOT_LIMIT -> character_creation.default_world_slot_limit MUD_TRANSLATION_ENABLED -> ollama_translation.enabled MUD_TRANSLATION_OLLAMA_URL -> ollama_translation.base_url MUD_TRANSLATION_TIMEOUT -> ollama_translation.timeout_seconds Attributes ---------- .. autoapisummary:: mud_server.config.PROJECT_ROOT mud_server.config.CONFIG_DIR mud_server.config.CONFIG_FILE mud_server.config.CONFIG_EXAMPLE mud_server.config.config Classes ------- .. autoapisummary:: mud_server.config.ServerSettings mud_server.config.SecuritySettings mud_server.config.SessionSettings mud_server.config.DatabaseSettings mud_server.config.LoggingSettings mud_server.config.RateLimitSettings mud_server.config.CharacterSettings mud_server.config.RegistrationSettings mud_server.config.WorldCharacterPolicy mud_server.config.CharacterCreationSettings mud_server.config.FeatureSettings mud_server.config.WorldSettings mud_server.config.IntegrationSettings mud_server.config.OllamaTranslationSettings mud_server.config.ServerConfig mud_server.config.use_test_database Functions --------- .. autoapisummary:: mud_server.config.load_config mud_server.config.reload_config mud_server.config.get_config_status mud_server.config.print_config_summary Module Contents --------------- .. py:data:: PROJECT_ROOT .. py:data:: CONFIG_DIR .. py:data:: CONFIG_FILE .. py:data:: CONFIG_EXAMPLE .. py:class:: ServerSettings Network server configuration. .. py:attribute:: host :type: str :value: '0.0.0.0' .. py:attribute:: port :type: int :value: 8000 .. py:class:: SecuritySettings Security-related configuration. .. py:attribute:: production :type: bool :value: False .. py:attribute:: cors_origins :type: list[str] :value: ['http://localhost:7860'] .. py:attribute:: cors_allow_credentials :type: bool :value: True .. py:attribute:: cors_allow_methods :type: list[str] :value: ['*'] .. py:attribute:: cors_allow_headers :type: list[str] :value: ['*'] .. py:attribute:: docs_enabled :type: Literal['auto', 'enabled', 'disabled'] :value: 'auto' .. py:class:: SessionSettings Session management configuration. .. py:attribute:: ttl_minutes :type: int :value: 480 .. py:attribute:: sliding_expiration :type: bool :value: True .. py:attribute:: allow_multiple_sessions :type: bool :value: False .. py:attribute:: active_window_minutes :type: int :value: 30 .. py:class:: DatabaseSettings Database configuration. .. py:attribute:: path :type: str :value: 'data/mud.db' .. py:property:: absolute_path :type: pathlib.Path Get absolute path to database file. .. py:class:: LoggingSettings Logging configuration. .. py:attribute:: level :type: str :value: 'INFO' .. py:attribute:: format :type: Literal['simple', 'detailed', 'json'] :value: 'detailed' .. py:class:: RateLimitSettings Rate limiting configuration. .. py:attribute:: enabled :type: bool :value: False .. py:attribute:: login_per_minute :type: int :value: 5 .. py:attribute:: register_per_minute :type: int :value: 5 .. py:attribute:: api_per_second :type: int :value: 30 .. py:class:: CharacterSettings Character slot limits and defaults. .. py:attribute:: default_slots :type: int :value: 2 .. py:attribute:: max_slots :type: int :value: 10 .. py:class:: RegistrationSettings Account-registration policy controls. .. py:attribute:: account_registration_mode :type: Literal['open', 'closed'] :value: 'open' .. py:attribute:: guest_registration_enabled :type: bool :value: True .. py:class:: WorldCharacterPolicy Character-creation policy for a specific world. .. attribute:: creation_mode ``open`` allows account holders to self-create in the world. ``invite`` requires explicit world permission. .. attribute:: naming_mode ``generated`` means the server mints names. ``manual`` is currently reserved for admin/superuser workflows. .. attribute:: slot_limit_per_account Maximum characters an account may own in this world. .. py:attribute:: creation_mode :type: Literal['open', 'invite'] :value: 'invite' .. py:attribute:: naming_mode :type: Literal['generated', 'manual'] :value: 'generated' .. py:attribute:: slot_limit_per_account :type: int :value: 10 .. py:class:: CharacterCreationSettings Global character-creation policy and world-level overrides. The defaults define baseline behavior for all worlds. Per-world sections in INI (``[world_policy.]``) can override individual fields. .. py:attribute:: player_self_create_enabled :type: bool :value: True .. py:attribute:: default_creation_mode :type: Literal['open', 'invite'] :value: 'invite' .. py:attribute:: default_naming_mode :type: Literal['generated', 'manual'] :value: 'generated' .. py:attribute:: default_world_slot_limit :type: int :value: 10 .. py:attribute:: world_policy_overrides :type: dict[str, WorldCharacterPolicy] .. py:method:: resolve_world_policy(world_id) Resolve effective character policy for ``world_id``. Resolution order: 1. ``[world_policy.]`` override 2. Global defaults from ``[character_creation]`` .. py:class:: FeatureSettings Feature flags. .. py:attribute:: ollama_enabled :type: bool :value: True .. py:attribute:: verbose_errors :type: bool :value: False .. py:class:: WorldSettings Multi-world configuration settings. .. py:attribute:: worlds_root :type: str :value: 'data/worlds' .. py:attribute:: default_world_id :type: str :value: 'pipeworks_web' .. py:attribute:: allow_multi_world_characters :type: bool :value: False .. py:class:: IntegrationSettings Optional integration settings for provisioning and name generation. .. py:attribute:: entity_state_enabled :type: bool :value: True .. py:attribute:: entity_state_base_url :type: str :value: 'https://entity-state-api.luminal.local' .. py:attribute:: entity_state_timeout_seconds :type: float :value: 3.0 .. py:attribute:: entity_state_include_prompts :type: bool :value: False .. py:attribute:: namegen_enabled :type: bool :value: True .. py:attribute:: namegen_base_url :type: str :value: 'https://namegen-api.luminal.local' .. py:attribute:: namegen_timeout_seconds :type: float :value: 3.0 .. py:class:: OllamaTranslationSettings Server-level controls for the OOC→IC translation layer. Acts as the master switch and provides server-wide defaults. Per-world config in ``world.json`` is checked second; both must be enabled for translation to activate. .. py:attribute:: enabled :type: bool :value: True .. py:attribute:: base_url :type: str :value: 'http://localhost:11434' .. py:attribute:: timeout_seconds :type: float :value: 10.0 .. py:class:: ServerConfig Complete server configuration. This is the main configuration object that aggregates all settings sections. Access via the module-level `config` singleton. .. py:attribute:: server :type: ServerSettings .. py:attribute:: security :type: SecuritySettings .. py:attribute:: session :type: SessionSettings .. py:attribute:: database :type: DatabaseSettings .. py:attribute:: logging :type: LoggingSettings .. py:attribute:: rate_limit :type: RateLimitSettings .. py:attribute:: characters :type: CharacterSettings .. py:attribute:: registration :type: RegistrationSettings .. py:attribute:: character_creation :type: CharacterCreationSettings .. py:attribute:: features :type: FeatureSettings .. py:attribute:: worlds :type: WorldSettings .. py:attribute:: integrations :type: IntegrationSettings .. py:attribute:: ollama_translation :type: OllamaTranslationSettings .. py:property:: is_production :type: bool Convenience property for production mode check. .. py:property:: docs_should_be_enabled :type: bool Determine if API docs should be enabled based on settings. .. py:method:: resolve_world_character_policy(world_id) Resolve world-level character-creation policy for ``world_id``. .. py:function:: load_config() Load configuration from all sources with proper priority. Priority (highest wins): 1. Environment variables 2. config/server.ini 3. config/server.example.ini (fallback for development) 4. Built-in defaults :returns: Fully populated configuration object. :rtype: ServerConfig .. py:function:: reload_config() Reload configuration from disk and environment. This updates the module-level `config` singleton. Use sparingly as it doesn't update already-running server middleware. :returns: The newly loaded configuration. :rtype: ServerConfig .. py:data:: config .. py:function:: get_config_status() Get configuration status for diagnostics. Returns a dictionary with configuration source information, useful for debugging and admin dashboards. .. py:function:: print_config_summary(*, resolved_host = None, resolved_port = None) Print a summary of current configuration to stdout. .. py:class:: use_test_database(db_path) Context manager for using a temporary test database. This is the recommended way to set up test databases. It properly configures the config system to use a temporary database path. Usage: from mud_server.config import use_test_database def test_something(tmp_path): db_path = tmp_path / "test.db" with use_test_database(db_path): # Database operations will use db_path database.init_database() :param db_path: Path to the test database file .. py:attribute:: db_path .. py:attribute:: original_path :type: str | None :value: None