langchain-core 0.3.75__py3-none-any.whl → 0.3.76__py3-none-any.whl

langchain_core/sys_info.py

@@ -1,12 +1,18 @@
-"""**sys_info** prints information about the system and langchain packages for debugging purposes."""  # noqa: E501
+"""**sys_info** implementation.
 
+sys_info prints information about the system and langchain packages for
+debugging purposes.
+"""
+
+import pkgutil
+import platform
+import sys
 from collections.abc import Sequence
+from importlib import metadata, util
 
 
 def _get_sub_deps(packages: Sequence[str]) -> list[str]:
     """Get any specified sub-dependencies."""
-    from importlib import metadata
-
     sub_deps = set()
     underscored_packages = {pkg.replace("-", "_") for pkg in packages}
 
@@ -33,11 +39,6 @@ def print_sys_info(*, additional_pkgs: Sequence[str] = ()) -> None:
     Args:
         additional_pkgs: Additional packages to include in the output.
     """
-    import pkgutil
-    import platform
-    import sys
-    from importlib import metadata, util
-
     # Packages that do not start with "langchain" prefix.
     other_langchain_packages = [
         "langserve",

langchain_core/tools/base.py

@@ -81,6 +81,7 @@ TOOL_MESSAGE_BLOCK_TYPES = (
     "json",
     "search_result",
     "custom_tool_call_output",
+    "document",
 )
 
 
@@ -271,15 +272,12 @@ def _function_annotations_are_pydantic_v1(
 
 
 class _SchemaConfig:
-    """Configuration for Pydantic models generated from function signatures.
-
-    Attributes:
-        extra: Whether to allow extra fields in the model.
-        arbitrary_types_allowed: Whether to allow arbitrary types in the model.
-    """
+    """Configuration for Pydantic models generated from function signatures."""
 
     extra: str = "forbid"
+    """Whether to allow extra fields in the model."""
     arbitrary_types_allowed: bool = True
+    """Whether to allow arbitrary types in the model."""
 
 
 def create_schema_from_function(
@@ -506,7 +504,12 @@ class ChildTool(BaseTool):
     """
 
     def __init__(self, **kwargs: Any) -> None:
-        """Initialize the tool."""
+        """Initialize the tool.
+
+        Raises:
+            TypeError: If ``args_schema`` is not a subclass of pydantic ``BaseModel`` or
+                dict.
+        """
         if (
             "args_schema" in kwargs
             and kwargs["args_schema"] is not None
@@ -628,9 +631,10 @@ class ChildTool(BaseTool):
             The parsed and validated input.
 
         Raises:
-            ValueError: If string input is provided with JSON schema or if
-                InjectedToolCallId is required but not provided.
-            NotImplementedError: If args_schema is not a supported type.
+            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.
         """
         input_args = self.args_schema
         if isinstance(tool_input, str):
@@ -655,10 +659,7 @@ class ChildTool(BaseTool):
                 return tool_input
             if issubclass(input_args, BaseModel):
                 for k, v in get_all_basemodel_annotations(input_args).items():
-                    if (
-                        _is_injected_arg_type(v, injected_type=InjectedToolCallId)
-                        and k not in tool_input
-                    ):
+                    if _is_injected_arg_type(v, injected_type=InjectedToolCallId):
                         if tool_call_id is None:
                             msg = (
                                 "When tool includes an InjectedToolCallId "
@@ -673,10 +674,7 @@ class ChildTool(BaseTool):
                 result_dict = result.model_dump()
             elif issubclass(input_args, BaseModelV1):
                 for k, v in get_all_basemodel_annotations(input_args).items():
-                    if (
-                        _is_injected_arg_type(v, injected_type=InjectedToolCallId)
-                        and k not in tool_input
-                    ):
+                    if _is_injected_arg_type(v, injected_type=InjectedToolCallId):
                         if tool_call_id is None:
                             msg = (
                                 "When tool includes an InjectedToolCallId "
@@ -725,6 +723,9 @@ class ChildTool(BaseTool):
 
         Add run_manager: Optional[CallbackManagerForToolRun] = None
         to child implementations to enable tracing.
+
+        Returns:
+            The result of the tool execution.
         """
 
     async def _arun(self, *args: Any, **kwargs: Any) -> Any:
@@ -732,6 +733,9 @@ class ChildTool(BaseTool):
 
         Add run_manager: Optional[AsyncCallbackManagerForToolRun] = None
         to child implementations to enable tracing.
+
+        Returns:
+            The result of the tool execution.
         """
         if kwargs.get("run_manager") and signature(self._run).parameters.get(
             "run_manager"
@@ -1285,7 +1289,7 @@ class InjectedToolCallId(InjectedToolArg):
 
 
 def _is_injected_arg_type(
-    type_: type, injected_type: Optional[type[InjectedToolArg]] = None
+    type_: Union[type, TypeVar], injected_type: Optional[type[InjectedToolArg]] = None
 ) -> bool:
     """Check if a type annotation indicates an injected argument.
 
@@ -1306,12 +1310,15 @@ def _is_injected_arg_type(
 
 def get_all_basemodel_annotations(
     cls: Union[TypeBaseModel, Any], *, default_to_bound: bool = True
-) -> dict[str, type]:
+) -> dict[str, Union[type, TypeVar]]:
     """Get all annotations from a Pydantic BaseModel and its parents.
 
     Args:
         cls: The Pydantic BaseModel class.
         default_to_bound: Whether to default to the bound of a TypeVar if it exists.
+
+    Returns:
+        A dictionary of field names to their type annotations.
     """
     # cls has no subscript: cls = FooBar
     if isinstance(cls, type):
@@ -1319,7 +1326,7 @@ def get_all_basemodel_annotations(
         fields = getattr(cls, "model_fields", {}) or getattr(cls, "__fields__", {})
         alias_map = {field.alias: name for name, field in fields.items() if field.alias}
 
-        annotations: dict[str, type] = {}
+        annotations: dict[str, Union[type, TypeVar]] = {}
         for name, param in inspect.signature(cls).parameters.items():
             # Exclude hidden init args added by pydantic Config. For example if
             # BaseModel(extra="allow") then "extra_data" will part of init sig.
@@ -1373,11 +1380,11 @@ def get_all_basemodel_annotations(
 
 
 def _replace_type_vars(
-    type_: type,
+    type_: Union[type, TypeVar],
     generic_map: Optional[dict[TypeVar, type]] = None,
     *,
     default_to_bound: bool = True,
-) -> type:
+) -> Union[type, TypeVar]:
     """Replace TypeVars in a type annotation with concrete types.
 
     Args:

langchain_core/tools/convert.py

@@ -92,12 +92,13 @@ 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.
@@ -119,6 +120,17 @@ def tool(
             whether to raise ValueError on invalid Google Style docstrings.
             Defaults to True.
 
+    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.
 
@@ -134,11 +146,13 @@ def tool(
                 # 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"}
@@ -171,18 +185,15 @@ def tool(
                     "bar": {
                         "title": "Bar",
                         "description": "The bar.",
-                        "type": "string"
+                        "type": "string",
                     },
                     "baz": {
                         "title": "Baz",
                         "description": "The baz.",
-                        "type": "integer"
-                    }
+                        "type": "integer",
+                    },
                 },
-                "required": [
-                    "bar",
-                    "baz"
-                ]
+                "required": ["bar", "baz"],
             }
 
         Note that parsing by default will raise ``ValueError`` if the docstring

langchain_core/tools/simple.py

@@ -76,7 +76,19 @@ class Tool(BaseTool):
     def _to_args_and_kwargs(
         self, tool_input: Union[str, dict], tool_call_id: Optional[str]
     ) -> tuple[tuple, dict]:
-        """Convert tool input to pydantic model."""
+        """Convert tool input to pydantic model.
+
+        Args:
+            tool_input: The input to the tool.
+            tool_call_id: The ID of the tool call.
+
+        Raises:
+            ToolException: If the tool input is invalid.
+
+        Returns:
+            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
         all_args = list(args) + list(kwargs.values())
@@ -96,7 +108,17 @@ class Tool(BaseTool):
         run_manager: Optional[CallbackManagerForToolRun] = None,
         **kwargs: Any,
     ) -> Any:
-        """Use the tool."""
+        """Use the tool.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            config: Configuration for the run
+            run_manager: Optional callback manager to use for the run
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of the tool execution
+        """
         if self.func:
             if run_manager and signature(self.func).parameters.get("callbacks"):
                 kwargs["callbacks"] = run_manager.get_child()
@@ -113,7 +135,17 @@ class Tool(BaseTool):
         run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
         **kwargs: Any,
     ) -> Any:
-        """Use the tool asynchronously."""
+        """Use the tool asynchronously.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            config: Configuration for the run
+            run_manager: Optional callback manager to use for the run
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of the tool execution
+        """
         if self.coroutine:
             if run_manager and signature(self.coroutine).parameters.get("callbacks"):
                 kwargs["callbacks"] = run_manager.get_child()

langchain_core/tools/structured.py

@@ -84,7 +84,17 @@ class StructuredTool(BaseTool):
         run_manager: Optional[CallbackManagerForToolRun] = None,
         **kwargs: Any,
     ) -> Any:
-        """Use the tool."""
+        """Use the tool.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            config: Configuration for the run
+            run_manager: Optional callback manager to use for the run
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of the tool execution
+        """
         if self.func:
             if run_manager and signature(self.func).parameters.get("callbacks"):
                 kwargs["callbacks"] = run_manager.get_child()
@@ -101,7 +111,17 @@ class StructuredTool(BaseTool):
         run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
         **kwargs: Any,
     ) -> Any:
-        """Use the tool asynchronously."""
+        """Use the tool asynchronously.
+
+        Args:
+            *args: Positional arguments to pass to the tool
+            config: Configuration for the run
+            run_manager: Optional callback manager to use for the run
+            **kwargs: Keyword arguments to pass to the tool
+
+        Returns:
+            The result of the tool execution
+        """
         if self.coroutine:
             if run_manager and signature(self.coroutine).parameters.get("callbacks"):
                 kwargs["callbacks"] = run_manager.get_child()
@@ -164,6 +184,9 @@ class StructuredTool(BaseTool):
 
         Raises:
             ValueError: If the function is not provided.
+            ValueError: If the function does not have a docstring and description
+                is not provided.
+            TypeError: If the ``args_schema`` is not a ``BaseModel`` or dict.
 
         Examples:
 

langchain_core/tracers/base.py

@@ -520,11 +520,11 @@ class BaseTracer(_TracerCore, BaseCallbackHandler, ABC):
         return retrieval_run
 
     def __deepcopy__(self, memo: dict) -> BaseTracer:
-        """Deepcopy the tracer."""
+        """Return self."""
         return self
 
     def __copy__(self) -> BaseTracer:
-        """Copy the tracer."""
+        """Return self."""
         return self
 
 

langchain_core/tracers/context.py

@@ -43,7 +43,11 @@ run_collector_var: ContextVar[Optional[RunCollectorCallbackHandler]] = ContextVa
 def tracing_enabled(
     session_name: str = "default",  # noqa: ARG001
 ) -> Generator[TracerSessionV1, None, None]:
-    """Throw an error because this has been replaced by tracing_v2_enabled."""
+    """Throw an error because this has been replaced by ``tracing_v2_enabled``.
+
+    Raises:
+        RuntimeError: Always, because this function is deprecated.
+    """
     msg = (
         "tracing_enabled is no longer supported. Please use tracing_enabled_v2 instead."
     )

langchain_core/tracers/core.py

@@ -71,7 +71,7 @@ class _TracerCore(ABC):
                   for streaming events.
                 - 'original+chat' is a format that is the same as 'original'
                   except it does NOT raise an attribute error on_chat_model_start
-            kwargs: Additional keyword arguments that will be passed to
+            **kwargs: Additional keyword arguments that will be passed to
                 the superclass.
         """
         super().__init__(**kwargs)
@@ -82,7 +82,7 @@ class _TracerCore(ABC):
         """Map of run ID to (trace_id, dotted_order). Cleared when tracer GCed."""
 
     @abstractmethod
-    def _persist_run(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:
+    def _persist_run(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:
         """Persist a run."""
 
     @staticmethod
@@ -108,7 +108,7 @@ class _TracerCore(ABC):
         except:  # noqa: E722
             return msg
 
-    def _start_trace(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # type: ignore[return]
+    def _start_trace(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # type: ignore[return]
         current_dotted_order = run.start_time.strftime("%Y%m%dT%H%M%S%fZ") + str(run.id)
         if run.parent_run_id:
             if parent := self.order_map.get(run.parent_run_id):
@@ -531,27 +531,43 @@ class _TracerCore(ABC):
         return retrieval_run
 
     def __deepcopy__(self, memo: dict) -> _TracerCore:
-        """Deepcopy the tracer."""
+        """Return self deepcopied."""
         return self
 
     def __copy__(self) -> _TracerCore:
-        """Copy the tracer."""
+        """Return self copied."""
         return self
 
-    def _end_trace(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """End a trace for a run."""
+    def _end_trace(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """End a trace for a run.
+
+        Args:
+            run: The run.
+        """
         return None
 
-    def _on_run_create(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process a run upon creation."""
+    def _on_run_create(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process a run upon creation.
+
+        Args:
+            run: The created run.
+        """
         return None
 
-    def _on_run_update(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process a run upon update."""
+    def _on_run_update(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process a run upon update.
+
+        Args:
+            run: The updated run.
+        """
         return None
 
-    def _on_llm_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run upon start."""
+    def _on_llm_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run upon start.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
     def _on_llm_new_token(
@@ -559,54 +575,108 @@ class _TracerCore(ABC):
         run: Run,  # noqa: ARG002
         token: str,  # noqa: ARG002
         chunk: Optional[Union[GenerationChunk, ChatGenerationChunk]],  # noqa: ARG002
-    ) -> Union[None, Coroutine[Any, Any, None]]:
-        """Process new LLM token."""
+    ) -> Union[Coroutine[Any, Any, None], None]:
+        """Process new LLM token.
+
+        Args:
+            run: The LLM run.
+            token: The new token.
+            chunk: Optional chunk.
+        """
         return None
 
-    def _on_llm_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run."""
+    def _on_llm_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
-    def _on_llm_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the LLM Run upon error."""
+    def _on_llm_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the LLM Run upon error.
+
+        Args:
+            run: The LLM run.
+        """
         return None
 
-    def _on_chain_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run upon start."""
+    def _on_chain_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run upon start.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_chain_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run."""
+    def _on_chain_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_chain_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chain Run upon error."""
+    def _on_chain_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chain Run upon error.
+
+        Args:
+            run: The chain run.
+        """
         return None
 
-    def _on_tool_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run upon start."""
+    def _on_tool_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run upon start.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_tool_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run."""
+    def _on_tool_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_tool_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Tool Run upon error."""
+    def _on_tool_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Tool Run upon error.
+
+        Args:
+            run: The tool run.
+        """
         return None
 
-    def _on_chat_model_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Chat Model Run upon start."""
+    def _on_chat_model_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Chat Model Run upon start.
+
+        Args:
+            run: The chat model run.
+        """
         return None
 
-    def _on_retriever_start(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run upon start."""
+    def _on_retriever_start(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run upon start.
+
+        Args:
+            run: The retriever run.
+        """
         return None
 
-    def _on_retriever_end(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run."""
+    def _on_retriever_end(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run.
+
+        Args:
+            run: The retriever run.
+        """
         return None
 
-    def _on_retriever_error(self, run: Run) -> Union[None, Coroutine[Any, Any, None]]:  # noqa: ARG002
-        """Process the Retriever Run upon error."""
+    def _on_retriever_error(self, run: Run) -> Union[Coroutine[Any, Any, None], None]:  # noqa: ARG002
+        """Process the Retriever Run upon error.
+
+        Args:
+            run: The retriever run.
+        """
         return None