langchain-dev-utils 1.3.5__tar.gz → 1.3.7__tar.gz

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-dev-utils
-Version: 1.3.5
+Version: 1.3.7
 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

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langchain-dev-utils"
-version = "1.3.5"
+version = "1.3.7"
 description = "A practical utility library for LangChain and LangGraph development"
 readme = "README.md"
 authors = [{ name = "tiebingice", email = "tiebingice123@outlook.com" }]

langchain_dev_utils-1.3.7/src/langchain_dev_utils/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.3.7"

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/src/langchain_dev_utils/_utils.py

@@ -97,6 +97,11 @@ def _validate_model_cls_name(model_cls_name: str) -> None:
             f"model_cls_name should start with an uppercase letter (PEP 8). Received: {model_cls_name}"
         )
 
+    if len(model_cls_name) > 30:
+        raise ValueError(
+            f"model_cls_name must be 30 characters or fewer. Received: {model_cls_name}"
+        )
+
 
 def _validate_provider_name(provider_name: str) -> None:
     """Validate provider name follows Python naming conventions.
@@ -112,7 +117,7 @@ def _validate_provider_name(provider_name: str) -> None:
 
     if not provider_name[0].isalnum():
         raise ValueError(
-            f"provider_name must start with a letter. Received: {provider_name}"
+            f"provider_name must start with a letter or number. Received: {provider_name}"
         )
 
     if not all(c.isalnum() or c == "_" for c in provider_name):

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/src/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-1.3.5 → langchain_dev_utils-1.3.7}/src/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-1.3.5 → langchain_dev_utils-1.3.7}/src/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-1.3.5 → langchain_dev_utils-1.3.7}/src/langchain_dev_utils/agents/wrap.py

@@ -1,8 +1,8 @@
 import asyncio
-from typing import Any, Awaitable, Callable, Optional, cast
+from typing import Any, Awaitable, Callable, Optional
 
 from langchain.tools import ToolRuntime
-from langchain_core.messages import AnyMessage, HumanMessage
+from langchain_core.messages import HumanMessage
 from langchain_core.tools import BaseTool, StructuredTool
 from langgraph.graph.state import CompiledStateGraph
 
@@ -14,9 +14,9 @@ def _process_input(request: str, runtime: ToolRuntime) -> str:
 
 
 def _process_output(
-    request: str, response: list[AnyMessage], runtime: ToolRuntime
+    request: str, response: dict[str, Any], runtime: ToolRuntime
 ) -> Any:
-    return response[-1].content
+    return response["messages"][-1].content
 
 
 def wrap_agent_as_tool(
@@ -25,17 +25,17 @@ def wrap_agent_as_tool(
     tool_description: Optional[str] = None,
     pre_input_hooks: Optional[
         tuple[
-            Callable[[str, ToolRuntime], str],
-            Callable[[str, ToolRuntime], Awaitable[str]],
+            Callable[[str, ToolRuntime], str | dict[str, Any]],
+            Callable[[str, ToolRuntime], Awaitable[str | dict[str, Any]]],
         ]
-        | Callable[[str, ToolRuntime], str]
+        | Callable[[str, ToolRuntime], str | dict[str, Any]]
     ] = None,
     post_output_hooks: Optional[
         tuple[
-            Callable[[str, list[AnyMessage], ToolRuntime], Any],
-            Callable[[str, list[AnyMessage], ToolRuntime], Awaitable[Any]],
+            Callable[[str, dict[str, Any], ToolRuntime], Any],
+            Callable[[str, dict[str, Any], ToolRuntime], Awaitable[Any]],
         ]
-        | Callable[[str, list[AnyMessage], ToolRuntime], Any]
+        | Callable[[str, dict[str, Any], ToolRuntime], Any]
     ] = None,
 ) -> BaseTool:
     """Wraps an agent as a tool
@@ -91,33 +91,58 @@ def wrap_agent_as_tool(
     def call_agent(
         request: str,
         runtime: ToolRuntime,
-    ) -> str:
-        request = process_input(request, runtime) if process_input else request
+    ):
+        _processed_input = process_input(request, runtime) if process_input else request
+        if isinstance(_processed_input, str):
+            agent_input = {"messages": [HumanMessage(content=_processed_input)]}
+        elif isinstance(_processed_input, dict):
+            if "messages" not in _processed_input:
+                raise ValueError("Agent input must contain 'messages' key")
+            agent_input = _processed_input
+        else:
+            raise ValueError("Pre Hooks must return a string or a dict")
 
-        messages = [HumanMessage(content=request)]
-        response = agent.invoke({"messages": messages})
+        response = agent.invoke(agent_input)
 
-        response = process_output(request, response["messages"], runtime)
+        response = (
+            process_output(request, response, runtime)
+            if process_output
+            else response["messages"][-1].content
+        )
         return response
 
     async def acall_agent(
         request: str,
         runtime: ToolRuntime,
-    ) -> str:
+    ):
         if asyncio.iscoroutinefunction(process_input_async):
-            request = await process_input_async(request, runtime)
+            _processed_input = await process_input_async(request, runtime)
+        else:
+            _processed_input = (
+                process_input_async(request, runtime)
+                if process_input_async
+                else request
+            )
+
+        if isinstance(_processed_input, str):
+            agent_input = {"messages": [HumanMessage(content=_processed_input)]}
+        elif isinstance(_processed_input, dict):
+            if "messages" not in _processed_input:
+                raise ValueError("Agent input must contain 'messages' key")
+            agent_input = _processed_input
         else:
-            request = cast(str, process_input_async(request, runtime))
+            raise ValueError("Pre Hooks must return a string or a dict")
 
-        messages = [HumanMessage(content=request)]
-        response = await agent.ainvoke({"messages": messages})
+        response = await agent.ainvoke(agent_input)
 
         if asyncio.iscoroutinefunction(process_output_async):
-            response = await process_output_async(
-                request, response["messages"], runtime
-            )
+            response = await process_output_async(request, response, runtime)
         else:
-            response = process_output(request, response["messages"], runtime)
+            response = (
+                process_output(request, response, runtime)
+                if process_output
+                else response["messages"][-1].content
+            )
 
         return response
 
@@ -143,17 +168,17 @@ def wrap_all_agents_as_tool(
     tool_description: Optional[str] = None,
     pre_input_hooks: Optional[
         tuple[
-            Callable[[str, ToolRuntime], str],
-            Callable[[str, ToolRuntime], Awaitable[str]],
+            Callable[[str, ToolRuntime], str | dict[str, Any]],
+            Callable[[str, ToolRuntime], Awaitable[str | dict[str, Any]]],
         ]
-        | Callable[[str, ToolRuntime], str]
+        | Callable[[str, ToolRuntime], str | dict[str, Any]]
     ] = None,
     post_output_hooks: Optional[
         tuple[
-            Callable[[str, list[AnyMessage], ToolRuntime], Any],
-            Callable[[str, list[AnyMessage], ToolRuntime], Awaitable[Any]],
+            Callable[[str, dict[str, Any], ToolRuntime], Any],
+            Callable[[str, dict[str, Any], ToolRuntime], Awaitable[Any]],
         ]
-        | Callable[[str, list[AnyMessage], ToolRuntime], Any]
+        | Callable[[str, dict[str, Any], ToolRuntime], Any]
     ] = None,
 ) -> BaseTool:
     """Wraps all agents as single tool
@@ -219,42 +244,67 @@ def wrap_all_agents_as_tool(
         agent_name: str,
         description: str,
         runtime: ToolRuntime,
-    ) -> str:
-        task_description = (
-            process_input(description, runtime) if process_input else description
-        )
-
+    ):
         if agent_name not in agents_map:
             raise ValueError(f"Agent {agent_name} not found")
 
-        messages = [HumanMessage(content=task_description)]
-        response = agents_map[agent_name].invoke({"messages": messages})
+        _processed_input = (
+            process_input(description, runtime) if process_input else description
+        )
+        if isinstance(_processed_input, str):
+            agent_input = {"messages": [HumanMessage(content=_processed_input)]}
+        elif isinstance(_processed_input, dict):
+            if "messages" not in _processed_input:
+                raise ValueError("Agent input must contain 'messages' key")
+            agent_input = _processed_input
+        else:
+            raise ValueError("Pre Hooks must return str or dict")
+
+        response = agent.invoke(agent_input)
 
-        response = process_output(task_description, response["messages"], runtime)
+        response = (
+            process_output(description, response, runtime)
+            if process_output
+            else response["messages"][-1].content
+        )
         return response
 
     async def acall_agent(
         agent_name: str,
         description: str,
         runtime: ToolRuntime,
-    ) -> str:
+    ):
+        if agent_name not in agents_map:
+            raise ValueError(f"Agent {agent_name} not found")
+
         if asyncio.iscoroutinefunction(process_input_async):
-            task_description = await process_input_async(description, runtime)
+            _processed_input = await process_input_async(description, runtime)
         else:
-            task_description = cast(str, process_input_async(description, runtime))
+            _processed_input = (
+                process_input_async(description, runtime)
+                if process_input_async
+                else description
+            )
 
-        if agent_name not in agents_map:
-            raise ValueError(f"Agent {agent_name} not found")
+        if isinstance(_processed_input, str):
+            agent_input = {"messages": [HumanMessage(content=_processed_input)]}
+        elif isinstance(_processed_input, dict):
+            if "messages" not in _processed_input:
+                raise ValueError("Agent input must contain 'messages' key")
+            agent_input = _processed_input
+        else:
+            raise ValueError("Pre Hooks must return str or dict")
 
-        messages = [HumanMessage(content=task_description)]
-        response = await agents_map[agent_name].ainvoke({"messages": messages})
+        response = await agents_map[agent_name].ainvoke(agent_input)
 
         if asyncio.iscoroutinefunction(process_output_async):
-            response = await process_output_async(
-                task_description, response["messages"], runtime
-            )
+            response = await process_output_async(description, response, runtime)
         else:
-            response = process_output(task_description, response["messages"], runtime)
+            response = (
+                process_output(description, response, runtime)
+                if process_output
+                else response["messages"][-1].content
+            )
 
         return response
 

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/tests/test_handoffs_middleware.py

@@ -1,8 +1,9 @@
 from datetime import datetime
 
-from langchain.tools import tool
+from langchain.tools import BaseTool, ToolRuntime, tool
 from langchain_core.messages import HumanMessage, ToolMessage
 from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.types import Command
 
 from langchain_dev_utils.agents import create_agent
 from langchain_dev_utils.agents.middleware import (
@@ -24,6 +25,22 @@ def run_code(code: str) -> str:
     return "Running code successfully"
 
 
+@tool
+def transfer_to_coding_agent(runtime: ToolRuntime) -> Command:
+    """This tool help you transfer to the coding agent."""
+    return Command(
+        update={
+            "messages": [
+                ToolMessage(
+                    content="Successfully transferred to coding agent",
+                    tool_call_id=runtime.tool_call_id,
+                )
+            ],
+            "active_agent": "code_agent",
+        }
+    )
+
+
 agents_config: dict[str, AgentConfig] = {
     "time_agent": {
         "model": "zai:glm-4.5",
@@ -56,14 +73,24 @@ agents_config: dict[str, AgentConfig] = {
 custom_tool_descriptions: dict[str, str] = {
     "time_agent": "transfer to the time agent to answer time-related questions",
     "talk_agent": "transfer to the talk agent to answer user questions",
-    "code_agent": "transfer to the code agent to answer code-related questions",
+}
+
+
+handoffs_tool_map: dict[str, BaseTool] = {
+    "code_agent": transfer_to_coding_agent,
 }
 
 
 def test_handoffs_middleware():
     agent = create_agent(
         model="dashscope:qwen3-max",
-        middleware=[HandoffAgentMiddleware(agents_config, custom_tool_descriptions)],
+        middleware=[
+            HandoffAgentMiddleware(
+                agents_config=agents_config,
+                custom_handoffs_tool_descriptions=custom_tool_descriptions,
+                handoffs_tool_overrides=handoffs_tool_map,
+            )
+        ],
         tools=[
             get_current_time,
             run_code,
@@ -95,13 +122,26 @@ def test_handoffs_middleware():
         == "qwen3-coder-plus"
     )
     assert isinstance(response["messages"][-2], ToolMessage)
+    assert any(
+        message
+        for message in response["messages"]
+        if isinstance(message, ToolMessage)
+        and "Successfully transferred to coding agent" in message.content
+        and message.name == "transfer_to_coding_agent"
+    )
     assert "active_agent" in response and response["active_agent"] == "code_agent"
 
 
 async def test_handoffs_middleware_async():
     agent = create_agent(
         model="dashscope:qwen3-max",
-        middleware=[HandoffAgentMiddleware(agents_config, custom_tool_descriptions)],
+        middleware=[
+            HandoffAgentMiddleware(
+                agents_config=agents_config,
+                custom_handoffs_tool_descriptions=custom_tool_descriptions,
+                handoffs_tool_overrides=handoffs_tool_map,
+            )
+        ],
         tools=[
             get_current_time,
             run_code,
@@ -133,4 +173,11 @@ async def test_handoffs_middleware_async():
         == "qwen3-coder-plus"
     )
     assert isinstance(response["messages"][-2], ToolMessage)
+    assert any(
+        message
+        for message in response["messages"]
+        if isinstance(message, ToolMessage)
+        and "Successfully transferred to coding agent" in message.content
+        and message.name == "transfer_to_coding_agent"
+    )
     assert "active_agent" in response and response["active_agent"] == "code_agent"

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/tests/test_load_model.py

@@ -76,17 +76,6 @@ async def test_model_tool_calling_async(
     assert hasattr(response, "tool_calls") and len(response.tool_calls) == 1
 
 
-def test_model_with_reasoning(reasoning_model: BaseChatModel):
-    response = reasoning_model.invoke("hello?")
-    assert response.additional_kwargs.get("reasoning_content")
-
-
-@pytest.mark.asyncio
-async def test_model_with_reasoning_async(reasoning_model: BaseChatModel):
-    response = await reasoning_model.ainvoke("hello？")
-    assert response.additional_kwargs.get("reasoning_content")
-
-
 def test_model_profile():
     model = load_chat_model("dashscope:qwen-flash")
     assert model.profile == ALI_PROFILES["qwen-flash"]

{langchain_dev_utils-1.3.5 → langchain_dev_utils-1.3.7}/tests/test_wrap_agent.py

@@ -31,18 +31,22 @@ async def process_input_async(request: str, runtime: ToolRuntime) -> str:
     return "<task_description>" + request + "</task_description>"
 
 
-def process_output(request: str, messages: list, runtime: ToolRuntime) -> str:
-    assert request.startswith("<task_description>")
-    assert request.endswith("</task_description>")
-    return "<task_response>" + messages[-1].content + "</task_response>"
+def process_output(request: str, response: dict[str, Any], runtime: ToolRuntime) -> str:
+    human_message = response["messages"][0]
+    assert human_message.content.startswith(
+        "<task_description>"
+    ) and human_message.content.endswith("</task_description>")
+    return "<task_response>" + response["messages"][-1].content + "</task_response>"
 
 
 async def process_output_async(
-    request: str, messages: list, runtime: ToolRuntime
+    request: str, response: dict[str, Any], runtime: ToolRuntime
 ) -> str:
-    assert request.startswith("<task_description>")
-    assert request.endswith("</task_description>")
-    return "<task_response>" + messages[-1].content + "</task_response>"
+    human_message = response["messages"][0]
+    assert human_message.content.startswith(
+        "<task_description>"
+    ) and human_message.content.endswith("</task_description>")
+    return "<task_response>" + response["messages"][-1].content + "</task_response>"
 
 
 def test_wrap_agent():

langchain_dev_utils-1.3.5/src/langchain_dev_utils/__init__.py

@@ -1 +0,0 @@
-__version__ = "1.3.5"