langchain-core 1.0.0a5__py3-none-any.whl → 1.0.3__py3-none-any.whl

langchain_core/tools/convert.py

@@ -1,7 +1,8 @@
 """Convert functions and runnables to tools."""
 
 import inspect
-from typing import Any, Callable, Literal, Optional, Union, get_type_hints, overload
+from collections.abc import Callable
+from typing import Any, Literal, get_type_hints, overload
 
 from pydantic import BaseModel, Field, create_model
 
@@ -15,14 +16,14 @@ from langchain_core.tools.structured import StructuredTool
 @overload
 def tool(
     *,
-    description: Optional[str] = None,
+    description: str | None = None,
     return_direct: bool = False,
-    args_schema: Optional[ArgsSchema] = None,
+    args_schema: ArgsSchema | None = None,
     infer_schema: bool = True,
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
-) -> Callable[[Union[Callable, Runnable]], BaseTool]: ...
+) -> Callable[[Callable | Runnable], BaseTool]: ...
 
 
 @overload
@@ -30,9 +31,9 @@ def tool(
     name_or_callable: str,
     runnable: Runnable,
     *,
-    description: Optional[str] = None,
+    description: str | None = None,
     return_direct: bool = False,
-    args_schema: Optional[ArgsSchema] = None,
+    args_schema: ArgsSchema | None = None,
     infer_schema: bool = True,
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
@@ -44,9 +45,9 @@ def tool(
 def tool(
     name_or_callable: Callable,
     *,
-    description: Optional[str] = None,
+    description: str | None = None,
     return_direct: bool = False,
-    args_schema: Optional[ArgsSchema] = None,
+    args_schema: ArgsSchema | None = None,
     infer_schema: bool = True,
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
@@ -58,180 +59,186 @@ def tool(
 def tool(
     name_or_callable: str,
     *,
-    description: Optional[str] = None,
+    description: str | None = None,
     return_direct: bool = False,
-    args_schema: Optional[ArgsSchema] = None,
+    args_schema: ArgsSchema | None = None,
     infer_schema: bool = True,
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
-) -> Callable[[Union[Callable, Runnable]], BaseTool]: ...
+) -> Callable[[Callable | Runnable], BaseTool]: ...
 
 
 def tool(
-    name_or_callable: Optional[Union[str, Callable]] = None,
-    runnable: Optional[Runnable] = None,
+    name_or_callable: str | Callable | None = None,
+    runnable: Runnable | None = None,
     *args: Any,
-    description: Optional[str] = None,
+    description: str | None = None,
     return_direct: bool = False,
-    args_schema: Optional[ArgsSchema] = None,
+    args_schema: ArgsSchema | None = None,
     infer_schema: bool = True,
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
-) -> Union[
-    BaseTool,
-    Callable[[Union[Callable, Runnable]], BaseTool],
-]:
-    """Make tools out of functions, can be used with or without arguments.
+) -> BaseTool | Callable[[Callable | Runnable], BaseTool]:
+    """Convert Python functions and `Runnables` to LangChain tools.
+
+    Can be used as a decorator with or without arguments to create tools from functions.
+
+    Functions can have any signature - the tool will automatically infer input schemas
+    unless disabled.
+
+    !!! note "Requirements"
+        - Functions must have type hints for proper schema inference
+        - When `infer_schema=False`, functions must be `(str) -> str` and have
+            docstrings
+        - When using with `Runnable`, a string name must be provided
 
     Args:
-        name_or_callable: Optional name of the tool or the callable to be
-            converted to a tool. Must be provided as a positional argument.
-        runnable: Optional runnable to convert to a tool. Must be provided as a
-            positional argument.
+        name_or_callable: Optional name of the tool or the `Callable` to be
+            converted to a tool. Overrides the function's name.
+
+            Must be provided as a positional argument.
+        runnable: Optional `Runnable` to convert to a tool.
+
+            Must be provided as a positional argument.
         description: Optional description for the tool.
+
             Precedence for the tool description value is as follows:
 
-            - ``description`` argument
-                (used even if docstring and/or ``args_schema`` are provided)
-            - tool function docstring
-                (used even if ``args_schema`` is provided)
-            - ``args_schema`` description
-                (used only if `description` / docstring are not provided)
+            - This `description` argument
+                (used even if docstring and/or `args_schema` are provided)
+            - Tool function docstring
+                (used even if `args_schema` is provided)
+            - `args_schema` description
+                (used only if `description` and docstring are not provided)
         *args: Extra positional arguments. Must be empty.
-        return_direct: Whether to return directly from the tool rather
-            than continuing the agent loop. Defaults to False.
-        args_schema: optional argument schema for user to specify.
-            Defaults to None.
-        infer_schema: Whether to infer the schema of the arguments from
-            the function's signature. This also makes the resultant tool
-            accept a dictionary input to its `run()` function.
-            Defaults to True.
-        response_format: The tool response format. If "content" then the output of
-            the tool is interpreted as the contents of a ToolMessage. If
-            "content_and_artifact" then the output is expected to be a two-tuple
-            corresponding to the (content, artifact) of a ToolMessage.
-            Defaults to "content".
-        parse_docstring: if ``infer_schema`` and ``parse_docstring``, will attempt to
+        return_direct: Whether to return directly from the tool rather than continuing
+            the agent loop.
+        args_schema: Optional argument schema for user to specify.
+        infer_schema: Whether to infer the schema of the arguments from the function's
+            signature. This also makes the resultant tool accept a dictionary input to
+            its `run()` function.
+        response_format: The tool response format.
+
+            If `'content'`, then the output of the tool is interpreted as the contents
+            of a `ToolMessage`.
+
+            If `'content_and_artifact'`, then the output is expected to be a two-tuple
+            corresponding to the `(content, artifact)` of a `ToolMessage`.
+        parse_docstring: If `infer_schema` and `parse_docstring`, will attempt to
             parse parameter descriptions from Google Style function docstrings.
-            Defaults to False.
-        error_on_invalid_docstring: if ``parse_docstring`` is provided, configure
-            whether to raise ValueError on invalid Google Style docstrings.
-            Defaults to True.
+        error_on_invalid_docstring: If `parse_docstring` is provided, configure
+            whether to raise `ValueError` on invalid Google Style docstrings.
 
     Raises:
-        ValueError: If too many positional arguments are provided.
-        ValueError: If a runnable is provided without a string name.
+        ValueError: If too many positional arguments are provided (e.g. violating the
+            `*args` constraint).
+        ValueError: If a `Runnable` is provided without a string name. When using `tool`
+            with a `Runnable`, a `str` name must be provided as the `name_or_callable`.
         ValueError: If the first argument is not a string or callable with
-            a ``__name__`` attribute.
+            a `__name__` attribute.
         ValueError: If the function does not have a docstring and description
-            is not provided and ``infer_schema`` is False.
-        ValueError: If ``parse_docstring`` is True and the function has an invalid
-            Google-style docstring and ``error_on_invalid_docstring`` is True.
-        ValueError: If a Runnable is provided that does not have an object schema.
+            is not provided and `infer_schema` is `False`.
+        ValueError: If `parse_docstring` is `True` and the function has an invalid
+            Google-style docstring and `error_on_invalid_docstring` is True.
+        ValueError: If a `Runnable` is provided that does not have an object schema.
 
     Returns:
         The tool.
 
-    Requires:
-        - Function must be of type (str) -> str
-        - Function must have a docstring
-
     Examples:
-        .. code-block:: python
-
-            @tool
-            def search_api(query: str) -> str:
-                # Searches the API for the query.
-                return
-
+        ```python
+        @tool
+        def search_api(query: str) -> str:
+            # Searches the API for the query.
+            return
 
-            @tool("search", return_direct=True)
-            def search_api(query: str) -> str:
-                # Searches the API for the query.
-                return
 
+        @tool("search", return_direct=True)
+        def search_api(query: str) -> str:
+            # Searches the API for the query.
+            return
 
-            @tool(response_format="content_and_artifact")
-            def search_api(query: str) -> tuple[str, dict]:
-                return "partial json of results", {"full": "object of results"}
 
-    .. versionadded:: 0.2.14
+        @tool(response_format="content_and_artifact")
+        def search_api(query: str) -> tuple[str, dict]:
+            return "partial json of results", {"full": "object of results"}
+        ```
 
         Parse Google-style docstrings:
 
-        .. code-block:: python
-
-            @tool(parse_docstring=True)
-            def foo(bar: str, baz: int) -> str:
-                \"\"\"The foo.
-
-                Args:
-                    bar: The bar.
-                    baz: The baz.
-                \"\"\"
-                return bar
-
-            foo.args_schema.model_json_schema()
-
-        .. code-block:: python
-
-            {
-                "title": "foo",
-                "description": "The foo.",
-                "type": "object",
-                "properties": {
-                    "bar": {
-                        "title": "Bar",
-                        "description": "The bar.",
-                        "type": "string",
-                    },
-                    "baz": {
-                        "title": "Baz",
-                        "description": "The baz.",
-                        "type": "integer",
-                    },
+        ```python
+        @tool(parse_docstring=True)
+        def foo(bar: str, baz: int) -> str:
+            \"\"\"The foo.
+
+            Args:
+                bar: The bar.
+                baz: The baz.
+            \"\"\"
+            return bar
+
+        foo.args_schema.model_json_schema()
+        ```
+
+        ```python
+        {
+            "title": "foo",
+            "description": "The foo.",
+            "type": "object",
+            "properties": {
+                "bar": {
+                    "title": "Bar",
+                    "description": "The bar.",
+                    "type": "string",
                 },
-                "required": ["bar", "baz"],
-            }
+                "baz": {
+                    "title": "Baz",
+                    "description": "The baz.",
+                    "type": "integer",
+                },
+            },
+            "required": ["bar", "baz"],
+        }
+        ```
 
-        Note that parsing by default will raise ``ValueError`` if the docstring
+        Note that parsing by default will raise `ValueError` if the docstring
         is considered invalid. A docstring is considered invalid if it contains
         arguments not in the function signature, or is unable to be parsed into
-        a summary and "Args:" blocks. Examples below:
-
-        .. code-block:: python
-
-            # No args section
-            def invalid_docstring_1(bar: str, baz: int) -> str:
-                \"\"\"The foo.\"\"\"
-                return bar
-
-            # Improper whitespace between summary and args section
-            def invalid_docstring_2(bar: str, baz: int) -> str:
-                \"\"\"The foo.
-                Args:
-                    bar: The bar.
-                    baz: The baz.
-                \"\"\"
-                return bar
-
-            # Documented args absent from function signature
-            def invalid_docstring_3(bar: str, baz: int) -> str:
-                \"\"\"The foo.
-
-                Args:
-                    banana: The bar.
-                    monkey: The baz.
-                \"\"\"
-                return bar
-
+        a summary and `"Args:"` blocks. Examples below:
+
+        ```python
+        # No args section
+        def invalid_docstring_1(bar: str, baz: int) -> str:
+            \"\"\"The foo.\"\"\"
+            return bar
+
+        # Improper whitespace between summary and args section
+        def invalid_docstring_2(bar: str, baz: int) -> str:
+            \"\"\"The foo.
+            Args:
+                bar: The bar.
+                baz: The baz.
+            \"\"\"
+            return bar
+
+        # Documented args absent from function signature
+        def invalid_docstring_3(bar: str, baz: int) -> str:
+            \"\"\"The foo.
+
+            Args:
+                banana: The bar.
+                monkey: The baz.
+            \"\"\"
+            return bar
+
+        ```
     """  # noqa: D214, D410, D411  # We're intentionally showing bad formatting in examples
 
     def _create_tool_factory(
         tool_name: str,
-    ) -> Callable[[Union[Callable, Runnable]], BaseTool]:
+    ) -> Callable[[Callable | Runnable], BaseTool]:
         """Create a decorator that takes a callable and returns a tool.
 
         Args:
@@ -241,7 +248,7 @@ def tool(
             A function that takes a callable or Runnable and returns a tool.
         """
 
-        def _tool_factory(dec_func: Union[Callable, Runnable]) -> BaseTool:
+        def _tool_factory(dec_func: Callable | Runnable) -> BaseTool:
             tool_description = description
             if isinstance(dec_func, Runnable):
                 runnable = dec_func
@@ -251,18 +258,18 @@ def tool(
                     raise ValueError(msg)
 
                 async def ainvoke_wrapper(
-                    callbacks: Optional[Callbacks] = None, **kwargs: Any
+                    callbacks: Callbacks | None = None, **kwargs: Any
                 ) -> Any:
                     return await runnable.ainvoke(kwargs, {"callbacks": callbacks})
 
                 def invoke_wrapper(
-                    callbacks: Optional[Callbacks] = None, **kwargs: Any
+                    callbacks: Callbacks | None = None, **kwargs: Any
                 ) -> Any:
                     return runnable.invoke(kwargs, {"callbacks": callbacks})
 
                 coroutine = ainvoke_wrapper
                 func = invoke_wrapper
-                schema: Optional[ArgsSchema] = runnable.input_schema
+                schema: ArgsSchema | None = runnable.input_schema
                 tool_description = description or repr(runnable)
             elif inspect.iscoroutinefunction(dec_func):
                 coroutine = dec_func
@@ -352,7 +359,7 @@ def tool(
     # @tool(parse_docstring=True)
     # def my_tool():
     #    pass
-    def _partial(func: Union[Callable, Runnable]) -> BaseTool:
+    def _partial(func: Callable | Runnable) -> BaseTool:
         """Partial function that takes a callable and returns a tool."""
         name_ = func.get_name() if isinstance(func, Runnable) else func.__name__
         tool_factory = _create_tool_factory(name_)
@@ -370,7 +377,7 @@ def _get_description_from_runnable(runnable: Runnable) -> str:
 def _get_schema_from_runnable_and_arg_types(
     runnable: Runnable,
     name: str,
-    arg_types: Optional[dict[str, type]] = None,
+    arg_types: dict[str, type] | None = None,
 ) -> type[BaseModel]:
     """Infer args_schema for tool."""
     if arg_types is None:
@@ -389,20 +396,20 @@ def _get_schema_from_runnable_and_arg_types(
 
 def convert_runnable_to_tool(
     runnable: Runnable,
-    args_schema: Optional[type[BaseModel]] = None,
+    args_schema: type[BaseModel] | None = None,
     *,
-    name: Optional[str] = None,
-    description: Optional[str] = None,
-    arg_types: Optional[dict[str, type]] = None,
+    name: str | None = None,
+    description: str | None = None,
+    arg_types: dict[str, type] | None = None,
 ) -> BaseTool:
     """Convert a Runnable into a BaseTool.
 
     Args:
         runnable: The runnable to convert.
-        args_schema: The schema for the tool's input arguments. Defaults to None.
-        name: The name of the tool. Defaults to None.
-        description: The description of the tool. Defaults to None.
-        arg_types: The types of the arguments. Defaults to None.
+        args_schema: The schema for the tool's input arguments.
+        name: The name of the tool.
+        description: The description of the tool.
+        arg_types: The types of the arguments.
 
     Returns:
         The tool.
@@ -421,12 +428,10 @@ def convert_runnable_to_tool(
             description=description,
         )
 
-    async def ainvoke_wrapper(
-        callbacks: Optional[Callbacks] = None, **kwargs: Any
-    ) -> Any:
+    async def ainvoke_wrapper(callbacks: Callbacks | None = None, **kwargs: Any) -> Any:
         return await runnable.ainvoke(kwargs, config={"callbacks": callbacks})
 
-    def invoke_wrapper(callbacks: Optional[Callbacks] = None, **kwargs: Any) -> Any:
+    def invoke_wrapper(callbacks: Callbacks | None = None, **kwargs: Any) -> Any:
         return runnable.invoke(kwargs, config={"callbacks": callbacks})
 
     if (

langchain_core/tools/render.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from inspect import signature
-from typing import Callable
 
 from langchain_core.tools.base import BaseTool
 
@@ -21,10 +21,10 @@ def render_text_description(tools: list[BaseTool]) -> str:
 
     Output will be in the format of:
 
-    .. code-block:: markdown
-
-        search: This tool is used for search
-        calculator: This tool is used for math
+    ```txt
+    search: This tool is used for search
+    calculator: This tool is used for math
+    ```
     """
     descriptions = []
     for tool in tools:
@@ -49,11 +49,11 @@ def render_text_description_and_args(tools: list[BaseTool]) -> str:
 
     Output will be in the format of:
 
-    .. code-block:: markdown
-
-        search: This tool is used for search, args: {"query": {"type": "string"}}
-        calculator: This tool is used for math, \
-args: {"expression": {"type": "string"}}
+    ```txt
+    search: This tool is used for search, args: {"query": {"type": "string"}}
+    calculator: This tool is used for math, \
+    args: {"expression": {"type": "string"}}
+    ```
     """
     tool_strings = []
     for tool in tools:

langchain_core/tools/retriever.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from functools import partial
-from typing import TYPE_CHECKING, Literal, Optional, Union
+from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, Field
 
@@ -34,7 +34,7 @@ def _get_relevant_documents(
     document_separator: str,
     callbacks: Callbacks = None,
     response_format: Literal["content", "content_and_artifact"] = "content",
-) -> Union[str, tuple[str, list[Document]]]:
+) -> str | tuple[str, list[Document]]:
     docs = retriever.invoke(query, config={"callbacks": callbacks})
     content = document_separator.join(
         format_document(doc, document_prompt) for doc in docs
@@ -52,7 +52,7 @@ async def _aget_relevant_documents(
     document_separator: str,
     callbacks: Callbacks = None,
     response_format: Literal["content", "content_and_artifact"] = "content",
-) -> Union[str, tuple[str, list[Document]]]:
+) -> str | tuple[str, list[Document]]:
     docs = await retriever.ainvoke(query, config={"callbacks": callbacks})
     content = document_separator.join(
         [await aformat_document(doc, document_prompt) for doc in docs]
@@ -69,7 +69,7 @@ def create_retriever_tool(
     name: str,
     description: str,
     *,
-    document_prompt: Optional[BasePromptTemplate] = None,
+    document_prompt: BasePromptTemplate | None = None,
     document_separator: str = "\n\n",
     response_format: Literal["content", "content_and_artifact"] = "content",
 ) -> Tool:
@@ -81,13 +81,14 @@ def create_retriever_tool(
             so should be unique and somewhat descriptive.
         description: The description for the tool. This will be passed to the language
             model, so should be descriptive.
-        document_prompt: The prompt to use for the document. Defaults to None.
-        document_separator: The separator to use between documents. Defaults to "\n\n".
-        response_format: The tool response format. If "content" then the output of
-            the tool is interpreted as the contents of a ToolMessage. If
-            "content_and_artifact" then the output is expected to be a two-tuple
-            corresponding to the (content, artifact) of a ToolMessage (artifact
-            being a list of documents in this case). Defaults to "content".
+        document_prompt: The prompt to use for the document.
+        document_separator: The separator to use between documents.
+        response_format: The tool response format.
+
+            If `"content"` then the output of the tool is interpreted as the contents of
+            a `ToolMessage`. If `"content_and_artifact"` then the output is expected to
+            be a two-tuple corresponding to the `(content, artifact)` of a `ToolMessage`
+            (artifact being a list of documents in this case).
 
     Returns:
         Tool class to pass to an agent.