langchain 1.0.0a12__py3-none-any.whl → 1.0.4__py3-none-any.whl

langchain/agents/middleware/tool_emulator.py

@@ -0,0 +1,200 @@
+"""Tool emulator middleware for testing."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import HumanMessage, ToolMessage
+
+from langchain.agents.middleware.types import AgentMiddleware
+from langchain.chat_models.base import init_chat_model
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langgraph.types import Command
+
+    from langchain.agents.middleware.types import ToolCallRequest
+    from langchain.tools import BaseTool
+
+
+class LLMToolEmulator(AgentMiddleware):
+    """Emulates specified tools using an LLM instead of executing them.
+
+    This middleware allows selective emulation of tools for testing purposes.
+    By default (when tools=None), all tools are emulated. You can specify which
+    tools to emulate by passing a list of tool names or BaseTool instances.
+
+    Examples:
+        Emulate all tools (default behavior):
+        ```python
+        from langchain.agents.middleware import LLMToolEmulator
+
+        middleware = LLMToolEmulator()
+
+        agent = create_agent(
+            model="openai:gpt-4o",
+            tools=[get_weather, get_user_location, calculator],
+            middleware=[middleware],
+        )
+        ```
+
+        Emulate specific tools by name:
+        ```python
+        middleware = LLMToolEmulator(tools=["get_weather", "get_user_location"])
+        ```
+
+        Use a custom model for emulation:
+        ```python
+        middleware = LLMToolEmulator(
+            tools=["get_weather"], model="anthropic:claude-sonnet-4-5-20250929"
+        )
+        ```
+
+        Emulate specific tools by passing tool instances:
+        ```python
+        middleware = LLMToolEmulator(tools=[get_weather, get_user_location])
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        tools: list[str | BaseTool] | None = None,
+        model: str | BaseChatModel | None = None,
+    ) -> None:
+        """Initialize the tool emulator.
+
+        Args:
+            tools: List of tool names (str) or BaseTool instances to emulate.
+                If None (default), ALL tools will be emulated.
+                If empty list, no tools will be emulated.
+            model: Model to use for emulation.
+                Defaults to "anthropic:claude-sonnet-4-5-20250929".
+                Can be a model identifier string or BaseChatModel instance.
+        """
+        super().__init__()
+
+        # Extract tool names from tools
+        # None means emulate all tools
+        self.emulate_all = tools is None
+        self.tools_to_emulate: set[str] = set()
+
+        if not self.emulate_all and tools is not None:
+            for tool in tools:
+                if isinstance(tool, str):
+                    self.tools_to_emulate.add(tool)
+                else:
+                    # Assume BaseTool with .name attribute
+                    self.tools_to_emulate.add(tool.name)
+
+        # Initialize emulator model
+        if model is None:
+            self.model = init_chat_model("anthropic:claude-sonnet-4-5-20250929", temperature=1)
+        elif isinstance(model, BaseChatModel):
+            self.model = model
+        else:
+            self.model = init_chat_model(model, temperature=1)
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        """Emulate tool execution using LLM if tool should be emulated.
+
+        Args:
+            request: Tool call request to potentially emulate.
+            handler: Callback to execute the tool (can be called multiple times).
+
+        Returns:
+            ToolMessage with emulated response if tool should be emulated,
+            otherwise calls handler for normal execution.
+        """
+        tool_name = request.tool_call["name"]
+
+        # Check if this tool should be emulated
+        should_emulate = self.emulate_all or tool_name in self.tools_to_emulate
+
+        if not should_emulate:
+            # Let it execute normally by calling the handler
+            return handler(request)
+
+        # Extract tool information for emulation
+        tool_args = request.tool_call["args"]
+        tool_description = request.tool.description if request.tool else "No description available"
+
+        # Build prompt for emulator LLM
+        prompt = (
+            f"You are emulating a tool call for testing purposes.\n\n"
+            f"Tool: {tool_name}\n"
+            f"Description: {tool_description}\n"
+            f"Arguments: {tool_args}\n\n"
+            f"Generate a realistic response that this tool would return "
+            f"given these arguments.\n"
+            f"Return ONLY the tool's output, no explanation or preamble. "
+            f"Introduce variation into your responses."
+        )
+
+        # Get emulated response from LLM
+        response = self.model.invoke([HumanMessage(prompt)])
+
+        # Short-circuit: return emulated result without executing real tool
+        return ToolMessage(
+            content=response.content,
+            tool_call_id=request.tool_call["id"],
+            name=tool_name,
+        )
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+    ) -> ToolMessage | Command:
+        """Async version of wrap_tool_call.
+
+        Emulate tool execution using LLM if tool should be emulated.
+
+        Args:
+            request: Tool call request to potentially emulate.
+            handler: Async callback to execute the tool (can be called multiple times).
+
+        Returns:
+            ToolMessage with emulated response if tool should be emulated,
+            otherwise calls handler for normal execution.
+        """
+        tool_name = request.tool_call["name"]
+
+        # Check if this tool should be emulated
+        should_emulate = self.emulate_all or tool_name in self.tools_to_emulate
+
+        if not should_emulate:
+            # Let it execute normally by calling the handler
+            return await handler(request)
+
+        # Extract tool information for emulation
+        tool_args = request.tool_call["args"]
+        tool_description = request.tool.description if request.tool else "No description available"
+
+        # Build prompt for emulator LLM
+        prompt = (
+            f"You are emulating a tool call for testing purposes.\n\n"
+            f"Tool: {tool_name}\n"
+            f"Description: {tool_description}\n"
+            f"Arguments: {tool_args}\n\n"
+            f"Generate a realistic response that this tool would return "
+            f"given these arguments.\n"
+            f"Return ONLY the tool's output, no explanation or preamble. "
+            f"Introduce variation into your responses."
+        )
+
+        # Get emulated response from LLM (using async invoke)
+        response = await self.model.ainvoke([HumanMessage(prompt)])
+
+        # Short-circuit: return emulated result without executing real tool
+        return ToolMessage(
+            content=response.content,
+            tool_call_id=request.tool_call["id"],
+            name=tool_name,
+        )

langchain/agents/middleware/tool_retry.py

@@ -0,0 +1,384 @@
+"""Tool retry middleware for agents."""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from typing import TYPE_CHECKING, Literal
+
+from langchain_core.messages import ToolMessage
+
+from langchain.agents.middleware.types import AgentMiddleware
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langgraph.types import Command
+
+    from langchain.agents.middleware.types import ToolCallRequest
+    from langchain.tools import BaseTool
+
+
+class ToolRetryMiddleware(AgentMiddleware):
+    """Middleware that automatically retries failed tool calls with configurable backoff.
+
+    Supports retrying on specific exceptions and exponential backoff.
+
+    Examples:
+        Basic usage with default settings (2 retries, exponential backoff):
+        ```python
+        from langchain.agents import create_agent
+        from langchain.agents.middleware import ToolRetryMiddleware
+
+        agent = create_agent(model, tools=[search_tool], middleware=[ToolRetryMiddleware()])
+        ```
+
+        Retry specific exceptions only:
+        ```python
+        from requests.exceptions import RequestException, Timeout
+
+        retry = ToolRetryMiddleware(
+            max_retries=4,
+            retry_on=(RequestException, Timeout),
+            backoff_factor=1.5,
+        )
+        ```
+
+        Custom exception filtering:
+        ```python
+        from requests.exceptions import HTTPError
+
+
+        def should_retry(exc: Exception) -> bool:
+            # Only retry on 5xx errors
+            if isinstance(exc, HTTPError):
+                return 500 <= exc.status_code < 600
+            return False
+
+
+        retry = ToolRetryMiddleware(
+            max_retries=3,
+            retry_on=should_retry,
+        )
+        ```
+
+        Apply to specific tools with custom error handling:
+        ```python
+        def format_error(exc: Exception) -> str:
+            return "Database temporarily unavailable. Please try again later."
+
+
+        retry = ToolRetryMiddleware(
+            max_retries=4,
+            tools=["search_database"],
+            on_failure=format_error,
+        )
+        ```
+
+        Apply to specific tools using BaseTool instances:
+        ```python
+        from langchain_core.tools import tool
+
+
+        @tool
+        def search_database(query: str) -> str:
+            '''Search the database.'''
+            return results
+
+
+        retry = ToolRetryMiddleware(
+            max_retries=4,
+            tools=[search_database],  # Pass BaseTool instance
+        )
+        ```
+
+        Constant backoff (no exponential growth):
+        ```python
+        retry = ToolRetryMiddleware(
+            max_retries=5,
+            backoff_factor=0.0,  # No exponential growth
+            initial_delay=2.0,  # Always wait 2 seconds
+        )
+        ```
+
+        Raise exception on failure:
+        ```python
+        retry = ToolRetryMiddleware(
+            max_retries=2,
+            on_failure="raise",  # Re-raise exception instead of returning message
+        )
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        max_retries: int = 2,
+        tools: list[BaseTool | str] | None = None,
+        retry_on: tuple[type[Exception], ...] | Callable[[Exception], bool] = (Exception,),
+        on_failure: (
+            Literal["raise", "return_message"] | Callable[[Exception], str]
+        ) = "return_message",
+        backoff_factor: float = 2.0,
+        initial_delay: float = 1.0,
+        max_delay: float = 60.0,
+        jitter: bool = True,
+    ) -> None:
+        """Initialize ToolRetryMiddleware.
+
+        Args:
+            max_retries: Maximum number of retry attempts after the initial call.
+                Default is 2 retries (3 total attempts). Must be >= 0.
+            tools: Optional list of tools or tool names to apply retry logic to.
+                Can be a list of `BaseTool` instances or tool name strings.
+                If `None`, applies to all tools. Default is `None`.
+            retry_on: Either a tuple of exception types to retry on, or a callable
+                that takes an exception and returns `True` if it should be retried.
+                Default is to retry on all exceptions.
+            on_failure: Behavior when all retries are exhausted. Options:
+                - `"return_message"` (default): Return a ToolMessage with error details,
+                  allowing the LLM to handle the failure and potentially recover.
+                - `"raise"`: Re-raise the exception, stopping agent execution.
+                - Custom callable: Function that takes the exception and returns a string
+                  for the ToolMessage content, allowing custom error formatting.
+            backoff_factor: Multiplier for exponential backoff. Each retry waits
+                `initial_delay * (backoff_factor ** retry_number)` seconds.
+                Set to 0.0 for constant delay. Default is 2.0.
+            initial_delay: Initial delay in seconds before first retry. Default is 1.0.
+            max_delay: Maximum delay in seconds between retries. Caps exponential
+                backoff growth. Default is 60.0.
+            jitter: Whether to add random jitter (±25%) to delay to avoid thundering herd.
+                Default is `True`.
+
+        Raises:
+            ValueError: If max_retries < 0 or delays are negative.
+        """
+        super().__init__()
+
+        # Validate parameters
+        if max_retries < 0:
+            msg = "max_retries must be >= 0"
+            raise ValueError(msg)
+        if initial_delay < 0:
+            msg = "initial_delay must be >= 0"
+            raise ValueError(msg)
+        if max_delay < 0:
+            msg = "max_delay must be >= 0"
+            raise ValueError(msg)
+        if backoff_factor < 0:
+            msg = "backoff_factor must be >= 0"
+            raise ValueError(msg)
+
+        self.max_retries = max_retries
+
+        # Extract tool names from BaseTool instances or strings
+        self._tool_filter: list[str] | None
+        if tools is not None:
+            self._tool_filter = [tool.name if not isinstance(tool, str) else tool for tool in tools]
+        else:
+            self._tool_filter = None
+
+        self.tools = []  # No additional tools registered by this middleware
+        self.retry_on = retry_on
+        self.on_failure = on_failure
+        self.backoff_factor = backoff_factor
+        self.initial_delay = initial_delay
+        self.max_delay = max_delay
+        self.jitter = jitter
+
+    def _should_retry_tool(self, tool_name: str) -> bool:
+        """Check if retry logic should apply to this tool.
+
+        Args:
+            tool_name: Name of the tool being called.
+
+        Returns:
+            `True` if retry logic should apply, `False` otherwise.
+        """
+        if self._tool_filter is None:
+            return True
+        return tool_name in self._tool_filter
+
+    def _should_retry_exception(self, exc: Exception) -> bool:
+        """Check if the exception should trigger a retry.
+
+        Args:
+            exc: The exception that occurred.
+
+        Returns:
+            `True` if the exception should be retried, `False` otherwise.
+        """
+        if callable(self.retry_on):
+            return self.retry_on(exc)
+        return isinstance(exc, self.retry_on)
+
+    def _calculate_delay(self, retry_number: int) -> float:
+        """Calculate delay for the given retry attempt.
+
+        Args:
+            retry_number: The retry attempt number (0-indexed).
+
+        Returns:
+            Delay in seconds before next retry.
+        """
+        if self.backoff_factor == 0.0:
+            delay = self.initial_delay
+        else:
+            delay = self.initial_delay * (self.backoff_factor**retry_number)
+
+        # Cap at max_delay
+        delay = min(delay, self.max_delay)
+
+        if self.jitter and delay > 0:
+            jitter_amount = delay * 0.25
+            delay = delay + random.uniform(-jitter_amount, jitter_amount)  # noqa: S311
+            # Ensure delay is not negative after jitter
+            delay = max(0, delay)
+
+        return delay
+
+    def _format_failure_message(self, tool_name: str, exc: Exception, attempts_made: int) -> str:
+        """Format the failure message when retries are exhausted.
+
+        Args:
+            tool_name: Name of the tool that failed.
+            exc: The exception that caused the failure.
+            attempts_made: Number of attempts actually made.
+
+        Returns:
+            Formatted error message string.
+        """
+        exc_type = type(exc).__name__
+        attempt_word = "attempt" if attempts_made == 1 else "attempts"
+        return f"Tool '{tool_name}' failed after {attempts_made} {attempt_word} with {exc_type}"
+
+    def _handle_failure(
+        self, tool_name: str, tool_call_id: str | None, exc: Exception, attempts_made: int
+    ) -> ToolMessage:
+        """Handle failure when all retries are exhausted.
+
+        Args:
+            tool_name: Name of the tool that failed.
+            tool_call_id: ID of the tool call (may be None).
+            exc: The exception that caused the failure.
+            attempts_made: Number of attempts actually made.
+
+        Returns:
+            ToolMessage with error details.
+
+        Raises:
+            Exception: If on_failure is "raise", re-raises the exception.
+        """
+        if self.on_failure == "raise":
+            raise exc
+
+        if callable(self.on_failure):
+            content = self.on_failure(exc)
+        else:
+            content = self._format_failure_message(tool_name, exc, attempts_made)
+
+        return ToolMessage(
+            content=content,
+            tool_call_id=tool_call_id,
+            name=tool_name,
+            status="error",
+        )
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        """Intercept tool execution and retry on failure.
+
+        Args:
+            request: Tool call request with call dict, BaseTool, state, and runtime.
+            handler: Callable to execute the tool (can be called multiple times).
+
+        Returns:
+            ToolMessage or Command (the final result).
+        """
+        tool_name = request.tool.name if request.tool else request.tool_call["name"]
+
+        # Check if retry should apply to this tool
+        if not self._should_retry_tool(tool_name):
+            return handler(request)
+
+        tool_call_id = request.tool_call["id"]
+
+        # Initial attempt + retries
+        for attempt in range(self.max_retries + 1):
+            try:
+                return handler(request)
+            except Exception as exc:  # noqa: BLE001
+                attempts_made = attempt + 1  # attempt is 0-indexed
+
+                # Check if we should retry this exception
+                if not self._should_retry_exception(exc):
+                    # Exception is not retryable, handle failure immediately
+                    return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
+
+                # Check if we have more retries left
+                if attempt < self.max_retries:
+                    # Calculate and apply backoff delay
+                    delay = self._calculate_delay(attempt)
+                    if delay > 0:
+                        time.sleep(delay)
+                    # Continue to next retry
+                else:
+                    # No more retries, handle failure
+                    return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
+
+        # Unreachable: loop always returns via handler success or _handle_failure
+        msg = "Unexpected: retry loop completed without returning"
+        raise RuntimeError(msg)
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+    ) -> ToolMessage | Command:
+        """Intercept and control async tool execution with retry logic.
+
+        Args:
+            request: Tool call request with call dict, BaseTool, state, and runtime.
+            handler: Async callable to execute the tool and returns ToolMessage or Command.
+
+        Returns:
+            ToolMessage or Command (the final result).
+        """
+        tool_name = request.tool.name if request.tool else request.tool_call["name"]
+
+        # Check if retry should apply to this tool
+        if not self._should_retry_tool(tool_name):
+            return await handler(request)
+
+        tool_call_id = request.tool_call["id"]
+
+        # Initial attempt + retries
+        for attempt in range(self.max_retries + 1):
+            try:
+                return await handler(request)
+            except Exception as exc:  # noqa: BLE001
+                attempts_made = attempt + 1  # attempt is 0-indexed
+
+                # Check if we should retry this exception
+                if not self._should_retry_exception(exc):
+                    # Exception is not retryable, handle failure immediately
+                    return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
+
+                # Check if we have more retries left
+                if attempt < self.max_retries:
+                    # Calculate and apply backoff delay
+                    delay = self._calculate_delay(attempt)
+                    if delay > 0:
+                        await asyncio.sleep(delay)
+                    # Continue to next retry
+                else:
+                    # No more retries, handle failure
+                    return self._handle_failure(tool_name, tool_call_id, exc, attempts_made)
+
+        # Unreachable: loop always returns via handler success or _handle_failure
+        msg = "Unexpected: retry loop completed without returning"
+        raise RuntimeError(msg)

langchain/agents/middleware/tool_selection.py

@@ -6,20 +6,24 @@ import logging
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Annotated, Literal, Union
 
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from langchain.tools import BaseTool
+
 from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.messages import HumanMessage
 from pydantic import Field, TypeAdapter
 from typing_extensions import TypedDict
 
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest, StateT
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    ModelCallResult,
+    ModelRequest,
+    ModelResponse,
+)
 from langchain.chat_models.base import init_chat_model
 
-if TYPE_CHECKING:
-    from langgraph.runtime import Runtime
-    from langgraph.typing import ContextT
-
-    from langchain.tools import BaseTool
-
 logger = logging.getLogger(__name__)
 
 DEFAULT_SYSTEM_PROMPT = (
@@ -243,16 +247,15 @@ class LLMToolSelectorMiddleware(AgentMiddleware):
         request.tools = [*selected_tools, *provider_tools]
         return request
 
-    def modify_model_request(
+    def wrap_model_call(
         self,
         request: ModelRequest,
-        state: StateT,  # noqa: ARG002
-        runtime: Runtime[ContextT],  # noqa: ARG002
-    ) -> ModelRequest:
-        """Modify the model request to filter tools based on LLM selection."""
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        """Filter tools based on LLM selection before invoking the model via handler."""
         selection_request = self._prepare_selection_request(request)
         if selection_request is None:
-            return request
+            return handler(request)
 
         # Create dynamic response model with Literal enum of available tool names
         type_adapter = _create_tool_selection_response(selection_request.available_tools)
@@ -270,20 +273,20 @@ class LLMToolSelectorMiddleware(AgentMiddleware):
         if not isinstance(response, dict):
             msg = f"Expected dict response, got {type(response)}"
             raise AssertionError(msg)
-        return self._process_selection_response(
+        modified_request = self._process_selection_response(
             response, selection_request.available_tools, selection_request.valid_tool_names, request
         )
+        return handler(modified_request)
 
-    async def amodify_model_request(
+    async def awrap_model_call(
         self,
         request: ModelRequest,
-        state: AgentState,  # noqa: ARG002
-        runtime: Runtime,  # noqa: ARG002
-    ) -> ModelRequest:
-        """Modify the model request to filter tools based on LLM selection."""
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Filter tools based on LLM selection before invoking the model via handler."""
         selection_request = self._prepare_selection_request(request)
         if selection_request is None:
-            return request
+            return await handler(request)
 
         # Create dynamic response model with Literal enum of available tool names
         type_adapter = _create_tool_selection_response(selection_request.available_tools)
@@ -301,6 +304,7 @@ class LLMToolSelectorMiddleware(AgentMiddleware):
         if not isinstance(response, dict):
             msg = f"Expected dict response, got {type(response)}"
             raise AssertionError(msg)
-        return self._process_selection_response(
+        modified_request = self._process_selection_response(
             response, selection_request.available_tools, selection_request.valid_tool_names, request
         )
+        return await handler(modified_request)