langchain 1.0.5__py3-none-any.whl → 1.2.4__py3-none-any.whl

langchain/agents/middleware/tool_emulator.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.messages import HumanMessage, ToolMessage
@@ -23,39 +23,44 @@ 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.
+
+    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
+        !!! example "Emulate all tools (default behavior)"
 
-        middleware = LLMToolEmulator()
+            ```python
+            from langchain.agents.middleware import LLMToolEmulator
 
-        agent = create_agent(
-            model="openai:gpt-4o",
-            tools=[get_weather, get_user_location, calculator],
-            middleware=[middleware],
-        )
-        ```
+            middleware = LLMToolEmulator()
 
-        Emulate specific tools by name:
-        ```python
-        middleware = LLMToolEmulator(tools=["get_weather", "get_user_location"])
-        ```
+            agent = create_agent(
+                model="openai:gpt-4o",
+                tools=[get_weather, get_user_location, calculator],
+                middleware=[middleware],
+            )
+            ```
 
-        Use a custom model for emulation:
-        ```python
-        middleware = LLMToolEmulator(
-            tools=["get_weather"], model="anthropic:claude-sonnet-4-5-20250929"
-        )
-        ```
+        !!! example "Emulate specific tools by name"
+
+            ```python
+            middleware = LLMToolEmulator(tools=["get_weather", "get_user_location"])
+            ```
+
+        !!! example "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])
-        ```
+        !!! example "Emulate specific tools by passing tool instances"
+
+            ```python
+            middleware = LLMToolEmulator(tools=[get_weather, get_user_location])
+            ```
     """
 
     def __init__(
@@ -67,12 +72,16 @@ class LLMToolEmulator(AgentMiddleware):
         """Initialize the tool emulator.
 
         Args:
-            tools: List of tool names (str) or BaseTool instances to emulate.
-                If None (default), ALL tools will be emulated.
+            tools: List of tool names (`str`) or `BaseTool` instances to emulate.
+
+                If `None`, 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.
+
+                Defaults to `'anthropic:claude-sonnet-4-5-20250929'`.
+
+                Can be a model identifier string or `BaseChatModel` instance.
         """
         super().__init__()
 
@@ -100,8 +109,8 @@ class LLMToolEmulator(AgentMiddleware):
     def wrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
         """Emulate tool execution using LLM if tool should be emulated.
 
         Args:
@@ -110,7 +119,7 @@ class LLMToolEmulator(AgentMiddleware):
 
         Returns:
             ToolMessage with emulated response if tool should be emulated,
-            otherwise calls handler for normal execution.
+                otherwise calls handler for normal execution.
         """
         tool_name = request.tool_call["name"]
 
@@ -150,9 +159,9 @@ class LLMToolEmulator(AgentMiddleware):
     async def awrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
-        """Async version of wrap_tool_call.
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+    ) -> ToolMessage | Command[Any]:
+        """Async version of `wrap_tool_call`.
 
         Emulate tool execution using LLM if tool should be emulated.
 
@@ -162,7 +171,7 @@ class LLMToolEmulator(AgentMiddleware):
 
         Returns:
             ToolMessage with emulated response if tool should be emulated,
-            otherwise calls handler for normal execution.
+                otherwise calls handler for normal execution.
         """
         tool_name = request.tool_call["name"]
 

langchain/agents/middleware/tool_retry.py

@@ -3,12 +3,19 @@
 from __future__ import annotations
 
 import asyncio
-import random
 import time
-from typing import TYPE_CHECKING, Literal
+import warnings
+from typing import TYPE_CHECKING, Any
 
 from langchain_core.messages import ToolMessage
 
+from langchain.agents.middleware._retry import (
+    OnFailure,
+    RetryOn,
+    calculate_delay,
+    should_retry_exception,
+    validate_retry_params,
+)
 from langchain.agents.middleware.types import AgentMiddleware
 
 if TYPE_CHECKING:
@@ -26,89 +33,96 @@ class ToolRetryMiddleware(AgentMiddleware):
     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,
-        )
-        ```
+        !!! example "Basic usage with default settings (2 retries, exponential backoff)"
 
-        Custom exception filtering:
-        ```python
-        from requests.exceptions import HTTPError
+            ```python
+            from langchain.agents import create_agent
+            from langchain.agents.middleware import ToolRetryMiddleware
 
+            agent = create_agent(model, tools=[search_tool], middleware=[ToolRetryMiddleware()])
+            ```
 
-        def should_retry(exc: Exception) -> bool:
-            # Only retry on 5xx errors
-            if isinstance(exc, HTTPError):
-                return 500 <= exc.status_code < 600
-            return False
+        !!! example "Retry specific exceptions only"
 
+            ```python
+            from requests.exceptions import RequestException, Timeout
 
-        retry = ToolRetryMiddleware(
-            max_retries=3,
-            retry_on=should_retry,
-        )
-        ```
+            retry = ToolRetryMiddleware(
+                max_retries=4,
+                retry_on=(RequestException, Timeout),
+                backoff_factor=1.5,
+            )
+            ```
 
-        Apply to specific tools with custom error handling:
-        ```python
-        def format_error(exc: Exception) -> str:
-            return "Database temporarily unavailable. Please try again later."
+        !!! example "Custom exception filtering"
 
+            ```python
+            from requests.exceptions import HTTPError
 
-        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
+            def should_retry(exc: Exception) -> bool:
+                # Only retry on 5xx errors
+                if isinstance(exc, HTTPError):
+                    return 500 <= exc.status_code < 600
+                return False
 
 
-        @tool
-        def search_database(query: str) -> str:
-            '''Search the database.'''
-            return results
+            retry = ToolRetryMiddleware(
+                max_retries=3,
+                retry_on=should_retry,
+            )
+            ```
 
+        !!! example "Apply to specific tools with custom error handling"
 
-        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
-        )
-        ```
+            ```python
+            def format_error(exc: Exception) -> str:
+                return "Database temporarily unavailable. Please try again later."
 
-        Raise exception on failure:
-        ```python
-        retry = ToolRetryMiddleware(
-            max_retries=2,
-            on_failure="raise",  # Re-raise exception instead of returning message
-        )
-        ```
+
+            retry = ToolRetryMiddleware(
+                max_retries=4,
+                tools=["search_database"],
+                on_failure=format_error,
+            )
+            ```
+
+        !!! example "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
+            )
+            ```
+
+        !!! example "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
+            )
+            ```
+
+        !!! example "Raise exception on failure"
+
+            ```python
+            retry = ToolRetryMiddleware(
+                max_retries=2,
+                on_failure="error",  # Re-raise exception instead of returning message
+            )
+            ```
     """
 
     def __init__(
@@ -116,59 +130,78 @@ class ToolRetryMiddleware(AgentMiddleware):
         *,
         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",
+        retry_on: RetryOn = (Exception,),
+        on_failure: OnFailure = "continue",
         backoff_factor: float = 2.0,
         initial_delay: float = 1.0,
         max_delay: float = 60.0,
         jitter: bool = True,
     ) -> None:
-        """Initialize ToolRetryMiddleware.
+        """Initialize `ToolRetryMiddleware`.
 
         Args:
             max_retries: Maximum number of retry attempts after the initial call.
-                Default is 2 retries (3 total attempts). Must be >= 0.
+
+                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`.
+
+                If `None`, applies to all tools.
             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`.
+            on_failure: Behavior when all retries are exhausted.
+
+                Options:
+
+                - `'continue'`: Return a `ToolMessage` with error details,
+                    allowing the LLM to handle the failure and potentially recover.
+                - `'error'`: 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.
+
+                **Deprecated values** (for backwards compatibility):
+
+                - `'return_message'`: Use `'continue'` instead.
+                - `'raise'`: Use `'error'` instead.
+            backoff_factor: Multiplier for exponential backoff.
+
+                Each retry waits `initial_delay * (backoff_factor ** retry_number)`
+                seconds.
+
+                Set to `0.0` for constant delay.
+            initial_delay: Initial delay in seconds before first retry.
+            max_delay: Maximum delay in seconds between retries.
+
+                Caps exponential backoff growth.
+            jitter: Whether to add random jitter (`±25%`) to delay to avoid thundering herd.
 
         Raises:
-            ValueError: If max_retries < 0 or delays are negative.
+            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)
+        validate_retry_params(max_retries, initial_delay, max_delay, backoff_factor)
+
+        # Handle backwards compatibility for deprecated on_failure values
+        if on_failure == "raise":  # type: ignore[comparison-overlap]
+            msg = (  # type: ignore[unreachable]
+                "on_failure='raise' is deprecated and will be removed in a future version. "
+                "Use on_failure='error' instead."
+            )
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
+            on_failure = "error"
+        elif on_failure == "return_message":  # type: ignore[comparison-overlap]
+            msg = (  # type: ignore[unreachable]
+                "on_failure='return_message' is deprecated and will be removed "
+                "in a future version. Use on_failure='continue' instead."
+            )
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
+            on_failure = "continue"
 
         self.max_retries = max_retries
 
@@ -200,45 +233,8 @@ class ToolRetryMiddleware(AgentMiddleware):
             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:
+    @staticmethod
+    def _format_failure_message(tool_name: str, exc: Exception, attempts_made: int) -> str:
         """Format the failure message when retries are exhausted.
 
         Args:
@@ -250,8 +246,12 @@ class ToolRetryMiddleware(AgentMiddleware):
             Formatted error message string.
         """
         exc_type = type(exc).__name__
+        exc_msg = str(exc)
         attempt_word = "attempt" if attempts_made == 1 else "attempts"
-        return f"Tool '{tool_name}' failed after {attempts_made} {attempt_word} with {exc_type}"
+        return (
+            f"Tool '{tool_name}' failed after {attempts_made} {attempt_word} "
+            f"with {exc_type}: {exc_msg}. Please try again."
+        )
 
     def _handle_failure(
         self, tool_name: str, tool_call_id: str | None, exc: Exception, attempts_made: int
@@ -260,17 +260,17 @@ class ToolRetryMiddleware(AgentMiddleware):
 
         Args:
             tool_name: Name of the tool that failed.
-            tool_call_id: ID of the tool call (may be None).
+            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.
+            `ToolMessage` with error details.
 
         Raises:
-            Exception: If on_failure is "raise", re-raises the exception.
+            Exception: If `on_failure` is `'error'`, re-raises the exception.
         """
-        if self.on_failure == "raise":
+        if self.on_failure == "error":
             raise exc
 
         if callable(self.on_failure):
@@ -288,16 +288,19 @@ class ToolRetryMiddleware(AgentMiddleware):
     def wrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], ToolMessage | Command],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
+    ) -> ToolMessage | Command[Any]:
         """Intercept tool execution and retry on failure.
 
         Args:
-            request: Tool call request with call dict, BaseTool, state, and runtime.
+            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).
+            `ToolMessage` or `Command` (the final result).
+
+        Raises:
+            RuntimeError: If the retry loop completes without returning. This should not happen.
         """
         tool_name = request.tool.name if request.tool else request.tool_call["name"]
 
@@ -311,18 +314,24 @@ class ToolRetryMiddleware(AgentMiddleware):
         for attempt in range(self.max_retries + 1):
             try:
                 return handler(request)
-            except Exception as exc:  # noqa: BLE001
+            except Exception as exc:
                 attempts_made = attempt + 1  # attempt is 0-indexed
 
                 # Check if we should retry this exception
-                if not self._should_retry_exception(exc):
+                if not should_retry_exception(exc, self.retry_on):
                     # 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)
+                    delay = calculate_delay(
+                        attempt,
+                        backoff_factor=self.backoff_factor,
+                        initial_delay=self.initial_delay,
+                        max_delay=self.max_delay,
+                        jitter=self.jitter,
+                    )
                     if delay > 0:
                         time.sleep(delay)
                     # Continue to next retry
@@ -337,16 +346,20 @@ class ToolRetryMiddleware(AgentMiddleware):
     async def awrap_tool_call(
         self,
         request: ToolCallRequest,
-        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
-    ) -> ToolMessage | Command:
+        handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
+    ) -> ToolMessage | Command[Any]:
         """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.
+            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).
+            `ToolMessage` or `Command` (the final result).
+
+        Raises:
+            RuntimeError: If the retry loop completes without returning. This should not happen.
         """
         tool_name = request.tool.name if request.tool else request.tool_call["name"]
 
@@ -360,18 +373,24 @@ class ToolRetryMiddleware(AgentMiddleware):
         for attempt in range(self.max_retries + 1):
             try:
                 return await handler(request)
-            except Exception as exc:  # noqa: BLE001
+            except Exception as exc:
                 attempts_made = attempt + 1  # attempt is 0-indexed
 
                 # Check if we should retry this exception
-                if not self._should_retry_exception(exc):
+                if not should_retry_exception(exc, self.retry_on):
                     # 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)
+                    delay = calculate_delay(
+                        attempt,
+                        backoff_factor=self.backoff_factor,
+                        initial_delay=self.initial_delay,
+                        max_delay=self.max_delay,
+                        jitter=self.jitter,
+                    )
                     if delay > 0:
                         await asyncio.sleep(delay)
                     # Continue to next retry