langchain-chaos-middleware 0.1.4__py3-none-any.whl

chaos_middleware.py

@@ -0,0 +1,158 @@
+import os
+import random
+from typing import List, Optional, Any, Type, Callable
+try:
+    from typing import TypedDict
+except ImportError:
+    from typing_extensions import TypedDict
+
+# Import LangChain v1 middleware types
+try:
+    from langchain.agents.middleware import (
+        AgentMiddleware,
+        ModelRequest,
+        ModelResponse,
+    )
+    # ToolCallRequest might be in a different location or named differently
+    # We'll handle this gracefully
+    try:
+        from langchain.agents.middleware import ToolCallRequest
+    except ImportError:
+        # If ToolCallRequest doesn't exist, we'll use the request object directly
+        ToolCallRequest = Any
+except ImportError:
+    # Fallback for development/testing without LangChain installed
+    class AgentMiddleware:
+        pass
+    ModelRequest = Any
+    ModelResponse = Any
+    ToolCallRequest = Any
+
+class ChaosConfig(TypedDict):
+    """Configuration for the Chaos Monkey Middleware.
+    
+    Attributes:
+        failure_rate: Probability of failure (0.0 to 1.0). Default is 0.1.
+        exception_types: List of exception classes to choose from when failing.
+        include_tools: List of tool names to target. If None, all tools are targeted.
+        exclude_tools: List of tool names to exclude from chaos.
+        seed: Random seed for reproducibility.
+        safety_key: Environment variable name that must be "true" to enable chaos. Default: "ENABLE_CHAOS".
+    """
+    failure_rate: float
+    exception_types: List[Type[Exception]]
+    include_tools: Optional[List[str]]
+    exclude_tools: List[str]
+    seed: Optional[int]
+    safety_key: str
+
+class ChaosMiddleware(AgentMiddleware):
+    """Middleware that injects random failures into tool and model calls.
+    
+    This middleware is designed to test the resilience of an agent by simulating
+    network errors, service outages, or other unexpected exceptions.
+    
+    !!!Important!!!
+        The middleware will ONLY be active if the environment variable specified
+        by `safety_key` (default: "ENABLE_CHAOS") is set to "true".
+    """
+    def __init__(self, config: ChaosConfig):
+        self.config = config
+        self.failure_rate = config.get("failure_rate", 0.1)
+        self.exception_types = config.get("exception_types", [])
+        self.include_tools = config.get("include_tools", None)
+        self.exclude_tools = config.get("exclude_tools", [])
+        self.seed = config.get("seed", None)
+        self.safety_key = config.get("safety_key", "ENABLE_CHAOS")
+        
+        if self.seed is not None:
+            random.seed(self.seed)
+
+    def wrap_tool_call(
+        self, 
+        request: ToolCallRequest, 
+        handler: Callable[[ToolCallRequest], Any]
+    ) -> Any:
+        """Intercepts tool calls and potentially raises an exception.
+        
+        Args:
+            request: The ToolCallRequest object containing tool information.
+            handler: The next handler in the chain.
+            
+        Returns:
+            The result of the handler if no exception is raised.
+            
+        Raises:
+            Exception: A random exception from `exception_types` if chaos is triggered.
+        """
+        # Safety Check
+        if os.environ.get(self.safety_key, "").lower() != "true":
+            return handler(request)
+
+        # Extract tool name from request
+        # The request object should have a 'tool' attribute with the BaseTool instance
+        tool_name = getattr(request, 'tool', None)
+        if tool_name is not None:
+            tool_name = getattr(tool_name, 'name', str(tool_name))
+        
+        # Target Check
+        if tool_name and tool_name in self.exclude_tools:
+            return handler(request)
+        
+        if self.include_tools is not None and (not tool_name or tool_name not in self.include_tools):
+            return handler(request)
+
+        # Roll Dice
+        if random.random() <= self.failure_rate:
+            if self.exception_types:
+                # Instantiate the exception class
+                raise random.choice(self.exception_types)()
+            else:
+                raise Exception("Chaos Monkey triggered!")
+
+        return handler(request)
+
+    def wrap_model_call(
+        self, 
+        request: ModelRequest, 
+        handler: Callable[[ModelRequest], ModelResponse]
+    ) -> ModelResponse:
+        """Intercepts model calls and potentially raises an exception.
+        
+        Args:
+            request: The ModelRequest object.
+            handler: The next handler in the chain.
+            
+        Returns:
+            The ModelResponse if no exception is raised.
+            
+        Raises:
+            Exception: A random exception from `exception_types` if chaos is triggered.
+        """
+        # Safety Check
+        if os.environ.get(self.safety_key, "").lower() != "true":
+            return handler(request)
+
+        # Roll Dice
+        if random.random() <= self.failure_rate:
+            if self.exception_types:
+                # Instantiate the exception class
+                raise random.choice(self.exception_types)()
+            else:
+                raise Exception("Chaos Monkey triggered on model call!")
+
+        return handler(request)
+
+# Custom Exceptions for Chaos
+class RateLimitError(Exception):
+    """Simulated Rate Limit Error"""
+    pass
+
+class ServiceUnavailableError(Exception):
+    """Simulated Service Unavailable Error"""
+    pass
+
+# Default Exception Profiles
+NETWORK_ERRORS = [TimeoutError, ConnectionError]
+LLM_ERRORS = [RateLimitError, ServiceUnavailableError]
+CRITICAL_ERRORS = [ValueError, KeyError]

langchain_chaos_middleware-0.1.4.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: langchain-chaos-middleware
+Version: 0.1.4
+Summary: Chaos testing middleware for LangChain agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: langchain>=1.0.0
+Requires-Dist: langgraph>=1.0.0
+
+# LangChain Chaos Middleware ( Chaos Monkey )
+
+A middleware for LangChain agents that intentionally injects failures (exceptions) into tool and model calls to test agent resilience.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+- [Configuration](#configuration)
+- [Default Exception Profiles](#default-exception-profiles)
+- [Custom Exception Profiles](#custom-exception-profiles)
+- [Understanding Failure Rates](#understanding-failure-rates)
+- [Important Note for Production](#important-note-for-production)
+- [For Developers](#for-developers)
+  - [Setting Up the Development Environment](#setting-up-the-development-environment)
+  - [Running Tests](#running-tests)
+  - [Test Coverage](#test-coverage)
+  - [Contributing](#contributing)
+
+## Features
+
+- **Failure Injection**: Randomly raises exceptions based on a configurable failure rate.
+- **Targeted Chaos**: Include or exclude specific tools from chaos.
+- **Safety Mechanism**: Requires an environment variable (`ENABLE_CHAOS=true`) to be active, preventing accidental production issues.
+- **Customizable Exceptions**: Choose which exceptions to raise (e.g., network errors, rate limits).
+
+## Installation
+
+```bash
+pip install langchain-chaos-middleware
+```
+
+## Usage
+
+### Basic Example
+
+```python
+import os
+from langchain.agents import create_agent
+from chaos_middleware import ChaosMiddleware, NETWORK_ERRORS
+
+# 1. Enable Chaos (Safety Check)
+os.environ["ENABLE_CHAOS"] = "true"
+
+# 2. Configure Middleware
+chaos_config = {
+    "failure_rate": 0.2,  # 20% chance of failure
+    "exception_types": NETWORK_ERRORS,
+    "exclude_tools": ["save_memory"], # Don't break critical tools
+}
+chaos = ChaosMiddleware(chaos_config)
+
+# 3. Inject into Agent
+agent = create_agent(
+    model="gpt-4o",
+    tools=[...],
+    middleware=[chaos]
+)
+
+# 4. Run Agent
+# The agent will now experience random network errors!
+```
+
+## Configuration
+
+The `ChaosMiddleware` is initialized with a `ChaosConfig` dictionary:
+
+| Key | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `failure_rate` | `float` | `0.1` | Probability of failure (0.0 to 1.0). |
+| `exception_types` | `List[Exception]` | `[]` | List of exceptions to randomly choose from. |
+| `include_tools` | `List[str]` | `None` | If set, only these tools will be targeted. |
+| `exclude_tools` | `List[str]` | `[]` | These tools will NEVER fail. |
+| `seed` | `int` | `None` | Random seed for reproducible chaos. |
+| `safety_key` | `str` | `"ENABLE_CHAOS"` | Env var name required to enable the middleware. |
+
+## Default Exception Profiles
+
+The library provides pre-built lists of exceptions for common scenarios:
+
+- `NETWORK_ERRORS`: `[TimeoutError, ConnectionError]`
+- `LLM_ERRORS`: `[RateLimitError, ServiceUnavailableError]`
+- `CRITICAL_ERRORS`: `[ValueError, KeyError]`
+
+## Custom Exception Profiles
+
+You can define your own lists of exceptions to simulate specific scenarios (e.g., database failures, custom API errors). Just create a list of exception classes and pass it to the `exception_types` configuration:
+
+```python
+class DatabaseError(Exception):
+    pass
+
+MY_DB_ERRORS = [DatabaseError]
+
+config = {
+    "exception_types": MY_DB_ERRORS,
+    # ...
+}
+```
+
+## Understanding Failure Rates
+
+The `failure_rate` applies to **each individual tool call**, not to the entire agent task. If your agent needs to call multiple tools to complete a task, the overall success rate will be lower than you might expect.
+
+**Example**: With a 20% failure rate per tool:
+- **Single tool call**: 80% chance of success
+- **Two tool calls**: 80% × 80% = **64% chance of success**
+- **Three tool calls**: 80% × 80% × 80% = **51% chance of success**
+
+This means that even with a "low" 20% failure rate, an agent that needs to call 3 tools has nearly a 50% chance of experiencing at least one failure during the task.
+
+**Tip**: Start with a low failure rate (e.g., 10-20%) and observe how it affects your agent's overall success rate before increasing it.
+
+## Important Note for Production
+
+To prevent accidental chaos in production, the middleware checks for an environment variable (default: `ENABLE_CHAOS`). If this variable is not set to `"true"`, the middleware acts as a pass-through and does nothing.
+
+## For Developers
+
+### Setting Up the Development Environment
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/iroy2000/langchain-chaos-middleware.git
+   cd langchain-chaos-middleware
+   ```
+
+2. **Create a virtual environment**:
+   ```bash
+   python3 -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   # Install the package dependencies
+   .venv/bin/pip install langchain langgraph
+   
+   # Install test dependencies
+   .venv/bin/pip install python-dotenv langchain-openai
+   ```
+
+### Running Tests
+
+The project includes unit tests to verify the middleware functionality.
+
+**Run all tests**:
+```bash
+.venv/bin/python -m unittest discover tests
+```
+
+**Run only unit tests**:
+```bash
+.venv/bin/python -m unittest tests.test_unit
+```
+
+**Run integration tests** (requires OpenAI API key):
+```bash
+# Create a .env file with your OpenAI API key
+echo "OPENAI_API_KEY=your-key-here" > .env
+
+# Run the integration test
+.venv/bin/python tests/test_integration.py
+```
+
+### Test Coverage
+
+The test suite includes:
+- **Safety mechanism tests**: Verifies chaos is disabled without the safety key
+- **Failure injection tests**: Confirms failures are injected at the configured rate
+- **Tool filtering tests**: Validates include/exclude tool lists work correctly
+- **Model call tests**: Ensures chaos applies to model calls as well
+
+### Contributing
+
+Contributions are welcome! Please ensure all tests pass before submitting a pull request:
+
+```bash
+.venv/bin/python -m unittest discover tests
+```

langchain_chaos_middleware-0.1.4.dist-info/RECORD

@@ -0,0 +1,5 @@
+chaos_middleware.py,sha256=jdpWXc7-Uzr0-icueqICsq6Ns0JSdPNTUJUvGiO3Emg,5589
+langchain_chaos_middleware-0.1.4.dist-info/METADATA,sha256=VMAVfAYikBVRkV3uDImilGuLVnyhTaCQ8XuZaqRLFc8,6127
+langchain_chaos_middleware-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+langchain_chaos_middleware-0.1.4.dist-info/top_level.txt,sha256=52Tu5Ki3CseAj-exVyTM2tIDqBejIWQnJBHRgnrkyRU,17
+langchain_chaos_middleware-0.1.4.dist-info/RECORD,,

langchain_chaos_middleware-0.1.4.dist-info/WHEEL

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

langchain_chaos_middleware-0.1.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+chaos_middleware