First implementation of the improved runtime Vamana API

Author: rfsaliev

bindings/cpp/CMakeLists.txt

@@ -20,12 +20,19 @@ set(SVS_RUNTIME_HEADERS
     include/IndexSVSImplDefs.h
     include/IndexSVSFlatImpl.h
     include/IndexSVSVamanaImpl.h
+    include/training.h
+    include/vamana_index.h
+    include/dynamic_vamana_index.h
 )
 
 set(SVS_RUNTIME_SOURCES
     src/IndexSVSImplUtils.h
+    src/svs_runtime_utils.h
+    src/dynamic_vamana_index_impl.h
     src/IndexSVSFlatImpl.cpp
     src/IndexSVSVamanaImpl.cpp
+    src/training.cpp
+    src/dynamic_vamana_index.cpp
 )
 
 option(SVS_RUNTIME_ENABLE_LVQ_LEANVEC "Enable compilation of SVS runtime with LVQ and LeanVec support" ON)

bindings/cpp/include/IndexSVSImplDefs.h

@@ -31,12 +31,19 @@ namespace svs {
 namespace runtime {
 enum class MetricType { L2, INNER_PRODUCT };
 
+enum class StorageKind { 
+    FP32, FP16, SQI8,
+    LVQ4x0, LVQ4x4, LVQ4x8,
+    LeanVec4x4, LeanVec4x8, LeanVec8x8,
+};
+
 enum class ErrorCode {
     SUCCESS = 0,
     UNKNOWN_ERROR = 1,
     INVALID_ARGUMENT = 2,
     NOT_IMPLEMENTED = 3,
-    NOT_INITIALIZED = 4
+    NOT_INITIALIZED = 4,
+    RUNTIME_ERROR = 5
 };
 
 struct Status {

bindings/cpp/include/dynamic_vamana_index.h

@@ -0,0 +1,79 @@
+/*
+ * Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include "IndexSVSImplDefs.h"
+#include "vamana_index.h"
+#include "training.h"
+
+#include <cstddef>
+#include <istream>
+#include <ostream>
+
+namespace svs {
+namespace runtime {
+
+// Abstract interface for Dynamic Vamana-based indexes.
+struct SVS_RUNTIME_API DynamicVamanaIndex : public VamanaIndex {
+
+    virtual Status add(size_t n, const size_t* labels, const float* x) noexcept = 0;
+    virtual Status remove_selected(size_t* num_removed, const IDFilter& selector) noexcept = 0;
+    virtual Status remove(size_t n, const size_t* labels) noexcept = 0;
+
+    virtual Status reset() noexcept = 0;
+
+    // Static constructors and destructors
+    static Status build(
+        DynamicVamanaIndex** index,
+        size_t dim,
+        MetricType metric,
+        StorageKind storage_kind,
+        const VamanaIndex::BuildParams& params,
+        const VamanaIndex::SearchParams& default_search_params = {10, 10, 0, 0}
+    ) noexcept;
+
+    static Status destroy(DynamicVamanaIndex* index) noexcept;
+
+    virtual Status save(std::ostream& out) const noexcept = 0;
+    static Status load(DynamicVamanaIndex** index, std::istream& in, MetricType metric, StorageKind storage_kind) noexcept;
+};
+
+struct SVS_RUNTIME_API DynamicVamanaIndexLeanVec : public DynamicVamanaIndex {
+    // Specialization to build LeanVec-based Vamana index with specified leanvec dims
+    static Status build(
+        DynamicVamanaIndex** index,
+        size_t dim,
+        MetricType metric,
+        StorageKind storage_kind,
+        size_t leanvec_dims,
+        const VamanaIndex::BuildParams& params,
+        const VamanaIndex::SearchParams& default_search_params = {10, 10, 0, 0}
+    ) noexcept;
+
+    // Specialization to build LeanVec-based Vamana index with provided training data
+    static Status build(
+        DynamicVamanaIndex** index,
+        size_t dim,
+        MetricType metric,
+        StorageKind storage_kind,
+        const LeanVecTrainingData* training_data,
+        const VamanaIndex::BuildParams& params,
+        const VamanaIndex::SearchParams& default_search_params = {10, 10, 0, 0}
+    ) noexcept;
+};
+
+} // namespace runtime
+} // namespace svs

bindings/cpp/include/training.h

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 Intel Corporation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+#include "IndexSVSImplDefs.h"
+
+#include <cstddef>
+#include <istream>
+#include <ostream>
+
+namespace svs {
+namespace runtime {
+struct SVS_RUNTIME_API LeanVecTrainingData {
+    virtual ~LeanVecTrainingData() = 0;
+    Status build(
+        LeanVecTrainingData** training_data,
+        size_t dim,
+        size_t n,
+        const float* x,
+        size_t leanvec_dims
+    ) noexcept;
+
+    static Status destroy(LeanVecTrainingData* training_data) noexcept;
+
+    virtual Status save(std::ostream& out) const noexcept;
+    static Status load(LeanVecTrainingData** training_data, std::istream& in) noexcept;
+};
+} // namespace runtime
+} // namespace svs

bindings/cpp/include/vamana_index.h

@@ -18,30 +18,16 @@
 #include "IndexSVSImplDefs.h"
 
 #include <cstddef>
-#include <istream>
-#include <memory>
-#include <numeric>
-#include <ostream>
-#include <vector>
 
 namespace svs {
 namespace runtime {
 
 // Abstract interface for Vamana-based indexes.
+// NOTE VamanaIndex is not implemented directly, only DynamicVamanaIndex is implemented.
 struct SVS_RUNTIME_API VamanaIndex {
-    enum StorageKind { 
-        FP32, FP16, SQI8,
-        LVQ4x0, LVQ4x4, LVQ4x8,
-        LeanVec4x4, LeanVec4x8, LeanVec8x8,
-    };
+    virtual ~VamanaIndex() = 0;
 
-    // TODO:
-    // 1. Should StorageKind, metric, be a part of BuildParams?
-    // 2. Does it make sense to have "Common" BuildParams{dim, metric} struct for other index algos (Flat, IVF)?
-    //    Or dim, metric, storage kind should be passed separately to the build() method?
-    //    What about storage kind in Flat, IVF?
     struct BuildParams {
-        size_t dim;
         size_t graph_max_degree;
         size_t prune_to = 0;
         float alpha = 0;
@@ -51,21 +37,12 @@ struct SVS_RUNTIME_API VamanaIndex {
     };
 
     struct SearchParams {
-        size_t search_window_size = 0;
-        size_t search_buffer_capacity = 0;
+        size_t search_window_size = 10;
+        size_t search_buffer_capacity = 10;
+        size_t prefetch_lookahead = 0;
+        size_t prefetch_step = 0;
     };
 
-    // Unused for now:
-    virtual size_t size() const noexcept = 0;
-    virtual size_t dimensions() const noexcept = 0;
-    virtual MetricType metric_type() const noexcept = 0;
-    virtual StorageKind get_storage_kind() const noexcept = 0;
-
-    virtual Status add(size_t n, const size_t* labels, const float* x) noexcept = 0;
-    virtual Status remove_selected(size_t* num_removed, const IDFilter& selector) noexcept = 0;
-    // Further method for deletion can be added later:
-    // virtual Status remove(size_t n, const size_t* labels) noexcept = 0;
-
     virtual Status search(
         size_t n,
         const float* x,
@@ -84,48 +61,6 @@ struct SVS_RUNTIME_API VamanaIndex {
         const SearchParams* params = nullptr,
         IDFilter* filter = nullptr
     ) const noexcept = 0;
-
-    virtual Status reset() noexcept = 0;
-    // TODO: Does it make sense to rename it to "save()"?
-    virtual Status serialize(std::ostream& out) const noexcept = 0;
-
-    // Static constructors and destructors
-    static Status build(
-        VamanaIndex** index,
-        MetricType metric,
-        StorageKind storage_kind,
-        const VamanaIndex::BuildParams& params,
-        const VamanaIndex::SearchParams& default_search_params = {10,10}
-    ) noexcept;
-
-    static Status destroy(VamanaIndex* index) noexcept;
-    // TODO: Does it make sense to rename it to "load()"?
-    // TODO: is it possible to get metric and storage kind from the stream instead of passing them explicitly?
-    static Status deserialize(VamanaIndex** index, std::istream& in, MetricType metric, VamanaIndex::StorageKind storage_kind) noexcept;
-};
-
-struct SVS_RUNTIME_API VamanaIndexLeanVecFactory {
-    static Status train(
-        VamanaIndexLeanVecFactory** factory,
-        size_t d,
-        size_t n,
-        const float* x,
-        size_t leanvec_dims
-    ) noexcept;
-
-    static Status destroy(VamanaIndexLeanVecFactory* factory) noexcept;
-
-    virtual Status serialize(std::ostream& out) const noexcept;
-    static Status deserialize(VamanaIndexLeanVecFactory** factory, std::istream& in) noexcept;
-
-    virtual Status buildIndex(
-        VamanaIndex** index,
-        size_t dim,
-        MetricType metric,
-        const VamanaIndex::BuildParams& params,
-        const VamanaIndex::SearchParams& default_search_params = {}
-    ) noexcept;
 };
-
 } // namespace runtime
 } // namespace svs