Trixy3/trixy_core/config/__init__.py

"""
Trixy Configuration Management System

This module provides comprehensive configuration management for the Trixy application
across all deployment modes (server, client, standalone). It includes:

- Type-safe configuration data structures
- Environment variable and command line override support
- Configuration validation with detailed error reporting
- Hot-reloading of configuration files during runtime
- Thread-safe configuration access for multi-satellite support
- Configuration backup and restore functionality
- Default configuration generation

Public API:
    ConfigManager: Main configuration management class
    ServerConfig, ClientConfig, StandaloneConfig: Configuration data models
    ConfigValidator: Configuration validation utilities
    ValidationResult: Validation result container

Example usage:
    from trixy_core.config import ConfigManager, DeploymentMode
    
    # Initialize configuration manager
    config_manager = ConfigManager(
        mode=DeploymentMode.SERVER,
        config_file="config/server_config.json",
        debug_mode=False
    )
    
    # Load configuration with validation
    config = config_manager.load_config()
    
    # Access configuration values
    command_port = config.network.command_port
    
    # Enable hot-reloading
    config_manager.enable_hot_reload()
    
    # Override configuration values
    config_manager.override_config({"network": {"command_port": 2105}})
"""

from pprint import pprint as _pprint

# Configuration data models
from .config_models import (
    # Main configuration classes
    ServerConfig,
    ClientConfig, 
    StandaloneConfig,
    ConfigType,
    
    # Component configuration classes
    NetworkConfig,
    AudioConfig,
    MLConfig,
    PluginConfig,
    SatelliteConfig,
    SecurityConfig,
    LoggingConfig,
    
    # Enums and types
    DeploymentMode,
    LogLevel,
    ConfigDict,
    
    # Utility functions
    get_config_class,
    create_default_config,
    merge_configs,
    CONFIG_CLASSES,
)

# Default configuration factories
from .config_defaults import (
    # Factory functions
    create_default_server_config,
    create_default_client_config,
    create_default_standalone_config,
    create_default_config_for_mode,
    
    # Environment handling
    get_env_override,
    get_environment_overrides,
    apply_environment_overrides,
    get_env_var_documentation,
    
    # System utilities
    get_system_defaults,
    get_config_template,
    validate_environment,
    
    # Constants
    ENV_PREFIX,
    DEFAULT_PATHS,
    DEFAULT_PORTS,
)

# Configuration validation
from .config_validator import (
    ConfigValidator,
    ValidationResult,
    validate_config_dict,
    quick_validate,
)

# Main configuration manager (import after other modules to avoid circular imports)
from .config_manager import (
    ConfigManager,
    ConfigurationError,
    ConfigurationValidationError,
    ConfigurationLoadError,
    ConfigurationSaveError,
)


def pprint(message: str) -> None:
    """
    Print function that adapts based on application mode.
    
    In production mode: Uses logging system
    In debug mode: Uses print() statements
    
    This is the standard logging function referenced in CLAUDE.md.
    """
    # For now, use standard pprint - will be enhanced when logging system is implemented
    _pprint(f"[CONFIG] {message}")


# Public API exports
__all__ = [
    # Main classes
    "ConfigManager",
    "ConfigValidator", 
    "ValidationResult",
    
    # Configuration models
    "ServerConfig",
    "ClientConfig", 
    "StandaloneConfig",
    "ConfigType",
    "NetworkConfig",
    "AudioConfig",
    "MLConfig",
    "PluginConfig",
    "SatelliteConfig", 
    "SecurityConfig",
    "LoggingConfig",
    
    # Enums and types
    "DeploymentMode",
    "LogLevel",
    "ConfigDict",
    
    # Exceptions
    "ConfigurationError",
    "ConfigurationValidationError", 
    "ConfigurationLoadError",
    "ConfigurationSaveError",
    
    # Utility functions
    "get_config_class",
    "create_default_config",
    "merge_configs",
    "create_default_config_for_mode",
    "get_env_override",
    "get_environment_overrides",
    "apply_environment_overrides",
    "get_system_defaults",
    "get_config_template",
    "validate_environment",
    "validate_config_dict",
    "quick_validate",
    "get_env_var_documentation",
    "pprint",
    
    # Constants
    "CONFIG_CLASSES",
    "ENV_PREFIX", 
    "DEFAULT_PATHS",
    "DEFAULT_PORTS",
]


# Version information
__version__ = "1.0.0"
__author__ = "Trixy Development Team"
__description__ = "Professional configuration management system for Trixy voice assistant"


def get_version() -> str:
    """Get the configuration module version."""
    return __version__


def create_config_manager(
    mode: DeploymentMode,
    config_file: str = None,
    debug_mode: bool = False,
    **kwargs
) -> ConfigManager:
    """
    Convenience function to create a ConfigManager instance.
    
    Args:
        mode: Deployment mode (server, client, standalone)
        config_file: Path to configuration file (optional)
        debug_mode: Enable debug mode
        **kwargs: Additional arguments passed to ConfigManager
    
    Returns:
        Configured ConfigManager instance
        
    Example:
        config_manager = create_config_manager(
            mode=DeploymentMode.SERVER,
            config_file="config/server_config.json",
            debug_mode=True
        )
    """
    return ConfigManager(
        mode=mode,
        config_file=config_file,
        debug_mode=debug_mode,
        **kwargs
    )


def load_config_from_file(
    config_file: str,
    validate: bool = True,
    strict_validation: bool = False
) -> ConfigType:
    """
    Convenience function to load configuration from a file.
    
    Args:
        config_file: Path to configuration file
        validate: Whether to validate the configuration
        strict_validation: Whether to treat warnings as errors
    
    Returns:
        Loaded and validated configuration object
        
    Raises:
        ConfigurationError: If loading or validation fails
        
    Example:
        config = load_config_from_file("config/server_config.json")
    """
    config_manager = ConfigManager.from_file(config_file)
    return config_manager.load_config(validate=validate, strict_validation=strict_validation)


def validate_config_file(config_file: str, strict: bool = False) -> ValidationResult:
    """
    Convenience function to validate a configuration file.
    
    Args:
        config_file: Path to configuration file
        strict: Whether to treat warnings as errors
    
    Returns:
        ValidationResult with detailed feedback
        
    Example:
        result = validate_config_file("config/server_config.json")
        if not result.is_valid:
            print("Configuration errors:")
            for error in result.errors:
                print(f"  - {error}")
    """
    validator = ConfigValidator(strict_mode=strict)
    return quick_validate(config_file)


def create_default_config_file(
    mode: DeploymentMode,
    output_file: str,
    debug_mode: bool = False,
    overrides: dict = None
) -> None:
    """
    Create a default configuration file for the specified mode.
    
    Args:
        mode: Deployment mode
        output_file: Path where to save the configuration file
        debug_mode: Whether to enable debug mode in the default config
        overrides: Optional configuration overrides to apply
    
    Example:
        create_default_config_file(
            mode=DeploymentMode.SERVER,
            output_file="config/server_config.json",
            debug_mode=False
        )
    """
    config_manager = ConfigManager(mode=mode, debug_mode=debug_mode)
    default_config = config_manager.get_default_config()
    
    if overrides:
        default_config = merge_configs(default_config, overrides)
    
    config_manager.save_config_to_file(default_config, output_file)
    pprint(f"Created default {mode.value} configuration: {output_file}")