runtime: expose batch_size_cap as an overridable LeanVec build parameter (SVS-164)

bindings/cpp/include/svs/runtime/dynamic_vamana_index.h

@@ -126,6 +126,21 @@ struct SVS_RUNTIME_API DynamicVamanaIndexLeanVec : public DynamicVamanaIndex {
         const VamanaIndex::SearchParams& default_search_params,
         const VamanaIndex::DynamicIndexParams& dynamic_index_params
     ) noexcept;
+
+    // Overload exposing batch_size_cap (SVS-164): caps the row count of each batch
+    // LeanVec's reduce() materializes while transforming the dataset, trading build-time
+    // peak memory for build time. Default (100'000) matches the other overloads.
+    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,
+        const VamanaIndex::DynamicIndexParams& dynamic_index_params,
+        size_t batch_size_cap
+    ) noexcept;
 };
 } // SVS_DECLARE_NAMESPACE_VERSION(0)
 } // namespace runtime

bindings/cpp/include/svs/runtime/vamana_index.h

@@ -165,6 +165,20 @@ struct SVS_RUNTIME_API VamanaIndexLeanVec : public VamanaIndex {
         const VamanaIndex::BuildParams& params = {},
         const VamanaIndex::SearchParams& default_search_params = {}
     ) noexcept;
+
+    // Overload exposing batch_size_cap (SVS-164): caps the row count of each batch
+    // LeanVec's reduce() materializes while transforming the dataset, trading build-time
+    // peak memory for build time. Default (100'000) matches the other overloads.
+    static Status build(
+        VamanaIndex** index,
+        size_t dim,
+        MetricType metric,
+        StorageKind storage_kind,
+        const LeanVecTrainingData* training_data,
+        const VamanaIndex::BuildParams& params,
+        const VamanaIndex::SearchParams& default_search_params,
+        size_t batch_size_cap
+    ) noexcept;
 };
 } // SVS_DECLARE_NAMESPACE_VERSION(0)
 } // namespace runtime

bindings/cpp/src/dynamic_vamana_index.cpp

@@ -360,6 +360,43 @@ Status DynamicVamanaIndexLeanVec::build(
     });
 }
 
+// Overload exposing batch_size_cap (SVS-164)
+Status DynamicVamanaIndexLeanVec::build(
+    DynamicVamanaIndex** index,
+    size_t dim,
+    MetricType metric,
+    StorageKind storage_kind,
+    const LeanVecTrainingData* training_data,
+    const DynamicVamanaIndex::BuildParams& params,
+    const DynamicVamanaIndex::SearchParams& default_search_params,
+    const DynamicVamanaIndex::DynamicIndexParams& dynamic_index_params,
+    size_t batch_size_cap
+) noexcept {
+    using Impl = DynamicVamanaIndexLeanVecImpl;
+    *index = nullptr;
+
+    auto status = DynamicVamanaIndex::check_params(dynamic_index_params);
+    if (!status.ok()) {
+        return status;
+    }
+
+    return runtime_error_wrapper([&] {
+        auto training_data_impl =
+            static_cast<const LeanVecTrainingDataManager*>(training_data)->impl_;
+        auto impl = std::make_unique<Impl>(
+            dim,
+            metric,
+            storage_kind,
+            training_data_impl,
+            params,
+            default_search_params,
+            dynamic_index_params,
+            batch_size_cap
+        );
+        *index = new DynamicVamanaIndexManagerBase<Impl>{std::move(impl)};
+    });
+}
+
 #else  // SVS_RUNTIME_HAVE_LVQ_LEANVEC
 // LeanVec storage kind is not supported in this build configuration
 Status DynamicVamanaIndexLeanVec::
@@ -377,6 +414,23 @@ Status DynamicVamanaIndexLeanVec::
         "DynamicVamanaIndexLeanVec is not supported in this build configuration."
     );
 }
+
+Status DynamicVamanaIndexLeanVec::build(
+    DynamicVamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    const LeanVecTrainingData*,
+    const DynamicVamanaIndex::BuildParams&,
+    const DynamicVamanaIndex::SearchParams&,
+    const DynamicVamanaIndex::DynamicIndexParams&,
+    size_t
+) noexcept {
+    return Status(
+        ErrorCode::NOT_IMPLEMENTED,
+        "DynamicVamanaIndexLeanVec is not supported in this build configuration."
+    );
+}
 #endif // SVS_RUNTIME_HAVE_LVQ_LEANVEC
 } // namespace runtime
 } // namespace svs

bindings/cpp/src/dynamic_vamana_index_leanvec_impl.h

@@ -43,7 +43,8 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
     )
         : DynamicVamanaIndexImpl{std::move(impl), metric, storage_kind}
         , leanvec_dims_{0}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , batch_size_cap_{100'000} {
         check_storage_kind(storage_kind);
     }
 
@@ -54,11 +55,13 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
         const LeanVecTrainingDataImpl& training_data,
         const VamanaIndex::BuildParams& params,
         const VamanaIndex::SearchParams& default_search_params,
-        const VamanaIndex::DynamicIndexParams& dynamic_index_params
+        const VamanaIndex::DynamicIndexParams& dynamic_index_params,
+        size_t batch_size_cap = 100'000
     )
         : DynamicVamanaIndexImpl{dim, metric, storage_kind, params, default_search_params, dynamic_index_params}
         , leanvec_dims_{training_data.get_leanvec_dims()}
-        , leanvec_matrices_{training_data.get_leanvec_matrices()} {
+        , leanvec_matrices_{training_data.get_leanvec_matrices()}
+        , batch_size_cap_{batch_size_cap} {
         check_storage_kind(storage_kind);
     }
 
@@ -73,7 +76,8 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
     )
         : DynamicVamanaIndexImpl{dim, metric, storage_kind, params, default_search_params, dynamic_index_params}
         , leanvec_dims_{leanvec_dims}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , batch_size_cap_{100'000} {
         check_storage_kind(storage_kind);
     }
 
@@ -124,7 +128,8 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
                     labels,
                     blocksize_bytes,
                     this->leanvec_dims_,
-                    this->leanvec_matrices_
+                    this->leanvec_matrices_,
+                    this->batch_size_cap_
                 );
             },
             data,
@@ -136,6 +141,7 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
   protected:
     size_t leanvec_dims_;
     std::optional<LeanVecMatricesType> leanvec_matrices_;
+    size_t batch_size_cap_;
 
     StorageKind check_storage_kind(StorageKind kind) {
         if (!storage::is_leanvec_storage(kind)) {

bindings/cpp/src/svs_runtime_utils.h

@@ -355,13 +355,20 @@ struct StorageFactory<LeanVecStorageType> {
         Pool& pool,
         const Alloc& alloc = {},
         size_t leanvec_d = 0,
-        std::optional<svs::leanvec::LeanVecMatrices<svs::Dynamic>> matrices = std::nullopt
+        std::optional<svs::leanvec::LeanVecMatrices<svs::Dynamic>> matrices = std::nullopt,
+        size_t batch_size_cap = 100'000
     ) {
         if (leanvec_d == 0) {
             leanvec_d = (data.dimensions() + 1) / 2;
         }
         return LeanVecStorageType::reduce(
-            data, std::move(matrices), pool, 0, svs::lib::MaybeStatic{leanvec_d}, alloc
+            data,
+            std::move(matrices),
+            pool,
+            0,
+            svs::lib::MaybeStatic{leanvec_d},
+            alloc,
+            batch_size_cap
         );
     }
 };

bindings/cpp/src/vamana_index.cpp

@@ -257,6 +257,40 @@ Status VamanaIndexLeanVec::build(
     });
 }
 
+// Overload exposing batch_size_cap (SVS-164)
+Status VamanaIndexLeanVec::build(
+    VamanaIndex** index,
+    size_t dim,
+    MetricType metric,
+    StorageKind storage_kind,
+    const LeanVecTrainingData* training_data,
+    const VamanaIndex::BuildParams& params,
+    const VamanaIndex::SearchParams& default_search_params,
+    size_t batch_size_cap
+) noexcept {
+    using Impl = VamanaIndexLeanVecImpl;
+    *index = nullptr;
+
+    return runtime_error_wrapper([&] {
+        if (training_data == nullptr) {
+            throw StatusException{
+                ErrorCode::INVALID_ARGUMENT, "Training data must not be null"};
+        }
+        auto training_data_impl =
+            static_cast<const LeanVecTrainingDataManager*>(training_data)->impl_;
+        auto impl = std::make_unique<Impl>(
+            dim,
+            metric,
+            storage_kind,
+            training_data_impl,
+            params,
+            default_search_params,
+            batch_size_cap
+        );
+        *index = new VamanaIndexManagerBase<Impl>{std::move(impl)};
+    });
+}
+
 #else  // SVS_RUNTIME_HAVE_LVQ_LEANVEC
 // LeanVec storage kind is not supported in this build configuration
 Status VamanaIndexLeanVec::
@@ -274,6 +308,22 @@ Status VamanaIndexLeanVec::
         "VamanaIndexLeanVec is not supported in this build configuration."
     );
 }
+
+Status VamanaIndexLeanVec::build(
+    VamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    const LeanVecTrainingData*,
+    const VamanaIndex::BuildParams&,
+    const VamanaIndex::SearchParams&,
+    size_t
+) noexcept {
+    return Status(
+        ErrorCode::NOT_IMPLEMENTED,
+        "VamanaIndexLeanVec is not supported in this build configuration."
+    );
+}
 #endif // SVS_RUNTIME_HAVE_LVQ_LEANVEC
 } // namespace runtime
 } // namespace svs

bindings/cpp/src/vamana_index_impl.h

@@ -574,7 +574,8 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
     )
         : VamanaIndexImpl{std::move(impl), metric, storage_kind}
         , leanvec_dims_{0}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , batch_size_cap_{100'000} {
         check_storage_kind(storage_kind);
     }
 
@@ -584,11 +585,13 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
         StorageKind storage_kind,
         const LeanVecTrainingDataImpl& training_data,
         const VamanaIndex::BuildParams& params,
-        const VamanaIndex::SearchParams& default_search_params
+        const VamanaIndex::SearchParams& default_search_params,
+        size_t batch_size_cap = 100'000
     )
         : VamanaIndexImpl{dim, metric, storage_kind, params, default_search_params}
         , leanvec_dims_{training_data.get_leanvec_dims()}
-        , leanvec_matrices_{training_data.get_leanvec_matrices()} {
+        , leanvec_matrices_{training_data.get_leanvec_matrices()}
+        , batch_size_cap_{batch_size_cap} {
         check_storage_kind(storage_kind);
     }
 
@@ -602,7 +605,8 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
     )
         : VamanaIndexImpl{dim, metric, storage_kind, params, default_search_params}
         , leanvec_dims_{leanvec_dims}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , batch_size_cap_{100'000} {
         check_storage_kind(storage_kind);
     }
 
@@ -642,7 +646,8 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
                     this->vamana_build_parameters(),
                     data,
                     leanvec_dims_,
-                    leanvec_matrices_
+                    leanvec_matrices_,
+                    batch_size_cap_
                 );
             },
             data
@@ -653,6 +658,7 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
   protected:
     size_t leanvec_dims_;
     std::optional<LeanVecMatricesType> leanvec_matrices_;
+    size_t batch_size_cap_;
 
     StorageKind check_storage_kind(StorageKind kind) {
         if (!storage::is_leanvec_storage(kind)) {