attune-ai 2.0.0__py3-none-any.whl

attune/hot_reload/README.md

@@ -0,0 +1,473 @@
+# Hot-Reload Infrastructure
+
+**Version:** 1.0.0
+**Status:** Production Ready
+**Phase:** 2 of 4 - Wizard Factory Enhancement
+
+## Overview
+
+The Hot-Reload Infrastructure enables real-time wizard reloading during development without server restarts. When you modify a wizard file, it's automatically reloaded and re-registered with the wizard API.
+
+### Key Features
+
+- ✅ **Zero Downtime** - No server restart required
+- ✅ **File Watching** - Automatic detection of wizard file changes
+- ✅ **WebSocket Notifications** - Real-time client notifications
+- ✅ **Graceful Error Handling** - Reload failures don't crash the server
+- ✅ **Development Mode Toggle** - Enable/disable via environment variable
+
+---
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+pip install watchdog
+```
+
+### 2. Enable Hot-Reload
+
+Set environment variable:
+
+```bash
+export HOT_RELOAD_ENABLED=true
+```
+
+### 3. Integrate with Wizard API
+
+Add to `backend/api/wizard_api.py`:
+
+```python
+from hot_reload.integration import HotReloadIntegration
+
+app = FastAPI(title="Empathy Wizard API")
+
+# Create hot-reload integration
+hot_reload = HotReloadIntegration(app, register_wizard)
+
+@app.on_event("startup")
+async def startup_event():
+    init_wizards()  # Initialize wizards
+    hot_reload.start()  # Start hot-reload
+
+@app.on_event("shutdown")
+async def shutdown_event():
+    hot_reload.stop()
+
+# Add status endpoint
+@app.get("/api/hot-reload/status")
+async def get_hot_reload_status():
+    if not hot_reload:
+        return {"enabled": False}
+    return hot_reload.get_status()
+```
+
+### 4. Connect Frontend (Optional)
+
+```javascript
+// Connect to WebSocket for reload notifications
+const ws = new WebSocket('ws://localhost:8001/ws/hot-reload');
+
+ws.onmessage = (event) => {
+    const message = JSON.parse(event.data);
+
+    if (message.event === 'wizard_reloaded') {
+        console.log(`✓ Wizard reloaded: ${message.wizard_id}`);
+        // Refresh wizard list or show notification
+    }
+
+    if (message.event === 'wizard_reload_failed') {
+        console.error(`✗ Reload failed: ${message.error}`);
+        // Show error notification
+    }
+};
+
+// Keep connection alive
+setInterval(() => ws.send('ping'), 30000);
+```
+
+---
+
+## Architecture
+
+### Components
+
+```
+hot_reload/
+├── __init__.py          # Package exports
+├── config.py            # Configuration from environment
+├── watcher.py           # File system watcher (watchdog)
+├── reloader.py          # Dynamic module reloader
+├── websocket.py         # WebSocket notifications
+└── integration.py       # FastAPI integration
+```
+
+### Flow Diagram
+
+```
+File Change → Watcher → Reloader → Register → Notify Clients
+              ↓          ↓          ↓          ↓
+         watchdog    importlib   wizard_api  WebSocket
+```
+
+### Detailed Flow
+
+1. **File Watcher** detects `.py` file change in wizard directory
+2. **Extract Wizard ID** from filename (`debug_wizard.py` → `debug`)
+3. **Unload Module** from `sys.modules`
+4. **Reload Module** with `importlib.import_module()`
+5. **Find Wizard Class** (classes ending with "Wizard")
+6. **Re-Register** with wizard API
+7. **Notify Clients** via WebSocket
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HOT_RELOAD_ENABLED` | `false` | Enable hot-reload |
+| `HOT_RELOAD_WATCH_DIRS` | Auto-detect | Comma-separated directories to watch |
+| `HOT_RELOAD_WS_PATH` | `/ws/hot-reload` | WebSocket endpoint path |
+| `HOT_RELOAD_DELAY` | `0.5` | Debounce delay in seconds |
+
+### Watched Directories (Default)
+
+- `wizards/` - Healthcare wizards
+- `coach_wizards/` - Coach wizards
+- `empathy_software_plugin/wizards/` - AI wizards
+- `attune_llm/wizards/` - Domain wizards
+
+### Custom Watch Directories
+
+```bash
+export HOT_RELOAD_WATCH_DIRS="/path/to/custom/wizards,/another/path"
+```
+
+---
+
+## API Reference
+
+### HotReloadIntegration
+
+Main integration class for hot-reload.
+
+```python
+class HotReloadIntegration:
+    def __init__(self, app: FastAPI, register_callback: callable):
+        """Initialize hot-reload integration.
+
+        Args:
+            app: FastAPI application
+            register_callback: Function to register wizard
+                               (wizard_id, wizard_class) -> bool
+        """
+
+    def start(self) -> None:
+        """Start file watcher"""
+
+    def stop(self) -> None:
+        """Stop file watcher"""
+
+    def get_status(self) -> dict:
+        """Get hot-reload status"""
+```
+
+### WizardReloader
+
+Handles dynamic module reloading.
+
+```python
+class WizardReloader:
+    def reload_wizard(self, wizard_id: str, file_path: str) -> ReloadResult:
+        """Reload a wizard module"""
+
+    def get_reload_count(self) -> int:
+        """Get total successful reloads"""
+```
+
+### ReloadResult
+
+Result of a reload operation.
+
+```python
+@dataclass
+class ReloadResult:
+    success: bool
+    wizard_id: str
+    message: str
+    error: str | None
+```
+
+---
+
+## Usage Examples
+
+### Example 1: Basic Integration
+
+```python
+from fastapi import FastAPI
+from hot_reload.integration import HotReloadIntegration
+
+app = FastAPI()
+
+def register_wizard(wizard_id: str, wizard_class: type) -> bool:
+    """Your wizard registration logic"""
+    try:
+        WIZARDS[wizard_id] = wizard_class()
+        return True
+    except Exception:
+        return False
+
+# Initialize
+hot_reload = HotReloadIntegration(app, register_wizard)
+
+@app.on_event("startup")
+async def startup():
+    hot_reload.start()
+```
+
+### Example 2: Manual Reload
+
+```python
+from hot_reload import WizardReloader
+
+reloader = WizardReloader(
+    register_callback=register_wizard,
+    notification_callback=notify_clients
+)
+
+# Manually reload a wizard
+result = reloader.reload_wizard("debug", "/path/to/debug_wizard.py")
+
+if result.success:
+    print(f"✓ {result.message}")
+else:
+    print(f"✗ Error: {result.error}")
+```
+
+### Example 3: Custom File Watcher
+
+```python
+from pathlib import Path
+from hot_reload import WizardFileWatcher
+
+def on_change(wizard_id: str, file_path: str):
+    print(f"File changed: {wizard_id} at {file_path}")
+
+watcher = WizardFileWatcher(
+    wizard_dirs=[Path("custom/wizards")],
+    reload_callback=on_change
+)
+
+with watcher:  # Context manager auto-starts/stops
+    # Watcher is active
+    input("Press Enter to stop...")
+```
+
+---
+
+## WebSocket Protocol
+
+### Events Sent by Server
+
+#### `connected`
+```json
+{
+    "event": "connected",
+    "message": "Hot-reload notifications enabled",
+    "active_connections": 1
+}
+```
+
+#### `wizard_reloaded`
+```json
+{
+    "event": "wizard_reloaded",
+    "wizard_id": "debug",
+    "success": true,
+    "reload_count": 5
+}
+```
+
+#### `wizard_reload_failed`
+```json
+{
+    "event": "wizard_reload_failed",
+    "wizard_id": "debug",
+    "success": false,
+    "error": "Failed to import module: ModuleNotFoundError"
+}
+```
+
+### Client Messages
+
+Send `"ping"` to keep connection alive.
+
+---
+
+## Error Handling
+
+### Graceful Degradation
+
+Hot-reload failures **never crash the server**. Common errors are handled gracefully:
+
+1. **Import Errors** - Logged, old wizard continues working
+2. **Registration Errors** - Logged, old wizard continues working
+3. **File System Errors** - Logged, watcher continues monitoring
+4. **WebSocket Errors** - Client disconnected, others unaffected
+
+### Error Scenarios
+
+| Scenario | Behavior | Old Wizard |
+|----------|----------|------------|
+| Syntax error in wizard | Reload fails, error logged | Still works |
+| Missing dependency | Import fails, error logged | Still works |
+| Registration fails | Logged, notification sent | Still works |
+| WebSocket disconnect | Client removed | Others unaffected |
+
+---
+
+## Performance
+
+### Reload Speed
+
+- **File Detection**: <100ms (watchdog)
+- **Module Reload**: ~50-200ms
+- **Total Reload Time**: <500ms
+
+### Resource Usage
+
+- **Memory**: ~2-5MB (watchdog observer)
+- **CPU**: <1% (idle), ~5-10% (during reload)
+- **Network**: Minimal (WebSocket keepalive only)
+
+### Optimization Tips
+
+1. **Use Reload Delay**: Set `HOT_RELOAD_DELAY=1.0` to debounce multiple file saves
+2. **Limit Watch Directories**: Only watch directories with wizards
+3. **Disable in Production**: `HOT_RELOAD_ENABLED=false` (default)
+
+---
+
+## Troubleshooting
+
+### Hot-Reload Not Working
+
+**Check if enabled:**
+```bash
+curl http://localhost:8001/api/hot-reload/status
+```
+
+**Expected response:**
+```json
+{
+    "enabled": true,
+    "running": true,
+    "watch_dirs": ["/path/to/wizards"],
+    "reload_count": 0,
+    "websocket_connections": 0
+}
+```
+
+**If enabled=false:**
+```bash
+export HOT_RELOAD_ENABLED=true
+# Restart server
+```
+
+### Wizard Not Reloading
+
+**Check logs for errors:**
+```bash
+tail -f app.log | grep "hot.reload"
+```
+
+**Common issues:**
+1. Wizard file not in watched directory
+2. Syntax error in wizard (check reload_failed event)
+3. Import error (missing dependency)
+
+### WebSocket Not Connecting
+
+**Check endpoint:**
+```bash
+# Default path
+wscat -c ws://localhost:8001/ws/hot-reload
+```
+
+**If connection fails:**
+1. Check `HOT_RELOAD_WS_PATH` environment variable
+2. Verify FastAPI app is running
+3. Check firewall/proxy settings
+
+---
+
+## Testing
+
+### Manual Testing
+
+1. Start API with hot-reload enabled
+2. Modify a wizard file
+3. Check logs for reload message
+4. Verify wizard works with new code
+
+### Integration Tests
+
+See `tests/integration/hot_reload/` for automated tests.
+
+---
+
+## Security Considerations
+
+### Development Only
+
+⚠️ **Hot-reload is for DEVELOPMENT ONLY**
+
+- Do NOT enable in production (`HOT_RELOAD_ENABLED=false`)
+- No authentication on WebSocket endpoint
+- File system watching has security implications
+
+### Recommended Setup
+
+**Development:**
+```bash
+export HOT_RELOAD_ENABLED=true
+```
+
+**Production:**
+```bash
+export HOT_RELOAD_ENABLED=false  # Default
+```
+
+---
+
+## Roadmap
+
+### Phase 2 (Current)
+- ✅ File watching with watchdog
+- ✅ Dynamic module reloading
+- ✅ WebSocket notifications
+- ✅ FastAPI integration
+- ✅ Configuration system
+
+### Future Enhancements
+- [ ] Selective reload (only changed functions)
+- [ ] Rollback on failed reload
+- [ ] Reload history/undo
+- [ ] Hot-reload for config files
+- [ ] Browser extension for notifications
+
+---
+
+## License
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+
+---
+
+**For questions or issues, see:** [Wizard Factory Enhancement Plan](../docs/architecture/WIZARD_FACTORY_DISCOVERY.md)

attune/hot_reload/__init__.py

@@ -0,0 +1,62 @@
+"""Hot-Reload Infrastructure for Workflow Factory.
+
+Enables real-time workflow reloading during development without server restarts.
+
+Features:
+- File system monitoring with watchdog
+- Dynamic module reloading
+- WebSocket notifications to frontend
+- Graceful error handling
+- Development mode toggle
+
+Usage:
+    from hot_reload.integration import HotReloadIntegration
+
+    app = FastAPI()
+    hot_reload = HotReloadIntegration(app, register_workflow)
+
+    @app.on_event("startup")
+    async def startup():
+        hot_reload.start()
+
+    @app.on_event("shutdown")
+    async def shutdown():
+        hot_reload.stop()
+
+Environment Variables:
+    HOT_RELOAD_ENABLED: Enable hot-reload (default: false)
+    HOT_RELOAD_WATCH_DIRS: Comma-separated directories to watch
+    HOT_RELOAD_WS_PATH: WebSocket path (default: /ws/hot-reload)
+    HOT_RELOAD_DELAY: Reload delay in seconds (default: 0.5)
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .config import HotReloadConfig, get_hot_reload_config
+from .integration import HotReloadIntegration
+from .reloader import ReloadResult, WorkflowReloader
+from .watcher import WorkflowFileWatcher
+from .websocket import (
+    ReloadNotificationManager,
+    create_notification_callback,
+    get_notification_manager,
+)
+
+__all__ = [
+    # Core components
+    "WorkflowFileWatcher",
+    "WorkflowReloader",
+    "ReloadResult",
+    # WebSocket
+    "ReloadNotificationManager",
+    "get_notification_manager",
+    "create_notification_callback",
+    # Config
+    "HotReloadConfig",
+    "get_hot_reload_config",
+    # Integration
+    "HotReloadIntegration",
+]
+
+__version__ = "1.0.0"

attune/hot_reload/config.py

@@ -0,0 +1,83 @@
+"""Configuration for hot-reload system.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import os
+from pathlib import Path
+
+
+class HotReloadConfig:
+    """Configuration for hot-reload system."""
+
+    def __init__(self):
+        """Initialize configuration from environment."""
+        # Development mode (enables hot-reload)
+        self.enabled = os.getenv("HOT_RELOAD_ENABLED", "false").lower() == "true"
+
+        # Workflow directories to watch
+        self.watch_dirs = self._get_watch_dirs()
+
+        # WebSocket endpoint for notifications
+        self.websocket_path = os.getenv("HOT_RELOAD_WS_PATH", "/ws/hot-reload")
+
+        # Reload delay (seconds) to debounce multiple file changes
+        self.reload_delay = float(os.getenv("HOT_RELOAD_DELAY", "0.5"))
+
+    def _get_watch_dirs(self) -> list[Path]:
+        """Get directories to watch for workflow changes.
+
+        Returns:
+            List of directories to watch
+
+        """
+        # Default workflow directories
+        project_root = Path(__file__).parent.parent
+
+        default_dirs = [
+            project_root / "workflows",
+            project_root / "empathy_software_plugin" / "workflows",
+            project_root / "empathy_llm_toolkit" / "workflows",
+        ]
+
+        # Filter to only existing directories
+        watch_dirs = [d for d in default_dirs if d.exists()]
+
+        # Allow override via environment variable
+        env_dirs = os.getenv("HOT_RELOAD_WATCH_DIRS")
+        if env_dirs:
+            watch_dirs = [Path(d.strip()) for d in env_dirs.split(",")]
+
+        return watch_dirs
+
+    def to_dict(self) -> dict:
+        """Convert config to dictionary.
+
+        Returns:
+            Configuration as dictionary
+
+        """
+        return {
+            "enabled": self.enabled,
+            "watch_dirs": [str(d) for d in self.watch_dirs],
+            "websocket_path": self.websocket_path,
+            "reload_delay": self.reload_delay,
+        }
+
+
+# Global config instance
+_config: HotReloadConfig | None = None
+
+
+def get_hot_reload_config() -> HotReloadConfig:
+    """Get the global hot-reload configuration.
+
+    Returns:
+        Global HotReloadConfig instance
+
+    """
+    global _config
+    if _config is None:
+        _config = HotReloadConfig()
+    return _config