🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
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.pyindex 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 metadataor 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 thequery 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 retrievedfrom 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.pyindex 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 validationdef _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):raisedef _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 clientdef _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 clientdef _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 clientdef _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._collectiondiff --git a/camel/storages/vectordb_storages/faiss.py b/camel/storages/vectordb_storages/faiss.pyindex 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 faissimport 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):@propertydef 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_clientdef _matches_filter(diff --git a/camel/storages/vectordb_storages/milvus.py b/camel/storages/vectordb_storages/milvus.pyindex 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 isoformat. (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 theMilvus 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 itif 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 createcollection."""@@ -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.pyindex 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):@propertydef 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._clientdiff --git a/camel/storages/vectordb_storages/pgvector.py b/camel/storages/vectordb_storages/pgvector.pyindex 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 psycopgfrom 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 toadd 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 bysimilarity.++ 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):raisedef _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):raisedef 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, Identifierdiff --git a/camel/storages/vectordb_storages/qdrant.py b/camel/storages/vectordb_storages/qdrant.pyindex 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_deldef __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 1if 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 Truereturn Falsedef _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):@propertydef 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._clientdiff --git a/camel/storages/vectordb_storages/surreal.py b/camel/storages/vectordb_storages/surreal.pyindex 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 vectordimension. 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 vectorand top_k value.+ **kwargs (Any): Additional keyword arguments.Returns:List[VectorDBQueryResult]: Ranked list of matching records@@ -276,7 +268,14 @@ class SurrealStorage(BaseVectorStorage):return resultsdef _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 loadingraise NotImplementedError("SurrealDB does not support loading")@propertydef 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_clientdiff --git a/camel/storages/vectordb_storages/tidb.py b/camel/storages/vectordb_storages/tidb.pyindex 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 tuplecontaining the database url and API key for connecting to a TiDBcluster. 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 forinterface 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 notprovided, set it to the current time with iso format.+ (default: :obj:`None`)**kwargs (Any): Additional keyword arguments for initializingTiDB connection.@@ -97,7 +98,8 @@ class TiDBStorage(BaseVectorStorage):Args:database_url (Optional[str]): The database connection string forthe 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 vectordimensionality.++ 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._clientdiff --git a/camel/storages/vectordb_storages/weaviate.py b/camel/storages/vectordb_storages/weaviate.pyindex 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):raisedef _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 parametersrequired_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_namedef _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 Falsedef _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 thestorage 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):@propertydef 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