empathy-framework 3.2.3__py3-none-any.whl → 3.8.2__py3-none-any.whl

hot_reload/integration.py

@@ -0,0 +1,228 @@
+"""Integration example for hot-reload with wizard API.
+
+Shows how to integrate hot-reload into the existing wizard_api.py.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from .config import get_hot_reload_config
+from .reloader import WizardReloader
+from .watcher import WizardFileWatcher
+from .websocket import create_notification_callback, get_notification_manager
+
+logger = logging.getLogger(__name__)
+
+
+class HotReloadIntegration:
+    """Integrates hot-reload with wizard API.
+
+    Example usage in wizard_api.py:
+
+        from hot_reload.integration import HotReloadIntegration
+
+        # Create FastAPI app
+        app = FastAPI()
+
+        # Initialize hot-reload (if enabled)
+        hot_reload = HotReloadIntegration(app, register_wizard)
+
+        @app.on_event("startup")
+        async def startup_event():
+            init_wizards()  # Initialize wizards
+            hot_reload.start()  # Start hot-reload watcher
+
+        @app.on_event("shutdown")
+        async def shutdown_event():
+            hot_reload.stop()
+
+    """
+
+    def __init__(
+        self,
+        app: FastAPI,
+        register_callback: callable,
+    ):
+        """Initialize hot-reload integration.
+
+        Args:
+            app: FastAPI application instance
+            register_callback: Function to register wizard (wizard_id, wizard_class) -> bool
+
+        """
+        self.app = app
+        self.register_callback = register_callback
+        self.config = get_hot_reload_config()
+
+        # Initialize components
+        self.notification_callback = create_notification_callback()
+        self.reloader = WizardReloader(
+            register_callback=self._register_wizard_wrapper,
+            notification_callback=self.notification_callback,
+        )
+
+        self.watcher: WizardFileWatcher | None = None
+
+        # Add WebSocket endpoint to app
+        if self.config.enabled:
+            self._setup_websocket_endpoint()
+
+    def _register_wizard_wrapper(self, wizard_id: str, wizard_class: type) -> bool:
+        """Wrapper for register callback that handles errors.
+
+        Args:
+            wizard_id: Wizard identifier
+            wizard_class: Wizard class to register
+
+        Returns:
+            True if registration succeeded
+
+        """
+        try:
+            return self.register_callback(wizard_id, wizard_class)
+        except Exception as e:
+            logger.error(f"Error registering wizard {wizard_id}: {e}")
+            return False
+
+    def _setup_websocket_endpoint(self) -> None:
+        """Add WebSocket endpoint to FastAPI app."""
+
+        @self.app.websocket(self.config.websocket_path)
+        async def hot_reload_websocket(websocket: WebSocket):
+            """WebSocket endpoint for hot-reload notifications."""
+            manager = get_notification_manager()
+
+            await manager.connect(websocket)
+
+            try:
+                # Keep connection alive
+                while True:
+                    # Receive ping messages
+                    await websocket.receive_text()
+
+            except WebSocketDisconnect:
+                await manager.disconnect(websocket)
+            except Exception as e:
+                logger.error(f"WebSocket error: {e}")
+                await manager.disconnect(websocket)
+
+        logger.info(f"WebSocket endpoint added: {self.config.websocket_path}")
+
+    def start(self) -> None:
+        """Start hot-reload watcher."""
+        if not self.config.enabled:
+            logger.info("Hot-reload disabled (set HOT_RELOAD_ENABLED=true to enable)")
+            return
+
+        if not self.config.watch_dirs:
+            logger.warning("No wizard directories found to watch")
+            return
+
+        if self.watcher and self.watcher.is_running():
+            logger.warning("Hot-reload already started")
+            return
+
+        # Create watcher
+        self.watcher = WizardFileWatcher(
+            wizard_dirs=self.config.watch_dirs,
+            reload_callback=self._on_file_change,
+        )
+
+        # Start watching
+        self.watcher.start()
+
+        logger.info(f"🔥 Hot-reload started - watching {len(self.config.watch_dirs)} directories")
+
+    def stop(self) -> None:
+        """Stop hot-reload watcher."""
+        if self.watcher:
+            self.watcher.stop()
+            self.watcher = None
+            logger.info("Hot-reload stopped")
+
+    def _on_file_change(self, wizard_id: str, file_path: str) -> None:
+        """Handle file change event.
+
+        Args:
+            wizard_id: ID of wizard that changed
+            file_path: Path to changed file
+
+        """
+        logger.info(f"File change detected: {wizard_id} ({file_path})")
+
+        # Reload wizard
+        result = self.reloader.reload_wizard(wizard_id, file_path)
+
+        if result.success:
+            logger.info(f"✓ {result.message}")
+        else:
+            logger.error(f"✗ Reload failed: {result.error}")
+
+    def get_status(self) -> dict:
+        """Get hot-reload status.
+
+        Returns:
+            Status dictionary
+
+        """
+        return {
+            "enabled": self.config.enabled,
+            "running": self.watcher.is_running() if self.watcher else False,
+            "watch_dirs": [str(d) for d in self.config.watch_dirs],
+            "reload_count": self.reloader.get_reload_count(),
+            "websocket_connections": get_notification_manager().get_connection_count(),
+            "websocket_path": self.config.websocket_path,
+        }
+
+
+# Example usage in wizard_api.py:
+"""
+from fastapi import FastAPI
+from hot_reload.integration import HotReloadIntegration
+
+app = FastAPI(title="Empathy Wizard API")
+
+# Global hot-reload instance
+hot_reload = None
+
+
+def register_wizard(wizard_id: str, wizard_class: type, *args, **kwargs) -> bool:
+    '''Register wizard with WIZARDS dict'''
+    try:
+        WIZARDS[wizard_id] = wizard_class(*args, **kwargs)
+        logger.info(f"✓ Registered wizard: {wizard_id}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to register {wizard_id}: {e}")
+        return False
+
+
+@app.on_event("startup")
+async def startup_event():
+    global hot_reload
+
+    # Initialize wizards
+    init_wizards()
+
+    # Start hot-reload
+    hot_reload = HotReloadIntegration(app, register_wizard)
+    hot_reload.start()
+
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    if hot_reload:
+        hot_reload.stop()
+
+
+@app.get("/api/hot-reload/status")
+async def get_hot_reload_status():
+    '''Get hot-reload status'''
+    if not hot_reload:
+        return {"enabled": False}
+    return hot_reload.get_status()
+"""

hot_reload/reloader.py

@@ -0,0 +1,298 @@
+"""Dynamic wizard reloader for hot-reload.
+
+Handles reloading wizard modules without server restart.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import importlib
+import logging
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class ReloadResult:
+    """Result of a wizard reload operation."""
+
+    def __init__(
+        self,
+        success: bool,
+        wizard_id: str,
+        message: str,
+        error: str | None = None,
+    ):
+        """Initialize reload result.
+
+        Args:
+            success: Whether reload succeeded
+            wizard_id: ID of wizard that was reloaded
+            message: Status message
+            error: Error message if failed
+
+        """
+        self.success = success
+        self.wizard_id = wizard_id
+        self.message = message
+        self.error = error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "success": self.success,
+            "wizard_id": self.wizard_id,
+            "message": self.message,
+            "error": self.error,
+        }
+
+
+class WizardReloader:
+    """Handles dynamic reloading of wizard modules.
+
+    Supports hot-reload of wizards without server restart by:
+    1. Unloading old module from sys.modules
+    2. Reloading module with importlib
+    3. Re-registering wizard with wizard API
+    4. Notifying clients via callback
+    """
+
+    def __init__(
+        self,
+        register_callback: Callable[[str, type], bool],
+        notification_callback: Callable[[dict], None] | None = None,
+    ):
+        """Initialize reloader.
+
+        Args:
+            register_callback: Function to register wizard (wizard_id, wizard_class) -> success
+            notification_callback: Optional function to notify clients of reload events
+
+        """
+        self.register_callback = register_callback
+        self.notification_callback = notification_callback
+        self._reload_count = 0
+
+    def reload_wizard(self, wizard_id: str, file_path: str) -> ReloadResult:
+        """Reload a wizard module.
+
+        Args:
+            wizard_id: Wizard identifier
+            file_path: Path to wizard file
+
+        Returns:
+            ReloadResult with outcome
+
+        """
+        logger.info(f"Attempting to reload wizard: {wizard_id} from {file_path}")
+
+        try:
+            # Get module name from file path
+            module_name = self._get_module_name(file_path)
+            if not module_name:
+                error_msg = f"Could not determine module name from {file_path}"
+                logger.error(error_msg)
+                return ReloadResult(
+                    success=False,
+                    wizard_id=wizard_id,
+                    message="Failed to reload",
+                    error=error_msg,
+                )
+
+            # Unload old module
+            self._unload_module(module_name)
+
+            # Reload module
+            try:
+                module = importlib.import_module(module_name)
+            except ImportError as e:
+                error_msg = f"Failed to import module {module_name}: {e}"
+                logger.error(error_msg)
+                self._notify_reload_failed(wizard_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    wizard_id=wizard_id,
+                    message="Import failed",
+                    error=error_msg,
+                )
+
+            # Find wizard class in module
+            wizard_class = self._find_wizard_class(module)
+            if not wizard_class:
+                error_msg = f"No wizard class found in {module_name}"
+                logger.error(error_msg)
+                self._notify_reload_failed(wizard_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    wizard_id=wizard_id,
+                    message="No wizard class found",
+                    error=error_msg,
+                )
+
+            # Re-register wizard
+            success = self.register_callback(wizard_id, wizard_class)
+
+            if success:
+                self._reload_count += 1
+                logger.info(
+                    f"✓ Successfully reloaded {wizard_id} ({self._reload_count} total reloads)"
+                )
+                self._notify_reload_success(wizard_id)
+
+                return ReloadResult(
+                    success=True,
+                    wizard_id=wizard_id,
+                    message=f"Reloaded successfully (reload #{self._reload_count})",
+                )
+            else:
+                error_msg = "Registration failed"
+                logger.error(f"Failed to re-register {wizard_id}")
+                self._notify_reload_failed(wizard_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    wizard_id=wizard_id,
+                    message="Registration failed",
+                    error=error_msg,
+                )
+
+        except Exception as e:
+            error_msg = f"Unexpected error reloading {wizard_id}: {e}"
+            logger.exception(error_msg)
+            self._notify_reload_failed(wizard_id, str(e))
+            return ReloadResult(
+                success=False,
+                wizard_id=wizard_id,
+                message="Unexpected error",
+                error=str(e),
+            )
+
+    def _get_module_name(self, file_path: str) -> str | None:
+        """Get Python module name from file path.
+
+        Args:
+            file_path: Path to Python file
+
+        Returns:
+            Module name or None if cannot determine
+
+        """
+        try:
+            path = Path(file_path).resolve()
+
+            # Remove .py extension
+            if not path.suffix == ".py":
+                return None
+
+            # Get parts relative to project root
+            # Try to find common patterns: wizards/, coach_wizards/, empathy_software_plugin/wizards/
+            parts = path.parts
+
+            # Find wizard directory in path
+            wizard_dir_indices = [i for i, part in enumerate(parts) if "wizard" in part.lower()]
+
+            if not wizard_dir_indices:
+                return None
+
+            # Take from first wizard directory
+            start_idx = wizard_dir_indices[0]
+
+            # Build module name
+            module_parts = list(parts[start_idx:])
+            module_parts[-1] = module_parts[-1].replace(".py", "")
+
+            module_name = ".".join(module_parts)
+            return module_name
+
+        except Exception as e:
+            logger.error(f"Error getting module name from {file_path}: {e}")
+            return None
+
+    def _unload_module(self, module_name: str) -> None:
+        """Unload module from sys.modules.
+
+        Args:
+            module_name: Name of module to unload
+
+        """
+        # Unload exact module
+        if module_name in sys.modules:
+            del sys.modules[module_name]
+            logger.debug(f"Unloaded module: {module_name}")
+
+        # Also unload any submodules
+        submodules = [name for name in sys.modules.keys() if name.startswith(f"{module_name}.")]
+        for submodule in submodules:
+            del sys.modules[submodule]
+            logger.debug(f"Unloaded submodule: {submodule}")
+
+    def _find_wizard_class(self, module: Any) -> type | None:
+        """Find wizard class in module.
+
+        Args:
+            module: Python module
+
+        Returns:
+            Wizard class or None if not found
+
+        """
+        # Look for classes ending with "Wizard"
+        for name in dir(module):
+            if name.endswith("Wizard") and not name.startswith("_"):
+                attr = getattr(module, name)
+                if isinstance(attr, type):
+                    return attr
+
+        return None
+
+    def _notify_reload_success(self, wizard_id: str) -> None:
+        """Notify clients of successful reload.
+
+        Args:
+            wizard_id: ID of reloaded wizard
+
+        """
+        if self.notification_callback:
+            try:
+                self.notification_callback(
+                    {
+                        "event": "wizard_reloaded",
+                        "wizard_id": wizard_id,
+                        "success": True,
+                        "reload_count": self._reload_count,
+                    }
+                )
+            except Exception as e:
+                logger.error(f"Error sending reload notification: {e}")
+
+    def _notify_reload_failed(self, wizard_id: str, error: str) -> None:
+        """Notify clients of failed reload.
+
+        Args:
+            wizard_id: ID of wizard that failed to reload
+            error: Error message
+
+        """
+        if self.notification_callback:
+            try:
+                self.notification_callback(
+                    {
+                        "event": "wizard_reload_failed",
+                        "wizard_id": wizard_id,
+                        "success": False,
+                        "error": error,
+                    }
+                )
+            except Exception as e:
+                logger.error(f"Error sending failure notification: {e}")
+
+    def get_reload_count(self) -> int:
+        """Get total number of successful reloads.
+
+        Returns:
+            Reload count
+
+        """
+        return self._reload_count

hot_reload/watcher.py

@@ -0,0 +1,179 @@
+"""File system watcher for wizard hot-reload.
+
+Monitors wizard directories for changes and triggers reloads.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+logger = logging.getLogger(__name__)
+
+
+class WizardFileHandler(FileSystemEventHandler):
+    """Handles file system events for wizard files."""
+
+    def __init__(self, reload_callback: Callable[[str], None]):
+        """Initialize handler.
+
+        Args:
+            reload_callback: Function to call when wizard file changes
+
+        """
+        super().__init__()
+        self.reload_callback = reload_callback
+        self._processing = set()  # Prevent duplicate events
+
+    def on_modified(self, event: FileSystemEvent) -> None:
+        """Handle file modification events.
+
+        Args:
+            event: File system event
+
+        """
+        if event.is_directory:
+            return
+
+        file_path = event.src_path
+
+        # Only process Python files
+        if not file_path.endswith(".py"):
+            return
+
+        # Skip __pycache__ and test files
+        if "__pycache__" in file_path or "test_" in file_path:
+            return
+
+        # Prevent duplicate processing
+        if file_path in self._processing:
+            return
+
+        try:
+            self._processing.add(file_path)
+
+            wizard_id = self._extract_wizard_id(file_path)
+            if wizard_id:
+                logger.info(f"Detected change in {wizard_id} ({file_path})")
+                self.reload_callback(wizard_id, file_path)
+
+        except Exception as e:
+            logger.error(f"Error processing file change {file_path}: {e}")
+        finally:
+            self._processing.discard(file_path)
+
+    def _extract_wizard_id(self, file_path: str) -> str | None:
+        """Extract wizard ID from file path.
+
+        Args:
+            file_path: Path to wizard file
+
+        Returns:
+            Wizard ID or None if cannot extract
+
+        """
+        path = Path(file_path)
+
+        # Get filename without extension
+        filename = path.stem
+
+        # Remove common suffixes
+        wizard_id = filename.replace("_wizard", "").replace("wizard_", "")
+
+        # Convert to wizard ID format (snake_case)
+        wizard_id = wizard_id.lower()
+
+        return wizard_id if wizard_id else None
+
+
+class WizardFileWatcher:
+    """Watches wizard directories for file changes.
+
+    Monitors specified directories and triggers reload callbacks
+    when wizard files are modified.
+    """
+
+    def __init__(self, wizard_dirs: list[Path], reload_callback: Callable[[str, str], None]):
+        """Initialize watcher.
+
+        Args:
+            wizard_dirs: List of directories to watch
+            reload_callback: Function to call on file changes (wizard_id, file_path)
+
+        """
+        self.wizard_dirs = [Path(d) for d in wizard_dirs]
+        self.reload_callback = reload_callback
+        self.observer = Observer()
+        self.event_handler = WizardFileHandler(reload_callback)
+        self._running = False
+
+    def start(self) -> None:
+        """Start watching wizard directories."""
+        if self._running:
+            logger.warning("Watcher already running")
+            return
+
+        valid_dirs = []
+        for directory in self.wizard_dirs:
+            if not directory.exists():
+                logger.warning(f"Directory does not exist: {directory}")
+                continue
+
+            if not directory.is_dir():
+                logger.warning(f"Not a directory: {directory}")
+                continue
+
+            # Schedule watching
+            self.observer.schedule(
+                self.event_handler,
+                str(directory),
+                recursive=True,
+            )
+            valid_dirs.append(directory)
+            logger.info(f"Watching directory: {directory}")
+
+        if not valid_dirs:
+            logger.error("No valid directories to watch")
+            return
+
+        self.observer.start()
+        self._running = True
+
+        logger.info(
+            f"Hot-reload enabled for {len(valid_dirs)} "
+            f"{'directory' if len(valid_dirs) == 1 else 'directories'}"
+        )
+
+    def stop(self) -> None:
+        """Stop watching wizard directories."""
+        if not self._running:
+            return
+
+        self.observer.stop()
+        self.observer.join(timeout=5.0)
+        self._running = False
+
+        logger.info("Hot-reload watcher stopped")
+
+    def is_running(self) -> bool:
+        """Check if watcher is running.
+
+        Returns:
+            True if watching, False otherwise
+
+        """
+        return self._running
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.stop()