agent-tool-resilience 0.1.0__py3-none-any.whl

agent_tool_resilience/__init__.py

@@ -0,0 +1,32 @@
+"""
+agent-tool-resilience: Production-grade resilience for AI agent tool calls.
+
+Provides smart retries, fallbacks, circuit breakers, and result validation
+to prevent silent failures in AI agent workflows.
+"""
+
+from .retry import RetryPolicy, RetryError
+from .circuit_breaker import CircuitBreaker, CircuitBreakerOpen
+from .fallback import FallbackChain, FallbackError
+from .validator import ResultValidator, ValidationError
+from .tracer import ToolExecutionTracer, ExecutionEvent
+from .rate_limit import RateLimitHandler, RateLimitExceeded
+from .resilient_tool import ResilientTool, resilient_tool
+
+__version__ = "0.1.0"
+__all__ = [
+    "ResilientTool",
+    "resilient_tool",
+    "RetryPolicy",
+    "RetryError",
+    "CircuitBreaker",
+    "CircuitBreakerOpen",
+    "FallbackChain",
+    "FallbackError",
+    "ResultValidator",
+    "ValidationError",
+    "ToolExecutionTracer",
+    "ExecutionEvent",
+    "RateLimitHandler",
+    "RateLimitExceeded",
+]

agent_tool_resilience/circuit_breaker.py

@@ -0,0 +1,246 @@
+"""
+Circuit breaker pattern to prevent cascade failures.
+"""
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Callable, Optional
+
+
+class CircuitState(Enum):
+    """Circuit breaker states."""
+    CLOSED = "closed"      # Normal operation, requests pass through
+    OPEN = "open"          # Circuit is open, requests fail immediately
+    HALF_OPEN = "half_open"  # Testing if service has recovered
+
+
+class CircuitBreakerOpen(Exception):
+    """Raised when the circuit breaker is open."""
+    
+    def __init__(self, message: str, reset_time: Optional[float] = None):
+        super().__init__(message)
+        self.reset_time = reset_time
+
+
+@dataclass
+class CircuitBreaker:
+    """
+    Circuit breaker to prevent cascade failures.
+    
+    The circuit breaker has three states:
+    - CLOSED: Normal operation, requests pass through
+    - OPEN: Too many failures, requests fail immediately
+    - HALF_OPEN: Testing recovery, limited requests allowed
+    
+    Attributes:
+        failure_threshold: Number of failures before opening circuit
+        success_threshold: Number of successes in half-open to close circuit
+        reset_timeout: Seconds to wait before transitioning from open to half-open
+        half_open_max_calls: Maximum concurrent calls in half-open state
+        exclude_exceptions: Exception types that don't count as failures
+        on_state_change: Callback for state transitions
+    """
+    failure_threshold: int = 5
+    success_threshold: int = 2
+    reset_timeout: float = 60.0
+    half_open_max_calls: int = 3
+    exclude_exceptions: tuple[type, ...] = field(default_factory=tuple)
+    on_state_change: Optional[Callable[[CircuitState, CircuitState], None]] = None
+    
+    # Internal state (not part of config)
+    _state: CircuitState = field(default=CircuitState.CLOSED, init=False)
+    _failure_count: int = field(default=0, init=False)
+    _success_count: int = field(default=0, init=False)
+    _last_failure_time: Optional[float] = field(default=None, init=False)
+    _half_open_calls: int = field(default=0, init=False)
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False)
+    
+    @property
+    def state(self) -> CircuitState:
+        """Get current circuit state."""
+        with self._lock:
+            self._maybe_transition_to_half_open()
+            return self._state
+    
+    @property
+    def failure_count(self) -> int:
+        """Get current failure count."""
+        with self._lock:
+            return self._failure_count
+    
+    @property
+    def is_closed(self) -> bool:
+        """Check if circuit is closed (normal operation)."""
+        return self.state == CircuitState.CLOSED
+    
+    @property
+    def is_open(self) -> bool:
+        """Check if circuit is open (blocking requests)."""
+        return self.state == CircuitState.OPEN
+    
+    @property
+    def is_half_open(self) -> bool:
+        """Check if circuit is half-open (testing recovery)."""
+        return self.state == CircuitState.HALF_OPEN
+    
+    def _maybe_transition_to_half_open(self) -> None:
+        """Check if we should transition from open to half-open."""
+        if self._state == CircuitState.OPEN and self._last_failure_time:
+            elapsed = time.time() - self._last_failure_time
+            if elapsed >= self.reset_timeout:
+                self._transition_to(CircuitState.HALF_OPEN)
+    
+    def _transition_to(self, new_state: CircuitState) -> None:
+        """Transition to a new state."""
+        old_state = self._state
+        self._state = new_state
+        
+        if new_state == CircuitState.CLOSED:
+            self._failure_count = 0
+            self._success_count = 0
+            self._half_open_calls = 0
+        elif new_state == CircuitState.HALF_OPEN:
+            self._success_count = 0
+            self._half_open_calls = 0
+        elif new_state == CircuitState.OPEN:
+            self._last_failure_time = time.time()
+        
+        if self.on_state_change and old_state != new_state:
+            self.on_state_change(old_state, new_state)
+    
+    def _record_success(self) -> None:
+        """Record a successful call."""
+        with self._lock:
+            if self._state == CircuitState.HALF_OPEN:
+                self._success_count += 1
+                if self._success_count >= self.success_threshold:
+                    self._transition_to(CircuitState.CLOSED)
+            elif self._state == CircuitState.CLOSED:
+                # Reset failure count on success
+                self._failure_count = 0
+    
+    def _record_failure(self, exception: Exception) -> None:
+        """Record a failed call."""
+        # Check if this exception type is excluded
+        if isinstance(exception, self.exclude_exceptions):
+            return
+        
+        with self._lock:
+            self._failure_count += 1
+            
+            if self._state == CircuitState.HALF_OPEN:
+                # Any failure in half-open immediately opens the circuit
+                self._transition_to(CircuitState.OPEN)
+            elif self._state == CircuitState.CLOSED:
+                if self._failure_count >= self.failure_threshold:
+                    self._transition_to(CircuitState.OPEN)
+    
+    def _allow_request(self) -> bool:
+        """Check if a request should be allowed."""
+        with self._lock:
+            self._maybe_transition_to_half_open()
+            
+            if self._state == CircuitState.CLOSED:
+                return True
+            elif self._state == CircuitState.OPEN:
+                return False
+            elif self._state == CircuitState.HALF_OPEN:
+                if self._half_open_calls < self.half_open_max_calls:
+                    self._half_open_calls += 1
+                    return True
+                return False
+        
+        return False
+    
+    def execute(
+        self,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any
+    ) -> Any:
+        """
+        Execute a function with circuit breaker protection.
+        
+        Args:
+            func: Function to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+            
+        Returns:
+            Function's return value
+            
+        Raises:
+            CircuitBreakerOpen: If circuit is open
+        """
+        if not self._allow_request():
+            reset_time = None
+            if self._last_failure_time:
+                reset_time = self._last_failure_time + self.reset_timeout
+            raise CircuitBreakerOpen(
+                f"Circuit breaker is {self._state.value}",
+                reset_time=reset_time
+            )
+        
+        try:
+            result = func(*args, **kwargs)
+            self._record_success()
+            return result
+        except Exception as e:
+            self._record_failure(e)
+            raise
+    
+    async def execute_async(
+        self,
+        func: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any
+    ) -> Any:
+        """
+        Execute an async function with circuit breaker protection.
+        
+        Args:
+            func: Async function to execute
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+            
+        Returns:
+            Function's return value
+            
+        Raises:
+            CircuitBreakerOpen: If circuit is open
+        """
+        if not self._allow_request():
+            reset_time = None
+            if self._last_failure_time:
+                reset_time = self._last_failure_time + self.reset_timeout
+            raise CircuitBreakerOpen(
+                f"Circuit breaker is {self._state.value}",
+                reset_time=reset_time
+            )
+        
+        try:
+            result = await func(*args, **kwargs)
+            self._record_success()
+            return result
+        except Exception as e:
+            self._record_failure(e)
+            raise
+    
+    def reset(self) -> None:
+        """Manually reset the circuit breaker to closed state."""
+        with self._lock:
+            self._transition_to(CircuitState.CLOSED)
+    
+    def get_stats(self) -> dict:
+        """Get circuit breaker statistics."""
+        with self._lock:
+            return {
+                "state": self._state.value,
+                "failure_count": self._failure_count,
+                "success_count": self._success_count,
+                "last_failure_time": self._last_failure_time,
+                "half_open_calls": self._half_open_calls,
+            }

agent_tool_resilience/fallback.py

@@ -0,0 +1,188 @@
+"""
+Fallback strategies for graceful degradation.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Sequence
+
+
+class FallbackError(Exception):
+    """Raised when all fallbacks have failed."""
+    
+    def __init__(self, message: str, errors: list[tuple[str, Exception]]):
+        super().__init__(message)
+        self.errors = errors
+
+
+@dataclass
+class FallbackChain:
+    """
+    Chain of fallback functions to try in sequence.
+    
+    Attributes:
+        fallbacks: Sequence of fallback functions to try
+        names: Optional names for each fallback (for error reporting)
+        on_fallback: Optional callback when a fallback is used
+    """
+    fallbacks: Sequence[Callable[..., Any]]
+    names: Optional[Sequence[str]] = None
+    on_fallback: Optional[Callable[[int, str, Exception], None]] = None
+    
+    def __post_init__(self):
+        if self.names is None:
+            self.names = [f"fallback_{i}" for i in range(len(self.fallbacks))]
+        elif len(self.names) != len(self.fallbacks):
+            raise ValueError("Number of names must match number of fallbacks")
+    
+    def execute(
+        self,
+        *args: Any,
+        primary_exception: Optional[Exception] = None,
+        **kwargs: Any
+    ) -> Any:
+        """
+        Execute fallbacks in sequence until one succeeds.
+        
+        Args:
+            *args: Positional arguments passed to fallbacks
+            primary_exception: The exception from the primary function
+            **kwargs: Keyword arguments passed to fallbacks
+            
+        Returns:
+            Result from the first successful fallback
+            
+        Raises:
+            FallbackError: If all fallbacks fail
+        """
+        errors: list[tuple[str, Exception]] = []
+        
+        if primary_exception:
+            errors.append(("primary", primary_exception))
+        
+        for i, (fallback, name) in enumerate(zip(self.fallbacks, self.names)):
+            try:
+                result = fallback(*args, **kwargs)
+                
+                if self.on_fallback and i > 0:
+                    last_error = errors[-1][1] if errors else None
+                    self.on_fallback(i, name, last_error)
+                
+                return result
+            except Exception as e:
+                errors.append((name, e))
+        
+        raise FallbackError(
+            f"All {len(self.fallbacks)} fallbacks failed",
+            errors=errors
+        )
+    
+    async def execute_async(
+        self,
+        *args: Any,
+        primary_exception: Optional[Exception] = None,
+        **kwargs: Any
+    ) -> Any:
+        """
+        Execute async fallbacks in sequence until one succeeds.
+        
+        Args:
+            *args: Positional arguments passed to fallbacks
+            primary_exception: The exception from the primary function
+            **kwargs: Keyword arguments passed to fallbacks
+            
+        Returns:
+            Result from the first successful fallback
+            
+        Raises:
+            FallbackError: If all fallbacks fail
+        """
+        errors: list[tuple[str, Exception]] = []
+        
+        if primary_exception:
+            errors.append(("primary", primary_exception))
+        
+        for i, (fallback, name) in enumerate(zip(self.fallbacks, self.names)):
+            try:
+                result = await fallback(*args, **kwargs)
+                
+                if self.on_fallback and i > 0:
+                    last_error = errors[-1][1] if errors else None
+                    self.on_fallback(i, name, last_error)
+                
+                return result
+            except Exception as e:
+                errors.append((name, e))
+        
+        raise FallbackError(
+            f"All {len(self.fallbacks)} fallbacks failed",
+            errors=errors
+        )
+
+
+@dataclass
+class CachedFallback:
+    """
+    Fallback that returns cached results when primary fails.
+    
+    Attributes:
+        cache: Dictionary mapping args to cached results
+        default: Default value if no cache entry exists
+        ttl_seconds: Time-to-live for cache entries (None = infinite)
+    """
+    cache: dict[Any, tuple[Any, float]] = field(default_factory=dict)
+    default: Any = None
+    ttl_seconds: Optional[float] = None
+    
+    def get(self, key: Any) -> Any:
+        """Get a cached value."""
+        import time
+        
+        if key not in self.cache:
+            return self.default
+        
+        value, timestamp = self.cache[key]
+        
+        if self.ttl_seconds is not None:
+            if time.time() - timestamp > self.ttl_seconds:
+                del self.cache[key]
+                return self.default
+        
+        return value
+    
+    def set(self, key: Any, value: Any) -> None:
+        """Set a cached value."""
+        import time
+        self.cache[key] = (value, time.time())
+    
+    def as_fallback(self) -> Callable[[Any], Any]:
+        """Return a fallback function that uses this cache."""
+        def fallback(*args, **kwargs):
+            # Use args as cache key
+            key = (args, tuple(sorted(kwargs.items())))
+            return self.get(key)
+        return fallback
+
+
+def static_fallback(value: Any) -> Callable[..., Any]:
+    """Create a fallback that always returns a static value."""
+    def fallback(*args, **kwargs):
+        return value
+    return fallback
+
+
+def error_fallback(
+    error_type: str = "service_unavailable",
+    include_args: bool = False
+) -> Callable[..., dict]:
+    """Create a fallback that returns an error response dict."""
+    def fallback(*args, **kwargs):
+        response = {
+            "error": True,
+            "error_type": error_type,
+            "message": "Service temporarily unavailable",
+        }
+        if include_args:
+            response["args"] = args
+            response["kwargs"] = kwargs
+        return response
+    return fallback