feat: refac entity and impl Vamana. (#371)

python/zvec/__init__.py

@@ -70,6 +70,8 @@ from .model.param import (
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    VamanaIndexParam,
+    VamanaQueryParam,
 )
 from .model.param.vector_query import VectorQuery
 
@@ -122,6 +124,8 @@ __all__ = [
     "HnswQueryParam",
     "HnswRabitqQueryParam",
     "IVFQueryParam",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
     # Extensions
     "DenseEmbeddingFunction",
     "SparseEmbeddingFunction",

python/zvec/__init__.pyi

@@ -26,6 +26,8 @@ from .model.param import (
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    VamanaIndexParam,
+    VamanaQueryParam,
 )
 from .model.param.vector_query import VectorQuery
 from .model.schema import CollectionSchema, CollectionStats, FieldSchema, VectorSchema
@@ -73,6 +75,8 @@ __all__: list = [
     "RrfReRanker",
     "Status",
     "StatusCode",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
     "VectorQuery",
     "VectorSchema",
     "WeightedReRanker",
@@ -122,6 +126,13 @@ class _Collection:
     def Stats(self) -> schema.CollectionStats: ...
     def Update(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
     def Upsert(self, arg0: collections.abc.Sequence[_Doc]) -> list[typing.Status]: ...
+    def _debug_hnsw_storage_mode(self, column_name: str) -> str:
+        """Debug-only: returns the storage mode of the HNSW entity on the
+        given vector column. One of 'mmap', 'buffer_pool', 'contiguous'.
+        Raises KeyError if no HNSW index exists on the column, or
+        ValueError if the column's index is not an HNSW index. Intended
+        for introspection and testing only; not part of the stable API."""
+
     def __getstate__(self) -> tuple: ...
     def __setstate__(self, arg0: tuple) -> None: ...
 

python/zvec/model/param/__init__.py

@@ -27,6 +27,8 @@ from _zvec.param import (
     IVFIndexParam,
     IVFQueryParam,
     OptimizeOption,
+    VamanaIndexParam,
+    VamanaQueryParam,
 )
 
 __all__ = [
@@ -43,4 +45,6 @@ __all__ = [
     "IndexOption",
     "InvertIndexParam",
     "OptimizeOption",
+    "VamanaIndexParam",
+    "VamanaQueryParam",
 ]

python/zvec/model/param/__init__.pyi

@@ -198,6 +198,10 @@ class HnswIndexParam(VectorIndexParam):
         quantize_type (QuantizeType): Optional quantization type for vector
             compression (e.g., FP16, INT8). Default is `QuantizeType.UNDEFINED` to
             disable quantization.
+        use_contiguous_memory (bool): If True, the HNSW streamer allocates a
+            single contiguous memory arena for all graph nodes, improving cache
+            locality and search throughput at the cost of peak memory usage.
+            Default is False.
 
     Examples:
         >>> from zvec.typing import MetricType, QuantizeType
@@ -205,10 +209,11 @@ class HnswIndexParam(VectorIndexParam):
         ...     metric_type=MetricType.COSINE,
         ...     m=16,
         ...     ef_construction=200,
-        ...     quantize_type=QuantizeType.INT8
+        ...     quantize_type=QuantizeType.INT8,
+        ...     use_contiguous_memory=True,
         ... )
         >>> print(params)
-        {'metric_type': 'IP', 'm': 16, 'ef_construction': 200, 'quantize_type': 'INT8'}
+        {'metric_type': 'IP', 'm': 16, 'ef_construction': 200, 'quantize_type': 'INT8', 'use_contiguous_memory': True}
     """
 
     def __getstate__(self) -> tuple: ...
@@ -218,6 +223,7 @@ class HnswIndexParam(VectorIndexParam):
         m: typing.SupportsInt = 50,
         ef_construction: typing.SupportsInt = 500,
         quantize_type: _zvec.typing.QuantizeType = ...,
+        use_contiguous_memory: bool = False,
     ) -> None: ...
     def __repr__(self) -> str: ...
     def __setstate__(self, arg0: tuple) -> None: ...
@@ -238,6 +244,14 @@ class HnswIndexParam(VectorIndexParam):
         int: Maximum number of neighbors per node in upper layers.
         """
 
+    @property
+    def use_contiguous_memory(self) -> bool:
+        """
+        bool: Whether to allocate a single contiguous memory arena for all
+        HNSW graph nodes. Improves cache locality and search throughput at
+        the cost of peak memory usage. Defaults to False.
+        """
+
 class HnswQueryParam(QueryParam):
     """