langchain-core 1.0.0rc3__py3-none-any.whl → 1.0.2__py3-none-any.whl

langchain_core/agents.py

@@ -5,12 +5,10 @@
 
 !!! warning
     New agents should be built using the
-    [langgraph library](https://github.com/langchain-ai/langgraph), which provides a
+    [`langchain` library](https://pypi.org/project/langchain/), which provides a
     simpler and more flexible way to define agents.
 
-    Please see the
-    [migration guide](https://python.langchain.com/docs/how_to/migrate_agent/) for
-    information on how to migrate existing agents to modern langgraph agents.
+    See docs on [building agents](https://docs.langchain.com/oss/python/langchain/agents).
 
 Agents use language models to choose a sequence of actions to take.
 

langchain_core/caches.py

@@ -1,7 +1,9 @@
-"""`caches` provides an optional caching layer for language models.
+"""Optional caching layer for language models.
 
-!!! warning
-    This is a beta feature! Please be wary of deploying experimental code to production
+Distinct from provider-based [prompt caching](https://docs.langchain.com/oss/python/langchain/models#prompt-caching).
+
+!!! warning "Beta feature"
+    This is a beta feature. Please be wary of deploying experimental code to production
     unless you've taken appropriate precautions.
 
 A cache is useful for two reasons:
@@ -47,17 +49,18 @@ class BaseCache(ABC):
         """Look up based on `prompt` and `llm_string`.
 
         A cache implementation is expected to generate a key from the 2-tuple
-        of prompt and llm_string (e.g., by concatenating them with a delimiter).
+        of `prompt` and `llm_string` (e.g., by concatenating them with a delimiter).
 
         Args:
             prompt: A string representation of the prompt.
                 In the case of a chat model, the prompt is a non-trivial
                 serialization of the prompt into the language model.
             llm_string: A string representation of the LLM configuration.
+
                 This is used to capture the invocation parameters of the LLM
                 (e.g., model name, temperature, stop tokens, max tokens, etc.).
-                These invocation parameters are serialized into a string
-                representation.
+
+                These invocation parameters are serialized into a string representation.
 
         Returns:
             On a cache miss, return `None`. On a cache hit, return the cached value.
@@ -76,8 +79,10 @@ class BaseCache(ABC):
                 In the case of a chat model, the prompt is a non-trivial
                 serialization of the prompt into the language model.
             llm_string: A string representation of the LLM configuration.
+
                 This is used to capture the invocation parameters of the LLM
                 (e.g., model name, temperature, stop tokens, max tokens, etc.).
+
                 These invocation parameters are serialized into a string
                 representation.
             return_val: The value to be cached. The value is a list of `Generation`
@@ -92,15 +97,17 @@ class BaseCache(ABC):
         """Async look up based on `prompt` and `llm_string`.
 
         A cache implementation is expected to generate a key from the 2-tuple
-        of prompt and llm_string (e.g., by concatenating them with a delimiter).
+        of `prompt` and `llm_string` (e.g., by concatenating them with a delimiter).
 
         Args:
             prompt: A string representation of the prompt.
                 In the case of a chat model, the prompt is a non-trivial
                 serialization of the prompt into the language model.
             llm_string: A string representation of the LLM configuration.
+
                 This is used to capture the invocation parameters of the LLM
                 (e.g., model name, temperature, stop tokens, max tokens, etc.).
+
                 These invocation parameters are serialized into a string
                 representation.
 
@@ -123,8 +130,10 @@ class BaseCache(ABC):
                 In the case of a chat model, the prompt is a non-trivial
                 serialization of the prompt into the language model.
             llm_string: A string representation of the LLM configuration.
+
                 This is used to capture the invocation parameters of the LLM
                 (e.g., model name, temperature, stop tokens, max tokens, etc.).
+
                 These invocation parameters are serialized into a string
                 representation.
             return_val: The value to be cached. The value is a list of `Generation`

langchain_core/callbacks/base.py

@@ -420,8 +420,6 @@ class RunManagerMixin:
                 (includes inherited tags).
             metadata: The metadata associated with the custom event
                 (includes inherited metadata).
-
-        !!! version-added "Added in version 0.2.15"
         """
 
 
@@ -882,8 +880,6 @@ class AsyncCallbackHandler(BaseCallbackHandler):
                 (includes inherited tags).
             metadata: The metadata associated with the custom event
                 (includes inherited metadata).
-
-        !!! version-added "Added in version 0.2.15"
         """
 
 

langchain_core/callbacks/manager.py

@@ -1566,9 +1566,6 @@ class CallbackManager(BaseCallbackManager):
 
         Raises:
             ValueError: If additional keyword arguments are passed.
-
-        !!! version-added "Added in version 0.2.14"
-
         """
         if not self.handlers:
             return
@@ -2042,8 +2039,6 @@ class AsyncCallbackManager(BaseCallbackManager):
 
         Raises:
             ValueError: If additional keyword arguments are passed.
-
-        !!! version-added "Added in version 0.2.14"
         """
         if not self.handlers:
             return
@@ -2555,9 +2550,6 @@ async def adispatch_custom_event(
         This is due to a limitation in asyncio for python <= 3.10 that prevents
         LangChain from automatically propagating the config object on the user's
         behalf.
-
-    !!! version-added "Added in version 0.2.15"
-
     """
     # Import locally to prevent circular imports.
     from langchain_core.runnables.config import (  # noqa: PLC0415
@@ -2630,9 +2622,6 @@ def dispatch_custom_event(
         foo_ = RunnableLambda(foo)
         foo_.invoke({"a": "1"}, {"callbacks": [CustomCallbackManager()]})
         ```
-
-    !!! version-added "Added in version 0.2.15"
-
     """
     # Import locally to prevent circular imports.
     from langchain_core.runnables.config import (  # noqa: PLC0415

langchain_core/chat_history.py

@@ -121,7 +121,7 @@ class BaseChatMessageHistory(ABC):
         This method may be deprecated in a future release.
 
         Args:
-            message: The human message to add to the store.
+            message: The `HumanMessage` to add to the store.
         """
         if isinstance(message, HumanMessage):
             self.add_message(message)
@@ -129,7 +129,7 @@ class BaseChatMessageHistory(ABC):
             self.add_message(HumanMessage(content=message))
 
     def add_ai_message(self, message: AIMessage | str) -> None:
-        """Convenience method for adding an AI message string to the store.
+        """Convenience method for adding an `AIMessage` string to the store.
 
         !!! note
             This is a convenience method. Code should favor the bulk `add_messages`
@@ -138,7 +138,7 @@ class BaseChatMessageHistory(ABC):
         This method may be deprecated in a future release.
 
         Args:
-            message: The AI message to add.
+            message: The `AIMessage` to add.
         """
         if isinstance(message, AIMessage):
             self.add_message(message)
@@ -173,7 +173,7 @@ class BaseChatMessageHistory(ABC):
         in an efficient manner to avoid unnecessary round-trips to the underlying store.
 
         Args:
-            messages: A sequence of BaseMessage objects to store.
+            messages: A sequence of `BaseMessage` objects to store.
         """
         for message in messages:
             self.add_message(message)
@@ -182,7 +182,7 @@ class BaseChatMessageHistory(ABC):
         """Async add a list of messages.
 
         Args:
-            messages: A sequence of BaseMessage objects to store.
+            messages: A sequence of `BaseMessage` objects to store.
         """
         await run_in_executor(None, self.add_messages, messages)
 

langchain_core/document_loaders/base.py

@@ -27,7 +27,7 @@ class BaseLoader(ABC):  # noqa: B024
     """Interface for Document Loader.
 
     Implementations should implement the lazy-loading method using generators
-    to avoid loading all Documents into memory at once.
+    to avoid loading all documents into memory at once.
 
     `load` is provided just for user convenience and should not be overridden.
     """
@@ -53,9 +53,11 @@ class BaseLoader(ABC):  # noqa: B024
     def load_and_split(
         self, text_splitter: TextSplitter | None = None
     ) -> list[Document]:
-        """Load Documents and split into chunks. Chunks are returned as `Document`.
+        """Load `Document` and split into chunks. Chunks are returned as `Document`.
 
-        Do not override this method. It should be considered to be deprecated!
+        !!! danger
+
+            Do not override this method. It should be considered to be deprecated!
 
         Args:
             text_splitter: `TextSplitter` instance to use for splitting documents.
@@ -135,7 +137,7 @@ class BaseBlobParser(ABC):
         """
 
     def parse(self, blob: Blob) -> list[Document]:
-        """Eagerly parse the blob into a `Document` or `Document` objects.
+        """Eagerly parse the blob into a `Document` or list of `Document` objects.
 
         This is a convenience method for interactive development environment.
 

langchain_core/document_loaders/blob_loaders.py

@@ -28,7 +28,7 @@ class BlobLoader(ABC):
     def yield_blobs(
         self,
     ) -> Iterable[Blob]:
-        """A lazy loader for raw data represented by LangChain's Blob object.
+        """A lazy loader for raw data represented by LangChain's `Blob` object.
 
         Returns:
             A generator over blobs

langchain_core/document_loaders/langsmith.py

@@ -14,13 +14,13 @@ from langchain_core.documents import Document
 
 
 class LangSmithLoader(BaseLoader):
-    """Load LangSmith Dataset examples as Documents.
+    """Load LangSmith Dataset examples as `Document` objects.
 
-    Loads the example inputs as the Document page content and places the entire example
-    into the Document metadata. This allows you to easily create few-shot example
-    retrievers from the loaded documents.
+    Loads the example inputs as the `Document` page content and places the entire
+    example into the `Document` metadata. This allows you to easily create few-shot
+    example retrievers from the loaded documents.
 
-    ??? note "Lazy load"
+    ??? note "Lazy loading example"
 
         ```python
         from langchain_core.document_loaders import LangSmithLoader
@@ -34,9 +34,6 @@ class LangSmithLoader(BaseLoader):
         ```python
         # -> [Document("...", metadata={"inputs": {...}, "outputs": {...}, ...}), ...]
         ```
-
-    !!! version-added "Added in version 0.2.34"
-
     """
 
     def __init__(
@@ -69,12 +66,11 @@ class LangSmithLoader(BaseLoader):
             format_content: Function for converting the content extracted from the example
                 inputs into a string. Defaults to JSON-encoding the contents.
             example_ids: The IDs of the examples to filter by.
-            as_of: The dataset version tag OR
-                timestamp to retrieve the examples as of.
-                Response examples will only be those that were present at the time
-                of the tagged (or timestamped) version.
+            as_of: The dataset version tag or timestamp to retrieve the examples as of.
+                Response examples will only be those that were present at the time of
+                the tagged (or timestamped) version.
             splits: A list of dataset splits, which are
-                divisions of your dataset such as 'train', 'test', or 'validation'.
+                divisions of your dataset such as `train`, `test`, or `validation`.
                 Returns examples only from the specified splits.
             inline_s3_urls: Whether to inline S3 URLs.
             offset: The offset to start from.

langchain_core/documents/__init__.py

@@ -1,7 +1,28 @@
-"""Documents module.
+"""Documents module for data retrieval and processing workflows.
 
-**Document** module is a collection of classes that handle documents
-and their transformations.
+This module provides core abstractions for handling data in retrieval-augmented
+generation (RAG) pipelines, vector stores, and document processing workflows.
+
+!!! warning "Documents vs. message content"
+    This module is distinct from `langchain_core.messages.content`, which provides
+    multimodal content blocks for **LLM chat I/O** (text, images, audio, etc. within
+    messages).
+
+    **Key distinction:**
+
+    - **Documents** (this module): For **data retrieval and processing workflows**
+        - Vector stores, retrievers, RAG pipelines
+        - Text chunking, embedding, and semantic search
+        - Example: Chunks of a PDF stored in a vector database
+
+    - **Content Blocks** (`messages.content`): For **LLM conversational I/O**
+        - Multimodal message content sent to/from models
+        - Tool calls, reasoning, citations within chat
+        - Example: An image sent to a vision model in a chat message (via
+            [`ImageContentBlock`][langchain.messages.ImageContentBlock])
+
+    While both can represent similar data types (text, files), they serve different
+    architectural purposes in LangChain applications.
 """
 
 from typing import TYPE_CHECKING

langchain_core/documents/base.py

@@ -1,4 +1,16 @@
-"""Base classes for media and documents."""
+"""Base classes for media and documents.
+
+This module contains core abstractions for **data retrieval and processing workflows**:
+
+- `BaseMedia`: Base class providing `id` and `metadata` fields
+- `Blob`: Raw data loading (files, binary data) - used by document loaders
+- `Document`: Text content for retrieval (RAG, vector stores, semantic search)
+
+!!! note "Not for LLM chat messages"
+    These classes are for data processing pipelines, not LLM I/O. For multimodal
+    content in chat messages (images, audio in conversations), see
+    `langchain.messages` content blocks instead.
+"""
 
 from __future__ import annotations
 
@@ -19,27 +31,23 @@ PathLike = str | PurePath
 
 
 class BaseMedia(Serializable):
-    """Use to represent media content.
-
-    Media objects can be used to represent raw data, such as text or binary data.
+    """Base class for content used in retrieval and data processing workflows.
 
-    LangChain Media objects allow associating metadata and an optional identifier
-    with the content.
+    Provides common fields for content that needs to be stored, indexed, or searched.
 
-    The presence of an ID and metadata make it easier to store, index, and search
-    over the content in a structured way.
+    !!! note
+        For multimodal content in **chat messages** (images, audio sent to/from LLMs),
+        use `langchain.messages` content blocks instead.
     """
 
     # The ID field is optional at the moment.
     # It will likely become required in a future major release after
-    # it has been adopted by enough vectorstore implementations.
+    # it has been adopted by enough VectorStore implementations.
     id: str | None = Field(default=None, coerce_numbers_to_str=True)
     """An optional identifier for the document.
 
     Ideally this should be unique across the document collection and formatted
     as a UUID, but this will not be enforced.
-
-    !!! version-added "Added in version 0.2.11"
     """
 
     metadata: dict = Field(default_factory=dict)
@@ -47,65 +55,64 @@ class BaseMedia(Serializable):
 
 
 class Blob(BaseMedia):
-    """Blob represents raw data by either reference or value.
+    """Raw data abstraction for document loading and file processing.
 
-    Provides an interface to materialize the blob in different representations, and
-    help to decouple the development of data loaders from the downstream parsing of
-    the raw data.
+    Represents raw bytes or text, either in-memory or by file reference. Used
+    primarily by document loaders to decouple data loading from parsing.
 
-    Inspired by: https://developer.mozilla.org/en-US/docs/Web/API/Blob
+    Inspired by [Mozilla's `Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob)
 
-    Example: Initialize a blob from in-memory data
+    ???+ example "Initialize a blob from in-memory data"
 
-    ```python
-    from langchain_core.documents import Blob
+        ```python
+        from langchain_core.documents import Blob
 
-    blob = Blob.from_data("Hello, world!")
+        blob = Blob.from_data("Hello, world!")
 
-    # Read the blob as a string
-    print(blob.as_string())
+        # Read the blob as a string
+        print(blob.as_string())
 
-    # Read the blob as bytes
-    print(blob.as_bytes())
+        # Read the blob as bytes
+        print(blob.as_bytes())
 
-    # Read the blob as a byte stream
-    with blob.as_bytes_io() as f:
-        print(f.read())
-    ```
+        # Read the blob as a byte stream
+        with blob.as_bytes_io() as f:
+            print(f.read())
+        ```
 
-    Example: Load from memory and specify mime-type and metadata
+    ??? example "Load from memory and specify MIME type and metadata"
 
-    ```python
-    from langchain_core.documents import Blob
+        ```python
+        from langchain_core.documents import Blob
 
-    blob = Blob.from_data(
-        data="Hello, world!",
-        mime_type="text/plain",
-        metadata={"source": "https://example.com"},
-    )
-    ```
+        blob = Blob.from_data(
+            data="Hello, world!",
+            mime_type="text/plain",
+            metadata={"source": "https://example.com"},
+        )
+        ```
 
-    Example: Load the blob from a file
+    ??? example "Load the blob from a file"
 
-    ```python
-    from langchain_core.documents import Blob
+        ```python
+        from langchain_core.documents import Blob
 
-    blob = Blob.from_path("path/to/file.txt")
+        blob = Blob.from_path("path/to/file.txt")
 
-    # Read the blob as a string
-    print(blob.as_string())
+        # Read the blob as a string
+        print(blob.as_string())
 
-    # Read the blob as bytes
-    print(blob.as_bytes())
+        # Read the blob as bytes
+        print(blob.as_bytes())
 
-    # Read the blob as a byte stream
-    with blob.as_bytes_io() as f:
-        print(f.read())
-    ```
+        # Read the blob as a byte stream
+        with blob.as_bytes_io() as f:
+            print(f.read())
+        ```
     """
 
     data: bytes | str | None = None
-    """Raw data associated with the blob."""
+    """Raw data associated with the `Blob`."""
     mimetype: str | None = None
     """MimeType not to be confused with a file extension."""
     encoding: str = "utf-8"
@@ -125,7 +132,7 @@ class Blob(BaseMedia):
     def source(self) -> str | None:
         """The source location of the blob as string if known otherwise none.
 
-        If a path is associated with the blob, it will default to the path location.
+        If a path is associated with the `Blob`, it will default to the path location.
 
         Unless explicitly set via a metadata field called `"source"`, in which
         case that value will be used instead.
@@ -213,13 +220,13 @@ class Blob(BaseMedia):
         Args:
             path: Path-like object to file to be read
             encoding: Encoding to use if decoding the bytes into a string
-            mime_type: If provided, will be set as the mime-type of the data
-            guess_type: If `True`, the mimetype will be guessed from the file extension,
-                if a mime-type was not provided
-            metadata: Metadata to associate with the blob
+            mime_type: If provided, will be set as the MIME type of the data
+            guess_type: If `True`, the MIME type will be guessed from the file
+                extension, if a MIME type was not provided
+            metadata: Metadata to associate with the `Blob`
 
         Returns:
-            Blob instance
+            `Blob` instance
         """
         if mime_type is None and guess_type:
             mimetype = mimetypes.guess_type(path)[0] if guess_type else None
@@ -245,17 +252,17 @@ class Blob(BaseMedia):
         path: str | None = None,
         metadata: dict | None = None,
     ) -> Blob:
-        """Initialize the blob from in-memory data.
+        """Initialize the `Blob` from in-memory data.
 
         Args:
-            data: The in-memory data associated with the blob
+            data: The in-memory data associated with the `Blob`
             encoding: Encoding to use if decoding the bytes into a string
-            mime_type: If provided, will be set as the mime-type of the data
+            mime_type: If provided, will be set as the MIME type of the data
             path: If provided, will be set as the source from which the data came
-            metadata: Metadata to associate with the blob
+            metadata: Metadata to associate with the `Blob`
 
         Returns:
-            Blob instance
+            `Blob` instance
         """
         return cls(
             data=data,
@@ -276,6 +283,10 @@ class Blob(BaseMedia):
 class Document(BaseMedia):
     """Class for storing a piece of text and associated metadata.
 
+    !!! note
+        `Document` is for **retrieval workflows**, not chat I/O. For sending text
+        to an LLM in a conversation, use message types from `langchain.messages`.
+
     Example:
         ```python
         from langchain_core.documents import Document

langchain_core/documents/compressor.py

@@ -21,14 +21,14 @@ class BaseDocumentCompressor(BaseModel, ABC):
 
     This abstraction is primarily used for post-processing of retrieved documents.
 
-    Documents matching a given query are first retrieved.
+    `Document` objects matching a given query are first retrieved.
 
     Then the list of documents can be further processed.
 
     For example, one could re-rank the retrieved documents using an LLM.
 
     !!! note
-        Users should favor using a RunnableLambda instead of sub-classing from this
+        Users should favor using a `RunnableLambda` instead of sub-classing from this
         interface.
 
     """
@@ -43,9 +43,9 @@ class BaseDocumentCompressor(BaseModel, ABC):
         """Compress retrieved documents given the query context.
 
         Args:
-            documents: The retrieved documents.
+            documents: The retrieved `Document` objects.
             query: The query context.
-            callbacks: Optional callbacks to run during compression.
+            callbacks: Optional `Callbacks` to run during compression.
 
         Returns:
             The compressed documents.
@@ -61,9 +61,9 @@ class BaseDocumentCompressor(BaseModel, ABC):
         """Async compress retrieved documents given the query context.
 
         Args:
-            documents: The retrieved documents.
+            documents: The retrieved `Document` objects.
             query: The query context.
-            callbacks: Optional callbacks to run during compression.
+            callbacks: Optional `Callbacks` to run during compression.
 
         Returns:
             The compressed documents.

langchain_core/documents/transformers.py

@@ -16,8 +16,8 @@ if TYPE_CHECKING:
 class BaseDocumentTransformer(ABC):
     """Abstract base class for document transformation.
 
-    A document transformation takes a sequence of Documents and returns a
-    sequence of transformed Documents.
+    A document transformation takes a sequence of `Document` objects and returns a
+    sequence of transformed `Document` objects.
 
     Example:
         ```python
@@ -57,10 +57,10 @@ class BaseDocumentTransformer(ABC):
         """Transform a list of documents.
 
         Args:
-            documents: A sequence of Documents to be transformed.
+            documents: A sequence of `Document` objects to be transformed.
 
         Returns:
-            A sequence of transformed Documents.
+            A sequence of transformed `Document` objects.
         """
 
     async def atransform_documents(
@@ -69,10 +69,10 @@ class BaseDocumentTransformer(ABC):
         """Asynchronously transform a list of documents.
 
         Args:
-            documents: A sequence of Documents to be transformed.
+            documents: A sequence of `Document` objects to be transformed.
 
         Returns:
-            A sequence of transformed Documents.
+            A sequence of transformed `Document` objects.
         """
         return await run_in_executor(
             None, self.transform_documents, documents, **kwargs

langchain_core/embeddings/fake.py

@@ -18,7 +18,7 @@ class FakeEmbeddings(Embeddings, BaseModel):
 
     This embedding model creates embeddings by sampling from a normal distribution.
 
-    !!! warning
+    !!! danger "Toy model"
         Do not use this outside of testing, as it is not a real embedding model.
 
     Instantiate:
@@ -73,7 +73,7 @@ class DeterministicFakeEmbedding(Embeddings, BaseModel):
     This embedding model creates embeddings by sampling from a normal distribution
     with a seed based on the hash of the text.
 
-    !!! warning
+    !!! danger "Toy model"
         Do not use this outside of testing, as it is not a real embedding model.
 
     Instantiate: