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

langchain_dev_utils/__init__.py

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

langchain_dev_utils/_utils.py

@@ -0,0 +1,131 @@
+from importlib import util
+from typing import Literal, Optional
+
+from pydantic import BaseModel
+
+
+def _check_pkg_install(
+    pkg: Literal["langchain_openai", "json_repair"],
+) -> None:
+    if not util.find_spec(pkg):
+        if pkg == "langchain_openai":
+            msg = "Please install langchain_dev_utils[standard],when use 'openai-compatible'"
+        else:
+            msg = "Please install langchain_dev_utils[standard] to use ToolCallRepairMiddleware."
+        raise ImportError(msg)
+
+
+def _get_base_url_field_name(model_cls: type[BaseModel]) -> str | None:
+    """
+    Return 'base_url' if the model has a field named or aliased as 'base_url',
+    else return 'api_base' if it has a field named or aliased as 'api_base',
+    else return None.
+    The return value is always either 'base_url', 'api_base', or None.
+    """
+    model_fields = model_cls.model_fields
+
+    # try model_fields first
+    if "base_url" in model_fields:
+        return "base_url"
+
+    if "api_base" in model_fields:
+        return "api_base"
+
+    # then try aliases
+    for field_info in model_fields.values():
+        if field_info.alias == "base_url":
+            return "base_url"
+
+    for field_info in model_fields.values():
+        if field_info.alias == "api_base":
+            return "api_base"
+
+    return None
+
+
+def _validate_base_url(base_url: Optional[str] = None) -> None:
+    """Validate base URL format.
+
+    Args:
+        base_url: Base URL to validate
+
+    Raises:
+        ValueError: If base URL is not a valid HTTP or HTTPS URL
+    """
+    if base_url is None:
+        return
+
+    from urllib.parse import urlparse
+
+    parsed = urlparse(base_url.strip())
+
+    if not parsed.scheme or not parsed.netloc:
+        raise ValueError(
+            f"base_url must be a valid HTTP or HTTPS URL. Received: {base_url}"
+        )
+
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"base_url must use HTTP or HTTPS protocol. Received: {parsed.scheme}"
+        )
+
+
+def _validate_model_cls_name(model_cls_name: str) -> None:
+    """Validate model class name follows Python naming conventions.
+
+    Args:
+        model_cls_name: Class name to validate
+
+    Raises:
+        ValueError: If class name is invalid
+    """
+    if not model_cls_name:
+        raise ValueError("model_cls_name cannot be empty")
+
+    if not model_cls_name[0].isalpha():
+        raise ValueError(
+            f"model_cls_name must start with a letter. Received: {model_cls_name}"
+        )
+
+    if not all(c.isalnum() or c == "_" for c in model_cls_name):
+        raise ValueError(
+            f"model_cls_name can only contain letters, numbers, and underscores. Received: {model_cls_name}"
+        )
+
+    if model_cls_name[0].islower():
+        raise ValueError(
+            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.
+
+    Args:
+        provider_name: Provider name to validate
+
+    Raises:
+        ValueError: If provider name is invalid
+    """
+    if not provider_name:
+        raise ValueError("provider_name cannot be empty")
+
+    if not provider_name[0].isalnum():
+        raise ValueError(
+            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):
+        raise ValueError(
+            f"provider_name can only contain letters, numbers, underscores. Received: {provider_name}"
+        )
+
+    if len(provider_name) > 20:
+        raise ValueError(
+            f"provider_name must be 20 characters or fewer. Received: {provider_name}"
+        )

langchain_dev_utils/agents/__init__.py

@@ -0,0 +1,4 @@
+from .factory import create_agent
+from .wrap import wrap_agent_as_tool, wrap_all_agents_as_tool
+
+__all__ = ["create_agent", "wrap_agent_as_tool", "wrap_all_agents_as_tool"]

langchain_dev_utils/agents/factory.py

@@ -0,0 +1,99 @@
+from typing import Any, Callable, Sequence
+
+from langchain.agents import create_agent as _create_agent
+from langchain.agents.middleware.types import (
+    AgentMiddleware,
+    AgentState,
+    ResponseT,
+    StateT_co,
+    _InputAgentState,
+    _OutputAgentState,
+)
+from langchain.agents.structured_output import ResponseFormat
+from langchain_core.messages import SystemMessage
+from langchain_core.tools import BaseTool
+from langgraph.cache.base import BaseCache
+from langgraph.graph.state import CompiledStateGraph
+from langgraph.store.base import BaseStore
+from langgraph.types import Checkpointer
+from langgraph.typing import ContextT
+
+from ..chat_models import load_chat_model
+
+
+def create_agent(  # noqa: PLR0915
+    model: str,
+    tools: Sequence[BaseTool | Callable | dict[str, Any]] | None = None,
+    *,
+    system_prompt: str | SystemMessage | None = None,
+    response_format: ResponseFormat[ResponseT] | type[ResponseT] | None = None,
+    middleware: Sequence[AgentMiddleware[StateT_co, ContextT]] = (),
+    state_schema: type[AgentState[ResponseT]] | None = None,
+    context_schema: type[ContextT] | None = None,
+    checkpointer: Checkpointer | None = None,
+    store: BaseStore | None = None,
+    interrupt_before: list[str] | None = None,
+    interrupt_after: list[str] | None = None,
+    debug: bool = False,
+    name: str | None = None,
+    cache: BaseCache | None = None,
+) -> CompiledStateGraph[
+    AgentState[ResponseT], ContextT, _InputAgentState, _OutputAgentState[ResponseT]
+]:
+    """
+    Create a prebuilt agent with string-based model specification.
+
+    This function provides the same functionality as the official `create_react_agent`,
+    but with the constraint that the model parameter must be a string that can be
+    loaded by the `load_chat_model` function. This allows for more flexible model
+    specification using the registered model providers.
+
+    Args:
+        model: Model identifier string that can be loaded by `load_chat_model`.
+               Can be specified as "provider:model-name" format.
+        *: All other parameters are the same as in langchain.agents.create_agent.
+           See langchain.agents.create_agent for documentation on available parameters.
+
+    Returns:
+        CompiledStateGraph: A compiled state graph representing the agent.
+
+    Raises:
+        ValueError: If the model string cannot be loaded by load_chat_model.
+
+    Example:
+        >>> from langchain_dev_utils.chat_models import register_model_provider
+        >>> from langchain_dev_utils.agents import create_agent
+        >>>
+        # Register a model provider, must be done before creating the agent
+        >>> register_model_provider(
+        ...     provider_name="vllm",
+        ...     chat_model="openai-compatible",
+        ...     base_url="http://localhost:8000/v1",
+        ... )
+        >>>
+        >>> agent = create_agent(
+        ...     "vllm:qwen3-4b",
+        ...     tools=[get_current_time],
+        ...     name="time-agent"
+        ... )
+        >>> response = agent.invoke({
+        ...     "messages": [{"role": "user", "content": "What's the time?"}]
+        ... })
+        >>> response
+    """
+    return _create_agent(
+        model=load_chat_model(model),
+        tools=tools,
+        system_prompt=system_prompt,
+        middleware=middleware,
+        response_format=response_format,
+        state_schema=state_schema,
+        context_schema=context_schema,
+        checkpointer=checkpointer,
+        store=store,
+        interrupt_before=interrupt_before,
+        interrupt_after=interrupt_after,
+        debug=debug,
+        name=name,
+        cache=cache,
+    )

langchain_dev_utils/agents/file_system.py

@@ -0,0 +1,252 @@
+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/middleware/__init__.py

@@ -0,0 +1,21 @@
+from .format_prompt import format_prompt
+from .handoffs import HandoffAgentMiddleware
+from .model_fallback import ModelFallbackMiddleware
+from .model_router import ModelRouterMiddleware
+from .plan import PlanMiddleware
+from .summarization import SummarizationMiddleware
+from .tool_call_repair import ToolCallRepairMiddleware
+from .tool_emulator import LLMToolEmulator
+from .tool_selection import LLMToolSelectorMiddleware
+
+__all__ = [
+    "SummarizationMiddleware",
+    "LLMToolSelectorMiddleware",
+    "PlanMiddleware",
+    "ModelFallbackMiddleware",
+    "LLMToolEmulator",
+    "ModelRouterMiddleware",
+    "ToolCallRepairMiddleware",
+    "format_prompt",
+    "HandoffAgentMiddleware",
+]

langchain_dev_utils/agents/middleware/format_prompt.py

@@ -0,0 +1,66 @@
+from langchain.agents.middleware import ModelRequest, dynamic_prompt
+from langchain_core.prompts.string import get_template_variables
+
+
+@dynamic_prompt
+def format_prompt(request: ModelRequest) -> str:
+    """Format the system prompt with variables from state and context.
+
+    This middleware function extracts template variables from the system prompt
+    and populates them with values from the agent's state and runtime context.
+    Variables are first resolved from the state, then from the context if not found.
+
+    Example:
+        >>> from langchain_dev_utils.agents.middleware import format_prompt
+        >>> from langchain.agents import create_agent
+        >>> from langchain_core.messages import HumanMessage
+        >>> from dataclasses import dataclass
+        >>>
+        >>> @dataclass
+        ... class Context:
+        ...       name: str
+        ...       user: str
+        >>>
+        >>> agent=create_agent(
+        ...     model=model,
+        ...     tools=tools,
+        ...     system_prompt="You are a helpful assistant. Your name is {name}. Your user is {user}.",
+        ...     middleware=[format_prompt],
+        ...     context_schema=Context,
+        ... )
+        >>> agent.invoke(
+        ...     {
+        ...         "messages": [HumanMessage(content="Hello")],
+        ...     },
+        ...     context=Context(name="assistant", user="Tom"),
+        ... )
+
+    """
+    system_msg = request.system_message
+    if system_msg is None:
+        raise ValueError(
+            "system_message must be provided,while use format_prompt in middleware."
+        )
+
+    system_prompt = "\n".join(
+        [content.get("text", "") for content in system_msg.content_blocks]
+    )
+    variables = get_template_variables(system_prompt, "f-string")
+
+    format_params = {}
+
+    state = request.state
+    for key in variables:
+        if var := state.get(key, None):
+            format_params[key] = var
+
+    other_var_keys = set(variables) - set(format_params.keys())
+
+    if other_var_keys:
+        context = request.runtime.context
+        if context is not None:
+            for key in other_var_keys:
+                if var := getattr(context, key, None):
+                    format_params[key] = var
+
+    return system_prompt.format(**format_params)