langchain-core 1.0.0a5__py3-none-any.whl → 1.0.3__py3-none-any.whl

langchain_core/documents/compressor.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel
 
@@ -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
+    !!! note
+        Users should favor using a `RunnableLambda` instead of sub-classing from this
         interface.
 
     """
@@ -38,14 +38,14 @@ class BaseDocumentCompressor(BaseModel, ABC):
         self,
         documents: Sequence[Document],
         query: str,
-        callbacks: Optional[Callbacks] = None,
+        callbacks: Callbacks | None = None,
     ) -> Sequence[Document]:
         """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.
@@ -56,14 +56,14 @@ class BaseDocumentCompressor(BaseModel, ABC):
         self,
         documents: Sequence[Document],
         query: str,
-        callbacks: Optional[Callbacks] = None,
+        callbacks: Callbacks | None = None,
     ) -> Sequence[Document]:
         """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,39 +16,38 @@ 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:
-        .. 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
-
+        ```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
@@ -58,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(
@@ -70,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,40 +18,38 @@ class FakeEmbeddings(Embeddings, BaseModel):
 
     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.
+    !!! danger "Toy model"
+        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
@@ -75,40 +73,38 @@ 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.
+    !!! danger "Toy model"
+        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

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,13 +35,13 @@ 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
-    """Extra arguments passed to similarity_search function of the vectorstore."""
+    vectorstore_kwargs: dict[str, Any] | None = None
+    """Extra arguments passed to similarity_search function of the `VectorStore`."""
 
     model_config = ConfigDict(
         arbitrary_types_allowed=True,
@@ -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,12 +154,12 @@ 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.
             vectorstore_kwargs: Extra arguments passed to similarity_search function
-                of the vectorstore.
+                of the `VectorStore`.
             vectorstore_cls_kwargs: optional kwargs containing url for vector store
 
         Returns:
@@ -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,12 +198,12 @@ 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.
             vectorstore_kwargs: Extra arguments passed to similarity_search function
-                of the vectorstore.
+                of the `VectorStore`.
             vectorstore_cls_kwargs: optional kwargs containing url for vector store
 
         Returns:
@@ -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,14 +285,13 @@ 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.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
+            k: Number of examples to select.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
             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.
             vectorstore_kwargs: Extra arguments passed to similarity_search function
-                of the vectorstore.
+                of the `VectorStore`.
             vectorstore_cls_kwargs: optional kwargs containing url for vector store
 
         Returns:
@@ -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,14 +332,13 @@ 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.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
+            k: Number of examples to select.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
             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.
             vectorstore_kwargs: Extra arguments passed to similarity_search function
-                of the vectorstore.
+                of the `VectorStore`.
             vectorstore_cls_kwargs: optional kwargs containing url for vector store
 
         Returns:

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,36 +16,37 @@ 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
-    available to catch and handle in ways to fix the parsing error, while other
-    errors will be raised.
+    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.
     """
 
     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.
+            observation: String explanation of error which can be passed to a 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.
+            ValueError: If `send_to_llm` is `True` but either observation or
+                `llm_output` are not provided.
         """
         if isinstance(error, str):
             error = create_message(
@@ -67,11 +68,11 @@ class ErrorCode(Enum):
     """Error codes."""
 
     INVALID_PROMPT_INPUT = "INVALID_PROMPT_INPUT"
-    INVALID_TOOL_RESULTS = "INVALID_TOOL_RESULTS"
+    INVALID_TOOL_RESULTS = "INVALID_TOOL_RESULTS"  # Used in JS; not Py (yet)
     MESSAGE_COERCION_FAILURE = "MESSAGE_COERCION_FAILURE"
-    MODEL_AUTHENTICATION = "MODEL_AUTHENTICATION"
-    MODEL_NOT_FOUND = "MODEL_NOT_FOUND"
-    MODEL_RATE_LIMIT = "MODEL_RATE_LIMIT"
+    MODEL_AUTHENTICATION = "MODEL_AUTHENTICATION"  # Used in JS; not Py (yet)
+    MODEL_NOT_FOUND = "MODEL_NOT_FOUND"  # Used in JS; not Py (yet)
+    MODEL_RATE_LIMIT = "MODEL_RATE_LIMIT"  # Used in JS; not Py (yet)
     OUTPUT_PARSING_FAILURE = "OUTPUT_PARSING_FAILURE"
 
 
@@ -87,6 +88,6 @@ def create_message(*, message: str, error_code: ErrorCode) -> str:
     """
     return (
         f"{message}\n"
-        "For troubleshooting, visit: https://python.langchain.com/docs/"
-        f"troubleshooting/errors/{error_code.value} "
+        "For troubleshooting, visit: https://docs.langchain.com/oss/python/langchain"
+        f"/errors/{error_code.value} "
     )