langchain-dev-utils 1.3.1__py3-none-any.whl → 1.3.2__py3-none-any.whl

langchain_dev_utils/__init__.py

@@ -1 +1 @@
-__version__ = "1.3.1"
+__version__ = "1.3.2"

langchain_dev_utils/agents/middleware/__init__.py

@@ -1,13 +1,8 @@
 from .format_prompt import format_prompt
-from .handoffs import HandoffsAgentMiddleware, create_handoffs_tool
+from .handoffs import HandoffAgentMiddleware
 from .model_fallback import ModelFallbackMiddleware
 from .model_router import ModelRouterMiddleware
-from .plan import (
-    PlanMiddleware,
-    create_finish_sub_plan_tool,
-    create_read_plan_tool,
-    create_write_plan_tool,
-)
+from .plan import PlanMiddleware
 from .summarization import SummarizationMiddleware
 from .tool_call_repair import ToolCallRepairMiddleware
 from .tool_emulator import LLMToolEmulator
@@ -17,14 +12,10 @@ __all__ = [
     "SummarizationMiddleware",
     "LLMToolSelectorMiddleware",
     "PlanMiddleware",
-    "create_finish_sub_plan_tool",
-    "create_read_plan_tool",
-    "create_write_plan_tool",
     "ModelFallbackMiddleware",
     "LLMToolEmulator",
     "ModelRouterMiddleware",
     "ToolCallRepairMiddleware",
     "format_prompt",
-    "create_handoffs_tool",
-    "HandoffsAgentMiddleware",
+    "HandoffAgentMiddleware",
 ]

langchain_dev_utils/agents/middleware/handoffs.py

@@ -1,4 +1,4 @@
-from typing import Any, Awaitable, Callable
+from typing import Any, Awaitable, Callable, Literal
 
 from langchain.agents import AgentState
 from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
@@ -19,35 +19,24 @@ class MultiAgentState(AgentState):
 class AgentConfig(TypedDict):
     model: NotRequired[str | BaseChatModel]
     prompt: str | SystemMessage
-    tools: list[BaseTool | dict[str, Any]]
+    tools: NotRequired[list[BaseTool | dict[str, Any]]]
     default: NotRequired[bool]
+    handoffs: list[str] | Literal["all"]
 
 
-def create_handoffs_tool(
-    agent_name: str,
-    tool_name: Optional[str] = None,
-    tool_description: Optional[str] = None,
-):
+def _create_handoffs_tool(agent_name: str, tool_description: Optional[str] = None):
     """Create a tool for handoffs to a specified agent.
 
     Args:
         agent_name (str): The name of the agent to transfer to.
-        tool_name (Optional[str], optional): The name of the tool. Defaults to None.
-        tool_description (Optional[str], optional): The description of the tool. Defaults to None.
 
     Returns:
         BaseTool: A tool instance for handoffs to the specified agent.
-
-    Example:
-        Basic usage
-        >>> from langchain_dev_utils.agents.middleware import create_handoffs_tool
-        >>> handoffs_tool = create_handoffs_tool("time_agent")
     """
-    if tool_name is None:
-        tool_name = f"transfer_to_{agent_name}"
-        if not tool_name.endswith("_agent"):
-            tool_name += "_agent"
 
+    tool_name = f"transfer_to_{agent_name}"
+    if not tool_name.endswith("_agent"):
+        tool_name += "_agent"
     if tool_description is None:
         tool_description = f"Transfer to the {agent_name}"
 
@@ -75,30 +64,92 @@ def _get_default_active_agent(state: dict[str, AgentConfig]) -> Optional[str]:
     return None
 
 
-class HandoffsAgentMiddleware(AgentMiddleware):
+def _transform_agent_config(
+    config: dict[str, AgentConfig],
+    handoffs_tools: list[BaseTool],
+) -> dict[str, AgentConfig]:
+    """Transform the agent config to add handoffs tools.
+
+    Args:
+        config (dict[str, AgentConfig]): The agent config.
+        handoffs_tools (list[BaseTool]): The list of handoffs tools.
+
+    Returns:
+        dict[str, AgentConfig]: The transformed agent config.
+    """
+
+    for agent_name, _cfg in config.items():
+        handoffs = _cfg.get("handoffs", [])
+        if handoffs == "all":
+            handoff_tools = [
+                handoff_tool
+                for handoff_tool in handoffs_tools
+                if handoff_tool.name != f"transfer_to_{agent_name}"
+            ]
+        else:
+            if not isinstance(handoffs, list):
+                raise ValueError(
+                    f"handoffs for agent {agent_name} must be a list of agent names or 'all'"
+                )
+
+            handoff_tools = [
+                handoff_tool
+                for handoff_tool in handoffs_tools
+                if handoff_tool.name
+                in [
+                    f"transfer_to_{_handoff_agent_name}"
+                    for _handoff_agent_name in handoffs
+                ]
+            ]
+
+        _cfg["tools"] = [*_cfg.get("tools", []), *handoff_tools]
+    return config
+
+
+class HandoffAgentMiddleware(AgentMiddleware):
     """Agent middleware for switching between multiple agents.
     This middleware dynamically replaces model call parameters based on the currently active agent configuration, enabling seamless switching between different agents.
 
     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.
 
     Examples:
         ```python
-        from langchain_dev_utils.agents.middleware import HandoffsAgentMiddleware
-        middleware = HandoffsAgentMiddleware(agents_config)
+        from langchain_dev_utils.agents.middleware import HandoffAgentMiddleware
+        middleware = HandoffAgentMiddleware(agents_config)
         ```
     """
 
     state_schema = MultiAgentState
 
-    def __init__(self, agents_config: dict[str, AgentConfig]):
+    def __init__(
+        self,
+        agents_config: dict[str, AgentConfig],
+        custom_handoffs_tool_descriptions: Optional[dict[str, str]] = None,
+    ) -> None:
         default_agent_name = _get_default_active_agent(agents_config)
         if default_agent_name is None:
             raise ValueError(
                 "No default agent found, you must set one by set default=True"
             )
+
+        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()
+        ]
         self.default_agent_name = default_agent_name
-        self.agents_config = agents_config
+        self.agents_config = _transform_agent_config(
+            agents_config,
+            handoffs_tools,
+        )
+        self.tools = handoffs_tools
 
     def _get_active_agent_config(self, request: ModelRequest) -> dict[str, Any]:
         active_agent_name = request.state.get("active_agent", self.default_agent_name)

langchain_dev_utils/agents/middleware/plan.py

@@ -104,9 +104,14 @@ class PlanState(AgentState):
     plan: NotRequired[list[Plan]]
 
 
-def create_write_plan_tool(
+class PlanToolDescription(TypedDict):
+    write_plan: NotRequired[str]
+    finish_sub_plan: NotRequired[str]
+    read_plan: NotRequired[str]
+
+
+def _create_write_plan_tool(
     description: Optional[str] = None,
-    message_key: Optional[str] = None,
 ) -> BaseTool:
     """Create a tool for writing initial plan.
 
@@ -116,22 +121,15 @@ def create_write_plan_tool(
 
     Args:
         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.middleware import create_write_plan_tool
-        >>> write_plan_tool = create_write_plan_tool()
     """
 
     @tool(
         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": [
@@ -141,7 +139,7 @@ def create_write_plan_tool(
                     }
                     for index, content in enumerate(plan)
                 ],
-                msg_key: [
+                "messages": [
                     ToolMessage(
                         content=f"Plan successfully written, please first execute the {plan[0]} sub-plan (no need to change the status to in_process)",
                         tool_call_id=runtime.tool_call_id,
@@ -153,9 +151,8 @@ def create_write_plan_tool(
     return write_plan
 
 
-def create_finish_sub_plan_tool(
+def _create_finish_sub_plan_tool(
     description: Optional[str] = None,
-    message_key: Optional[str] = None,
 ) -> BaseTool:
     """Create a tool for finishing sub-plan tasks.
 
@@ -164,15 +161,9 @@ def create_finish_sub_plan_tool(
 
     Args:
         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 finishing sub-plan tasks.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.middleware import create_finish_sub_plan_tool
-        >>> finish_sub_plan_tool = create_finish_sub_plan_tool()
     """
 
     @tool(
@@ -181,7 +172,6 @@ def create_finish_sub_plan_tool(
     def finish_sub_plan(
         runtime: ToolRuntime,
     ):
-        msg_key = message_key or "messages"
         plan_list = runtime.state.get("plan", [])
 
         sub_finish_plan = ""
@@ -200,7 +190,7 @@ def create_finish_sub_plan_tool(
         return Command(
             update={
                 "plan": plan_list,
-                msg_key: [
+                "messages": [
                     ToolMessage(
                         content=sub_finish_plan + sub_next_plan,
                         tool_call_id=runtime.tool_call_id,
@@ -212,7 +202,7 @@ def create_finish_sub_plan_tool(
     return finish_sub_plan
 
 
-def create_read_plan_tool(
+def _create_read_plan_tool(
     description: Optional[str] = None,
 ):
     """Create a tool for reading all sub-plans.
@@ -225,11 +215,6 @@ def create_read_plan_tool(
 
     Returns:
         BaseTool: The tool for reading all sub-plans.
-
-    Example:
-        Basic usage:
-        >>> from langchain_dev_utils.agents.middleware import create_read_plan_tool
-        >>> read_plan_tool = create_read_plan_tool()
     """
 
     @tool(
@@ -287,12 +272,8 @@ class PlanMiddleware(AgentMiddleware):
             tool. If not provided, uses the default `_PLAN_SYSTEM_PROMPT` or
             `_PLAN_SYSTEM_PROMPT_NOT_READ_PLAN` based on the `use_read_plan_tool`
             parameter.
-        write_plan_tool_description: Description of the `write_plan` tool.
-            If not provided, uses the default `_DEFAULT_WRITE_PLAN_TOOL_DESCRIPTION`.
-        finish_sub_plan_tool_description: Description of the `finish_sub_plan` tool.
-            If not provided, uses the default `_DEFAULT_FINISH_SUB_PLAN_TOOL_DESCRIPTION`.
-        read_plan_tool_description: Description of the `read_plan` tool.
-            If not provided, uses the default `_DEFAULT_READ_PLAN_TOOL_DESCRIPTION`.
+        custom_plan_tool_descriptions: Custom descriptions for the plan tools.
+            If not provided, uses the default descriptions.
         use_read_plan_tool: Whether to use the `read_plan` tool.
             If not provided, uses the default `True`.
 
@@ -316,31 +297,34 @@ class PlanMiddleware(AgentMiddleware):
         self,
         *,
         system_prompt: Optional[str] = None,
-        write_plan_tool_description: Optional[str] = None,
-        finish_sub_plan_tool_description: Optional[str] = None,
-        read_plan_tool_description: Optional[str] = None,
+        custom_plan_tool_descriptions: Optional[PlanToolDescription] = None,
         use_read_plan_tool: bool = True,
     ) -> None:
         super().__init__()
 
-        write_plan_tool_description = (
-            write_plan_tool_description or _DEFAULT_WRITE_PLAN_TOOL_DESCRIPTION
+        if not custom_plan_tool_descriptions:
+            custom_plan_tool_descriptions = {}
+
+        write_plan_tool_description = custom_plan_tool_descriptions.get(
+            "write_plan",
+            _DEFAULT_WRITE_PLAN_TOOL_DESCRIPTION,
         )
-        finish_sub_plan_tool_description = (
-            finish_sub_plan_tool_description
-            or _DEFAULT_FINISH_SUB_PLAN_TOOL_DESCRIPTION
+        finish_sub_plan_tool_description = custom_plan_tool_descriptions.get(
+            "finish_sub_plan",
+            _DEFAULT_FINISH_SUB_PLAN_TOOL_DESCRIPTION,
         )
-        read_plan_tool_description = (
-            read_plan_tool_description or _DEFAULT_READ_PLAN_TOOL_DESCRIPTION
+        read_plan_tool_description = custom_plan_tool_descriptions.get(
+            "read_plan",
+            _DEFAULT_READ_PLAN_TOOL_DESCRIPTION,
         )
 
         tools = [
-            create_write_plan_tool(description=write_plan_tool_description),
-            create_finish_sub_plan_tool(description=finish_sub_plan_tool_description),
+            _create_write_plan_tool(description=write_plan_tool_description),
+            _create_finish_sub_plan_tool(description=finish_sub_plan_tool_description),
         ]
 
         if use_read_plan_tool:
-            tools.append(create_read_plan_tool(description=read_plan_tool_description))
+            tools.append(_create_read_plan_tool(description=read_plan_tool_description))
 
         if system_prompt is None:
             if use_read_plan_tool:

langchain_dev_utils/chat_models/adapters/openai_compatible.py

@@ -134,9 +134,8 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
     from other model providers.
 
     **2. Dynamically adapts to choose the most suitable structured-output method**
-    OpenAICompatibleChatModel adds method="auto" (default), which selects the best
-    structured-output method (function_calling or json_schema) based on the actual
-    capabilities of the model provider.
+    OpenAICompatibleChatModel selects the best structured-output method (function_calling or json_schema)
+    based on the actual capabilities of the model provider.
 
     **3. Supports configuration of related parameters**
     For cases where parameters differ from the official OpenAI API, this library
@@ -527,11 +526,10 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
         schema: Optional[_DictOrPydanticClass] = None,
         *,
         method: Literal[
-            "auto",
             "function_calling",
             "json_mode",
             "json_schema",
-        ] = "auto",
+        ] = "json_schema",
         include_raw: bool = False,
         strict: Optional[bool] = None,
         **kwargs: Any,
@@ -545,7 +543,7 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
 
         Args:
             schema: Output schema (Pydantic model class or dictionary definition)
-            method: Extraction method - defaults to auto,it will choice best method based on provider supported response format
+            method: Extraction method - defaults to json_schema, it the provider doesn't support json_schema, it will fallback to function_calling
             include_raw: Whether to include raw model response alongside parsed output
             strict: Schema enforcement strictness (provider-dependent)
             **kwargs: Additional structured output parameters
@@ -553,16 +551,11 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
         Returns:
             Runnable configured for structured output extraction
         """
-        if method not in ["auto", "function_calling", "json_mode", "json_schema"]:
+        if method not in ["function_calling", "json_mode", "json_schema"]:
             raise ValueError(
-                f"Unsupported method: {method}. Please choose from 'auto', 'function_calling', 'json_mode', 'json_schema'."
+                f"Unsupported method: {method}. Please choose from 'function_calling', 'json_mode', 'json_schema'."
             )
-        if method == "auto":
-            if "json_schema" in self.supported_response_format:
-                method = "json_schema"
-            else:
-                method = "function_calling"
-        elif (
+        if (
             method == "json_schema"
             and "json_schema" not in self.supported_response_format
         ):

{langchain_dev_utils-1.3.1.dist-info → langchain_dev_utils-1.3.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-dev-utils
-Version: 1.3.1
+Version: 1.3.2
 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.1.dist-info → langchain_dev_utils-1.3.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-langchain_dev_utils/__init__.py,sha256=-ypEJktJToAL9by62JJKWEzDo_KPCQtmE5kwFgX24z4,22
+langchain_dev_utils/__init__.py,sha256=HgKA3RqZvC7slo8MgLyffCGwJbQ3cY6I7oUMFvGLWps,22
 langchain_dev_utils/_utils.py,sha256=MFEzR1BjXMj6HEVwt2x2omttFuDJ_rYAEbNqe99r9pM,1338
 langchain_dev_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langchain_dev_utils/agents/__init__.py,sha256=PJ-lSDZv_AXMYA3H4fx-HzJa14tPbkGmq1HX8LNfaPo,125
@@ -6,12 +6,12 @@ langchain_dev_utils/agents/factory.py,sha256=8XB6y_ddf58vXlTLHBL6KCirFqkD2Gjtzsu
 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=RuchoH_VotPmKFuYEn2SXoSgNxZhSA9jKM0Iv_8oHLk,4718
-langchain_dev_utils/agents/middleware/__init__.py,sha256=n3PsbL8LSmariEe94rUMoT0GnUQMrZUNdSj-z4om2cY,962
+langchain_dev_utils/agents/middleware/__init__.py,sha256=QVQibaNHvHPyNTZ2UNFfYL153ZboaCHcoioTHK0FsiY,710
 langchain_dev_utils/agents/middleware/format_prompt.py,sha256=LzYiQXCRvkpfDhGPxhZwdepeU3j-HUWPJqcx3FWsfT4,2357
-langchain_dev_utils/agents/middleware/handoffs.py,sha256=aCD90yTiAPyG8pC_DAr0eDi-iYW57W0wt6LzIoKLT_Y,5024
+langchain_dev_utils/agents/middleware/handoffs.py,sha256=hYtm6NKUvfJQ_fxtTBuvEay185_RCB0yXAEdgSL7-Ls,6721
 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=0qDCmenxgY_zrwMfOyYlgLfhYNw-HszNLeeOkfj14NA,16002
+langchain_dev_utils/agents/middleware/plan.py,sha256=-ZLkp85QQTSCX9thMblacJ1N86h0BYPoTwCfJlJ_jzQ,14981
 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
@@ -20,7 +20,7 @@ langchain_dev_utils/chat_models/__init__.py,sha256=YSLUyHrWEEj4y4DtGFCOnDW02VIYZ
 langchain_dev_utils/chat_models/base.py,sha256=BzaoCIv145eE8b5wNDsbZDHn4EAxe4vdlptp7qXPWKk,11625
 langchain_dev_utils/chat_models/types.py,sha256=MD3cv_ZIe9fCdgwisNfuxAOhy-j4YSs1ZOQYyCjlNKs,927
 langchain_dev_utils/chat_models/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-langchain_dev_utils/chat_models/adapters/openai_compatible.py,sha256=PkOoYNwp2kEhXalUHXCCAnL7LXfeiNoeiQ678suEse4,24492
+langchain_dev_utils/chat_models/adapters/openai_compatible.py,sha256=ws1CTZhyl8gxoY_RCLsV3cDgc8d7yDLWUa6ZfloxuMs,24239
 langchain_dev_utils/embeddings/__init__.py,sha256=zbEOaV86TUi9Zrg_dH9dpdgacWg31HMJTlTQknA9EKk,244
 langchain_dev_utils/embeddings/base.py,sha256=BGoWY0L7nG9iRV3d4sSagXhECXrwvS1xA-A_OVltn3k,9406
 langchain_dev_utils/message_convert/__init__.py,sha256=ZGrHGXPKMrZ_p9MqfIVZ4jgbEyb7aC4Q7X-muuThIYU,457
@@ -33,7 +33,7 @@ langchain_dev_utils/pipeline/types.py,sha256=T3aROKKXeWvd0jcH5XkgMDQfEkLfPaiOhhV
 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.1.dist-info/METADATA,sha256=6UJeWibp3qpwITK0THhTdFpM8tq7XyLyoUvbkMnRhLc,4552
-langchain_dev_utils-1.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-langchain_dev_utils-1.3.1.dist-info/licenses/LICENSE,sha256=AWAOzNEcsvCEzHOF0qby5OKxviVH_eT9Yce1sgJTico,1084
-langchain_dev_utils-1.3.1.dist-info/RECORD,,
+langchain_dev_utils-1.3.2.dist-info/METADATA,sha256=PLQKHjjqwlL9lvaW3Et1q0gYbZTtRdmTN6w5A4gJiYM,4552
+langchain_dev_utils-1.3.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+langchain_dev_utils-1.3.2.dist-info/licenses/LICENSE,sha256=AWAOzNEcsvCEzHOF0qby5OKxviVH_eT9Yce1sgJTico,1084
+langchain_dev_utils-1.3.2.dist-info/RECORD,,