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

agent_tool_resilience/validator.py

@@ -0,0 +1,217 @@
+"""
+Result validation for tool outputs.
+"""
+
+import json
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional, Sequence, Union
+
+
+class ValidationError(Exception):
+    """Raised when tool output fails validation."""
+    
+    def __init__(self, message: str, result: Any, errors: list[str]):
+        super().__init__(message)
+        self.result = result
+        self.errors = errors
+
+
+@dataclass
+class ResultValidator:
+    """
+    Validates tool outputs against schemas and conditions.
+    
+    Attributes:
+        schema: JSON Schema dict for validation (requires jsonschema package)
+        conditions: List of predicate functions that must all return True
+        required_keys: Keys that must be present in dict results
+        type_check: Expected type for the result
+        on_invalid: Callback when validation fails
+    """
+    schema: Optional[dict] = None
+    conditions: Sequence[Callable[[Any], bool]] = field(default_factory=list)
+    required_keys: Sequence[str] = field(default_factory=list)
+    type_check: Optional[type] = None
+    on_invalid: Optional[Callable[[Any, list[str]], None]] = None
+    
+    def validate(self, result: Any) -> Any:
+        """
+        Validate a result, raising ValidationError if invalid.
+        
+        Args:
+            result: The result to validate
+            
+        Returns:
+            The result if valid
+            
+        Raises:
+            ValidationError: If validation fails
+        """
+        errors: list[str] = []
+        
+        # Type check
+        if self.type_check is not None:
+            if not isinstance(result, self.type_check):
+                errors.append(
+                    f"Expected type {self.type_check.__name__}, "
+                    f"got {type(result).__name__}"
+                )
+        
+        # Required keys check
+        if self.required_keys and isinstance(result, dict):
+            missing = [k for k in self.required_keys if k not in result]
+            if missing:
+                errors.append(f"Missing required keys: {missing}")
+        
+        # JSON Schema validation
+        if self.schema is not None:
+            schema_errors = self._validate_schema(result)
+            errors.extend(schema_errors)
+        
+        # Custom condition checks
+        for i, condition in enumerate(self.conditions):
+            try:
+                if not condition(result):
+                    errors.append(f"Condition {i} failed")
+            except Exception as e:
+                errors.append(f"Condition {i} raised exception: {e}")
+        
+        if errors:
+            if self.on_invalid:
+                self.on_invalid(result, errors)
+            raise ValidationError(
+                f"Validation failed with {len(errors)} error(s)",
+                result=result,
+                errors=errors
+            )
+        
+        return result
+    
+    def _validate_schema(self, result: Any) -> list[str]:
+        """Validate against JSON Schema."""
+        errors = []
+        
+        try:
+            import jsonschema
+            
+            validator = jsonschema.Draft7Validator(self.schema)
+            for error in validator.iter_errors(result):
+                path = ".".join(str(p) for p in error.path) or "root"
+                errors.append(f"Schema error at {path}: {error.message}")
+        except ImportError:
+            # Fall back to basic validation if jsonschema not installed
+            errors.extend(self._basic_schema_validate(result, self.schema))
+        
+        return errors
+    
+    def _basic_schema_validate(
+        self,
+        result: Any,
+        schema: dict,
+        path: str = "root"
+    ) -> list[str]:
+        """Basic schema validation without jsonschema package."""
+        errors = []
+        
+        # Type validation
+        schema_type = schema.get("type")
+        if schema_type:
+            type_map = {
+                "string": str,
+                "number": (int, float),
+                "integer": int,
+                "boolean": bool,
+                "array": list,
+                "object": dict,
+                "null": type(None),
+            }
+            expected = type_map.get(schema_type)
+            if expected and not isinstance(result, expected):
+                errors.append(
+                    f"Schema error at {path}: expected {schema_type}, "
+                    f"got {type(result).__name__}"
+                )
+        
+        # Required fields for objects
+        if isinstance(result, dict):
+            required = schema.get("required", [])
+            for key in required:
+                if key not in result:
+                    errors.append(
+                        f"Schema error at {path}: missing required key '{key}'"
+                    )
+            
+            # Validate properties
+            properties = schema.get("properties", {})
+            for key, prop_schema in properties.items():
+                if key in result:
+                    errors.extend(
+                        self._basic_schema_validate(
+                            result[key],
+                            prop_schema,
+                            f"{path}.{key}"
+                        )
+                    )
+        
+        # Validate array items
+        if isinstance(result, list):
+            items_schema = schema.get("items")
+            if items_schema:
+                for i, item in enumerate(result):
+                    errors.extend(
+                        self._basic_schema_validate(
+                            item,
+                            items_schema,
+                            f"{path}[{i}]"
+                        )
+                    )
+        
+        return errors
+    
+    def is_valid(self, result: Any) -> bool:
+        """Check if a result is valid without raising an exception."""
+        try:
+            self.validate(result)
+            return True
+        except ValidationError:
+            return False
+
+
+# Common validators
+def not_none() -> ResultValidator:
+    """Validate that result is not None."""
+    return ResultValidator(
+        conditions=[lambda r: r is not None]
+    )
+
+
+def not_empty() -> ResultValidator:
+    """Validate that result is not empty (for strings, lists, dicts)."""
+    return ResultValidator(
+        conditions=[lambda r: bool(r)]
+    )
+
+
+def has_keys(*keys: str) -> ResultValidator:
+    """Validate that result dict has specific keys."""
+    return ResultValidator(required_keys=list(keys))
+
+
+def matches_type(expected_type: type) -> ResultValidator:
+    """Validate that result is of a specific type."""
+    return ResultValidator(type_check=expected_type)
+
+
+def in_range(
+    min_val: Optional[Union[int, float]] = None,
+    max_val: Optional[Union[int, float]] = None
+) -> ResultValidator:
+    """Validate that numeric result is within a range."""
+    conditions = []
+    
+    if min_val is not None:
+        conditions.append(lambda r: r >= min_val)
+    if max_val is not None:
+        conditions.append(lambda r: r <= max_val)
+    
+    return ResultValidator(conditions=conditions)

agent_tool_resilience-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+agent_tool_resilience/__init__.py,sha256=7rXh6-kxCQlZrFnAT26GquZ4_eLg7o6TSkGK_gLXeL4,950
+agent_tool_resilience/circuit_breaker.py,sha256=ejC1L9qmfRpaB2AUnrJ2fvjip_llrkxYrdU3kyCROKs,8566
+agent_tool_resilience/fallback.py,sha256=QSsYIwyS6UZOUzU2ISnWqydlx9Jp9YEdfrvFWzPurzw,5915
+agent_tool_resilience/rate_limit.py,sha256=w5Ak05Of5CC2uKXr74IeP6CXYLkiOOsXcCxQxqKKVkc,8787
+agent_tool_resilience/resilient_tool.py,sha256=bUTNMSoqViA8jqT9sjf8ttD8RtnA2fnFKPJtftyFREU,13773
+agent_tool_resilience/retry.py,sha256=_b_KVmjWS5-p2UPhhj206Da1mZeN1vF3RkOge8DJbE0,6774
+agent_tool_resilience/tracer.py,sha256=YRQi9naD66oRbrP8KxT7D-H82dslwH0XVoOQ59CsxFQ,10299
+agent_tool_resilience/validator.py,sha256=-3SeWs5z89-v9QJ_O66u4pGBylRsIOrsXI94YB4Q3dU,7078
+agent_tool_resilience-0.1.0.dist-info/METADATA,sha256=ntSPXS-hzw7t5ZLe8ua_w0_TXgaAiNlclDjQdojnokw,5344
+agent_tool_resilience-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+agent_tool_resilience-0.1.0.dist-info/top_level.txt,sha256=2iwiEMf33mMYIhEGThg6xhl-k69BGa_8SKMSh95umOM,22
+agent_tool_resilience-0.1.0.dist-info/RECORD,,

agent_tool_resilience-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_tool_resilience-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent_tool_resilience