langchain-core 1.0.0a8__py3-none-any.whl → 1.0.0rc2__py3-none-any.whl

langchain_core/tools/base.py

@@ -92,7 +92,7 @@ def _is_annotated_type(typ: type[Any]) -> bool:
         typ: The type to check.
 
     Returns:
-        True if the type is an Annotated type, False otherwise.
+        `True` if the type is an Annotated type, `False` otherwise.
     """
     return get_origin(typ) is typing.Annotated
 
@@ -226,7 +226,7 @@ def _is_pydantic_annotation(annotation: Any, pydantic_version: str = "v2") -> bo
         pydantic_version: The Pydantic version to check against ("v1" or "v2").
 
     Returns:
-        True if the annotation is a Pydantic model, False otherwise.
+        `True` if the annotation is a Pydantic model, `False` otherwise.
     """
     base_model_class = BaseModelV1 if pydantic_version == "v1" else BaseModel
     try:
@@ -245,7 +245,7 @@ def _function_annotations_are_pydantic_v1(
         func: The function being checked.
 
     Returns:
-        True if all Pydantic annotations are from V1, False otherwise.
+        True if all Pydantic annotations are from V1, `False` otherwise.
 
     Raises:
         NotImplementedError: If the function contains mixed V1 and V2 annotations.
@@ -285,24 +285,23 @@ def create_schema_from_function(
     error_on_invalid_docstring: bool = False,
     include_injected: bool = True,
 ) -> type[BaseModel]:
-    """Create a pydantic schema from a function's signature.
+    """Create a Pydantic schema from a function's signature.
 
     Args:
-        model_name: Name to assign to the generated pydantic schema.
+        model_name: Name to assign to the generated Pydantic schema.
         func: Function to generate the schema from.
         filter_args: Optional list of arguments to exclude from the schema.
-            Defaults to FILTERED_ARGS.
+            Defaults to `FILTERED_ARGS`.
         parse_docstring: Whether to parse the function's docstring for descriptions
-            for each argument. Defaults to False.
-        error_on_invalid_docstring: if ``parse_docstring`` is provided, configure
-            whether to raise ValueError on invalid Google Style docstrings.
-            Defaults to False.
+            for each argument.
+        error_on_invalid_docstring: if `parse_docstring` is provided, configure
+            whether to raise `ValueError` on invalid Google Style docstrings.
         include_injected: Whether to include injected arguments in the schema.
-            Defaults to True, since we want to include them in the schema
+            Defaults to `True`, since we want to include them in the schema
             when *validating* tool inputs.
 
     Returns:
-        A pydantic model with the same arguments as the function.
+        A Pydantic model with the same arguments as the function.
     """
     sig = inspect.signature(func)
 
@@ -312,7 +311,7 @@ def create_schema_from_function(
         # https://docs.pydantic.dev/latest/usage/validation_decorator/
         with warnings.catch_warnings():
             # We are using deprecated functionality here.
-            # This code should be re-written to simply construct a pydantic model
+            # This code should be re-written to simply construct a Pydantic model
             # using inspect.signature and create_model.
             warnings.simplefilter("ignore", category=PydanticDeprecationWarning)
             validated = validate_arguments(func, config=_SchemaConfig)  # type: ignore[operator]
@@ -460,13 +459,13 @@ class ChildTool(BaseTool):
     """Callbacks to be called during tool execution."""
 
     tags: list[str] | None = None
-    """Optional list of tags associated with the tool. Defaults to None.
+    """Optional list of tags associated with the tool.
     These tags will be associated with each call to this tool,
     and passed as arguments to the handlers defined in `callbacks`.
     You can use these to eg identify a specific instance of a tool with its use case.
     """
     metadata: dict[str, Any] | None = None
-    """Optional metadata associated with the tool. Defaults to None.
+    """Optional metadata associated with the tool.
     This metadata will be associated with each call to this tool,
     and passed as arguments to the handlers defined in `callbacks`.
     You can use these to eg identify a specific instance of a tool with its use case.
@@ -481,18 +480,18 @@ class ChildTool(BaseTool):
     """Handle the content of the ValidationError thrown."""
 
     response_format: Literal["content", "content_and_artifact"] = "content"
-    """The tool response format. Defaults to 'content'.
+    """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.
+    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`.
     """
 
     def __init__(self, **kwargs: Any) -> None:
         """Initialize the tool.
 
         Raises:
-            TypeError: If ``args_schema`` is not a subclass of pydantic ``BaseModel`` or
+            TypeError: If `args_schema` is not a subclass of pydantic `BaseModel` or
                 dict.
         """
         if (
@@ -517,7 +516,7 @@ class ChildTool(BaseTool):
         """Check if the tool accepts only a single input argument.
 
         Returns:
-            True if the tool has only one input argument, False otherwise.
+            `True` if the tool has only one input argument, `False` otherwise.
         """
         keys = {k for k in self.args if k != "kwargs"}
         return len(keys) == 1
@@ -616,10 +615,10 @@ class ChildTool(BaseTool):
             The parsed and validated input.
 
         Raises:
-            ValueError: If string input is provided with JSON schema ``args_schema``.
-            ValueError: If InjectedToolCallId is required but ``tool_call_id`` is not
+            ValueError: If string input is provided with JSON schema `args_schema`.
+            ValueError: If InjectedToolCallId is required but `tool_call_id` is not
                 provided.
-            TypeError: If args_schema is not a Pydantic ``BaseModel`` or dict.
+            TypeError: If args_schema is not a Pydantic `BaseModel` or dict.
         """
         input_args = self.args_schema
         if isinstance(tool_input, str):
@@ -686,8 +685,8 @@ class ChildTool(BaseTool):
     def _run(self, *args: Any, **kwargs: Any) -> Any:
         """Use the tool.
 
-        Add run_manager: Optional[CallbackManagerForToolRun] = None
-        to child implementations to enable tracing.
+        Add `run_manager: CallbackManagerForToolRun | None = None` to child
+        implementations to enable tracing.
 
         Returns:
             The result of the tool execution.
@@ -696,8 +695,8 @@ class ChildTool(BaseTool):
     async def _arun(self, *args: Any, **kwargs: Any) -> Any:
         """Use the tool asynchronously.
 
-        Add run_manager: Optional[AsyncCallbackManagerForToolRun] = None
-        to child implementations to enable tracing.
+        Add `run_manager: AsyncCallbackManagerForToolRun | None = None` to child
+        implementations to enable tracing.
 
         Returns:
             The result of the tool execution.
@@ -767,17 +766,17 @@ class ChildTool(BaseTool):
 
         Args:
             tool_input: The input to the tool.
-            verbose: Whether to log the tool's progress. Defaults to None.
-            start_color: The color to use when starting the tool. Defaults to 'green'.
-            color: The color to use when ending the tool. Defaults to 'green'.
-            callbacks: Callbacks to be called during tool execution. Defaults to None.
-            tags: Optional list of tags associated with the tool. Defaults to None.
-            metadata: Optional metadata associated with the tool. Defaults to None.
-            run_name: The name of the run. Defaults to None.
-            run_id: The id of the run. Defaults to None.
-            config: The configuration for the tool. Defaults to None.
-            tool_call_id: The id of the tool call. Defaults to None.
-            kwargs: Keyword arguments to be passed to tool callbacks (event handler)
+            verbose: Whether to log the tool's progress.
+            start_color: The color to use when starting the tool.
+            color: The color to use when ending the tool.
+            callbacks: Callbacks to be called during tool execution.
+            tags: Optional list of tags associated with the tool.
+            metadata: Optional metadata associated with the tool.
+            run_name: The name of the run.
+            run_id: The id of the run.
+            config: The configuration for the tool.
+            tool_call_id: The id of the tool call.
+            **kwargs: Keyword arguments to be passed to tool callbacks (event handler)
 
         Returns:
             The output of the tool.
@@ -879,17 +878,17 @@ class ChildTool(BaseTool):
 
         Args:
             tool_input: The input to the tool.
-            verbose: Whether to log the tool's progress. Defaults to None.
-            start_color: The color to use when starting the tool. Defaults to 'green'.
-            color: The color to use when ending the tool. Defaults to 'green'.
-            callbacks: Callbacks to be called during tool execution. Defaults to None.
-            tags: Optional list of tags associated with the tool. Defaults to None.
-            metadata: Optional metadata associated with the tool. Defaults to None.
-            run_name: The name of the run. Defaults to None.
-            run_id: The id of the run. Defaults to None.
-            config: The configuration for the tool. Defaults to None.
-            tool_call_id: The id of the tool call. Defaults to None.
-            kwargs: Keyword arguments to be passed to tool callbacks
+            verbose: Whether to log the tool's progress.
+            start_color: The color to use when starting the tool.
+            color: The color to use when ending the tool.
+            callbacks: Callbacks to be called during tool execution.
+            tags: Optional list of tags associated with the tool.
+            metadata: Optional metadata associated with the tool.
+            run_name: The name of the run.
+            run_id: The id of the run.
+            config: The configuration for the tool.
+            tool_call_id: The id of the tool call.
+            **kwargs: Keyword arguments to be passed to tool callbacks
 
         Returns:
             The output of the tool.
@@ -981,7 +980,7 @@ def _is_tool_call(x: Any) -> bool:
         x: The input to check.
 
     Returns:
-        True if the input is a tool call, False otherwise.
+        `True` if the input is a tool call, `False` otherwise.
     """
     return isinstance(x, dict) and x.get("type") == "tool_call"
 
@@ -1128,7 +1127,7 @@ def _is_message_content_type(obj: Any) -> bool:
         obj: The object to check.
 
     Returns:
-        True if the object is valid message content, False otherwise.
+        `True` if the object is valid message content, `False` otherwise.
     """
     return isinstance(obj, str) or (
         isinstance(obj, list) and all(_is_message_content_block(e) for e in obj)
@@ -1144,7 +1143,7 @@ def _is_message_content_block(obj: Any) -> bool:
         obj: The object to check.
 
     Returns:
-        True if the object is a valid content block, False otherwise.
+        `True` if the object is a valid content block, `False` otherwise.
     """
     if isinstance(obj, str):
         return True
@@ -1217,24 +1216,24 @@ class InjectedToolCallId(InjectedToolArg):
     This annotation is used to mark a tool parameter that should receive
     the tool call ID at runtime.
 
-    .. code-block:: python
-
-        from typing import Annotated
-        from langchain_core.messages import ToolMessage
-        from langchain_core.tools import tool, InjectedToolCallId
-
-        @tool
-        def foo(
-            x: int, tool_call_id: Annotated[str, InjectedToolCallId]
-        ) -> ToolMessage:
-            \"\"\"Return x.\"\"\"
-            return ToolMessage(
-                str(x),
-                artifact=x,
-                name="foo",
-                tool_call_id=tool_call_id
-            )
+    ```python
+    from typing import Annotated
+    from langchain_core.messages import ToolMessage
+    from langchain_core.tools import tool, InjectedToolCallId
+
+    @tool
+    def foo(
+        x: int, tool_call_id: Annotated[str, InjectedToolCallId]
+    ) -> ToolMessage:
+        \"\"\"Return x.\"\"\"
+        return ToolMessage(
+            str(x),
+            artifact=x,
+            name="foo",
+            tool_call_id=tool_call_id
+        )
 
+    ```
     """
 
 
@@ -1248,7 +1247,7 @@ def _is_injected_arg_type(
         injected_type: The specific injected type to check for.
 
     Returns:
-        True if the type is an injected argument, False otherwise.
+        `True` if the type is an injected argument, `False` otherwise.
     """
     injected_type = injected_type or InjectedToolArg
     return any(

langchain_core/tools/convert.py

@@ -81,7 +81,7 @@ def tool(
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
 ) -> BaseTool | Callable[[Callable | Runnable], BaseTool]:
-    """Make tools out of functions, can be used with or without arguments.
+    """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
@@ -91,140 +91,136 @@ 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"}
+        ```
 
     !!! 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(
@@ -397,10 +393,10 @@ def convert_runnable_to_tool(
 
     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.

langchain_core/tools/render.py

@@ -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

@@ -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

@@ -69,7 +69,7 @@ class Tool(BaseTool):
     def _to_args_and_kwargs(
         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.
@@ -79,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
@@ -177,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.