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

langchain/__init__.py

@@ -1,3 +1,3 @@
 """Main entrypoint into LangChain."""
 
-__version__ = "1.0.0a13"
+__version__ = "1.0.0a14"

langchain/agents/factory.py

@@ -13,9 +13,6 @@ from typing import (
     get_type_hints,
 )
 
-if TYPE_CHECKING:
-    from collections.abc import Awaitable
-
 from langchain_core.language_models.chat_models import BaseChatModel
 from langchain_core.messages import AIMessage, AnyMessage, SystemMessage, ToolMessage
 from langchain_core.tools import BaseTool
@@ -47,11 +44,10 @@ from langchain.agents.structured_output import (
     ToolStrategy,
 )
 from langchain.chat_models import init_chat_model
-from langchain.tools import ToolNode
-from langchain.tools.tool_node import ToolCallWithContext
+from langchain.tools.tool_node import ToolCallWithContext, _ToolNode
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Sequence
+    from collections.abc import Awaitable, Callable, Sequence
 
     from langchain_core.runnables import Runnable
     from langgraph.cache.base import BaseCache
@@ -449,6 +445,70 @@ def _chain_tool_call_wrappers(
     return result
 
 
+def _chain_async_tool_call_wrappers(
+    wrappers: Sequence[
+        Callable[
+            [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]],
+            Awaitable[ToolMessage | Command],
+        ]
+    ],
+) -> (
+    Callable[
+        [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]],
+        Awaitable[ToolMessage | Command],
+    ]
+    | None
+):
+    """Compose async wrappers into middleware stack (first = outermost).
+
+    Args:
+        wrappers: Async wrappers in middleware order.
+
+    Returns:
+        Composed async wrapper, or None if empty.
+    """
+    if not wrappers:
+        return None
+
+    if len(wrappers) == 1:
+        return wrappers[0]
+
+    def compose_two(
+        outer: Callable[
+            [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]],
+            Awaitable[ToolMessage | Command],
+        ],
+        inner: Callable[
+            [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]],
+            Awaitable[ToolMessage | Command],
+        ],
+    ) -> Callable[
+        [ToolCallRequest, Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]]],
+        Awaitable[ToolMessage | Command],
+    ]:
+        """Compose two async wrappers where outer wraps inner."""
+
+        async def composed(
+            request: ToolCallRequest,
+            execute: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
+        ) -> ToolMessage | Command:
+            # Create an async callable that invokes inner with the original execute
+            async def call_inner(req: ToolCallRequest) -> ToolMessage | Command:
+                return await inner(req, execute)
+
+            # Outer can call call_inner multiple times
+            return await outer(request, call_inner)
+
+        return composed
+
+    # Chain all wrappers: first -> second -> ... -> last
+    result = wrappers[-1]
+    for wrapper in reversed(wrappers[:-1]):
+        result = compose_two(wrapper, result)
+
+    return result
+
+
 def create_agent(  # noqa: PLR0915
     model: str | BaseChatModel,
     tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
@@ -477,13 +537,12 @@ def create_agent(  # noqa: PLR0915
             (e.g., `"openai:gpt-4"`), a chat model instance (e.g., `ChatOpenAI()`).
         tools: A list of tools, dicts, or callables. If `None` or an empty list,
             the agent will consist of a model node without a tool calling loop.
-        system_prompt: An optional system prompt for the LLM. If provided as a string,
-            it will be converted to a SystemMessage and added to the beginning
-            of the message list.
+        system_prompt: An optional system prompt for the LLM. Prompts are converted to a
+        `SystemMessage` and added to the beginning of the message list.
         middleware: A sequence of middleware instances to apply to the agent.
             Middleware can intercept and modify agent behavior at various stages.
         response_format: An optional configuration for structured responses.
-            Can be a ToolStrategy, ProviderStrategy, or a Pydantic model class.
+            Can be a `ToolStrategy`, `ProviderStrategy`, or a Pydantic model class.
             If provided, the agent will handle structured output during the
             conversation flow. Raw schemas will be wrapped in an appropriate strategy
             based on model capabilities.
@@ -500,14 +559,14 @@ def create_agent(  # noqa: PLR0915
             This is useful if you want to return directly or run additional processing
             on an output.
         debug: A flag indicating whether to enable debug mode.
-        name: An optional name for the CompiledStateGraph.
+        name: An optional name for the `CompiledStateGraph`.
             This name will be automatically used when adding the agent graph to
             another graph as a subgraph node - particularly useful for building
             multi-agent systems.
-        cache: An optional BaseCache instance to enable caching of graph execution.
+        cache: An optional `BaseCache` instance to enable caching of graph execution.
 
     Returns:
-        A compiled StateGraph that can be used for chat interactions.
+        A compiled `StateGraph` that can be used for chat interactions.
 
     The agent node calls the language model with the messages list (after applying
     the system prompt). If the resulting AIMessage contains `tool_calls`, the graph will
@@ -576,9 +635,14 @@ def create_agent(  # noqa: PLR0915
             structured_output_tools[structured_tool_info.tool.name] = structured_tool_info
     middleware_tools = [t for m in middleware for t in getattr(m, "tools", [])]
 
-    # Collect middleware with wrap_tool_call hooks
+    # Collect middleware with wrap_tool_call or awrap_tool_call hooks
+    # Include middleware with either implementation to ensure NotImplementedError is raised
+    # when middleware doesn't support the execution path
     middleware_w_wrap_tool_call = [
-        m for m in middleware if m.__class__.wrap_tool_call is not AgentMiddleware.wrap_tool_call
+        m
+        for m in middleware
+        if m.__class__.wrap_tool_call is not AgentMiddleware.wrap_tool_call
+        or m.__class__.awrap_tool_call is not AgentMiddleware.awrap_tool_call
     ]
 
     # Chain all wrap_tool_call handlers into a single composed handler
@@ -587,8 +651,24 @@ def create_agent(  # noqa: PLR0915
         wrappers = [m.wrap_tool_call for m in middleware_w_wrap_tool_call]
         wrap_tool_call_wrapper = _chain_tool_call_wrappers(wrappers)
 
+    # Collect middleware with awrap_tool_call or wrap_tool_call hooks
+    # Include middleware with either implementation to ensure NotImplementedError is raised
+    # when middleware doesn't support the execution path
+    middleware_w_awrap_tool_call = [
+        m
+        for m in middleware
+        if m.__class__.awrap_tool_call is not AgentMiddleware.awrap_tool_call
+        or m.__class__.wrap_tool_call is not AgentMiddleware.wrap_tool_call
+    ]
+
+    # Chain all awrap_tool_call handlers into a single composed async handler
+    awrap_tool_call_wrapper = None
+    if middleware_w_awrap_tool_call:
+        async_wrappers = [m.awrap_tool_call for m in middleware_w_awrap_tool_call]
+        awrap_tool_call_wrapper = _chain_async_tool_call_wrappers(async_wrappers)
+
     # Setup tools
-    tool_node: ToolNode | None = None
+    tool_node: _ToolNode | None = None
     # Extract built-in provider tools (dict format) and regular tools (BaseTool/callables)
     built_in_tools = [t for t in tools if isinstance(t, dict)]
     regular_tools = [t for t in tools if not isinstance(t, dict)]
@@ -598,7 +678,11 @@ def create_agent(  # noqa: PLR0915
 
     # Only create ToolNode if we have client-side tools
     tool_node = (
-        ToolNode(tools=available_tools, wrap_tool_call=wrap_tool_call_wrapper)
+        _ToolNode(
+            tools=available_tools,
+            wrap_tool_call=wrap_tool_call_wrapper,
+            awrap_tool_call=awrap_tool_call_wrapper,
+        )
         if available_tools
         else None
     )
@@ -640,13 +724,23 @@ def create_agent(  # noqa: PLR0915
         if m.__class__.after_agent is not AgentMiddleware.after_agent
         or m.__class__.aafter_agent is not AgentMiddleware.aafter_agent
     ]
+    # Collect middleware with wrap_model_call or awrap_model_call hooks
+    # Include middleware with either implementation to ensure NotImplementedError is raised
+    # when middleware doesn't support the execution path
     middleware_w_wrap_model_call = [
-        m for m in middleware if m.__class__.wrap_model_call is not AgentMiddleware.wrap_model_call
+        m
+        for m in middleware
+        if m.__class__.wrap_model_call is not AgentMiddleware.wrap_model_call
+        or m.__class__.awrap_model_call is not AgentMiddleware.awrap_model_call
     ]
+    # Collect middleware with awrap_model_call or wrap_model_call hooks
+    # Include middleware with either implementation to ensure NotImplementedError is raised
+    # when middleware doesn't support the execution path
     middleware_w_awrap_model_call = [
         m
         for m in middleware
         if m.__class__.awrap_model_call is not AgentMiddleware.awrap_model_call
+        or m.__class__.wrap_model_call is not AgentMiddleware.wrap_model_call
     ]
 
     # Compose wrap_model_call handlers into a single middleware stack (sync)
@@ -937,11 +1031,7 @@ def create_agent(  # noqa: PLR0915
         if response.structured_response is not None:
             state_updates["structured_response"] = response.structured_response
 
-        return {
-            "thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
-            "run_model_call_count": state.get("run_model_call_count", 0) + 1,
-            **state_updates,
-        }
+        return state_updates
 
     async def _execute_model_async(request: ModelRequest) -> ModelResponse:
         """Execute model asynchronously and return response.
@@ -992,11 +1082,7 @@ def create_agent(  # noqa: PLR0915
         if response.structured_response is not None:
             state_updates["structured_response"] = response.structured_response
 
-        return {
-            "thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
-            "run_model_call_count": state.get("run_model_call_count", 0) + 1,
-            **state_updates,
-        }
+        return state_updates
 
     # Use sync or async based on model capabilities
     graph.add_node("model", RunnableCallable(model_node, amodel_node, trace=False))
@@ -1378,7 +1464,7 @@ def _make_model_to_model_edge(
 
 def _make_tools_to_model_edge(
     *,
-    tool_node: ToolNode,
+    tool_node: _ToolNode,
     model_destination: str,
     structured_output_tools: dict[str, OutputToolBinding],
     end_destination: str,

langchain/agents/middleware/__init__.py

@@ -11,9 +11,8 @@ from .human_in_the_loop import (
 from .model_call_limit import ModelCallLimitMiddleware
 from .model_fallback import ModelFallbackMiddleware
 from .pii import PIIDetectionError, PIIMiddleware
-from .planning import PlanningMiddleware
-from .prompt_caching import AnthropicPromptCachingMiddleware
 from .summarization import SummarizationMiddleware
+from .todo import TodoListMiddleware
 from .tool_call_limit import ToolCallLimitMiddleware
 from .tool_emulator import LLMToolEmulator
 from .tool_selection import LLMToolSelectorMiddleware
@@ -21,6 +20,7 @@ from .types import (
     AgentMiddleware,
     AgentState,
     ModelRequest,
+    ModelResponse,
     after_agent,
     after_model,
     before_agent,
@@ -28,13 +28,12 @@ from .types import (
     dynamic_prompt,
     hook_config,
     wrap_model_call,
+    wrap_tool_call,
 )
 
 __all__ = [
     "AgentMiddleware",
     "AgentState",
-    # should move to langchain-anthropic if we decide to keep it
-    "AnthropicPromptCachingMiddleware",
     "ClearToolUsesEdit",
     "ContextEditingMiddleware",
     "HumanInTheLoopMiddleware",
@@ -44,10 +43,11 @@ __all__ = [
     "ModelCallLimitMiddleware",
     "ModelFallbackMiddleware",
     "ModelRequest",
+    "ModelResponse",
     "PIIDetectionError",
     "PIIMiddleware",
-    "PlanningMiddleware",
     "SummarizationMiddleware",
+    "TodoListMiddleware",
     "ToolCallLimitMiddleware",
     "after_agent",
     "after_model",
@@ -56,4 +56,5 @@ __all__ = [
     "dynamic_prompt",
     "hook_config",
     "wrap_model_call",
+    "wrap_tool_call",
 ]

langchain/agents/middleware/context_editing.py

@@ -8,7 +8,7 @@ with any LangChain chat model.
 
 from __future__ import annotations
 
-from collections.abc import Callable, Iterable, Sequence
+from collections.abc import Awaitable, Callable, Iterable, Sequence
 from dataclasses import dataclass
 from typing import Literal
 
@@ -239,6 +239,34 @@ class ContextEditingMiddleware(AgentMiddleware):
 
         return handler(request)
 
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Apply context edits before invoking the model via handler (async version)."""
+        if not request.messages:
+            return await handler(request)
+
+        if self.token_count_method == "approximate":  # noqa: S105
+
+            def count_tokens(messages: Sequence[BaseMessage]) -> int:
+                return count_tokens_approximately(messages)
+        else:
+            system_msg = (
+                [SystemMessage(content=request.system_prompt)] if request.system_prompt else []
+            )
+
+            def count_tokens(messages: Sequence[BaseMessage]) -> int:
+                return request.model.get_num_tokens_from_messages(
+                    system_msg + list(messages), request.tools
+                )
+
+        for edit in self.edits:
+            edit.apply(request.messages, count_tokens=count_tokens)
+
+        return await handler(request)
+
 
 __all__ = [
     "ClearToolUsesEdit",

langchain/agents/middleware/human_in_the_loop.py

@@ -11,23 +11,23 @@ from langchain.agents.middleware.types import AgentMiddleware, AgentState
 
 
 class Action(TypedDict):
-    """Represents an action with a name and arguments."""
+    """Represents an action with a name and args."""
 
     name: str
     """The type or name of action being requested (e.g., "add_numbers")."""
 
-    arguments: dict[str, Any]
-    """Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2})."""
+    args: dict[str, Any]
+    """Key-value pairs of args needed for the action (e.g., {"a": 1, "b": 2})."""
 
 
 class ActionRequest(TypedDict):
-    """Represents an action request with a name, arguments, and description."""
+    """Represents an action request with a name, args, and description."""
 
     name: str
     """The name of the action being requested."""
 
-    arguments: dict[str, Any]
-    """Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2})."""
+    args: dict[str, Any]
+    """Key-value pairs of args needed for the action (e.g., {"a": 1, "b": 2})."""
 
     description: NotRequired[str]
     """The description of the action to be reviewed."""
@@ -45,8 +45,8 @@ class ReviewConfig(TypedDict):
     allowed_decisions: list[DecisionType]
     """The decisions that are allowed for this request."""
 
-    arguments_schema: NotRequired[dict[str, Any]]
-    """JSON schema for the arguments associated with the action, if edits are allowed."""
+    args_schema: NotRequired[dict[str, Any]]
+    """JSON schema for the args associated with the action, if edits are allowed."""
 
 
 class HITLRequest(TypedDict):
@@ -150,8 +150,8 @@ class InterruptOnConfig(TypedDict):
         )
         ```
     """
-    arguments_schema: NotRequired[dict[str, Any]]
-    """JSON schema for the arguments associated with the action, if edits are allowed."""
+    args_schema: NotRequired[dict[str, Any]]
+    """JSON schema for the args associated with the action, if edits are allowed."""
 
 
 class HumanInTheLoopMiddleware(AgentMiddleware):
@@ -214,12 +214,12 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
         # Create ActionRequest with description
         action_request = ActionRequest(
             name=tool_name,
-            arguments=tool_args,
+            args=tool_args,
             description=description,
         )
 
         # Create ReviewConfig
-        # eventually can get tool information and populate arguments_schema from there
+        # eventually can get tool information and populate args_schema from there
         review_config = ReviewConfig(
             action_name=tool_name,
             allowed_decisions=config["allowed_decisions"],
@@ -244,7 +244,7 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
                 ToolCall(
                     type="tool_call",
                     name=edited_action["name"],
-                    args=edited_action["arguments"],
+                    args=edited_action["args"],
                     id=tool_call["id"],
                 ),
                 None,

langchain/agents/middleware/model_call_limit.py

@@ -2,16 +2,33 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from langchain_core.messages import AIMessage
+from langgraph.channels.untracked_value import UntrackedValue
+from typing_extensions import NotRequired
 
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, hook_config
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    PrivateStateAttr,
+    hook_config,
+)
 
 if TYPE_CHECKING:
     from langgraph.runtime import Runtime
 
 
+class ModelCallLimitState(AgentState):
+    """State schema for ModelCallLimitMiddleware.
+
+    Extends AgentState with model call tracking fields.
+    """
+
+    thread_model_call_count: NotRequired[Annotated[int, PrivateStateAttr]]
+    run_model_call_count: NotRequired[Annotated[int, UntrackedValue, PrivateStateAttr]]
+
+
 def _build_limit_exceeded_message(
     thread_count: int,
     run_count: int,
@@ -69,7 +86,7 @@ class ModelCallLimitExceededError(Exception):
         super().__init__(msg)
 
 
-class ModelCallLimitMiddleware(AgentMiddleware):
+class ModelCallLimitMiddleware(AgentMiddleware[ModelCallLimitState, Any]):
     """Middleware that tracks model call counts and enforces limits.
 
     This middleware monitors the number of model calls made during agent execution
@@ -97,6 +114,8 @@ class ModelCallLimitMiddleware(AgentMiddleware):
         ```
     """
 
+    state_schema = ModelCallLimitState
+
     def __init__(
         self,
         *,
@@ -135,7 +154,7 @@ class ModelCallLimitMiddleware(AgentMiddleware):
         self.exit_behavior = exit_behavior
 
     @hook_config(can_jump_to=["end"])
-    def before_model(self, state: AgentState, runtime: Runtime) -> dict[str, Any] | None:  # noqa: ARG002
+    def before_model(self, state: ModelCallLimitState, runtime: Runtime) -> dict[str, Any] | None:  # noqa: ARG002
         """Check model call limits before making a model call.
 
         Args:
@@ -175,3 +194,18 @@ class ModelCallLimitMiddleware(AgentMiddleware):
                 return {"jump_to": "end", "messages": [limit_ai_message]}
 
         return None
+
+    def after_model(self, state: ModelCallLimitState, runtime: Runtime) -> dict[str, Any] | None:  # noqa: ARG002
+        """Increment model call counts after a model call.
+
+        Args:
+            state: The current agent state.
+            runtime: The langgraph runtime.
+
+        Returns:
+            State updates with incremented call counts.
+        """
+        return {
+            "thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
+            "run_model_call_count": state.get("run_model_call_count", 0) + 1,
+        }

langchain/agents/middleware/model_fallback.py

@@ -13,7 +13,7 @@ from langchain.agents.middleware.types import (
 from langchain.chat_models import init_chat_model
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Awaitable, Callable
 
     from langchain_core.language_models.chat_models import BaseChatModel
 
@@ -102,3 +102,38 @@ class ModelFallbackMiddleware(AgentMiddleware):
                 continue
 
         raise last_exception
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Try fallback models in sequence on errors (async version).
+
+        Args:
+            request: Initial model request.
+            handler: Async callback to execute the model.
+
+        Returns:
+            AIMessage from successful model call.
+
+        Raises:
+            Exception: If all models fail, re-raises last exception.
+        """
+        # Try primary model first
+        last_exception: Exception
+        try:
+            return await 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 await handler(request)
+            except Exception as e:  # noqa: BLE001
+                last_exception = e
+                continue
+
+        raise last_exception

langchain/agents/middleware/pii.py

@@ -431,14 +431,12 @@ class PIIMiddleware(AgentMiddleware):
 
     Strategy Selection Guide:
 
-        ========  ===================  =======================================
-        Strategy  Preserves Identity?  Best For
-        ========  ===================  =======================================
-        `block`   N/A                  Avoid PII completely
-        `redact`  No                   General compliance, log sanitization
-        `mask`    No                   Human readability, customer service UIs
-        `hash`    Yes (pseudonymous)   Analytics, debugging
-        ========  ===================  =======================================
+        | Strategy | Preserves Identity? | Best For                                |
+        | -------- | ------------------- | --------------------------------------- |
+        | `block`  | N/A                 | Avoid PII completely                    |
+        | `redact` | No                  | General compliance, log sanitization    |
+        | `mask`   | No                  | Human readability, customer service UIs |
+        | `hash`   | Yes (pseudonymous)  | Analytics, debugging                    |
 
     Example:
         ```python

langchain/agents/middleware/{planning.py → todo.py}

@@ -6,7 +6,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Annotated, Literal
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Awaitable, Callable
 
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
@@ -126,7 +126,7 @@ def write_todos(todos: list[Todo], tool_call_id: Annotated[str, InjectedToolCall
     )
 
 
-class PlanningMiddleware(AgentMiddleware):
+class TodoListMiddleware(AgentMiddleware):
     """Middleware that provides todo list management capabilities to agents.
 
     This middleware adds a `write_todos` tool that allows agents to create and manage
@@ -139,10 +139,10 @@ class PlanningMiddleware(AgentMiddleware):
 
     Example:
         ```python
-        from langchain.agents.middleware.planning import PlanningMiddleware
+        from langchain.agents.middleware.todo import TodoListMiddleware
         from langchain.agents import create_agent
 
-        agent = create_agent("openai:gpt-4o", middleware=[PlanningMiddleware()])
+        agent = create_agent("openai:gpt-4o", middleware=[TodoListMiddleware()])
 
         # Agent now has access to write_todos tool and todo state tracking
         result = await agent.invoke({"messages": [HumanMessage("Help me refactor my codebase")]})
@@ -165,7 +165,7 @@ class PlanningMiddleware(AgentMiddleware):
         system_prompt: str = WRITE_TODOS_SYSTEM_PROMPT,
         tool_description: str = WRITE_TODOS_TOOL_DESCRIPTION,
     ) -> None:
-        """Initialize the PlanningMiddleware with optional custom prompts.
+        """Initialize the TodoListMiddleware with optional custom prompts.
 
         Args:
             system_prompt: Custom system prompt to guide the agent on using the todo tool.
@@ -204,3 +204,16 @@ class PlanningMiddleware(AgentMiddleware):
             else self.system_prompt
         )
         return handler(request)
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Update the system prompt to include the todo system prompt (async version)."""
+        request.system_prompt = (
+            request.system_prompt + "\n\n" + self.system_prompt
+            if request.system_prompt
+            else self.system_prompt
+        )
+        return await handler(request)