Docstrings updates

libs/astradb/langchain_astradb/__init__.py

@@ -1,4 +1,20 @@
-"""Astra DB integration for LangChain."""
+"""Astra DB integration for LangChain.
+
+This module provides several LangChain components using Astra DB as the backend.
+
+For an overview, consult the integration
+[docs page](https://docs.langchain.com/oss/python/integrations/providers/astradb).
+
+Provided components:
+
+- `AstraDBVectorStore`, a vector store backed by Astra DB, with Vectorize support,
+  hybrid search and more.
+- `AstraDBStore`, `AstraDBByteStore`, key-value storage components for generic
+  values and binary blobs, respectively
+- `AstraDBCache`, `AstraDBSemanticCache`, LLM response caches.
+- `AstraDBChatMessageHistory`, memory for use in chat interfaces.
+- `AstraDBLoader`, loaders of data from Astra DB collections.
+"""
 
 from astrapy.info import VectorServiceOptions
 

libs/astradb/langchain_astradb/cache.py

@@ -122,13 +122,13 @@ def __init__(
         ext_callers: list[tuple[str | None, str | None] | str | None] | None = None,
         api_options: APIOptions | None = None,
     ):
-        """Cache that uses Astra DB as a backend.
+        """Cache using Astra DB as a backend, using a collection as a key-value store.
 
-        It uses a single collection as a kv store
         The lookup keys, combined in the _id of the documents, are:
-            - prompt, a string
-            - llm_string, a deterministic str representation of the model parameters.
-              (needed to prevent same-prompt-different-model collisions)
+
+        - prompt, a string
+        - llm_string, a deterministic str representation of the model parameters.
+          (needed to prevent same-prompt-different-model collisions)
 
         Args:
             collection_name: name of the Astra DB collection to create/use.

libs/astradb/langchain_astradb/storage.py

@@ -338,7 +338,8 @@ def __init__(
     ) -> None:
         """ByteStore implementation using DataStax AstraDB as the underlying store.
 
-        The bytes values are converted to base64 encoded strings
+        The bytes values are converted to base64 encoded strings.
+
         Documents in the AstraDB collection will have the format
 
         ```json

libs/astradb/langchain_astradb/vectorstores.py

@@ -408,20 +408,6 @@ class AstraDBVectorStore(VectorStore):
         pip install -qU langchain-astradb
         ```
 
-    Key init args — indexing params:
-        collection_name: str
-            Name of the collection.
-        embedding: Embeddings
-            Embedding function to use.
-
-    Key init args — client params:
-        api_endpoint: str
-            Astra DB API endpoint.
-        token: str
-            API token for Astra DB usage.
-        namespace: Optional[str]
-            Namespace (aka keyspace) where the collection is created
-
     Instantiate:
         Get your API endpoint and application token from the dashboard of your database.
 
@@ -561,6 +547,8 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Add Documents:
+        Add one or more documents to the vector store. IDs are optional: if provided,
+        and matching existing documents, an overwrite is performed.
 
         ```python
         from langchain_core.documents import Document
@@ -575,12 +563,14 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Delete Documents:
+        Delete one or more documents from the vector store by their IDs.
 
         ```python
         vector_store.delete(ids=["3"])
         ```
 
     Search:
+        Run a similarity search with a provided query string.
 
         ```python
         results = vector_store.similarity_search(query="thud", k=1)
@@ -593,6 +583,10 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Search with filter:
+        Specify metadata filters for a search. Simple `key: value` syntax
+        for the filter means equality (with implied 'and').
+        More complex syntax is available, following the Data API specifications, see
+        (docs)[https://docs.datastax.com/en/astra-db-serverless/api-reference/filter-operator-collections.html].
 
         ```python
         results = vector_store.similarity_search(
@@ -607,6 +601,7 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Search with score:
+        Search results are returned with their similarity score.
 
         ```python
         results = vector_store.similarity_search_with_score(query="qux", k=1)
@@ -619,6 +614,7 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Async:
+        All methods come with their async counterpart (method name prepended with `a`).
 
         ```python
         # add documents
@@ -641,6 +637,7 @@ class AstraDBVectorStore(VectorStore):
         ```
 
     Use as Retriever:
+        A Retriever can be spawned from the vector store for further usage.
 
         ```python
         retriever = vector_store.as_retriever(
@@ -911,7 +908,7 @@ def __init__(
 
         Note:
             For concurrency in synchronous
-            [add_texts](langchain_astradb.AstraDBVectorStore.add_texts),
+            [`add_texts`][langchain_astradb.AstraDBVectorStore.add_texts],
             as a rule of thumb,
             on a typical client machine it is suggested to keep the quantity
             bulk_insert_batch_concurrency * bulk_insert_overwrite_concurrency
@@ -926,8 +923,9 @@ def __init__(
             depending on both the machine/network specs and the expected workload
             (specifically, how often a write is an update of an existing id).
             Remember you can pass concurrency settings to individual calls to
-            [add_texts](langchain_astradb.AstraDBVectorStore.add_texts) and
-            [add_documents](langchain_astradb.AstraDBVectorStore.add_documents) as well.
+            [`add_texts`][langchain_astradb.AstraDBVectorStore.add_texts] and
+            [`add_documents`][langchain_astradb.AstraDBVectorStore.add_documents]as
+            well.
         """
         # general collection settings
         self.collection_name = collection_name
@@ -1468,8 +1466,8 @@ def delete_collection(self) -> None:
         """Completely delete the collection from the database.
 
         Completely delete the collection from the database (as opposed
-        to [clear](langchain_astradb.AstraDBVectorStore.clear), which empties it only).
-        Stored data is lost and unrecoverable, resources are freed.
+        to [`clear`][langchain_astradb.AstraDBVectorStore.clear], which empties it
+        only). Stored data is lost and unrecoverable, resources are freed.
         Use with caution.
         """
         self.astra_env.ensure_db_setup()
@@ -1479,7 +1477,7 @@ async def adelete_collection(self) -> None:
         """Completely delete the collection from the database.
 
         Completely delete the collection from the database (as opposed to
-        [aclear](langchain_astradb.AstraDBVectorStore.aclear),
+        [`aclear`][langchain_astradb.AstraDBVectorStore.aclear],
         which empties it only).
         Stored data is lost and unrecoverable, resources are freed.
         Use with caution.
@@ -1556,9 +1554,8 @@ def add_texts(
         Note:
             The allowed field names for the metadata document attributes must
             obey certain rules (such as: keys cannot start with a dollar sign
-            and cannot be empty).
-            See [Naming Conventions](https://docs.datastax.com/en/astra-db-serverless/api-reference/dataapiclient.html#naming-conventions)
-            for details.
+            and cannot be empty). See the
+            [document field naming rules](https://docs.datastax.com/en/astra-db-serverless/api-reference/document-methods/insert-one.html#parameters).
 
         Returns:
             The list of ids of the added texts.
@@ -1700,9 +1697,8 @@ async def aadd_texts(
         Note:
             The allowed field names for the metadata document attributes must
             obey certain rules (such as: keys cannot start with a dollar sign
-            and cannot be empty).
-            See [Naming Conventions](https://docs.datastax.com/en/astra-db-serverless/api-reference/dataapiclient.html#naming-conventions)
-            for details.
+            and cannot be empty). See the
+            [document field naming rules](https://docs.datastax.com/en/astra-db-serverless/api-reference/document-methods/insert-one.html#parameters).
 
         Returns:
             The list of ids of the added texts.
@@ -3873,7 +3869,7 @@ def from_texts(
             metadatas: metadata dicts for the texts.
             ids: ids to associate to the texts.
             **kwargs: you can pass any argument that you would to
-                [add_texts](langchain_astradb.AstraDBVectorStore.add_texts)
+                [`add_texts`][langchain_astradb.AstraDBVectorStore.add_texts]
                 and/or to the
                 `AstraDBVectorStore` constructor (see these methods for
                 details). These arguments will be
@@ -3918,7 +3914,7 @@ async def afrom_texts(
             metadatas: metadata dicts for the texts.
             ids: ids to associate to the texts.
             **kwargs: you can pass any argument that you would to
-                [aadd_texts](langchain_astradb.AstraDBVectorStore.aadd_texts)
+                [`aadd_texts`][langchain_astradb.AstraDBVectorStore.aadd_texts]
                 and/or to the `AstraDBVectorStore`
                 constructor (see these methods for details). These arguments
                 will be routed to the respective methods as they are.
@@ -3956,13 +3952,13 @@ def from_documents(
         """Create an Astra DB vectorstore from a document list.
 
         Utility method that defers to
-        [from_texts](langchain_astradb.AstraDBVectorStore.from_texts).
+        [`from_texts`][langchain_astradb.AstraDBVectorStore.from_texts].
 
         Args:
             documents: a list of `Document` objects for insertion in the store.
             embedding: the embedding function to use in the store.
             **kwargs: you can pass any argument that you would to
-                [add_texts](langchain_astradb.AstraDBVectorStore.add_texts)
+                [`add_texts`][langchain_astradb.AstraDBVectorStore.add_texts]
                 and/or to the `AstraDBVectorStore` constructor (see these methods for
                 details). These arguments will be
                 routed to the respective methods as they are.
@@ -4006,13 +4002,13 @@ async def afrom_documents(
         """Create an Astra DB vectorstore from a document list.
 
         Utility method that defers to
-        [afrom_texts](langchain_astradb.AstraDBVectorStore.afrom_texts).
+        [`afrom_texts`][langchain_astradb.AstraDBVectorStore.afrom_texts].
 
         Args:
             documents: a list of `Document` objects for insertion in the store.
             embedding: the embedding function to use in the store.
             **kwargs: you can pass any argument that you would to
-                [aadd_texts](langchain_astradb.AstraDBVectorStore.aadd_texts)
+                [`aadd_texts`][langchain_astradb.AstraDBVectorStore.aadd_texts]
                 and/or to the `AstraDBVectorStore` constructor (see these methods for
                 details). These arguments will be
                 routed to the respective methods as they are.