langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/utils/function_calling.py

@@ -8,22 +8,26 @@ import logging
 import types
 import typing
 import uuid
+from collections.abc import Callable
 from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
-    Callable,
     Literal,
-    Optional,
     Union,
     cast,
+    get_args,
+    get_origin,
 )
 
 from pydantic import BaseModel
 from pydantic.v1 import BaseModel as BaseModelV1
-from typing_extensions import TypedDict, get_args, get_origin, is_typeddict
+from pydantic.v1 import Field as Field_v1
+from pydantic.v1 import create_model as create_model_v1
+from typing_extensions import TypedDict, is_typeddict
 
-from langchain_core._api import beta, deprecated
+import langchain_core
+from langchain_core._api import beta
 from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, ToolMessage
 from langchain_core.utils.json_schema import dereference_refs
 from langchain_core.utils.pydantic import is_basemodel_subclass
@@ -68,11 +72,11 @@ def _rm_titles(kv: dict, prev_key: str = "") -> dict:
     except when a "title" appears within a property definition under "properties".
 
     Args:
-        kv (dict): The input JSON schema as a dictionary.
-        prev_key (str): The key from the parent dictionary, used to identify context.
+        kv: The input JSON schema as a dictionary.
+        prev_key: The key from the parent dictionary, used to identify context.
 
     Returns:
-        dict: A new dictionary with appropriate "title" fields removed.
+        A new dictionary with appropriate "title" fields removed.
     """
     new_kv = {}
 
@@ -98,8 +102,8 @@ def _rm_titles(kv: dict, prev_key: str = "") -> dict:
 def _convert_json_schema_to_openai_function(
     schema: dict,
     *,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
+    name: str | None = None,
+    description: str | None = None,
     rm_titles: bool = True,
 ) -> FunctionDescription:
     """Converts a Pydantic model to a function description for the OpenAI API.
@@ -110,7 +114,7 @@ def _convert_json_schema_to_openai_function(
             used.
         description: The description of the function. If not provided, the description
             of the schema will be used.
-        rm_titles: Whether to remove titles from the schema. Defaults to True.
+        rm_titles: Whether to remove titles from the schema.
 
     Returns:
         The function description.
@@ -132,8 +136,8 @@ def _convert_json_schema_to_openai_function(
 def _convert_pydantic_to_openai_function(
     model: type,
     *,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
+    name: str | None = None,
+    description: str | None = None,
     rm_titles: bool = True,
 ) -> FunctionDescription:
     """Converts a Pydantic model to a function description for the OpenAI API.
@@ -144,7 +148,10 @@ def _convert_pydantic_to_openai_function(
             used.
         description: The description of the function. If not provided, the description
             of the schema will be used.
-        rm_titles: Whether to remove titles from the schema. Defaults to True.
+        rm_titles: Whether to remove titles from the schema.
+
+    Raises:
+        TypeError: If the model is not a Pydantic model.
 
     Returns:
         The function description.
@@ -161,42 +168,6 @@ def _convert_pydantic_to_openai_function(
     )
 
 
-convert_pydantic_to_openai_function = deprecated(
-    "0.1.16",
-    alternative="langchain_core.utils.function_calling.convert_to_openai_function()",
-    removal="1.0",
-)(_convert_pydantic_to_openai_function)
-
-
-@deprecated(
-    "0.1.16",
-    alternative="langchain_core.utils.function_calling.convert_to_openai_tool()",
-    removal="1.0",
-)
-def convert_pydantic_to_openai_tool(
-    model: type[BaseModel],
-    *,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-) -> ToolDescription:
-    """Converts a Pydantic model to a function description for the OpenAI API.
-
-    Args:
-        model: The Pydantic model to convert.
-        name: The name of the function. If not provided, the title of the schema will be
-            used.
-        description: The description of the function. If not provided, the description
-            of the schema will be used.
-
-    Returns:
-        The tool description.
-    """
-    function = _convert_pydantic_to_openai_function(
-        model, name=name, description=description
-    )
-    return {"type": "function", "function": function}
-
-
 def _get_python_function_name(function: Callable) -> str:
     """Get the name of a Python function."""
     return function.__name__
@@ -217,10 +188,8 @@ def _convert_python_function_to_openai_function(
     Returns:
         The OpenAI function description.
     """
-    from langchain_core.tools.base import create_schema_from_function
-
     func_name = _get_python_function_name(function)
-    model = create_schema_from_function(
+    model = langchain_core.tools.base.create_schema_from_function(
         func_name,
         function,
         filter_args=(),
@@ -235,13 +204,6 @@ def _convert_python_function_to_openai_function(
     )
 
 
-convert_python_function_to_openai_function = deprecated(
-    "0.1.16",
-    alternative="langchain_core.utils.function_calling.convert_to_openai_function()",
-    removal="1.0",
-)(_convert_python_function_to_openai_function)
-
-
 def _convert_typed_dict_to_openai_function(typed_dict: type) -> FunctionDescription:
     visited: dict = {}
 
@@ -261,9 +223,6 @@ def _convert_any_typed_dicts_to_pydantic(
     visited: dict,
     depth: int = 0,
 ) -> type:
-    from pydantic.v1 import Field as Field_v1
-    from pydantic.v1 import create_model as create_model_v1
-
     if type_ in visited:
         return visited[type_]
     if depth >= _MAX_TYPED_DICT_RECURSION:
@@ -277,12 +236,14 @@ def _convert_any_typed_dicts_to_pydantic(
         )
         fields: dict = {}
         for arg, arg_type in annotations_.items():
-            if get_origin(arg_type) is Annotated:
+            if get_origin(arg_type) is Annotated:  # type: ignore[comparison-overlap]
                 annotated_args = get_args(arg_type)
                 new_arg_type = _convert_any_typed_dicts_to_pydantic(
                     annotated_args[0], depth=depth + 1, visited=visited
                 )
-                field_kwargs = dict(zip(("default", "description"), annotated_args[1:]))
+                field_kwargs = dict(
+                    zip(("default", "description"), annotated_args[1:], strict=False)
+                )
                 if (field_desc := field_kwargs.get("description")) and not isinstance(
                     field_desc, str
                 ):
@@ -323,12 +284,15 @@ def _format_tool_to_openai_function(tool: BaseTool) -> FunctionDescription:
     Args:
         tool: The tool to format.
 
+    Raises:
+        ValueError: If the tool call schema is not supported.
+
     Returns:
         The function description.
     """
-    from langchain_core.tools import simple
-
-    is_simple_oai_tool = isinstance(tool, simple.Tool) and not tool.args_schema
+    is_simple_oai_tool = (
+        isinstance(tool, langchain_core.tools.simple.Tool) and not tool.args_schema
+    )
     if tool.tool_call_schema and not is_simple_oai_tool:
         if isinstance(tool.tool_call_schema, dict):
             return _convert_json_schema_to_openai_function(
@@ -361,48 +325,23 @@ def _format_tool_to_openai_function(tool: BaseTool) -> FunctionDescription:
     }
 
 
-format_tool_to_openai_function = deprecated(
-    "0.1.16",
-    alternative="langchain_core.utils.function_calling.convert_to_openai_function()",
-    removal="1.0",
-)(_format_tool_to_openai_function)
-
-
-@deprecated(
-    "0.1.16",
-    alternative="langchain_core.utils.function_calling.convert_to_openai_tool()",
-    removal="1.0",
-)
-def format_tool_to_openai_tool(tool: BaseTool) -> ToolDescription:
-    """Format tool into the OpenAI function API.
-
-    Args:
-        tool: The tool to format.
-
-    Returns:
-        The tool description.
-    """
-    function = _format_tool_to_openai_function(tool)
-    return {"type": "function", "function": function}
-
-
 def convert_to_openai_function(
-    function: Union[dict[str, Any], type, Callable, BaseTool],
+    function: dict[str, Any] | type | Callable | BaseTool,
     *,
-    strict: Optional[bool] = None,
+    strict: bool | None = None,
 ) -> dict[str, Any]:
     """Convert a raw function/class to an OpenAI function.
 
     Args:
         function:
-            A dictionary, Pydantic BaseModel class, TypedDict class, a LangChain
-            Tool object, or a Python function. If a dictionary is passed in, it is
+            A dictionary, Pydantic `BaseModel` class, `TypedDict` class, a LangChain
+            `Tool` object, or a Python function. If a dictionary is passed in, it is
             assumed to already be a valid OpenAI function, a JSON schema with
-            top-level 'title' key specified, an Anthropic format
-            tool, or an Amazon Bedrock Converse format tool.
+            top-level `title` key specified, an Anthropic format tool, or an Amazon
+            Bedrock Converse format tool.
         strict:
-            If True, model output is guaranteed to exactly match the JSON Schema
-            provided in the function definition. If None, ``strict`` argument will not
+            If `True`, model output is guaranteed to exactly match the JSON Schema
+            provided in the function definition. If `None`, `strict` argument will not
             be included in function definition.
 
     Returns:
@@ -412,25 +351,10 @@ def convert_to_openai_function(
     Raises:
         ValueError: If function is not in a supported format.
 
-    .. versionchanged:: 0.2.29
-
-        ``strict`` arg added.
-
-    .. versionchanged:: 0.3.13
-
-        Support for Anthropic format tools added.
-
-    .. versionchanged:: 0.3.14
-
-        Support for Amazon Bedrock Converse format tools added.
-
-    .. versionchanged:: 0.3.16
-
-        'description' and 'parameters' keys are now optional. Only 'name' is
+    !!! warning "Behavior changed in 0.3.16"
+        `description` and `parameters` keys are now optional. Only `name` is
         required and guaranteed to be part of the output.
     """
-    from langchain_core.tools import BaseTool
-
     # an Anthropic format tool
     if isinstance(function, dict) and all(
         k in function for k in ("name", "input_schema")
@@ -470,7 +394,7 @@ def convert_to_openai_function(
         oai_function = cast(
             "dict", _convert_typed_dict_to_openai_function(cast("type", function))
         )
-    elif isinstance(function, BaseTool):
+    elif isinstance(function, langchain_core.tools.base.BaseTool):
         oai_function = cast("dict", _format_tool_to_openai_function(function))
     elif callable(function):
         oai_function = cast(
@@ -515,82 +439,87 @@ _WellKnownOpenAITools = (
     "mcp",
     "image_generation",
     "web_search_preview",
+    "web_search",
 )
 
 
 def convert_to_openai_tool(
-    tool: Union[dict[str, Any], type[BaseModel], Callable, BaseTool],
+    tool: dict[str, Any] | type[BaseModel] | Callable | BaseTool,
     *,
-    strict: Optional[bool] = None,
+    strict: bool | None = None,
 ) -> dict[str, Any]:
     """Convert a tool-like object to an OpenAI tool schema.
 
-    OpenAI tool schema reference:
-    https://platform.openai.com/docs/api-reference/chat/create#chat-create-tools
+    [OpenAI tool schema reference](https://platform.openai.com/docs/api-reference/chat/create#chat-create-tools)
 
     Args:
         tool:
-            Either a dictionary, a pydantic.BaseModel class, Python function, or
-            BaseTool. If a dictionary is passed in, it is
-            assumed to already be a valid OpenAI function, a JSON schema with
-            top-level 'title' key specified, an Anthropic format
-            tool, or an Amazon Bedrock Converse format tool.
+            Either a dictionary, a `pydantic.BaseModel` class, Python function, or
+            `BaseTool`. If a dictionary is passed in, it is assumed to already be a
+            valid OpenAI function, a JSON schema with top-level `title` key specified,
+            an Anthropic format tool, or an Amazon Bedrock Converse format tool.
         strict:
-            If True, model output is guaranteed to exactly match the JSON Schema
-            provided in the function definition. If None, ``strict`` argument will not
+            If `True`, model output is guaranteed to exactly match the JSON Schema
+            provided in the function definition. If `None`, `strict` argument will not
             be included in tool definition.
 
     Returns:
         A dict version of the passed in tool which is compatible with the
         OpenAI tool-calling API.
 
-    .. versionchanged:: 0.2.29
-
-        ``strict`` arg added.
-
-    .. versionchanged:: 0.3.13
-
-        Support for Anthropic format tools added.
-
-    .. versionchanged:: 0.3.14
-
-        Support for Amazon Bedrock Converse format tools added.
-
-    .. versionchanged:: 0.3.16
-
-        'description' and 'parameters' keys are now optional. Only 'name' is
+    !!! warning "Behavior changed in 0.3.16"
+        `description` and `parameters` keys are now optional. Only `name` is
         required and guaranteed to be part of the output.
 
-    .. versionchanged:: 0.3.44
-
+    !!! warning "Behavior changed in 0.3.44"
         Return OpenAI Responses API-style tools unchanged. This includes
-        any dict with "type" in "file_search", "function", "computer_use_preview",
-        "web_search_preview".
-
-    .. versionchanged:: 0.3.61
-
-        Added support for OpenAI's built-in code interpreter and remote MCP tools.
-
-    .. versionchanged:: 0.3.63
+        any dict with `"type"` in `"file_search"`, `"function"`,
+        `"computer_use_preview"`, `"web_search_preview"`.
 
+    !!! warning "Behavior changed in 0.3.63"
         Added support for OpenAI's image generation built-in tool.
     """
+    # Import locally to prevent circular import
+    from langchain_core.tools import Tool  # noqa: PLC0415
+
     if isinstance(tool, dict):
         if tool.get("type") in _WellKnownOpenAITools:
             return tool
         # As of 03.12.25 can be "web_search_preview" or "web_search_preview_2025_03_11"
         if (tool.get("type") or "").startswith("web_search_preview"):
             return tool
+    if isinstance(tool, Tool) and (tool.metadata or {}).get("type") == "custom_tool":
+        oai_tool = {
+            "type": "custom",
+            "name": tool.name,
+            "description": tool.description,
+        }
+        if tool.metadata is not None and "format" in tool.metadata:
+            oai_tool["format"] = tool.metadata["format"]
+        return oai_tool
     oai_function = convert_to_openai_function(tool, strict=strict)
     return {"type": "function", "function": oai_function}
 
 
 def convert_to_json_schema(
-    schema: Union[dict[str, Any], type[BaseModel], Callable, BaseTool],
+    schema: dict[str, Any] | type[BaseModel] | Callable | BaseTool,
     *,
-    strict: Optional[bool] = None,
+    strict: bool | None = None,
 ) -> dict[str, Any]:
-    """Convert a schema representation to a JSON schema."""
+    """Convert a schema representation to a JSON schema.
+
+    Args:
+        schema: The schema to convert.
+        strict: If `True`, model output is guaranteed to exactly match the JSON Schema
+            provided in the function definition. If `None`, `strict` argument will not
+            be included in function definition.
+
+    Raises:
+        ValueError: If the input is not a valid OpenAI-format tool.
+
+    Returns:
+        A JSON schema representation of the input schema.
+    """
     openai_tool = convert_to_openai_tool(schema, strict=strict)
     if (
         not isinstance(openai_tool, dict)
@@ -618,9 +547,9 @@ def convert_to_json_schema(
 def tool_example_to_messages(
     input: str,
     tool_calls: list[BaseModel],
-    tool_outputs: Optional[list[str]] = None,
+    tool_outputs: list[str] | None = None,
     *,
-    ai_response: Optional[str] = None,
+    ai_response: str | None = None,
 ) -> list[BaseMessage]:
     """Convert an example into a list of messages that can be fed into an LLM.
 
@@ -629,65 +558,62 @@ def tool_example_to_messages(
 
     The list of messages per example by default corresponds to:
 
-    1) HumanMessage: contains the content from which content should be extracted.
-    2) AIMessage: contains the extracted information from the model
-    3) ToolMessage: contains confirmation to the model that the model requested a tool
-       correctly.
+    1. `HumanMessage`: contains the content from which content should be extracted.
+    2. `AIMessage`: contains the extracted information from the model
+    3. `ToolMessage`: contains confirmation to the model that the model requested a
+        tool correctly.
 
-    If `ai_response` is specified, there will be a final AIMessage with that response.
+    If `ai_response` is specified, there will be a final `AIMessage` with that
+    response.
 
-    The ToolMessage is required because some chat models are hyper-optimized for agents
-    rather than for an extraction use case.
+    The `ToolMessage` is required because some chat models are hyper-optimized for
+    agents rather than for an extraction use case.
 
-    Arguments:
-        input: string, the user input
-        tool_calls: list[BaseModel], a list of tool calls represented as Pydantic
-            BaseModels
-        tool_outputs: Optional[list[str]], a list of tool call outputs.
+    Args:
+        input: The user input
+        tool_calls: Tool calls represented as Pydantic BaseModels
+        tool_outputs: Tool call outputs.
             Does not need to be provided. If not provided, a placeholder value
-            will be inserted. Defaults to None.
-        ai_response: Optional[str], if provided, content for a final AIMessage.
+            will be inserted.
+        ai_response: If provided, content for a final `AIMessage`.
 
     Returns:
         A list of messages
 
     Examples:
+        ```python
+        from typing import Optional
+        from pydantic import BaseModel, Field
+        from langchain_openai import ChatOpenAI
 
-        .. code-block:: python
 
-            from typing import Optional
-            from pydantic import BaseModel, Field
-            from langchain_openai import ChatOpenAI
+        class Person(BaseModel):
+            '''Information about a person.'''
 
-            class Person(BaseModel):
-                '''Information about a person.'''
-                name: Optional[str] = Field(..., description="The name of the person")
-                hair_color: Optional[str] = Field(
-                    ..., description="The color of the person's hair if known"
-                )
-                height_in_meters: Optional[str] = Field(
-                    ..., description="Height in METERS"
-                )
+            name: str | None = Field(..., description="The name of the person")
+            hair_color: str | None = Field(
+                ..., description="The color of the person's hair if known"
+            )
+            height_in_meters: str | None = Field(..., description="Height in METERS")
 
-            examples = [
-                (
-                    "The ocean is vast and blue. It's more than 20,000 feet deep.",
-                    Person(name=None, height_in_meters=None, hair_color=None),
-                ),
-                (
-                    "Fiona traveled far from France to Spain.",
-                    Person(name="Fiona", height_in_meters=None, hair_color=None),
-                ),
-            ]
 
+        examples = [
+            (
+                "The ocean is vast and blue. It's more than 20,000 feet deep.",
+                Person(name=None, height_in_meters=None, hair_color=None),
+            ),
+            (
+                "Fiona traveled far from France to Spain.",
+                Person(name="Fiona", height_in_meters=None, hair_color=None),
+            ),
+        ]
 
-            messages = []
 
-            for txt, tool_call in examples:
-                messages.extend(
-                    tool_example_to_messages(txt, [tool_call])
-                )
+        messages = []
 
+        for txt, tool_call in examples:
+            messages.extend(tool_example_to_messages(txt, [tool_call]))
+        ```
     """
     messages: list[BaseMessage] = [HumanMessage(content=input)]
     openai_tool_calls = [
@@ -696,7 +622,7 @@ def tool_example_to_messages(
             "type": "function",
             "function": {
                 # The name of the function right now corresponds to the name
-                # of the pydantic model. This is implicit in the API right now,
+                # of the Pydantic model. This is implicit in the API right now,
                 # and will be improved over time.
                 "name": tool_call.__class__.__name__,
                 "arguments": tool_call.model_dump_json(),
@@ -711,7 +637,7 @@ def tool_example_to_messages(
     tool_outputs = tool_outputs or ["You have correctly called this tool."] * len(
         openai_tool_calls
     )
-    for output, tool_call_dict in zip(tool_outputs, openai_tool_calls):
+    for output, tool_call_dict in zip(tool_outputs, openai_tool_calls, strict=False):
         messages.append(ToolMessage(content=output, tool_call_id=tool_call_dict["id"]))
 
     if ai_response:
@@ -720,7 +646,7 @@ def tool_example_to_messages(
 
 
 def _parse_google_docstring(
-    docstring: Optional[str],
+    docstring: str | None,
     args: list[str],
     *,
     error_on_invalid_docstring: bool = False,
@@ -728,6 +654,7 @@ def _parse_google_docstring(
     """Parse the function and argument descriptions from the docstring of a function.
 
     Assumes the function docstring follows Google Python style guide.
+
     """
     if docstring:
         docstring_blocks = docstring.split("\n\n")
@@ -803,8 +730,14 @@ def _recursive_set_additional_properties_false(
     if isinstance(schema, dict):
         # Check if 'required' is a key at the current level or if the schema is empty,
         # in which case additionalProperties still needs to be specified.
-        if "required" in schema or (
-            "properties" in schema and not schema["properties"]
+        if (
+            "required" in schema
+            or ("properties" in schema and not schema["properties"])
+            # Since Pydantic 2.11, it will always add `additionalProperties: True`
+            # for arbitrary dictionary schemas
+            # See: https://pydantic.dev/articles/pydantic-v2-11-release#changes
+            # If it is already set to True, we need override it to False
+            or "additionalProperties" in schema
         ):
             schema["additionalProperties"] = False
 

langchain_core/utils/html.py

@@ -3,7 +3,6 @@
 import logging
 import re
 from collections.abc import Sequence
-from typing import Optional, Union
 from urllib.parse import urljoin, urlparse
 
 logger = logging.getLogger(__name__)
@@ -35,7 +34,7 @@ DEFAULT_LINK_REGEX = (
 
 
 def find_all_links(
-    raw_html: str, *, pattern: Union[str, re.Pattern, None] = None
+    raw_html: str, *, pattern: str | re.Pattern | None = None
 ) -> list[str]:
     """Extract all links from a raw HTML string.
 
@@ -44,7 +43,7 @@ def find_all_links(
         pattern: Regex to use for extracting links from raw HTML.
 
     Returns:
-        list[str]: all links
+        all links
     """
     pattern = pattern or DEFAULT_LINK_REGEX
     return list(set(re.findall(pattern, raw_html)))
@@ -54,8 +53,8 @@ def extract_sub_links(
     raw_html: str,
     url: str,
     *,
-    base_url: Optional[str] = None,
-    pattern: Union[str, re.Pattern, None] = None,
+    base_url: str | None = None,
+    pattern: str | re.Pattern | None = None,
     prevent_outside: bool = True,
     exclude_prefixes: Sequence[str] = (),
     continue_on_failure: bool = False,
@@ -67,14 +66,14 @@ def extract_sub_links(
         url: the url of the HTML.
         base_url: the base URL to check for outside links against.
         pattern: Regex to use for extracting links from raw HTML.
-        prevent_outside: If True, ignore external links which are not children
+        prevent_outside: If `True`, ignore external links which are not children
             of the base URL.
         exclude_prefixes: Exclude any URLs that start with one of these prefixes.
-        continue_on_failure: If True, continue if parsing a specific link raises an
+        continue_on_failure: If `True`, continue if parsing a specific link raises an
             exception. Otherwise, raise the exception.
 
     Returns:
-        list[str]: sub links.
+        sub links.
     """
     base_url_to_use = base_url if base_url is not None else url
     parsed_base_url = urlparse(base_url_to_use)

langchain_core/utils/input.py

@@ -1,6 +1,6 @@
 """Handle chained inputs."""
 
-from typing import Optional, TextIO
+from typing import TextIO
 
 _TEXT_COLOR_MAPPING = {
     "blue": "36;1",
@@ -12,7 +12,7 @@ _TEXT_COLOR_MAPPING = {
 
 
 def get_color_mapping(
-    items: list[str], excluded_colors: Optional[list] = None
+    items: list[str], excluded_colors: list | None = None
 ) -> dict[str, str]:
     """Get mapping for items to a support color.
 
@@ -56,7 +56,7 @@ def get_bolded_text(text: str) -> str:
 
 
 def print_text(
-    text: str, color: Optional[str] = None, end: str = "", file: Optional[TextIO] = None
+    text: str, color: str | None = None, end: str = "", file: TextIO | None = None
 ) -> None:
     """Print text with highlighting and no end characters.
 
@@ -65,9 +65,9 @@ def print_text(
 
     Args:
         text: The text to print.
-        color: The color to use. Defaults to None.
-        end: The end character to use. Defaults to "".
-        file: The file to write to. Defaults to None.
+        color: The color to use.
+        end: The end character to use.
+        file: The file to write to.
     """
     text_to_print = get_colored_text(text, color) if color else text
     print(text_to_print, end=end, file=file)