Add leanvec_primary_only build option to C++ runtime

.github/scripts/test-cpp-runtime-bindings.sh

@@ -27,15 +27,30 @@ conda create -y -n svsenv python=3.11
 source /opt/conda/etc/profile.d/conda.sh
 conda activate svsenv
 conda config --set solver libmamba
-conda install -y -c conda-forge cmake=3.30.4 make=4.2 swig=4.0 "numpy>=2.0,<3.0" scipy=1.16 pytest=7.4 gflags=2.2 setuptools
+conda install -y -c conda-forge cmake=3.30.4 make=4.2 swig=4.0 "numpy>=2.0,<3.0" scipy=1.16 pytest=7.4 gflags=2.2 setuptools curl
 conda install -y -c conda-forge gxx_linux-64=14.2 sysroot_linux-64=2.17
 conda install -y mkl=2025.3 mkl-devel=2025.3
 
-# Install libsvs-runtime from local conda package
-conda install -y /runtime_conda/libsvs-runtime-*.conda
+# Install libsvs-runtime from the public release tarball (includes the
+# leanvec_primary_only API). Once a conda-forge package with this API is
+# published, this can revert to:
+#   conda install -y /runtime_conda/libsvs-runtime-*.conda
+SVS_RUNTIME_URL="${SVS_RUNTIME_URL:-https://github.com/intel/ScalableVectorSearch/releases/download/nightly/svs_runtime-0.3.0-linux-x86_64-leanvec-primary-only-glibc228.tar.gz}"
+SVS_RUNTIME_PREFIX="${SVS_RUNTIME_PREFIX:-$HOME/svs_runtime}"
+mkdir -p "$SVS_RUNTIME_PREFIX"
+curl -fsSL "$SVS_RUNTIME_URL" | tar -xz -C "$SVS_RUNTIME_PREFIX"
+export CMAKE_PREFIX_PATH="$SVS_RUNTIME_PREFIX${CMAKE_PREFIX_PATH:+:$CMAKE_PREFIX_PATH}"
+export LD_LIBRARY_PATH="$SVS_RUNTIME_PREFIX/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
 
 # Validate python and C++ tests against FAISS CI
-git clone https://github.com/facebookresearch/faiss.git
+# NOTE: temporarily clone the ibhati/faiss fork's leanvec_primary_only
+# branch instead of upstream facebookresearch/faiss, since the new
+# leanvec_primary_only API is not yet merged upstream. Revert to
+# `git clone https://github.com/facebookresearch/faiss.git` once the
+# corresponding FAISS PR lands.
+FAISS_REPO="${FAISS_REPO:-https://github.com/ibhati/faiss.git}"
+FAISS_BRANCH="${FAISS_BRANCH:-ib/leanvec-primary-only}"
+git clone --depth 1 --branch "$FAISS_BRANCH" "$FAISS_REPO" faiss
 cd faiss
 
 echo "==============================================="

bindings/cpp/CMakeLists.txt

@@ -123,14 +123,14 @@ if (SVS_RUNTIME_ENABLE_LVQ_LEANVEC)
     else()
         # Links to LTO-enabled static library, requires GCC/G++ 11.2
         if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU" AND CMAKE_CXX_COMPILER_VERSION VERSION_GREATER_EQUAL "11.2" AND CMAKE_CXX_COMPILER_VERSION VERSION_LESS "11.3")
-            set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/nightly/svs-shared-library-lto-nightly-2026-05-06-1253.tar.gz"
+            set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/nightly/svs-shared-library-lto-nightly-leanvec-primary-only-glibc228-2026-05-11.tar.gz"
                 CACHE STRING "URL to download SVS shared library")
         else()
             message(WARNING
                 "Pre-built LVQ/LeanVec SVS library requires GCC/G++ v.11.2 to apply LTO optimizations."
                 "Current compiler: ${CMAKE_CXX_COMPILER_ID} ${CMAKE_CXX_COMPILER_VERSION}"
             )
-            set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/nightly/svs-shared-library-nightly-2026-05-06-1253.tar.gz"
+            set(SVS_URL "https://github.com/intel/ScalableVectorSearch/releases/download/nightly/svs-shared-library-nightly-leanvec-primary-only-glibc228-2026-05-11.tar.gz"
                 CACHE STRING "URL to download SVS shared library")
         endif()
         include(FetchContent)

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

@@ -105,7 +105,8 @@ struct SVS_RUNTIME_API DynamicVamanaIndexLeanVec : public DynamicVamanaIndex {
         size_t leanvec_dims,
         const VamanaIndex::BuildParams& params,
         const VamanaIndex::SearchParams& default_search_params,
-        const VamanaIndex::DynamicIndexParams& dynamic_index_params
+        const VamanaIndex::DynamicIndexParams& dynamic_index_params,
+        bool leanvec_primary_only = false
     ) noexcept;
 
     // Specialization to build LeanVec-based Vamana index with provided training data
@@ -128,7 +129,8 @@ struct SVS_RUNTIME_API DynamicVamanaIndexLeanVec : public DynamicVamanaIndex {
         const LeanVecTrainingData* training_data,
         const VamanaIndex::BuildParams& params,
         const VamanaIndex::SearchParams& default_search_params,
-        const VamanaIndex::DynamicIndexParams& dynamic_index_params
+        const VamanaIndex::DynamicIndexParams& dynamic_index_params,
+        bool leanvec_primary_only = false
     ) noexcept;
 };
 

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

@@ -114,7 +114,8 @@ struct SVS_RUNTIME_API VamanaIndexLeanVec : public VamanaIndex {
         StorageKind storage_kind,
         size_t leanvec_dims,
         const VamanaIndex::BuildParams& params = {},
-        const VamanaIndex::SearchParams& default_search_params = {}
+        const VamanaIndex::SearchParams& default_search_params = {},
+        bool leanvec_primary_only = false
     ) noexcept;
 
     // Specialization to build LeanVec-based Vamana index with provided training data
@@ -125,7 +126,8 @@ struct SVS_RUNTIME_API VamanaIndexLeanVec : public VamanaIndex {
         StorageKind storage_kind,
         const LeanVecTrainingData* training_data,
         const VamanaIndex::BuildParams& params = {},
-        const VamanaIndex::SearchParams& default_search_params = {}
+        const VamanaIndex::SearchParams& default_search_params = {},
+        bool leanvec_primary_only = false
     ) noexcept;
 };
 

bindings/cpp/src/dynamic_vamana_index.cpp

@@ -271,7 +271,8 @@ Status DynamicVamanaIndexLeanVec::build(
     size_t leanvec_dims,
     const DynamicVamanaIndex::BuildParams& params,
     const DynamicVamanaIndex::SearchParams& default_search_params,
-    const DynamicVamanaIndex::DynamicIndexParams& dynamic_index_params
+    const DynamicVamanaIndex::DynamicIndexParams& dynamic_index_params,
+    bool leanvec_primary_only
 ) noexcept {
     using Impl = DynamicVamanaIndexLeanVecImpl;
     *index = nullptr;
@@ -288,7 +289,8 @@ Status DynamicVamanaIndexLeanVec::build(
             leanvec_dims,
             params,
             default_search_params,
-            dynamic_index_params
+            dynamic_index_params,
+            leanvec_primary_only
         );
         *index = new DynamicVamanaIndexManagerBase<Impl>{std::move(impl)};
     });
@@ -303,7 +305,8 @@ Status DynamicVamanaIndexLeanVec::build(
     const LeanVecTrainingData* training_data,
     const DynamicVamanaIndex::BuildParams& params,
     const DynamicVamanaIndex::SearchParams& default_search_params,
-    const DynamicVamanaIndex::DynamicIndexParams& dynamic_index_params
+    const DynamicVamanaIndex::DynamicIndexParams& dynamic_index_params,
+    bool leanvec_primary_only
 ) noexcept {
     using Impl = DynamicVamanaIndexLeanVecImpl;
     *index = nullptr;
@@ -322,24 +325,43 @@ Status DynamicVamanaIndexLeanVec::build(
             training_data_impl,
             params,
             default_search_params,
-            dynamic_index_params
+            dynamic_index_params,
+            leanvec_primary_only
         );
         *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::
-    build(DynamicVamanaIndex**, size_t, MetricType, StorageKind, size_t, const DynamicVamanaIndex::BuildParams&, const DynamicVamanaIndex::SearchParams&, const DynamicVamanaIndex::DynamicIndexParams&) noexcept {
+Status DynamicVamanaIndexLeanVec::build(
+    DynamicVamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    size_t,
+    const DynamicVamanaIndex::BuildParams&,
+    const DynamicVamanaIndex::SearchParams&,
+    const DynamicVamanaIndex::DynamicIndexParams&,
+    bool
+) noexcept {
     return Status(
         ErrorCode::NOT_IMPLEMENTED,
         "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&) noexcept {
+Status DynamicVamanaIndexLeanVec::build(
+    DynamicVamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    const LeanVecTrainingData*,
+    const DynamicVamanaIndex::BuildParams&,
+    const DynamicVamanaIndex::SearchParams&,
+    const DynamicVamanaIndex::DynamicIndexParams&,
+    bool
+) noexcept {
     return Status(
         ErrorCode::NOT_IMPLEMENTED,
         "DynamicVamanaIndexLeanVec is not supported in this build configuration."

bindings/cpp/src/dynamic_vamana_index_leanvec_impl.h

@@ -54,11 +54,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,
+        bool leanvec_primary_only = false
     )
         : 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()}
+        , leanvec_primary_only_{leanvec_primary_only} {
         check_storage_kind(storage_kind);
     }
 
@@ -69,11 +71,13 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
         size_t leanvec_dims,
         const VamanaIndex::BuildParams& params,
         const VamanaIndex::SearchParams& default_search_params,
-        const VamanaIndex::DynamicIndexParams& dynamic_index_params
+        const VamanaIndex::DynamicIndexParams& dynamic_index_params,
+        bool leanvec_primary_only = false
     )
         : DynamicVamanaIndexImpl{dim, metric, storage_kind, params, default_search_params, dynamic_index_params}
         , leanvec_dims_{leanvec_dims}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , leanvec_primary_only_{leanvec_primary_only} {
         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->leanvec_primary_only_
                 );
             },
             data,
@@ -136,6 +141,7 @@ struct DynamicVamanaIndexLeanVecImpl : public DynamicVamanaIndexImpl {
   protected:
     size_t leanvec_dims_;
     std::optional<LeanVecMatricesType> leanvec_matrices_;
+    bool leanvec_primary_only_ = false;
 
     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,
+        bool leanvec_primary_only = false
     ) {
         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,
+            leanvec_primary_only
         );
     }
 };

bindings/cpp/src/vamana_index.cpp

@@ -153,14 +153,21 @@ Status VamanaIndexLeanVec::build(
     StorageKind storage_kind,
     size_t leanvec_dims,
     const VamanaIndex::BuildParams& params,
-    const VamanaIndex::SearchParams& default_search_params
+    const VamanaIndex::SearchParams& default_search_params,
+    bool leanvec_primary_only
 ) noexcept {
     using Impl = VamanaIndexLeanVecImpl;
     *index = nullptr;
 
     return runtime_error_wrapper([&] {
         auto impl = std::make_unique<Impl>(
-            dim, metric, storage_kind, leanvec_dims, params, default_search_params
+            dim,
+            metric,
+            storage_kind,
+            leanvec_dims,
+            params,
+            default_search_params,
+            leanvec_primary_only
         );
         *index = new VamanaIndexManagerBase<Impl>{std::move(impl)};
     });
@@ -174,7 +181,8 @@ Status VamanaIndexLeanVec::build(
     StorageKind storage_kind,
     const LeanVecTrainingData* training_data,
     const VamanaIndex::BuildParams& params,
-    const VamanaIndex::SearchParams& default_search_params
+    const VamanaIndex::SearchParams& default_search_params,
+    bool leanvec_primary_only
 ) noexcept {
     using Impl = VamanaIndexLeanVecImpl;
     *index = nullptr;
@@ -187,24 +195,46 @@ Status VamanaIndexLeanVec::build(
         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
+            dim,
+            metric,
+            storage_kind,
+            training_data_impl,
+            params,
+            default_search_params,
+            leanvec_primary_only
         );
         *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::
-    build(VamanaIndex**, size_t, MetricType, StorageKind, size_t, const VamanaIndex::BuildParams&, const VamanaIndex::SearchParams&) noexcept {
+Status VamanaIndexLeanVec::build(
+    VamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    size_t,
+    const VamanaIndex::BuildParams&,
+    const VamanaIndex::SearchParams&,
+    bool
+) noexcept {
     return Status(
         ErrorCode::NOT_IMPLEMENTED,
         "VamanaIndexLeanVec is not supported in this build configuration."
     );
 }
 
-Status VamanaIndexLeanVec::
-    build(VamanaIndex**, size_t, MetricType, StorageKind, const LeanVecTrainingData*, const VamanaIndex::BuildParams&, const VamanaIndex::SearchParams&) noexcept {
+Status VamanaIndexLeanVec::build(
+    VamanaIndex**,
+    size_t,
+    MetricType,
+    StorageKind,
+    const LeanVecTrainingData*,
+    const VamanaIndex::BuildParams&,
+    const VamanaIndex::SearchParams&,
+    bool
+) noexcept {
     return Status(
         ErrorCode::NOT_IMPLEMENTED,
         "VamanaIndexLeanVec is not supported in this build configuration."

bindings/cpp/src/vamana_index_impl.h

@@ -515,11 +515,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,
+        bool leanvec_primary_only = false
     )
         : 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()}
+        , leanvec_primary_only_{leanvec_primary_only} {
         check_storage_kind(storage_kind);
     }
 
@@ -529,11 +531,13 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
         StorageKind storage_kind,
         size_t leanvec_dims,
         const VamanaIndex::BuildParams& params,
-        const VamanaIndex::SearchParams& default_search_params
+        const VamanaIndex::SearchParams& default_search_params,
+        bool leanvec_primary_only = false
     )
         : VamanaIndexImpl{dim, metric, storage_kind, params, default_search_params}
         , leanvec_dims_{leanvec_dims}
-        , leanvec_matrices_{std::nullopt} {
+        , leanvec_matrices_{std::nullopt}
+        , leanvec_primary_only_{leanvec_primary_only} {
         check_storage_kind(storage_kind);
     }
 
@@ -573,7 +577,8 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
                     this->vamana_build_parameters(),
                     data,
                     leanvec_dims_,
-                    leanvec_matrices_
+                    leanvec_matrices_,
+                    leanvec_primary_only_
                 );
             },
             data
@@ -584,6 +589,7 @@ struct VamanaIndexLeanVecImpl : public VamanaIndexImpl {
   protected:
     size_t leanvec_dims_;
     std::optional<LeanVecMatricesType> leanvec_matrices_;
+    bool leanvec_primary_only_ = false;
 
     StorageKind check_storage_kind(StorageKind kind) {
         if (!storage::is_leanvec_storage(kind)) {