attune-ai 2.0.0__py3-none-any.whl

attune/hot_reload/integration.py

@@ -0,0 +1,229 @@
+"""Integration example for hot-reload with workflow API.
+
+Shows how to integrate hot-reload into the existing workflow_api.py.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+from collections.abc import Callable
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+from .config import get_hot_reload_config
+from .reloader import WorkflowReloader
+from .watcher import WorkflowFileWatcher
+from .websocket import create_notification_callback, get_notification_manager
+
+logger = logging.getLogger(__name__)
+
+
+class HotReloadIntegration:
+    """Integrates hot-reload with workflow API.
+
+    Example usage in workflow_api.py:
+
+        from hot_reload.integration import HotReloadIntegration
+
+        # Create FastAPI app
+        app = FastAPI()
+
+        # Initialize hot-reload (if enabled)
+        hot_reload = HotReloadIntegration(app, register_workflow)
+
+        @app.on_event("startup")
+        async def startup_event():
+            init_workflows()  # Initialize workflows
+            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[[str, type], bool],
+    ):
+        """Initialize hot-reload integration.
+
+        Args:
+            app: FastAPI application instance
+            register_callback: Function to register workflow (workflow_id, workflow_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 = WorkflowReloader(
+            register_callback=self._register_workflow_wrapper,
+            notification_callback=self.notification_callback,
+        )
+
+        self.watcher: WorkflowFileWatcher | None = None
+
+        # Add WebSocket endpoint to app
+        if self.config.enabled:
+            self._setup_websocket_endpoint()
+
+    def _register_workflow_wrapper(self, workflow_id: str, workflow_class: type) -> bool:
+        """Wrapper for register callback that handles errors.
+
+        Args:
+            workflow_id: Workflow identifier
+            workflow_class: Workflow class to register
+
+        Returns:
+            True if registration succeeded
+
+        """
+        try:
+            return self.register_callback(workflow_id, workflow_class)
+        except Exception as e:
+            logger.error(f"Error registering workflow {workflow_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 workflow directories found to watch")
+            return
+
+        if self.watcher and self.watcher.is_running():
+            logger.warning("Hot-reload already started")
+            return
+
+        # Create watcher
+        self.watcher = WorkflowFileWatcher(
+            workflow_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, workflow_id: str, file_path: str) -> None:
+        """Handle file change event.
+
+        Args:
+            workflow_id: ID of workflow that changed
+            file_path: Path to changed file
+
+        """
+        logger.info(f"File change detected: {workflow_id} ({file_path})")
+
+        # Reload workflow
+        result = self.reloader.reload_workflow(workflow_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 workflow_api.py:
+"""
+from fastapi import FastAPI
+from hot_reload.integration import HotReloadIntegration
+
+app = FastAPI(title="Empathy Workflow API")
+
+# Global hot-reload instance
+hot_reload = None
+
+
+def register_workflow(workflow_id: str, workflow_class: type, *args, **kwargs) -> bool:
+    '''Register workflow with WORKFLOWS dict'''
+    try:
+        WORKFLOWS[workflow_id] = workflow_class(*args, **kwargs)
+        logger.info(f"✓ Registered workflow: {workflow_id}")
+        return True
+    except Exception as e:
+        logger.error(f"Failed to register {workflow_id}: {e}")
+        return False
+
+
+@app.on_event("startup")
+async def startup_event():
+    global hot_reload
+
+    # Initialize workflows
+    init_workflows()
+
+    # Start hot-reload
+    hot_reload = HotReloadIntegration(app, register_workflow)
+    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()
+"""

attune/hot_reload/reloader.py

@@ -0,0 +1,298 @@
+"""Dynamic workflow reloader for hot-reload.
+
+Handles reloading workflow 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 workflow reload operation."""
+
+    def __init__(
+        self,
+        success: bool,
+        workflow_id: str,
+        message: str,
+        error: str | None = None,
+    ):
+        """Initialize reload result.
+
+        Args:
+            success: Whether reload succeeded
+            workflow_id: ID of workflow that was reloaded
+            message: Status message
+            error: Error message if failed
+
+        """
+        self.success = success
+        self.workflow_id = workflow_id
+        self.message = message
+        self.error = error
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "success": self.success,
+            "workflow_id": self.workflow_id,
+            "message": self.message,
+            "error": self.error,
+        }
+
+
+class WorkflowReloader:
+    """Handles dynamic reloading of workflow modules.
+
+    Supports hot-reload of workflows without server restart by:
+    1. Unloading old module from sys.modules
+    2. Reloading module with importlib
+    3. Re-registering workflow with workflow 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 workflow (workflow_id, workflow_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_workflow(self, workflow_id: str, file_path: str) -> ReloadResult:
+        """Reload a workflow module.
+
+        Args:
+            workflow_id: Workflow identifier
+            file_path: Path to workflow file
+
+        Returns:
+            ReloadResult with outcome
+
+        """
+        logger.info(f"Attempting to reload workflow: {workflow_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,
+                    workflow_id=workflow_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(workflow_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    workflow_id=workflow_id,
+                    message="Import failed",
+                    error=error_msg,
+                )
+
+            # Find workflow class in module
+            workflow_class = self._find_workflow_class(module)
+            if not workflow_class:
+                error_msg = f"No workflow class found in {module_name}"
+                logger.error(error_msg)
+                self._notify_reload_failed(workflow_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    workflow_id=workflow_id,
+                    message="No workflow class found",
+                    error=error_msg,
+                )
+
+            # Re-register workflow
+            success = self.register_callback(workflow_id, workflow_class)
+
+            if success:
+                self._reload_count += 1
+                logger.info(
+                    f"✓ Successfully reloaded {workflow_id} ({self._reload_count} total reloads)"
+                )
+                self._notify_reload_success(workflow_id)
+
+                return ReloadResult(
+                    success=True,
+                    workflow_id=workflow_id,
+                    message=f"Reloaded successfully (reload #{self._reload_count})",
+                )
+            else:
+                error_msg = "Registration failed"
+                logger.error(f"Failed to re-register {workflow_id}")
+                self._notify_reload_failed(workflow_id, error_msg)
+                return ReloadResult(
+                    success=False,
+                    workflow_id=workflow_id,
+                    message="Registration failed",
+                    error=error_msg,
+                )
+
+        except Exception as e:
+            error_msg = f"Unexpected error reloading {workflow_id}: {e}"
+            logger.exception(error_msg)
+            self._notify_reload_failed(workflow_id, str(e))
+            return ReloadResult(
+                success=False,
+                workflow_id=workflow_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: workflows/, empathy_software_plugin/workflows/
+            parts = path.parts
+
+            # Find workflow directory in path
+            workflow_dir_indices = [i for i, part in enumerate(parts) if "workflow" in part.lower()]
+
+            if not workflow_dir_indices:
+                return None
+
+            # Take from first workflow directory
+            start_idx = workflow_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_workflow_class(self, module: Any) -> type | None:
+        """Find workflow class in module.
+
+        Args:
+            module: Python module
+
+        Returns:
+            Workflow class or None if not found
+
+        """
+        # Look for classes ending with "Workflow"
+        for name in dir(module):
+            if name.endswith("Workflow") and not name.startswith("_"):
+                attr = getattr(module, name)
+                if isinstance(attr, type):
+                    return attr
+
+        return None
+
+    def _notify_reload_success(self, workflow_id: str) -> None:
+        """Notify clients of successful reload.
+
+        Args:
+            workflow_id: ID of reloaded workflow
+
+        """
+        if self.notification_callback:
+            try:
+                self.notification_callback(
+                    {
+                        "event": "workflow_reloaded",
+                        "workflow_id": workflow_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, workflow_id: str, error: str) -> None:
+        """Notify clients of failed reload.
+
+        Args:
+            workflow_id: ID of workflow that failed to reload
+            error: Error message
+
+        """
+        if self.notification_callback:
+            try:
+                self.notification_callback(
+                    {
+                        "event": "workflow_reload_failed",
+                        "workflow_id": workflow_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

attune/hot_reload/watcher.py

@@ -0,0 +1,183 @@
+"""File system watcher for workflow hot-reload.
+
+Monitors workflow 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 WorkflowFileHandler(FileSystemEventHandler):
+    """Handles file system events for workflow files."""
+
+    def __init__(self, reload_callback: Callable[[str, str], None]):
+        """Initialize handler.
+
+        Args:
+            reload_callback: Function to call when workflow file changes (workflow_id, file_path)
+
+        """
+        super().__init__()
+        self.reload_callback = reload_callback
+        self._processing: set[str] = 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
+
+        # Convert file_path to str if it's bytes
+        file_path_raw = event.src_path
+        file_path = (
+            file_path_raw.decode("utf-8") if isinstance(file_path_raw, bytes) else file_path_raw
+        )
+
+        # 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)
+
+            workflow_id = self._extract_workflow_id(file_path)
+            if workflow_id:
+                logger.info(f"Detected change in {workflow_id} ({file_path})")
+                self.reload_callback(workflow_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_workflow_id(self, file_path: str) -> str | None:
+        """Extract workflow ID from file path.
+
+        Args:
+            file_path: Path to workflow file
+
+        Returns:
+            Workflow ID or None if cannot extract
+
+        """
+        path = Path(file_path)
+
+        # Get filename without extension
+        filename = path.stem
+
+        # Remove common suffixes
+        workflow_id = filename.replace("_workflow", "").replace("workflow_", "")
+
+        # Convert to workflow ID format (snake_case)
+        workflow_id = workflow_id.lower()
+
+        return workflow_id if workflow_id else None
+
+
+class WorkflowFileWatcher:
+    """Watches workflow directories for file changes.
+
+    Monitors specified directories and triggers reload callbacks
+    when workflow files are modified.
+    """
+
+    def __init__(self, workflow_dirs: list[Path], reload_callback: Callable[[str, str], None]):
+        """Initialize watcher.
+
+        Args:
+            workflow_dirs: List of directories to watch
+            reload_callback: Function to call on file changes (workflow_id, file_path)
+
+        """
+        self.workflow_dirs = [Path(d) for d in workflow_dirs]
+        self.reload_callback = reload_callback
+        self.observer = Observer()
+        self.event_handler = WorkflowFileHandler(reload_callback)
+        self._running = False
+
+    def start(self) -> None:
+        """Start watching workflow directories."""
+        if self._running:
+            logger.warning("Watcher already running")
+            return
+
+        valid_dirs = []
+        for directory in self.workflow_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 workflow 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()