langchain-core 1.0.7__py3-none-any.whl → 1.2.1__py3-none-any.whl

langchain_core/tools/convert.py

@@ -23,6 +23,7 @@ def tool(
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
+    extras: dict[str, Any] | None = None,
 ) -> Callable[[Callable | Runnable], BaseTool]: ...
 
 
@@ -38,6 +39,7 @@ def tool(
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
+    extras: dict[str, Any] | None = None,
 ) -> BaseTool: ...
 
 
@@ -52,6 +54,7 @@ def tool(
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
+    extras: dict[str, Any] | None = None,
 ) -> BaseTool: ...
 
 
@@ -66,6 +69,7 @@ def tool(
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
+    extras: dict[str, Any] | None = None,
 ) -> Callable[[Callable | Runnable], BaseTool]: ...
 
 
@@ -80,6 +84,7 @@ def tool(
     response_format: Literal["content", "content_and_artifact"] = "content",
     parse_docstring: bool = False,
     error_on_invalid_docstring: bool = True,
+    extras: dict[str, Any] | None = None,
 ) -> BaseTool | Callable[[Callable | Runnable], BaseTool]:
     """Convert Python functions and `Runnables` to LangChain tools.
 
@@ -130,6 +135,15 @@ def tool(
             parse parameter descriptions from Google Style function docstrings.
         error_on_invalid_docstring: If `parse_docstring` is provided, configure
             whether to raise `ValueError` on invalid Google Style docstrings.
+        extras: Optional provider-specific extra fields for the tool.
+
+            Used to pass configuration that doesn't fit into standard tool fields.
+            Chat models should process known extras when constructing model payloads.
+
+            !!! example
+
+                For example, Anthropic-specific fields like `cache_control`,
+                `defer_loading`, or `input_examples`.
 
     Raises:
         ValueError: If too many positional arguments are provided (e.g. violating the
@@ -292,6 +306,7 @@ def tool(
                     response_format=response_format,
                     parse_docstring=parse_docstring,
                     error_on_invalid_docstring=error_on_invalid_docstring,
+                    extras=extras,
                 )
             # If someone doesn't want a schema applied, we must treat it as
             # a simple string->string function
@@ -308,6 +323,7 @@ def tool(
                 return_direct=return_direct,
                 coroutine=coroutine,
                 response_format=response_format,
+                extras=extras,
             )
 
         return _tool_factory

langchain_core/tools/retriever.py

@@ -2,22 +2,21 @@
 
 from __future__ import annotations
 
-from functools import partial
 from typing import TYPE_CHECKING, Literal
 
 from pydantic import BaseModel, Field
 
+from langchain_core.callbacks import Callbacks
+from langchain_core.documents import Document
 from langchain_core.prompts import (
     BasePromptTemplate,
     PromptTemplate,
     aformat_document,
     format_document,
 )
-from langchain_core.tools.simple import Tool
+from langchain_core.tools.structured import StructuredTool
 
 if TYPE_CHECKING:
-    from langchain_core.callbacks import Callbacks
-    from langchain_core.documents import Document
     from langchain_core.retrievers import BaseRetriever
 
 
@@ -27,43 +26,6 @@ class RetrieverInput(BaseModel):
     query: str = Field(description="query to look up in retriever")
 
 
-def _get_relevant_documents(
-    query: str,
-    retriever: BaseRetriever,
-    document_prompt: BasePromptTemplate,
-    document_separator: str,
-    callbacks: Callbacks = None,
-    response_format: Literal["content", "content_and_artifact"] = "content",
-) -> 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
-    )
-    if response_format == "content_and_artifact":
-        return (content, docs)
-
-    return content
-
-
-async def _aget_relevant_documents(
-    query: str,
-    retriever: BaseRetriever,
-    document_prompt: BasePromptTemplate,
-    document_separator: str,
-    callbacks: Callbacks = None,
-    response_format: Literal["content", "content_and_artifact"] = "content",
-) -> 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]
-    )
-
-    if response_format == "content_and_artifact":
-        return (content, docs)
-
-    return content
-
-
 def create_retriever_tool(
     retriever: BaseRetriever,
     name: str,
@@ -72,7 +34,7 @@ def create_retriever_tool(
     document_prompt: BasePromptTemplate | None = None,
     document_separator: str = "\n\n",
     response_format: Literal["content", "content_and_artifact"] = "content",
-) -> Tool:
+) -> StructuredTool:
     r"""Create a tool to do retrieval of documents.
 
     Args:
@@ -93,22 +55,31 @@ def create_retriever_tool(
     Returns:
         Tool class to pass to an agent.
     """
-    document_prompt = document_prompt or PromptTemplate.from_template("{page_content}")
-    func = partial(
-        _get_relevant_documents,
-        retriever=retriever,
-        document_prompt=document_prompt,
-        document_separator=document_separator,
-        response_format=response_format,
-    )
-    afunc = partial(
-        _aget_relevant_documents,
-        retriever=retriever,
-        document_prompt=document_prompt,
-        document_separator=document_separator,
-        response_format=response_format,
-    )
-    return Tool(
+    document_prompt_ = document_prompt or PromptTemplate.from_template("{page_content}")
+
+    def func(
+        query: str, callbacks: Callbacks = None
+    ) -> 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
+        )
+        if response_format == "content_and_artifact":
+            return (content, docs)
+        return content
+
+    async def afunc(
+        query: str, callbacks: Callbacks = None
+    ) -> 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]
+        )
+        if response_format == "content_and_artifact":
+            return (content, docs)
+        return content
+
+    return StructuredTool(
         name=name,
         description=description,
         func=func,

langchain_core/tracers/event_stream.py

@@ -12,7 +12,7 @@ from typing import (
     TypeVar,
     cast,
 )
-from uuid import UUID, uuid4
+from uuid import UUID
 
 from typing_extensions import NotRequired, override
 
@@ -42,7 +42,8 @@ from langchain_core.tracers.log_stream import (
     _astream_log_implementation,
 )
 from langchain_core.tracers.memory_stream import _MemoryStream
-from langchain_core.utils.aiter import aclosing, py_anext
+from langchain_core.utils.aiter import aclosing
+from langchain_core.utils.uuid import uuid7
 
 if TYPE_CHECKING:
     from collections.abc import AsyncIterator, Iterator, Sequence
@@ -188,7 +189,7 @@ class _AstreamEventsCallbackHandler(AsyncCallbackHandler, _StreamingCallbackHand
         # atomic check and set
         tap = self.is_tapped.setdefault(run_id, sentinel)
         # wait for first chunk
-        first = await py_anext(output, default=sentinel)
+        first = await anext(output, sentinel)
         if first is sentinel:
             return
         # get run info
@@ -1006,7 +1007,11 @@ async def _astream_events_implementation_v2(
 
     # Assign the stream handler to the config
     config = ensure_config(config)
-    run_id = cast("UUID", config.setdefault("run_id", uuid4()))
+    if "run_id" in config:
+        run_id = cast("UUID", config["run_id"])
+    else:
+        run_id = uuid7()
+        config["run_id"] = run_id
     callbacks = config.get("callbacks")
     if callbacks is None:
         config["callbacks"] = [event_streamer]

langchain_core/utils/aiter.py

@@ -26,13 +26,15 @@ from typing import (
 
 from typing_extensions import override
 
+from langchain_core._api.deprecation import deprecated
+
 T = TypeVar("T")
 
 _no_default = object()
 
 
 # https://github.com/python/cpython/blob/main/Lib/test/test_asyncgen.py#L54
-# before 3.10, the builtin anext() was not available
+@deprecated(since="1.1.2", removal="2.0.0")
 def py_anext(
     iterator: AsyncIterator[T], default: T | Any = _no_default
 ) -> Awaitable[T | Any | None]:

langchain_core/utils/function_calling.py

@@ -8,6 +8,7 @@ import logging
 import types
 import typing
 import uuid
+from collections.abc import Mapping
 from typing import (
     TYPE_CHECKING,
     Annotated,
@@ -327,7 +328,7 @@ def _format_tool_to_openai_function(tool: BaseTool) -> FunctionDescription:
 
 
 def convert_to_openai_function(
-    function: dict[str, Any] | type | Callable | BaseTool,
+    function: Mapping[str, Any] | type | Callable | BaseTool,
     *,
     strict: bool | None = None,
 ) -> dict[str, Any]:
@@ -353,6 +354,7 @@ def convert_to_openai_function(
         ValueError: If function is not in a supported format.
 
     !!! warning "Behavior changed in `langchain-core` 0.3.16"
+
         `description` and `parameters` keys are now optional. Only `name` is
         required and guaranteed to be part of the output.
     """
@@ -453,7 +455,7 @@ _WellKnownOpenAITools = (
 
 
 def convert_to_openai_tool(
-    tool: dict[str, Any] | type[BaseModel] | Callable | BaseTool,
+    tool: Mapping[str, Any] | type[BaseModel] | Callable | BaseTool,
     *,
     strict: bool | None = None,
 ) -> dict[str, Any]:
@@ -477,15 +479,18 @@ def convert_to_openai_tool(
         OpenAI tool-calling API.
 
     !!! warning "Behavior changed in `langchain-core` 0.3.16"
+
         `description` and `parameters` keys are now optional. Only `name` is
         required and guaranteed to be part of the output.
 
     !!! warning "Behavior changed in `langchain-core` 0.3.44"
+
         Return OpenAI Responses API-style tools unchanged. This includes
         any dict with `"type"` in `"file_search"`, `"function"`,
         `"computer_use_preview"`, `"web_search_preview"`.
 
     !!! warning "Behavior changed in `langchain-core` 0.3.63"
+
         Added support for OpenAI's image generation built-in tool.
     """
     # Import locally to prevent circular import

langchain_core/utils/json_schema.py

@@ -170,28 +170,33 @@ def dereference_refs(
     full_schema: dict | None = None,
     skip_keys: Sequence[str] | None = None,
 ) -> dict:
-    """Resolve and inline JSON Schema $ref references in a schema object.
+    """Resolve and inline JSON Schema `$ref` references in a schema object.
 
-    This function processes a JSON Schema and resolves all $ref references by replacing
-    them with the actual referenced content. It handles both simple references and
-    complex cases like circular references and mixed $ref objects that contain
-    additional properties alongside the $ref.
+    This function processes a JSON Schema and resolves all `$ref` references by
+    replacing them with the actual referenced content.
+
+    Handles both simple references and complex cases like circular references and mixed
+    `$ref` objects that contain additional properties alongside the `$ref`.
 
     Args:
-        schema_obj: The JSON Schema object or fragment to process. This can be a
-            complete schema or just a portion of one.
-        full_schema: The complete schema containing all definitions that $refs might
-            point to. If not provided, defaults to schema_obj (useful when the
-            schema is self-contained).
-        skip_keys: Controls recursion behavior and reference resolution depth:
-            - If `None` (Default): Only recurse under '$defs' and use shallow reference
-              resolution (break cycles but don't deep-inline nested refs)
-            - If provided (even as []): Recurse under all keys and use deep reference
-              resolution (fully inline all nested references)
+        schema_obj: The JSON Schema object or fragment to process.
+
+            This can be a complete schema or just a portion of one.
+        full_schema: The complete schema containing all definitions that `$refs` might
+            point to.
+
+            If not provided, defaults to `schema_obj` (useful when the schema is
+            self-contained).
+        skip_keys: Controls recursion behavior and reference resolution depth.
+
+            - If `None` (Default): Only recurse under `'$defs'` and use shallow
+                reference resolution (break cycles but don't deep-inline nested refs)
+            - If provided (even as `[]`): Recurse under all keys and use deep reference
+                resolution (fully inline all nested references)
 
     Returns:
-        A new dictionary with all $ref references resolved and inlined. The original
-        schema_obj is not modified.
+        A new dictionary with all $ref references resolved and inlined.
+            The original `schema_obj` is not modified.
 
     Examples:
         Basic reference resolution:
@@ -203,7 +208,8 @@ def dereference_refs(
         >>> result = dereference_refs(schema)
         >>> result["properties"]["name"]  # {"type": "string"}
 
-        Mixed $ref with additional properties:
+        Mixed `$ref` with additional properties:
+
         >>> schema = {
         ...     "properties": {
         ...         "name": {"$ref": "#/$defs/base", "description": "User name"}
@@ -215,6 +221,7 @@ def dereference_refs(
         # {"type": "string", "minLength": 1, "description": "User name"}
 
         Handling circular references:
+
         >>> schema = {
         ...     "properties": {"user": {"$ref": "#/$defs/User"}},
         ...     "$defs": {
@@ -227,10 +234,11 @@ def dereference_refs(
         >>> result = dereference_refs(schema)  # Won't cause infinite recursion
 
     !!! note
+
         - Circular references are handled gracefully by breaking cycles
-        - Mixed $ref objects (with both $ref and other properties) are supported
-        - Additional properties in mixed $refs override resolved properties
-        - The $defs section is preserved in the output by default
+        - Mixed `$ref` objects (with both `$ref` and other properties) are supported
+        - Additional properties in mixed `$refs` override resolved properties
+        - The `$defs` section is preserved in the output by default
     """
     full = full_schema or schema_obj
     keys_to_skip = list(skip_keys) if skip_keys is not None else ["$defs"]

langchain_core/utils/pydantic.py

@@ -88,18 +88,18 @@ def is_pydantic_v2_subclass(cls: type) -> bool:
     """Check if the given class is Pydantic v2-like.
 
     Returns:
-        `True` if the given class is a subclass of Pydantic BaseModel 2.x.
+        `True` if the given class is a subclass of Pydantic `BaseModel` 2.x.
     """
     return issubclass(cls, BaseModel)
 
 
 def is_basemodel_subclass(cls: type) -> bool:
-    """Check if the given class is a subclass of Pydantic BaseModel.
+    """Check if the given class is a subclass of Pydantic `BaseModel`.
 
     Check if the given class is a subclass of any of the following:
 
-    * pydantic.BaseModel in Pydantic 2.x
-    * pydantic.v1.BaseModel in Pydantic 2.x
+    * `pydantic.BaseModel` in Pydantic 2.x
+    * `pydantic.v1.BaseModel` in Pydantic 2.x
 
     Returns:
         `True` if the given class is a subclass of Pydantic `BaseModel`.
@@ -112,12 +112,12 @@ def is_basemodel_subclass(cls: type) -> bool:
 
 
 def is_basemodel_instance(obj: Any) -> bool:
-    """Check if the given class is an instance of Pydantic BaseModel.
+    """Check if the given class is an instance of Pydantic `BaseModel`.
 
     Check if the given class is an instance of any of the following:
 
-    * pydantic.BaseModel in Pydantic 2.x
-    * pydantic.v1.BaseModel in Pydantic 2.x
+    * `pydantic.BaseModel` in Pydantic 2.x
+    * `pydantic.v1.BaseModel` in Pydantic 2.x
 
     Returns:
         `True` if the given class is an instance of Pydantic `BaseModel`.

langchain_core/utils/uuid.py

@@ -0,0 +1,54 @@
+"""UUID utility functions.
+
+This module exports a uuid7 function to generate monotonic, time-ordered UUIDs
+for tracing and similar operations.
+"""
+
+from __future__ import annotations
+
+import typing
+from uuid import UUID
+
+from uuid_utils.compat import uuid7 as _uuid_utils_uuid7
+
+if typing.TYPE_CHECKING:
+    from uuid import UUID
+
+_NANOS_PER_SECOND: typing.Final = 1_000_000_000
+
+
+def _to_timestamp_and_nanos(nanoseconds: int) -> tuple[int, int]:
+    """Split a nanosecond timestamp into seconds and remaining nanoseconds."""
+    seconds, nanos = divmod(nanoseconds, _NANOS_PER_SECOND)
+    return seconds, nanos
+
+
+def uuid7(nanoseconds: int | None = None) -> UUID:
+    """Generate a UUID from a Unix timestamp in nanoseconds and random bits.
+
+    UUIDv7 objects feature monotonicity within a millisecond.
+
+    Args:
+        nanoseconds: Optional ns timestamp. If not provided, uses current time.
+    """
+    # --- 48 ---   -- 4 --   --- 12 ---   -- 2 --   --- 30 ---   - 32 -
+    # unix_ts_ms | version | counter_hi | variant | counter_lo | random
+    #
+    # 'counter = counter_hi | counter_lo' is a 42-bit counter constructed
+    # with Method 1 of RFC 9562, §6.2, and its MSB is set to 0.
+    #
+    # 'random' is a 32-bit random value regenerated for every new UUID.
+    #
+    # If multiple UUIDs are generated within the same millisecond, the LSB
+    # of 'counter' is incremented by 1. When overflowing, the timestamp is
+    # advanced and the counter is reset to a random 42-bit integer with MSB
+    # set to 0.
+
+    # For now, just delegate to the uuid_utils implementation
+    if nanoseconds is None:
+        return _uuid_utils_uuid7()
+    seconds, nanos = _to_timestamp_and_nanos(nanoseconds)
+    return _uuid_utils_uuid7(timestamp=seconds, nanos=nanos)
+
+
+__all__ = ["uuid7"]

langchain_core/vectorstores/base.py

@@ -294,8 +294,9 @@ class VectorStore(ABC):
 
         Args:
             query: Input text.
-            search_type: Type of search to perform. Can be `'similarity'`, `'mmr'`, or
-                `'similarity_score_threshold'`.
+            search_type: Type of search to perform.
+
+                Can be `'similarity'`, `'mmr'`, or `'similarity_score_threshold'`.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
@@ -328,8 +329,9 @@ class VectorStore(ABC):
 
         Args:
             query: Input text.
-            search_type: Type of search to perform. Can be `'similarity'`, `'mmr'`, or
-                `'similarity_score_threshold'`.
+            search_type: Type of search to perform.
+
+                Can be `'similarity'`, `'mmr'`, or `'similarity_score_threshold'`.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
@@ -460,9 +462,10 @@ class VectorStore(ABC):
         Args:
             query: Input text.
             k: Number of `Document` objects to return.
-            **kwargs: kwargs to be passed to similarity search. Should include
-                `score_threshold`, An optional floating point value between `0` to `1`
-                to filter the resulting set of retrieved docs
+            **kwargs: Kwargs to be passed to similarity search.
+
+                Should include `score_threshold`, an optional floating point value
+                between `0` to `1` to filter the resulting set of retrieved docs.
 
         Returns:
             List of tuples of `(doc, similarity_score)`
@@ -487,9 +490,10 @@ class VectorStore(ABC):
         Args:
             query: Input text.
             k: Number of `Document` objects to return.
-            **kwargs: kwargs to be passed to similarity search. Should include
-                `score_threshold`, An optional floating point value between `0` to `1`
-                to filter the resulting set of retrieved docs
+            **kwargs: Kwargs to be passed to similarity search.
+
+                Should include `score_threshold`, an optional floating point value
+                between `0` to `1` to filter the resulting set of retrieved docs.
 
         Returns:
             List of tuples of `(doc, similarity_score)`
@@ -511,9 +515,10 @@ class VectorStore(ABC):
         Args:
             query: Input text.
             k: Number of `Document` objects to return.
-            **kwargs: kwargs to be passed to similarity search. Should include
-                `score_threshold`, An optional floating point value between `0` to `1`
-                to filter the resulting set of retrieved docs
+            **kwargs: Kwargs to be passed to similarity search.
+
+                Should include `score_threshold`, an optional floating point value
+                between `0` to `1` to filter the resulting set of retrieved docs.
 
         Returns:
             List of tuples of `(doc, similarity_score)`.
@@ -560,9 +565,10 @@ class VectorStore(ABC):
         Args:
             query: Input text.
             k: Number of `Document` objects to return.
-            **kwargs: kwargs to be passed to similarity search. Should include
-                `score_threshold`, An optional floating point value between `0` to `1`
-                to filter the resulting set of retrieved docs
+            **kwargs: Kwargs to be passed to similarity search.
+
+                Should include `score_threshold`, an optional floating point value
+                between `0` to `1` to filter the resulting set of retrieved docs.
 
         Returns:
             List of tuples of `(doc, similarity_score)`
@@ -900,13 +906,15 @@ class VectorStore(ABC):
 
         Args:
             **kwargs: Keyword arguments to pass to the search function.
+
                 Can include:
 
                 * `search_type`: Defines the type of search that the Retriever should
                     perform. Can be `'similarity'` (default), `'mmr'`, or
                     `'similarity_score_threshold'`.
-                * `search_kwargs`: Keyword arguments to pass to the search function. Can
-                    include things like:
+                * `search_kwargs`: Keyword arguments to pass to the search function.
+
+                    Can include things like:
 
                     * `k`: Amount of documents to return (Default: `4`)
                     * `score_threshold`: Minimum relevance threshold

langchain_core/version.py

@@ -1,3 +1,3 @@
 """langchain-core version information and utilities."""
 
-VERSION = "1.0.7"
+VERSION = "1.2.1"

{langchain_core-1.0.7.dist-info → langchain_core-1.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langchain-core
-Version: 1.0.7
+Version: 1.2.1
 Summary: Building applications with LLMs through composability
 Project-URL: Homepage, https://docs.langchain.com/
 Project-URL: Documentation, https://reference.langchain.com/python/langchain_core/
@@ -18,6 +18,7 @@ Requires-Dist: pydantic<3.0.0,>=2.7.4
 Requires-Dist: pyyaml<7.0.0,>=5.3.0
 Requires-Dist: tenacity!=8.4.0,<10.0.0,>=8.1.0
 Requires-Dist: typing-extensions<5.0.0,>=4.7.0
+Requires-Dist: uuid-utils<1.0,>=0.12.0
 Description-Content-Type: text/markdown
 
 # 🦜🍎️ LangChain Core