langchain-dev-utils 1.3.7__py3-none-any.whl

langchain_dev_utils/agents/plan.py

@@ -0,0 +1,188 @@
+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

langchain_dev_utils/agents/wrap.py

@@ -0,0 +1,324 @@
+import asyncio
+from typing import Any, Awaitable, Callable, Optional
+
+from langchain.tools import ToolRuntime
+from langchain_core.messages import HumanMessage
+from langchain_core.tools import BaseTool, StructuredTool
+from langgraph.graph.state import CompiledStateGraph
+
+from langchain_dev_utils.message_convert import format_sequence
+
+
+def _process_input(request: str, runtime: ToolRuntime) -> str:
+    return request
+
+
+def _process_output(
+    request: str, response: dict[str, Any], runtime: ToolRuntime
+) -> Any:
+    return response["messages"][-1].content
+
+
+def wrap_agent_as_tool(
+    agent: CompiledStateGraph,
+    tool_name: Optional[str] = None,
+    tool_description: Optional[str] = None,
+    pre_input_hooks: Optional[
+        tuple[
+            Callable[[str, ToolRuntime], str | dict[str, Any]],
+            Callable[[str, ToolRuntime], Awaitable[str | dict[str, Any]]],
+        ]
+        | Callable[[str, ToolRuntime], str | dict[str, Any]]
+    ] = None,
+    post_output_hooks: Optional[
+        tuple[
+            Callable[[str, dict[str, Any], ToolRuntime], Any],
+            Callable[[str, dict[str, Any], ToolRuntime], Awaitable[Any]],
+        ]
+        | Callable[[str, dict[str, Any], ToolRuntime], Any]
+    ] = None,
+) -> BaseTool:
+    """Wraps an agent as a tool
+
+    Args:
+        agent: The agent to wrap
+        tool_name: The name of the tool
+        tool_description: The description of the tool
+        pre_input_hooks: Hooks to run before the input is processed
+        post_output_hooks: Hooks to run after the output is processed
+
+    Returns:
+        BaseTool: The wrapped agent as a tool
+
+    Example:
+        >>> from langchain_dev_utils.agents import wrap_agent_as_tool, create_agent
+        >>>
+        >>> call_time_agent_tool = wrap_agent_as_tool(
+        ...     time_agent,
+        ...     tool_name="call_time_agent",
+        ...     tool_description="Used to invoke the time sub-agent to perform time-related tasks"
+        ... )
+        >>>
+        >>> agent = create_agent("vllm:qwen3-4b", tools=[call_time_agent_tool], name="agent")
+
+        >>> response = agent.invoke({"messages": [HumanMessage(content="What time is it now?")]})
+        >>> response
+    """
+    if agent.name is None:
+        raise ValueError("Agent name must not be None")
+
+    process_input = _process_input
+    process_input_async = _process_input
+    process_output = _process_output
+    process_output_async = _process_output
+
+    if pre_input_hooks:
+        if isinstance(pre_input_hooks, tuple):
+            process_input = pre_input_hooks[0]
+            process_input_async = pre_input_hooks[1]
+        else:
+            process_input = pre_input_hooks
+            process_input_async = pre_input_hooks
+
+    if post_output_hooks:
+        if isinstance(post_output_hooks, tuple):
+            process_output = post_output_hooks[0]
+            process_output_async = post_output_hooks[1]
+        else:
+            process_output = post_output_hooks
+            process_output_async = post_output_hooks
+
+    def call_agent(
+        request: str,
+        runtime: ToolRuntime,
+    ):
+        _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")
+
+        response = agent.invoke(agent_input)
+
+        response = (
+            process_output(request, response, runtime)
+            if process_output
+            else response["messages"][-1].content
+        )
+        return response
+
+    async def acall_agent(
+        request: str,
+        runtime: ToolRuntime,
+    ):
+        if asyncio.iscoroutinefunction(process_input_async):
+            _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:
+            raise ValueError("Pre Hooks must return a string or a dict")
+
+        response = await agent.ainvoke(agent_input)
+
+        if asyncio.iscoroutinefunction(process_output_async):
+            response = await process_output_async(request, response, runtime)
+        else:
+            response = (
+                process_output(request, response, runtime)
+                if process_output
+                else response["messages"][-1].content
+            )
+
+        return response
+
+    if tool_name is None:
+        tool_name = f"transfor_to_{agent.name}"
+        if not tool_name.endswith("_agent"):
+            tool_name += "_agent"
+
+    if tool_description is None:
+        tool_description = f"This tool transforms input to {agent.name}"
+
+    return StructuredTool.from_function(
+        func=call_agent,
+        coroutine=acall_agent,
+        name=tool_name,
+        description=tool_description,
+    )
+
+
+def wrap_all_agents_as_tool(
+    agents: list[CompiledStateGraph],
+    tool_name: Optional[str] = None,
+    tool_description: Optional[str] = None,
+    pre_input_hooks: Optional[
+        tuple[
+            Callable[[str, ToolRuntime], str | dict[str, Any]],
+            Callable[[str, ToolRuntime], Awaitable[str | dict[str, Any]]],
+        ]
+        | Callable[[str, ToolRuntime], str | dict[str, Any]]
+    ] = None,
+    post_output_hooks: Optional[
+        tuple[
+            Callable[[str, dict[str, Any], ToolRuntime], Any],
+            Callable[[str, dict[str, Any], ToolRuntime], Awaitable[Any]],
+        ]
+        | Callable[[str, dict[str, Any], ToolRuntime], Any]
+    ] = None,
+) -> BaseTool:
+    """Wraps all agents as single tool
+
+    Args:
+        agents: The agents to wrap
+        tool_name: The name of the tool, default to "task"
+        tool_description: The description of the tool
+        pre_input_hooks: Hooks to run before the input is processed
+        post_output_hooks: Hooks to run after the output is processed
+
+    Returns:
+        BaseTool: The wrapped agents as single tool
+
+    Example:
+        >>> from langchain_dev_utils.agents import wrap_all_agents_as_tool, create_agent
+        >>>
+        >>> call_agent_tool = wrap_all_agents_as_tool(
+        ...     [time_agent,weather_agent],
+        ...     tool_name="call_sub_agents",
+        ...     tool_description="Used to invoke the sub-agents to perform tasks"
+        ... )
+        >>>
+        >>> agent = create_agent("vllm:qwen3-4b", tools=[call_sub_agents_tool], name="agent")
+
+        >>> response = agent.invoke({"messages": [HumanMessage(content="What time is it now?")]})
+        >>> response
+    """
+    if len(agents) <= 1:
+        raise ValueError("At least more than one agent must be provided")
+
+    agents_map = {}
+
+    for agent in agents:
+        if agent.name is None:
+            raise ValueError("Agent name must not be provided")
+        if agent.name in agents_map:
+            raise ValueError("Agent name must be unique")
+        agents_map[agent.name] = agent
+
+    process_input = _process_input
+    process_input_async = _process_input
+    process_output = _process_output
+    process_output_async = _process_output
+
+    if pre_input_hooks:
+        if isinstance(pre_input_hooks, tuple):
+            process_input = pre_input_hooks[0]
+            process_input_async = pre_input_hooks[1]
+        else:
+            process_input = pre_input_hooks
+            process_input_async = pre_input_hooks
+
+    if post_output_hooks:
+        if isinstance(post_output_hooks, tuple):
+            process_output = post_output_hooks[0]
+            process_output_async = post_output_hooks[1]
+        else:
+            process_output = post_output_hooks
+            process_output_async = post_output_hooks
+
+    def call_agent(
+        agent_name: str,
+        description: str,
+        runtime: ToolRuntime,
+    ):
+        if agent_name not in agents_map:
+            raise ValueError(f"Agent {agent_name} not found")
+
+        _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(description, response, runtime)
+            if process_output
+            else response["messages"][-1].content
+        )
+        return response
+
+    async def acall_agent(
+        agent_name: str,
+        description: str,
+        runtime: ToolRuntime,
+    ):
+        if agent_name not in agents_map:
+            raise ValueError(f"Agent {agent_name} not found")
+
+        if asyncio.iscoroutinefunction(process_input_async):
+            _processed_input = await process_input_async(description, runtime)
+        else:
+            _processed_input = (
+                process_input_async(description, runtime)
+                if process_input_async
+                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 = await agents_map[agent_name].ainvoke(agent_input)
+
+        if asyncio.iscoroutinefunction(process_output_async):
+            response = await process_output_async(description, response, runtime)
+        else:
+            response = (
+                process_output(description, response, runtime)
+                if process_output
+                else response["messages"][-1].content
+            )
+
+        return response
+
+    if tool_name is None:
+        tool_name = "task"
+
+    if tool_description is None:
+        tool_description = (
+            "Launch an ephemeral subagent for a task.\nAvailable agents:\n "
+            + format_sequence(list(agents_map.keys()), with_num=True)
+        )
+    return StructuredTool.from_function(
+        func=call_agent,
+        coroutine=acall_agent,
+        name=tool_name,
+        description=tool_description,
+    )

langchain_dev_utils/chat_models/__init__.py

@@ -0,0 +1,11 @@
+from .base import (
+    batch_register_model_provider,
+    load_chat_model,
+    register_model_provider,
+)
+
+__all__ = [
+    "load_chat_model",
+    "register_model_provider",
+    "batch_register_model_provider",
+]

langchain_dev_utils/chat_models/adapters/__init__.py

@@ -0,0 +1,3 @@
+from .create_utils import create_openai_compatible_model
+
+__all__ = ["create_openai_compatible_model"]

langchain_dev_utils/chat_models/adapters/create_utils.py

@@ -0,0 +1,53 @@
+from typing import Any, Optional, cast
+
+from langchain_core.utils import from_env
+
+from langchain_dev_utils._utils import _check_pkg_install
+
+from ..types import CompatibilityOptions
+
+
+def create_openai_compatible_model(
+    model_provider: str,
+    base_url: Optional[str] = None,
+    compatibility_options: Optional[CompatibilityOptions] = None,
+    model_profiles: Optional[dict[str, dict[str, Any]]] = None,
+    chat_model_cls_name: Optional[str] = None,
+):
+    """Factory function for creating provider-specific OpenAI-compatible model classes.
+
+    Dynamically generates model classes for different OpenAI-compatible providers,
+    configuring environment variable mappings and default base URLs specific to each provider.
+
+    Args:
+        model_provider (str): Identifier for the OpenAI-compatible provider (e.g. `vllm`, `moonshot`)
+        base_url (Optional[str], optional): Default API base URL for the provider. Defaults to None. If not provided, will try to use the environment variable.
+        compatibility_options (Optional[CompatibilityOptions], optional): Optional configuration for compatibility options with the provider. Defaults to None.
+        model_profiles (Optional[dict[str, dict[str, Any]]], optional): Optional model profiles for the provider. Defaults to None.
+        chat_model_cls_name (Optional[str], optional): Optional custom class name for the generated model. Defaults to None.
+    Returns:
+        Type[_BaseChatOpenAICompatible]: Configured model class ready for instantiation with provider-specific settings
+
+    Examples:
+        >>> from langchain_dev_utils.chat_models.adapters import create_openai_compatible_chat_model
+        >>> ChatVLLM = create_openai_compatible_chat_model(
+        ...     "vllm",
+        ...     base_url="http://localhost:8000",
+        ...     chat_model_cls_name="ChatVLLM",
+        ... )
+        >>> model = ChatVLLM(model="qwen3-4b")
+        >>> model.invoke("hello")
+    """
+    _check_pkg_install("langchain_openai")
+    from .openai_compatible import _create_openai_compatible_model
+
+    base_url = (
+        base_url or from_env(f"{model_provider.upper()}_API_BASE", default=None)()
+    )
+    return _create_openai_compatible_model(
+        chat_model_cls_name=chat_model_cls_name,
+        provider=model_provider,
+        base_url=cast(str, base_url),
+        compatibility_options=compatibility_options,
+        profiles=model_profiles,
+    )