attune-ai 2.0.0__py3-none-any.whl

attune/resilience/health.py

@@ -0,0 +1,300 @@
+"""Health Check Module
+
+Provides system health monitoring and status reporting.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class HealthStatus(Enum):
+    """Health status levels."""
+
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class HealthCheckResult:
+    """Result of a single health check."""
+
+    name: str
+    status: HealthStatus
+    message: str = ""
+    latency_ms: float = 0.0
+    details: dict[str, Any] = field(default_factory=dict)
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+@dataclass
+class SystemHealth:
+    """Overall system health status."""
+
+    status: HealthStatus
+    checks: list[HealthCheckResult]
+    version: str = "unknown"
+    uptime_seconds: float = 0.0
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        return {
+            "status": self.status.value,
+            "version": self.version,
+            "uptime_seconds": self.uptime_seconds,
+            "timestamp": self.timestamp.isoformat(),
+            "checks": [
+                {
+                    "name": c.name,
+                    "status": c.status.value,
+                    "message": c.message,
+                    "latency_ms": c.latency_ms,
+                    "details": c.details,
+                }
+                for c in self.checks
+            ],
+        }
+
+
+class HealthCheck:
+    """Health check manager for monitoring system components.
+
+    Example:
+        health = HealthCheck(version="3.1.0")
+
+        @health.register("database")
+        async def check_database():
+            await db.ping()
+            return True
+
+        @health.register("memory_graph")
+        async def check_memory_graph():
+            graph = MemoryGraph()
+            return len(graph.nodes) >= 0
+
+        status = await health.run_all()
+        print(status.to_dict())
+
+    """
+
+    def __init__(self, version: str = "unknown"):
+        self.version = version
+        self.start_time = time.time()
+        self._checks: dict[str, Callable] = {}
+        self._timeouts: dict[str, float] = {}
+
+    def register(
+        self,
+        name: str,
+        timeout: float = 10.0,
+        critical: bool = False,
+    ) -> Callable:
+        """Decorator to register a health check.
+
+        Args:
+            name: Name of the health check
+            timeout: Maximum time for check in seconds
+            critical: If True, failure makes system unhealthy
+
+        The decorated function should:
+        - Return True for healthy
+        - Return False for unhealthy
+        - Raise exception for error
+        - Return dict with 'healthy' key for details
+
+        """
+
+        def decorator(func: Callable) -> Callable:
+            self._checks[name] = func
+            self._timeouts[name] = timeout
+            return func
+
+        return decorator
+
+    async def run_check(self, name: str) -> HealthCheckResult:
+        """Run a single health check."""
+        if name not in self._checks:
+            return HealthCheckResult(
+                name=name,
+                status=HealthStatus.UNKNOWN,
+                message=f"Check '{name}' not found",
+            )
+
+        check_func = self._checks[name]
+        timeout = self._timeouts.get(name, 10.0)
+        start = time.time()
+
+        try:
+            if asyncio.iscoroutinefunction(check_func):
+                result = await asyncio.wait_for(check_func(), timeout=timeout)
+            else:
+                result = check_func()
+
+            latency = (time.time() - start) * 1000
+
+            # Parse result
+            if isinstance(result, bool):
+                status = HealthStatus.HEALTHY if result else HealthStatus.UNHEALTHY
+                return HealthCheckResult(
+                    name=name,
+                    status=status,
+                    latency_ms=latency,
+                )
+            if isinstance(result, dict):
+                healthy = result.get("healthy", True)
+                status = HealthStatus.HEALTHY if healthy else HealthStatus.UNHEALTHY
+                return HealthCheckResult(
+                    name=name,
+                    status=status,
+                    message=result.get("message", ""),
+                    latency_ms=latency,
+                    details=result,
+                )
+            return HealthCheckResult(
+                name=name,
+                status=HealthStatus.HEALTHY,
+                latency_ms=latency,
+            )
+
+        except asyncio.TimeoutError:
+            return HealthCheckResult(
+                name=name,
+                status=HealthStatus.UNHEALTHY,
+                message=f"Check timed out after {timeout}s",
+                latency_ms=timeout * 1000,
+            )
+        except Exception as e:
+            latency = (time.time() - start) * 1000
+            return HealthCheckResult(
+                name=name,
+                status=HealthStatus.UNHEALTHY,
+                message=str(e),
+                latency_ms=latency,
+            )
+
+    async def run_all(self) -> SystemHealth:
+        """Run all registered health checks."""
+        results = await asyncio.gather(*[self.run_check(name) for name in self._checks.keys()])
+
+        # Determine overall status
+        statuses = [r.status for r in results]
+
+        if all(s == HealthStatus.HEALTHY for s in statuses):
+            overall = HealthStatus.HEALTHY
+        elif any(s == HealthStatus.UNHEALTHY for s in statuses):
+            overall = HealthStatus.UNHEALTHY
+        elif any(s == HealthStatus.DEGRADED for s in statuses):
+            overall = HealthStatus.DEGRADED
+        else:
+            overall = HealthStatus.UNKNOWN
+
+        return SystemHealth(
+            status=overall,
+            checks=list(results),
+            version=self.version,
+            uptime_seconds=time.time() - self.start_time,
+        )
+
+    def run_all_sync(self) -> SystemHealth:
+        """Synchronous version of run_all."""
+        return asyncio.run(self.run_all())
+
+
+# Global health check instance
+_health_check: HealthCheck | None = None
+
+
+def get_health_check() -> HealthCheck:
+    """Get or create global health check instance."""
+    global _health_check
+    if _health_check is None:
+        _health_check = HealthCheck()
+    return _health_check
+
+
+def register_default_checks(health: HealthCheck) -> None:
+    """Register default health checks for Empathy Framework."""
+
+    @health.register("workflow_registry")
+    async def check_workflow_registry() -> dict[str, Any]:
+        """Check workflow registry is loaded."""
+        try:
+            from attune.routing import WorkflowRegistry
+
+            registry = WorkflowRegistry()
+            workflow_count = len(registry.list_all())
+            return {
+                "healthy": workflow_count > 0,
+                "workflow_count": workflow_count,
+                "message": f"{workflow_count} workflows registered",
+            }
+        except Exception as e:
+            return {"healthy": False, "message": str(e)}
+
+    @health.register("memory_graph")
+    async def check_memory_graph() -> dict[str, Any]:
+        """Check memory graph is accessible."""
+        try:
+            from attune.memory import MemoryGraph
+
+            graph_path = Path("patterns/memory_graph.json")
+            if graph_path.exists():
+                graph = MemoryGraph(path=graph_path)
+                return {
+                    "healthy": True,
+                    "node_count": len(graph.nodes),
+                    "edge_count": len(graph.edges),
+                }
+            return {
+                "healthy": True,
+                "node_count": 0,
+                "edge_count": 0,
+                "message": "Graph file not yet created",
+            }
+        except Exception as e:
+            return {"healthy": False, "message": str(e)}
+
+    @health.register("smart_router")
+    async def check_smart_router() -> dict[str, Any]:
+        """Check smart router is functional."""
+        try:
+            from attune.routing import SmartRouter
+
+            router = SmartRouter()
+            # Test with a simple request
+            decision = router.route_sync("test request")
+            return {
+                "healthy": decision is not None,
+                "primary_workflow": decision.primary_workflow,
+            }
+        except Exception as e:
+            return {"healthy": False, "message": str(e)}
+
+    @health.register("chain_executor")
+    async def check_chain_executor() -> dict[str, Any]:
+        """Check chain executor is loaded."""
+        try:
+            from attune.routing import ChainExecutor
+
+            executor = ChainExecutor()
+            templates = executor.list_templates()
+            return {
+                "healthy": True,
+                "template_count": len(templates),
+            }
+        except Exception as e:
+            return {"healthy": False, "message": str(e)}

attune/resilience/retry.py

@@ -0,0 +1,209 @@
+"""Retry Pattern Implementation
+
+Provides exponential backoff retry logic for transient failures.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import asyncio
+import logging
+import random
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import wraps
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+@dataclass
+class RetryConfig:
+    """Configuration for retry behavior."""
+
+    max_attempts: int = 3
+    backoff_factor: float = 2.0
+    initial_delay: float = 1.0
+    max_delay: float = 60.0
+    jitter: bool = True
+    retryable_exceptions: tuple[type[Exception], ...] = field(default_factory=lambda: (Exception,))
+
+    def get_delay(self, attempt: int) -> float:
+        """Calculate delay for given attempt with exponential backoff."""
+        delay = self.initial_delay * (self.backoff_factor ** (attempt - 1))
+        delay = min(delay, self.max_delay)
+
+        if self.jitter:
+            # Add up to 25% jitter
+            delay = delay * (0.75 + random.random() * 0.5)
+
+        return delay
+
+
+def retry(
+    max_attempts: int = 3,
+    backoff_factor: float = 2.0,
+    initial_delay: float = 1.0,
+    max_delay: float = 60.0,
+    jitter: bool = True,
+    retryable_exceptions: tuple[type[Exception], ...] | None = None,
+    on_retry: Callable[[Exception, int], None] | None = None,
+) -> Callable:
+    """Decorator for retrying functions with exponential backoff.
+
+    Args:
+        max_attempts: Maximum number of retry attempts
+        backoff_factor: Multiplier for delay between attempts
+        initial_delay: Initial delay in seconds
+        max_delay: Maximum delay in seconds
+        jitter: Add randomness to prevent thundering herd
+        retryable_exceptions: Tuple of exceptions to retry on
+        on_retry: Callback called on each retry with (exception, attempt)
+
+    Example:
+        @retry(max_attempts=3, backoff_factor=2.0)
+        async def call_api():
+            response = await httpx.get("https://api.example.com")
+            return response.json()
+
+    """
+    if retryable_exceptions is None:
+        retryable_exceptions = (Exception,)
+
+    config = RetryConfig(
+        max_attempts=max_attempts,
+        backoff_factor=backoff_factor,
+        initial_delay=initial_delay,
+        max_delay=max_delay,
+        jitter=jitter,
+        retryable_exceptions=retryable_exceptions,
+    )
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            last_exception: Exception | None = None
+
+            for attempt in range(1, config.max_attempts + 1):
+                try:
+                    result: T = await func(*args, **kwargs)  # type: ignore[misc]
+                    return result
+                except config.retryable_exceptions as e:
+                    last_exception = e
+
+                    if attempt == config.max_attempts:
+                        logger.error(
+                            f"All {config.max_attempts} retries failed for {func.__name__}: {e}",
+                        )
+                        raise
+
+                    delay = config.get_delay(attempt)
+                    logger.warning(
+                        f"Attempt {attempt}/{config.max_attempts} failed for {func.__name__}: {e}. "
+                        f"Retrying in {delay:.2f}s",
+                    )
+
+                    if on_retry:
+                        on_retry(e, attempt)
+
+                    await asyncio.sleep(delay)
+
+            # Should never reach here, but satisfy type checker
+            if last_exception:
+                raise last_exception
+            raise RuntimeError("Unexpected retry loop exit")
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            import time
+
+            last_exception: Exception | None = None
+
+            for attempt in range(1, config.max_attempts + 1):
+                try:
+                    return func(*args, **kwargs)
+                except config.retryable_exceptions as e:
+                    last_exception = e
+
+                    if attempt == config.max_attempts:
+                        logger.error(
+                            f"All {config.max_attempts} retries failed for {func.__name__}: {e}",
+                        )
+                        raise
+
+                    delay = config.get_delay(attempt)
+                    logger.warning(
+                        f"Attempt {attempt}/{config.max_attempts} failed for {func.__name__}: {e}. "
+                        f"Retrying in {delay:.2f}s",
+                    )
+
+                    if on_retry:
+                        on_retry(e, attempt)
+
+                    time.sleep(delay)
+
+            if last_exception:
+                raise last_exception
+            raise RuntimeError("Unexpected retry loop exit")
+
+        # Return appropriate wrapper based on function type
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper
+
+    return decorator
+
+
+async def retry_with_backoff(
+    func: Callable[..., T],
+    *args: Any,
+    config: RetryConfig | None = None,
+    **kwargs: Any,
+) -> T:
+    """Execute a function with retry logic.
+
+    Args:
+        func: Function to execute
+        *args: Positional arguments to pass to func
+        config: Retry configuration (uses defaults if None)
+        **kwargs: Keyword arguments to pass to func
+
+    Returns:
+        Result of the function
+
+    Example:
+        result = await retry_with_backoff(
+            call_api,
+            "https://api.example.com",
+            config=RetryConfig(max_attempts=5)
+        )
+
+    """
+    if config is None:
+        config = RetryConfig()
+
+    last_exception: Exception | None = None
+
+    for attempt in range(1, config.max_attempts + 1):
+        try:
+            if asyncio.iscoroutinefunction(func):
+                result: T = await func(*args, **kwargs)
+                return result
+            return func(*args, **kwargs)
+        except config.retryable_exceptions as e:
+            last_exception = e
+
+            if attempt == config.max_attempts:
+                raise
+
+            delay = config.get_delay(attempt)
+            logger.warning(
+                f"Attempt {attempt}/{config.max_attempts} failed: {e}. Retrying in {delay:.2f}s",
+            )
+            await asyncio.sleep(delay)
+
+    if last_exception:
+        raise last_exception
+    raise RuntimeError("Unexpected retry loop exit")

attune/resilience/timeout.py

@@ -0,0 +1,135 @@
+"""Timeout Pattern Implementation
+
+Prevents operations from hanging indefinitely.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import asyncio
+import logging
+import signal
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+
+class TimeoutError(Exception):
+    """Raised when an operation times out."""
+
+    def __init__(self, operation: str, timeout: float):
+        self.operation = operation
+        self.timeout = timeout
+        super().__init__(f"Operation '{operation}' timed out after {timeout}s")
+
+
+def timeout(
+    seconds: float,
+    error_message: str | None = None,
+    fallback: Callable[..., T] | None = None,
+) -> Callable:
+    """Decorator to add timeout to a function.
+
+    Args:
+        seconds: Maximum execution time in seconds
+        error_message: Custom error message
+        fallback: Function to call on timeout
+
+    Example:
+        @timeout(30)
+        async def slow_operation():
+            ...
+
+        @timeout(10, fallback=lambda: "default")
+        async def get_data():
+            ...
+
+    """
+
+    def decorator(func: Callable[..., T]) -> Callable[..., T]:
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> T:
+            try:
+                coro = func(*args, **kwargs)
+                result: T = await asyncio.wait_for(coro, timeout=seconds)  # type: ignore[arg-type]
+                return result
+            except asyncio.TimeoutError:
+                operation = error_message or func.__name__
+                logger.warning(f"Timeout after {seconds}s: {operation}")
+
+                if fallback:
+                    logger.info(f"Using fallback for {func.__name__}")
+                    if asyncio.iscoroutinefunction(fallback):
+                        result = await fallback(*args, **kwargs)
+                        return result
+                    return fallback(*args, **kwargs)
+
+                raise TimeoutError(operation, seconds)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> T:
+            # For sync functions, use signal-based timeout (Unix only)
+            import platform
+
+            if platform.system() == "Windows":
+                # Windows doesn't support SIGALRM, just run without timeout
+                logger.warning(
+                    f"Timeout not supported on Windows for sync function {func.__name__}",
+                )
+                return func(*args, **kwargs)
+
+            def timeout_handler(signum: int, frame: Any) -> None:
+                raise TimeoutError(func.__name__, seconds)
+
+            old_handler = signal.signal(signal.SIGALRM, timeout_handler)
+            signal.setitimer(signal.ITIMER_REAL, seconds)
+
+            try:
+                result = func(*args, **kwargs)
+                signal.setitimer(signal.ITIMER_REAL, 0)
+                return result
+            except TimeoutError:
+                if fallback:
+                    return fallback(*args, **kwargs)
+                raise
+            finally:
+                signal.signal(signal.SIGALRM, old_handler)
+                signal.setitimer(signal.ITIMER_REAL, 0)
+
+        if asyncio.iscoroutinefunction(func):
+            return async_wrapper  # type: ignore[return-value]
+        return sync_wrapper
+
+    return decorator
+
+
+async def with_timeout(
+    coro: Any,
+    seconds: float,
+    fallback_value: T | None = None,
+) -> T:
+    """Execute a coroutine with a timeout.
+
+    Args:
+        coro: Coroutine to execute
+        seconds: Maximum execution time
+        fallback_value: Value to return on timeout (raises if None)
+
+    Returns:
+        Result of coroutine or fallback value
+
+    Example:
+        result = await with_timeout(slow_api_call(), 30)
+        result = await with_timeout(get_data(), 10, fallback_value={})
+
+    """
+    try:
+        return await asyncio.wait_for(coro, timeout=seconds)
+    except asyncio.TimeoutError:
+        if fallback_value is not None:
+            return fallback_value
+        raise TimeoutError("coroutine", seconds)

attune/routing/__init__.py

@@ -0,0 +1,43 @@
+"""Empathy Framework Routing Module
+
+Intelligent request routing to workflows using LLM classification.
+
+Usage:
+    from attune.routing import SmartRouter, quick_route
+
+    # Full router
+    router = SmartRouter()
+    decision = await router.route("Fix security issue in auth.py")
+    print(f"Use: {decision.primary_workflow}")
+
+    # Quick helper
+    decision = await quick_route("Optimize database queries")
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .chain_executor import ChainConfig, ChainExecution, ChainExecutor, ChainStep, ChainTrigger
+from .classifier import ClassificationResult, HaikuClassifier
+from .smart_router import RoutingDecision, SmartRouter, quick_route
+from .workflow_registry import WORKFLOW_REGISTRY, WorkflowInfo, WorkflowRegistry
+
+__all__ = [
+    "WORKFLOW_REGISTRY",
+    "ChainConfig",
+    "ChainExecution",
+    # Chain Executor
+    "ChainExecutor",
+    "ChainStep",
+    "ChainTrigger",
+    "ClassificationResult",
+    # Classifier
+    "HaikuClassifier",
+    "RoutingDecision",
+    # Smart Router
+    "SmartRouter",
+    "WorkflowInfo",
+    # Workflow Registry
+    "WorkflowRegistry",
+    "quick_route",
+]