agent-tool-resilience 0.1.0__tar.gz

agent_tool_resilience-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: agent-tool-resilience
+Version: 0.1.0
+Summary: Production-grade resilience for AI agent tool calls: retries, fallbacks, circuit breakers, and validation
+Author-email: Korah Stone <korahcomm@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/KorahStone/agent-tool-resilience
+Project-URL: Documentation, https://github.com/KorahStone/agent-tool-resilience#readme
+Project-URL: Repository, https://github.com/KorahStone/agent-tool-resilience.git
+Project-URL: Issues, https://github.com/KorahStone/agent-tool-resilience/issues
+Keywords: ai,agents,llm,resilience,retry,circuit-breaker,fallback,tools,langchain,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: jsonschema
+Requires-Dist: jsonschema>=4.0.0; extra == "jsonschema"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: agent-tool-resilience[dev,jsonschema]; extra == "all"
+
+# agent-tool-resilience
+
+A Python library for making AI agent tool calls resilient, with smart retries, fallbacks, circuit breakers, and result validation.
+
+## Why?
+
+AI agents fail silently when tools break. This library provides production-grade resilience patterns:
+
+- **Smart Retries**: Exponential backoff with jitter, respects rate limits
+- **Fallbacks**: Graceful degradation when primary tools fail
+- **Circuit Breakers**: Prevent cascade failures by stopping calls to broken services
+- **Result Validation**: Ensure tool outputs meet expected schemas/conditions
+- **Observability**: Full visibility into what happened during tool execution
+
+## Installation
+
+```bash
+pip install agent-tool-resilience
+```
+
+## Quick Start
+
+```python
+from agent_tool_resilience import ResilientTool, RetryPolicy, CircuitBreaker
+
+# Wrap any tool with resilience
+@ResilientTool(
+    retry=RetryPolicy(max_attempts=3, backoff="exponential"),
+    circuit_breaker=CircuitBreaker(failure_threshold=5, reset_timeout=60),
+    fallback=lambda *args, **kwargs: {"error": "service unavailable", "cached": True}
+)
+def call_weather_api(location: str) -> dict:
+    return requests.get(f"https://api.weather.com/{location}").json()
+
+# Use it normally - resilience is automatic
+result = call_weather_api("NYC")
+```
+
+## Features
+
+### Retry Policies
+
+```python
+from agent_tool_resilience import RetryPolicy
+
+# Exponential backoff with jitter
+policy = RetryPolicy(
+    max_attempts=5,
+    backoff="exponential",
+    base_delay=1.0,
+    max_delay=60.0,
+    jitter=True,
+    retry_on=[TimeoutError, ConnectionError, RateLimitError]
+)
+```
+
+### Circuit Breakers
+
+Prevent cascade failures by temporarily stopping calls to failing services:
+
+```python
+from agent_tool_resilience import CircuitBreaker
+
+breaker = CircuitBreaker(
+    failure_threshold=5,      # Open after 5 failures
+    success_threshold=2,      # Close after 2 successes
+    reset_timeout=60,         # Try again after 60 seconds
+    half_open_max_calls=3     # Limited calls in half-open state
+)
+```
+
+### Fallback Strategies
+
+```python
+from agent_tool_resilience import FallbackChain
+
+fallbacks = FallbackChain([
+    lambda loc: call_backup_weather_api(loc),
+    lambda loc: get_cached_weather(loc),
+    lambda loc: {"status": "unavailable", "location": loc}
+])
+```
+
+### Result Validation
+
+```python
+from agent_tool_resilience import ResultValidator
+
+validator = ResultValidator(
+    schema={"type": "object", "required": ["temperature", "humidity"]},
+    conditions=[
+        lambda r: r.get("temperature") is not None,
+        lambda r: -100 < r.get("temperature", 0) < 150
+    ]
+)
+```
+
+### Observability
+
+```python
+from agent_tool_resilience import ToolExecutionTracer
+
+tracer = ToolExecutionTracer()
+
+@ResilientTool(tracer=tracer)
+def my_tool():
+    ...
+
+# After execution
+print(tracer.get_execution_log())
+# [
+#   {"tool": "my_tool", "attempt": 1, "status": "failed", "error": "timeout", "duration_ms": 5023},
+#   {"tool": "my_tool", "attempt": 2, "status": "success", "duration_ms": 234}
+# ]
+```
+
+### Rate Limit Awareness
+
+```python
+from agent_tool_resilience import RateLimitHandler
+
+handler = RateLimitHandler(
+    requests_per_minute=60,
+    respect_retry_after=True,
+    auto_throttle=True
+)
+```
+
+## Integration with Agent Frameworks
+
+Works with any Python agent framework:
+
+```python
+# LangChain
+from langchain.tools import Tool
+from agent_tool_resilience import ResilientTool
+
+@ResilientTool(retry=RetryPolicy(max_attempts=3))
+def search(query: str) -> str:
+    ...
+
+langchain_tool = Tool(name="search", func=search, description="Search the web")
+
+# OpenAI Function Calling
+@ResilientTool(circuit_breaker=CircuitBreaker(failure_threshold=3))
+def get_stock_price(symbol: str) -> dict:
+    ...
+```
+
+## License
+
+MIT

agent_tool_resilience-0.1.0/README.md

@@ -0,0 +1,152 @@
+# agent-tool-resilience
+
+A Python library for making AI agent tool calls resilient, with smart retries, fallbacks, circuit breakers, and result validation.
+
+## Why?
+
+AI agents fail silently when tools break. This library provides production-grade resilience patterns:
+
+- **Smart Retries**: Exponential backoff with jitter, respects rate limits
+- **Fallbacks**: Graceful degradation when primary tools fail
+- **Circuit Breakers**: Prevent cascade failures by stopping calls to broken services
+- **Result Validation**: Ensure tool outputs meet expected schemas/conditions
+- **Observability**: Full visibility into what happened during tool execution
+
+## Installation
+
+```bash
+pip install agent-tool-resilience
+```
+
+## Quick Start
+
+```python
+from agent_tool_resilience import ResilientTool, RetryPolicy, CircuitBreaker
+
+# Wrap any tool with resilience
+@ResilientTool(
+    retry=RetryPolicy(max_attempts=3, backoff="exponential"),
+    circuit_breaker=CircuitBreaker(failure_threshold=5, reset_timeout=60),
+    fallback=lambda *args, **kwargs: {"error": "service unavailable", "cached": True}
+)
+def call_weather_api(location: str) -> dict:
+    return requests.get(f"https://api.weather.com/{location}").json()
+
+# Use it normally - resilience is automatic
+result = call_weather_api("NYC")
+```
+
+## Features
+
+### Retry Policies
+
+```python
+from agent_tool_resilience import RetryPolicy
+
+# Exponential backoff with jitter
+policy = RetryPolicy(
+    max_attempts=5,
+    backoff="exponential",
+    base_delay=1.0,
+    max_delay=60.0,
+    jitter=True,
+    retry_on=[TimeoutError, ConnectionError, RateLimitError]
+)
+```
+
+### Circuit Breakers
+
+Prevent cascade failures by temporarily stopping calls to failing services:
+
+```python
+from agent_tool_resilience import CircuitBreaker
+
+breaker = CircuitBreaker(
+    failure_threshold=5,      # Open after 5 failures
+    success_threshold=2,      # Close after 2 successes
+    reset_timeout=60,         # Try again after 60 seconds
+    half_open_max_calls=3     # Limited calls in half-open state
+)
+```
+
+### Fallback Strategies
+
+```python
+from agent_tool_resilience import FallbackChain
+
+fallbacks = FallbackChain([
+    lambda loc: call_backup_weather_api(loc),
+    lambda loc: get_cached_weather(loc),
+    lambda loc: {"status": "unavailable", "location": loc}
+])
+```
+
+### Result Validation
+
+```python
+from agent_tool_resilience import ResultValidator
+
+validator = ResultValidator(
+    schema={"type": "object", "required": ["temperature", "humidity"]},
+    conditions=[
+        lambda r: r.get("temperature") is not None,
+        lambda r: -100 < r.get("temperature", 0) < 150
+    ]
+)
+```
+
+### Observability
+
+```python
+from agent_tool_resilience import ToolExecutionTracer
+
+tracer = ToolExecutionTracer()
+
+@ResilientTool(tracer=tracer)
+def my_tool():
+    ...
+
+# After execution
+print(tracer.get_execution_log())
+# [
+#   {"tool": "my_tool", "attempt": 1, "status": "failed", "error": "timeout", "duration_ms": 5023},
+#   {"tool": "my_tool", "attempt": 2, "status": "success", "duration_ms": 234}
+# ]
+```
+
+### Rate Limit Awareness
+
+```python
+from agent_tool_resilience import RateLimitHandler
+
+handler = RateLimitHandler(
+    requests_per_minute=60,
+    respect_retry_after=True,
+    auto_throttle=True
+)
+```
+
+## Integration with Agent Frameworks
+
+Works with any Python agent framework:
+
+```python
+# LangChain
+from langchain.tools import Tool
+from agent_tool_resilience import ResilientTool
+
+@ResilientTool(retry=RetryPolicy(max_attempts=3))
+def search(query: str) -> str:
+    ...
+
+langchain_tool = Tool(name="search", func=search, description="Search the web")
+
+# OpenAI Function Calling
+@ResilientTool(circuit_breaker=CircuitBreaker(failure_threshold=3))
+def get_stock_price(symbol: str) -> dict:
+    ...
+```
+
+## License
+
+MIT

agent_tool_resilience-0.1.0/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-0.1.0/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,
+            }