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

langchain_core/vectorstores/base.py

@@ -3,21 +3,7 @@
 One of the most common ways to store and search over unstructured data is to
 embed it and store the resulting embedding vectors, and then query the store
 and retrieve the data that are 'most similar' to the embedded query.
-
-**Class hierarchy:**
-
-.. code-block::
-
-    VectorStore --> <name>  # Examples: Annoy, FAISS, Milvus
-
-    BaseRetriever --> VectorStoreRetriever --> <name>Retriever  # Example: VespaRetriever
-
-**Main helpers:**
-
-.. code-block::
-
-    Embeddings, Document
-"""  # noqa: E501
+"""
 
 from __future__ import annotations
 
@@ -25,13 +11,12 @@ import logging
 import math
 import warnings
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from itertools import cycle
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     ClassVar,
-    Optional,
     TypeVar,
 )
 
@@ -62,27 +47,27 @@ class VectorStore(ABC):
     def add_texts(
         self,
         texts: Iterable[str],
-        metadatas: Optional[list[dict]] = None,
+        metadatas: list[dict] | None = None,
         *,
-        ids: Optional[list[str]] = None,
+        ids: list[str] | None = None,
         **kwargs: Any,
     ) -> list[str]:
-        """Run more texts through the embeddings and add to the vectorstore.
+        """Run more texts through the embeddings and add to the `VectorStore`.
 
         Args:
-            texts: Iterable of strings to add to the vectorstore.
+            texts: Iterable of strings to add to the `VectorStore`.
             metadatas: Optional list of metadatas associated with the texts.
             ids: Optional list of IDs associated with the texts.
-            **kwargs: vectorstore specific parameters.
+            **kwargs: `VectorStore` specific parameters.
                 One of the kwargs should be `ids` which is a list of ids
                 associated with the texts.
 
         Returns:
-            List of ids from adding the texts into the vectorstore.
+            List of IDs from adding the texts into the `VectorStore`.
 
         Raises:
             ValueError: If the number of metadatas does not match the number of texts.
-            ValueError: If the number of ids does not match the number of texts.
+            ValueError: If the number of IDs does not match the number of texts.
         """
         if type(self).add_documents != VectorStore.add_documents:
             # This condition is triggered if the subclass has provided
@@ -98,10 +83,10 @@ class VectorStore(ABC):
                 )
                 raise ValueError(msg)
             metadatas_ = iter(metadatas) if metadatas else cycle([{}])
-            ids_: Iterator[Optional[str]] = iter(ids) if ids else cycle([None])
+            ids_: Iterator[str | None] = iter(ids) if ids else cycle([None])
             docs = [
                 Document(id=id_, page_content=text, metadata=metadata_)
-                for text, metadata_, id_ in zip(texts, metadatas_, ids_)
+                for text, metadata_, id_ in zip(texts, metadatas_, ids_, strict=False)
             ]
             if ids is not None:
                 # For backward compatibility
@@ -112,7 +97,7 @@ class VectorStore(ABC):
         raise NotImplementedError(msg)
 
     @property
-    def embeddings(self) -> Optional[Embeddings]:
+    def embeddings(self) -> Embeddings | None:
         """Access the query embedding object if available."""
         logger.debug(
             "The embeddings property has not been implemented for %s",
@@ -120,16 +105,16 @@ class VectorStore(ABC):
         )
         return None
 
-    def delete(self, ids: Optional[list[str]] = None, **kwargs: Any) -> Optional[bool]:
+    def delete(self, ids: list[str] | None = None, **kwargs: Any) -> bool | None:
         """Delete by vector ID or other criteria.
 
         Args:
-            ids: List of ids to delete. If None, delete all. Default is None.
+            ids: List of IDs to delete. If `None`, delete all.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns:
-            Optional[bool]: True if deletion is successful,
-            False otherwise, None if not implemented.
+            `True` if deletion is successful, `False` otherwise, `None` if not
+                implemented.
         """
         msg = "delete method must be implemented by subclass."
         raise NotImplementedError(msg)
@@ -151,12 +136,10 @@ class VectorStore(ABC):
         some IDs.
 
         Args:
-            ids: List of ids to retrieve.
+            ids: List of IDs to retrieve.
 
         Returns:
-            List of Documents.
-
-        .. versionadded:: 0.2.11
+            List of `Document` objects.
         """
         msg = f"{self.__class__.__name__} does not yet support get_by_ids."
         raise NotImplementedError(msg)
@@ -179,53 +162,48 @@ class VectorStore(ABC):
         some IDs.
 
         Args:
-            ids: List of ids to retrieve.
+            ids: List of IDs to retrieve.
 
         Returns:
-            List of Documents.
-
-        .. versionadded:: 0.2.11
+            List of `Document` objects.
         """
         return await run_in_executor(None, self.get_by_ids, ids)
 
-    async def adelete(
-        self, ids: Optional[list[str]] = None, **kwargs: Any
-    ) -> Optional[bool]:
+    async def adelete(self, ids: list[str] | None = None, **kwargs: Any) -> bool | None:
         """Async delete by vector ID or other criteria.
 
         Args:
-            ids: List of ids to delete. If None, delete all. Default is None.
+            ids: List of IDs to delete. If `None`, delete all.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns:
-            Optional[bool]: True if deletion is successful,
-            False otherwise, None if not implemented.
+            `True` if deletion is successful, `False` otherwise, `None` if not
+                implemented.
         """
         return await run_in_executor(None, self.delete, ids, **kwargs)
 
     async def aadd_texts(
         self,
         texts: Iterable[str],
-        metadatas: Optional[list[dict]] = None,
+        metadatas: list[dict] | None = None,
         *,
-        ids: Optional[list[str]] = None,
+        ids: list[str] | None = None,
         **kwargs: Any,
     ) -> list[str]:
-        """Async run more texts through the embeddings and add to the vectorstore.
+        """Async run more texts through the embeddings and add to the `VectorStore`.
 
         Args:
-            texts: Iterable of strings to add to the vectorstore.
+            texts: Iterable of strings to add to the `VectorStore`.
             metadatas: Optional list of metadatas associated with the texts.
-                Default is None.
             ids: Optional list
-            **kwargs: vectorstore specific parameters.
+            **kwargs: `VectorStore` specific parameters.
 
         Returns:
-            List of ids from adding the texts into the vectorstore.
+            List of IDs from adding the texts into the `VectorStore`.
 
         Raises:
             ValueError: If the number of metadatas does not match the number of texts.
-            ValueError: If the number of ids does not match the number of texts.
+            ValueError: If the number of IDs does not match the number of texts.
         """
         if ids is not None:
             # For backward compatibility
@@ -244,23 +222,24 @@ class VectorStore(ABC):
                 )
                 raise ValueError(msg)
             metadatas_ = iter(metadatas) if metadatas else cycle([{}])
-            ids_: Iterator[Optional[str]] = iter(ids) if ids else cycle([None])
+            ids_: Iterator[str | None] = iter(ids) if ids else cycle([None])
 
             docs = [
                 Document(id=id_, page_content=text, metadata=metadata_)
-                for text, metadata_, id_ in zip(texts, metadatas_, ids_)
+                for text, metadata_, id_ in zip(texts, metadatas_, ids_, strict=False)
             ]
             return await self.aadd_documents(docs, **kwargs)
         return await run_in_executor(None, self.add_texts, texts, metadatas, **kwargs)
 
     def add_documents(self, documents: list[Document], **kwargs: Any) -> list[str]:
-        """Add or update documents in the vectorstore.
+        """Add or update documents in the `VectorStore`.
 
         Args:
-            documents: Documents to add to the vectorstore.
-            kwargs: Additional keyword arguments.
-                if kwargs contains ids and documents contain ids,
-                the ids in the kwargs will receive precedence.
+            documents: Documents to add to the `VectorStore`.
+            **kwargs: Additional keyword arguments.
+
+                If kwargs contains IDs and documents contain ids, the IDs in the kwargs
+                will receive precedence.
 
         Returns:
             List of IDs of the added texts.
@@ -286,11 +265,11 @@ class VectorStore(ABC):
     async def aadd_documents(
         self, documents: list[Document], **kwargs: Any
     ) -> list[str]:
-        """Async run more documents through the embeddings and add to the vectorstore.
+        """Async run more documents through the embeddings and add to the `VectorStore`.
 
         Args:
-            documents: Documents to add to the vectorstore.
-            kwargs: Additional keyword arguments.
+            documents: Documents to add to the `VectorStore`.
+            **kwargs: Additional keyword arguments.
 
         Returns:
             List of IDs of the added texts.
@@ -315,17 +294,17 @@ class VectorStore(ABC):
         """Return docs most similar to query using a specified search type.
 
         Args:
-            query: Input text
-            search_type: Type of search to perform. Can be "similarity",
-                "mmr", or "similarity_score_threshold".
+            query: Input text.
+            search_type: Type of search to perform. Can be `'similarity'`, `'mmr'`, or
+                `'similarity_score_threshold'`.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents most similar to the query.
+            List of `Document` objects most similar to the query.
 
         Raises:
-            ValueError: If search_type is not one of "similarity",
-                "mmr", or "similarity_score_threshold".
+            ValueError: If `search_type` is not one of `'similarity'`,
+                `'mmr'`, or `'similarity_score_threshold'`.
         """
         if search_type == "similarity":
             return self.similarity_search(query, **kwargs)
@@ -350,16 +329,16 @@ 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:
-            List of Documents most similar to the query.
+            List of `Document` objects most similar to the query.
 
         Raises:
-            ValueError: If search_type is not one of "similarity",
-                "mmr", or "similarity_score_threshold".
+            ValueError: If `search_type` is not one of `'similarity'`,
+                `'mmr'`, or `'similarity_score_threshold'`.
         """
         if search_type == "similarity":
             return await self.asimilarity_search(query, **kwargs)
@@ -384,11 +363,11 @@ class VectorStore(ABC):
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
+            k: Number of `Document` objects to return.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents most similar to the query.
+            List of `Document` objects most similar to the query.
         """
 
     @staticmethod
@@ -443,7 +422,7 @@ class VectorStore(ABC):
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Tuples of (doc, similarity_score).
+            List of tuples of `(doc, similarity_score)`.
         """
         raise NotImplementedError
 
@@ -457,7 +436,7 @@ class VectorStore(ABC):
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Tuples of (doc, similarity_score).
+            List of tuples of `(doc, similarity_score)`.
         """
         # This is a temporary workaround to make the similarity search
         # asynchronous. The proper solution is to make the similarity search
@@ -475,19 +454,19 @@ class VectorStore(ABC):
         """Default similarity search with relevance scores.
 
         Modify if necessary in subclass.
-        Return docs and relevance scores in the range [0, 1].
+        Return docs and relevance scores in the range `[0, 1]`.
 
-        0 is dissimilar, 1 is most similar.
+        `0` is dissimilar, `1` is most similar.
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
-            **kwargs: kwargs to be passed to similarity search. Should include:
-                score_threshold: Optional, a floating point value between 0 to 1 to
-                    filter the resulting set of retrieved docs
+            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
 
         Returns:
-            List of Tuples of (doc, similarity_score)
+            List of tuples of `(doc, similarity_score)`
         """
         relevance_score_fn = self._select_relevance_score_fn()
         docs_and_scores = self.similarity_search_with_score(query, k, **kwargs)
@@ -502,19 +481,19 @@ class VectorStore(ABC):
         """Default similarity search with relevance scores.
 
         Modify if necessary in subclass.
-        Return docs and relevance scores in the range [0, 1].
+        Return docs and relevance scores in the range `[0, 1]`.
 
-        0 is dissimilar, 1 is most similar.
+        `0` is dissimilar, `1` is most similar.
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
-            **kwargs: kwargs to be passed to similarity search. Should include:
-                score_threshold: Optional, a floating point value between 0 to 1 to
-                    filter the resulting set of retrieved docs
+            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
 
         Returns:
-            List of Tuples of (doc, similarity_score)
+            List of tuples of `(doc, similarity_score)`
         """
         relevance_score_fn = self._select_relevance_score_fn()
         docs_and_scores = await self.asimilarity_search_with_score(query, k, **kwargs)
@@ -526,19 +505,19 @@ class VectorStore(ABC):
         k: int = 4,
         **kwargs: Any,
     ) -> list[tuple[Document, float]]:
-        """Return docs and relevance scores in the range [0, 1].
+        """Return docs and relevance scores in the range `[0, 1]`.
 
-        0 is dissimilar, 1 is most similar.
+        `0` is dissimilar, `1` is most similar.
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
-            **kwargs: kwargs to be passed to similarity search. Should include:
-                score_threshold: Optional, a floating point value between 0 to 1 to
-                    filter the resulting set of retrieved docs.
+            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
 
         Returns:
-            List of Tuples of (doc, similarity_score).
+            List of tuples of `(doc, similarity_score)`.
         """
         score_threshold = kwargs.pop("score_threshold", None)
 
@@ -575,19 +554,19 @@ class VectorStore(ABC):
         k: int = 4,
         **kwargs: Any,
     ) -> list[tuple[Document, float]]:
-        """Async return docs and relevance scores in the range [0, 1].
+        """Async return docs and relevance scores in the range `[0, 1]`.
 
-        0 is dissimilar, 1 is most similar.
+        `0` is dissimilar, `1` is most similar.
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
-            **kwargs: kwargs to be passed to similarity search. Should include:
-                score_threshold: Optional, a floating point value between 0 to 1 to
-                    filter the resulting set of retrieved docs
+            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
 
         Returns:
-            List of Tuples of (doc, similarity_score)
+            List of tuples of `(doc, similarity_score)`
         """
         score_threshold = kwargs.pop("score_threshold", None)
 
@@ -625,11 +604,11 @@ class VectorStore(ABC):
 
         Args:
             query: Input text.
-            k: Number of Documents to return. Defaults to 4.
+            k: Number of `Document` objects to return.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents most similar to the query.
+            List of `Document` objects most similar to the query.
         """
         # This is a temporary workaround to make the similarity search
         # asynchronous. The proper solution is to make the similarity search
@@ -643,11 +622,11 @@ class VectorStore(ABC):
 
         Args:
             embedding: Embedding to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
+            k: Number of `Document` objects to return.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents most similar to the query vector.
+            List of `Document` objects most similar to the query vector.
         """
         raise NotImplementedError
 
@@ -658,11 +637,11 @@ class VectorStore(ABC):
 
         Args:
             embedding: Embedding to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
+            k: Number of `Document` objects to return.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents most similar to the query vector.
+            List of `Document` objects most similar to the query vector.
         """
         # This is a temporary workaround to make the similarity search
         # asynchronous. The proper solution is to make the similarity search
@@ -686,17 +665,15 @@ class VectorStore(ABC):
 
         Args:
             query: Text to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
-            lambda_mult: Number between 0 and 1 that determines the degree
-                of diversity among the results with 0 corresponding
-                to maximum diversity and 1 to minimum diversity.
-                Defaults to 0.5.
+            k: Number of `Document` objects to return.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
+            lambda_mult: Number between `0` and `1` that determines the degree
+                of diversity among the results with `0` corresponding
+                to maximum diversity and `1` to minimum diversity.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents selected by maximal marginal relevance.
+            List of `Document` objects selected by maximal marginal relevance.
         """
         raise NotImplementedError
 
@@ -715,17 +692,15 @@ class VectorStore(ABC):
 
         Args:
             query: Text to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
-            lambda_mult: Number between 0 and 1 that determines the degree
-                of diversity among the results with 0 corresponding
-                to maximum diversity and 1 to minimum diversity.
-                Defaults to 0.5.
+            k: Number of `Document` objects to return.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
+            lambda_mult: Number between `0` and `1` that determines the degree
+                of diversity among the results with `0` corresponding
+                to maximum diversity and `1` to minimum diversity.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents selected by maximal marginal relevance.
+            List of `Document` objects selected by maximal marginal relevance.
         """
         # This is a temporary workaround to make the similarity search
         # asynchronous. The proper solution is to make the similarity search
@@ -755,17 +730,15 @@ class VectorStore(ABC):
 
         Args:
             embedding: Embedding to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
-            lambda_mult: Number between 0 and 1 that determines the degree
-                of diversity among the results with 0 corresponding
-                to maximum diversity and 1 to minimum diversity.
-                Defaults to 0.5.
+            k: Number of `Document` objects to return.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
+            lambda_mult: Number between `0` and `1` that determines the degree
+                of diversity among the results with `0` corresponding
+                to maximum diversity and `1` to minimum diversity.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents selected by maximal marginal relevance.
+            List of `Document` objects selected by maximal marginal relevance.
         """
         raise NotImplementedError
 
@@ -784,17 +757,15 @@ class VectorStore(ABC):
 
         Args:
             embedding: Embedding to look up documents similar to.
-            k: Number of Documents to return. Defaults to 4.
-            fetch_k: Number of Documents to fetch to pass to MMR algorithm.
-                Default is 20.
-            lambda_mult: Number between 0 and 1 that determines the degree
-                of diversity among the results with 0 corresponding
-                to maximum diversity and 1 to minimum diversity.
-                Defaults to 0.5.
+            k: Number of `Document` objects to return.
+            fetch_k: Number of `Document` objects to fetch to pass to MMR algorithm.
+            lambda_mult: Number between `0` and `1` that determines the degree
+                of diversity among the results with `0` corresponding
+                to maximum diversity and `1` to minimum diversity.
             **kwargs: Arguments to pass to the search method.
 
         Returns:
-            List of Documents selected by maximal marginal relevance.
+            List of `Document` objects selected by maximal marginal relevance.
         """
         return await run_in_executor(
             None,
@@ -813,15 +784,15 @@ class VectorStore(ABC):
         embedding: Embeddings,
         **kwargs: Any,
     ) -> Self:
-        """Return VectorStore initialized from documents and embeddings.
+        """Return `VectorStore` initialized from documents and embeddings.
 
         Args:
-            documents: List of Documents to add to the vectorstore.
+            documents: List of `Document` objects to add to the `VectorStore`.
             embedding: Embedding function to use.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from documents and embeddings.
+            `VectorStore` initialized from documents and embeddings.
         """
         texts = [d.page_content for d in documents]
         metadatas = [d.metadata for d in documents]
@@ -843,15 +814,15 @@ class VectorStore(ABC):
         embedding: Embeddings,
         **kwargs: Any,
     ) -> Self:
-        """Async return VectorStore initialized from documents and embeddings.
+        """Async return `VectorStore` initialized from documents and embeddings.
 
         Args:
-            documents: List of Documents to add to the vectorstore.
+            documents: List of `Document` objects to add to the `VectorStore`.
             embedding: Embedding function to use.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from documents and embeddings.
+            `VectorStore` initialized from documents and embeddings.
         """
         texts = [d.page_content for d in documents]
         metadatas = [d.metadata for d in documents]
@@ -872,23 +843,22 @@ class VectorStore(ABC):
         cls: type[VST],
         texts: list[str],
         embedding: Embeddings,
-        metadatas: Optional[list[dict]] = None,
+        metadatas: list[dict] | None = None,
         *,
-        ids: Optional[list[str]] = None,
+        ids: list[str] | None = None,
         **kwargs: Any,
     ) -> VST:
-        """Return VectorStore initialized from texts and embeddings.
+        """Return `VectorStore` initialized from texts and embeddings.
 
         Args:
-            texts: Texts to add to the vectorstore.
+            texts: Texts to add to the `VectorStore`.
             embedding: Embedding function to use.
             metadatas: Optional list of metadatas associated with the texts.
-                Default is None.
             ids: Optional list of IDs associated with the texts.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from texts and embeddings.
+            `VectorStore` initialized from texts and embeddings.
         """
 
     @classmethod
@@ -896,23 +866,22 @@ class VectorStore(ABC):
         cls,
         texts: list[str],
         embedding: Embeddings,
-        metadatas: Optional[list[dict]] = None,
+        metadatas: list[dict] | None = None,
         *,
-        ids: Optional[list[str]] = None,
+        ids: list[str] | None = None,
         **kwargs: Any,
     ) -> Self:
-        """Async return VectorStore initialized from texts and embeddings.
+        """Async return `VectorStore` initialized from texts and embeddings.
 
         Args:
-            texts: Texts to add to the vectorstore.
+            texts: Texts to add to the `VectorStore`.
             embedding: Embedding function to use.
             metadatas: Optional list of metadatas associated with the texts.
-                Default is None.
             ids: Optional list of IDs associated with the texts.
-            kwargs: Additional keyword arguments.
+            **kwargs: Additional keyword arguments.
 
         Returns:
-            VectorStore: VectorStore initialized from texts and embeddings.
+            `VectorStore` initialized from texts and embeddings.
         """
         if ids is not None:
             kwargs["ids"] = ids
@@ -928,60 +897,57 @@ class VectorStore(ABC):
         return tags
 
     def as_retriever(self, **kwargs: Any) -> VectorStoreRetriever:
-        """Return VectorStoreRetriever initialized from this VectorStore.
+        """Return `VectorStoreRetriever` initialized from this `VectorStore`.
 
         Args:
             **kwargs: Keyword arguments to pass to the search function.
                 Can include:
-                search_type (Optional[str]): Defines the type of search that
-                    the Retriever should perform.
-                    Can be "similarity" (default), "mmr", or
-                    "similarity_score_threshold".
-                search_kwargs (Optional[Dict]): 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
-                            for similarity_score_threshold
-                        fetch_k: Amount of documents to pass to MMR algorithm
-                            (Default: 20)
-                        lambda_mult: Diversity of results returned by MMR;
-                            1 for minimum diversity and 0 for maximum. (Default: 0.5)
-                        filter: Filter by document metadata
+
+                * `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:
+
+                    * `k`: Amount of documents to return (Default: `4`)
+                    * `score_threshold`: Minimum relevance threshold
+                        for `similarity_score_threshold`
+                    * `fetch_k`: Amount of documents to pass to MMR algorithm
+                        (Default: `20`)
+                    * `lambda_mult`: Diversity of results returned by MMR;
+                        `1` for minimum diversity and 0 for maximum. (Default: `0.5`)
+                    * `filter`: Filter by document metadata
 
         Returns:
-            VectorStoreRetriever: Retriever class for VectorStore.
+            Retriever class for `VectorStore`.
 
         Examples:
+        ```python
+        # Retrieve more documents with higher diversity
+        # Useful if your dataset has many similar documents
+        docsearch.as_retriever(
+            search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25}
+        )
 
-        .. code-block:: python
-
-            # Retrieve more documents with higher diversity
-            # Useful if your dataset has many similar documents
-            docsearch.as_retriever(
-                search_type="mmr", search_kwargs={"k": 6, "lambda_mult": 0.25}
-            )
-
-            # Fetch more documents for the MMR algorithm to consider
-            # But only return the top 5
-            docsearch.as_retriever(
-                search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50}
-            )
-
-            # Only retrieve documents that have a relevance score
-            # Above a certain threshold
-            docsearch.as_retriever(
-                search_type="similarity_score_threshold",
-                search_kwargs={"score_threshold": 0.8},
-            )
+        # Fetch more documents for the MMR algorithm to consider
+        # But only return the top 5
+        docsearch.as_retriever(search_type="mmr", search_kwargs={"k": 5, "fetch_k": 50})
 
-            # Only get the single most similar document from the dataset
-            docsearch.as_retriever(search_kwargs={"k": 1})
+        # Only retrieve documents that have a relevance score
+        # Above a certain threshold
+        docsearch.as_retriever(
+            search_type="similarity_score_threshold",
+            search_kwargs={"score_threshold": 0.8},
+        )
 
-            # Use a filter to only retrieve documents from a specific paper
-            docsearch.as_retriever(
-                search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}}
-            )
+        # Only get the single most similar document from the dataset
+        docsearch.as_retriever(search_kwargs={"k": 1})
 
+        # Use a filter to only retrieve documents from a specific paper
+        docsearch.as_retriever(
+            search_kwargs={"filter": {"paper_title": "GPT-4 Technical Report"}}
+        )
+        ```
         """
         tags = kwargs.pop("tags", None) or [*self._get_retriever_tags()]
         return VectorStoreRetriever(vectorstore=self, tags=tags, **kwargs)
@@ -993,7 +959,7 @@ class VectorStoreRetriever(BaseRetriever):
     vectorstore: VectorStore
     """VectorStore to use for retrieval."""
     search_type: str = "similarity"
-    """Type of search to perform. Defaults to "similarity"."""
+    """Type of search to perform."""
     search_kwargs: dict = Field(default_factory=dict)
     """Keyword arguments to pass to the search function."""
     allowed_search_types: ClassVar[Collection[str]] = (
@@ -1015,11 +981,11 @@ class VectorStoreRetriever(BaseRetriever):
             values: Values to validate.
 
         Returns:
-            Values: Validated values.
+            Validated values.
 
         Raises:
-            ValueError: If search_type is not one of the allowed search types.
-            ValueError: If score_threshold is not specified with a float value(0~1)
+            ValueError: If `search_type` is not one of the allowed search types.
+            ValueError: If `score_threshold` is not specified with a float value(`0~1`)
         """
         search_type = values.get("search_type", "similarity")
         if search_type not in cls.allowed_search_types:
@@ -1107,10 +1073,10 @@ class VectorStoreRetriever(BaseRetriever):
         return docs
 
     def add_documents(self, documents: list[Document], **kwargs: Any) -> list[str]:
-        """Add documents to the vectorstore.
+        """Add documents to the `VectorStore`.
 
         Args:
-            documents: Documents to add to the vectorstore.
+            documents: Documents to add to the `VectorStore`.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns:
@@ -1121,10 +1087,10 @@ class VectorStoreRetriever(BaseRetriever):
     async def aadd_documents(
         self, documents: list[Document], **kwargs: Any
     ) -> list[str]:
-        """Async add documents to the vectorstore.
+        """Async add documents to the `VectorStore`.
 
         Args:
-            documents: Documents to add to the vectorstore.
+            documents: Documents to add to the `VectorStore`.
             **kwargs: Other keyword arguments that subclasses might use.
 
         Returns: