endee 0.1.7__tar.gz → 0.1.9__tar.gz

{endee-0.1.7 → endee-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: endee
-Version: 0.1.7
+Version: 0.1.9
 Summary: Endee is the Next-Generation Vector Database for Scalable, High-Performance AI
 Home-page: https://endee.io
 Author: Endee Labs
@@ -29,6 +29,7 @@ Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: numpy>=2.2.4
 Requires-Dist: msgpack>=1.1.0
 Requires-Dist: orjson>=3.11.5
+Requires-Dist: pydantic>=2.0.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -602,6 +603,23 @@ index = client.get_index(name="your-index-name")
 index.delete_vector("vec1")
 ```
 
+### Filtered Deletion
+
+In cases where you don't know the exact vector `id`, but want to delete vectors based on filter fields, you can use filtered deletion. This is especially useful for:
+
+- Bulk deleting vectors by tag, type, or timestamp
+- Enforcing access control or data expiration policies
+
+```python
+from endee import Endee
+
+client = Endee(token="your-token-here")
+index = client.get_index(name="your-index-name")
+
+# Delete all vectors matching filter conditions
+index.delete_with_filter([{"tags": {"$eq": "important"}}])
+```
+
 ### Index Deletion
 
 Index deletion permanently removes the entire index and all vectors associated with it. This should be used when:
@@ -669,6 +687,7 @@ info = index.describe()
 | `upsert(input_array)` | Insert or update vectors (max 1000 per batch) |
 | `query(vector, top_k, filter, ef, include_vectors, sparse_indices, sparse_values)` | Search for similar vectors (sparse params optional for hybrid) |
 | `delete_vector(id)` | Delete a vector by ID |
+| `delete_with_filter(filter)` | Delete vectors matching a filter |
 | `get_vector(id)` | Get a specific vector by ID |
 | `describe()` | Get index statistics and configuration |
 

{endee-0.1.7 → endee-0.1.9}/README.md

@@ -558,6 +558,23 @@ index = client.get_index(name="your-index-name")
 index.delete_vector("vec1")
 ```
 
+### Filtered Deletion
+
+In cases where you don't know the exact vector `id`, but want to delete vectors based on filter fields, you can use filtered deletion. This is especially useful for:
+
+- Bulk deleting vectors by tag, type, or timestamp
+- Enforcing access control or data expiration policies
+
+```python
+from endee import Endee
+
+client = Endee(token="your-token-here")
+index = client.get_index(name="your-index-name")
+
+# Delete all vectors matching filter conditions
+index.delete_with_filter([{"tags": {"$eq": "important"}}])
+```
+
 ### Index Deletion
 
 Index deletion permanently removes the entire index and all vectors associated with it. This should be used when:
@@ -625,6 +642,7 @@ info = index.describe()
 | `upsert(input_array)` | Insert or update vectors (max 1000 per batch) |
 | `query(vector, top_k, filter, ef, include_vectors, sparse_indices, sparse_values)` | Search for similar vectors (sparse params optional for hybrid) |
 | `delete_vector(id)` | Delete a vector by ID |
+| `delete_with_filter(filter)` | Delete vectors matching a filter |
 | `get_vector(id)` | Get a specific vector by ID |
 | `describe()` | Get index statistics and configuration |
 

{endee-0.1.7 → endee-0.1.9}/endee/compression.py

@@ -6,9 +6,10 @@ metadata. Metadata is serialized to JSON and compressed using zlib
 to reduce storage size, memory usage, and network transfer overhead.
 """
 
-import json
 import zlib
 
+import orjson
+
 
 def json_zip(data: dict) -> bytes:
     """
@@ -24,10 +25,9 @@ def json_zip(data: dict) -> bytes:
         >>> compressed = json_zip({"user": "alice", "age": 30})
     """
     if not data:
-        return b''
+        return b""
 
-    json_bytes = json.dumps(data).encode("utf-8")
-    return zlib.compress(json_bytes)
+    return zlib.compress(orjson.dumps(data))
 
 
 def json_unzip(compressed_data: bytes) -> dict:
@@ -46,5 +46,4 @@ def json_unzip(compressed_data: bytes) -> dict:
     if not compressed_data:
         return {}
 
-    decompressed = zlib.decompress(compressed_data)
-    return json.loads(decompressed.decode("utf-8"))
+    return orjson.loads(zlib.decompress(compressed_data))

{endee-0.1.7 → endee-0.1.9}/endee/constants.py

@@ -21,13 +21,15 @@ class Precision(str, Enum):
         INT16D: 16-bit integer
         INT8D: 8-bit integer
     """
+
     BINARY2 = "binary"
     FLOAT16 = "float16"
     FLOAT32 = "float32"
     INT16D = "int16d"
     INT8D = "int8d"
 
-#Checksum Value while creating an index
+
+# Checksum Value while creating an index
 CHECKSUM = -1
 
 # HTTP Configuration
@@ -69,13 +71,7 @@ LOCAL_REGION = "local"
 
 # Supported Types
 # List of precision types supported by the vector database
-PRECISION_TYPES_SUPPORTED = [
-    "binary",
-    "float16",
-    "float32",
-    "int16d",
-    "int8d"
-]
+PRECISION_TYPES_SUPPORTED = ["binary", "float16", "float32", "int16d", "int8d"]
 
 # Distance metric types
 COSINE = "cosine"  # Cosine similarity (normalized dot product)

{endee-0.1.7 → endee-0.1.9}/endee/endee.py

@@ -6,7 +6,6 @@ vector database service. It includes session management, index operations.
 """
 
 import os
-import sys
 from functools import lru_cache
 
 import httpx
@@ -30,18 +29,14 @@ from endee.constants import (
     HTTPX_TIMEOUT_SEC,
     LOCAL_BASE_URL,
     LOCAL_REGION,
-    MAX_DIMENSION_ALLOWED,
-    MAX_INDEX_NAME_LENGTH_ALLOWED,
-    PRECISION_TYPES_SUPPORTED,
     SESSION_MAX_RETRIES,
     SESSION_POOL_CONNECTIONS,
     SESSION_POOL_MAXSIZE,
-    SPACE_TYPES_SUPPORTED,
     Precision,
 )
 from endee.exceptions import raise_exception
 from endee.index import Index
-from endee.utils import is_valid_index_name
+from endee.schema import IndexCreateRequest, IndexMetadata
 
 
 class SessionManager:
@@ -417,58 +412,34 @@ class Endee:
             ValueError: If parameters are invalid
             HTTPError: If API request fails
         """
-        # Validate index name
-        if not is_valid_index_name(name):
-            raise ValueError(
-                f"Invalid index name. Index name must be alphanumeric and can "
-                f"contain underscores and should be less than "
-                f"{MAX_INDEX_NAME_LENGTH_ALLOWED} characters"
-            )
-
-        # Validate dimension
-        if dimension > MAX_DIMENSION_ALLOWED:
-            raise ValueError(
-                f"Dimension cannot be greater than {MAX_DIMENSION_ALLOWED}"
-            )
-
-        # Validate sparse dimension
-        # Lower bound check
-        if sparse_dim < 0:
-            raise ValueError("sparse_dim cannot be negative")
-
-        # Upper bound check
-        if sparse_dim > sys.maxsize:
-            raise ValueError(f"sparse_dim cannot exceed {sys.maxsize}")
-
-        # Validate space type
-        space_type = space_type.lower()
-        if space_type not in SPACE_TYPES_SUPPORTED:
-            raise ValueError(f"Invalid space type: {space_type}")
-
-        # Validate precision
-        if precision not in PRECISION_TYPES_SUPPORTED:
-            raise ValueError(
-                f"Invalid precision: {precision}. Use one of Precision enum "
-                f"values: Precision.BINARY2, Precision.INT8D, "
-                f"Precision.INT16D, Precision.FLOAT16, or Precision.FLOAT32"
-            )
+        # Validate parameters using Pydantic
+        request_data = IndexCreateRequest(
+            name=name,
+            dimension=dimension,
+            space_type=space_type,
+            M=M,
+            ef_con=ef_con,
+            precision=precision,
+            version=version,
+            sparse_dim=sparse_dim,
+        )
 
         # Prepare request headers and data
         headers = {"Authorization": f"{self.token}", "Content-Type": "application/json"}
         data = {
-            "index_name": name,
-            "dim": dimension,
-            "space_type": space_type,
-            "M": M,
-            "ef_con": ef_con,
+            "index_name": request_data.name,
+            "dim": request_data.dimension,
+            "space_type": request_data.space_type,
+            "M": request_data.M,
+            "ef_con": request_data.ef_con,
             "checksum": CHECKSUM,
-            "precision": precision,
-            "version": version,
+            "precision": request_data.precision,
+            "version": request_data.version,
         }
 
         # Add sparse dimension if specified
-        if sparse_dim > 0:
-            data["sparse_dim"] = sparse_dim
+        if request_data.sparse_dim > 0:
+            data["sparse_dim"] = request_data.sparse_dim
 
         url = f"{self.base_url}/index/create"
 
@@ -588,6 +559,9 @@ class Endee:
 
         data = response.json()
 
+        # Validate index metadata
+        metadata = IndexMetadata(**data)
+
         # Create Index object with appropriate manager
         if self.library == HTTP_REQUESTS_LIBRARY:
             idx = Index(
@@ -595,7 +569,7 @@ class Endee:
                 token=self.token,
                 url=self.base_url,
                 version=self.version,
-                params=data,
+                params=metadata.model_dump(by_alias=True),
                 session_client_manager=self.session_manager,
             )
         else:
@@ -604,7 +578,7 @@ class Endee:
                 token=self.token,
                 url=self.base_url,
                 version=self.version,
-                params=data,
+                params=metadata.model_dump(by_alias=True),
                 session_client_manager=self.client_manager,
             )
 

{endee-0.1.7 → endee-0.1.9}/endee/exceptions.py

@@ -6,7 +6,7 @@ conditions that can occur when interacting with the Endee API. Each exception
 type corresponds to specific HTTP status codes and error scenarios.
 """
 
-import json
+import orjson
 
 
 class EndeeException(Exception):
@@ -231,8 +231,8 @@ def raise_exception(code: int, text: str = None):
     # Try to parse JSON error message
     message = None
     try:
-        message = json.loads(text).get("error", "Unknown error")
-    except (json.JSONDecodeError, TypeError, AttributeError):
+        message = orjson.loads(text).get("error", "Unknown error")
+    except (orjson.JSONDecodeError, TypeError, AttributeError):
         # Fall back to raw text or default message
         message = text or "Unknown error"
 

{endee-0.1.7 → endee-0.1.9}/endee/index.py

@@ -6,6 +6,8 @@ upsert, query, delete, and retrieval on vector indices. It supports both dense
 and hybrid (dense + sparse) vector operations.
 """
 
+from typing import List
+
 import msgpack
 import numpy as np
 import orjson
@@ -20,8 +22,6 @@ from .constants import (
     DIMENSION_FIELD,
     IS_HYBRID_FIELD,
     MAX_CONNECTIONS_FIELD,
-    MAX_EF_SEARCH_ALLOWED,
-    MAX_TOP_K_ALLOWED,
     MAX_VECTORS_PER_BATCH,
     NAME_FIELD,
     PRECISION_FIELD,
@@ -29,6 +29,7 @@ from .constants import (
     SPARSE_DIM_FIELD,
 )
 from .exceptions import raise_exception
+from .schema import IndexMetadata, QueryRequest, VectorItem
 
 
 class Index:
@@ -76,18 +77,19 @@ class Index:
             session_client_manager: Shared SessionManager or ClientManager
                 from parent Endee client
         """
+        metadata = IndexMetadata(**params)
         self.name = name
         self.token = token
         self.url = url
         self.version = version
         self.checksum = CHECKSUM
-        self.lib_token = params["lib_token"]
-        self.count = params["total_elements"]
-        self.space_type = params[SPACE_TYPE_FIELD]
-        self.dimension = params[DIMENSION_FIELD]
-        self.precision = params.get(PRECISION_FIELD)
-        self.M = params[MAX_CONNECTIONS_FIELD]
-        self.sparse_dim = params.get(SPARSE_DIM_FIELD, 0)
+        self.lib_token = metadata.lib_token
+        self.count = metadata.total_elements
+        self.space_type = metadata.space_type
+        self.dimension = metadata.dimension
+        self.precision = metadata.precision
+        self.M = metadata.M
+        self.sparse_dim = metadata.sparse_dim
 
         # Use shared HTTP manager from Endee client
         self.session_client_manager = session_client_manager
@@ -134,12 +136,12 @@ class Index:
         """
         return self.name
 
-    def _validate_and_prepare_vectors(self, input_array):
+    def _validate_and_prepare_vectors(self, raw_vectors: List[List[float]]):
         """
-        Validate and prepare vectors from input array.
+        Validate and prepare vectors from raw input lists.
 
         Args:
-            input_array: List of vector dictionaries
+            raw_vectors: List of dense vector lists
 
         Returns:
             tuple: (vectors_array, norms_array, vectors_list)
@@ -149,9 +151,7 @@ class Index:
         """
         # Extract vectors
         try:
-            vectors = np.asarray(
-                [item["vector"] for item in input_array], dtype=np.float32
-            )
+            vectors = np.asarray(raw_vectors, dtype=np.float32)
         except Exception as e:
             raise ValueError(f"Invalid vector data: {e}") from e
 
@@ -166,42 +166,29 @@ class Index:
             raise ValueError("Vectors contain NaN or infinity")
 
         # Normalize vectors for cosine similarity
-        N = len(input_array)
+        n_vectors = len(raw_vectors)
         if self.space_type == "cosine":
             norms = np.sqrt(np.einsum("ij,ij->i", vectors, vectors))
             np.maximum(norms, 1e-10, out=norms)  # Prevent division by zero
             vectors /= norms[:, None]
         else:
-            norms = np.ones(N, dtype=np.float32)
+            norms = np.ones(n_vectors, dtype=np.float32)
 
         return vectors, norms, vectors.tolist()
 
-    def _validate_sparse_data(self, sparse_indices, sparse_values):
-        """
-        Validate sparse data for hybrid indexes.
-
-        Args:
-            sparse_indices: List of sparse vector indices
-            sparse_values: List of sparse vector values
-
-        Raises:
-            ValueError: If sparse data is invalid
-        """
-        if len(sparse_indices) != len(sparse_values):
-            raise ValueError("sparse_indices and sparse_values must match in length")
-
-        if sparse_indices:
-            min_idx = min(sparse_indices)
-            max_idx = max(sparse_indices)
-            if min_idx < 0 or max_idx >= self.sparse_dim:
-                raise ValueError(f"Sparse indices out of bounds [0, {self.sparse_dim})")
-
-    def _build_vector_batch_item(self, item, i, norms, vectors_list, is_hybrid):
+    def _build_vector_batch_item(
+        self,
+        item: VectorItem,
+        i: int,
+        norms: np.ndarray,
+        vectors_list: list,
+        is_hybrid: bool,
+    ):
         """
         Build a single vector batch item.
 
         Args:
-            item: Input dictionary for one vector
+            item: Validated VectorItem
             i: Index in the batch
             norms: Array of vector norms
             vectors_list: List of vectors
@@ -213,14 +200,19 @@ class Index:
         Raises:
             ValueError: If sparse data is invalid
         """
-        get_func = dict.get
+        # Localize functions for performance
         dumps_func = orjson.dumps
+        zip_func = json_zip
         str_func = str
         float_func = float
 
-        sparse_indices = get_func(item, "sparse_indices", None)
-        sparse_values = get_func(item, "sparse_values", None)
-        has_sparse = sparse_indices is not None or sparse_values is not None
+        item_id = item.id
+        item_meta = item.meta
+        item_filter = item.filter
+        sparse_indices = item.sparse_indices
+        sparse_values = item.sparse_values
+
+        has_sparse = sparse_indices is not None
 
         # XOR logic: hybrid index requires sparse data,
         # dense-only forbids it
@@ -230,15 +222,18 @@ class Index:
                 "and dense-only index forbids it."
             )
 
-        # Validate sparse data if present
-        if is_hybrid:
-            self._validate_sparse_data(sparse_indices, sparse_values)
+        # Validate sparse indices if present
+        if has_sparse:
+            max_idx = max(sparse_indices)
+            min_idx = min(sparse_indices)
+            if min_idx < 0 or max_idx >= self.sparse_dim:
+                raise ValueError(f"Sparse indices out of bounds [0, {self.sparse_dim})")
 
         # Build vector object: [id, meta, filter, norm, vector, ...]
         obj = [
-            str_func(get_func(item, "id", "")),
-            json_zip(get_func(item, "meta", {})),
-            dumps_func(get_func(item, "filter", {})).decode("utf-8"),
+            str_func(item_id),
+            zip_func(item_meta),
+            dumps_func(item_filter).decode("utf-8"),
             float_func(norms[i]),
             vectors_list[i],
         ]
@@ -248,7 +243,7 @@ class Index:
             obj.extend(
                 (
                     sparse_indices,
-                    [float(v) for v in sparse_values],
+                    [float_func(v) for v in sparse_values],
                 )
             )
 
@@ -294,20 +289,40 @@ class Index:
                 f"Cannot insert more than {MAX_VECTORS_PER_BATCH} vectors at a time"
             )
 
-        # Validate IDs upfront
-        ids = [item.get("id", "") for item in input_array]
-        if any(not id_val or id_val is None for id_val in ids):
-            raise ValueError("All vectors must have a non-empty ID")
-
+        # Localize for the loop
         is_hybrid = self.is_hybrid
+        seen_ids = set()
+        duplicate_ids = []
+        validated_items = []
+        vector_item_cls = VectorItem
+
+        # Combine validation, duplicate check, and vector extraction
+        vectors_to_process = []
+        for item in input_array:
+            v_item = vector_item_cls(**item)
+            item_id = v_item.id
+            if item_id in seen_ids:
+                duplicate_ids.append(item_id)
+            else:
+                seen_ids.add(item_id)
+            validated_items.append(v_item)
+            vectors_to_process.append(v_item.vector)
 
-        # Validate and prepare vectors
-        vectors, norms, vectors_list = self._validate_and_prepare_vectors(input_array)
+        if duplicate_ids:
+            raise ValueError(
+                f"Duplicate IDs found in input array: {sorted(duplicate_ids)}"
+            )
+
+        # Validate and prepare vectors - Passing pre-extracted vectors
+        vectors, norms, vectors_list = self._validate_and_prepare_vectors(
+            vectors_to_process
+        )
 
-        # Build batch
+        # Build batch - localizing method call for performance
+        build_item = self._build_vector_batch_item
         vector_batch = [
-            self._build_vector_batch_item(item, i, norms, vectors_list, is_hybrid)
-            for i, item in enumerate(input_array)
+            build_item(item, i, norms, vectors_list, is_hybrid)
+            for i, item in enumerate(validated_items)
         ]
 
         serialized_data = msgpack.packb(
@@ -329,62 +344,23 @@ class Index:
 
         return "Vectors inserted successfully"
 
-    def _validate_query_params(
-        self, top_k, ef, has_sparse, has_dense, sparse_indices, sparse_values
-    ):
+    def _validate_query_params(self, query: QueryRequest):
         """
-        Validate query parameters.
+        Validate query parameters against index configuration.
 
         Args:
-            top_k: Number of results to return
-            ef: HNSW ef_search parameter
-            has_sparse: Whether sparse query is provided
-            has_dense: Whether dense query is provided
-            sparse_indices: Sparse vector indices
-            sparse_values: Sparse vector values
+            query: Validated QueryRequest model
 
         Raises:
-            ValueError: If parameters are invalid
+            ValueError: If parameters are invalid for this index
         """
-        # Validate top_k parameter
-        if top_k > MAX_TOP_K_ALLOWED or top_k <= 0:
-            raise ValueError(
-                f"top_k must be between 1 and {MAX_TOP_K_ALLOWED}, got {top_k}"
-            )
-
-        # Validate ef parameter
-        if ef > MAX_EF_SEARCH_ALLOWED:
-            raise ValueError(
-                f"ef search cannot be greater than {MAX_EF_SEARCH_ALLOWED}"
-            )
-
-        # At least one query type must be provided
-        if not has_dense and not has_sparse:
-            raise ValueError(
-                "At least one of 'vector' or 'sparse_indices'/'sparse_values' "
-                "must be provided."
-            )
-
         # Cannot use sparse query on dense-only index
-        if has_sparse and not self.is_hybrid:
+        if query.sparse_indices is not None and not self.is_hybrid:
             raise ValueError(
                 "Cannot perform sparse search on a dense-only index. "
                 "Create index with sparse_dim > 0 for hybrid support."
             )
 
-        # If one sparse parameter is provided, both must be provided
-        if has_sparse:
-            if sparse_indices is None or sparse_values is None:
-                raise ValueError(
-                    "Both sparse_indices and sparse_values must be provided together."
-                )
-            if len(sparse_indices) != len(sparse_values):
-                raise ValueError(
-                    f"sparse_indices and sparse_values must have the same "
-                    f"length. Got {len(sparse_indices)} indices and "
-                    f"{len(sparse_values)} values."
-                )
-
     def _prepare_dense_vector(self, vector):
         """
         Prepare and validate dense query vector.
@@ -513,33 +489,42 @@ class Index:
             ...     filter={"category": "A"}
             ... )
         """
-        # Validate sparse query parameters
-        has_sparse = sparse_indices is not None or sparse_values is not None
-        has_dense = vector is not None
-
-        # Validate all query parameters
-        self._validate_query_params(
-            top_k, ef, has_sparse, has_dense, sparse_indices, sparse_values
+        # Validate and prepare query using Pydantic
+        query_params = QueryRequest(
+            vector=vector,
+            top_k=top_k,
+            filter=filter,
+            ef=ef,
+            include_vectors=include_vectors,
+            sparse_indices=sparse_indices,
+            sparse_values=sparse_values,
         )
 
+        # Additional index-specific validation
+        self._validate_query_params(query_params)
+
         # Prepare search request headers
         headers = {"Authorization": f"{self.token}", "Content-Type": "application/json"}
 
         # Prepare search request data
-        data = {"k": top_k, "ef": ef, "include_vectors": include_vectors}
+        data = {
+            "k": query_params.top_k,
+            "ef": query_params.ef,
+            "include_vectors": query_params.include_vectors,
+        }
 
         # Add dense vector if provided
-        if has_dense:
-            data["vector"] = self._prepare_dense_vector(vector)
+        if query_params.vector is not None:
+            data["vector"] = self._prepare_dense_vector(query_params.vector)
 
         # Add sparse query if provided
-        if has_sparse:
-            data["sparse_indices"] = list(sparse_indices)
-            data["sparse_values"] = [float(v) for v in sparse_values]
+        if query_params.sparse_indices is not None:
+            data["sparse_indices"] = list(query_params.sparse_indices)
+            data["sparse_values"] = [float(v) for v in query_params.sparse_values]
 
         # Add filter if provided
-        if filter:
-            data["filter"] = orjson.dumps(filter).decode("utf-8")
+        if query_params.filter:
+            data["filter"] = orjson.dumps(query_params.filter).decode("utf-8")
 
         url = f"{self.url}/index/{self.name}/search"
 
@@ -555,7 +540,7 @@ class Index:
         results = msgpack.unpackb(response.content, raw=False)
 
         # Process and format results
-        return self._process_query_results(results, top_k, include_vectors)
+        return self._process_query_results(results, query_params.top_k, include_vectors)
 
     def delete_vector(self, id):
         """
@@ -584,6 +569,35 @@ class Index:
 
         return response.text + " rows deleted"
 
+    def delete_with_filter(self, filter):
+        """
+        Delete multiple vectors based on a filter.
+
+        Deletes all vectors that match the provided filter criteria.
+
+        Args:
+            filter: Dictionary containing filter criteria
+
+        Returns:
+            str: Server response with deletion details
+
+        Raises:
+            HTTPError: If deletion fails
+        """
+        headers = {"Authorization": f"{self.token}", "Content-Type": "application/json"}
+
+        data = {"filter": filter}
+
+        url = f"{self.url}/index/{self.name}/vectors/delete"
+
+        http_client = self._get_session_client()
+        response = http_client.delete(url, headers=headers, json=data)
+
+        if response.status_code != 200:
+            raise_exception(response.status_code, response.text)
+
+        return response.text
+
     def get_vector(self, id):
         """
         Retrieve a single vector by ID.

endee-0.1.9/endee/schema.py

@@ -0,0 +1,138 @@
+import re
+import sys
+from typing import Any, Dict, List, Optional, Union
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from .constants import (
+    DEFAULT_EF_SEARCH,
+    DEFAULT_TOPK,
+    MAX_DIMENSION_ALLOWED,
+    MAX_EF_SEARCH_ALLOWED,
+    MAX_INDEX_NAME_LENGTH_ALLOWED,
+    MAX_TOP_K_ALLOWED,
+    PRECISION_TYPES_SUPPORTED,
+    SPACE_TYPES_SUPPORTED,
+    Precision,
+)
+
+
+class VectorItem(BaseModel):
+    """Model for a single vector item in an upsert operation."""
+
+    id: str = Field(..., min_length=1)
+    vector: List[float]
+    meta: Optional[Dict[str, Any]] = Field(default_factory=dict)
+    filter: Optional[Dict[str, Any]] = Field(default_factory=dict)
+    sparse_indices: Optional[List[int]] = None
+    sparse_values: Optional[List[float]] = None
+
+    @model_validator(mode="after")
+    def validate_sparse_data(self) -> "VectorItem":
+        if (self.sparse_indices is None) != (self.sparse_values is None):
+            raise ValueError(
+                "Both sparse_indices and sparse_values must be provided together"
+            )
+        if self.sparse_indices is not None and len(self.sparse_indices) != len(
+            self.sparse_values
+        ):
+            raise ValueError("sparse_indices and sparse_values must match in length")
+        return self
+
+
+class QueryRequest(BaseModel):
+    """Model for query parameters."""
+
+    vector: Optional[List[float]] = None
+    top_k: int = Field(default=DEFAULT_TOPK, gt=0, le=MAX_TOP_K_ALLOWED)
+    filter: Optional[List[Dict[str, Any]]] = None
+    ef: int = Field(default=DEFAULT_EF_SEARCH, le=MAX_EF_SEARCH_ALLOWED)
+    include_vectors: bool = False
+    sparse_indices: Optional[List[int]] = None
+    sparse_values: Optional[List[float]] = None
+
+    @model_validator(mode="after")
+    def validate_query_type(self) -> "QueryRequest":
+        has_dense = self.vector is not None
+        has_sparse = self.sparse_indices is not None or self.sparse_values is not None
+
+        if not has_dense and not has_sparse:
+            raise ValueError(
+                "At least one of 'vector' or 'sparse_indices'/'sparse_values'"
+                " must be provided."
+            )
+
+        if (self.sparse_indices is None) != (self.sparse_values is None):
+            raise ValueError(
+                "Both sparse_indices and sparse_values must be provided together"
+            )
+
+        if self.sparse_indices is not None and len(self.sparse_indices) != len(
+            self.sparse_values
+        ):
+            raise ValueError("sparse_indices and sparse_values must match in length")
+
+        return self
+
+
+class IndexCreateRequest(BaseModel):
+    """Model for index creation parameters."""
+
+    name: str
+    dimension: int = Field(..., gt=0, le=MAX_DIMENSION_ALLOWED)
+    space_type: str
+    M: int = Field(..., gt=0)
+    ef_con: int = Field(..., gt=0)
+    precision: Union[str, Precision]
+    version: Optional[int] = None
+    sparse_dim: int = Field(default=0, ge=0, le=sys.maxsize)
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        if not re.match(r"^[a-zA-Z0-9_]+$", v):
+            raise ValueError(
+                "Index name must be alphanumeric and can contain underscores"
+            )
+        if len(v) > MAX_INDEX_NAME_LENGTH_ALLOWED:
+            raise ValueError(
+                f"Index name should be less than {MAX_INDEX_NAME_LENGTH_ALLOWED}"
+                " characters"
+            )
+        return v
+
+    @field_validator("space_type")
+    @classmethod
+    def validate_space_type(cls, v: str) -> str:
+        v = v.lower()
+        if v not in SPACE_TYPES_SUPPORTED:
+            raise ValueError(
+                f"Invalid space type: {v}. Must be one of {SPACE_TYPES_SUPPORTED}"
+            )
+        return v
+
+    @field_validator("precision")
+    @classmethod
+    def validate_precision(cls, v: Union[str, Precision]) -> Union[str, Precision]:
+        if isinstance(v, Precision):
+            return v
+        if v not in PRECISION_TYPES_SUPPORTED:
+            raise ValueError(
+                f"Invalid precision: {v}. Must be one of {PRECISION_TYPES_SUPPORTED}"
+            )
+        return v
+
+
+class IndexMetadata(BaseModel):
+    """Model for index metadata returned by the server."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    name: Optional[str] = Field(None, alias="name")
+    lib_token: str
+    total_elements: int = Field(..., alias="total_elements")
+    space_type: str = Field(..., alias="space_type")
+    dimension: int = Field(..., alias="dimension")
+    precision: Optional[str] = Field(None, alias="precision")
+    M: int = Field(..., alias="M")
+    sparse_dim: int = Field(0, alias="sparse_dim")

{endee-0.1.7 → endee-0.1.9}/endee/utils.py

@@ -35,10 +35,10 @@ def is_valid_index_name(index_name):
         False
     """
     # Pattern matches alphanumeric characters and underscores only
-    pattern = re.compile(r'^[a-zA-Z0-9_]+$')
+    pattern = re.compile(r"^[a-zA-Z0-9_]+$")
 
     # Check both pattern match and length constraint
     return (
-        pattern.match(index_name) is not None and
-        len(index_name) <= MAX_INDEX_NAME_LENGTH_ALLOWED
+        pattern.match(index_name) is not None
+        and len(index_name) <= MAX_INDEX_NAME_LENGTH_ALLOWED
     )

{endee-0.1.7 → endee-0.1.9}/endee.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: endee
-Version: 0.1.7
+Version: 0.1.9
 Summary: Endee is the Next-Generation Vector Database for Scalable, High-Performance AI
 Home-page: https://endee.io
 Author: Endee Labs
@@ -29,6 +29,7 @@ Requires-Dist: httpx[http2]>=0.28.1
 Requires-Dist: numpy>=2.2.4
 Requires-Dist: msgpack>=1.1.0
 Requires-Dist: orjson>=3.11.5
+Requires-Dist: pydantic>=2.0.0
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -602,6 +603,23 @@ index = client.get_index(name="your-index-name")
 index.delete_vector("vec1")
 ```
 
+### Filtered Deletion
+
+In cases where you don't know the exact vector `id`, but want to delete vectors based on filter fields, you can use filtered deletion. This is especially useful for:
+
+- Bulk deleting vectors by tag, type, or timestamp
+- Enforcing access control or data expiration policies
+
+```python
+from endee import Endee
+
+client = Endee(token="your-token-here")
+index = client.get_index(name="your-index-name")
+
+# Delete all vectors matching filter conditions
+index.delete_with_filter([{"tags": {"$eq": "important"}}])
+```
+
 ### Index Deletion
 
 Index deletion permanently removes the entire index and all vectors associated with it. This should be used when:
@@ -669,6 +687,7 @@ info = index.describe()
 | `upsert(input_array)` | Insert or update vectors (max 1000 per batch) |
 | `query(vector, top_k, filter, ef, include_vectors, sparse_indices, sparse_values)` | Search for similar vectors (sparse params optional for hybrid) |
 | `delete_vector(id)` | Delete a vector by ID |
+| `delete_with_filter(filter)` | Delete vectors matching a filter |
 | `get_vector(id)` | Get a specific vector by ID |
 | `describe()` | Get index statistics and configuration |
 

{endee-0.1.7 → endee-0.1.9}/endee.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ endee/constants.py
 endee/endee.py
 endee/exceptions.py
 endee/index.py
+endee/schema.py
 endee/utils.py
 endee.egg-info/PKG-INFO
 endee.egg-info/SOURCES.txt

{endee-0.1.7 → endee-0.1.9}/endee.egg-info/requires.txt

@@ -3,3 +3,4 @@ httpx[http2]>=0.28.1
 numpy>=2.2.4
 msgpack>=1.1.0
 orjson>=3.11.5
+pydantic>=2.0.0

{endee-0.1.7 → endee-0.1.9}/setup.py

@@ -15,7 +15,7 @@ with open("README.md", encoding="utf-8") as f:
 setup(
     # Package Metadata
     name="endee",
-    version="0.1.7",
+    version="0.1.9",
     author="Endee Labs",
     author_email="dev@endee.io",
     description=(
@@ -33,6 +33,7 @@ setup(
         "numpy>=2.2.4",  # Array operations and vector normalization
         "msgpack>=1.1.0",  # Efficient binary serialization
         "orjson>=3.11.5",  # Ultra-fast JSON serialization/deserialization
+        "pydantic>=2.0.0",  # Data validation and settings management
     ],
     # Python Version Requirements
     python_requires=">=3.6",