langchain-core 0.3.79__py3-none-any.whl → 1.0.0__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,32 +59,29 @@ 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]:
+    """Make tools out of Python functions, can be used with or without arguments.
 
     Args:
         name_or_callable: Optional name of the tool or the callable to be
@@ -93,145 +91,141 @@ def tool(
         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
+            - `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)
         *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.
+            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.
-            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
+        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 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.
+            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 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"}
+        @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
+    !!! version-added "Added in version 0.2.14"
 
         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 +235,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 +245,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 +346,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 +364,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 +383,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 +415,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,13 @@ 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.

langchain_core/tools/simple.py

@@ -2,14 +2,11 @@
 
 from __future__ import annotations
 
-from collections.abc import Awaitable
+from collections.abc import Awaitable, Callable
 from inspect import signature
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
-    Optional,
-    Union,
 )
 
 from typing_extensions import override
@@ -34,9 +31,9 @@ class Tool(BaseTool):
     """Tool that takes in function or coroutine directly."""
 
     description: str = ""
-    func: Optional[Callable[..., str]]
+    func: Callable[..., str] | None
     """The function to run when the tool is called."""
-    coroutine: Optional[Callable[..., Awaitable[str]]] = None
+    coroutine: Callable[..., Awaitable[str]] | None = None
     """The asynchronous version of the function."""
 
     # --- Runnable ---
@@ -44,8 +41,8 @@ class Tool(BaseTool):
     @override
     async def ainvoke(
         self,
-        input: Union[str, dict, ToolCall],
-        config: Optional[RunnableConfig] = None,
+        input: str | dict | ToolCall,
+        config: RunnableConfig | None = None,
         **kwargs: Any,
     ) -> Any:
         if not self.coroutine:
@@ -70,9 +67,9 @@ class Tool(BaseTool):
         return {"tool_input": {"type": "string"}}
 
     def _to_args_and_kwargs(
-        self, tool_input: Union[str, dict], tool_call_id: Optional[str]
+        self, tool_input: str | dict, tool_call_id: str | None
     ) -> tuple[tuple, dict]:
-        """Convert tool input to pydantic model.
+        """Convert tool input to Pydantic model.
 
         Args:
             tool_input: The input to the tool.
@@ -82,8 +79,7 @@ class Tool(BaseTool):
             ToolException: If the tool input is invalid.
 
         Returns:
-            the pydantic model args and kwargs.
-
+            The Pydantic model args and kwargs.
         """
         args, kwargs = super()._to_args_and_kwargs(tool_input, tool_call_id)
         # For backwards compatibility. The tool must be run with a single input
@@ -101,7 +97,7 @@ class Tool(BaseTool):
         self,
         *args: Any,
         config: RunnableConfig,
-        run_manager: Optional[CallbackManagerForToolRun] = None,
+        run_manager: CallbackManagerForToolRun | None = None,
         **kwargs: Any,
     ) -> Any:
         """Use the tool.
@@ -128,7 +124,7 @@ class Tool(BaseTool):
         self,
         *args: Any,
         config: RunnableConfig,
-        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+        run_manager: AsyncCallbackManagerForToolRun | None = None,
         **kwargs: Any,
     ) -> Any:
         """Use the tool asynchronously.
@@ -157,7 +153,7 @@ class Tool(BaseTool):
 
     # TODO: this is for backwards compatibility, remove in future
     def __init__(
-        self, name: str, func: Optional[Callable], description: str, **kwargs: Any
+        self, name: str, func: Callable | None, description: str, **kwargs: Any
     ) -> None:
         """Initialize tool."""
         super().__init__(name=name, func=func, description=description, **kwargs)
@@ -165,14 +161,13 @@ class Tool(BaseTool):
     @classmethod
     def from_function(
         cls,
-        func: Optional[Callable],
+        func: Callable | None,
         name: str,  # We keep these required to support backwards compatibility
         description: str,
         return_direct: bool = False,  # noqa: FBT001,FBT002
-        args_schema: Optional[ArgsSchema] = None,
-        coroutine: Optional[
-            Callable[..., Awaitable[Any]]
-        ] = None,  # This is last for compatibility, but should be after func
+        args_schema: ArgsSchema | None = None,
+        coroutine: Callable[..., Awaitable[Any]]
+        | None = None,  # This is last for compatibility, but should be after func
         **kwargs: Any,
     ) -> Tool:
         """Initialize tool from a function.
@@ -181,10 +176,10 @@ class Tool(BaseTool):
             func: The function to create the tool from.
             name: The name of the tool.
             description: The description of the tool.
-            return_direct: Whether to return the output directly. Defaults to False.
-            args_schema: The schema of the tool's input arguments. Defaults to None.
-            coroutine: The asynchronous version of the function. Defaults to None.
-            kwargs: Additional arguments to pass to the tool.
+            return_direct: Whether to return the output directly.
+            args_schema: The schema of the tool's input arguments.
+            coroutine: The asynchronous version of the function.
+            **kwargs: Additional arguments to pass to the tool.
 
         Returns:
             The tool.