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

langchain_core/callbacks/usage.py

@@ -12,6 +12,7 @@ from langchain_core.callbacks import BaseCallbackHandler
 from langchain_core.messages import AIMessage
 from langchain_core.messages.ai import UsageMetadata, add_usage
 from langchain_core.outputs import ChatGeneration, LLMResult
+from langchain_core.tracers.context import register_configure_hook
 
 
 class UsageMetadataCallbackHandler(BaseCallbackHandler):
@@ -101,6 +102,9 @@ def get_usage_metadata_callback(
         name (str): The name of the context variable. Defaults to
             ``'usage_metadata_callback'``.
 
+    Yields:
+        The usage metadata callback.
+
     Example:
         .. code-block:: python
 
@@ -130,8 +134,6 @@ def get_usage_metadata_callback(
     .. versionadded:: 0.3.49
 
     """
-    from langchain_core.tracers.context import register_configure_hook
-
     usage_metadata_callback_var: ContextVar[Optional[UsageMetadataCallbackHandler]] = (
         ContextVar(name, default=None)
     )

langchain_core/chat_history.py

@@ -27,6 +27,7 @@ from langchain_core.messages import (
     HumanMessage,
     get_buffer_string,
 )
+from langchain_core.runnables.config import run_in_executor
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -109,17 +110,18 @@ class BaseChatMessageHistory(ABC):
 
         In general, fetching messages may involve IO to the underlying
         persistence layer.
-        """
-        from langchain_core.runnables.config import run_in_executor
 
+        Returns:
+            The messages.
+        """
         return await run_in_executor(None, lambda: self.messages)
 
     def add_user_message(self, message: Union[HumanMessage, str]) -> None:
         """Convenience method for adding a human message string to the store.
 
-        Please note that this is a convenience method. Code should favor the
-        bulk add_messages interface instead to save on round-trips to the underlying
-        persistence layer.
+        .. note::
+            This is a convenience method. Code should favor the bulk ``add_messages``
+            interface instead to save on round-trips to the persistence layer.
 
         This method may be deprecated in a future release.
 
@@ -134,9 +136,9 @@ class BaseChatMessageHistory(ABC):
     def add_ai_message(self, message: Union[AIMessage, str]) -> None:
         """Convenience method for adding an AI message string to the store.
 
-        Please note that this is a convenience method. Code should favor the bulk
-        add_messages interface instead to save on round-trips to the underlying
-        persistence layer.
+        .. note::
+            This is a convenience method. Code should favor the bulk ``add_messages``
+            interface instead to save on round-trips to the persistence layer.
 
         This method may be deprecated in a future release.
 
@@ -187,8 +189,6 @@ class BaseChatMessageHistory(ABC):
         Args:
             messages: A sequence of BaseMessage objects to store.
         """
-        from langchain_core.runnables.config import run_in_executor
-
         await run_in_executor(None, self.add_messages, messages)
 
     @abstractmethod
@@ -197,8 +197,6 @@ class BaseChatMessageHistory(ABC):
 
     async def aclear(self) -> None:
         """Async remove all messages from the store."""
-        from langchain_core.runnables.config import run_in_executor
-
         await run_in_executor(None, self.clear)
 
     def __str__(self) -> str:

langchain_core/document_loaders/base.py

@@ -15,6 +15,13 @@ if TYPE_CHECKING:
     from langchain_core.documents import Document
     from langchain_core.documents.base import Blob
 
+try:
+    from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+    _HAS_TEXT_SPLITTERS = True
+except ImportError:
+    _HAS_TEXT_SPLITTERS = False
+
 
 class BaseLoader(ABC):  # noqa: B024
     """Interface for Document Loader.
@@ -28,11 +35,19 @@ class BaseLoader(ABC):  # noqa: B024
     # Sub-classes should not implement this method directly. Instead, they
     # should implement the lazy load method.
     def load(self) -> list[Document]:
-        """Load data into Document objects."""
+        """Load data into Document objects.
+
+        Returns:
+            the documents.
+        """
         return list(self.lazy_load())
 
     async def aload(self) -> list[Document]:
-        """Load data into Document objects."""
+        """Load data into Document objects.
+
+        Returns:
+            the documents.
+        """
         return [document async for document in self.alazy_load()]
 
     def load_and_split(
@@ -44,21 +59,23 @@ class BaseLoader(ABC):  # noqa: B024
 
         Args:
             text_splitter: TextSplitter instance to use for splitting documents.
-              Defaults to RecursiveCharacterTextSplitter.
+                Defaults to RecursiveCharacterTextSplitter.
+
+        Raises:
+            ImportError: If langchain-text-splitters is not installed
+                and no text_splitter is provided.
 
         Returns:
             List of Documents.
         """
         if text_splitter is None:
-            try:
-                from langchain_text_splitters import RecursiveCharacterTextSplitter
-            except ImportError as e:
+            if not _HAS_TEXT_SPLITTERS:
                 msg = (
                     "Unable to import from langchain_text_splitters. Please specify "
                     "text_splitter or install langchain_text_splitters with "
                     "`pip install -U langchain-text-splitters`."
                 )
-                raise ImportError(msg) from e
+                raise ImportError(msg)
 
             text_splitter_: TextSplitter = RecursiveCharacterTextSplitter()
         else:
@@ -69,14 +86,22 @@ class BaseLoader(ABC):  # noqa: B024
     # Attention: This method will be upgraded into an abstractmethod once it's
     #            implemented in all the existing subclasses.
     def lazy_load(self) -> Iterator[Document]:
-        """A lazy loader for Documents."""
+        """A lazy loader for Documents.
+
+        Yields:
+            the documents.
+        """
         if type(self).load != BaseLoader.load:
             return iter(self.load())
         msg = f"{self.__class__.__name__} does not implement lazy_load()"
         raise NotImplementedError(msg)
 
     async def alazy_load(self) -> AsyncIterator[Document]:
-        """A lazy loader for Documents."""
+        """A lazy loader for Documents.
+
+        Yields:
+            the documents.
+        """
         iterator = await run_in_executor(None, self.lazy_load)
         done = object()
         while True:

langchain_core/document_loaders/langsmith.py

@@ -84,6 +84,9 @@ class LangSmithLoader(BaseLoader):
             client: LangSmith Client. If not provided will be initialized from below args.
             client_kwargs: Keyword args to pass to LangSmith client init. Should only be
                 specified if ``client`` isn't.
+
+        Raises:
+            ValueError: If both ``client`` and ``client_kwargs`` are provided.
         """  # noqa: E501
         if client and client_kwargs:
             raise ValueError

langchain_core/documents/base.py

@@ -82,7 +82,7 @@ class Blob(BaseMedia):
             blob = Blob.from_data(
                 data="Hello, world!",
                 mime_type="text/plain",
-                metadata={"source": "https://example.com"}
+                metadata={"source": "https://example.com"},
             )
 
     Example: Load the blob from a file
@@ -145,7 +145,14 @@ class Blob(BaseMedia):
         return values
 
     def as_string(self) -> str:
-        """Read data as a string."""
+        """Read data as a string.
+
+        Raises:
+            ValueError: If the blob cannot be represented as a string.
+
+        Returns:
+            The data as a string.
+        """
         if self.data is None and self.path:
             return Path(self.path).read_text(encoding=self.encoding)
         if isinstance(self.data, bytes):
@@ -156,7 +163,14 @@ class Blob(BaseMedia):
         raise ValueError(msg)
 
     def as_bytes(self) -> bytes:
-        """Read data as bytes."""
+        """Read data as bytes.
+
+        Raises:
+            ValueError: If the blob cannot be represented as bytes.
+
+        Returns:
+            The data as bytes.
+        """
         if isinstance(self.data, bytes):
             return self.data
         if isinstance(self.data, str):
@@ -168,7 +182,14 @@ class Blob(BaseMedia):
 
     @contextlib.contextmanager
     def as_bytes_io(self) -> Generator[Union[BytesIO, BufferedReader], None, None]:
-        """Read data as a byte stream."""
+        """Read data as a byte stream.
+
+        Raises:
+            NotImplementedError: If the blob cannot be represented as a byte stream.
+
+        Yields:
+            The data as a byte stream.
+        """
         if isinstance(self.data, bytes):
             yield BytesIO(self.data)
         elif self.data is None and self.path:
@@ -246,7 +267,7 @@ class Blob(BaseMedia):
         )
 
     def __repr__(self) -> str:
-        """Define the blob representation."""
+        """Return the blob representation."""
         str_repr = f"Blob {id(self)}"
         if self.source:
             str_repr += f" {self.source}"
@@ -263,8 +284,7 @@ class Document(BaseMedia):
             from langchain_core.documents import Document
 
             document = Document(
-                page_content="Hello, world!",
-                metadata={"source": "https://example.com"}
+                page_content="Hello, world!", metadata={"source": "https://example.com"}
             )
 
     """
@@ -277,23 +297,28 @@ class Document(BaseMedia):
         """Pass page_content in as positional or named arg."""
         # my-py is complaining that page_content is not defined on the base class.
         # Here, we're relying on pydantic base class to handle the validation.
-        super().__init__(page_content=page_content, **kwargs)  # type: ignore[call-arg]
+        super().__init__(page_content=page_content, **kwargs)
 
     @classmethod
     def is_lc_serializable(cls) -> bool:
-        """Return whether this class is serializable."""
+        """Return True as this class is serializable."""
         return True
 
     @classmethod
     def get_lc_namespace(cls) -> list[str]:
         """Get the namespace of the langchain object.
 
-        Default namespace is ["langchain", "schema", "document"].
+        Returns:
+            ["langchain", "schema", "document"]
         """
         return ["langchain", "schema", "document"]
 
     def __str__(self) -> str:
-        """Override __str__ to restrict it to page_content and metadata."""
+        """Override __str__ to restrict it to page_content and metadata.
+
+        Returns:
+            A string representation of the Document.
+        """
         # The format matches pydantic format for __str__.
         #
         # The purpose of this change is to make sure that user code that

langchain_core/documents/compressor.py

@@ -19,17 +19,18 @@ if TYPE_CHECKING:
 class BaseDocumentCompressor(BaseModel, ABC):
     """Base class for document compressors.
 
-    This abstraction is primarily used for
-    post-processing of retrieved documents.
+    This abstraction is primarily used for post-processing of retrieved documents.
 
     Documents 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.
+    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
+        interface.
 
-    **Note** users should favor using a RunnableLambda
-    instead of sub-classing from this interface.
     """
 
     @abstractmethod
@@ -48,6 +49,7 @@ class BaseDocumentCompressor(BaseModel, ABC):
 
         Returns:
             The compressed documents.
+
         """
 
     async def acompress_documents(
@@ -65,6 +67,7 @@ class BaseDocumentCompressor(BaseModel, ABC):
 
         Returns:
             The compressed documents.
+
         """
         return await run_in_executor(
             None, self.compress_documents, documents, query, callbacks

langchain_core/documents/transformers.py

@@ -38,7 +38,9 @@ class BaseDocumentTransformer(ABC):
                         self.embeddings, stateful_documents
                     )
                     included_idxs = _filter_similar_embeddings(
-                        embedded_documents, self.similarity_fn, self.similarity_threshold
+                        embedded_documents,
+                        self.similarity_fn,
+                        self.similarity_threshold,
                     )
                     return [stateful_documents[i] for i in sorted(included_idxs)]
 
@@ -47,7 +49,7 @@ class BaseDocumentTransformer(ABC):
                 ) -> Sequence[Document]:
                     raise NotImplementedError
 
-    """  # noqa: E501
+    """
 
     @abstractmethod
     def transform_documents(

langchain_core/embeddings/fake.py

@@ -1,6 +1,7 @@
 """Module contains a few fake embedding models for testing purposes."""
 
 # Please do not add additional fake embedding model implementations here.
+import contextlib
 import hashlib
 
 from pydantic import BaseModel
@@ -8,6 +9,9 @@ from typing_extensions import override
 
 from langchain_core.embeddings import Embeddings
 
+with contextlib.suppress(ImportError):
+    import numpy as np
+
 
 class FakeEmbeddings(Embeddings, BaseModel):
     """Fake embedding model for unit testing purposes.
@@ -20,6 +24,7 @@ class FakeEmbeddings(Embeddings, BaseModel):
         .. code-block:: python
 
             from langchain_core.embeddings import FakeEmbeddings
+
             embed = FakeEmbeddings(size=100)
 
     Embed single text:
@@ -53,8 +58,6 @@ class FakeEmbeddings(Embeddings, BaseModel):
     """The size of the embedding vector."""
 
     def _get_embedding(self) -> list[float]:
-        import numpy as np
-
         return list(np.random.default_rng().normal(size=self.size))
 
     @override
@@ -78,6 +81,7 @@ class DeterministicFakeEmbedding(Embeddings, BaseModel):
         .. code-block:: python
 
             from langchain_core.embeddings import DeterministicFakeEmbedding
+
             embed = DeterministicFakeEmbedding(size=100)
 
     Embed single text:
@@ -111,13 +115,12 @@ class DeterministicFakeEmbedding(Embeddings, BaseModel):
     """The size of the embedding vector."""
 
     def _get_embedding(self, seed: int) -> list[float]:
-        import numpy as np
-
         # set the seed for the random generator
         rng = np.random.default_rng(seed)
         return list(rng.normal(size=self.size))
 
-    def _get_seed(self, text: str) -> int:
+    @staticmethod
+    def _get_seed(text: str) -> int:
         """Get a seed for the random generator, using the hash of the text."""
         return int(hashlib.sha256(text.encode("utf-8")).hexdigest(), 16) % 10**8
 

langchain_core/env.py

@@ -3,6 +3,8 @@
 import platform
 from functools import lru_cache
 
+from langchain_core import __version__
+
 
 @lru_cache(maxsize=1)
 def get_runtime_environment() -> dict:
@@ -11,9 +13,6 @@ def get_runtime_environment() -> dict:
     Returns:
         A dictionary with information about the runtime environment.
     """
-    # Lazy import to avoid circular imports
-    from langchain_core import __version__
-
     return {
         "library_version": __version__,
         "library": "langchain-core",

langchain_core/example_selectors/base.py

@@ -16,6 +16,9 @@ class BaseExampleSelector(ABC):
         Args:
             example: A dictionary with keys as input variables
                 and values as their values.
+
+        Returns:
+            Any return value.
         """
 
     async def aadd_example(self, example: dict[str, str]) -> Any:
@@ -24,6 +27,9 @@ class BaseExampleSelector(ABC):
         Args:
             example: A dictionary with keys as input variables
                 and values as their values.
+
+        Returns:
+            Any return value.
         """
         return await run_in_executor(None, self.add_example, example)
 
@@ -34,6 +40,9 @@ class BaseExampleSelector(ABC):
         Args:
             input_variables: A dictionary with keys as input variables
                 and values as their values.
+
+        Returns:
+            A list of examples.
         """
 
     async def aselect_examples(self, input_variables: dict[str, str]) -> list[dict]:
@@ -42,5 +51,8 @@ class BaseExampleSelector(ABC):
         Args:
             input_variables: A dictionary with keys as input variables
                 and values as their values.
+
+        Returns:
+            A list of examples.
         """
         return await run_in_executor(None, self.select_examples, input_variables)

langchain_core/exceptions.py

@@ -42,6 +42,10 @@ class OutputParserException(ValueError, LangChainException):  # noqa: N818
                 previous output was improperly structured, in the hopes that it will
                 update the output to the correct format.
                 Defaults to False.
+
+        Raises:
+            ValueError: If ``send_to_llm`` is True but either observation or
+                ``llm_output`` are not provided.
         """
         if isinstance(error, str):
             error = create_message(
@@ -77,6 +81,9 @@ def create_message(*, message: str, error_code: ErrorCode) -> str:
     Args:
         message: The message to display.
         error_code: The error code to display.
+
+    Returns:
+        The full message with the troubleshooting link.
     """
     return (
         f"{message}\n"

langchain_core/globals.py

@@ -6,6 +6,13 @@ from typing import TYPE_CHECKING, Optional
 if TYPE_CHECKING:
     from langchain_core.caches import BaseCache
 
+try:
+    import langchain  # type: ignore[import-not-found]
+
+    _HAS_LANGCHAIN = True
+except ImportError:
+    _HAS_LANGCHAIN = False
+
 
 # DO NOT USE THESE VALUES DIRECTLY!
 # Use them only via `get_<X>()` and `set_<X>()` below,
@@ -22,9 +29,7 @@ def set_verbose(value: bool) -> None:  # noqa: FBT001
     Args:
         value: The new value for the `verbose` global setting.
     """
-    try:
-        import langchain  # type: ignore[import-not-found]
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -43,8 +48,6 @@ def set_verbose(value: bool) -> None:  # noqa: FBT001
             # Remove it once `langchain.verbose` is no longer supported, and once all
             # users have migrated to using `set_verbose()` here.
             langchain.verbose = value
-    except ImportError:
-        pass
 
     global _verbose  # noqa: PLW0603
     _verbose = value
@@ -56,9 +59,7 @@ def get_verbose() -> bool:
     Returns:
         The value of the `verbose` global setting.
     """
-    try:
-        import langchain
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -83,7 +84,7 @@ def get_verbose() -> bool:
             # deprecation warnings directing them to use `set_verbose()` when they
             # import `langchain.verbose`.
             old_verbose = langchain.verbose
-    except ImportError:
+    else:
         old_verbose = False
 
     return _verbose or old_verbose
@@ -95,9 +96,7 @@ def set_debug(value: bool) -> None:  # noqa: FBT001
     Args:
         value: The new value for the `debug` global setting.
     """
-    try:
-        import langchain
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -114,8 +113,6 @@ def set_debug(value: bool) -> None:  # noqa: FBT001
             # Remove it once `langchain.debug` is no longer supported, and once all
             # users have migrated to using `set_debug()` here.
             langchain.debug = value
-    except ImportError:
-        pass
 
     global _debug  # noqa: PLW0603
     _debug = value
@@ -127,9 +124,7 @@ def get_debug() -> bool:
     Returns:
         The value of the `debug` global setting.
     """
-    try:
-        import langchain
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -151,7 +146,7 @@ def get_debug() -> bool:
             # to using `set_debug()` yet. Those users are getting deprecation warnings
             # directing them to use `set_debug()` when they import `langchain.debug`.
             old_debug = langchain.debug
-    except ImportError:
+    else:
         old_debug = False
 
     return _debug or old_debug
@@ -163,9 +158,7 @@ def set_llm_cache(value: Optional["BaseCache"]) -> None:
     Args:
         value: The new LLM cache to use. If `None`, the LLM cache is disabled.
     """
-    try:
-        import langchain
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -184,22 +177,18 @@ def set_llm_cache(value: Optional["BaseCache"]) -> None:
             # Remove it once `langchain.llm_cache` is no longer supported, and
             # once all users have migrated to using `set_llm_cache()` here.
             langchain.llm_cache = value
-    except ImportError:
-        pass
 
     global _llm_cache  # noqa: PLW0603
     _llm_cache = value
 
 
-def get_llm_cache() -> "BaseCache":
+def get_llm_cache() -> Optional["BaseCache"]:
     """Get the value of the `llm_cache` global setting.
 
     Returns:
         The value of the `llm_cache` global setting.
     """
-    try:
-        import langchain
-
+    if _HAS_LANGCHAIN:
         # We're about to run some deprecated code, don't report warnings from it.
         # The user called the correct (non-deprecated) code path and shouldn't get
         # warnings.
@@ -225,7 +214,7 @@ def get_llm_cache() -> "BaseCache":
             # Those users are getting deprecation warnings directing them
             # to use `set_llm_cache()` when they import `langchain.llm_cache`.
             old_llm_cache = langchain.llm_cache
-    except ImportError:
+    else:
         old_llm_cache = None
 
     return _llm_cache or old_llm_cache