Trixy3/trixy_core/__init__.py

"""
Trixy Core - Professional Voice Assistant System

This module provides the core components and systems for the Trixy voice assistant,
including event handling, configuration management, networking, plugins, and more.

The core system is designed with:
- Event-driven architecture using the central EventHandler
- Professional dependency injection via ApplicationContainer
- Thread-safe, scalable components supporting multiple satellites
- Robust configuration management with validation
- Plugin system with hot-loading capabilities
- Professional logging and error handling

Main Components:
- ApplicationContainer: Central dependency injection container
- EventHandler: Event-driven communication system
- ConfigManager: Configuration management with validation
- Plugin System: Dynamic plugin loading and management
- Satellite Manager: Multi-satellite connection management
- Network Manager: Custom Trixy protocol implementation

Usage:
    from trixy_core import ApplicationContainer, DeploymentMode
    
    # Create application container
    application = ApplicationContainer(
        mode=DeploymentMode.SERVER,
        config_path="config/server_config.json"
    )
    
    # Start the application
    application.start()
    
    # Access components
    event_handler = application.get_event_handler()
    plugin_system = application.get_plugin_system()
    satellite_manager = application.get_satellite_manager()
    
    # Graceful shutdown
    application.shutdown()
"""

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

# Import core application container
try:
    from .application import (
        ApplicationContainer,
        ApplicationContainerError,
        ComponentInitializationError,
        ComponentLifecycleError,
        ApplicationStatus,
        ComponentStatus,
        ComponentHealth,
        create_application_container,
        get_application_container,
        cleanup_application_containers,
    )
    _APPLICATION_AVAILABLE = True
except ImportError as e:
    print(f"Warning: Application container not available: {e}")
    _APPLICATION_AVAILABLE = False

# Import event system
try:
    from .events import (
        EventHandler,
        TrixyEvent,
        EventType,
        TrixyEventData,
        EventDataFactory,
        EventStatus,
        EventHistoryEntry,
        SatelliteInfo,
        SpeakerInfo,
        # Event data classes
        SatelliteConnectedEventData,
        SatelliteDisconnectedEventData,
        SatelliteRegisteredEventData,
        WakewordReceivedEventData,
        RawAudioInputReceivedEventData,
        TextReceivedEventData,
        IntentReceivedEventData,
        TTSReceivedEventData,
        SystemStartupEventData,
        SystemShutdownEventData,
        PluginEventData,
        PluginLoadedEventData,
        PluginUnloadedEventData,
        TrainingStartedEventData,
        TrainingCompletedEventData,
        ScheduleTriggeredEventData,
        # Registry and utilities
        TrixyEventRegistry,
        register_event_handlers,
        unregister_event_handlers,
        get_event_registry,
        validate_event_handler,
        list_registered_events,
        get_handler_info,
        create_default_event_handler,
        setup_event_system,
    )
    _EVENTS_AVAILABLE = True
except ImportError as e:
    print(f"Warning: Event system not available: {e}")
    _EVENTS_AVAILABLE = False

# Import configuration system
try:
    from .config import (
        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,
        create_config_manager,
        load_config_from_file,
        validate_config_file,
        create_default_config_file,
        # Constants
        CONFIG_CLASSES,
        ENV_PREFIX,
        DEFAULT_PATHS,
        DEFAULT_PORTS,
    )
    _CONFIG_AVAILABLE = True
except ImportError as e:
    print(f"Warning: Configuration system not available: {e}")
    _CONFIG_AVAILABLE = False


def pprint(message: str) -> None:
    """
    Core module logging function that adapts based on application mode.
    
    This is the standard pprint() function referenced throughout CLAUDE.md:
    - Debug mode: Uses print() statements  
    - Production mode: Uses logging system with Textual TUI
    
    Args:
        message: Message to print/log
    """
    # This will be enhanced when the main logging system is integrated
    print(f"[TRIXY_CORE] {message}")


# Public API - Core Classes
__all__ = []

# Application Container
if _APPLICATION_AVAILABLE:
    __all__.extend([
        "ApplicationContainer",
        "ApplicationContainerError", 
        "ComponentInitializationError",
        "ComponentLifecycleError",
        "ApplicationStatus",
        "ComponentStatus",
        "ComponentHealth",
        "create_application_container",
        "get_application_container",
        "cleanup_application_containers",
    ])

# Event System  
if _EVENTS_AVAILABLE:
    __all__.extend([
        "EventHandler",
        "TrixyEvent",
        "EventType",
        "TrixyEventData",
        "EventDataFactory",
        "EventStatus", 
        "EventHistoryEntry",
        "SatelliteInfo",
        "SpeakerInfo",
        # Event data classes
        "SatelliteConnectedEventData",
        "SatelliteDisconnectedEventData",
        "SatelliteRegisteredEventData",
        "WakewordReceivedEventData",
        "RawAudioInputReceivedEventData",
        "TextReceivedEventData",
        "IntentReceivedEventData",
        "TTSReceivedEventData",
        "SystemStartupEventData",
        "SystemShutdownEventData",
        "PluginEventData",
        "PluginLoadedEventData",
        "PluginUnloadedEventData", 
        "TrainingStartedEventData",
        "TrainingCompletedEventData",
        "ScheduleTriggeredEventData",
        # Registry and utilities
        "TrixyEventRegistry",
        "register_event_handlers",
        "unregister_event_handlers", 
        "get_event_registry",
        "validate_event_handler",
        "list_registered_events",
        "get_handler_info",
        "create_default_event_handler",
        "setup_event_system",
    ])

# Configuration System
if _CONFIG_AVAILABLE:
    __all__.extend([
        "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",
        "create_config_manager",
        "load_config_from_file",
        "validate_config_file", 
        "create_default_config_file",
        # Constants
        "CONFIG_CLASSES",
        "ENV_PREFIX",
        "DEFAULT_PATHS",
        "DEFAULT_PORTS",
    ])

# Always available
__all__.extend([
    "pprint",
])


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


def get_available_components() -> dict:
    """
    Get information about which core components are available.
    
    Returns:
        Dictionary showing availability status of each component
    """
    return {
        "application_container": _APPLICATION_AVAILABLE,
        "event_system": _EVENTS_AVAILABLE, 
        "configuration_system": _CONFIG_AVAILABLE,
        "version": __version__,
    }


def create_application(
    mode: str = "server",
    config_path: str = None,
    debug_mode: bool = False,
    **kwargs
) -> 'ApplicationContainer':
    """
    Convenience function to create and start a Trixy application.
    
    This is the main entry point for creating a Trixy application instance
    as referenced in CLAUDE.md.
    
    Args:
        mode: Deployment mode ("server", "client", "standalone")
        config_path: Path to configuration file
        debug_mode: Enable debug mode
        **kwargs: Additional configuration options
        
    Returns:
        ApplicationContainer instance
        
    Raises:
        ImportError: If application container is not available
        ApplicationContainerError: If application creation fails
        
    Example:
        application = create_application(
            mode="server",
            config_path="config/server_config.json",
            debug_mode=False
        )
        application.start()
        
        # Access components as specified in CLAUDE.md
        event_handler = application.get_event_handler()
        plugin_system = application.get_plugin_system()
        satellite_manager = application.get_satellite_manager()
        config_manager = application.get_config_manager()
    """
    if not _APPLICATION_AVAILABLE:
        raise ImportError("ApplicationContainer is not available. Check if all dependencies are installed.")
    
    pprint(f"Creating Trixy application in {mode} mode")
    
    application = create_application_container(
        mode=mode,
        config_path=config_path, 
        debug_mode=debug_mode,
        **kwargs
    )
    
    pprint(f"Trixy application created successfully")
    return application


def setup_trixy_core(debug_mode: bool = False) -> dict:
    """
    Set up the trixy_core module with default configurations.
    
    Args:
        debug_mode: Enable debug mode for all components
        
    Returns:
        Dictionary with setup information and component status
        
    Example:
        setup_info = setup_trixy_core(debug_mode=True)
        pprint(f"Setup completed: {setup_info}")
    """
    setup_info = {
        "trixy_core_version": __version__,
        "debug_mode": debug_mode,
        "available_components": get_available_components(),
        "setup_timestamp": time.time(),
    }
    
    pprint(f"Trixy Core v{__version__} setup completed")
    pprint(f"Available components: {list(setup_info['available_components'].keys())}")
    
    if debug_mode:
        pprint("Debug mode enabled for all core components")
    
    return setup_info


# Initialize the module
def _init_trixy_core():
    """Initialize the trixy_core module."""
    pprint(f"Trixy Core v{__version__} loaded")
    
    components = get_available_components()
    available = [name for name, status in components.items() if status and name != "version"]
    
    if available:
        pprint(f"Available components: {', '.join(available)}")
    else:
        pprint("Warning: No core components are available")
        pprint("This may be expected during initial setup")


# Import time for setup function
import time

# Initialize on import
_init_trixy_core()


# Compatibility functions for easy integration

def quick_start_server(config_path: str = None, debug_mode: bool = False) -> 'ApplicationContainer':
    """Quickly start a Trixy server instance."""
    application = create_application("server", config_path, debug_mode)
    application.start()
    return application


def quick_start_client(config_path: str = None, debug_mode: bool = False) -> 'ApplicationContainer':
    """Quickly start a Trixy client/satellite instance.""" 
    application = create_application("client", config_path, debug_mode)
    application.start()
    return application


def quick_start_standalone(config_path: str = None, debug_mode: bool = False) -> 'ApplicationContainer':
    """Quickly start a Trixy standalone instance."""
    application = create_application("standalone", config_path, debug_mode) 
    application.start()
    return application


# Add convenience functions to exports
__all__.extend([
    "get_version",
    "get_available_components",
    "create_application",
    "setup_trixy_core", 
    "quick_start_server",
    "quick_start_client",
    "quick_start_standalone",
])


# Module documentation
def get_module_info() -> dict:
    """
    Get comprehensive information about the trixy_core module.
    
    Returns:
        Dictionary with module information, component status, and usage examples
    """
    return {
        "module": "trixy_core",
        "version": __version__,
        "description": __description__,
        "author": __author__,
        "components": get_available_components(),
        "exported_symbols": len(__all__),
        "usage_example": """
from trixy_core import create_application

# Create and start Trixy application
application = create_application(
    mode="server",
    config_path="config/server_config.json"
)
application.start()

# Access core components as specified in CLAUDE.md
event_handler = application.get_event_handler()
plugin_system = application.get_plugin_system() 
satellite_manager = application.get_satellite_manager()
config_manager = application.get_config_manager()

# Graceful shutdown
application.shutdown()
        """.strip()
    }


__all__.append("get_module_info")