langchain 1.0.0a4__py3-none-any.whl → 1.0.0a6__py3-none-any.whl

langchain/__init__.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-__version__ = "1.0.0a3"
+__version__ = "1.0.0a4"
 
 
 def __getattr__(name: str) -> Any:  # noqa: ANN401

langchain/_internal/_lazy_import.py

@@ -1,13 +1,12 @@
 """Lazy import utilities."""
 
 from importlib import import_module
-from typing import Union
 
 
 def import_attr(
     attr_name: str,
-    module_name: Union[str, None],
-    package: Union[str, None],
+    module_name: str | None,
+    package: str | None,
 ) -> object:
     """Import an attribute from a module located in a package.
 

langchain/_internal/_prompts.py

@@ -12,7 +12,7 @@ particularly for summarization chains and other document processing workflows.
 from __future__ import annotations
 
 import inspect
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from collections.abc import Awaitable, Callable
@@ -24,11 +24,7 @@ if TYPE_CHECKING:
 
 
 def resolve_prompt(
-    prompt: Union[
-        str,
-        None,
-        Callable[[StateT, Runtime[ContextT]], list[MessageLikeRepresentation]],
-    ],
+    prompt: str | None | Callable[[StateT, Runtime[ContextT]], list[MessageLikeRepresentation]],
     state: StateT,
     runtime: Runtime[ContextT],
     default_user_content: str,
@@ -61,6 +57,7 @@ def resolve_prompt(
         def custom_prompt(state, runtime):
             return [{"role": "system", "content": "Custom"}]
 
+
         messages = resolve_prompt(custom_prompt, state, runtime, "content", "default")
         messages = resolve_prompt("Custom system", state, runtime, "content", "default")
         messages = resolve_prompt(None, state, runtime, "content", "Default")
@@ -88,12 +85,10 @@ def resolve_prompt(
 
 
 async def aresolve_prompt(
-    prompt: Union[
-        str,
-        None,
-        Callable[[StateT, Runtime[ContextT]], list[MessageLikeRepresentation]],
-        Callable[[StateT, Runtime[ContextT]], Awaitable[list[MessageLikeRepresentation]]],
-    ],
+    prompt: str
+    | None
+    | Callable[[StateT, Runtime[ContextT]], list[MessageLikeRepresentation]]
+    | Callable[[StateT, Runtime[ContextT]], Awaitable[list[MessageLikeRepresentation]]],
     state: StateT,
     runtime: Runtime[ContextT],
     default_user_content: str,
@@ -128,15 +123,13 @@ async def aresolve_prompt(
         async def async_prompt(state, runtime):
             return [{"role": "system", "content": "Async"}]
 
+
         def sync_prompt(state, runtime):
             return [{"role": "system", "content": "Sync"}]
 
-        messages = await aresolve_prompt(
-            async_prompt, state, runtime, "content", "default"
-        )
-        messages = await aresolve_prompt(
-            sync_prompt, state, runtime, "content", "default"
-        )
+
+        messages = await aresolve_prompt(async_prompt, state, runtime, "content", "default")
+        messages = await aresolve_prompt(sync_prompt, state, runtime, "content", "default")
         messages = await aresolve_prompt("Custom", state, runtime, "content", "default")
         ```
 

langchain/_internal/_typing.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeAlias, TypeVar, Union
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol, TypeAlias, TypeVar
 
 from langgraph.graph._node import StateNode
 from pydantic import BaseModel
@@ -44,7 +44,7 @@ class DataclassLike(Protocol):
     __dataclass_fields__: ClassVar[dict[str, Field[Any]]]
 
 
-StateLike: TypeAlias = Union[TypedDictLikeV1, TypedDictLikeV2, DataclassLike, BaseModel]
+StateLike: TypeAlias = TypedDictLikeV1 | TypedDictLikeV2 | DataclassLike | BaseModel
 """Type alias for state-like types.
 
 It can either be a ``TypedDict``, ``dataclass``, or Pydantic ``BaseModel``.
@@ -58,7 +58,7 @@ It can either be a ``TypedDict``, ``dataclass``, or Pydantic ``BaseModel``.
 StateT = TypeVar("StateT", bound=StateLike)
 """Type variable used to represent the state in a graph."""
 
-ContextT = TypeVar("ContextT", bound=Union[StateLike, None])
+ContextT = TypeVar("ContextT", bound=StateLike | None)
 """Type variable for context types."""
 
 

langchain/agents/_internal/_typing.py

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable
-from typing import TypeVar, Union
+from typing import TypeVar
 
 from typing_extensions import ParamSpec
 
 P = ParamSpec("P")
 R = TypeVar("R")
 
-SyncOrAsync = Callable[P, Union[R, Awaitable[R]]]
+SyncOrAsync = Callable[P, R | Awaitable[R]]

langchain/agents/middleware/__init__.py

@@ -1,5 +1,6 @@
 """Middleware plugins for agents."""
 
+from .dynamic_system_prompt import DynamicSystemPromptMiddleware
 from .human_in_the_loop import HumanInTheLoopMiddleware
 from .prompt_caching import AnthropicPromptCachingMiddleware
 from .summarization import SummarizationMiddleware
@@ -8,7 +9,9 @@ from .types import AgentMiddleware, AgentState, ModelRequest
 __all__ = [
     "AgentMiddleware",
     "AgentState",
+    # should move to langchain-anthropic if we decide to keep it
     "AnthropicPromptCachingMiddleware",
+    "DynamicSystemPromptMiddleware",
     "HumanInTheLoopMiddleware",
     "ModelRequest",
     "SummarizationMiddleware",

langchain/agents/middleware/dynamic_system_prompt.py

@@ -0,0 +1,105 @@
+"""Dynamic System Prompt Middleware.
+
+Allows setting the system prompt dynamically right before each model invocation.
+Useful when the prompt depends on the current agent state or per-invocation context.
+"""
+
+from __future__ import annotations
+
+from inspect import signature
+from typing import TYPE_CHECKING, Protocol, TypeAlias, cast
+
+from langgraph.typing import ContextT
+
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ModelRequest,
+)
+
+if TYPE_CHECKING:
+    from langgraph.runtime import Runtime
+
+
+class DynamicSystemPromptWithoutRuntime(Protocol):
+    """Dynamic system prompt without runtime in call signature."""
+
+    def __call__(self, state: AgentState) -> str:
+        """Return the system prompt for the next model call."""
+        ...
+
+
+class DynamicSystemPromptWithRuntime(Protocol[ContextT]):
+    """Dynamic system prompt with runtime in call signature."""
+
+    def __call__(self, state: AgentState, runtime: Runtime[ContextT]) -> str:
+        """Return the system prompt for the next model call."""
+        ...
+
+
+DynamicSystemPrompt: TypeAlias = (
+    DynamicSystemPromptWithoutRuntime | DynamicSystemPromptWithRuntime[ContextT]
+)
+
+
+class DynamicSystemPromptMiddleware(AgentMiddleware):
+    """Dynamic System Prompt Middleware.
+
+    Allows setting the system prompt dynamically right before each model invocation.
+    Useful when the prompt depends on the current agent state or per-invocation context.
+
+    Example:
+        ```python
+        from langchain.agents.middleware import DynamicSystemPromptMiddleware
+
+
+        class Context(TypedDict):
+            user_name: str
+
+
+        def system_prompt(state: AgentState, runtime: Runtime[Context]) -> str:
+            user_name = runtime.context.get("user_name", "n/a")
+            return (
+                f"You are a helpful assistant. Always address the user by their name: {user_name}"
+            )
+
+
+        middleware = DynamicSystemPromptMiddleware(system_prompt)
+        ```
+    """
+
+    _accepts_runtime: bool
+
+    def __init__(
+        self,
+        dynamic_system_prompt: DynamicSystemPrompt[ContextT],
+    ) -> None:
+        """Initialize the dynamic system prompt middleware.
+
+        Args:
+            dynamic_system_prompt: Function that receives the current agent state
+                and optionally runtime with context, and returns the system prompt for
+                the next model call. Returns a string.
+        """
+        super().__init__()
+        self.dynamic_system_prompt = dynamic_system_prompt
+        self._accepts_runtime = "runtime" in signature(dynamic_system_prompt).parameters
+
+    def modify_model_request(
+        self,
+        request: ModelRequest,
+        state: AgentState,
+        runtime: Runtime[ContextT],
+    ) -> ModelRequest:
+        """Modify the model request to include the dynamic system prompt."""
+        if self._accepts_runtime:
+            system_prompt = cast(
+                "DynamicSystemPromptWithRuntime[ContextT]", self.dynamic_system_prompt
+            )(state, runtime)
+        else:
+            system_prompt = cast("DynamicSystemPromptWithoutRuntime", self.dynamic_system_prompt)(
+                state
+            )
+
+        request.system_prompt = system_prompt
+        return request

langchain/agents/middleware/human_in_the_loop.py

@@ -1,19 +1,110 @@
 """Human in the loop middleware."""
 
-from typing import Any
-
-from langgraph.prebuilt.interrupt import (
-    ActionRequest,
-    HumanInterrupt,
-    HumanInterruptConfig,
-    HumanResponse,
-)
+from typing import Any, Literal
+
+from langchain_core.messages import AIMessage, ToolCall, ToolMessage
 from langgraph.types import interrupt
+from typing_extensions import NotRequired, TypedDict
 
-from langchain.agents.middleware._utils import _generate_correction_tool_messages
 from langchain.agents.middleware.types import AgentMiddleware, AgentState
 
-ToolInterruptConfig = dict[str, HumanInterruptConfig]
+
+class HumanInTheLoopConfig(TypedDict):
+    """Configuration that defines what actions are allowed for a human interrupt.
+
+    This controls the available interaction options when the graph is paused for human input.
+    """
+
+    allow_accept: NotRequired[bool]
+    """Whether the human can approve the current action without changes."""
+    allow_edit: NotRequired[bool]
+    """Whether the human can approve the current action with edited content."""
+    allow_respond: NotRequired[bool]
+    """Whether the human can reject the current action with feedback."""
+
+
+class ActionRequest(TypedDict):
+    """Represents a request with a name and arguments."""
+
+    action: str
+    """The type or name of action being requested (e.g., "add_numbers")."""
+    args: dict
+    """Key-value pairs of arguments needed for the action (e.g., {"a": 1, "b": 2})."""
+
+
+class HumanInTheLoopRequest(TypedDict):
+    """Represents an interrupt triggered by the graph that requires human intervention.
+
+    Example:
+        ```python
+        # Extract a tool call from the state and create an interrupt request
+        request = HumanInterrupt(
+            action_request=ActionRequest(
+                action="run_command",  # The action being requested
+                args={"command": "ls", "args": ["-l"]},  # Arguments for the action
+            ),
+            config=HumanInTheLoopConfig(
+                allow_accept=True,  # Allow approval
+                allow_respond=True,  # Allow rejection with feedback
+                allow_edit=False,  # Don't allow approval with edits
+            ),
+            description="Please review the command before execution",
+        )
+        # Send the interrupt request and get the response
+        response = interrupt([request])[0]
+        ```
+    """
+
+    action_request: ActionRequest
+    """The specific action being requested from the human."""
+    config: HumanInTheLoopConfig
+    """Configuration defining what response types are allowed."""
+    description: str | None
+    """Optional detailed description of what input is needed."""
+
+
+class AcceptPayload(TypedDict):
+    """Response when a human approves the action."""
+
+    type: Literal["accept"]
+    """The type of response when a human approves the action."""
+
+
+class ResponsePayload(TypedDict):
+    """Response when a human rejects the action."""
+
+    type: Literal["response"]
+    """The type of response when a human rejects the action."""
+
+    args: NotRequired[str]
+    """The message to be sent to the model explaining why the action was rejected."""
+
+
+class EditPayload(TypedDict):
+    """Response when a human edits the action."""
+
+    type: Literal["edit"]
+    """The type of response when a human edits the action."""
+
+    args: ActionRequest
+    """The action request with the edited content."""
+
+
+HumanInTheLoopResponse = AcceptPayload | ResponsePayload | EditPayload
+"""Aggregated response type for all possible human in the loop responses."""
+
+
+class ToolConfig(TypedDict):
+    """Configuration for a tool requiring human in the loop."""
+
+    allow_accept: NotRequired[bool]
+    """Whether the human can approve the current action without changes."""
+    allow_edit: NotRequired[bool]
+    """Whether the human can approve the current action with edited content."""
+    allow_respond: NotRequired[bool]
+    """Whether the human can reject the current action with feedback."""
+    description: NotRequired[str]
+    """The description attached to the request for human input."""
 
 
 class HumanInTheLoopMiddleware(AgentMiddleware):
@@ -21,108 +112,142 @@ class HumanInTheLoopMiddleware(AgentMiddleware):
 
     def __init__(
         self,
-        tool_configs: ToolInterruptConfig,
-        message_prefix: str = "Tool execution requires approval",
+        tool_configs: dict[str, bool | ToolConfig],
+        *,
+        description_prefix: str = "Tool execution requires approval",
     ) -> None:
         """Initialize the human in the loop middleware.
 
         Args:
-            tool_configs: The tool interrupt configs to use for the middleware.
-            message_prefix: The message prefix to use when constructing interrupt content.
+            tool_configs: Mapping of tool name to allowed actions.
+                If a tool doesn't have an entry, it's auto-approved by default.
+                * `True` indicates all actions are allowed: accept, edit, and respond.
+                * `False` indicates that the tool is auto-approved.
+                * ToolConfig indicates the specific actions allowed for this tool.
+            description_prefix: The prefix to use when constructing action requests.
+                This is used to provide context about the tool call and the action being requested.
+                Not used if a tool has a description in its ToolConfig.
         """
         super().__init__()
-        self.tool_configs = tool_configs
-        self.message_prefix = message_prefix
+        resolved_tool_configs: dict[str, ToolConfig] = {}
+        for tool_name, tool_config in tool_configs.items():
+            if isinstance(tool_config, bool):
+                if tool_config is True:
+                    resolved_tool_configs[tool_name] = ToolConfig(
+                        allow_accept=True,
+                        allow_edit=True,
+                        allow_respond=True,
+                    )
+            else:
+                resolved_tool_configs[tool_name] = tool_config
+        self.tool_configs = resolved_tool_configs
+        self.description_prefix = description_prefix
 
-    def after_model(self, state: AgentState) -> dict[str, Any] | None:
+    def after_model(self, state: AgentState) -> dict[str, Any] | None:  # type: ignore[override]
         """Trigger HITL flows for relevant tool calls after an AIMessage."""
         messages = state["messages"]
         if not messages:
             return None
 
-        last_message = messages[-1]
-
-        if not hasattr(last_message, "tool_calls") or not last_message.tool_calls:
+        last_ai_msg = next((msg for msg in messages if isinstance(msg, AIMessage)), None)
+        if not last_ai_msg or not last_ai_msg.tool_calls:
             return None
 
         # Separate tool calls that need interrupts from those that don't
-        interrupt_tool_calls = []
+        hitl_tool_calls: list[ToolCall] = []
         auto_approved_tool_calls = []
 
-        for tool_call in last_message.tool_calls:
-            tool_name = tool_call["name"]
-            if tool_name in self.tool_configs:
-                interrupt_tool_calls.append(tool_call)
-            else:
-                auto_approved_tool_calls.append(tool_call)
+        for tool_call in last_ai_msg.tool_calls:
+            hitl_tool_calls.append(tool_call) if tool_call[
+                "name"
+            ] in self.tool_configs else auto_approved_tool_calls.append(tool_call)
 
         # If no interrupts needed, return early
-        if not interrupt_tool_calls:
+        if not hitl_tool_calls:
             return None
 
-        approved_tool_calls = auto_approved_tool_calls.copy()
+        # Process all tool calls that require interrupts
+        approved_tool_calls: list[ToolCall] = auto_approved_tool_calls.copy()
+        artificial_tool_messages: list[ToolMessage] = []
 
-        # Right now, we do not support multiple tool calls with interrupts
-        if len(interrupt_tool_calls) > 1:
-            tool_names = [t["name"] for t in interrupt_tool_calls]
-            msg = f"Called the following tools which require interrupts: {tool_names}\n\nYou may only call ONE tool that requires an interrupt at a time"
-            return {
-                "messages": _generate_correction_tool_messages(msg, last_message.tool_calls),
-                "jump_to": "model",
+        # Create interrupt requests for all tools that need approval
+        hitl_requests: list[HumanInTheLoopRequest] = []
+        for tool_call in hitl_tool_calls:
+            tool_name = tool_call["name"]
+            tool_args = tool_call["args"]
+            config = self.tool_configs[tool_name]
+            description = (
+                config.get("description")
+                or f"{self.description_prefix}\n\nTool: {tool_name}\nArgs: {tool_args}"
+            )
+
+            request: HumanInTheLoopRequest = {
+                "action_request": ActionRequest(
+                    action=tool_name,
+                    args=tool_args,
+                ),
+                "config": config,
+                "description": description,
             }
+            hitl_requests.append(request)
 
-        # Right now, we do not support interrupting a tool call if other tool calls exist
-        if auto_approved_tool_calls:
-            tool_names = [t["name"] for t in interrupt_tool_calls]
-            msg = f"Called the following tools which require interrupts: {tool_names}. You also called other tools that do not require interrupts. If you call a tool that requires and interrupt, you may ONLY call that tool."
-            return {
-                "messages": _generate_correction_tool_messages(msg, last_message.tool_calls),
-                "jump_to": "model",
-            }
+        responses: list[HumanInTheLoopResponse] = interrupt(hitl_requests)
 
-        # Only one tool call will need interrupts
-        tool_call = interrupt_tool_calls[0]
-        tool_name = tool_call["name"]
-        tool_args = tool_call["args"]
-        description = f"{self.message_prefix}\n\nTool: {tool_name}\nArgs: {tool_args}"
-        tool_config = self.tool_configs[tool_name]
-
-        request: HumanInterrupt = {
-            "action_request": ActionRequest(
-                action=tool_name,
-                args=tool_args,
-            ),
-            "config": tool_config,
-            "description": description,
-        }
-
-        responses: list[HumanResponse] = interrupt([request])
-        response = responses[0]
-
-        if response["type"] == "accept":
-            approved_tool_calls.append(tool_call)
-        elif response["type"] == "edit":
-            edited: ActionRequest = response["args"]  # type: ignore[assignment]
-            new_tool_call = {
-                "type": "tool_call",
-                "name": tool_call["name"],
-                "args": edited["args"],
-                "id": tool_call["id"],
-            }
-            approved_tool_calls.append(new_tool_call)
-        elif response["type"] == "ignore":
-            return {"jump_to": "__end__"}
-        elif response["type"] == "response":
-            tool_message = {
-                "role": "tool",
-                "tool_call_id": tool_call["id"],
-                "content": response["args"],
-            }
-            return {"messages": [tool_message], "jump_to": "model"}
-        else:
-            msg = f"Unknown response type: {response['type']}"
+        # Validate that the number of responses matches the number of interrupt tool calls
+        if (responses_len := len(responses)) != (hitl_tool_calls_len := len(hitl_tool_calls)):
+            msg = (
+                f"Number of human responses ({responses_len}) does not match "
+                f"number of hanging tool calls ({hitl_tool_calls_len})."
+            )
             raise ValueError(msg)
 
-        last_message.tool_calls = approved_tool_calls
-
-        return {"messages": [last_message]}
+        for i, response in enumerate(responses):
+            tool_call = hitl_tool_calls[i]
+            config = self.tool_configs[tool_call["name"]]
+
+            if response["type"] == "accept" and config.get("allow_accept"):
+                approved_tool_calls.append(tool_call)
+            elif response["type"] == "edit" and config.get("allow_edit"):
+                edited_action = response["args"]
+                approved_tool_calls.append(
+                    ToolCall(
+                        type="tool_call",
+                        name=edited_action["action"],
+                        args=edited_action["args"],
+                        id=tool_call["id"],
+                    )
+                )
+            elif response["type"] == "response" and config.get("allow_respond"):
+                # Create a tool message with the human's text response
+                content = response.get("args") or (
+                    f"User rejected the tool call for `{tool_call['name']}` "
+                    f"with id {tool_call['id']}"
+                )
+                tool_message = ToolMessage(
+                    content=content,
+                    name=tool_call["name"],
+                    tool_call_id=tool_call["id"],
+                    status="error",
+                )
+                artificial_tool_messages.append(tool_message)
+            else:
+                allowed_actions = [
+                    action
+                    for action in ["accept", "edit", "response"]
+                    if config.get(f"allow_{'respond' if action == 'response' else action}")
+                ]
+                msg = (
+                    f"Unexpected human response: {response}. "
+                    f"Response action '{response.get('type')}' "
+                    f"is not allowed for tool '{tool_call['name']}'. "
+                    f"Expected one of {allowed_actions} based on the tool's configuration."
+                )
+                raise ValueError(msg)
+
+        # Update the AI message to only include approved tool calls
+        last_ai_msg.tool_calls = approved_tool_calls
+
+        if len(approved_tool_calls) > 0:
+            return {"messages": [last_ai_msg, *artificial_tool_messages]}
+
+        return {"jump_to": "model", "messages": artificial_tool_messages}

langchain/agents/middleware/prompt_caching.py

@@ -2,13 +2,16 @@
 
 from typing import Literal
 
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+from langchain.agents.middleware.types import AgentMiddleware, ModelRequest
 
 
 class AnthropicPromptCachingMiddleware(AgentMiddleware):
-    """Prompt Caching Middleware - Optimizes API usage by caching conversation prefixes for Anthropic models.
+    """Prompt Caching Middleware.
 
-    Learn more about anthropic prompt caching [here](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching).
+    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>`__.
     """
 
     def __init__(
@@ -22,27 +25,32 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
         Args:
             type: The type of cache to use, only "ephemeral" is supported.
             ttl: The time to live for the cache, only "5m" and "1h" are supported.
-            min_messages_to_cache: The minimum number of messages until the cache is used, default is 0.
+            min_messages_to_cache: The minimum number of messages until the cache is used,
+                default is 0.
         """
         self.type = type
         self.ttl = ttl
         self.min_messages_to_cache = min_messages_to_cache
 
-    def modify_model_request(self, request: ModelRequest, state: AgentState) -> ModelRequest:  # noqa: ARG002
+    def modify_model_request(  # type: ignore[override]
+        self,
+        request: ModelRequest,
+    ) -> ModelRequest:
         """Modify the model request to add cache control blocks."""
         try:
             from langchain_anthropic import ChatAnthropic
         except ImportError:
             msg = (
-                "AnthropicPromptCachingMiddleware caching middleware only supports Anthropic models."
+                "AnthropicPromptCachingMiddleware caching middleware only supports "
+                "Anthropic models."
                 "Please install langchain-anthropic."
             )
             raise ValueError(msg)
 
         if not isinstance(request.model, ChatAnthropic):
             msg = (
-                "AnthropicPromptCachingMiddleware caching middleware only supports Anthropic models, "
-                f"not instances of {type(request.model)}"
+                "AnthropicPromptCachingMiddleware caching middleware only supports "
+                f"Anthropic models, not instances of {type(request.model)}"
             )
             raise ValueError(msg)