langchain-dev-utils 1.3.6__py3-none-any.whl → 1.4.0__py3-none-any.whl

langchain_dev_utils/__init__.py

@@ -1 +1 @@
-__version__ = "1.3.6"
+__version__ = "1.4.0"

langchain_dev_utils/_utils.py

@@ -1,9 +1,27 @@
 from importlib import util
-from typing import Literal, Optional
+from typing import Literal, Optional, cast
 
+from langgraph.graph import StateGraph
+from langgraph.graph.state import StateNode
 from pydantic import BaseModel
 
 
+def _transform_node_to_tuple(
+    node: StateNode | tuple[str, StateNode],
+) -> tuple[str, StateNode]:
+    if not isinstance(node, tuple):
+        if isinstance(node, StateGraph):
+            node = node.compile()
+            name = node.name
+            return name, node
+        name = cast(str, getattr(node, "name", getattr(node, "__name__", None)))
+        if name is None:
+            raise ValueError("Node name must be provided if action is not a function")
+        return name, node
+    else:
+        return node
+
+
 def _check_pkg_install(
     pkg: Literal["langchain_openai", "json_repair"],
 ) -> None:

langchain_dev_utils/agents/middleware/handoffs.py

@@ -1,4 +1,4 @@
-from typing import Any, Awaitable, Callable, Literal
+from typing import Any, Awaitable, Callable, Literal, cast
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
@@ -128,6 +128,7 @@ class HandoffAgentMiddleware(AgentMiddleware):
     Args:
         agents_config (dict[str, AgentConfig]): A dictionary of agent configurations.
         custom_handoffs_tool_descriptions (Optional[dict[str, str]]): A dictionary of custom tool descriptions for handoffs tools. Defaults to None.
+        handoffs_tool_overrides (Optional[dict[str, BaseTool]]): A dictionary of handoffs tools to override. Defaults to None.
 
     Examples:
         ```python
@@ -142,6 +143,7 @@ class HandoffAgentMiddleware(AgentMiddleware):
         self,
         agents_config: dict[str, AgentConfig],
         custom_handoffs_tool_descriptions: Optional[dict[str, str]] = None,
+        handoffs_tool_overrides: Optional[dict[str, BaseTool]] = None,
     ) -> None:
         default_agent_name = _get_default_active_agent(agents_config)
         if default_agent_name is None:
@@ -152,13 +154,23 @@ class HandoffAgentMiddleware(AgentMiddleware):
         if custom_handoffs_tool_descriptions is None:
             custom_handoffs_tool_descriptions = {}
 
-        handoffs_tools = [
-            _create_handoffs_tool(
-                agent_name,
-                custom_handoffs_tool_descriptions.get(agent_name),
-            )
-            for agent_name in agents_config.keys()
-        ]
+        if handoffs_tool_overrides is None:
+            handoffs_tool_overrides = {}
+
+        handoffs_tools = []
+        for agent_name in agents_config.keys():
+            if not handoffs_tool_overrides.get(agent_name):
+                handoffs_tools.append(
+                    _create_handoffs_tool(
+                        agent_name,
+                        custom_handoffs_tool_descriptions.get(agent_name),
+                    )
+                )
+            else:
+                handoffs_tools.append(
+                    cast(BaseTool, handoffs_tool_overrides.get(agent_name))
+                )
+
         self.default_agent_name = default_agent_name
         self.agents_config = _transform_agent_config(
             agents_config,
@@ -166,7 +178,7 @@ class HandoffAgentMiddleware(AgentMiddleware):
         )
         self.tools = handoffs_tools
 
-    def _get_active_agent_config(self, request: ModelRequest) -> dict[str, Any]:
+    def _get_override_request(self, request: ModelRequest) -> ModelRequest:
         active_agent_name = request.state.get("active_agent", self.default_agent_name)
 
         _config = self.agents_config[active_agent_name]
@@ -181,24 +193,22 @@ class HandoffAgentMiddleware(AgentMiddleware):
             params["system_prompt"] = _config.get("prompt")
         if _config.get("tools"):
             params["tools"] = _config.get("tools")
-        return params
+
+        if params:
+            return request.override(**params)
+        else:
+            return request
 
     def wrap_model_call(
         self, request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]
     ) -> ModelCallResult:
-        override_kwargs = self._get_active_agent_config(request)
-        if override_kwargs:
-            return handler(request.override(**override_kwargs))
-        else:
-            return handler(request)
+        override_request = self._get_override_request(request)
+        return handler(override_request)
 
     async def awrap_model_call(
         self,
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelCallResult:
-        override_kwargs = self._get_active_agent_config(request)
-        if override_kwargs:
-            return await handler(request.override(**override_kwargs))
-        else:
-            return await handler(request)
+        override_request = self._get_override_request(request)
+        return await handler(override_request)

langchain_dev_utils/agents/middleware/model_router.py

@@ -150,7 +150,7 @@ class ModelRouterMiddleware(AgentMiddleware):
         model_name = await self._aselect_model(state["messages"])
         return {"router_model_selection": model_name}
 
-    def _get_override_kwargs(self, request: ModelRequest) -> dict[str, Any]:
+    def _get_override_request(self, request: ModelRequest) -> ModelRequest:
         model_dict = {
             item["model_name"]: {
                 "tools": item.get("tools", None),
@@ -180,24 +180,21 @@ class ModelRouterMiddleware(AgentMiddleware):
                     content=model_values["system_prompt"]
                 )
 
-        return override_kwargs
+        if override_kwargs:
+            return request.override(**override_kwargs)
+        else:
+            return request
 
     def wrap_model_call(
         self, request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]
     ) -> ModelCallResult:
-        override_kwargs = self._get_override_kwargs(request)
-        if override_kwargs:
-            return handler(request.override(**override_kwargs))
-        else:
-            return handler(request)
+        override_request = self._get_override_request(request)
+        return handler(override_request)
 
     async def awrap_model_call(
         self,
         request: ModelRequest,
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelCallResult:
-        override_kwargs = self._get_override_kwargs(request)
-        if override_kwargs:
-            return await handler(request.override(**override_kwargs))
-        else:
-            return await handler(request)
+        override_request = self._get_override_request(request)
+        return await handler(override_request)

langchain_dev_utils/agents/middleware/plan.py

@@ -335,12 +335,8 @@ class PlanMiddleware(AgentMiddleware):
         self.system_prompt = system_prompt
         self.tools = tools
 
-    def wrap_model_call(
-        self,
-        request: ModelRequest,
-        handler: Callable[[ModelRequest], ModelResponse],
-    ) -> ModelCallResult:
-        """Update the system message to include the plan system prompt."""
+    def _get_override_request(self, request: ModelRequest) -> ModelRequest:
+        """Add the plan system prompt to the system message."""
         if request.system_message is not None:
             new_system_content = [
                 *request.system_message.content_blocks,
@@ -351,7 +347,15 @@ class PlanMiddleware(AgentMiddleware):
         new_system_message = SystemMessage(
             content=cast("list[str | dict[str, str]]", new_system_content)
         )
-        return handler(request.override(system_message=new_system_message))
+        return request.override(system_message=new_system_message)
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        override_request = self._get_override_request(request)
+        return handler(override_request)
 
     async def awrap_model_call(
         self,
@@ -359,14 +363,5 @@ class PlanMiddleware(AgentMiddleware):
         handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
     ) -> ModelCallResult:
         """Update the system message to include the plan system prompt."""
-        if request.system_message is not None:
-            new_system_content = [
-                *request.system_message.content_blocks,
-                {"type": "text", "text": f"\n\n{self.system_prompt}"},
-            ]
-        else:
-            new_system_content = [{"type": "text", "text": self.system_prompt}]
-        new_system_message = SystemMessage(
-            content=cast("list[str | dict[str, str]]", new_system_content)
-        )
-        return await handler(request.override(system_message=new_system_message))
+        override_request = self._get_override_request(request)
+        return await handler(override_request)

langchain_dev_utils/agents/wrap.py

@@ -1,12 +1,13 @@
-import asyncio
-from typing import Any, Awaitable, Callable, Optional
+import inspect
+from typing import Any, Awaitable, Callable, Optional, cast
 
 from langchain.tools import ToolRuntime
-from langchain_core.messages import HumanMessage
+from langchain_core.messages import AIMessage, HumanMessage
 from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.graph.state import CompiledStateGraph
 
 from langchain_dev_utils.message_convert import format_sequence
+from langchain_dev_utils.tool_calling import parse_tool_calling
 
 
 def _process_input(request: str, runtime: ToolRuntime) -> str:
@@ -19,6 +20,18 @@ def _process_output(
     return response["messages"][-1].content
 
 
+def get_subagent_name(runtime: ToolRuntime) -> str:
+    messages = runtime.state.get("messages", [])
+    last_ai_msg = cast(
+        AIMessage,
+        next((msg for msg in reversed(messages) if isinstance(msg, AIMessage)), None),
+    )
+
+    _, args = parse_tool_calling(last_ai_msg, first_tool_call_only=True)
+    args = cast(dict[str, Any], args)
+    return args["agent_name"]
+
+
 def wrap_agent_as_tool(
     agent: CompiledStateGraph,
     tool_name: Optional[str] = None,
@@ -115,7 +128,7 @@ def wrap_agent_as_tool(
         request: str,
         runtime: ToolRuntime,
     ):
-        if asyncio.iscoroutinefunction(process_input_async):
+        if inspect.iscoroutinefunction(process_input_async):
             _processed_input = await process_input_async(request, runtime)
         else:
             _processed_input = (
@@ -135,7 +148,7 @@ def wrap_agent_as_tool(
 
         response = await agent.ainvoke(agent_input)
 
-        if asyncio.iscoroutinefunction(process_output_async):
+        if inspect.iscoroutinefunction(process_output_async):
             response = await process_output_async(request, response, runtime)
         else:
             response = (
@@ -277,7 +290,7 @@ def wrap_all_agents_as_tool(
         if agent_name not in agents_map:
             raise ValueError(f"Agent {agent_name} not found")
 
-        if asyncio.iscoroutinefunction(process_input_async):
+        if inspect.iscoroutinefunction(process_input_async):
             _processed_input = await process_input_async(description, runtime)
         else:
             _processed_input = (
@@ -297,7 +310,7 @@ def wrap_all_agents_as_tool(
 
         response = await agents_map[agent_name].ainvoke(agent_input)
 
-        if asyncio.iscoroutinefunction(process_output_async):
+        if inspect.iscoroutinefunction(process_output_async):
             response = await process_output_async(description, response, runtime)
         else:
             response = (

langchain_dev_utils/chat_models/adapters/openai_compatible.py

@@ -218,14 +218,15 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
         stop: list[str] | None = None,
         **kwargs: Any,
     ) -> dict:
+        if stop is not None:
+            kwargs["stop"] = stop
+
         payload = {**self._default_params, **kwargs}
 
         if self._use_responses_api(payload):
             return super()._get_request_payload(input_, stop=stop, **kwargs)
 
         messages = self._convert_input(input_).to_messages()
-        if stop is not None:
-            kwargs["stop"] = stop
 
         payload_messages = []
         last_human_index = -1

langchain_dev_utils/graph/__init__.py

@@ -0,0 +1,7 @@
+from .parallel import create_parallel_graph
+from .sequential import create_sequential_graph
+
+__all__ = [
+    "create_parallel_graph",
+    "create_sequential_graph",
+]

langchain_dev_utils/graph/parallel.py

@@ -0,0 +1,119 @@
+from typing import Awaitable, Callable, Optional, Union, cast
+
+from langgraph.cache.base import BaseCache
+from langgraph.graph import StateGraph
+from langgraph.graph.state import CompiledStateGraph, StateNode
+from langgraph.store.base import BaseStore
+from langgraph.types import Checkpointer, Send
+from langgraph.typing import ContextT, InputT, OutputT, StateT
+
+from langchain_dev_utils._utils import _transform_node_to_tuple
+
+from .types import Node
+
+
+def create_parallel_graph(
+    nodes: list[Node],
+    state_schema: type[StateT],
+    graph_name: Optional[str] = None,
+    branches_fn: Optional[
+        Union[
+            Callable[..., list[Send]],
+            Callable[..., Awaitable[list[Send]]],
+        ]
+    ] = None,
+    context_schema: type[ContextT] | None = None,
+    input_schema: type[InputT] | None = None,
+    output_schema: type[OutputT] | None = None,
+    checkpointer: Checkpointer | None = None,
+    store: BaseStore | None = None,
+    cache: BaseCache | None = None,
+) -> CompiledStateGraph[StateT, ContextT, InputT, OutputT]:
+    """
+    Create a parallel graph from a list of nodes.
+
+    This function lets you build a parallel StateGraph simply by writing the corresponding Nodes.
+
+    Args:
+        nodes: List of nodes to execute in parallel
+        state_schema: state schema of the final state graph
+        graph_name: Name of the final state graph
+        branches_fn: Optional function to determine which nodes to execute
+            in parallel
+        context_schema: context schema of the final state graph
+        input_schema: input schema of the final state graph
+        output_schema: output schema of the final state graph
+        checkpointer: Optional LangGraph checkpointer for the final state graph
+        store: Optional LangGraph store for the final state graph
+        cache: Optional LangGraph cache for the final state graph
+
+    Returns:
+        CompiledStateGraph[StateT, ContextT, InputT, OutputT]: Compiled state graph
+
+    Example:
+        # Basic parallel pipeline: multiple specialized agents run concurrently
+        >>> from langchain_dev_utils.graph import create_parallel_graph
+        >>>
+        >>> graph = create_parallel_graph(
+        ...     nodes=[
+        ...        node1, node2, node3
+        ...     ],
+        ...     state_schema=StateT,
+        ...     graph_name="parallel_graph",
+        ... )
+        >>>
+        >>> response = graph.invoke({"messages": [HumanMessage("Hello")]})
+
+        # Dynamic parallel pipeline: decide which nodes to run based on conditional branches
+        >>> graph = create_parallel_graph(
+        ...     nodes=[
+        ...         node1, node2, node3
+        ...     ],
+        ...     state_schema=StateT,
+        ...     branches_fn=lambda state: [
+        ...         Send("node1", arg={"messages": [HumanMessage("Hello")]}),
+        ...         Send("node2", arg={"messages": [HumanMessage("Hello")]}),
+        ...     ],
+        ...     graph_name="parallel_graph",
+        ... )
+        >>>
+        >>> response = graph.invoke({"messages": [HumanMessage("Hello")]})
+    """
+    graph = StateGraph(
+        state_schema=state_schema,
+        context_schema=context_schema,
+        input_schema=input_schema,
+        output_schema=output_schema,
+    )
+
+    node_list: list[tuple[str, StateNode]] = []
+
+    for node in nodes:
+        node_list.append(_transform_node_to_tuple(node))
+
+    if branches_fn:
+        for name, node in node_list:
+            node = cast(StateNode[StateT, ContextT], node)
+            graph.add_node(name, node)
+        graph.add_conditional_edges(
+            "__start__",
+            branches_fn,
+            [node_name for node_name, _ in node_list],
+        )
+        return graph.compile(
+            name=graph_name or "parallel graph",
+            checkpointer=checkpointer,
+            store=store,
+            cache=cache,
+        )
+    else:
+        for node_name, node in node_list:
+            node = cast(StateNode[StateT, ContextT], node)
+            graph.add_node(node_name, node)
+            graph.add_edge("__start__", node_name)
+        return graph.compile(
+            name=graph_name or "parallel graph",
+            checkpointer=checkpointer,
+            store=store,
+            cache=cache,
+        )

langchain_dev_utils/graph/sequential.py

@@ -0,0 +1,78 @@
+from typing import Optional
+
+from langgraph.cache.base import BaseCache
+from langgraph.graph import StateGraph
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.store.base import BaseStore
+from langgraph.types import Checkpointer
+from langgraph.typing import ContextT, InputT, OutputT, StateT
+
+from langchain_dev_utils._utils import _transform_node_to_tuple
+
+from .types import Node
+
+
+def create_sequential_graph(
+    nodes: list[Node],
+    state_schema: type[StateT],
+    graph_name: Optional[str] = None,
+    context_schema: type[ContextT] | None = None,
+    input_schema: type[InputT] | None = None,
+    output_schema: type[OutputT] | None = None,
+    checkpointer: Checkpointer | None = None,
+    store: BaseStore | None = None,
+    cache: BaseCache | None = None,
+) -> CompiledStateGraph[StateT, ContextT, InputT, OutputT]:
+    """
+    Create a sequential graph from a list of nodes.
+
+    This function lets you build a sequential StateGraph simply by writing the corresponding Nodes.
+
+    Args:
+        nodes: List of nodes to execute sequentially
+        state_schema: state schema of the final state graph
+        graph_name: Name of the final state graph
+        context_schema: context schema of the final state graph
+        input_schema: input schema of the final state graph
+        output_schema: output schema of the final state graph
+        checkpointer: Optional LangGraph checkpointer for the final state graph
+        store: Optional LangGraph store for the final state graph
+        cache: Optional LangGraph cache for the final state graph
+    Returns:
+        CompiledStateGraph[StateT, ContextT, InputT, OutputT]: Compiled state graph.
+
+    Example:
+        # Basic sequential graph with multiple specialized agents:
+        >>> from langchain_dev_utils.graph.sequential import create_sequential_graph
+        >>>
+        >>> graph = create_sequential_graph(
+        ...     nodes=[
+        ...         node1, node2, node3
+        ...     ],
+        ...     state_schema=State,
+        ...     graph_name="sequential_graph",
+        ... )
+        >>>
+        >>> response = graph.invoke({"messages": [HumanMessage("Hello")]})
+    """
+    graph = StateGraph(
+        state_schema=state_schema,
+        context_schema=context_schema,
+        input_schema=input_schema,
+        output_schema=output_schema,
+    )
+
+    node_list = []
+    for node in nodes:
+        node = _transform_node_to_tuple(node)
+        node_list.append(node)
+
+    graph.add_sequence(node_list)
+    first_node_name, _ = node_list[0]
+    graph.add_edge("__start__", first_node_name)
+    return graph.compile(
+        name=graph_name or "sequential graph",
+        checkpointer=checkpointer,
+        store=store,
+        cache=cache,
+    )

langchain_dev_utils/graph/types.py

@@ -0,0 +1,3 @@
+from langgraph.graph.state import StateNode
+
+Node = StateNode | tuple[str, StateNode]

langchain_dev_utils/message_convert/format.py

@@ -10,6 +10,39 @@ from langchain_core.messages import (
 )
 
 
+def _format_message(item: BaseMessage) -> str:
+    if (
+        isinstance(item, HumanMessage)
+        or isinstance(item, SystemMessage)
+        or isinstance(item, ToolMessage)
+    ):
+        text = "\n".join(
+            [block["text"] for block in item.content_blocks if block["type"] == "text"]
+        )
+
+        role = item.type.title()
+        return f"{role}: {text}"
+    elif isinstance(item, AIMessage):
+        content = (
+            "\n".join(
+                [
+                    block["text"]
+                    for block in item.content_blocks
+                    if block["type"] == "text"
+                ]
+            )
+            or ""
+        )
+
+        for tool_call in item.tool_calls:
+            content += f"\n<tool_call>{tool_call['name']}</tool_call>"
+        return f"AI: {content}"
+    else:
+        raise ValueError(
+            f"Unsupported message type: {type(item)},expected HumanMessage, AIMessage, SystemMessage, ToolMessage"
+        )
+
+
 def format_sequence(
     inputs: Union[Sequence[Document], Sequence[BaseMessage], Sequence[str]],
     separator: str = "-",
@@ -57,7 +90,7 @@ def format_sequence(
         if isinstance(
             input_item, (HumanMessage, AIMessage, SystemMessage, ToolMessage)
         ):
-            outputs.append(input_item.content)
+            outputs.append(_format_message(input_item))
         elif isinstance(input_item, Document):
             outputs.append(input_item.page_content)
         elif isinstance(input_item, str):

langchain_dev_utils/pipeline/parallel.py

@@ -6,10 +6,16 @@ from langgraph.graph.state import CompiledStateGraph
 from langgraph.store.base import BaseStore
 from langgraph.types import Checkpointer, Send
 from langgraph.typing import ContextT, InputT, OutputT, StateT
+from typing_extensions import deprecated
 
 from .types import SubGraph
 
 
+@deprecated(
+    """The function create_parallel_pipeline is deprecated since v1.4.0. And it will be remove in v1.5.0.
+    Please use create_parallel_graph instead（from graph module）.
+    """
+)
 def create_parallel_pipeline(
     sub_graphs: list[SubGraph],
     state_schema: type[StateT],

langchain_dev_utils/pipeline/sequential.py

@@ -6,10 +6,16 @@ from langgraph.graph.state import CompiledStateGraph
 from langgraph.store.base import BaseStore
 from langgraph.types import Checkpointer
 from langgraph.typing import ContextT, InputT, OutputT, StateT
+from typing_extensions import deprecated
 
 from .types import SubGraph
 
 
+@deprecated(
+    """The function create_sequential_pipeline is deprecated since v1.4.0. And it will be remove in v1.5.0.
+    Please use create_sequential_graph instead（from graph module）.
+    """
+)
 def create_sequential_pipeline(
     sub_graphs: list[SubGraph],
     state_schema: type[StateT],

{langchain_dev_utils-1.3.6.dist-info → langchain_dev_utils-1.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-dev-utils
-Version: 1.3.6
+Version: 1.4.0
 Summary: A practical utility library for LangChain and LangGraph development
 Project-URL: Source Code, https://github.com/TBice123123/langchain-dev-utils
 Project-URL: repository, https://github.com/TBice123123/langchain-dev-utils
@@ -27,10 +27,11 @@ Description-Content-Type: text/markdown
   <a href="https://tbice123123.github.io/langchain-dev-utils/zh/">中文</a>
 </p>
 
-[![PyPI](https://img.shields.io/pypi/v/langchain-dev-utils.svg?color=%2334D058&label=pypi%20package)](https://pypi.org/project/langchain-dev-utils/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python](https://img.shields.io/badge/python-3.11|3.12|3.13|3.14-%2334D058)](https://www.python.org/downloads)
-[![Downloads](https://static.pepy.tech/badge/langchain-dev-utils/month)](https://pepy.tech/project/langchain-dev-utils)
+[![GitHub Repo](https://img.shields.io/badge/GitHub-Repo-black.svg?logo=github)](https://github.com/TBice123123/langchain-dev-utils)
+[![PyPI](https://img.shields.io/pypi/v/langchain-dev-utils.svg?color=%2334D058&label=pypi%20package&logo=python)](https://pypi.org/project/langchain-dev-utils/)
+[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg?logo=python&label=Python)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?label=License)](https://opensource.org/licenses/MIT)
+[![Last Commit](https://img.shields.io/github/last-commit/TBice123123/langchain-dev-utils)](https://github.com/TBice123123/langchain-dev-utils)
 [![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://tbice123123.github.io/langchain-dev-utils)
 
 > This is the English version. For the Chinese version, please visit [中文版本](https://github.com/TBice123123/langchain-dev-utils/blob/master/README_cn.md)
@@ -51,7 +52,7 @@ Tired of writing repetitive code in LangChain development? `langchain-dev-utils`
 - **💬 Flexible message handling** - Support for chain-of-thought concatenation, streaming processing, and message formatting
 - **🛠️ Powerful tool calling** - Built-in tool call detection, parameter parsing, and human review functionality
 - **🤖 Efficient Agent development** - Simplify agent creation process, expand more common middleware
-- **📊 Flexible state graph composition** - Support for serial and parallel composition of multiple StateGraphs
+- **📊 Convenient State Graph Construction** - Provides pre-built functions to easily create sequential or parallel state graphs
 
 ## ⚡ Quick Start
 

{langchain_dev_utils-1.3.6.dist-info → langchain_dev_utils-1.4.0.dist-info}/RECORD

@@ -1,17 +1,15 @@
-langchain_dev_utils/__init__.py,sha256=i3AHxnb5CSWmIhimmqttiPmRwfh2zYzO6idNDuUtzMI,23
-langchain_dev_utils/_utils.py,sha256=hWuxzxIlCPkT02xglWqkRnroky2mCmW5qtK-zHDH4RY,4032
+langchain_dev_utils/__init__.py,sha256=-pa9pj_zJgPDZtE3ena4mjuVS3FEWQWYij1shjLYS80,23
+langchain_dev_utils/_utils.py,sha256=cWWq0sLA3yNGtcB9YyM60gcUg-hz0mjEa5CYg60cXHE,4663
 langchain_dev_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langchain_dev_utils/agents/__init__.py,sha256=69_biZzyJvW9OBT1g8TX_77mp9-I_TvWo9QtlvHq83E,177
 langchain_dev_utils/agents/factory.py,sha256=8XB6y_ddf58vXlTLHBL6KCirFqkD2GjtzsuOt98sS7U,3732
-langchain_dev_utils/agents/file_system.py,sha256=Yk3eetREE26WNrnTWLoiDUpOyCJ-rhjlfFDk6foLa1E,8468
-langchain_dev_utils/agents/plan.py,sha256=WwhoiJBmVYVI9bT8HfjCzTJ_SIp9WFil0gOeznv2omQ,6497
-langchain_dev_utils/agents/wrap.py,sha256=Tw6KYMdZ5ESsWVjoImZimZI2Eg5rEipsqUVJ0tSVbUw,11536
+langchain_dev_utils/agents/wrap.py,sha256=ufxcOCLDE4Aw2TbgcyFYor0BXXaJDzLTTJJyyD4x7bQ,12011
 langchain_dev_utils/agents/middleware/__init__.py,sha256=QVQibaNHvHPyNTZ2UNFfYL153ZboaCHcoioTHK0FsiY,710
 langchain_dev_utils/agents/middleware/format_prompt.py,sha256=yIkoSVPp0FemkjezvGsOmtgOkZDyEYQ8yh4YWYYGtVc,2343
-langchain_dev_utils/agents/middleware/handoffs.py,sha256=r196Xk0Jws1Tz6JQuvy5HEc3HAAQejCxFmJpB6KrvLU,7230
+langchain_dev_utils/agents/middleware/handoffs.py,sha256=rSkNXxqtjB8_xT0HUdxnKbchgY76BuTPX-Zc69H-_wI,7687
 langchain_dev_utils/agents/middleware/model_fallback.py,sha256=8xiNjTJ0yiRkPLCRfAGNnqY1TLstj1Anmiqyv5w2mA8,1633
-langchain_dev_utils/agents/middleware/model_router.py,sha256=qBspvj9ZoKfmC1pHWTO0EHHfxjgCUd-TuSbqvZl0kmg,7977
-langchain_dev_utils/agents/middleware/plan.py,sha256=-ZLkp85QQTSCX9thMblacJ1N86h0BYPoTwCfJlJ_jzQ,14981
+langchain_dev_utils/agents/middleware/model_router.py,sha256=IidYq72tPLa053gEg5IQpPzDzyCxYYEvpgT1K4qBwXw,7862
+langchain_dev_utils/agents/middleware/plan.py,sha256=Zz0dh1BRbsVgROmhjH2IIqylSsuKHZXJx0iztMBm8EU,14719
 langchain_dev_utils/agents/middleware/summarization.py,sha256=IoZ2PM1OC3AXwf0DWpfreuPOAipeiYu0KPmAABWXuY0,3087
 langchain_dev_utils/agents/middleware/tool_call_repair.py,sha256=oZF0Oejemqs9kSn8xbW79FWyVVarL4IGCz0gpqYBkFM,3529
 langchain_dev_utils/agents/middleware/tool_emulator.py,sha256=OgtPhqturaWzF4fRSJ3f_IXvIrYrrAjlpOC5zmLtrkY,2031
@@ -21,24 +19,28 @@ langchain_dev_utils/chat_models/base.py,sha256=G_SNvd53ogho-LRgD7DCD65xj51J2JxmO
 langchain_dev_utils/chat_models/types.py,sha256=MD3cv_ZIe9fCdgwisNfuxAOhy-j4YSs1ZOQYyCjlNKs,927
 langchain_dev_utils/chat_models/adapters/__init__.py,sha256=4tTbhAAQdpX_gWyWeH97hqS5HnaoqQqW6QBh9Qd1SKs,106
 langchain_dev_utils/chat_models/adapters/create_utils.py,sha256=r8_XWLNF3Yc6sumlBhmgG1QcBa4Dsba7X3f_9YeMeGA,2479
-langchain_dev_utils/chat_models/adapters/openai_compatible.py,sha256=Xsd6HN1zGGDl87bZ5NMfwKfxWkgdP4DpszEqlb4Z-MY,27198
+langchain_dev_utils/chat_models/adapters/openai_compatible.py,sha256=Z-AOpMm6MldKpL8EtuZ9pzfOFAjirZUKxw2K7EPk87w,27200
 langchain_dev_utils/chat_models/adapters/register_profiles.py,sha256=YS9ItCEq2ISoB_bp6QH5NVKOVR9-7la3r7B_xQNxZxE,366
 langchain_dev_utils/embeddings/__init__.py,sha256=zbEOaV86TUi9Zrg_dH9dpdgacWg31HMJTlTQknA9EKk,244
 langchain_dev_utils/embeddings/base.py,sha256=GXFKZSAExMtCFUpsd6mY4NxCWCrq7JAatBw3kS9LaKY,8803
 langchain_dev_utils/embeddings/adapters/__init__.py,sha256=yJEZZdzZ2fv1ExezLaNxo0VU9HJTHKYbS3T_XP8Ab9c,114
 langchain_dev_utils/embeddings/adapters/create_utils.py,sha256=K4JlbjG-O5xLY3wxaVt0UZ3QwI--cVb4qyxLATKVAWQ,2012
 langchain_dev_utils/embeddings/adapters/openai_compatible.py,sha256=fo7-m7dcWL4xrhSqdAHHVREsiXfVOvIrlaotaYTEiyE,3159
+langchain_dev_utils/graph/__init__.py,sha256=CqujmJ6YhBDHZdvf4nGWzB9dEuzRciI3AaRQBlE0kMk,174
+langchain_dev_utils/graph/parallel.py,sha256=HsHxwmAs0wqmg33GWJocYfYU5VyHgdiRJC5JzMBOQjs,4387
+langchain_dev_utils/graph/sequential.py,sha256=s0_hHZbImhEIyqNA3u50Cs3mjM_6X-vJjIYO1cnmYYo,2828
+langchain_dev_utils/graph/types.py,sha256=P6dHhq6GPG38NbbAY2oW6M_MHwhfmqZ26ARFU8IU5u4,89
 langchain_dev_utils/message_convert/__init__.py,sha256=nnkDa_Im0dCb5u4aa2FRB9tqB8e6H6sEGYK6Vg81u2s,472
 langchain_dev_utils/message_convert/content.py,sha256=2V1g21byg3iLv5RjUW8zv3jwYwV7IH2hNim7jGRsIes,8096
-langchain_dev_utils/message_convert/format.py,sha256=NdrYX0cJn2-G1ArLSjJ7yO788KV1d83F4Kimpyft0IM,2446
+langchain_dev_utils/message_convert/format.py,sha256=D75GYNrfB_3VkxyaztNhCr_LiCdcKhPDp8WFHW9D4Wc,3467
 langchain_dev_utils/pipeline/__init__.py,sha256=eE6WktaLHDkqMeXDIDaLtm-OPTwtsX_Av8iK9uYrceo,186
-langchain_dev_utils/pipeline/parallel.py,sha256=nwZWbdSNeyanC9WufoJBTceotgT--UnPOfStXjgNMOc,5271
-langchain_dev_utils/pipeline/sequential.py,sha256=sYJXQzVHDKUc-UV-HMv38JTPnse1A7sRM0vqSdpHK0k,3850
+langchain_dev_utils/pipeline/parallel.py,sha256=dO53_IKYAKmme69byDZjVlRTcariJFKVCe8tFKMdJv4,5516
+langchain_dev_utils/pipeline/sequential.py,sha256=TEAzLEmL9OxBZoIPvAhnuHbI0HeevqHIzc75KTgs2Fw,4099
 langchain_dev_utils/pipeline/types.py,sha256=T3aROKKXeWvd0jcH5XkgMDQfEkLfPaiOhhV2q58fDHs,112
 langchain_dev_utils/tool_calling/__init__.py,sha256=mu_WxKMcu6RoTf4vkTPbA1WSBSNc6YIqyBtOQ6iVQj4,322
 langchain_dev_utils/tool_calling/human_in_the_loop.py,sha256=7Z_QO5OZUR6K8nLoIcafc6osnvX2IYNorOJcbx6bVso,9672
 langchain_dev_utils/tool_calling/utils.py,sha256=S4-KXQ8jWmpGTXYZitovF8rxKpaSSUkFruM8LDwvcvE,2765
-langchain_dev_utils-1.3.6.dist-info/METADATA,sha256=voBBn5Zqd3zoJ4b4W93Aj9L0UsMLuDhG_iZUDJ6hY0k,4552
-langchain_dev_utils-1.3.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-langchain_dev_utils-1.3.6.dist-info/licenses/LICENSE,sha256=AWAOzNEcsvCEzHOF0qby5OKxviVH_eT9Yce1sgJTico,1084
-langchain_dev_utils-1.3.6.dist-info/RECORD,,
+langchain_dev_utils-1.4.0.dist-info/METADATA,sha256=bF2sQIAP0N0yDnBm-_DZDQbFS5sHqrmF7HtRHFQEexY,4758
+langchain_dev_utils-1.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+langchain_dev_utils-1.4.0.dist-info/licenses/LICENSE,sha256=AWAOzNEcsvCEzHOF0qby5OKxviVH_eT9Yce1sgJTico,1084
+langchain_dev_utils-1.4.0.dist-info/RECORD,,

langchain_dev_utils/agents/file_system.py

@@ -1,252 +0,0 @@
-import warnings
-from typing import Annotated, Literal, Optional
-
-from langchain.tools import BaseTool, ToolRuntime, tool
-from langchain_core.messages import ToolMessage
-from langgraph.types import Command
-from typing_extensions import TypedDict
-
-warnings.warn(
-    "langchain_dev_utils.agents.file_system is deprecated, and it will be removed in a future version. Please use middleware in deepagents instead.",
-    DeprecationWarning,
-)
-
-_DEFAULT_WRITE_FILE_DESCRIPTION = """
-A tool for writing files.
-
-Args:
-    content: The content of the file
-"""
-
-_DEFAULT_LS_DESCRIPTION = """List all the saved file names."""
-
-
-_DEFAULT_QUERY_FILE_DESCRIPTION = """
-Query the content of a file.
-
-Args:
-    file_name: The name of the file
-"""
-
-_DEFAULT_UPDATE_FILE_DESCRIPTION = """
-Update the content of a file.
-
-Args:
-    file_name: The name of the file
-    origin_content: The original content of the file, must be a content in the file
-    new_content: The new content of the file
-    replace_all: Whether to replace all the origin content
-"""
-
-
-def file_reducer(left: dict | None, right: dict | None):
-    if left is None:
-        return right
-    elif right is None:
-        return left
-    else:
-        return {**left, **right}
-
-
-class FileStateMixin(TypedDict):
-    file: Annotated[dict[str, str], file_reducer]
-
-
-def create_write_file_tool(
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    message_key: Optional[str] = None,
-) -> BaseTool:
-    """Create a tool for writing files.
-
-    This function creates a tool that allows agents to write files and store them
-    in the state. The files are stored in a dictionary with the file name as the key
-    and the content as the value.
-
-    Args:
-        name: The name of the tool. Defaults to "write_file".
-        description: The description of the tool. Uses default description if not provided.
-        message_key: The key of the message to be updated. Defaults to "messages".
-
-    Returns:
-        BaseTool: The tool for writing files.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.file_system import create_write_file_tool
-        >>> write_file = create_write_file_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "write_file",
-        description=description or _DEFAULT_WRITE_FILE_DESCRIPTION,
-    )
-    def write_file(
-        file_name: Annotated[str, "the name of the file"],
-        content: Annotated[str, "the content of the file"],
-        runtime: ToolRuntime,
-        write_mode: Annotated[
-            Literal["write", "append"], "the write mode of the file"
-        ] = "write",
-    ):
-        files = runtime.state.get("file", {})
-        if write_mode == "append":
-            content = files.get(file_name, "") + content
-        if write_mode == "write" and file_name in files:
-            # if the file already exists, append a suffix to the file name when write_mode is "write"
-            file_name = file_name + "_" + str(len(files[file_name]))
-        msg_key = message_key or "messages"
-        return Command(
-            update={
-                "file": {file_name: content},
-                msg_key: [
-                    ToolMessage(
-                        content=f"file {file_name} written successfully, content is {content}",
-                        tool_call_id=runtime.tool_call_id,
-                    )
-                ],
-            }
-        )
-
-    return write_file
-
-
-def create_ls_file_tool(
-    name: Optional[str] = None, description: Optional[str] = None
-) -> BaseTool:
-    """Create a tool for listing all the saved file names.
-
-    This function creates a tool that allows agents to list all available files
-    stored in the state. This is useful for discovering what files have been
-    created before querying or updating them.
-
-    Args:
-        name: The name of the tool. Defaults to "ls".
-        description: The description of the tool. Uses default description if not provided.
-
-    Returns:
-        BaseTool: The tool for listing all the saved file names.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.file_system import create_ls_file_tool
-        >>> ls = create_ls_file_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "ls",
-        description=description or _DEFAULT_LS_DESCRIPTION,
-    )
-    def ls(runtime: ToolRuntime):
-        files = runtime.state.get("file", {})
-        return list(files.keys())
-
-    return ls
-
-
-def create_query_file_tool(
-    name: Optional[str] = None, description: Optional[str] = None
-) -> BaseTool:
-    """Create a tool for querying the content of a file.
-
-    This function creates a tool that allows agents to retrieve the content of
-    a specific file by its name. This is useful for accessing previously stored
-    information during the conversation.
-
-    Args:
-        name: The name of the tool. Defaults to "query_file".
-        description: The description of the tool. Uses default description if not provided.
-
-    Returns:
-        BaseTool: The tool for querying the content of a file.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.file_system import create_query_file_tool
-        >>> query_file = create_query_file_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "query_file",
-        description=description or _DEFAULT_QUERY_FILE_DESCRIPTION,
-    )
-    def query_file(file_name: str, runtime: ToolRuntime):
-        files = runtime.state.get("file", {})
-        if file_name not in files:
-            raise ValueError(f"Error: File {file_name} not found")
-
-        content = files.get(file_name)
-
-        if not content or content.strip() == "":
-            raise ValueError(f"Error: File {file_name} is empty")
-
-        return content
-
-    return query_file
-
-
-def create_update_file_tool(
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    message_key: Optional[str] = None,
-) -> BaseTool:
-    """Create a tool for updating files.
-
-    This function creates a tool that allows agents to update the content of
-    existing files. The tool can replace either the first occurrence of the
-    original content or all occurrences, depending on the replace_all parameter.
-
-    Args:
-        name: The name of the tool. Defaults to "update_file".
-        description: The description of the tool. Uses default description if not provided.
-        message_key: The key of the message to be updated. Defaults to "messages".
-
-    Returns:
-        BaseTool: The tool for updating files.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.file_system import create_update_file_tool
-        >>> update_file_tool = create_update_file_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "update_file",
-        description=description or _DEFAULT_UPDATE_FILE_DESCRIPTION,
-    )
-    def update_file(
-        file_name: Annotated[str, "the name of the file"],
-        origin_content: Annotated[str, "the original content of the file"],
-        new_content: Annotated[str, "the new content of the file"],
-        runtime: ToolRuntime,
-        replace_all: Annotated[bool, "replace all the origin content"] = False,
-    ):
-        msg_key = message_key or "messages"
-        files = runtime.state.get("file", {})
-        if file_name not in files:
-            raise ValueError(f"Error: File {file_name} not found")
-
-        if origin_content not in files.get(file_name, ""):
-            raise ValueError(
-                f"Error: Origin content {origin_content} not found in file {file_name}"
-            )
-
-        if replace_all:
-            new_content = files.get(file_name, "").replace(origin_content, new_content)
-        else:
-            new_content = files.get(file_name, "").replace(
-                origin_content, new_content, 1
-            )
-        return Command(
-            update={
-                "file": {file_name: new_content},
-                msg_key: [
-                    ToolMessage(
-                        content=f"file {file_name} updated successfully, content is {new_content}",
-                        tool_call_id=runtime.tool_call_id,
-                    )
-                ],
-            }
-        )
-
-    return update_file

langchain_dev_utils/agents/plan.py

@@ -1,188 +0,0 @@
-import warnings
-from typing import Literal, Optional
-
-from langchain.tools import BaseTool, ToolRuntime, tool
-from langchain_core.messages import ToolMessage
-from langgraph.types import Command
-from typing_extensions import TypedDict
-
-warnings.warn(
-    "langchain_dev_utils.agents.plan is deprecated, and it will be removed in a future version. Please use middleware in langchain-dev-utils instead.",
-    DeprecationWarning,
-)
-
-_DEFAULT_WRITE_PLAN_TOOL_DESCRIPTION = """
-A tool for writing initial plan — can only be used once, at the very beginning. 
-Use update_plan for subsequent modifications.
-
-Args:
-    plan: The list of plan items to write. Each string in the list represents 
-          the content of one plan item.
-"""
-
-_DEFAULT_UPDATE_PLAN_TOOL_DESCRIPTION = """
-A tool for updating the status of plan tasks. Can be called multiple times to track task progress.
-
-Args:
-    update_plans: A list of plan items to update. Each item is a dictionary containing 
-                  the following fields:
-                  - content: str — The exact content of the plan task. Must match an 
-                    existing task verbatim.
-                  - status: str — The task status. Must be either "in_progress" or "done".
-
-Usage Guidelines:
-- Only pass the tasks whose status needs to be updated — no need to include all tasks.
-- Each call must include at least one task with status "done" AND at least one task with 
-  status "in_progress":
-  - Mark completed tasks as "done"
-  - Mark the next tasks to work on as "in_progress"
-- The "content" field must exactly match the content of an existing task 
-  (case-sensitive, whitespace-sensitive).
-
-Example:
-Suppose the current task list is:
-- Task 1 (in_progress)
-- Task 2 (pending)
-- Task 3 (pending)
-
-When "Task 1" is completed and you are ready to start "Task 2", pass in:
-[
-    {"content": "Task 1", "status": "done"},
-    {"content": "Task 2", "status": "in_progress"}
-]
-"""
-
-
-class Plan(TypedDict):
-    content: str
-    status: Literal["pending", "in_progress", "done"]
-
-
-class PlanStateMixin(TypedDict):
-    plan: list[Plan]
-
-
-def create_write_plan_tool(
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    message_key: Optional[str] = None,
-) -> BaseTool:
-    """Create a tool for writing initial plan.
-
-    This function creates a tool that allows agents to write an initial plan
-    with a list of tasks. The first task in the plan will be marked as "in_progress"
-    and the rest as "pending".
-
-    Args:
-        name: The name of the tool. Defaults to "write_plan".
-        description: The description of the tool. Uses default description if not provided.
-        message_key: The key of the message to be updated. Defaults to "messages".
-
-    Returns:
-        BaseTool: The tool for writing initial plan.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.plan import create_write_plan_tool
-        >>> write_plan_tool = create_write_plan_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "write_plan",
-        description=description or _DEFAULT_WRITE_PLAN_TOOL_DESCRIPTION,
-    )
-    def write_plan(plan: list[str], runtime: ToolRuntime):
-        msg_key = message_key or "messages"
-        return Command(
-            update={
-                "plan": [
-                    {
-                        "content": content,
-                        "status": "pending" if index > 0 else "in_progress",
-                    }
-                    for index, content in enumerate(plan)
-                ],
-                msg_key: [
-                    ToolMessage(
-                        content=f"Plan successfully written, please first execute the {plan[0]} task (no need to change the status to in_process)",
-                        tool_call_id=runtime.tool_call_id,
-                    )
-                ],
-            }
-        )
-
-    return write_plan
-
-
-def create_update_plan_tool(
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    message_key: Optional[str] = None,
-) -> BaseTool:
-    """Create a tool for updating plan tasks.
-
-    This function creates a tool that allows agents to update the status of tasks
-    in a plan. Tasks can be marked as "in_progress" or "done" to track progress.
-
-    Args:
-        name: The name of the tool. Defaults to "update_plan".
-        description: The description of the tool. Uses default description if not provided.
-        message_key: The key of the message to be updated. Defaults to "messages".
-
-    Returns:
-        BaseTool: The tool for updating plan tasks.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.plan import create_update_plan_tool
-        >>> update_plan_tool = create_update_plan_tool()
-    """
-
-    @tool(
-        name_or_callable=name or "update_plan",
-        description=description or _DEFAULT_UPDATE_PLAN_TOOL_DESCRIPTION,
-    )
-    def update_plan(
-        update_plans: list[Plan],
-        runtime: ToolRuntime,
-    ):
-        plan_list = runtime.state.get("plan", [])
-
-        updated_plan_list = []
-
-        for update_plan in update_plans:
-            for plan in plan_list:
-                if plan["content"] == update_plan["content"]:
-                    plan["status"] = update_plan["status"]
-                    updated_plan_list.append(plan)
-
-        if len(updated_plan_list) < len(update_plans):
-            raise ValueError(
-                "Not fullly updated plan, missing:"
-                + ",".join(
-                    [
-                        plan["content"]
-                        for plan in update_plans
-                        if plan not in updated_plan_list
-                    ]
-                )
-                + "\nPlease check the plan list, the current plan list is:"
-                + "\n".join(
-                    [plan["content"] for plan in plan_list if plan["status"] != "done"]
-                )
-            )
-        msg_key = message_key or "messages"
-
-        return Command(
-            update={
-                "plan": plan_list,
-                msg_key: [
-                    ToolMessage(
-                        content="Plan updated successfully",
-                        tool_call_id=runtime.tool_call_id,
-                    )
-                ],
-            }
-        )
-
-    return update_plan