langchain-core 0.4.0.dev0__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,15 +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,
-    message_version: Literal["v0", "v1"] = "v0",
-) -> Callable[[Union[Callable, Runnable]], BaseTool]: ...
+) -> Callable[[Callable | Runnable], BaseTool]: ...
 
 
 @overload
@@ -31,14 +31,13 @@ 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,
     error_on_invalid_docstring: bool = True,
-    message_version: Literal["v0", "v1"] = "v0",
 ) -> BaseTool: ...
 
 
@@ -46,14 +45,13 @@ 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,
     error_on_invalid_docstring: bool = True,
-    message_version: Literal["v0", "v1"] = "v0",
 ) -> BaseTool: ...
 
 
@@ -61,34 +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,
-    message_version: Literal["v0", "v1"] = "v0",
-) -> 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,
-    message_version: Literal["v0", "v1"] = "v0",
-) -> 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
@@ -97,140 +90,142 @@ def tool(
             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)
+
+            - `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.
-        message_version: Version of ToolMessage to return given
-            :class:`~langchain_core.messages.content_blocks.ToolCall` input.
-
-            If ``"v0"``, output will be a v0 :class:`~langchain_core.messages.tool.ToolMessage`.
-            If ``"v1"``, output will be a v1 :class:`~langchain_core.messages.v1.ToolMessage`.
+        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.
+        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.
 
     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
+        ```python
+        @tool
+        def search_api(query: str) -> str:
+            # Searches the API for the query.
+            return
 
-            @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"}
+        ```
+
+    !!! 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",
+                },
+                "baz": {
+                    "title": "Baz",
+                    "description": "The baz.",
+                    "type": "integer",
                 },
-                "required": [
-                    "bar",
-                    "baz"
-                ]
-            }
+            },
+            "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
-
-    """  # noqa: D214, D410, D411, E501
+        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:
@@ -240,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
@@ -250,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
@@ -284,7 +279,6 @@ def tool(
                     response_format=response_format,
                     parse_docstring=parse_docstring,
                     error_on_invalid_docstring=error_on_invalid_docstring,
-                    message_version=message_version,
                 )
             # If someone doesn't want a schema applied, we must treat it as
             # a simple string->string function
@@ -301,7 +295,6 @@ def tool(
                 return_direct=return_direct,
                 coroutine=coroutine,
                 response_format=response_format,
-                message_version=message_version,
             )
 
         return _tool_factory
@@ -316,7 +309,7 @@ def tool(
 
     if runnable is not None:
         # tool is used as a function
-        # tool_from_runnable = tool("name", runnable)
+        # for instance tool_from_runnable = tool("name", runnable)
         if not name_or_callable:
             msg = "Runnable without name for tool constructor"
             raise ValueError(msg)
@@ -353,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_)
@@ -371,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:
@@ -390,30 +383,24 @@ 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,
-    message_version: Literal["v0", "v1"] = "v0",
+    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.
-        message_version: Version of ToolMessage to return given
-            :class:`~langchain_core.messages.content_blocks.ToolCall` input.
-
-            If ``"v0"``, output will be a v0 :class:`~langchain_core.messages.tool.ToolMessage`.
-            If ``"v1"``, output will be a v1 :class:`~langchain_core.messages.v1.ToolMessage`.
+        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.
-    """  # noqa: E501
+    """
     if args_schema:
         runnable = runnable.with_types(input_type=args_schema)
     description = description or _get_description_from_runnable(runnable)
@@ -426,15 +413,12 @@ def convert_runnable_to_tool(
             func=runnable.invoke,
             coroutine=runnable.ainvoke,
             description=description,
-            message_version=message_version,
         )
 
-    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 (
@@ -454,5 +438,4 @@ def convert_runnable_to_tool(
         coroutine=ainvoke_wrapper,
         description=description,
         args_schema=args_schema,
-        message_version=message_version,
     )

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,10 +69,9 @@ 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",
-    message_version: Literal["v0", "v1"] = "v1",
 ) -> Tool:
     r"""Create a tool to do retrieval of documents.
 
@@ -82,22 +81,17 @@ 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".
-        message_version: Version of ToolMessage to return given
-            :class:`~langchain_core.messages.content_blocks.ToolCall` input.
-
-            If ``"v0"``, output will be a v0 :class:`~langchain_core.messages.tool.ToolMessage`.
-            If ``"v1"``, output will be a v1 :class:`~langchain_core.messages.v1.ToolMessage`.
+        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.
-    """  # noqa: E501
+    """
     document_prompt = document_prompt or PromptTemplate.from_template("{page_content}")
     func = partial(
         _get_relevant_documents,
@@ -120,5 +114,4 @@ def create_retriever_tool(
         coroutine=afunc,
         args_schema=RetrieverInput,
         response_format=response_format,
-        message_version=message_version,
     )