hammad-python 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

hammad/data/collections/collection.py

@@ -13,6 +13,7 @@ from typing import (
 from typing_extensions import TypedDict
 
 if TYPE_CHECKING:
+    from .base_collection import BaseCollection
     from .searchable_collection import SearchableCollection
     from .vector_collection import VectorCollection
 
@@ -58,6 +59,231 @@ class VectorCollectionSettings(TypedDict, total=False):
     timeout: Optional[float]
 
 
+class Collection:
+    """
+    A unified collection factory that creates the appropriate collection type
+    based on the provided parameters.
+
+    This class acts as a factory and doesn't contain its own logic - it simply
+    returns instances of SearchableCollection or VectorCollection based on the
+    type parameter.
+    """
+
+    @overload
+    def __new__(
+        cls,
+        type: Literal["searchable"],
+        name: str,
+        *,
+        schema: Optional[Any] = None,
+        default_ttl: Optional[int] = None,
+        storage_backend: Optional[Any] = None,
+        heap_size: Optional[int] = None,
+        num_threads: Optional[int] = None,
+        index_path: Optional[str] = None,
+        schema_builder: Optional[Any] = None,
+        writer_memory: Optional[int] = None,
+        reload_policy: Optional[str] = None,
+    ) -> "SearchableCollection": ...
+
+    @overload
+    def __new__(
+        cls,
+        type: Literal["vector"],
+        name: str,
+        vector_size: int,
+        *,
+        schema: Optional[Any] = None,
+        default_ttl: Optional[int] = None,
+        storage_backend: Optional[Any] = None,
+        distance_metric: Optional[Any] = None,
+        embedding_function: Optional[Callable[[Any], List[float]]] = None,
+        model: Optional[str] = None,
+        # Common embedding parameters
+        format: bool = False,
+        # LiteLLM parameters
+        dimensions: Optional[int] = None,
+        encoding_format: Optional[str] = None,
+        timeout: Optional[int] = None,
+        api_base: Optional[str] = None,
+        api_version: Optional[str] = None,
+        api_key: Optional[str] = None,
+        api_type: Optional[str] = None,
+        caching: bool = False,
+        user: Optional[str] = None,
+        # FastEmbed parameters
+        parallel: Optional[int] = None,
+        batch_size: Optional[int] = None,
+        # Qdrant parameters
+        path: Optional[str] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        grpc_port: Optional[int] = None,
+        prefer_grpc: Optional[bool] = None,
+        qdrant_timeout: Optional[float] = None,
+    ) -> "VectorCollection": ...
+
+    def __new__(
+        cls,
+        type: Literal["searchable", "vector"],
+        name: str,
+        vector_size: Optional[int] = None,
+        *,
+        schema: Optional[Any] = None,
+        default_ttl: Optional[int] = None,
+        storage_backend: Optional[Any] = None,
+        distance_metric: Optional[Any] = None,
+        embedding_function: Optional[Callable[[Any], List[float]]] = None,
+        model: Optional[str] = None,
+        # Common embedding parameters
+        format: bool = False,
+        # LiteLLM parameters
+        dimensions: Optional[int] = None,
+        encoding_format: Optional[str] = None,
+        timeout: Optional[int] = None,
+        api_base: Optional[str] = None,
+        api_version: Optional[str] = None,
+        api_key: Optional[str] = None,
+        api_type: Optional[str] = None,
+        caching: bool = False,
+        user: Optional[str] = None,
+        # FastEmbed parameters
+        parallel: Optional[int] = None,
+        batch_size: Optional[int] = None,
+        # Tantivy parameters (searchable collections only)
+        heap_size: Optional[int] = None,
+        num_threads: Optional[int] = None,
+        index_path: Optional[str] = None,
+        schema_builder: Optional[Any] = None,
+        writer_memory: Optional[int] = None,
+        reload_policy: Optional[str] = None,
+        # Qdrant parameters (vector collections only)
+        path: Optional[str] = None,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        grpc_port: Optional[int] = None,
+        prefer_grpc: Optional[bool] = None,
+        qdrant_timeout: Optional[float] = None,
+    ) -> "BaseCollection":
+        """
+        Create a collection of the specified type.
+
+        Args:
+            type: Type of collection to create ("searchable" or "vector")
+            name: Name of the collection
+            vector_size: Size of vectors (required for vector collections)
+            schema: Optional schema for type validation
+            default_ttl: Default TTL for items in seconds
+            storage_backend: Optional storage backend
+            distance_metric: Distance metric for similarity search (vector collections only)
+            embedding_function: Function to convert objects to vectors (vector collections only)
+
+            Tantivy parameters (searchable collections only):
+            heap_size: Memory allocation for tantivy heap
+            num_threads: Number of threads for tantivy operations
+            index_path: Path to store tantivy index files
+            schema_builder: Custom schema builder for tantivy
+            writer_memory: Memory allocation for tantivy writer
+            reload_policy: Policy for reloading tantivy index
+
+            Qdrant parameters (vector collections only):
+            path: Path for local Qdrant storage
+            host: Qdrant server host
+            port: Qdrant server port
+            grpc_port: Qdrant gRPC port
+            prefer_grpc: Whether to prefer gRPC over HTTP
+            api_key: API key for Qdrant authentication
+            timeout: Request timeout for Qdrant operations
+
+        Returns:
+            A SearchableCollection or VectorCollection instance
+        """
+        if type == "searchable":
+            from .searchable_collection import SearchableCollection
+
+            # Build tantivy config from individual parameters
+            tantivy_config = {}
+            if heap_size is not None:
+                tantivy_config["heap_size"] = heap_size
+            if num_threads is not None:
+                tantivy_config["num_threads"] = num_threads
+            if index_path is not None:
+                tantivy_config["index_path"] = index_path
+            if schema_builder is not None:
+                tantivy_config["schema_builder"] = schema_builder
+            if writer_memory is not None:
+                tantivy_config["writer_memory"] = writer_memory
+            if reload_policy is not None:
+                tantivy_config["reload_policy"] = reload_policy
+
+            return SearchableCollection(
+                name=name,
+                schema=schema,
+                default_ttl=default_ttl,
+                storage_backend=storage_backend,
+                tantivy_config=tantivy_config if tantivy_config else None,
+            )
+        elif type == "vector":
+            if vector_size is None:
+                raise ValueError("vector_size is required for vector collections")
+
+            try:
+                from .vector_collection import VectorCollection, Distance
+            except ImportError:
+                raise ImportError(
+                    "qdrant-client is required for vector collections. "
+                    "Please install it with 'pip install qdrant-client'."
+                )
+
+            # Set default distance metric if not provided and Distance is available
+            if distance_metric is None and Distance is not None:
+                distance_metric = Distance.DOT
+
+            # Build qdrant config from individual parameters
+            qdrant_config = {}
+            if path is not None:
+                qdrant_config["path"] = path
+            if host is not None:
+                qdrant_config["host"] = host
+            if port is not None:
+                qdrant_config["port"] = port
+            if grpc_port is not None:
+                qdrant_config["grpc_port"] = grpc_port
+            if prefer_grpc is not None:
+                qdrant_config["prefer_grpc"] = prefer_grpc
+            if qdrant_timeout is not None:
+                qdrant_config["timeout"] = qdrant_timeout
+
+            return VectorCollection(
+                name=name,
+                vector_size=vector_size,
+                schema=schema,
+                default_ttl=default_ttl,
+                storage_backend=storage_backend,
+                distance_metric=distance_metric,
+                qdrant_config=qdrant_config if qdrant_config else None,
+                embedding_function=embedding_function,
+                model=model,
+                # Common embedding parameters
+                format=format,
+                # LiteLLM parameters
+                dimensions=dimensions,
+                encoding_format=encoding_format,
+                timeout=timeout,
+                api_base=api_base,
+                api_version=api_version,
+                api_key=api_key,
+                api_type=api_type,
+                caching=caching,
+                user=user,
+                # FastEmbed parameters
+                parallel=parallel,
+                batch_size=batch_size,
+            )
+        else:
+            raise ValueError(f"Unsupported collection type: {type}")
+
+
 @overload
 def create_collection(
     type: Literal["searchable"],
@@ -86,13 +312,29 @@ def create_collection(
     storage_backend: Optional[Any] = None,
     distance_metric: Optional[Any] = None,
     embedding_function: Optional[Callable[[Any], List[float]]] = None,
+    model: Optional[str] = None,
+    # Common embedding parameters
+    format: bool = False,
+    # LiteLLM parameters
+    dimensions: Optional[int] = None,
+    encoding_format: Optional[str] = None,
+    timeout: Optional[int] = None,
+    api_base: Optional[str] = None,
+    api_version: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_type: Optional[str] = None,
+    caching: bool = False,
+    user: Optional[str] = None,
+    # FastEmbed parameters
+    parallel: Optional[int] = None,
+    batch_size: Optional[int] = None,
+    # Qdrant parameters
     path: Optional[str] = None,
     host: Optional[str] = None,
     port: Optional[int] = None,
     grpc_port: Optional[int] = None,
     prefer_grpc: Optional[bool] = None,
-    api_key: Optional[str] = None,
-    timeout: Optional[float] = None,
+    qdrant_timeout: Optional[float] = None,
 ) -> "VectorCollection": ...
 
 
@@ -106,6 +348,22 @@ def create_collection(
     storage_backend: Optional[Any] = None,
     distance_metric: Optional[Any] = None,
     embedding_function: Optional[Callable[[Any], List[float]]] = None,
+    model: Optional[str] = None,
+    # Common embedding parameters
+    format: bool = False,
+    # LiteLLM parameters
+    dimensions: Optional[int] = None,
+    encoding_format: Optional[str] = None,
+    timeout: Optional[int] = None,
+    api_base: Optional[str] = None,
+    api_version: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_type: Optional[str] = None,
+    caching: bool = False,
+    user: Optional[str] = None,
+    # FastEmbed parameters
+    parallel: Optional[int] = None,
+    batch_size: Optional[int] = None,
     # Tantivy parameters (searchable collections only)
     heap_size: Optional[int] = None,
     num_threads: Optional[int] = None,
@@ -119,12 +377,14 @@ def create_collection(
     port: Optional[int] = None,
     grpc_port: Optional[int] = None,
     prefer_grpc: Optional[bool] = None,
-    api_key: Optional[str] = None,
-    timeout: Optional[float] = None,
-) -> Union["SearchableCollection", "VectorCollection"]:
+    qdrant_timeout: Optional[float] = None,
+) -> "BaseCollection":
     """
     Create a collection of the specified type.
 
+    This function provides a factory pattern for creating collections.
+    Use the Collection class for a more object-oriented approach.
+
     Args:
         type: Type of collection to create ("searchable" or "vector")
         name: Name of the collection
@@ -155,73 +415,38 @@ def create_collection(
     Returns:
         A SearchableCollection or VectorCollection instance
     """
-    if type == "searchable":
-        from .searchable_collection import SearchableCollection
-
-        # Build tantivy config from individual parameters
-        tantivy_config = {}
-        if heap_size is not None:
-            tantivy_config["heap_size"] = heap_size
-        if num_threads is not None:
-            tantivy_config["num_threads"] = num_threads
-        if index_path is not None:
-            tantivy_config["index_path"] = index_path
-        if schema_builder is not None:
-            tantivy_config["schema_builder"] = schema_builder
-        if writer_memory is not None:
-            tantivy_config["writer_memory"] = writer_memory
-        if reload_policy is not None:
-            tantivy_config["reload_policy"] = reload_policy
-
-        return SearchableCollection(
-            name=name,
-            schema=schema,
-            default_ttl=default_ttl,
-            storage_backend=storage_backend,
-            tantivy_config=tantivy_config if tantivy_config else None,
-        )
-    elif type == "vector":
-        if vector_size is None:
-            raise ValueError("vector_size is required for vector collections")
-
-        try:
-            from .vector_collection import VectorCollection, Distance
-        except ImportError:
-            raise ImportError(
-                "qdrant-client is required for vector collections. "
-                "Please install it with 'pip install qdrant-client'."
-            )
-
-        # Set default distance metric if not provided and Distance is available
-        if distance_metric is None and Distance is not None:
-            distance_metric = Distance.DOT
-
-        # Build qdrant config from individual parameters
-        qdrant_config = {}
-        if path is not None:
-            qdrant_config["path"] = path
-        if host is not None:
-            qdrant_config["host"] = host
-        if port is not None:
-            qdrant_config["port"] = port
-        if grpc_port is not None:
-            qdrant_config["grpc_port"] = grpc_port
-        if prefer_grpc is not None:
-            qdrant_config["prefer_grpc"] = prefer_grpc
-        if api_key is not None:
-            qdrant_config["api_key"] = api_key
-        if timeout is not None:
-            qdrant_config["timeout"] = timeout
-
-        return VectorCollection(
-            name=name,
-            vector_size=vector_size,
-            schema=schema,
-            default_ttl=default_ttl,
-            storage_backend=storage_backend,
-            distance_metric=distance_metric,
-            qdrant_config=qdrant_config if qdrant_config else None,
-            embedding_function=embedding_function,
-        )
-    else:
-        raise ValueError(f"Unsupported collection type: {type}")
+    return Collection(
+        type=type,
+        name=name,
+        vector_size=vector_size,
+        schema=schema,
+        default_ttl=default_ttl,
+        storage_backend=storage_backend,
+        distance_metric=distance_metric,
+        embedding_function=embedding_function,
+        model=model,
+        format=format,
+        dimensions=dimensions,
+        encoding_format=encoding_format,
+        timeout=timeout,
+        api_base=api_base,
+        api_version=api_version,
+        api_key=api_key,
+        api_type=api_type,
+        caching=caching,
+        user=user,
+        parallel=parallel,
+        batch_size=batch_size,
+        heap_size=heap_size,
+        num_threads=num_threads,
+        index_path=index_path,
+        schema_builder=schema_builder,
+        writer_memory=writer_memory,
+        reload_policy=reload_policy,
+        path=path,
+        host=host,
+        port=port,
+        grpc_port=grpc_port,
+        prefer_grpc=prefer_grpc,
+        qdrant_timeout=qdrant_timeout,
+    )

hammad/data/collections/vector_collection.py

@@ -25,6 +25,16 @@ except ImportError as e:
     ) from e
 
 from .base_collection import BaseCollection, Object, Filters, Schema
+from ...ai.embeddings.create import (
+    create_embeddings,
+    async_create_embeddings,
+)
+from ...ai.embeddings.client.fastembed_text_embeddings_client import (
+    FastEmbedTextEmbeddingModel,
+)
+from ...ai.embeddings.client.litellm_embeddings_client import (
+    LiteLlmEmbeddingModel,
+)
 
 __all__ = ("VectorCollection",)
 
@@ -50,6 +60,22 @@ class VectorCollection(BaseCollection, Generic[Object]):
         distance_metric: Distance = Distance.DOT,
         qdrant_config: Optional[Dict[str, Any]] = None,
         embedding_function: Optional[Callable[[Any], List[float]]] = None,
+        model: Optional[str] = None,
+        # Common embedding parameters
+        format: bool = False,
+        # LiteLLM parameters
+        dimensions: Optional[int] = None,
+        encoding_format: Optional[str] = None,
+        timeout: Optional[int] = None,
+        api_base: Optional[str] = None,
+        api_version: Optional[str] = None,
+        api_key: Optional[str] = None,
+        api_type: Optional[str] = None,
+        caching: bool = False,
+        user: Optional[str] = None,
+        # FastEmbed parameters
+        parallel: Optional[int] = None,
+        batch_size: Optional[int] = None,
     ):
         """
         Initialize a vector collection.
@@ -71,6 +97,23 @@ class VectorCollection(BaseCollection, Generic[Object]):
                               "api_key": "your-api-key"
                           }
             embedding_function: Optional function to convert objects to vectors
+            model: Optional model name (e.g., 'fastembed/BAAI/bge-small-en-v1.5', 'openai/text-embedding-3-small')
+            format: Whether to format each non-string input as a markdown string
+
+            # LiteLLM-specific parameters:
+            dimensions: The dimensions of the embedding
+            encoding_format: The encoding format of the embedding (e.g. "float", "base64")
+            timeout: The timeout for the embedding request
+            api_base: The base URL for the embedding API
+            api_version: The version of the embedding API
+            api_key: The API key for the embedding API
+            api_type: The type of the embedding API
+            caching: Whether to cache the embedding
+            user: The user for the embedding
+
+            # FastEmbed-specific parameters:
+            parallel: The number of parallel processes to use for the embedding
+            batch_size: The batch size to use for the embedding
         """
         self.name = name
         self.vector_size = vector_size
@@ -79,6 +122,29 @@ class VectorCollection(BaseCollection, Generic[Object]):
         self.distance_metric = distance_metric
         self._storage_backend = storage_backend
         self._embedding_function = embedding_function
+        self._model = model
+
+        # Store embedding parameters
+        self._embedding_params = {
+            "format": format,
+            # LiteLLM parameters
+            "dimensions": dimensions,
+            "encoding_format": encoding_format,
+            "timeout": timeout,
+            "api_base": api_base,
+            "api_version": api_version,
+            "api_key": api_key,
+            "api_type": api_type,
+            "caching": caching,
+            "user": user,
+            # FastEmbed parameters
+            "parallel": parallel,
+            "batch_size": batch_size,
+        }
+
+        # If model is provided, create embedding function
+        if model:
+            self._embedding_function = self._create_embedding_function(model)
 
         # Store qdrant configuration
         self._qdrant_config = qdrant_config or {}
@@ -92,6 +158,28 @@ class VectorCollection(BaseCollection, Generic[Object]):
         # Initialize Qdrant client
         self._init_qdrant_client()
 
+    def _create_embedding_function(
+        self,
+        model_name: str,
+    ) -> Callable[[Any], List[float]]:
+        """Create an embedding function from a model name."""
+
+        def embedding_function(text: Any) -> List[float]:
+            if not isinstance(text, str):
+                text = str(text)
+
+            # Filter out None values from embedding parameters
+            embedding_kwargs = {
+                k: v for k, v in self._embedding_params.items() if v is not None
+            }
+            embedding_kwargs["model"] = model_name
+            embedding_kwargs["input"] = text
+
+            response = create_embeddings(**embedding_kwargs)
+            return response.data[0].embedding
+
+        return embedding_function
+
     def _init_qdrant_client(self):
         """Initialize the Qdrant client and collection."""
         config = self._qdrant_config
@@ -257,18 +345,28 @@ class VectorCollection(BaseCollection, Generic[Object]):
     def add(
         self,
         entry: Object,
-        *,
         id: Optional[str] = None,
+        *,
         filters: Optional[Filters] = None,
         ttl: Optional[int] = None,
-    ) -> None:
-        """Add an item to the collection."""
+    ) -> str:
+        """Add an item to the collection.
+
+        Args:
+            entry: The object/data to store
+            id: Optional ID for the item (will generate UUID if not provided)
+            filters: Optional metadata filters
+            ttl: Time-to-live in seconds
+
+        Returns:
+            The ID of the added item
+        """
         if self._storage_backend is not None:
             # Delegate to storage backend
             self._storage_backend.add(
                 entry, id=id, collection=self.name, filters=filters, ttl=ttl
             )
-            return
+            return id or str(uuid.uuid4())
 
         # Independent operation
         item_id = id or str(uuid.uuid4())
@@ -313,24 +411,32 @@ class VectorCollection(BaseCollection, Generic[Object]):
 
         self._client.upsert(collection_name=self.name, points=[point])
 
+        return item_id
+
     def query(
         self,
+        query: Optional[str] = None,
         *,
         filters: Optional[Filters] = None,
-        search: Optional[str] = None,
         limit: Optional[int] = None,
     ) -> List[Object]:
-        """Query items from the collection."""
+        """Query items from the collection.
+
+        Args:
+            query: Search query string. If provided, performs semantic similarity search.
+            filters: Optional filters to apply
+            limit: Maximum number of results to return
+        """
         if self._storage_backend is not None:
             return self._storage_backend.query(
                 collection=self.name,
                 filters=filters,
-                search=search,
+                search=query,
                 limit=limit,
             )
 
         # For basic query without vector search, just return all items with filters
-        if search is None:
+        if query is None:
             return self._query_all(filters=filters, limit=limit)
 
         # If search is provided but no embedding function, treat as error
@@ -341,7 +447,7 @@ class VectorCollection(BaseCollection, Generic[Object]):
             )
 
         # Convert search to vector and perform similarity search
-        query_vector = self._embedding_function(search)
+        query_vector = self._embedding_function(query)
         return self.vector_search(
             query_vector=query_vector, filters=filters, limit=limit
         )
@@ -386,7 +492,7 @@ class VectorCollection(BaseCollection, Generic[Object]):
         query_vector: Union[List[float], np.ndarray],
         *,
         filters: Optional[Filters] = None,
-        limit: Optional[int] = None,
+        limit: int = 10,
         score_threshold: Optional[float] = None,
     ) -> List[Object]:
         """
@@ -395,7 +501,7 @@ class VectorCollection(BaseCollection, Generic[Object]):
         Args:
             query_vector: Query vector for similarity search
             filters: Optional filters to apply
-            limit: Maximum number of results to return
+            limit: Maximum number of results to return (default: 10)
             score_threshold: Minimum similarity score threshold
 
         Returns:
@@ -414,7 +520,7 @@ class VectorCollection(BaseCollection, Generic[Object]):
                 collection_name=self.name,
                 query=query_vector,
                 query_filter=self._build_qdrant_filter(filters),
-                limit=limit or 10,
+                limit=limit,
                 score_threshold=score_threshold,
                 with_payload=True,
                 with_vectors=False,

hammad/data/databases/__init__.py

@@ -1,7 +1,7 @@
 """hammad.data.databases"""
 
 from typing import TYPE_CHECKING
-from ...based.utils import auto_create_lazy_loader
+from ..._core._utils._import_utils import _auto_create_getattr_loader
 
 if TYPE_CHECKING:
     from .database import Database, create_database
@@ -13,7 +13,7 @@ __all__ = (
 )
 
 
-__getattr__ = auto_create_lazy_loader(__all__)
+__getattr__ = _auto_create_getattr_loader(__all__)
 
 
 def __dir__() -> list[str]: