ai-lib-python 0.5.0__py3-none-any.whl

ai_lib_python/resilience/executor.py

@@ -0,0 +1,343 @@
+"""
+Resilient executor combining all resilience patterns.
+
+Provides a unified interface for executing operations with
+retry, rate limiting, circuit breaking, and backpressure.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ai_lib_python.resilience.backpressure import Backpressure, BackpressureConfig
+from ai_lib_python.resilience.circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+)
+from ai_lib_python.resilience.rate_limiter import RateLimiter, RateLimiterConfig
+from ai_lib_python.resilience.retry import RetryConfig, RetryPolicy, RetryResult
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+T = TypeVar("T")
+
+
+@dataclass
+class ResilientConfig:
+    """Combined configuration for all resilience patterns.
+
+    Attributes:
+        retry: Retry configuration
+        rate_limit: Rate limiter configuration
+        circuit_breaker: Circuit breaker configuration
+        backpressure: Backpressure configuration
+    """
+
+    retry: RetryConfig | None = None
+    rate_limit: RateLimiterConfig | None = None
+    circuit_breaker: CircuitBreakerConfig | None = None
+    backpressure: BackpressureConfig | None = None
+
+    @classmethod
+    def default(cls) -> ResilientConfig:
+        """Create default configuration with all patterns enabled."""
+        return cls(
+            retry=RetryConfig(),
+            rate_limit=RateLimiterConfig(),
+            circuit_breaker=CircuitBreakerConfig(),
+            backpressure=BackpressureConfig(),
+        )
+
+    @classmethod
+    def minimal(cls) -> ResilientConfig:
+        """Create minimal configuration with basic retry only."""
+        return cls(retry=RetryConfig(max_retries=2))
+
+    @classmethod
+    def production(cls) -> ResilientConfig:
+        """Create production-grade configuration."""
+        return cls(
+            retry=RetryConfig(
+                max_retries=3,
+                min_delay_ms=1000,
+                max_delay_ms=30000,
+            ),
+            rate_limit=RateLimiterConfig.from_rps(10),
+            circuit_breaker=CircuitBreakerConfig(
+                failure_threshold=5,
+                cooldown_seconds=30,
+            ),
+            backpressure=BackpressureConfig(max_concurrent=10),
+        )
+
+
+@dataclass
+class ExecutionStats:
+    """Statistics from a resilient execution.
+
+    Attributes:
+        success: Whether operation succeeded
+        retry_result: Result from retry policy
+        rate_limit_wait_ms: Time spent waiting for rate limit
+        circuit_state: Current circuit breaker state
+        inflight_at_start: In-flight count at execution start
+    """
+
+    success: bool
+    retry_result: RetryResult | None = None
+    rate_limit_wait_ms: float = 0.0
+    circuit_state: str = "unknown"
+    inflight_at_start: int = 0
+
+
+class ResilientExecutor:
+    """Executor combining all resilience patterns.
+
+    Executes operations with:
+    1. Backpressure control (concurrency limiting)
+    2. Rate limiting
+    3. Circuit breaker
+    4. Retry with exponential backoff
+
+    Example:
+        >>> config = ResilientConfig.production()
+        >>> executor = ResilientExecutor(config)
+        >>> result = await executor.execute(async_operation)
+    """
+
+    def __init__(
+        self,
+        config: ResilientConfig | None = None,
+        name: str = "default",
+    ) -> None:
+        """Initialize resilient executor.
+
+        Args:
+            config: Combined resilience configuration
+            name: Identifier for this executor
+        """
+        self._config = config or ResilientConfig()
+        self._name = name
+
+        # Initialize components
+        self._retry = (
+            RetryPolicy(self._config.retry) if self._config.retry else None
+        )
+        self._rate_limiter = (
+            RateLimiter(self._config.rate_limit)
+            if self._config.rate_limit
+            else None
+        )
+        self._circuit_breaker = (
+            CircuitBreaker(self._config.circuit_breaker)
+            if self._config.circuit_breaker
+            else None
+        )
+        self._backpressure = (
+            Backpressure(self._config.backpressure)
+            if self._config.backpressure
+            else None
+        )
+
+    @property
+    def name(self) -> str:
+        """Get executor name."""
+        return self._name
+
+    @property
+    def circuit_state(self) -> str:
+        """Get current circuit breaker state."""
+        if self._circuit_breaker:
+            return self._circuit_breaker.state.value
+        return "disabled"
+
+    @property
+    def current_inflight(self) -> int:
+        """Get current in-flight count."""
+        if self._backpressure:
+            return self._backpressure.current_inflight
+        return 0
+
+    async def execute(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        on_retry: Callable[[int, Exception, float], None] | None = None,
+    ) -> T:
+        """Execute an operation with all resilience patterns.
+
+        Args:
+            operation: Async operation to execute
+            on_retry: Optional callback on retry
+
+        Returns:
+            Operation result
+
+        Raises:
+            CircuitOpenError: If circuit is open
+            Exception: Original exception if all retries fail
+        """
+        # 1. Backpressure control
+        if self._backpressure:
+            async with self._backpressure.acquire():
+                return await self._execute_inner(operation, on_retry)
+        else:
+            return await self._execute_inner(operation, on_retry)
+
+    async def _execute_inner(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        on_retry: Callable[[int, Exception, float], None] | None = None,
+    ) -> T:
+        """Execute with rate limiting, circuit breaker, and retry.
+
+        Args:
+            operation: Async operation
+            on_retry: Retry callback
+
+        Returns:
+            Operation result
+        """
+        # 2. Rate limiting
+        if self._rate_limiter:
+            await self._rate_limiter.acquire()
+
+        # 3. Circuit breaker + 4. Retry
+        if self._circuit_breaker:
+            return await self._circuit_breaker.execute(
+                lambda: self._execute_with_retry(operation, on_retry)
+            )
+        else:
+            return await self._execute_with_retry(operation, on_retry)
+
+    async def _execute_with_retry(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        on_retry: Callable[[int, Exception, float], None] | None = None,
+    ) -> T:
+        """Execute with retry.
+
+        Args:
+            operation: Async operation
+            on_retry: Retry callback
+
+        Returns:
+            Operation result
+        """
+        if self._retry:
+            result = await self._retry.execute(operation, on_retry)
+            if result.success:
+                return result.value
+            raise result.error  # type: ignore
+        else:
+            return await operation()
+
+    async def execute_with_stats(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        on_retry: Callable[[int, Exception, float], None] | None = None,
+    ) -> tuple[T, ExecutionStats]:
+        """Execute and return execution statistics.
+
+        Args:
+            operation: Async operation
+            on_retry: Retry callback
+
+        Returns:
+            Tuple of (result, stats)
+        """
+        stats = ExecutionStats(
+            success=False,
+            circuit_state=self.circuit_state,
+            inflight_at_start=self.current_inflight,
+        )
+
+        try:
+            # 1. Backpressure
+            if self._backpressure:
+                async with self._backpressure.acquire():
+                    result = await self._execute_inner_with_stats(
+                        operation, on_retry, stats
+                    )
+            else:
+                result = await self._execute_inner_with_stats(
+                    operation, on_retry, stats
+                )
+
+            stats.success = True
+            return result, stats
+
+        except Exception:
+            stats.success = False
+            raise
+
+    async def _execute_inner_with_stats(
+        self,
+        operation: Callable[[], Awaitable[T]],
+        on_retry: Callable[[int, Exception, float], None] | None,
+        stats: ExecutionStats,
+    ) -> T:
+        """Execute with stats collection.
+
+        Args:
+            operation: Async operation
+            on_retry: Retry callback
+            stats: Stats object to populate
+
+        Returns:
+            Operation result
+        """
+        # Rate limiting
+        if self._rate_limiter:
+            wait_time = await self._rate_limiter.acquire()
+            stats.rate_limit_wait_ms = wait_time * 1000
+
+        # Circuit breaker + Retry
+        async def inner() -> T:
+            if self._retry:
+                result = await self._retry.execute(operation, on_retry)
+                stats.retry_result = result
+                if result.success:
+                    return result.value
+                raise result.error  # type: ignore
+            return await operation()
+
+        if self._circuit_breaker:
+            stats.circuit_state = self._circuit_breaker.state.value
+            return await self._circuit_breaker.execute(inner)
+        else:
+            return await inner()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get current statistics from all components.
+
+        Returns:
+            Dict with component statistics
+        """
+        stats: dict[str, Any] = {"name": self._name}
+
+        if self._rate_limiter:
+            stats["rate_limiter"] = {
+                "available_tokens": self._rate_limiter.available_tokens,
+                "is_limited": self._rate_limiter.is_limited,
+            }
+
+        if self._circuit_breaker:
+            cb_stats = self._circuit_breaker.get_stats()
+            stats["circuit_breaker"] = {
+                "state": self._circuit_breaker.state.value,
+                "total_requests": cb_stats.total_requests,
+                "failed_requests": cb_stats.failed_requests,
+                "rejected_requests": cb_stats.rejected_requests,
+            }
+
+        if self._backpressure:
+            stats["backpressure"] = self._backpressure.get_stats()
+
+        return stats
+
+    def reset(self) -> None:
+        """Reset all components to initial state."""
+        if self._circuit_breaker:
+            self._circuit_breaker.reset()

ai_lib_python/resilience/fallback.py

@@ -0,0 +1,341 @@
+"""
+Fallback chain for multi-model degradation.
+
+Provides automatic failover between multiple AI providers/models.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from ai_lib_python.errors import AiLibError, is_fallbackable
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+T = TypeVar("T")
+
+
+@dataclass
+class FallbackTarget:
+    """A target in the fallback chain.
+
+    Attributes:
+        name: Identifier for this target
+        operation: Async operation factory
+        weight: Priority weight (higher = preferred)
+        enabled: Whether this target is enabled
+    """
+
+    name: str
+    operation: Callable[..., Awaitable[T]]
+    weight: float = 1.0
+    enabled: bool = True
+
+
+@dataclass
+class FallbackConfig:
+    """Configuration for fallback chain.
+
+    Attributes:
+        retry_all: Whether to retry all targets on failure
+        max_attempts_per_target: Max attempts per target before fallback
+        delay_between_targets_ms: Delay between fallback attempts
+    """
+
+    retry_all: bool = True
+    max_attempts_per_target: int = 1
+    delay_between_targets_ms: int = 0
+
+
+@dataclass
+class FallbackResult:
+    """Result of a fallback chain execution.
+
+    Attributes:
+        success: Whether operation succeeded
+        value: Result value (if success)
+        target_used: Name of target that succeeded
+        targets_tried: List of targets attempted
+        errors: Mapping of target names to errors
+    """
+
+    success: bool
+    value: Any = None
+    target_used: str | None = None
+    targets_tried: list[str] = field(default_factory=list)
+    errors: dict[str, Exception] = field(default_factory=dict)
+
+
+class FallbackChain:
+    """Fallback chain for automatic failover.
+
+    Executes operations through a chain of targets, falling back
+    to the next target on failure.
+
+    Example:
+        >>> chain = FallbackChain()
+        >>> chain.add_target("gpt-4", lambda: call_openai("gpt-4"))
+        >>> chain.add_target("claude", lambda: call_anthropic("claude"))
+        >>> result = await chain.execute()
+    """
+
+    def __init__(self, config: FallbackConfig | None = None) -> None:
+        """Initialize fallback chain.
+
+        Args:
+            config: Fallback configuration
+        """
+        self._config = config or FallbackConfig()
+        self._targets: list[FallbackTarget] = []
+
+    def add_target(
+        self,
+        name: str,
+        operation: Callable[..., Awaitable[T]],
+        weight: float = 1.0,
+        enabled: bool = True,
+    ) -> FallbackChain:
+        """Add a target to the fallback chain.
+
+        Args:
+            name: Target identifier
+            operation: Async operation factory
+            weight: Priority weight
+            enabled: Whether target is enabled
+
+        Returns:
+            Self for chaining
+        """
+        self._targets.append(
+            FallbackTarget(
+                name=name,
+                operation=operation,
+                weight=weight,
+                enabled=enabled,
+            )
+        )
+        return self
+
+    def remove_target(self, name: str) -> bool:
+        """Remove a target from the chain.
+
+        Args:
+            name: Target name to remove
+
+        Returns:
+            True if removed, False if not found
+        """
+        for i, target in enumerate(self._targets):
+            if target.name == name:
+                self._targets.pop(i)
+                return True
+        return False
+
+    def set_enabled(self, name: str, enabled: bool) -> bool:
+        """Enable or disable a target.
+
+        Args:
+            name: Target name
+            enabled: Whether to enable
+
+        Returns:
+            True if target found, False otherwise
+        """
+        for target in self._targets:
+            if target.name == name:
+                target.enabled = enabled
+                return True
+        return False
+
+    def get_targets(self) -> list[str]:
+        """Get list of target names in priority order.
+
+        Returns:
+            List of target names
+        """
+        # Sort by weight (descending)
+        sorted_targets = sorted(
+            [t for t in self._targets if t.enabled],
+            key=lambda t: t.weight,
+            reverse=True,
+        )
+        return [t.name for t in sorted_targets]
+
+    def _should_fallback(self, error: Exception) -> bool:
+        """Check if error should trigger fallback.
+
+        Args:
+            error: The exception
+
+        Returns:
+            True if should fallback
+        """
+        # Check if error has error_class
+        if hasattr(error, "error_class"):
+            return is_fallbackable(error.error_class)
+
+        # Default: fallback on any AiLibError
+        return isinstance(error, AiLibError)
+
+    async def execute(
+        self,
+        *args: Any,
+        on_fallback: Callable[[str, str, Exception], None] | None = None,
+        **kwargs: Any,
+    ) -> FallbackResult:
+        """Execute operation through fallback chain.
+
+        Args:
+            *args: Arguments to pass to operations
+            on_fallback: Callback when falling back (from, to, error)
+            **kwargs: Keyword arguments to pass to operations
+
+        Returns:
+            FallbackResult with outcome
+        """
+        # Get enabled targets sorted by weight
+        targets = sorted(
+            [t for t in self._targets if t.enabled],
+            key=lambda t: t.weight,
+            reverse=True,
+        )
+
+        if not targets:
+            return FallbackResult(
+                success=False,
+                errors={"_chain": ValueError("No enabled targets in chain")},
+            )
+
+        errors: dict[str, Exception] = {}
+        targets_tried: list[str] = []
+        last_target: str | None = None
+
+        for target in targets:
+            targets_tried.append(target.name)
+
+            for attempt in range(self._config.max_attempts_per_target):
+                try:
+                    result = await target.operation(*args, **kwargs)
+                    return FallbackResult(
+                        success=True,
+                        value=result,
+                        target_used=target.name,
+                        targets_tried=targets_tried,
+                        errors=errors,
+                    )
+                except Exception as e:
+                    errors[target.name] = e
+
+                    # Check if should fallback
+                    if not self._should_fallback(e):
+                        # Non-fallbackable error, stop chain
+                        return FallbackResult(
+                            success=False,
+                            errors=errors,
+                            targets_tried=targets_tried,
+                        )
+
+                    # Only retry if more attempts available
+                    if attempt < self._config.max_attempts_per_target - 1:
+                        continue
+                    break
+
+            # Callback before falling back
+            if on_fallback and last_target:
+                next_target = (
+                    targets[targets.index(target) + 1].name
+                    if targets.index(target) + 1 < len(targets)
+                    else None
+                )
+                if next_target:
+                    on_fallback(target.name, next_target, errors[target.name])
+
+            last_target = target.name
+
+            # Delay between targets
+            if self._config.delay_between_targets_ms > 0:
+                await asyncio.sleep(self._config.delay_between_targets_ms / 1000)
+
+        # All targets failed
+        return FallbackResult(
+            success=False,
+            errors=errors,
+            targets_tried=targets_tried,
+        )
+
+
+class MultiFallback:
+    """Multi-strategy fallback manager.
+
+    Manages multiple fallback chains for different scenarios.
+
+    Example:
+        >>> mf = MultiFallback()
+        >>> mf.register_chain("chat", chat_chain)
+        >>> mf.register_chain("embed", embed_chain)
+        >>> result = await mf.execute("chat", messages=[...])
+    """
+
+    def __init__(self) -> None:
+        """Initialize multi-fallback manager."""
+        self._chains: dict[str, FallbackChain] = {}
+
+    def register_chain(self, name: str, chain: FallbackChain) -> MultiFallback:
+        """Register a fallback chain.
+
+        Args:
+            name: Chain identifier
+            chain: FallbackChain instance
+
+        Returns:
+            Self for chaining
+        """
+        self._chains[name] = chain
+        return self
+
+    def get_chain(self, name: str) -> FallbackChain | None:
+        """Get a registered chain.
+
+        Args:
+            name: Chain name
+
+        Returns:
+            Chain or None if not found
+        """
+        return self._chains.get(name)
+
+    async def execute(
+        self,
+        chain_name: str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> FallbackResult:
+        """Execute operation through a named chain.
+
+        Args:
+            chain_name: Name of chain to use
+            *args: Arguments to pass
+            **kwargs: Keyword arguments to pass
+
+        Returns:
+            FallbackResult
+
+        Raises:
+            ValueError: If chain not found
+        """
+        chain = self._chains.get(chain_name)
+        if not chain:
+            raise ValueError(f"Unknown fallback chain: {chain_name}")
+
+        return await chain.execute(*args, **kwargs)
+
+    def list_chains(self) -> list[str]:
+        """Get list of registered chain names.
+
+        Returns:
+            List of chain names
+        """
+        return list(self._chains.keys())