langchain 1.0.0a3__py3-none-any.whl → 1.0.0a5__py3-none-any.whl

langchain/__init__.py

@@ -2,7 +2,7 @@
 
 from typing import Any
 
-__version__ = "1.0.0a1"
+__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/interrupt.py

@@ -1,6 +1,6 @@
 """Interrupt types to use with agent inbox like setups."""
 
-from typing import Literal, Union
+from typing import Literal
 
 from typing_extensions import TypedDict
 
@@ -53,15 +53,15 @@ class HumanInterrupt(TypedDict):
         request = HumanInterrupt(
             action_request=ActionRequest(
                 action="run_command",  # The action being requested
-                args={"command": "ls", "args": ["-l"]}  # Arguments for the action
+                args={"command": "ls", "args": ["-l"]},  # Arguments for the action
             ),
             config=HumanInterruptConfig(
-                allow_ignore=True,    # Allow skipping this step
-                allow_respond=True,   # Allow text feedback
-                allow_edit=False,     # Don't allow editing
-                allow_accept=True     # Allow direct acceptance
+                allow_ignore=True,  # Allow skipping this step
+                allow_respond=True,  # Allow text feedback
+                allow_edit=False,  # Don't allow editing
+                allow_accept=True,  # Allow direct acceptance
             ),
-            description="Please review the command before execution"
+            description="Please review the command before execution",
         )
         # Send the interrupt request and get the response
         response = interrupt([request])[0]
@@ -74,19 +74,24 @@ class HumanInterrupt(TypedDict):
 
 
 class HumanResponse(TypedDict):
-    """The response provided by a human to an interrupt, which is returned when graph execution resumes.
+    """Human response.
+
+    The response provided by a human to an interrupt,
+    which is returned when graph execution resumes.
 
     Attributes:
         type: The type of response:
+
             - "accept": Approves the current state without changes
             - "ignore": Skips/ignores the current step
             - "response": Provides text feedback or instructions
             - "edit": Modifies the current state/content
         args: The response payload:
+
             - None: For ignore/accept actions
             - str: For text responses
             - ActionRequest: For edit actions with updated content
     """
 
     type: Literal["accept", "ignore", "response", "edit"]
-    args: Union[None, str, ActionRequest]
+    args: None | str | ActionRequest

langchain/agents/middleware/__init__.py

@@ -0,0 +1,15 @@
+"""Middleware plugins for agents."""
+
+from .human_in_the_loop import HumanInTheLoopMiddleware
+from .prompt_caching import AnthropicPromptCachingMiddleware
+from .summarization import SummarizationMiddleware
+from .types import AgentMiddleware, AgentState, ModelRequest
+
+__all__ = [
+    "AgentMiddleware",
+    "AgentState",
+    "AnthropicPromptCachingMiddleware",
+    "HumanInTheLoopMiddleware",
+    "ModelRequest",
+    "SummarizationMiddleware",
+]

langchain/agents/middleware/_utils.py

@@ -0,0 +1,11 @@
+"""Utility functions for middleware."""
+
+from typing import Any
+
+
+def _generate_correction_tool_messages(content: str, tool_calls: list) -> list[dict[str, Any]]:
+    """Generate tool messages for model behavior correction."""
+    return [
+        {"role": "tool", "content": content, "tool_call_id": tool_call["id"]}
+        for tool_call in tool_calls
+    ]

langchain/agents/middleware/human_in_the_loop.py

@@ -0,0 +1,135 @@
+"""Human in the loop middleware."""
+
+from typing import Any
+
+from langgraph.prebuilt.interrupt import (
+    ActionRequest,
+    HumanInterrupt,
+    HumanInterruptConfig,
+    HumanResponse,
+)
+from langgraph.types import interrupt
+
+from langchain.agents.middleware._utils import _generate_correction_tool_messages
+from langchain.agents.middleware.types import AgentMiddleware, AgentState
+
+ToolInterruptConfig = dict[str, HumanInterruptConfig]
+
+
+class HumanInTheLoopMiddleware(AgentMiddleware):
+    """Human in the loop middleware."""
+
+    def __init__(
+        self,
+        tool_configs: ToolInterruptConfig,
+        message_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.
+        """
+        super().__init__()
+        self.tool_configs = tool_configs
+        self.message_prefix = message_prefix
+
+    def after_model(self, state: AgentState) -> dict[str, Any] | None:
+        """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:
+            return None
+
+        # Separate tool calls that need interrupts from those that don't
+        interrupt_tool_calls = []
+        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)
+
+        # If no interrupts needed, return early
+        if not interrupt_tool_calls:
+            return None
+
+        approved_tool_calls = auto_approved_tool_calls.copy()
+
+        # 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\n"
+                "You 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",
+            }
+
+        # 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",
+            }
+
+        # 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']}"
+            raise ValueError(msg)
+
+        last_message.tool_calls = approved_tool_calls
+
+        return {"messages": [last_message]}

langchain/agents/middleware/prompt_caching.py

@@ -0,0 +1,62 @@
+"""Anthropic prompt caching middleware."""
+
+from typing import Literal
+
+from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+
+
+class AnthropicPromptCachingMiddleware(AgentMiddleware):
+    """Prompt Caching Middleware.
+
+    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__(
+        self,
+        type: Literal["ephemeral"] = "ephemeral",
+        ttl: Literal["5m", "1h"] = "5m",
+        min_messages_to_cache: int = 0,
+    ) -> None:
+        """Initialize the middleware with cache control settings.
+
+        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.
+        """
+        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
+        """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."
+                "Please install langchain-anthropic."
+            )
+            raise ValueError(msg)
+
+        if not isinstance(request.model, ChatAnthropic):
+            msg = (
+                "AnthropicPromptCachingMiddleware caching middleware only supports "
+                f"Anthropic models, not instances of {type(request.model)}"
+            )
+            raise ValueError(msg)
+
+        messages_count = (
+            len(request.messages) + 1 if request.system_prompt else len(request.messages)
+        )
+        if messages_count < self.min_messages_to_cache:
+            return request
+
+        request.model_settings["cache_control"] = {"type": self.type, "ttl": self.ttl}
+
+        return request

langchain/agents/middleware/summarization.py

@@ -0,0 +1,248 @@
+"""Summarization middleware."""
+
+import uuid
+from collections.abc import Callable, Iterable
+from typing import Any, cast
+
+from langchain_core.messages import (
+    AIMessage,
+    AnyMessage,
+    MessageLikeRepresentation,
+    RemoveMessage,
+    ToolMessage,
+)
+from langchain_core.messages.human import HumanMessage
+from langchain_core.messages.utils import count_tokens_approximately, trim_messages
+from langgraph.graph.message import (
+    REMOVE_ALL_MESSAGES,
+)
+
+from langchain.agents.middleware.types import AgentMiddleware, AgentState
+from langchain.chat_models import BaseChatModel, init_chat_model
+
+TokenCounter = Callable[[Iterable[MessageLikeRepresentation]], int]
+
+DEFAULT_SUMMARY_PROMPT = """<role>
+Context Extraction Assistant
+</role>
+
+<primary_objective>
+Your sole objective in this task is to extract the highest quality/most relevant context from the conversation history below.
+</primary_objective>
+
+<objective_information>
+You're nearing the total number of input tokens you can accept, so you must extract the highest quality/most relevant pieces of information from your conversation history.
+This context will then overwrite the conversation history presented below. Because of this, ensure the context you extract is only the most important information to your overall goal.
+</objective_information>
+
+<instructions>
+The conversation history below will be replaced with the context you extract in this step. Because of this, you must do your very best to extract and record all of the most important context from the conversation history.
+You want to ensure that you don't repeat any actions you've already completed, so the context you extract from the conversation history should be focused on the most important information to your overall goal.
+</instructions>
+
+The user will message you with the full message history you'll be extracting context from, to then replace. Carefully read over it all, and think deeply about what information is most important to your overall goal that should be saved:
+
+With all of this in mind, please carefully read over the entire conversation history, and extract the most important and relevant context to replace it so that you can free up space in the conversation history.
+Respond ONLY with the extracted context. Do not include any additional information, or text before or after the extracted context.
+
+<messages>
+Messages to summarize:
+{messages}
+</messages>"""  # noqa: E501
+
+SUMMARY_PREFIX = "## Previous conversation summary:"
+
+_DEFAULT_MESSAGES_TO_KEEP = 20
+_DEFAULT_TRIM_TOKEN_LIMIT = 4000
+_DEFAULT_FALLBACK_MESSAGE_COUNT = 15
+_SEARCH_RANGE_FOR_TOOL_PAIRS = 5
+
+
+class SummarizationMiddleware(AgentMiddleware):
+    """Middleware that summarizes conversation history when token limits are approached.
+
+    This middleware monitors message token counts and automatically summarizes older
+    messages when a threshold is reached, preserving recent messages and maintaining
+    context continuity by ensuring AI/Tool message pairs remain together.
+    """
+
+    def __init__(
+        self,
+        model: str | BaseChatModel,
+        max_tokens_before_summary: int | None = None,
+        messages_to_keep: int = _DEFAULT_MESSAGES_TO_KEEP,
+        token_counter: TokenCounter = count_tokens_approximately,
+        summary_prompt: str = DEFAULT_SUMMARY_PROMPT,
+        summary_prefix: str = SUMMARY_PREFIX,
+    ) -> None:
+        """Initialize the summarization middleware.
+
+        Args:
+            model: The language model to use for generating summaries.
+            max_tokens_before_summary: Token threshold to trigger summarization.
+                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.
+            summary_prefix: Prefix added to system message when including summary.
+        """
+        super().__init__()
+
+        if isinstance(model, str):
+            model = init_chat_model(model)
+
+        self.model = model
+        self.max_tokens_before_summary = max_tokens_before_summary
+        self.messages_to_keep = messages_to_keep
+        self.token_counter = token_counter
+        self.summary_prompt = summary_prompt
+        self.summary_prefix = summary_prefix
+
+    def before_model(self, state: AgentState) -> dict[str, Any] | None:
+        """Process messages before model invocation, potentially triggering summarization."""
+        messages = state["messages"]
+        self._ensure_message_ids(messages)
+
+        total_tokens = self.token_counter(messages)
+        if (
+            self.max_tokens_before_summary is not None
+            and total_tokens < self.max_tokens_before_summary
+        ):
+            return None
+
+        cutoff_index = self._find_safe_cutoff(messages)
+
+        if cutoff_index <= 0:
+            return None
+
+        messages_to_summarize, preserved_messages = self._partition_messages(messages, cutoff_index)
+
+        summary = self._create_summary(messages_to_summarize)
+        new_messages = self._build_new_messages(summary)
+
+        return {
+            "messages": [
+                RemoveMessage(id=REMOVE_ALL_MESSAGES),
+                *new_messages,
+                *preserved_messages,
+            ]
+        }
+
+    def _build_new_messages(self, summary: str) -> list[HumanMessage]:
+        return [
+            HumanMessage(content=f"Here is a summary of the conversation to date:\n\n{summary}")
+        ]
+
+    def _ensure_message_ids(self, messages: list[AnyMessage]) -> None:
+        """Ensure all messages have unique IDs for the add_messages reducer."""
+        for msg in messages:
+            if msg.id is None:
+                msg.id = str(uuid.uuid4())
+
+    def _partition_messages(
+        self,
+        conversation_messages: list[AnyMessage],
+        cutoff_index: int,
+    ) -> tuple[list[AnyMessage], list[AnyMessage]]:
+        """Partition messages into those to summarize and those to preserve."""
+        messages_to_summarize = conversation_messages[:cutoff_index]
+        preserved_messages = conversation_messages[cutoff_index:]
+
+        return messages_to_summarize, preserved_messages
+
+    def _find_safe_cutoff(self, messages: list[AnyMessage]) -> int:
+        """Find safe cutoff point that preserves AI/Tool message pairs.
+
+        Returns the index where messages can be safely cut without separating
+        related AI and Tool messages. Returns 0 if no safe cutoff is found.
+        """
+        if len(messages) <= self.messages_to_keep:
+            return 0
+
+        target_cutoff = len(messages) - self.messages_to_keep
+
+        for i in range(target_cutoff, -1, -1):
+            if self._is_safe_cutoff_point(messages, i):
+                return i
+
+        return 0
+
+    def _is_safe_cutoff_point(self, messages: list[AnyMessage], cutoff_index: int) -> bool:
+        """Check if cutting at index would separate AI/Tool message pairs."""
+        if cutoff_index >= len(messages):
+            return True
+
+        search_start = max(0, cutoff_index - _SEARCH_RANGE_FOR_TOOL_PAIRS)
+        search_end = min(len(messages), cutoff_index + _SEARCH_RANGE_FOR_TOOL_PAIRS)
+
+        for i in range(search_start, search_end):
+            if not self._has_tool_calls(messages[i]):
+                continue
+
+            tool_call_ids = self._extract_tool_call_ids(cast("AIMessage", messages[i]))
+            if self._cutoff_separates_tool_pair(messages, i, cutoff_index, tool_call_ids):
+                return False
+
+        return True
+
+    def _has_tool_calls(self, message: AnyMessage) -> bool:
+        """Check if message is an AI message with tool calls."""
+        return (
+            isinstance(message, AIMessage) and hasattr(message, "tool_calls") and message.tool_calls  # type: ignore[return-value]
+        )
+
+    def _extract_tool_call_ids(self, ai_message: AIMessage) -> set[str]:
+        """Extract tool call IDs from an AI message."""
+        tool_call_ids = set()
+        for tc in ai_message.tool_calls:
+            call_id = tc.get("id") if isinstance(tc, dict) else getattr(tc, "id", None)
+            if call_id is not None:
+                tool_call_ids.add(call_id)
+        return tool_call_ids
+
+    def _cutoff_separates_tool_pair(
+        self,
+        messages: list[AnyMessage],
+        ai_message_index: int,
+        cutoff_index: int,
+        tool_call_ids: set[str],
+    ) -> bool:
+        """Check if cutoff separates an AI message from its corresponding tool messages."""
+        for j in range(ai_message_index + 1, len(messages)):
+            message = messages[j]
+            if isinstance(message, ToolMessage) and message.tool_call_id in tool_call_ids:
+                ai_before_cutoff = ai_message_index < cutoff_index
+                tool_before_cutoff = j < cutoff_index
+                if ai_before_cutoff != tool_before_cutoff:
+                    return True
+        return False
+
+    def _create_summary(self, messages_to_summarize: list[AnyMessage]) -> str:
+        """Generate summary for the given messages."""
+        if not messages_to_summarize:
+            return "No previous conversation history."
+
+        trimmed_messages = self._trim_messages_for_summary(messages_to_summarize)
+        if not trimmed_messages:
+            return "Previous conversation was too long to summarize."
+
+        try:
+            response = self.model.invoke(self.summary_prompt.format(messages=trimmed_messages))
+            return cast("str", response.content).strip()
+        except Exception as e:  # noqa: BLE001
+            return f"Error generating summary: {e!s}"
+
+    def _trim_messages_for_summary(self, messages: list[AnyMessage]) -> list[AnyMessage]:
+        """Trim messages to fit within summary generation limits."""
+        try:
+            return trim_messages(
+                messages,
+                max_tokens=_DEFAULT_TRIM_TOKEN_LIMIT,
+                token_counter=self.token_counter,
+                start_on="human",
+                strategy="last",
+                allow_partial=True,
+                include_system=True,
+            )
+        except Exception:  # noqa: BLE001
+            return messages[-_DEFAULT_FALLBACK_MESSAGE_COUNT:]