langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/documents/transformers.py

@@ -20,34 +20,35 @@ class BaseDocumentTransformer(ABC):
     sequence of transformed Documents.
 
     Example:
-        .. code-block:: python
-
-            class EmbeddingsRedundantFilter(BaseDocumentTransformer, BaseModel):
-                embeddings: Embeddings
-                similarity_fn: Callable = cosine_similarity
-                similarity_threshold: float = 0.95
-
-                class Config:
-                    arbitrary_types_allowed = True
-
-                def transform_documents(
-                    self, documents: Sequence[Document], **kwargs: Any
-                ) -> Sequence[Document]:
-                    stateful_documents = get_stateful_documents(documents)
-                    embedded_documents = _get_embeddings_from_stateful_docs(
-                        self.embeddings, stateful_documents
-                    )
-                    included_idxs = _filter_similar_embeddings(
-                        embedded_documents, self.similarity_fn, self.similarity_threshold
-                    )
-                    return [stateful_documents[i] for i in sorted(included_idxs)]
-
-                async def atransform_documents(
-                    self, documents: Sequence[Document], **kwargs: Any
-                ) -> Sequence[Document]:
-                    raise NotImplementedError
-
-    """  # noqa: E501
+        ```python
+        class EmbeddingsRedundantFilter(BaseDocumentTransformer, BaseModel):
+            embeddings: Embeddings
+            similarity_fn: Callable = cosine_similarity
+            similarity_threshold: float = 0.95
+
+            class Config:
+                arbitrary_types_allowed = True
+
+            def transform_documents(
+                self, documents: Sequence[Document], **kwargs: Any
+            ) -> Sequence[Document]:
+                stateful_documents = get_stateful_documents(documents)
+                embedded_documents = _get_embeddings_from_stateful_docs(
+                    self.embeddings, stateful_documents
+                )
+                included_idxs = _filter_similar_embeddings(
+                    embedded_documents,
+                    self.similarity_fn,
+                    self.similarity_threshold,
+                )
+                return [stateful_documents[i] for i in sorted(included_idxs)]
+
+            async def atransform_documents(
+                self, documents: Sequence[Document], **kwargs: Any
+            ) -> Sequence[Document]:
+                raise NotImplementedError
+        ```
+    """
 
     @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,53 +9,53 @@ 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.
 
     This embedding model creates embeddings by sampling from a normal distribution.
 
-    Do not use this outside of testing, as it is not a real embedding model.
+    !!! warning
+        Do not use this outside of testing, as it is not a real embedding model.
 
     Instantiate:
-        .. code-block:: python
+        ```python
+        from langchain_core.embeddings import FakeEmbeddings
 
-            from langchain_core.embeddings import FakeEmbeddings
-            embed = FakeEmbeddings(size=100)
+        embed = FakeEmbeddings(size=100)
+        ```
 
     Embed single text:
-        .. code-block:: python
-
-            input_text = "The meaning of life is 42"
-            vector = embed.embed_query(input_text)
-            print(vector[:3])
-
-        .. code-block:: python
-
-            [-0.700234640213188, -0.581266257710429, -1.1328482266445354]
+        ```python
+        input_text = "The meaning of life is 42"
+        vector = embed.embed_query(input_text)
+        print(vector[:3])
+        ```
+        ```python
+        [-0.700234640213188, -0.581266257710429, -1.1328482266445354]
+        ```
 
     Embed multiple texts:
-        .. code-block:: python
-
-            input_texts = ["Document 1...", "Document 2..."]
-            vectors = embed.embed_documents(input_texts)
-            print(len(vectors))
-            # The first 3 coordinates for the first vector
-            print(vectors[0][:3])
-
-        .. code-block:: python
-
-            2
-            [-0.5670477847544458, -0.31403828652395727, -0.5840547508955257]
-
+        ```python
+        input_texts = ["Document 1...", "Document 2..."]
+        vectors = embed.embed_documents(input_texts)
+        print(len(vectors))
+        # The first 3 coordinates for the first vector
+        print(vectors[0][:3])
+        ```
+        ```python
+        2
+        [-0.5670477847544458, -0.31403828652395727, -0.5840547508955257]
+        ```
     """
 
     size: int
     """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
@@ -72,52 +73,50 @@ 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.
 
-    Do not use this outside of testing, as it is not a real embedding model.
+    !!! warning
+        Do not use this outside of testing, as it is not a real embedding model.
 
     Instantiate:
-        .. code-block:: python
+        ```python
+        from langchain_core.embeddings import DeterministicFakeEmbedding
 
-            from langchain_core.embeddings import DeterministicFakeEmbedding
-            embed = DeterministicFakeEmbedding(size=100)
+        embed = DeterministicFakeEmbedding(size=100)
+        ```
 
     Embed single text:
-        .. code-block:: python
-
-            input_text = "The meaning of life is 42"
-            vector = embed.embed_query(input_text)
-            print(vector[:3])
-
-        .. code-block:: python
-
-            [-0.700234640213188, -0.581266257710429, -1.1328482266445354]
+        ```python
+        input_text = "The meaning of life is 42"
+        vector = embed.embed_query(input_text)
+        print(vector[:3])
+        ```
+        ```python
+        [-0.700234640213188, -0.581266257710429, -1.1328482266445354]
+        ```
 
     Embed multiple texts:
-        .. code-block:: python
-
-            input_texts = ["Document 1...", "Document 2..."]
-            vectors = embed.embed_documents(input_texts)
-            print(len(vectors))
-            # The first 3 coordinates for the first vector
-            print(vectors[0][:3])
-
-        .. code-block:: python
-
-            2
-            [-0.5670477847544458, -0.31403828652395727, -0.5840547508955257]
-
+        ```python
+        input_texts = ["Document 1...", "Document 2..."]
+        vectors = embed.embed_documents(input_texts)
+        print(len(vectors))
+        # The first 3 coordinates for the first vector
+        print(vectors[0][:3])
+        ```
+        ```python
+        2
+        [-0.5670477847544458, -0.31403828652395727, -0.5840547508955257]
+        ```
     """
 
     size: int
     """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/example_selectors/length_based.py

@@ -1,7 +1,7 @@
 """Select examples based on length."""
 
 import re
-from typing import Callable
+from collections.abc import Callable
 
 from pydantic import BaseModel, Field, model_validator
 from typing_extensions import Self

langchain_core/example_selectors/semantic_similarity.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 from pydantic import BaseModel, ConfigDict
 
@@ -35,12 +35,12 @@ class _VectorStoreExampleSelector(BaseExampleSelector, BaseModel, ABC):
     """VectorStore that contains information about examples."""
     k: int = 4
     """Number of examples to select."""
-    example_keys: Optional[list[str]] = None
+    example_keys: list[str] | None = None
     """Optional keys to filter examples to."""
-    input_keys: Optional[list[str]] = None
+    input_keys: list[str] | None = None
     """Optional keys to filter input to. If provided, the search is based on
     the input variables instead of all variables."""
-    vectorstore_kwargs: Optional[dict[str, Any]] = None
+    vectorstore_kwargs: dict[str, Any] | None = None
     """Extra arguments passed to similarity_search function of the vectorstore."""
 
     model_config = ConfigDict(
@@ -49,9 +49,7 @@ class _VectorStoreExampleSelector(BaseExampleSelector, BaseModel, ABC):
     )
 
     @staticmethod
-    def _example_to_text(
-        example: dict[str, str], input_keys: Optional[list[str]]
-    ) -> str:
+    def _example_to_text(example: dict[str, str], input_keys: list[str] | None) -> str:
         if input_keys:
             return " ".join(sorted_values({key: example[key] for key in input_keys}))
         return " ".join(sorted_values(example))
@@ -142,10 +140,10 @@ class SemanticSimilarityExampleSelector(_VectorStoreExampleSelector):
         embeddings: Embeddings,
         vectorstore_cls: type[VectorStore],
         k: int = 4,
-        input_keys: Optional[list[str]] = None,
+        input_keys: list[str] | None = None,
         *,
-        example_keys: Optional[list[str]] = None,
-        vectorstore_kwargs: Optional[dict] = None,
+        example_keys: list[str] | None = None,
+        vectorstore_kwargs: dict | None = None,
         **vectorstore_cls_kwargs: Any,
     ) -> SemanticSimilarityExampleSelector:
         """Create k-shot example selector using example list and embeddings.
@@ -156,7 +154,7 @@ class SemanticSimilarityExampleSelector(_VectorStoreExampleSelector):
             examples: List of examples to use in the prompt.
             embeddings: An initialized embedding API interface, e.g. OpenAIEmbeddings().
             vectorstore_cls: A vector store DB interface class, e.g. FAISS.
-            k: Number of examples to select. Default is 4.
+            k: Number of examples to select.
             input_keys: If provided, the search is based on the input variables
                 instead of all variables.
             example_keys: If provided, keys to filter examples to.
@@ -186,10 +184,10 @@ class SemanticSimilarityExampleSelector(_VectorStoreExampleSelector):
         embeddings: Embeddings,
         vectorstore_cls: type[VectorStore],
         k: int = 4,
-        input_keys: Optional[list[str]] = None,
+        input_keys: list[str] | None = None,
         *,
-        example_keys: Optional[list[str]] = None,
-        vectorstore_kwargs: Optional[dict] = None,
+        example_keys: list[str] | None = None,
+        vectorstore_kwargs: dict | None = None,
         **vectorstore_cls_kwargs: Any,
     ) -> SemanticSimilarityExampleSelector:
         """Async create k-shot example selector using example list and embeddings.
@@ -200,7 +198,7 @@ class SemanticSimilarityExampleSelector(_VectorStoreExampleSelector):
             examples: List of examples to use in the prompt.
             embeddings: An initialized embedding API interface, e.g. OpenAIEmbeddings().
             vectorstore_cls: A vector store DB interface class, e.g. FAISS.
-            k: Number of examples to select. Default is 4.
+            k: Number of examples to select.
             input_keys: If provided, the search is based on the input variables
                 instead of all variables.
             example_keys: If provided, keys to filter examples to.
@@ -273,10 +271,10 @@ class MaxMarginalRelevanceExampleSelector(_VectorStoreExampleSelector):
         embeddings: Embeddings,
         vectorstore_cls: type[VectorStore],
         k: int = 4,
-        input_keys: Optional[list[str]] = None,
+        input_keys: list[str] | None = None,
         fetch_k: int = 20,
-        example_keys: Optional[list[str]] = None,
-        vectorstore_kwargs: Optional[dict] = None,
+        example_keys: list[str] | None = None,
+        vectorstore_kwargs: dict | None = None,
         **vectorstore_cls_kwargs: Any,
     ) -> MaxMarginalRelevanceExampleSelector:
         """Create k-shot example selector using example list and embeddings.
@@ -287,9 +285,8 @@ class MaxMarginalRelevanceExampleSelector(_VectorStoreExampleSelector):
             examples: List of examples to use in the prompt.
             embeddings: An initialized embedding API interface, e.g. OpenAIEmbeddings().
             vectorstore_cls: A vector store DB interface class, e.g. FAISS.
-            k: Number of examples to select. Default is 4.
+            k: Number of examples to select.
             fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
             input_keys: If provided, the search is based on the input variables
                 instead of all variables.
             example_keys: If provided, keys to filter examples to.
@@ -321,10 +318,10 @@ class MaxMarginalRelevanceExampleSelector(_VectorStoreExampleSelector):
         vectorstore_cls: type[VectorStore],
         *,
         k: int = 4,
-        input_keys: Optional[list[str]] = None,
+        input_keys: list[str] | None = None,
         fetch_k: int = 20,
-        example_keys: Optional[list[str]] = None,
-        vectorstore_kwargs: Optional[dict] = None,
+        example_keys: list[str] | None = None,
+        vectorstore_kwargs: dict | None = None,
         **vectorstore_cls_kwargs: Any,
     ) -> MaxMarginalRelevanceExampleSelector:
         """Create k-shot example selector using example list and embeddings.
@@ -335,9 +332,8 @@ class MaxMarginalRelevanceExampleSelector(_VectorStoreExampleSelector):
             examples: List of examples to use in the prompt.
             embeddings: An initialized embedding API interface, e.g. OpenAIEmbeddings().
             vectorstore_cls: A vector store DB interface class, e.g. FAISS.
-            k: Number of examples to select. Default is 4.
+            k: Number of examples to select.
             fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
             input_keys: If provided, the search is based on the input variables
                 instead of all variables.
             example_keys: If provided, keys to filter examples to.

langchain_core/exceptions.py

@@ -1,7 +1,7 @@
 """Custom **exceptions** for LangChain."""
 
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 
 class LangChainException(Exception):  # noqa: N818
@@ -16,7 +16,7 @@ class OutputParserException(ValueError, LangChainException):  # noqa: N818
     """Exception that output parsers should raise to signify a parsing error.
 
     This exists to differentiate parsing errors from other code or execution errors
-    that also may arise inside the output parser. OutputParserExceptions will be
+    that also may arise inside the output parser. `OutputParserException` will be
     available to catch and handle in ways to fix the parsing error, while other
     errors will be raised.
     """
@@ -24,24 +24,27 @@ class OutputParserException(ValueError, LangChainException):  # noqa: N818
     def __init__(
         self,
         error: Any,
-        observation: Optional[str] = None,
-        llm_output: Optional[str] = None,
+        observation: str | None = None,
+        llm_output: str | None = None,
         send_to_llm: bool = False,  # noqa: FBT001,FBT002
     ):
-        """Create an OutputParserException.
+        """Create an `OutputParserException`.
 
         Args:
             error: The error that's being re-raised or an error message.
             observation: String explanation of error which can be passed to a
-                model to try and remediate the issue. Defaults to None.
+                model to try and remediate the issue.
             llm_output: String model output which is error-ing.
-                Defaults to None.
+
             send_to_llm: Whether to send the observation and llm_output back to an Agent
-                after an OutputParserException has been raised.
+                after an `OutputParserException` has been raised.
                 This gives the underlying model driving the agent the context that the
                 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 +80,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"