Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

refactor(storages): standardize docstrings in vectordb_storages (#911) (#4153)

K RUSHIKESH0ae768de632d
diff --git a/camel/storages/vectordb_storages/base.py b/camel/storages/vectordb_storages/base.py
index 733d6460c..b40cc9d07 100644
--- a/camel/storages/vectordb_storages/base.py
+++ b/camel/storages/vectordb_storages/base.py
@@ -27,7 +27,7 @@ class VectorRecord(BaseModel):
Attributes:
vector (List[float]): The numerical representation of the vector.
id (str, optional): A unique identifier for the vector. If not
- provided, an random uuid will be assigned.
+ provided, a random uuid will be assigned.
payload (Optional[Dict[str, Any]], optional): Any additional metadata
or information related to the vector. (default: :obj:`None`)
"""
@@ -48,14 +48,15 @@ class VectorDBQuery(BaseModel):
"""
query_vector: List[float]
- """The numerical representation of the query vector."""
+ r"""The numerical representation of the query vector."""
top_k: int = 1
- """The number of top similar vectors to retrieve from the database."""
+ r"""The number of top similar vectors to retrieve from the database."""
def __init__(
self, query_vector: List[float], top_k: int, **kwargs: Any
) -> None:
- """Pass in query_vector and tok_k as positional arg.
+ r"""Pass in query_vector and top_k as positional arg.
+
Args:
query_vector (List[float]): The numerical representation of the
query vector.
@@ -85,7 +86,19 @@ class VectorDBQueryResult(BaseModel):
id: str,
payload: Optional[Dict[str, Any]] = None,
) -> "VectorDBQueryResult":
- r"""A class method to construct a `VectorDBQueryResult` instance."""
+ r"""A class method to construct a `VectorDBQueryResult` instance.
+
+ Args:
+ similarity (float): The similarity score.
+ vector (List[float]): The numerical representation of the vector.
+ id (str): A unique identifier for the vector.
+ payload (Optional[Dict[str, Any]], optional): Any additional
+ metadata or information related to the vector.
+ (default: :obj:`None`)
+
+ Returns:
+ VectorDBQueryResult: The constructed query result instance.
+ """
return cls(
record=VectorRecord(
vector=vector,
@@ -207,7 +220,7 @@ class BaseVectorStorage(ABC):
top_k (int): The number of top similar vectors.
Returns:
- List[List[Dict[str, Any]]]: A list of vector payloads retrieved
+ List[Dict[str, Any]]: A list of vector payloads retrieved
from the storage based on similarity to the query vector.
"""
results = self.query(VectorDBQuery(query_vector=vector, top_k=top_k))
diff --git a/camel/storages/vectordb_storages/chroma.py b/camel/storages/vectordb_storages/chroma.py
index 023ab7a6a..49f8dbb75 100644
--- a/camel/storages/vectordb_storages/chroma.py
+++ b/camel/storages/vectordb_storages/chroma.py
@@ -270,7 +270,11 @@ class ChromaStorage(BaseVectorStorage):
# and don't require validation
def _get_connection_client(self) -> "ClientAPI":
- r"""Get ChromaDB client based on client type and user settings."""
+ r"""Get ChromaDB client based on client type and user settings.
+
+ Returns:
+ ClientAPI: The ChromaDB client instance.
+ """
import chromadb
# Map client types to handler methods
@@ -293,14 +297,28 @@ class ChromaStorage(BaseVectorStorage):
raise
def _create_ephemeral_client(self, chromadb_module: Any) -> "ClientAPI":
- r"""Create an ephemeral ChromaDB client (in-memory)."""
+ r"""Create an ephemeral ChromaDB client (in-memory).
+
+ Args:
+ chromadb_module (Any): The imported chromadb module.
+
+ Returns:
+ ClientAPI: The ephemeral ChromaDB client instance.
+ """
client_kwargs = self._get_common_client_kwargs()
client = chromadb_module.EphemeralClient(**client_kwargs)
logger.info("Created ChromaDB EphemeralClient (in-memory)")
return client
def _create_persistent_client(self, chromadb_module: Any) -> "ClientAPI":
- r"""Create a persistent ChromaDB client (local file storage)."""
+ r"""Create a persistent ChromaDB client (local file storage).
+
+ Args:
+ chromadb_module (Any): The imported chromadb module.
+
+ Returns:
+ ClientAPI: The persistent ChromaDB client instance.
+ """
client_kwargs = {'path': self._connection_params['path']}
client_kwargs.update(self._get_common_client_kwargs())
client = chromadb_module.PersistentClient(**client_kwargs)
@@ -311,7 +329,14 @@ class ChromaStorage(BaseVectorStorage):
return client
def _create_http_client(self, chromadb_module: Any) -> "ClientAPI":
- r"""Create an HTTP ChromaDB client (remote server)."""
+ r"""Create an HTTP ChromaDB client (remote server).
+
+ Args:
+ chromadb_module (Any): The imported chromadb module.
+
+ Returns:
+ ClientAPI: The HTTP ChromaDB client instance.
+ """
client_kwargs = {
'host': self._connection_params['host'],
'port': self._connection_params['port'],
@@ -329,7 +354,14 @@ class ChromaStorage(BaseVectorStorage):
return client
def _create_cloud_client(self, chromadb_module: Any) -> "ClientAPI":
- r"""Create a cloud ChromaDB client."""
+ r"""Create a cloud ChromaDB client.
+
+ Args:
+ chromadb_module (Any): The imported chromadb module.
+
+ Returns:
+ ClientAPI: The cloud ChromaDB client instance.
+ """
try:
client_kwargs = {
'cloud_host': self._connection_params['cloud_host'],
@@ -359,7 +391,12 @@ class ChromaStorage(BaseVectorStorage):
)
def _get_common_client_kwargs(self) -> Dict[str, Any]:
- r"""Get common kwargs for all ChromaDB clients."""
+ r"""Get common kwargs for all ChromaDB clients.
+
+ Returns:
+ Dict[str, Any]: Common keyword arguments for client
+ initialization.
+ """
common_kwargs: Dict[str, Any] = {}
# Add truly common parameters that all ChromaDB clients support
@@ -403,7 +440,7 @@ class ChromaStorage(BaseVectorStorage):
r"""Gets existing collection or creates a new one.
Returns:
- ChromaDB collection object.
+ Collection: The ChromaDB collection object.
Raises:
RuntimeError: If collection operations fail.
@@ -726,6 +763,6 @@ class ChromaStorage(BaseVectorStorage):
r"""Provides access to the underlying ChromaDB collection.
Returns:
- ChromaDB collection instance.
+ Collection: The ChromaDB collection instance.
"""
return self._collection
diff --git a/camel/storages/vectordb_storages/faiss.py b/camel/storages/vectordb_storages/faiss.py
index 20f1c1604..3f71ba6e3 100644
--- a/camel/storages/vectordb_storages/faiss.py
+++ b/camel/storages/vectordb_storages/faiss.py
@@ -82,18 +82,7 @@ class FaissStorage(BaseVectorStorage):
m: int = 16,
**kwargs: Any,
) -> None:
- r"""Initialize the FAISS vector storage.
-
- Args:
- vector_dim: Dimension of vectors to be stored
- index_type: FAISS index type ('Flat', 'IVF', 'HNSW', etc.)
- collection_name: Name of the collection (defaults to timestamp)
- storage_path: Directory to save the index (None for in-memory only)
- distance: Vector distance metric
- nlist: Number of clusters for IVF indexes
- m: HNSW parameter for connections per node
- **kwargs: Additional parameters
- """
+ r"""Initialize the FAISS vector storage."""
import faiss
import numpy as np
@@ -126,17 +115,35 @@ class FaissStorage(BaseVectorStorage):
self._load_from_disk()
def _generate_collection_name(self) -> str:
- r"""Generates a collection name if user doesn't provide"""
+ r"""Generates a collection name if user doesn't provide.
+
+ Returns:
+ str: Generated collection name.
+ """
return f"faiss_index_{datetime.now().isoformat()}"
def _get_index_path(self) -> str:
- r"""Returns the path to the index file"""
+ r"""Returns the path to the index file.
+
+ Returns:
+ str: The path to the index file.
+
+ Raises:
+ ValueError: If storage path is not set.
+ """
if self.storage_path is None:
raise ValueError("Storage path is not set.")
return os.path.join(self.storage_path, f"{self.collection_name}.index")
def _get_metadata_path(self) -> str:
- r"""Returns the path to the metadata file"""
+ r"""Returns the path to the metadata file.
+
+ Returns:
+ str: The path to the metadata file.
+
+ Raises:
+ ValueError: If storage path is not set.
+ """
if self.storage_path is None:
raise ValueError("Storage path is not set.")
return os.path.join(
@@ -147,7 +154,11 @@ class FaissStorage(BaseVectorStorage):
r"""Creates a new FAISS index based on specified parameters.
Returns:
- A FAISS index object configured according to the parameters.
+ Any: A FAISS index object configured according to the parameters.
+
+ Raises:
+ ValueError: If an unsupported distance metric or index type is
+ specified.
"""
import faiss
@@ -225,7 +236,11 @@ class FaissStorage(BaseVectorStorage):
logger.info(f"Saved FAISS index and metadata to {self.storage_path}")
def _load_from_disk(self) -> None:
- r"""Loads the index and metadata from disk if they exist."""
+ r"""Loads the index and metadata from disk if they exist.
+
+ If loading fails, including when metadata is missing required keys,
+ logs the error and attempts to create a new index.
+ """
if self.storage_path is None:
return
@@ -684,7 +699,11 @@ class FaissStorage(BaseVectorStorage):
@property
def client(self) -> Any:
- r"""Provides access to the underlying FAISS client."""
+ r"""Provides access to the underlying FAISS client.
+
+ Returns:
+ Any: The FAISS client module or instance.
+ """
return self._faiss_client
def _matches_filter(
diff --git a/camel/storages/vectordb_storages/milvus.py b/camel/storages/vectordb_storages/milvus.py
index 4925e22c0..211ddd9cf 100644
--- a/camel/storages/vectordb_storages/milvus.py
+++ b/camel/storages/vectordb_storages/milvus.py
@@ -47,7 +47,7 @@ class MilvusStorage(BaseVectorStorage):
the Milvus. If not provided, set it to the current time with iso
format. (default: :obj:`None`)
**kwargs (Any): Additional keyword arguments for initializing
- `MilvusClient`.
+ :obj:`MilvusClient`.
Raises:
ImportError: If `pymilvus` package is not installed.
@@ -81,7 +81,8 @@ class MilvusStorage(BaseVectorStorage):
Args:
url_and_api_key (Tuple[str, str]): The URL and API key for the
Milvus server.
- **kwargs: Additional keyword arguments passed to the Milvus client.
+ **kwargs (Any): Additional keyword arguments passed to the Milvus
+ client.
"""
from pymilvus import MilvusClient
@@ -94,6 +95,10 @@ class MilvusStorage(BaseVectorStorage):
def _check_and_create_collection(self) -> None:
r"""Checks if the specified collection exists in Milvus and creates it
if it doesn't, ensuring it matches the specified vector dimensionality.
+
+ Raises:
+ ValueError: If vector dimension of the existing collection is
+ different from the given embedding dimension.
"""
if self._collection_exists(self.collection_name):
in_dim = self._get_collection_info(self.collection_name)[
@@ -120,7 +125,7 @@ class MilvusStorage(BaseVectorStorage):
Args:
collection_name (str): Name of the collection to be created.
- **kwargs (Any): Additional keyword arguments pass to create
+ **kwargs (Any): Additional keyword arguments passed to create
collection.
"""
@@ -184,7 +189,7 @@ class MilvusStorage(BaseVectorStorage):
r"""Deletes an existing collection from the database.
Args:
- collection (str): Name of the collection to be deleted.
+ collection_name (str): Name of the collection to be deleted.
"""
self._client.drop_collection(collection_name=collection_name)
@@ -282,7 +287,7 @@ class MilvusStorage(BaseVectorStorage):
Args:
records (List[VectorRecord]): List of vectors to be added.
- **kwargs (Any): Additional keyword arguments pass to insert.
+ **kwargs (Any): Additional keyword arguments passed to insert.
Raises:
RuntimeError: If there was an error in the addition process.
diff --git a/camel/storages/vectordb_storages/oceanbase.py b/camel/storages/vectordb_storages/oceanbase.py
index db64431ac..a00f74ac0 100644
--- a/camel/storages/vectordb_storages/oceanbase.py
+++ b/camel/storages/vectordb_storages/oceanbase.py
@@ -54,7 +54,7 @@ class OceanBaseStorage(BaseVectorStorage):
table should be deleted upon object destruction.
(default: :obj:`False`)
**kwargs (Any): Additional keyword arguments for initializing
- `ObVecClient`.
+ :obj:`ObVecClient`.
Raises:
ImportError: If `pyobvector` package is not installed.
@@ -168,7 +168,8 @@ class OceanBaseStorage(BaseVectorStorage):
Raises:
RuntimeError: If there is an error during the saving process.
- ValueError: If any vector dimension doesn't match vector_dim.
+ ValueError: If any vector dimension doesn't match
+ :obj:`vector_dim`.
"""
if not records:
@@ -271,6 +272,9 @@ class OceanBaseStorage(BaseVectorStorage):
Returns:
VectorDBStatus: The vector database status.
+
+ Raises:
+ RuntimeError: If there is an error getting status from OceanBase.
"""
try:
# Get count of records
@@ -494,7 +498,11 @@ class OceanBaseStorage(BaseVectorStorage):
return max(0.0, min(1.0, 1.0 - min(1.0, distance)))
def clear(self) -> None:
- r"""Remove all vectors from the storage."""
+ r"""Remove all vectors from the storage.
+
+ Raises:
+ RuntimeError: If there is an error clearing records from OceanBase.
+ """
try:
self._client.delete(self.table_name)
logger.info(f"Cleared all records from table {self.table_name}")
@@ -510,5 +518,9 @@ class OceanBaseStorage(BaseVectorStorage):
@property
def client(self) -> "ObVecClient":
- r"""Provides access to underlying OceanBase vector database client."""
+ r"""Provides access to underlying OceanBase vector database client.
+
+ Returns:
+ ObVecClient: The underlying OceanBase client instance.
+ """
return self._client
diff --git a/camel/storages/vectordb_storages/pgvector.py b/camel/storages/vectordb_storages/pgvector.py
index bf95c1cea..1bb1a2faf 100644
--- a/camel/storages/vectordb_storages/pgvector.py
+++ b/camel/storages/vectordb_storages/pgvector.py
@@ -40,7 +40,7 @@ class PgVectorStorage(BaseVectorStorage):
Args:
vector_dim (int): The dimension of the vectors to be stored.
conn_info (Dict[str, Any]): Connection information for
- psycopg2.connect.
+ :obj:`psycopg2.connect`.
table_name (str, optional): Name of the table to store vectors.
(default: :obj:`None`)
distance (VectorDistance, optional): Distance metric for vector
@@ -56,15 +56,7 @@ class PgVectorStorage(BaseVectorStorage):
distance: VectorDistance = VectorDistance.COSINE,
**kwargs: Any,
) -> None:
- r"""Initialize PgVectorStorage.
-
- Args:
- vector_dim (int): The dimension of the vectors.
- conn_info (Dict[str, Any]): Connection info for psycopg2.connect.
- table_name (str, optional): Table name. (default: :obj:`None`)
- distance (VectorDistance, optional): Distance metric.
- (default: :obj:`VectorDistance.COSINE`)
- """
+ r"""Initialize PgVectorStorage."""
import psycopg
from pgvector.psycopg import register_vector
@@ -88,6 +80,9 @@ class PgVectorStorage(BaseVectorStorage):
def _ensure_table(self) -> None:
r"""Ensure the vector table exists in the database.
Creates the table if it does not exist.
+
+ Raises:
+ Exception: If creating the table fails.
"""
try:
from psycopg.sql import SQL, Identifier, Literal
@@ -137,6 +132,11 @@ class PgVectorStorage(BaseVectorStorage):
Args:
records (List[VectorRecord]): List of vector records to
add or update.
+ **kwargs (Any): Additional keyword arguments.
+
+ Raises:
+ ValueError: If there is a vector dimension mismatch.
+ Exception: If adding or updating records fails.
"""
if not records:
return
@@ -185,6 +185,10 @@ class PgVectorStorage(BaseVectorStorage):
Args:
ids (List[str]): List of record IDs to delete.
+ **kwargs (Any): Additional keyword arguments.
+
+ Raises:
+ Exception: If deleting records fails.
"""
from psycopg.sql import SQL, Identifier
@@ -217,6 +221,10 @@ class PgVectorStorage(BaseVectorStorage):
Returns:
List[VectorDBQueryResult]: List of query results sorted by
similarity.
+
+ Raises:
+ ValueError: If vector dimension mismatches or unsupported distance
+ metric is used.
"""
if len(query.query_vector) != self.vector_dim:
raise ValueError(
@@ -277,7 +285,17 @@ class PgVectorStorage(BaseVectorStorage):
raise
def _score_to_similarity(self, score: float) -> float:
- r"""Convert a pgvector operator result to high-is-better similarity."""
+ r"""Convert a pgvector operator result to high-is-better similarity.
+
+ Args:
+ score (float): The distance or score returned by pgvector.
+
+ Returns:
+ float: The similarity score.
+
+ Raises:
+ ValueError: If an unsupported distance metric is specified.
+ """
if self.distance == VectorDistance.COSINE:
return max(0.0, min(1.0, 1.0 - score))
if self.distance == VectorDistance.EUCLIDEAN:
@@ -295,6 +313,9 @@ class PgVectorStorage(BaseVectorStorage):
Returns:
VectorDBStatus: Status object with vector dimension and count.
+
+ Raises:
+ Exception: If querying database status fails.
"""
try:
with self._conn.cursor() as cur:
@@ -314,7 +335,11 @@ class PgVectorStorage(BaseVectorStorage):
raise
def clear(self) -> None:
- r"""Remove all vectors from the storage by truncating the table."""
+ r"""Remove all vectors from the storage by truncating the table.
+
+ Raises:
+ Exception: If clearing table fails.
+ """
try:
with self._conn.cursor() as cur:
from psycopg.sql import SQL, Identifier
diff --git a/camel/storages/vectordb_storages/qdrant.py b/camel/storages/vectordb_storages/qdrant.py
index f94412b0a..dacb8b484 100644
--- a/camel/storages/vectordb_storages/qdrant.py
+++ b/camel/storages/vectordb_storages/qdrant.py
@@ -96,8 +96,8 @@ class QdrantStorage(BaseVectorStorage):
self.delete_collection_on_del = delete_collection_on_del
def __del__(self):
- r"""Deletes the collection if :obj:`del_collection` is set to
- :obj:`True`.
+ r"""Deletes the collection if :obj:`delete_collection_on_del` is set
+ to :obj:`True`.
"""
# If the client is a local client, decrease count by 1
if self._local_path is not None:
@@ -211,7 +211,7 @@ class QdrantStorage(BaseVectorStorage):
r"""Deletes an existing collection from the database.
Args:
- collection (str): Name of the collection to be deleted.
+ collection_name (str): Name of the collection to be deleted.
**kwargs (Any): Additional keyword arguments.
"""
self._client.delete_collection(
@@ -219,14 +219,25 @@ class QdrantStorage(BaseVectorStorage):
)
def _collection_exists(self, collection_name: str) -> bool:
- r"""Returns whether the collection exists in the database"""
+ r"""Returns whether the collection exists in the database.
+
+ Args:
+ collection_name (str): The name of the collection to check.
+
+ Returns:
+ bool: True if the collection exists, False otherwise.
+ """
for c in self._client.get_collections().collections:
if collection_name == c.name:
return True
return False
def _generate_collection_name(self) -> str:
- r"""Generates a collection name if user doesn't provide"""
+ r"""Generates a collection name if user doesn't provide.
+
+ Returns:
+ str: Generated collection name.
+ """
return datetime.now().isoformat()
def _get_collection_info(self, collection_name: str) -> Dict[str, Any]:
@@ -255,8 +266,12 @@ class QdrantStorage(BaseVectorStorage):
"config": collection_info.config,
}
- def close_client(self, **kwargs):
- r"""Closes the client connection to the Qdrant storage."""
+ def close_client(self, **kwargs: Any) -> None:
+ r"""Closes the client connection to the Qdrant storage.
+
+ Args:
+ **kwargs (Any): Additional keyword arguments passed to close.
+ """
self._client.close(**kwargs)
def add(
@@ -267,7 +282,7 @@ class QdrantStorage(BaseVectorStorage):
r"""Adds a list of vectors to the specified collection.
Args:
- vectors (List[VectorRecord]): List of vectors to be added.
+ records (List[VectorRecord]): List of vectors to be added.
**kwargs (Any): Additional keyword arguments.
Raises:
@@ -407,6 +422,11 @@ class QdrantStorage(BaseVectorStorage):
)
def status(self) -> VectorDBStatus:
+ r"""Returns status of the vector database.
+
+ Returns:
+ VectorDBStatus: The vector database status.
+ """
status = self._get_collection_info(self.collection_name)
return VectorDBStatus(
vector_dim=status["vector_dim"],
@@ -487,5 +507,9 @@ class QdrantStorage(BaseVectorStorage):
@property
def client(self) -> "QdrantClient":
- r"""Provides access to the underlying vector database client."""
+ r"""Provides access to the underlying vector database client.
+
+ Returns:
+ QdrantClient: The underlying Qdrant client instance.
+ """
return self._client
diff --git a/camel/storages/vectordb_storages/surreal.py b/camel/storages/vectordb_storages/surreal.py
index 15767f744..3c2434e50 100644
--- a/camel/storages/vectordb_storages/surreal.py
+++ b/camel/storages/vectordb_storages/surreal.py
@@ -37,17 +37,18 @@ class SurrealStorage(BaseVectorStorage):
`SurrealDB <https://surrealdb.com>`_
Args:
- url (str): WebSocket URL for connecting to SurrealDB
- (default: "ws://localhost:8000/rpc").
- table (str): Name of the table used for storing vectors
- (default: "vector_store").
+ url (str): WebSocket URL for connecting to SurrealDB.
+ (default: :obj:`"ws://localhost:8000/rpc"`)
+ table (str): Name of the table used for storing vectors.
+ (default: :obj:`"vector_store"`)
vector_dim (int): Dimensionality of the stored vectors.
distance (VectorDistance): Distance metric used for similarity
- comparisons (default: VectorDistance.COSINE).
- namespace (str): SurrealDB namespace to use (default: "default").
- database (str): SurrealDB database name (default: "demo").
- user (str): Username for authentication (default: "root").
- password (str): Password for authentication (default: "root").
+ comparisons. (default: :obj:`VectorDistance.COSINE`)
+ namespace (str): SurrealDB namespace to use.
+ (default: :obj:`"default"`)
+ database (str): SurrealDB database name. (default: :obj:`"demo"`)
+ user (str): Username for authentication. (default: :obj:`"root"`)
+ password (str): Password for authentication. (default: :obj:`"root"`)
Notes:
- SurrealDB supports flexible schema and powerful querying capabilities
@@ -73,27 +74,7 @@ class SurrealStorage(BaseVectorStorage):
user: str = "root",
password: str = "root",
) -> None:
- r"""Initialize SurrealStorage with connection settings and ensure
- the target table exists.
-
- Args:
- url (str): WebSocket URL for connecting to SurrealDB.
- (default: :obj:`"ws://localhost:8000/rpc"`)
- table (str): Name of the table used for vector storage.
- (default: :obj:`"vector_store"`)
- vector_dim (int): Dimensionality of the stored vectors.
- (default: :obj:`786`)
- distance (VectorDistance): Distance metric for similarity
- searches. (default: :obj:`VectorDistance.COSINE`)
- namespace (str): SurrealDB namespace to use.
- (default: :obj:`"default"`)
- database (str): SurrealDB database name.
- (default: :obj:`"demo"`)
- user (str): Username for authentication.
- (default: :obj:`"root"`)
- password (str): Password for authentication.
- (default: :obj:`"root"`)
- """
+ r"""Initialize SurrealStorage with connection settings."""
from surrealdb import Surreal
@@ -156,6 +137,9 @@ class SurrealStorage(BaseVectorStorage):
Documentation: https://surrealdb.com/docs/surrealdb/reference-guide/
vector-search#vector-search-cheat-sheet
+
+ Raises:
+ ValueError: If unsupported distance metric or table creation fails.
"""
if self.distance.value not in ["cosine", "euclidean", "manhattan"]:
raise ValueError(
@@ -187,6 +171,10 @@ class SurrealStorage(BaseVectorStorage):
def _check_and_create_table(self):
r"""Check if the table exists and matches the expected vector
dimension. If not, create a new table.
+
+ Raises:
+ ValueError: If existing table dimension does not match expected
+ dimension.
"""
if self._table_exists():
in_dim = self._get_table_info()["dim"]
@@ -209,6 +197,9 @@ class SurrealStorage(BaseVectorStorage):
Returns:
List[Dict]: Transformed list of dicts ready for insertion.
+
+ Raises:
+ ValueError: If vector dimension mismatch occurs.
"""
validate_data = []
for record in records:
@@ -236,6 +227,7 @@ class SurrealStorage(BaseVectorStorage):
Args:
query (VectorDBQuery): Query containing the query vector
and top_k value.
+ **kwargs (Any): Additional keyword arguments.
Returns:
List[VectorDBQueryResult]: Ranked list of matching records
@@ -276,7 +268,14 @@ class SurrealStorage(BaseVectorStorage):
return results
def _distance_to_similarity(self, distance: float) -> float:
- r"""Convert a SurrealDB distance value to high-is-better similarity."""
+ r"""Convert a SurrealDB distance value to high-is-better similarity.
+
+ Args:
+ distance (float): The distance value returned by SurrealDB.
+
+ Returns:
+ float: The similarity score.
+ """
distance = max(0.0, distance)
if self.distance == VectorDistance.COSINE:
return max(0.0, min(1.0, 1.0 - distance))
@@ -287,6 +286,10 @@ class SurrealStorage(BaseVectorStorage):
Args:
records (List[VectorRecord]): List of vector records to add.
+ **kwargs (Any): Additional keyword arguments.
+
+ Raises:
+ Exception: If adding records fails.
"""
logger.info(
"Adding %d records to table '%s'.", len(records), self.table
@@ -318,6 +321,11 @@ class SurrealStorage(BaseVectorStorage):
Args:
ids (Optional[List[str]]): List of record IDs to delete.
if_all (bool): Whether to delete all records in the table.
+ **kwargs (Any): Additional keyword arguments.
+
+ Raises:
+ RuntimeError: If neither ids nor if_all=True is provided, or if
+ deleting records fails.
"""
from surrealdb.data.types.record_id import RecordID
@@ -347,6 +355,9 @@ class SurrealStorage(BaseVectorStorage):
Returns:
VectorDBStatus: Object containing vector table metadata.
+
+ Raises:
+ ValueError: If vector dimension or count is None.
"""
status = self._get_table_info()
@@ -367,11 +378,20 @@ class SurrealStorage(BaseVectorStorage):
self._create_table()
def load(self) -> None:
- r"""Load the collection hosted on cloud service."""
+ r"""Load the collection hosted on cloud service.
+
+ Raises:
+ NotImplementedError: Always raised as SurrealDB does not support
+ loading.
+ """
# SurrealDB doesn't require explicit loading
raise NotImplementedError("SurrealDB does not support loading")
@property
def client(self) -> Any:
- r"""Provides access to the underlying SurrealDB client."""
+ r"""Provides access to the underlying SurrealDB client.
+
+ Returns:
+ Any: The underlying SurrealDB client instance.
+ """
return self._surreal_client
diff --git a/camel/storages/vectordb_storages/tidb.py b/camel/storages/vectordb_storages/tidb.py
index 66431b19f..0ea1dd381 100644
--- a/camel/storages/vectordb_storages/tidb.py
+++ b/camel/storages/vectordb_storages/tidb.py
@@ -51,12 +51,13 @@ class TiDBStorage(BaseVectorStorage):
url_and_api_key (Optional[Union[Tuple[str, str], str]]): A tuple
containing the database url and API key for connecting to a TiDB
cluster. The URL should be in the format:
- "mysql+pymysql://<username>:<password>@<host>:<port>/<db_name>".
- TiDB will not use the API Key, but retains the definition for
+ :obj:`"mysql+pymysql://<username>:<password>@<host>:<port>/<db_name>"`
+ . TiDB will not use the API Key, but retains the definition for
interface compatible.
- collection_name (Optional[str]): Name of the collection.
+ collection_name (Optional[str], optional): Name of the collection.
The collection name will be used as the table name in TiDB. If not
provided, set it to the current time with iso format.
+ (default: :obj:`None`)
**kwargs (Any): Additional keyword arguments for initializing
TiDB connection.
@@ -97,7 +98,8 @@ class TiDBStorage(BaseVectorStorage):
Args:
database_url (Optional[str]): The database connection string for
the TiDB server.
- **kwargs: Additional keyword arguments passed to the TiDB client.
+ **kwargs (Any): Additional keyword arguments passed to the TiDB
+ client.
"""
from pytidb import TiDBClient
@@ -107,6 +109,14 @@ class TiDBStorage(BaseVectorStorage):
)
def _get_table_model(self, collection_name: str) -> Any:
+ r"""Generates a dynamic SQLAlchemy table model for TiDB vector storage.
+
+ Args:
+ collection_name (str): Name of the collection table.
+
+ Returns:
+ Any: The generated table model class.
+ """
from pytidb.datatype import JSON # type: ignore[import-not-found]
from pytidb.schema import Field, TableModel, VectorField
@@ -125,7 +135,11 @@ class TiDBStorage(BaseVectorStorage):
)
def _open_and_create_table(self) -> "Table[Any]":
- r"""Opens an existing table or creates a new table in TiDB."""
+ r"""Opens an existing table or creates a new table in TiDB.
+
+ Returns:
+ Table[Any]: The opened or created table instance.
+ """
table = self._client.open_table(self.collection_name)
if table is None:
table_model = self._get_table_model(self.collection_name)
@@ -138,6 +152,10 @@ class TiDBStorage(BaseVectorStorage):
def _check_table(self):
r"""Ensuring the specified table matches the specified vector
dimensionality.
+
+ Raises:
+ ValueError: If existing table dimension does not match expected
+ dimension.
"""
in_dim = self._get_table_info()["vector_dim"]
if in_dim != self.vector_dim:
@@ -201,7 +219,7 @@ class TiDBStorage(BaseVectorStorage):
and convert.
Returns:
- List[VectorDBRecord]: A list of VectorDBRecord instances.
+ List[Any]: A list of converted database record instances.
"""
db_records = []
for record in records:
@@ -231,7 +249,7 @@ class TiDBStorage(BaseVectorStorage):
Args:
records (List[VectorRecord]): List of vectors to be added.
- **kwargs (Any): Additional keyword arguments pass to insert.
+ **kwargs (Any): Additional keyword arguments passed to insert.
Raises:
RuntimeError: If there was an error in the addition process.
@@ -330,6 +348,6 @@ class TiDBStorage(BaseVectorStorage):
r"""Provides direct access to the TiDB client.
Returns:
- Any: The TiDB client instance.
+ TiDBClient: The TiDB client instance.
"""
return self._client
diff --git a/camel/storages/vectordb_storages/weaviate.py b/camel/storages/vectordb_storages/weaviate.py
index 2c1b1408d..6c206886d 100644
--- a/camel/storages/vectordb_storages/weaviate.py
+++ b/camel/storages/vectordb_storages/weaviate.py
@@ -228,7 +228,14 @@ class WeaviateStorage(BaseVectorStorage):
self._check_and_create_collection(**kwargs)
def _get_connection_client(self) -> "WeaviateClient":
- r"""Get Weaviate client based on connection type and user settings."""
+ r"""Get Weaviate client based on connection type and user settings.
+
+ Returns:
+ WeaviateClient: The created Weaviate client instance.
+
+ Raises:
+ Exception: If creating the client fails.
+ """
import weaviate
# Map connection types to handler methods
@@ -251,7 +258,17 @@ class WeaviateStorage(BaseVectorStorage):
raise
def _create_cloud_client(self, weaviate_module: Any) -> "WeaviateClient":
- r"""Create a Weaviate Cloud client."""
+ r"""Create a Weaviate Cloud client.
+
+ Args:
+ weaviate_module (Any): The imported weaviate package module.
+
+ Returns:
+ WeaviateClient: Connected Weaviate Cloud client.
+
+ Raises:
+ ValueError: If cluster URL or API key is missing.
+ """
cluster_url = self._connection_params.get('wcd_cluster_url')
api_key = self._connection_params.get('wcd_api_key')
@@ -273,7 +290,14 @@ class WeaviateStorage(BaseVectorStorage):
)
def _create_local_client(self, weaviate_module: Any) -> "WeaviateClient":
- r"""Create a local Weaviate client."""
+ r"""Create a local Weaviate client.
+
+ Args:
+ weaviate_module (Any): The imported weaviate package module.
+
+ Returns:
+ WeaviateClient: Connected local Weaviate client.
+ """
return weaviate_module.connect_to_local(
host=self._connection_params.get('local_host', 'localhost'),
port=self._connection_params.get('local_port', 8080),
@@ -291,7 +315,14 @@ class WeaviateStorage(BaseVectorStorage):
def _create_embedded_client(
self, weaviate_module: Any
) -> "WeaviateClient":
- r"""Create an embedded Weaviate client."""
+ r"""Create an embedded Weaviate client.
+
+ Args:
+ weaviate_module (Any): The imported weaviate package module.
+
+ Returns:
+ WeaviateClient: Connected embedded Weaviate client.
+ """
embedded_kwargs = {
'hostname': self._connection_params.get(
'embedded_hostname', '127.0.0.1'
@@ -333,7 +364,17 @@ class WeaviateStorage(BaseVectorStorage):
return weaviate_module.connect_to_embedded(**embedded_kwargs)
def _create_custom_client(self, weaviate_module: Any) -> "WeaviateClient":
- r"""Create a custom Weaviate client."""
+ r"""Create a custom Weaviate client.
+
+ Args:
+ weaviate_module (Any): The imported weaviate package module.
+
+ Returns:
+ WeaviateClient: Connected custom Weaviate client.
+
+ Raises:
+ ValueError: If any required custom connection parameter is missing.
+ """
# Validate required custom parameters
required_params = [
'custom_http_host',
@@ -381,7 +422,11 @@ class WeaviateStorage(BaseVectorStorage):
logger.info("Explicitly closed Weaviate client connection")
def _generate_collection_name(self) -> str:
- r"""Generate a collection name if user doesn't provide one."""
+ r"""Generate a collection name if user doesn't provide one.
+
+ Returns:
+ str: Generated collection name.
+ """
timestamp = datetime.now().isoformat()
# Weaviate collection names must start with uppercase and be valid
# GraphQL names
@@ -389,12 +434,24 @@ class WeaviateStorage(BaseVectorStorage):
return valid_name
def _check_and_create_collection(self, **kwargs: Any) -> None:
- r"""Check if collection exists and create if it doesn't."""
+ r"""Check if collection exists and create if it doesn't.
+
+ Args:
+ **kwargs (Any): Additional keyword arguments for collection
+ creation.
+ """
if not self._collection_exists(self.collection_name):
self._create_collection(**kwargs)
def _collection_exists(self, collection_name: str) -> bool:
- r"""Check if the collection exists."""
+ r"""Check if the collection exists.
+
+ Args:
+ collection_name (str): Name of the collection to check.
+
+ Returns:
+ bool: True if collection exists, False otherwise.
+ """
try:
collection = self._client.collections.get(collection_name)
collection.config.get()
@@ -403,7 +460,14 @@ class WeaviateStorage(BaseVectorStorage):
return False
def _get_vector_index_config(self, **kwargs: Any) -> Any:
- r"""Get vector index configuration based on user settings."""
+ r"""Get vector index configuration based on user settings.
+
+ Args:
+ **kwargs (Any): Additional keyword arguments for vector index.
+
+ Returns:
+ Any: The configured vector index configuration object.
+ """
import weaviate.classes.config as wvc
# Map distance metrics - type safety guaranteed by Literal
@@ -431,7 +495,12 @@ class WeaviateStorage(BaseVectorStorage):
)
def _create_collection(self, **kwargs: Any) -> None:
- r"""Create a new collection in Weaviate."""
+ r"""Create a new collection in Weaviate.
+
+ Args:
+ **kwargs (Any): Additional keyword arguments for creating
+ collection.
+ """
import weaviate.classes.config as wvc
# Separate vector index kwargs from general kwargs to avoid conflicts
@@ -627,6 +696,9 @@ class WeaviateStorage(BaseVectorStorage):
Returns:
List[VectorDBQueryResult]: A list of vectors retrieved from the
storage based on similarity to the query vector.
+
+ Raises:
+ RuntimeError: If querying vectors fails.
"""
from weaviate.classes.query import MetadataQuery
@@ -695,7 +767,11 @@ class WeaviateStorage(BaseVectorStorage):
raise RuntimeError(f"Failed to query vectors from Weaviate: {e}")
def clear(self) -> None:
- r"""Remove all vectors from the storage."""
+ r"""Remove all vectors from the storage.
+
+ Raises:
+ RuntimeError: If clearing collection fails.
+ """
try:
self._client.collections.delete(self.collection_name)
self._create_collection(**self._original_collection_kwargs)
@@ -710,5 +786,9 @@ class WeaviateStorage(BaseVectorStorage):
@property
def client(self) -> "WeaviateClient":
- r"""Provides access to the underlying vector database client."""
+ r"""Provides access to the underlying vector database client.
+
+ Returns:
+ WeaviateClient: The underlying Weaviate client instance.
+ """
return self._client