agno 2.1.2__py3-none-any.whl → 2.3.13__py3-none-any.whl

agno/vectordb/base.py

@@ -1,11 +1,29 @@
 from abc import ABC, abstractmethod
 from typing import Any, Dict, List, Optional
 
+from agno.knowledge.document import Document
+from agno.utils.log import log_warning
+from agno.utils.string import generate_id
+
 
 class VectorDb(ABC):
     """Base class for Vector Databases"""
 
-    from agno.knowledge.document import Document
+    def __init__(self, *, id: Optional[str] = None, name: Optional[str] = None, description: Optional[str] = None):
+        """Initialize base VectorDb.
+
+        Args:
+            id: Optional custom ID. If not provided, an id will be generated.
+            name: Optional name for the vector database.
+            description: Optional description for the vector database.
+        """
+        if name is None:
+            name = self.__class__.__name__
+
+        self.name = name
+        self.description = description
+        # Last resort fallback to generate id from name if ID not specified
+        self.id = id if id else generate_id(name)
 
     @abstractmethod
     def create(self) -> None:
@@ -55,13 +73,11 @@ class VectorDb(ABC):
         raise NotImplementedError
 
     @abstractmethod
-    def search(self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+    def search(self, query: str, limit: int = 5, filters: Optional[Any] = None) -> List[Document]:
         raise NotImplementedError
 
     @abstractmethod
-    async def async_search(
-        self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None
-    ) -> List[Document]:
+    async def async_search(self, query: str, limit: int = 5, filters: Optional[Any] = None) -> List[Document]:
         raise NotImplementedError
 
     @abstractmethod
@@ -99,10 +115,26 @@ class VectorDb(ABC):
     def delete_by_metadata(self, metadata: Dict[str, Any]) -> bool:
         raise NotImplementedError
 
-    @abstractmethod
     def update_metadata(self, content_id: str, metadata: Dict[str, Any]) -> None:
-        raise NotImplementedError
+        """
+        Update the metadata for documents with the given content_id.
+
+        Default implementation logs a warning. Subclasses should override this method
+        to provide their specific implementation.
+
+        Args:
+            content_id (str): The content ID to update
+            metadata (Dict[str, Any]): The metadata to update
+        """
+        log_warning(
+            f"{self.__class__.__name__}.update_metadata() is not implemented. "
+            f"Metadata update for content_id '{content_id}' was skipped."
+        )
 
     @abstractmethod
     def delete_by_content_id(self, content_id: str) -> bool:
         raise NotImplementedError
+
+    @abstractmethod
+    def get_supported_search_types(self) -> List[str]:
+        raise NotImplementedError

agno/vectordb/cassandra/cassandra.py

@@ -1,9 +1,10 @@
 import asyncio
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Dict, Iterable, List, Optional, Union
 
+from agno.filters import FilterExpr
 from agno.knowledge.document import Document
 from agno.knowledge.embedder import Embedder
-from agno.utils.log import log_debug, log_error, log_info
+from agno.utils.log import log_debug, log_error, log_info, log_warning
 from agno.vectordb.base import VectorDb
 from agno.vectordb.cassandra.index import AgnoMetadataVectorCassandraTable
 
@@ -15,6 +16,8 @@ class Cassandra(VectorDb):
         keyspace: str,
         embedder: Optional[Embedder] = None,
         session=None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
     ) -> None:
         if not table_name:
             raise ValueError("Table name must be provided.")
@@ -30,6 +33,9 @@ class Cassandra(VectorDb):
 
             embedder = OpenAIEmbedder()
             log_info("Embedder not provided, using OpenAIEmbedder as default.")
+        # Initialize base class with name and description
+        super().__init__(name=name, description=description)
+
         self.table_name: str = table_name
         self.embedder: Embedder = embedder
         self.session = session
@@ -199,13 +205,17 @@ class Cassandra(VectorDb):
             self.delete_by_content_hash(content_hash)
         await self.async_insert(content_hash, documents, filters)
 
-    def search(self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+    def search(
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
+    ) -> List[Document]:
         """Keyword-based search on document metadata."""
         log_debug(f"Cassandra VectorDB : Performing Vector Search on {self.table_name} with query {query}")
+        if filters is not None:
+            log_warning("Filters are not yet supported in Cassandra. No filters will be applied.")
         return self.vector_search(query=query, limit=limit)
 
     async def async_search(
-        self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     ) -> List[Document]:
         """Search asynchronously by running in a thread."""
         return await asyncio.to_thread(self.search, query, limit, filters)
@@ -216,7 +226,9 @@ class Cassandra(VectorDb):
     ) -> List[Document]:
         return [self._row_to_document(row=hit) for hit in hits]
 
-    def vector_search(self, query: str, limit: int = 5) -> List[Document]:
+    def vector_search(
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
+    ) -> List[Document]:
         """Vector similarity search implementation."""
         query_embedding = self.embedder.get_embedding(query)
         hits = list(
@@ -483,3 +495,7 @@ class Cassandra(VectorDb):
         except Exception as e:
             log_error(f"Error updating metadata for content_id {content_id}: {e}")
             raise
+
+    def get_supported_search_types(self) -> List[str]:
+        """Get the supported search types for this vector database."""
+        return []  # Cassandra doesn't use SearchType enum

agno/vectordb/chroma/chromadb.py

@@ -13,10 +13,11 @@ try:
 except ImportError:
     raise ImportError("The `chromadb` package is not installed. Please install it via `pip install chromadb`.")
 
+from agno.filters import FilterExpr
 from agno.knowledge.document import Document
 from agno.knowledge.embedder import Embedder
 from agno.knowledge.reranker.base import Reranker
-from agno.utils.log import log_debug, log_error, log_info, logger
+from agno.utils.log import log_debug, log_error, log_info, log_warning, logger
 from agno.vectordb.base import VectorDb
 from agno.vectordb.distance import Distance
 
@@ -25,6 +26,9 @@ class ChromaDb(VectorDb):
     def __init__(
         self,
         collection: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        id: Optional[str] = None,
         embedder: Optional[Embedder] = None,
         distance: Distance = Distance.cosine,
         path: str = "tmp/chromadb",
@@ -32,9 +36,22 @@ class ChromaDb(VectorDb):
         reranker: Optional[Reranker] = None,
         **kwargs,
     ):
+        # Validate required parameters
+        if not collection:
+            raise ValueError("Collection name must be provided.")
+
+        # Dynamic ID generation based on unique identifiers
+        if id is None:
+            from agno.utils.string import generate_id
+
+            seed = f"{path}#{collection}"
+            id = generate_id(seed)
+
+        # Initialize base class with name, description, and generated ID
+        super().__init__(id=id, name=name, description=description)
+
         # Collection attributes
         self.collection_name: str = collection
-
         # Embedder for embedding the document contents
         if embedder is None:
             from agno.knowledge.embedder.openai import OpenAIEmbedder
@@ -259,7 +276,9 @@ class ChromaDb(VectorDb):
 
         for document in documents:
             cleaned_content = document.content.replace("\x00", "\ufffd")
-            doc_id = md5(cleaned_content.encode()).hexdigest()
+            # Include content_hash in ID to ensure uniqueness across different content hashes
+            base_id = document.id or md5(cleaned_content.encode()).hexdigest()
+            doc_id = md5(f"{base_id}_{content_hash}".encode()).hexdigest()
 
             # Handle metadata and filters
             metadata = document.meta_data or {}
@@ -418,7 +437,9 @@ class ChromaDb(VectorDb):
 
         for document in documents:
             cleaned_content = document.content.replace("\x00", "\ufffd")
-            doc_id = md5(cleaned_content.encode()).hexdigest()
+            # Include content_hash in ID to ensure uniqueness across different content hashes
+            base_id = document.id or md5(cleaned_content.encode()).hexdigest()
+            doc_id = md5(f"{base_id}_{content_hash}".encode()).hexdigest()
 
             # Handle metadata and filters
             metadata = document.meta_data or {}
@@ -461,13 +482,15 @@ class ChromaDb(VectorDb):
             logger.error(f"Error upserting documents by content hash: {e}")
             raise
 
-    def search(self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+    def search(
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
+    ) -> List[Document]:
         """Search the collection for a query.
 
         Args:
             query (str): Query to search for.
             limit (int): Number of results to return.
-            filters (Optional[Dict[str, Any]]): Filters to apply while searching.
+            filters (Optional[Union[Dict[str, Any], List[FilterExpr]]]): Filters to apply while searching.
                 Supports ChromaDB's filtering operators:
                 - $eq, $ne: Equality/Inequality
                 - $gt, $gte, $lt, $lte: Numeric comparisons
@@ -476,6 +499,9 @@ class ChromaDb(VectorDb):
         Returns:
             List[Document]: List of search results.
         """
+        if isinstance(filters, list):
+            log_warning("Filter Expressions are not yet supported in ChromaDB. No filters will be applied.")
+            filters = None
         query_embedding = self.embedder.get_embedding(query)
         if query_embedding is None:
             logger.error(f"Error getting embedding for Query: {query}")
@@ -497,11 +523,11 @@ class ChromaDb(VectorDb):
         # Build search results
         search_results: List[Document] = []
 
-        ids_list = result.get("ids", [[]])
-        metadata_list = result.get("metadatas", [[{}]])
-        documents_list = result.get("documents", [[]])
-        embeddings_list = result.get("embeddings")
-        distances_list = result.get("distances", [[]])
+        ids_list = result.get("ids", [[]])  # type: ignore
+        metadata_list = result.get("metadatas", [[{}]])  # type: ignore
+        documents_list = result.get("documents", [[]])  # type: ignore
+        embeddings_list = result.get("embeddings")  # type: ignore
+        distances_list = result.get("distances", [[]])  # type: ignore
 
         if not ids_list or not metadata_list or not documents_list or embeddings_list is None or not distances_list:
             return search_results
@@ -590,7 +616,7 @@ class ChromaDb(VectorDb):
         return converted
 
     async def async_search(
-        self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     ) -> List[Document]:
         """Search asynchronously by running in a thread."""
         return await asyncio.to_thread(self.search, query, limit, filters)
@@ -886,6 +912,7 @@ class ChromaDb(VectorDb):
 
                 # Convert to the expected type for ChromaDB
                 chroma_metadatas = cast(List[Mapping[str, Union[str, int, float, bool]]], updated_metadatas)
+                chroma_metadatas = [{k: v for k, v in m.items() if k and v} for m in chroma_metadatas]
                 collection.update(ids=ids, metadatas=chroma_metadatas)  # type: ignore
                 logger.debug(f"Updated metadata for {len(ids)} documents with content_id: {content_id}")
 
@@ -901,3 +928,7 @@ class ChromaDb(VectorDb):
         except Exception as e:
             logger.error(f"Error updating metadata for content_id '{content_id}': {e}")
             raise
+
+    def get_supported_search_types(self) -> List[str]:
+        """Get the supported search types for this vector database."""
+        return []  # ChromaDb doesn't use SearchType enum

agno/vectordb/clickhouse/clickhousedb.py

@@ -1,6 +1,6 @@
 import asyncio
 from hashlib import md5
-from typing import Any, Dict, List, Optional
+from typing import Any, Dict, List, Optional, Union
 
 from agno.vectordb.clickhouse.index import HNSW
 
@@ -11,9 +11,10 @@ try:
 except ImportError:
     raise ImportError("`clickhouse-connect` not installed. Use `pip install clickhouse-connect` to install it")
 
+from agno.filters import FilterExpr
 from agno.knowledge.document import Document
 from agno.knowledge.embedder import Embedder
-from agno.utils.log import log_debug, log_info, logger
+from agno.utils.log import log_debug, log_info, log_warning, logger
 from agno.vectordb.base import VectorDb
 from agno.vectordb.distance import Distance
 
@@ -23,6 +24,8 @@ class Clickhouse(VectorDb):
         self,
         table_name: str,
         host: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
         username: Optional[str] = None,
         password: str = "",
         port: int = 0,
@@ -41,9 +44,11 @@ class Clickhouse(VectorDb):
         self.password = password
         self.port = port
         self.dsn = dsn
+        # Initialize base class with name and description
+        super().__init__(name=name, description=description)
+
         self.compress = compress
         self.database_name = database_name
-
         if not client:
             client = clickhouse_connect.get_client(
                 host=self.host,
@@ -444,7 +449,11 @@ class Clickhouse(VectorDb):
             parameters=parameters,
         )
 
-    def search(self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+    def search(
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
+    ) -> List[Document]:
+        if filters is not None:
+            log_warning("Filters are not yet supported in Clickhouse. No filters will be applied.")
         query_embedding = self.embedder.get_embedding(query)
         if query_embedding is None:
             logger.error(f"Error getting embedding for Query: {query}")
@@ -498,11 +507,14 @@ class Clickhouse(VectorDb):
         return search_results
 
     async def async_search(
-        self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     ) -> List[Document]:
         """Search for documents asynchronously."""
         async_client = await self._ensure_async_client()
 
+        if filters is not None:
+            log_warning("Filters are not yet supported in Clickhouse. No filters will be applied.")
+
         query_embedding = self.embedder.get_embedding(query)
         if query_embedding is None:
             logger.error(f"Error getting embedding for Query: {query}")
@@ -817,3 +829,7 @@ class Clickhouse(VectorDb):
         except Exception as e:
             logger.error(f"Error updating metadata for content_id '{content_id}': {e}")
             raise
+
+    def get_supported_search_types(self) -> List[str]:
+        """Get the supported search types for this vector database."""
+        return []  # Clickhouse doesn't use SearchType enum

agno/vectordb/couchbase/couchbase.py

@@ -3,10 +3,10 @@ import time
 from datetime import timedelta
 from typing import Any, Dict, List, Optional, Union
 
+from agno.filters import FilterExpr
 from agno.knowledge.document import Document
 from agno.knowledge.embedder import Embedder
-from agno.knowledge.embedder.openai import OpenAIEmbedder
-from agno.utils.log import log_debug, log_info, logger
+from agno.utils.log import log_debug, log_info, log_warning, logger
 from agno.vectordb.base import VectorDb
 
 try:
@@ -61,11 +61,13 @@ class CouchbaseSearch(VectorDb):
         couchbase_connection_string: str,
         cluster_options: ClusterOptions,
         search_index: Union[str, SearchIndex],
-        embedder: Embedder = OpenAIEmbedder(),
+        embedder: Optional[Embedder] = None,
         overwrite: bool = False,
         is_global_level_index: bool = False,
         wait_until_index_ready: float = 0,
         batch_limit: int = 500,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
         **kwargs,
     ):
         """
@@ -75,6 +77,8 @@ class CouchbaseSearch(VectorDb):
             bucket_name (str): Name of the Couchbase bucket.
             scope_name (str): Name of the scope within the bucket.
             collection_name (str): Name of the collection within the scope.
+            name (Optional[str]): Name of the vector database.
+            description (Optional[str]): Description of the vector database.
             couchbase_connection_string (str): Couchbase connection string.
             cluster_options (ClusterOptions): Options for configuring the Couchbase cluster connection.
             search_index (Union[str, SearchIndex], optional): Search index configuration, either as index name or SearchIndex definition.
@@ -92,10 +96,18 @@ class CouchbaseSearch(VectorDb):
         self.collection_name = collection_name
         self.connection_string = couchbase_connection_string
         self.cluster_options = cluster_options
+        if embedder is None:
+            from agno.knowledge.embedder.openai import OpenAIEmbedder
+
+            embedder = OpenAIEmbedder()
+            log_info("Embedder not provided, using OpenAIEmbedder as default.")
         self.embedder = embedder
         self.overwrite = overwrite
         self.is_global_level_index = is_global_level_index
         self.wait_until_index_ready = wait_until_index_ready
+        # Initialize base class with name and description
+        super().__init__(name=name, description=description)
+
         self.kwargs = kwargs
         self.batch_limit = batch_limit
         if isinstance(search_index, str):
@@ -451,7 +463,12 @@ class CouchbaseSearch(VectorDb):
         if errors_occurred:
             logger.warning("Some errors occurred during the upsert operation. Please check logs for details.")
 
-    def search(self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None) -> List[Document]:
+    def search(
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
+    ) -> List[Document]:
+        if isinstance(filters, List):
+            log_warning("Filter Expressions are not yet supported in Couchbase. No filters will be applied.")
+            filters = None
         """Search the Couchbase bucket for documents relevant to the query."""
         query_embedding = self.embedder.get_embedding(query)
         if query_embedding is None:
@@ -1061,8 +1078,11 @@ class CouchbaseSearch(VectorDb):
         logger.info(f"[async] Total successfully upserted: {total_upserted_count}, Total failed: {total_failed_count}.")
 
     async def async_search(
-        self, query: str, limit: int = 5, filters: Optional[Dict[str, Any]] = None
+        self, query: str, limit: int = 5, filters: Optional[Union[Dict[str, Any], List[FilterExpr]]] = None
     ) -> List[Document]:
+        if isinstance(filters, List):
+            log_warning("Filter Expressions are not yet supported in Couchbase. No filters will be applied.")
+            filters = None
         query_embedding = self.embedder.get_embedding(query)
         if query_embedding is None:
             logger.error(f"[async] Failed to generate embedding for query: {query}")
@@ -1420,3 +1440,7 @@ class CouchbaseSearch(VectorDb):
         except Exception as e:
             logger.error(f"Error updating metadata for content_id '{content_id}': {e}")
             raise
+
+    def get_supported_search_types(self) -> List[str]:
+        """Get the supported search types for this vector database."""
+        return []  # CouchbaseSearch doesn't use SearchType enum