hammad-python 0.0.18__py3-none-any.whl → 0.0.20__py3-none-any.whl

hammad/data/collections/indexes/qdrant/settings.py

@@ -18,7 +18,7 @@ __all__ = (
 DistanceMetric = Literal[
     "cosine",
     "dot",
-    "euclidean", 
+    "euclidean",
     "manhattan",
 ]
 
@@ -30,28 +30,28 @@ class QdrantCollectionIndexSettings:
 
     vector_size: int = 768
     """The size/dimension of the vectors to store."""
-    
+
     distance_metric: DistanceMetric = "dot"
     """Distance metric for similarity search."""
-    
+
     path: Optional[str] = None
     """Path for local Qdrant storage (None = in-memory)."""
-    
+
     host: Optional[str] = None
     """Qdrant server host (if using remote server)."""
-    
+
     port: int = 6333
     """Qdrant server port."""
-    
+
     grpc_port: int = 6334
     """Qdrant gRPC port."""
-    
+
     prefer_grpc: bool = False
     """Whether to prefer gRPC over HTTP."""
-    
+
     api_key: Optional[str] = None
     """API key for Qdrant authentication."""
-    
+
     timeout: Optional[float] = None
     """Request timeout for Qdrant operations."""
 
@@ -59,7 +59,7 @@ class QdrantCollectionIndexSettings:
         """Returns a configuration dictionary used
         to configure the qdrant client internally."""
         config = {}
-        
+
         if self.path is not None:
             config["path"] = self.path
         elif self.host is not None:
@@ -74,7 +74,7 @@ class QdrantCollectionIndexSettings:
         else:
             # In-memory database
             config["location"] = ":memory:"
-            
+
         return config
 
 
@@ -86,9 +86,9 @@ class QdrantCollectionIndexQuerySettings:
 
     limit: int = 10
     """The maximum number of results to return."""
-    
+
     score_threshold: Optional[float] = None
     """Minimum similarity score threshold for results."""
-    
+
     exact: bool = False
-    """Whether to use exact search (slower but more accurate)."""
+    """Whether to use exact search (slower but more accurate)."""

hammad/data/collections/indexes/qdrant/utils.py

@@ -1,14 +1,7 @@
 """hammad.data.collections.indexes.qdrant.utils"""
 
 from dataclasses import dataclass
-from typing import (
-    Any,
-    Dict,
-    List,
-    Optional,
-    Union,
-    final
-)
+from typing import Any, Dict, List, Optional, Union, final
 import uuid
 
 from .....cache import cached
@@ -21,6 +14,7 @@ from .settings import (
 # Lazy imports to avoid errors when qdrant is not installed
 try:
     import numpy as np
+
     NUMPY_AVAILABLE = True
 except ImportError:
     NUMPY_AVAILABLE = False
@@ -42,10 +36,10 @@ class QdrantCollectionIndexError(Exception):
 @dataclass
 class QdrantClientWrapper:
     """Wrapper over the qdrant client and collection setup."""
-    
+
     client: Any
     """The qdrant client object."""
-    
+
     collection_name: str
     """The name of the qdrant collection."""
 
@@ -55,14 +49,14 @@ def convert_distance_metric(metric: DistanceMetric) -> Any:
     """Convert string distance metric to qdrant Distance enum."""
     try:
         from qdrant_client.models import Distance
-        
+
         mapping = {
             "cosine": Distance.COSINE,
             "dot": Distance.DOT,
             "euclidean": Distance.EUCLID,
             "manhattan": Distance.MANHATTAN,
         }
-        
+
         return mapping.get(metric, Distance.DOT)
     except ImportError:
         raise QdrantCollectionIndexError(
@@ -71,7 +65,7 @@ def convert_distance_metric(metric: DistanceMetric) -> Any:
         )
 
 
-@cached 
+@cached
 def create_qdrant_client(settings: QdrantCollectionIndexSettings) -> Any:
     """Create a qdrant client from settings."""
     try:
@@ -81,9 +75,9 @@ def create_qdrant_client(settings: QdrantCollectionIndexSettings) -> Any:
             "qdrant-client is required for QdrantCollectionIndex. "
             "Install with: pip install qdrant-client"
         )
-    
+
     config = settings.get_qdrant_config()
-    
+
     if "path" in config:
         # Local persistent storage
         return QdrantClient(path=config["path"])
@@ -95,12 +89,12 @@ def create_qdrant_client(settings: QdrantCollectionIndexSettings) -> Any:
             "grpc_port": config.get("grpc_port", 6334),
             "prefer_grpc": config.get("prefer_grpc", False),
         }
-        
+
         if config.get("api_key"):
             client_kwargs["api_key"] = config["api_key"]
         if config.get("timeout"):
             client_kwargs["timeout"] = config["timeout"]
-            
+
         return QdrantClient(**client_kwargs)
     else:
         # In-memory database
@@ -112,47 +106,43 @@ def prepare_vector(
     expected_size: int,
 ) -> List[float]:
     """Prepare and validate a vector for qdrant storage."""
-    if NUMPY_AVAILABLE and hasattr(vector, 'tolist'):
+    if NUMPY_AVAILABLE and hasattr(vector, "tolist"):
         # Handle numpy arrays
         vector = vector.tolist()
     elif not isinstance(vector, list):
         raise QdrantCollectionIndexError(
             f"Vector must be a list or numpy array, got {type(vector)}"
         )
-    
+
     if len(vector) != expected_size:
         raise QdrantCollectionIndexError(
             f"Vector size {len(vector)} doesn't match expected size {expected_size}"
         )
-    
+
     # Ensure all elements are floats
     try:
         return [float(x) for x in vector]
     except (TypeError, ValueError) as e:
-        raise QdrantCollectionIndexError(
-            f"Vector contains non-numeric values: {e}"
-        )
+        raise QdrantCollectionIndexError(f"Vector contains non-numeric values: {e}")
 
 
 def build_qdrant_filter(filters: Optional[Dict[str, Any]]) -> Optional[Any]:
     """Build qdrant filter from filters dict."""
     if not filters:
         return None
-    
+
     try:
         from qdrant_client.models import Filter, FieldCondition, MatchValue
-        
+
         conditions = []
         for key, value in filters.items():
-            conditions.append(
-                FieldCondition(key=key, match=MatchValue(value=value))
-            )
-        
+            conditions.append(FieldCondition(key=key, match=MatchValue(value=value)))
+
         if len(conditions) == 1:
             return Filter(must=[conditions[0]])
         else:
             return Filter(must=conditions)
-            
+
     except ImportError:
         raise QdrantCollectionIndexError(
             "qdrant-client is required for QdrantCollectionIndex. "
@@ -168,27 +158,26 @@ def create_collection_if_not_exists(
     """Create qdrant collection if it doesn't exist."""
     try:
         from qdrant_client.models import VectorParams
-        
+
         # Check if collection exists
         try:
             collections = client.get_collections()
             collection_names = [col.name for col in collections.collections]
-            
+
             if collection_name not in collection_names:
                 # Create collection
                 distance_metric = convert_distance_metric(settings.distance_metric)
-                
+
                 client.create_collection(
                     collection_name=collection_name,
                     vectors_config=VectorParams(
-                        size=settings.vector_size,
-                        distance=distance_metric
+                        size=settings.vector_size, distance=distance_metric
                     ),
                 )
         except Exception:
             # Collection might already exist or other issue
             pass
-            
+
     except ImportError:
         raise QdrantCollectionIndexError(
             "qdrant-client is required for QdrantCollectionIndex. "
@@ -201,11 +190,12 @@ def serialize(obj: Any) -> Any:
     """Serialize an object to JSON-compatible format."""
     try:
         from msgspec import json
+
         return json.decode(json.encode(obj))
     except Exception:
         # Fallback to manual serialization if msgspec fails
         from dataclasses import is_dataclass, asdict
-        
+
         if isinstance(obj, (str, int, float, bool, type(None))):
             return obj
         elif isinstance(obj, (list, tuple)):
@@ -217,4 +207,4 @@ def serialize(obj: Any) -> Any:
         elif hasattr(obj, "__dict__"):
             return serialize(obj.__dict__)
         else:
-            return str(obj)
+            return str(obj)

hammad/data/collections/indexes/tantivy/__init__.py

@@ -1 +1 @@
-"""hammad.data.collections.indexes.tantivy"""
+"""hammad.data.collections.indexes.tantivy"""

hammad/data/collections/indexes/tantivy/index.py

@@ -1,15 +1,7 @@
 """hammad.data.collections.indexes.tantivy.index"""
 
 from datetime import datetime, timezone, timedelta
-from typing import (
-    Any,
-    Dict,
-    Generic,
-    List,
-    Optional,
-    Type,
-    final
-)
+from typing import Any, Dict, Generic, List, Optional, Type, final
 import uuid
 from pathlib import Path
 import json
@@ -25,7 +17,7 @@ from ....sql.database import Database
 from . import utils
 from .settings import (
     TantivyCollectionIndexSettings,
-    TantivyCollectionIndexQuerySettings
+    TantivyCollectionIndexQuerySettings,
 )
 
 
@@ -35,7 +27,7 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
     storage / search engine for a collection, that implements
     fast indexing & querying capabilities using the
     `tantivy` package.
-    
+
     This collection index is built into the core dependencies
     of the `hammad-python` package, and is the default index
     used by the `Collection` class."""
@@ -52,15 +44,15 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         query_settings: Optional[TantivyCollectionIndexQuerySettings] = None,
     ) -> None:
         """Initialize a new `TantivyCollectionIndex` with a given set
-        of parameters. 
-        
+        of parameters.
+
         Args:
             name: The name of the index.
             schema: The schema of the items that can be stored
                 within this index.
             ttl: The time to live for the items within this index.
             path: The path to the directory where the index will be stored.
-                (If not provided, the collection will be built on memory. This is how to 
+                (If not provided, the collection will be built on memory. This is how to
                 distinguish between different collection locations.)
             fast: Whether to use fast schema building & indexing
                 from `tantivy`'s builtin implementation.
@@ -106,13 +98,13 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         database_path = None
         if self.path is not None:
             database_path = self.path / f"{name}.db"
-        
+
         self._database = Database[DatabaseItemType](
             name=name,
             schema=schema,
             ttl=ttl,
             path=database_path,
-            table_name=f"tantivy_{name}"
+            table_name=f"tantivy_{name}",
         )
 
         try:
@@ -136,13 +128,13 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         ttl: Optional[int] = None,
     ) -> str:
         """Add a new item to the index.
-        
+
         Args:
             item: The item to add to the index.
             id: The id of the item.
             filters: The filters to apply to the item.
             ttl: The time to live for the item.
-            
+
         Returns:
             The ID of the added item.
         """
@@ -153,10 +145,10 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
             filters=filters,
             ttl=ttl,
         )
-        
+
         # Add to tantivy index for search
         self._add_to_tantivy_index(item_id, item, filters)
-        
+
         return item_id
 
     def _add_to_tantivy_index(
@@ -167,37 +159,41 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
     ) -> None:
         """Add item to tantivy search index."""
         doc = tantivy.Document()
-        
+
         # Add ID field
         doc.add_text("id", item_id)
-        
+
         # Extract and add content for search
         content = utils.extract_content_for_indexing(item)
         doc.add_text("content", content)
-        
+
         # Add title field if present
         if isinstance(item, dict) and "title" in item:
             doc.add_text("title", str(item["title"]))
-        
+
         # Store the full data as JSON in tantivy
         serialized_data = utils.serialize(item)
         json_data = {"value": serialized_data}
         doc.add_json("data", json.dumps(json_data))
-        
+
         # Add filters as facets
         if filters:
             for key, value in filters.items():
                 facet_value = f"/{key}/{value}"
                 doc.add_facet("filters", tantivy.Facet.from_string(facet_value))
-        
+
         # Add timestamps
         now = datetime.now(timezone.utc)
         doc.add_date("created_at", now)
-        
+
         # Add score field if present
-        if isinstance(item, dict) and "score" in item and isinstance(item["score"], (int, float)):
+        if (
+            isinstance(item, dict)
+            and "score" in item
+            and isinstance(item["score"], (int, float))
+        ):
             doc.add_integer("score", int(item["score"]))
-        
+
         # Add to index
         self._writer.add_document(doc)
         self._writer.commit()
@@ -209,11 +205,11 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         filters: Optional[DatabaseItemFilters] = None,
     ) -> Optional[DatabaseItem[DatabaseItemType]]:
         """Get an item by ID.
-        
+
         Args:
             id: The item ID.
             filters: Optional filters to match.
-            
+
         Returns:
             The database item or None if not found.
         """
@@ -236,7 +232,7 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         ascending: bool = True,
     ) -> List[DatabaseItem[DatabaseItemType]]:
         """Query items using tantivy search.
-        
+
         Args:
             query: Search query string.
             filters: Dictionary of filters to apply.
@@ -250,7 +246,7 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
             min_score: Minimum relevance score threshold.
             sort_by: Field to sort by.
             ascending: Sort direction.
-            
+
         Returns:
             List of matching database items.
         """
@@ -262,14 +258,14 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
                 order_by=sort_by,
                 ascending=ascending,
             )
-        
+
         # Use tantivy for search
         self._index.reload()
         searcher = self._index.searcher()
-        
+
         # Build tantivy query
         query_parts = []
-        
+
         # Add filter queries
         if filters:
             for key, value in filters.items():
@@ -279,7 +275,7 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
                     tantivy.Facet.from_string(f"/{key}/{value}"),
                 )
                 query_parts.append((tantivy.Occur.Must, facet_query))
-        
+
         # Add search query
         if phrase:
             words = query.split()
@@ -292,7 +288,7 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
             for term in terms:
                 fuzzy_q = tantivy.Query.fuzzy_term_query(
                     self._schema,
-                    "content", 
+                    "content",
                     term,
                     distance=fuzzy_distance,
                 )
@@ -310,63 +306,63 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
                 search_query = self._index.parse_query(
                     query, default_field_names=["content", "title"]
                 )
-        
+
         query_parts.append((tantivy.Occur.Must, search_query))
-        
+
         # Build final query
         if query_parts:
             final_query = tantivy.Query.boolean_query(query_parts)
         else:
             final_query = tantivy.Query.all_query()
-        
+
         # Execute search
         search_limit = limit or self.query_settings.limit
-        
+
         # Perform search
         search_result = searcher.search(
             final_query,
             limit=search_limit,
             offset=offset,
         )
-        
+
         # Get IDs from search results and fetch from database
         item_ids = []
         for score, doc_address in search_result.hits:
             if min_score and score < min_score:
                 continue
-                
+
             doc = searcher.doc(doc_address)
             item_id = doc.get_first("id")
             if item_id:
                 item_ids.append(item_id)
-        
+
         # Fetch items from database by IDs
         results = []
         for item_id in item_ids:
             db_item = self._database.get(item_id, filters=filters)
             if db_item:
                 results.append(db_item)
-                
+
         return results
 
     def delete(self, id: str) -> bool:
         """Delete an item by ID.
-        
+
         Args:
             id: The item ID.
-            
+
         Returns:
             True if item was deleted, False if not found.
         """
         # Delete from database
         deleted = self._database.delete(id)
-        
+
         if deleted:
             # Remove from tantivy index by reindexing without this item
             # Note: Tantivy doesn't have efficient single-document deletion
             # For now, we rely on the database as the source of truth
             pass
-            
+
         return deleted
 
     def count(
@@ -376,25 +372,27 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
         filters: Optional[DatabaseItemFilters] = None,
     ) -> int:
         """Count items matching the query and filters.
-        
+
         Args:
             query: Search query string.
             filters: Dictionary of filters to apply.
-            
+
         Returns:
             Number of matching items.
         """
         if not query:
             # Simple count from database
             from ....sql.types import QueryFilter, QueryCondition
-            
+
             query_filter = None
             if filters:
                 conditions = [
-                    QueryCondition(field="filters", operator="contains", value=json.dumps(filters))
+                    QueryCondition(
+                        field="filters", operator="contains", value=json.dumps(filters)
+                    )
                 ]
                 query_filter = QueryFilter(conditions=conditions)
-                
+
             return self._database.count(query_filter)
         else:
             # Count via search results
@@ -403,12 +401,12 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
 
     def clear(self) -> int:
         """Clear all items from the index.
-        
+
         Returns:
             Number of items deleted.
         """
         count = self._database.clear()
-        
+
         # Clear tantivy index by rebuilding it
         try:
             self._tantivy_wrapper = utils.build_tantivy_index_from_settings(
@@ -419,10 +417,10 @@ class TantivyCollectionIndex(Generic[DatabaseItemType]):
             self._writer = self._tantivy_wrapper.index_writer
         except Exception:
             pass
-            
+
         return count
 
     def __repr__(self) -> str:
         """String representation of the index."""
         location = str(self.path) if self.path else "memory"
-        return f"<TantivyCollectionIndex name='{self.name}' location='{location}'>"
+        return f"<TantivyCollectionIndex name='{self.name}' location='{location}'>"

hammad/data/collections/indexes/tantivy/settings.py

@@ -6,10 +6,7 @@ from typing import (
     Dict,
 )
 
-__all__ = (
-    "TantivyCollectionIndexSettings",
-    "TantivyCollectionIndexQuerySettings"
-)
+__all__ = ("TantivyCollectionIndexSettings", "TantivyCollectionIndexQuerySettings")
 
 
 @dataclass
@@ -17,7 +14,7 @@ class TantivyCollectionIndexSettings:
     """Object representation of user configurable settings
     that can be used to configure a `TantivyCollectionIndex`."""
 
-    fast : bool = True
+    fast: bool = True
     """Whether to use fast schema building & indexing from
     `tantivy`'s builtin implementation."""
 
@@ -26,18 +23,10 @@ class TantivyCollectionIndexSettings:
         to configure the tantivy index internally."""
 
         return {
-            "text_fields" : {
-                "stored" : True, "fast" : self.fast
-            },
-            "numeric_fields" : {
-                "stored" : True, "indexed" : True, "fast" : self.fast
-            },
-            "date_fields" : {
-                "stored" : True, "indexed" : True, "fast" : self.fast
-            },
-            "json_fields" : {
-                "stored" : True
-            }
+            "text_fields": {"stored": True, "fast": self.fast},
+            "numeric_fields": {"stored": True, "indexed": True, "fast": self.fast},
+            "date_fields": {"stored": True, "indexed": True, "fast": self.fast},
+            "json_fields": {"stored": True},
         }
 
 
@@ -47,5 +36,5 @@ class TantivyCollectionIndexQuerySettings:
     that can be used to configure the query engine for a
     `TantivyCollectionIndex`."""
 
-    limit : int = 10
-    """The maximum number of results to return."""
+    limit: int = 10
+    """The maximum number of results to return."""