langchain 1.0.0a12__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

langchain/agents/middleware/model_fallback.py

@@ -4,30 +4,34 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    ModelCallResult,
+    ModelRequest,
+    ModelResponse,
+)
 from langchain.chat_models import init_chat_model
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from langchain_core.language_models.chat_models import BaseChatModel
-    from langgraph.runtime import Runtime
 
 
 class ModelFallbackMiddleware(AgentMiddleware):
-    """Middleware that provides automatic model fallback on errors.
+    """Automatic fallback to alternative models on errors.
 
-    This middleware attempts to retry failed model calls with alternative models
-    in sequence. When a model call fails, it tries the next model in the fallback
-    list until either a call succeeds or all models have been exhausted.
+    Retries failed model calls with alternative models in sequence until
+    success or all models exhausted. Primary model specified in create_agent().
 
     Example:
         ```python
         from langchain.agents.middleware.model_fallback import ModelFallbackMiddleware
         from langchain.agents import create_agent
 
-        # Create middleware with fallback models (not including primary)
         fallback = ModelFallbackMiddleware(
-            "openai:gpt-4o-mini",  # First fallback
-            "anthropic:claude-3-5-sonnet-20241022",  # Second fallback
+            "openai:gpt-4o-mini",  # Try first on error
+            "anthropic:claude-3-5-sonnet-20241022",  # Then this
         )
 
         agent = create_agent(
@@ -35,7 +39,7 @@ class ModelFallbackMiddleware(AgentMiddleware):
             middleware=[fallback],
         )
 
-        # If gpt-4o fails, automatically tries gpt-4o-mini, then claude
+        # If primary fails: tries gpt-4o-mini, then claude-3-5-sonnet
         result = await agent.invoke({"messages": [HumanMessage("Hello")]})
         ```
     """
@@ -45,13 +49,11 @@ class ModelFallbackMiddleware(AgentMiddleware):
         first_model: str | BaseChatModel,
         *additional_models: str | BaseChatModel,
     ) -> None:
-        """Initialize the model fallback middleware.
+        """Initialize model fallback middleware.
 
         Args:
-            first_model: The first fallback model to try when the primary model fails.
-                Can be a model name string or BaseChatModel instance.
-            *additional_models: Additional fallback models to try, in order.
-                Can be model name strings or BaseChatModel instances.
+            first_model: First fallback model (string name or instance).
+            *additional_models: Additional fallbacks in order.
         """
         super().__init__()
 
@@ -64,31 +66,39 @@ class ModelFallbackMiddleware(AgentMiddleware):
             else:
                 self.models.append(model)
 
-    def retry_model_request(
+    def wrap_model_call(
         self,
-        error: Exception,  # noqa: ARG002
         request: ModelRequest,
-        state: AgentState,  # noqa: ARG002
-        runtime: Runtime,  # noqa: ARG002
-        attempt: int,
-    ) -> ModelRequest | None:
-        """Retry with the next fallback model.
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        """Try fallback models in sequence on errors.
 
         Args:
-            error: The exception that occurred during model invocation.
-            request: The original model request that failed.
-            state: The current agent state.
-            runtime: The langgraph runtime.
-            attempt: The current attempt number (1-indexed).
+            request: Initial model request.
+            state: Current agent state.
+            runtime: LangGraph runtime.
+            handler: Callback to execute the model.
 
         Returns:
-            ModelRequest with the next fallback model, or None if all models exhausted.
+            AIMessage from successful model call.
+
+        Raises:
+            Exception: If all models fail, re-raises last exception.
         """
-        # attempt 1 = primary model failed, try models[0] (first fallback)
-        fallback_index = attempt - 1
-        # All fallback models exhausted
-        if fallback_index >= len(self.models):
-            return None
-        # Try next fallback model
-        request.model = self.models[fallback_index]
-        return request
+        # Try primary model first
+        last_exception: Exception
+        try:
+            return handler(request)
+        except Exception as e:  # noqa: BLE001
+            last_exception = e
+
+        # Try fallback models
+        for fallback_model in self.models:
+            request.model = fallback_model
+            try:
+                return handler(request)
+            except Exception as e:  # noqa: BLE001
+                last_exception = e
+                continue
+
+        raise last_exception

langchain/agents/middleware/pii.py

@@ -417,17 +417,17 @@ class PIIMiddleware(AgentMiddleware):
     MAC addresses, and URLs in both user input and agent output.
 
     Built-in PII types:
-        - ``email``: Email addresses
-        - ``credit_card``: Credit card numbers (validated with Luhn algorithm)
-        - ``ip``: IP addresses (validated with stdlib)
-        - ``mac_address``: MAC addresses
-        - ``url``: URLs (both http/https and bare URLs)
+        - `email`: Email addresses
+        - `credit_card`: Credit card numbers (validated with Luhn algorithm)
+        - `ip`: IP addresses (validated with stdlib)
+        - `mac_address`: MAC addresses
+        - `url`: URLs (both http/https and bare URLs)
 
     Strategies:
-        - ``block``: Raise an exception when PII is detected
-        - ``redact``: Replace PII with ``[REDACTED_TYPE]`` placeholders
-        - ``mask``: Partially mask PII (e.g., ``****-****-****-1234`` for credit card)
-        - ``hash``: Replace PII with deterministic hash (e.g., ``<email_hash:a1b2c3d4>``)
+        - `block`: Raise an exception when PII is detected
+        - `redact`: Replace PII with `[REDACTED_TYPE]` placeholders
+        - `mask`: Partially mask PII (e.g., `****-****-****-1234` for credit card)
+        - `hash`: Replace PII with deterministic hash (e.g., `<email_hash:a1b2c3d4>`)
 
     Strategy Selection Guide:
 
@@ -487,21 +487,21 @@ class PIIMiddleware(AgentMiddleware):
 
         Args:
             pii_type: Type of PII to detect. Can be a built-in type
-                (``email``, ``credit_card``, ``ip``, ``mac_address``, ``url``)
+                (`email`, `credit_card`, `ip`, `mac_address`, `url`)
                 or a custom type name.
             strategy: How to handle detected PII:
 
-                * ``block``: Raise PIIDetectionError when PII is detected
-                * ``redact``: Replace with ``[REDACTED_TYPE]`` placeholders
-                * ``mask``: Partially mask PII (show last few characters)
-                * ``hash``: Replace with deterministic hash (format: ``<type_hash:digest>``)
+                * `block`: Raise PIIDetectionError when PII is detected
+                * `redact`: Replace with `[REDACTED_TYPE]` placeholders
+                * `mask`: Partially mask PII (show last few characters)
+                * `hash`: Replace with deterministic hash (format: `<type_hash:digest>`)
 
             detector: Custom detector function or regex pattern.
 
-                * If ``Callable``: Function that takes content string and returns
-                  list of PIIMatch objects
-                * If ``str``: Regex pattern to match PII
-                * If ``None``: Uses built-in detector for the pii_type
+                * If `Callable`: Function that takes content string and returns
+                    list of PIIMatch objects
+                * If `str`: Regex pattern to match PII
+                * If `None`: Uses built-in detector for the pii_type
 
             apply_to_input: Whether to check user messages before model call.
             apply_to_output: Whether to check AI messages after model call.
@@ -626,7 +626,7 @@ class PIIMiddleware(AgentMiddleware):
 
         # Check tool results if enabled
         if self.apply_to_tool_results:
-            # Find the last AIMessage, then process all ToolMessages after it
+            # Find the last AIMessage, then process all `ToolMessage` objects after it
             last_ai_idx = None
             for i in range(len(messages) - 1, -1, -1):
                 if isinstance(messages[i], AIMessage):

langchain/agents/middleware/planning.py

@@ -5,17 +5,23 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Annotated, Literal
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
 from langgraph.types import Command
 from typing_extensions import NotRequired, TypedDict
 
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ModelCallResult,
+    ModelRequest,
+    ModelResponse,
+)
 from langchain.tools import InjectedToolCallId
 
-if TYPE_CHECKING:
-    from langgraph.runtime import Runtime
-
 
 class Todo(TypedDict):
     """A single todo item with content and status."""
@@ -146,9 +152,9 @@ class PlanningMiddleware(AgentMiddleware):
 
     Args:
         system_prompt: Custom system prompt to guide the agent on using the todo tool.
-            If not provided, uses the default ``WRITE_TODOS_SYSTEM_PROMPT``.
+            If not provided, uses the default `WRITE_TODOS_SYSTEM_PROMPT`.
         tool_description: Custom description for the write_todos tool.
-            If not provided, uses the default ``WRITE_TODOS_TOOL_DESCRIPTION``.
+            If not provided, uses the default `WRITE_TODOS_TOOL_DESCRIPTION`.
     """
 
     state_schema = PlanningState
@@ -186,16 +192,15 @@ class PlanningMiddleware(AgentMiddleware):
 
         self.tools = [write_todos]
 
-    def modify_model_request(
+    def wrap_model_call(
         self,
         request: ModelRequest,
-        state: AgentState,  # noqa: ARG002
-        runtime: Runtime,  # noqa: ARG002
-    ) -> ModelRequest:
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
         """Update the system prompt to include the todo system prompt."""
         request.system_prompt = (
             request.system_prompt + "\n\n" + self.system_prompt
             if request.system_prompt
             else self.system_prompt
         )
-        return request
+        return handler(request)

langchain/agents/middleware/prompt_caching.py

@@ -1,11 +1,15 @@
 """Anthropic prompt caching middleware."""
 
+from collections.abc import Callable
 from typing import Literal
 from warnings import warn
 
-from langgraph.runtime import Runtime
-
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    ModelCallResult,
+    ModelRequest,
+    ModelResponse,
+)
 
 
 class AnthropicPromptCachingMiddleware(AgentMiddleware):
@@ -14,7 +18,7 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
     Optimizes API usage by caching conversation prefixes for Anthropic models.
 
     Learn more about Anthropic prompt caching
-    `here <https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching>`__.
+    [here](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching).
     """
 
     def __init__(
@@ -41,12 +45,11 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
         self.min_messages_to_cache = min_messages_to_cache
         self.unsupported_model_behavior = unsupported_model_behavior
 
-    def modify_model_request(
+    def wrap_model_call(
         self,
         request: ModelRequest,
-        state: AgentState,  # noqa: ARG002
-        runtime: Runtime,  # noqa: ARG002
-    ) -> ModelRequest:
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
         """Modify the model request to add cache control blocks."""
         try:
             from langchain_anthropic import ChatAnthropic
@@ -73,14 +76,14 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
             if self.unsupported_model_behavior == "warn":
                 warn(msg, stacklevel=3)
             else:
-                return request
+                return handler(request)
 
         messages_count = (
             len(request.messages) + 1 if request.system_prompt else len(request.messages)
         )
         if messages_count < self.min_messages_to_cache:
-            return request
+            return handler(request)
 
         request.model_settings["cache_control"] = {"type": self.type, "ttl": self.ttl}
 
-        return request
+        return handler(request)

langchain/agents/middleware/summarization.py

@@ -81,7 +81,7 @@ class SummarizationMiddleware(AgentMiddleware):
         Args:
             model: The language model to use for generating summaries.
             max_tokens_before_summary: Token threshold to trigger summarization.
-                If None, summarization is disabled.
+                If `None`, summarization is disabled.
             messages_to_keep: Number of recent messages to preserve after summarization.
             token_counter: Function to count tokens in messages.
             summary_prompt: Prompt template for generating summaries.

langchain/agents/middleware/tool_call_limit.py

@@ -18,7 +18,7 @@ def _count_tool_calls_in_messages(messages: list[AnyMessage], tool_name: str | N
     Args:
         messages: List of messages to count tool calls in.
         tool_name: If specified, only count calls to this specific tool.
-            If None, count all tool calls.
+            If `None`, count all tool calls.
 
     Returns:
         The total number of tool calls (optionally filtered by tool_name).
@@ -168,12 +168,12 @@ class ToolCallLimitMiddleware(AgentMiddleware):
         """Initialize the tool call limit middleware.
 
         Args:
-            tool_name: Name of the specific tool to limit. If None, limits apply
-                to all tools. Defaults to None.
+            tool_name: Name of the specific tool to limit. If `None`, limits apply
+                to all tools. Defaults to `None`.
             thread_limit: Maximum number of tool calls allowed per thread.
-                None means no limit. Defaults to None.
+                None means no limit. Defaults to `None`.
             run_limit: Maximum number of tool calls allowed per run.
-                None means no limit. Defaults to None.
+                None means no limit. Defaults to `None`.
             exit_behavior: What to do when limits are exceeded.
                 - "end": Jump to the end of the agent execution and
                     inject an artificial AI message indicating that the limit was exceeded.

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.tools import BaseTool
+    from langchain.tools.tool_node import ToolCallRequest
+
+
+class LLMToolEmulator(AgentMiddleware):
+    """Middleware that 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-3-5-sonnet-latest"
+        )
+        ```
+
+        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-3-5-sonnet-latest".
+                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-3-5-sonnet-latest", 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
+
+        # 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
+
+        # 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_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)