langchain-dev-utils 1.2.16__tar.gz → 1.3.1__tar.gz

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-dev-utils
-Version: 1.2.16
+Version: 1.3.1
 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
@@ -8,7 +8,8 @@ Project-URL: documentation, https://tbice123123.github.io/langchain-dev-utils
 Author-email: tiebingice <tiebingice123@outlook.com>
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: langchain>=1.1.0
+Requires-Dist: langchain-core>=1.2.5
+Requires-Dist: langchain>=1.2.0
 Requires-Dist: langgraph>=1.0.0
 Provides-Extra: standard
 Requires-Dist: json-repair>=0.53.1; extra == 'standard'

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/pyproject.toml

@@ -1,50 +1,47 @@
-[project]
-name = "langchain-dev-utils"
-version = "1.2.16"
-description = "A practical utility library for LangChain and LangGraph development"
-readme = "README.md"
-authors = [{ name = "tiebingice", email = "tiebingice123@outlook.com" }]
-requires-python = ">=3.11"
-dependencies = [
-    "langchain>=1.1.0",
-    "langgraph>=1.0.0",
-]
-
-[project.urls]
-"Source Code" = "https://github.com/TBice123123/langchain-dev-utils"
-repository = "https://github.com/TBice123123/langchain-dev-utils"
-documentation = "https://tbice123123.github.io/langchain-dev-utils"
-
-
-[project.optional-dependencies]
-standard = ["json-repair>=0.53.1", "langchain-openai"]
-
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build]
-exclude = ["/data", "/docs", "mkdocs.yml"]
-
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_functions = ["test_*"]
-
-[dependency-groups]
-dev = ["langchain-model-profiles>=0.0.5", "ruff>=0.14.5"]
-docs = ["mkdocs-material>=9.7.0", "mkdocs-static-i18n>=1.3.0"]
-tests = [
-    "python-dotenv>=1.1.1",
-    "langchain-tests>=1.0.0",
-    "langchain-deepseek>=1.0.0",
-    "langchain-qwq>=0.3.0",
-    "langchain-ollama>=1.0.0",
-    "langchain-community>=0.4.1",
-]
-
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "PGH003", "T201"]
-ignore = ["E501"]
+[project]
+name = "langchain-dev-utils"
+version = "1.3.1"
+description = "A practical utility library for LangChain and LangGraph development"
+readme = "README.md"
+authors = [{ name = "tiebingice", email = "tiebingice123@outlook.com" }]
+requires-python = ">=3.11"
+dependencies = ["langchain>=1.2.0", "langchain-core>=1.2.5", "langgraph>=1.0.0"]
+
+[project.urls]
+"Source Code" = "https://github.com/TBice123123/langchain-dev-utils"
+repository = "https://github.com/TBice123123/langchain-dev-utils"
+documentation = "https://tbice123123.github.io/langchain-dev-utils"
+
+
+[project.optional-dependencies]
+standard = ["json-repair>=0.53.1", "langchain-openai"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = ["/data", "/docs", "mkdocs.yml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+
+[dependency-groups]
+dev = ["langchain-model-profiles>=0.0.5", "ruff>=0.14.5"]
+docs = ["mkdocs-material>=9.7.0", "mkdocs-static-i18n>=1.3.0"]
+tests = [
+    "python-dotenv>=1.1.1",
+    "langchain-tests>=1.0.0",
+    "langchain-deepseek>=1.0.0",
+    "langchain-qwq>=0.3.0",
+    "langchain-ollama>=1.0.0",
+    "langchain-community>=0.4.1",
+]
+
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "PGH003", "T201"]
+ignore = ["E501"]

langchain_dev_utils-1.3.1/src/langchain_dev_utils/__init__.py

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

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/src/langchain_dev_utils/agents/factory.py

@@ -5,9 +5,9 @@ from langchain.agents.middleware.types import (
     AgentMiddleware,
     AgentState,
     ResponseT,
+    StateT_co,
     _InputAgentState,
     _OutputAgentState,
-    StateT_co,
 )
 from langchain.agents.structured_output import ResponseFormat
 from langchain_core.messages import SystemMessage

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/src/langchain_dev_utils/agents/middleware/__init__.py

@@ -1,4 +1,5 @@
 from .format_prompt import format_prompt
+from .handoffs import HandoffsAgentMiddleware, create_handoffs_tool
 from .model_fallback import ModelFallbackMiddleware
 from .model_router import ModelRouterMiddleware
 from .plan import (
@@ -24,4 +25,6 @@ __all__ = [
     "ModelRouterMiddleware",
     "ToolCallRepairMiddleware",
     "format_prompt",
+    "create_handoffs_tool",
+    "HandoffsAgentMiddleware",
 ]

langchain_dev_utils-1.3.1/src/langchain_dev_utils/agents/middleware/handoffs.py

@@ -0,0 +1,138 @@
+from typing import Any, Awaitable, Callable
+
+from langchain.agents import AgentState
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+from langchain.agents.middleware.types import ModelCallResult
+from langchain.tools import BaseTool, ToolRuntime, tool
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import SystemMessage, ToolMessage
+from langgraph.types import Command
+from typing_extensions import NotRequired, Optional, TypedDict
+
+from langchain_dev_utils.chat_models import load_chat_model
+
+
+class MultiAgentState(AgentState):
+    active_agent: NotRequired[str]
+
+
+class AgentConfig(TypedDict):
+    model: NotRequired[str | BaseChatModel]
+    prompt: str | SystemMessage
+    tools: list[BaseTool | dict[str, Any]]
+    default: NotRequired[bool]
+
+
+def create_handoffs_tool(
+    agent_name: str,
+    tool_name: Optional[str] = None,
+    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"
+
+    if tool_description is None:
+        tool_description = f"Transfer to the {agent_name}"
+
+    @tool(name_or_callable=tool_name, description=tool_description)
+    def handoffs_tool(runtime: ToolRuntime) -> Command:
+        return Command(
+            update={
+                "messages": [
+                    ToolMessage(
+                        content=f"Transferred to {agent_name}",
+                        tool_call_id=runtime.tool_call_id,
+                    )
+                ],
+                "active_agent": agent_name,
+            }
+        )
+
+    return handoffs_tool
+
+
+def _get_default_active_agent(state: dict[str, AgentConfig]) -> Optional[str]:
+    for agent_name, config in state.items():
+        if config.get("default", False):
+            return agent_name
+    return None
+
+
+class HandoffsAgentMiddleware(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.
+
+    Examples:
+        ```python
+        from langchain_dev_utils.agents.middleware import HandoffsAgentMiddleware
+        middleware = HandoffsAgentMiddleware(agents_config)
+        ```
+    """
+
+    state_schema = MultiAgentState
+
+    def __init__(self, agents_config: dict[str, AgentConfig]):
+        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"
+            )
+        self.default_agent_name = default_agent_name
+        self.agents_config = agents_config
+
+    def _get_active_agent_config(self, request: ModelRequest) -> dict[str, Any]:
+        active_agent_name = request.state.get("active_agent", self.default_agent_name)
+
+        _config = self.agents_config[active_agent_name]
+
+        params = {}
+        if _config.get("model"):
+            model = _config.get("model")
+            if isinstance(model, str):
+                model = load_chat_model(model)
+            params["model"] = model
+        if _config.get("prompt"):
+            params["system_prompt"] = _config.get("prompt")
+        if _config.get("tools"):
+            params["tools"] = _config.get("tools")
+        return params
+
+    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)
+
+    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)

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/src/langchain_dev_utils/agents/middleware/model_fallback.py

@@ -22,7 +22,7 @@ class ModelFallbackMiddleware(_ModelFallbackMiddleware):
 
         fallback = ModelFallbackMiddleware(
             "vllm:qwen3-8b", ## Try first on error
-            "openrouter:meta-llama/llama-3.3-8b-instruct:free" #Then this
+            "vllm:gpt-oss-20b", #Then this
         )
 
         agent = create_agent(
@@ -30,7 +30,7 @@ class ModelFallbackMiddleware(_ModelFallbackMiddleware):
             middleware=[fallback],
         )
 
-        # If primary fails: tries qwen3-8b, then llama-3.3-8b-instruct
+        # If primary fails: tries qwen3-8b, then gpt-oss-20b
         result = await agent.invoke({"messages": [HumanMessage("Hello")]})
         ```
     """

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/src/langchain_dev_utils/chat_models/adapters/openai_compatible.py

@@ -126,13 +126,12 @@ class _BaseChatOpenAICompatible(BaseChatOpenAI):
     Base template class for OpenAI-compatible chat model implementations.
 
     This class provides a foundation for integrating various LLM providers that
-    offer OpenAI-compatible APIs (such as vLLM, OpenRouter, ZAI, Moonshot,
-    and many others). It enhances the base OpenAI functionality by:
+    offer OpenAI-compatible APIs. It enhances the base OpenAI functionality by:
 
     **1. Supports output of more types of reasoning content (reasoning_content)**
     ChatOpenAI can only output reasoning content natively supported by official
     OpenAI models, while OpenAICompatibleChatModel can output reasoning content
-    from other model providers (e.g., OpenRouter, vLLM).
+    from other model providers.
 
     **2. Dynamically adapts to choose the most suitable structured-output method**
     OpenAICompatibleChatModel adds method="auto" (default), which selects the best
@@ -593,7 +592,7 @@ def _create_openai_compatible_model(
     configuring environment variable mappings and default base URLs specific to each provider.
 
     Args:
-        provider: Provider identifier (e.g., `vllm`,`openrouter`)
+        provider: Provider identifier (e.g.`vllm`)
         base_url: Default API base URL for the provider
         compatibility_options: Optional configuration for the provider
 

{langchain_dev_utils-1.2.16 → langchain_dev_utils-1.3.1}/tests/__init__.py

@@ -5,7 +5,6 @@ from .utils.register import (
     register_all_model_providers,
 )
 
-
 load_dotenv()
 register_all_model_providers()
 register_all_embeddings_providers()

langchain_dev_utils-1.3.1/tests/test_handoffs_middleware.py

@@ -0,0 +1,75 @@
+from datetime import datetime
+from langchain.tools import tool
+from langchain_core.messages import HumanMessage, ToolMessage
+from langchain_dev_utils.agents import create_agent
+from langchain_dev_utils.agents.middleware import (
+    HandoffsAgentMiddleware,
+    create_handoffs_tool,
+)
+from langchain_dev_utils.agents.middleware.handoffs import AgentConfig
+from tests.utils.register import register_all_model_providers
+
+register_all_model_providers()
+
+transfer_time_agent = create_handoffs_tool("time_agent")
+transfer_talk_agent = create_handoffs_tool("talk_agent")
+
+
+@tool
+def get_current_time() -> str:
+    """Get the current time."""
+    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+agents_config: dict[str, AgentConfig] = {
+    "time_agent": {
+        "model": "zai:glm-4.5",
+        "prompt": "你是一个时间助手，你可以回答用户的时间相关问题",
+        "tools": [transfer_talk_agent, get_current_time],
+    },
+    "talk_agent": {
+        "prompt": "你是一个对话助手，你可以回答用户的问题",
+        "tools": [transfer_time_agent],
+        "default": True,
+    },
+}
+
+
+def test_handoffs_middleware():
+    agent = create_agent(
+        model="dashscope:qwen-flash",
+        middleware=[HandoffsAgentMiddleware(agents_config)],
+        tools=[
+            get_current_time,
+            transfer_time_agent,
+            transfer_talk_agent,
+        ],
+    )
+
+    response = agent.invoke({"messages": [HumanMessage(content="get current time")]})
+
+    assert response
+    assert response["messages"][-1].response_metadata.get("model_name") == "glm-4.5"
+    assert isinstance(response["messages"][-2], ToolMessage)
+    assert "active_agent" in response and response["active_agent"] == "time_agent"
+
+
+async def test_handoffs_middleware_async():
+    agent = create_agent(
+        model="dashscope:qwen-flash",
+        middleware=[HandoffsAgentMiddleware(agents_config)],
+        tools=[
+            get_current_time,
+            transfer_time_agent,
+            transfer_talk_agent,
+        ],
+    )
+
+    response = await agent.ainvoke(
+        {"messages": [HumanMessage(content="get current time")]}
+    )
+
+    assert response
+    assert response["messages"][-1].response_metadata.get("model_name") == "glm-4.5"
+    assert isinstance(response["messages"][-2], ToolMessage)
+    assert "active_agent" in response and response["active_agent"] == "time_agent"