usearch 2.4.1 → 2.5.1

package/.github/workflows/release.yml

@@ -591,8 +591,10 @@ jobs:
       GITHUB_PACKAGES_SOURCE: https://nuget.pkg.github.com/${{ github.repository_owner }}/index.json
     steps:
       - uses: actions/checkout@v3
+        with:
+          ref: 'main'  
       - run: git submodule update --init --recursive
-        
+          
       - name: Download usearch libs artifact
         uses: actions/download-artifact@v3
         with:
@@ -606,8 +608,7 @@ jobs:
 
       - name: Pack project
         run: |
-          VERSION_CONTENT=$(< VERSION)
-          dotnet pack "${{ env.SOLUTION }}" -c Release -p:Version="$VERSION_CONTENT" --output ${{ env.NUGET_PACKAGES }}
+          dotnet pack "${{ env.SOLUTION }}" -c Release --output ${{ env.NUGET_PACKAGES }}
         working-directory: ${{ github.workspace }}
 
       - name: Publish to NuGet

package/CITATION.cff

@@ -5,7 +5,7 @@ authors:
   given-names: "Ash"
   orcid: "https://orcid.org/0000-0002-4882-1815"
 title: "USearch by Unum Cloud"
-version: 2.4.1
+version: 2.5.1
 doi: 10.5281/zenodo.7949416
 date-released: 2022-06-12
 url: "https://github.com/unum-cloud/usearch"

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "usearch"
-version = "2.4.1"
+version = "2.5.1"
 authors = ["Ash Vardanian <1983160+ashvardanian@users.noreply.github.com>"]
 description = "Smaller & Faster Single-File Vector Search Engine from Unum"
 edition = "2021"

package/README.md

@@ -392,7 +392,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.4.1},
+version = {2.5.1},
 year = {2022},
 month = jun,
 }

package/conanfile.py

@@ -7,7 +7,7 @@ required_conan_version = ">=1.53.0"
 class USearchConan(ConanFile):
 
     name = "usearch"
-    version = '2.4.1'
+    version = '2.5.1'
     license = "Apache-2.0"
     description = "Smaller & Faster Single-File Vector Search Engine from Unum"
     homepage = "https://github.com/unum-cloud/usearch"

package/cpp/CMakeLists.txt

@@ -20,6 +20,8 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -march=native")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fmax-errors=1")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fdiagnostics-color=always")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftime-report")
 
     if(${USEARCH_USE_OPENMP})
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")
@@ -32,6 +34,8 @@ elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -fsanitize=address -fsanitize=leak -fsanitize=alignment -fsanitize=undefined")
     set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -Wfatal-errors")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -pedantic")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fcolor-diagnostics")
+    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -ftime-trace")
 
     if(${USEARCH_USE_OPENMP})
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fopenmp")

package/csharp/nuget/nuget-package.props

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project>
   <PropertyGroup>
-    <Version Condition="'$(Version)' == ''">2.4.1</Version>
+    <Version Condition="'$(Version)' == ''">2.5.1</Version>
 
     <Authors>Unum</Authors>
     <Company>Unum</Company>

package/include/usearch/index.hpp

@@ -10,7 +10,7 @@
 #define UNUM_USEARCH_HPP
 
 #define USEARCH_VERSION_MAJOR 2
-#define USEARCH_VERSION_MINOR 4
+#define USEARCH_VERSION_MINOR 5
 #define USEARCH_VERSION_PATCH 1
 
 // Inferring C++ version

package/include/usearch/index_dense.hpp

@@ -1,15 +1,18 @@
 #pragma once
 #include <stdlib.h> // `aligned_alloc`
 
-#include <functional>   // `std::function`
-#include <numeric>      // `std::iota`
-#include <shared_mutex> // `std::shared_mutex`
-#include <thread>       // `std::thread`
-#include <vector>       // `std::vector`
+#include <functional> // `std::function`
+#include <numeric>    // `std::iota`
+#include <thread>     // `std::thread`
+#include <vector>     // `std::vector`
 
 #include <usearch/index.hpp>
 #include <usearch/index_plugins.hpp>
 
+#if defined(USEARCH_DEFINED_CPP17)
+#include <shared_mutex> // `std::shared_mutex`
+#endif
+
 namespace unum {
 namespace usearch {
 
@@ -383,7 +386,11 @@ class index_dense_gt {
     /// @brief Mutex, controlling concurrent access to `available_threads_`.
     mutable std::mutex available_threads_mutex_;
 
+#if defined(USEARCH_DEFINED_CPP17)
+    using shared_mutex_t = std::shared_mutex;
+#else
     using shared_mutex_t = unfair_shared_mutex_t;
+#endif
     using shared_lock_t = shared_lock_gt<shared_mutex_t>;
     using unique_lock_t = std::unique_lock<shared_mutex_t>;
 

package/include/usearch/index_plugins.hpp

@@ -42,14 +42,10 @@
 
 #if USEARCH_USE_SIMSIMD
 #if defined(USEARCH_DEFINED_LINUX)
-#define SIMSIMD_TARGET_X86_AVX2 1
-#define SIMSIMD_TARGET_X86_AVX512 1
-#define SIMSIMD_TARGET_ARM_NEON 1
-#define SIMSIMD_TARGET_ARM_SVE 1
 #include <simsimd/simsimd.h>
 #elif defined(USEARCH_DEFINED_APPLE)
-#define SIMSIMD_TARGET_X86_AVX2 1
-#define SIMSIMD_TARGET_ARM_NEON 1
+#define SIMSIMD_TARGET_X86_AVX512 0
+#define SIMSIMD_TARGET_ARM_SVE 0
 #include <simsimd/simsimd.h>
 #endif
 #endif

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "usearch",
-    "version": "2.4.1",
+    "version": "2.5.1",
     "description": "Smaller & Faster Single-File Vector Search Engine from Unum",
     "author": "Ash Vardanian",
     "license": "Apache 2.0",

package/python/lib.cpp

@@ -526,22 +526,26 @@ static void search_typed_brute_force(                                //
     byte_t const* dataset_data = reinterpret_cast<byte_t const*>(dataset_info.ptr);
     byte_t const* queries_data = reinterpret_cast<byte_t const*>(queries_info.ptr);
     for (std::size_t query_idx = 0; query_idx != queries_count; ++query_idx)
-        counts_py1d(query_idx) = 0;
+        counts_py1d(query_idx) = wanted;
 
     if (!threads)
         threads = std::thread::hardware_concurrency();
 
     std::size_t tasks_count = static_cast<std::size_t>(dataset_count * queries_count);
-    bitset_t query_mutexes(static_cast<std::size_t>(queries_count));
-    if (!query_mutexes)
-        throw std::bad_alloc();
 
     // Progress status
     progress_t progress_{progress};
     std::atomic<std::size_t> processed{0};
 
+    // Allocate temporary memory to store the distance matrix
+    // Previous version didn't need temporary memory, but the performance was much lower
+    struct dense_key_and_distance_t {
+        u32_t offset;
+        f32_t distance;
+    };
+    std::vector<dense_key_and_distance_t> keys_and_distances(tasks_count);
+
     executor_default_t{threads}.dynamic(tasks_count, [&](std::size_t thread_idx, std::size_t task_idx) {
-        //
         std::size_t dataset_idx = task_idx / queries_count;
         std::size_t query_idx = task_idx % queries_count;
 
@@ -549,24 +553,7 @@ static void search_typed_brute_force(                                //
         byte_t const* query = queries_data + query_idx * queries_info.strides[0];
         distance_t distance = metric(dataset, query);
 
-        {
-            auto lock = query_mutexes.lock(query_idx);
-            dense_key_t* keys = &keys_py2d(query_idx, 0);
-            distance_t* distances = &distances_py2d(query_idx, 0);
-            std::size_t& matches = reinterpret_cast<std::size_t&>(counts_py1d(query_idx));
-            if (matches == wanted)
-                if (distances[wanted - 1] <= distance)
-                    return true;
-
-            std::size_t offset = std::lower_bound(distances, distances + matches, distance) - distances;
-
-            std::size_t count_worse = matches - offset - (wanted == matches);
-            std::memmove(keys + offset + 1, keys + offset, count_worse * sizeof(dense_key_t));
-            std::memmove(distances + offset + 1, distances + offset, count_worse * sizeof(distance_t));
-            keys[offset] = static_cast<dense_key_t>(dataset_idx);
-            distances[offset] = distance;
-            matches += matches != wanted;
-        }
+        keys_and_distances[task_idx] = {static_cast<u32_t>(query_idx), static_cast<f32_t>(distance)};
 
         // We don't want to check for signals from multiple threads
         ++processed;
@@ -576,6 +563,20 @@ static void search_typed_brute_force(                                //
         return true;
     });
 
+    // Partial-sort every query result
+    executor_default_t{threads}.fixed(queries_count, [&](std::size_t, std::size_t query_idx) {
+        auto start = keys_and_distances.data() + query_idx * dataset_count;
+        std::partial_sort(start, start + wanted, start + dataset_count,
+                          [](dense_key_and_distance_t const& a, dense_key_and_distance_t const& b) {
+                              return a.distance < b.distance;
+                          });
+
+        dense_key_t* keys = &keys_py2d(query_idx, 0);
+        distance_t* distances = &distances_py2d(query_idx, 0);
+        for (std::size_t i = 0; i != wanted; ++i)
+            keys[i] = static_cast<dense_key_t>(start[i].offset), distances[i] = start[i].distance;
+    });
+
     // At the end report the latest numbers, because the reporter thread may be finished earlier
     progress_(processed.load(), tasks_count);
 }
@@ -602,6 +603,8 @@ static py::tuple search_many_brute_force(    //
     Py_ssize_t queries_dimensions = queries_info.shape[1];
     if (dataset_dimensions != queries_dimensions)
         throw std::invalid_argument("The number of vector dimensions doesn't match!");
+    if (wanted > dataset_count)
+        throw std::invalid_argument("You can't request more matches than in the dataset!");
 
     scalar_kind_t dataset_kind = numpy_string_to_kind(dataset_info.format);
     scalar_kind_t queries_kind = numpy_string_to_kind(queries_info.format);

package/python/scripts/test_tooling.py

@@ -56,13 +56,13 @@ def test_exact_search(rows: int, cols: int):
     :param int cols: The number of columns in the matrix.
     """
     original = np.random.rand(rows, cols)
-    matches: BatchMatches = search(original, original, 10, exact=True)
+    matches: BatchMatches = search(original, original, min(10, rows), exact=True)
     top_matches = (
         [int(m.keys[0]) for m in matches] if rows > 1 else int(matches.keys[0])
     )
     assert np.all(top_matches == np.arange(rows))
 
-    matches: Matches = search(original, original[0], 10, exact=True)
+    matches: Matches = search(original, original[0], min(10, rows), exact=True)
     top_match = int(matches.keys[0])
     assert top_match == 0
 

package/python/usearch/index.py

@@ -871,6 +871,10 @@ class Index:
     def serialized_length(self) -> int:
         return self._compiled.serialized_length
 
+    @property
+    def metric_kind(self) -> Union[MetricKind, CompiledMetric]:
+        return self._metric_jit if self._metric_jit.kind else self._metric_kind
+
     @property
     def metric(self) -> Union[MetricKind, CompiledMetric]:
         return self._metric_jit if self._metric_jit else self._metric_kind
@@ -1190,6 +1194,7 @@ class Index:
             "size": self.size,
             "jit": self.jit,
             "hardware_acceleration": self.hardware_acceleration,
+            "metric_kind": self.metric_kind,
             "dtype": self.dtype,
             "path": self.path,
             "compiled_with_openmp": USES_OPENMP,
@@ -1204,7 +1209,7 @@ class Index:
         return f.format(
             self.dtype,
             self.ndim,
-            self.metric,
+            self.metric_kind,
             self.connectivity,
             self.expansion_add,
             self.expansion_search,
@@ -1225,7 +1230,7 @@ class Index:
                 "- config",
                 f"-- data type: {self.dtype}",
                 f"-- dimensions: {self.ndim}",
-                f"-- metric: {self.metric}",
+                f"-- metric: {self.metric_kind}",
                 f"-- connectivity: {self.connectivity}",
                 f"-- expansion on addition:{self.expansion_add} candidates",
                 f"-- expansion on search: {self.expansion_search} candidates",
@@ -1233,7 +1238,7 @@ class Index:
                 f"-- uses OpenMP: {USES_OPENMP}",
                 f"-- uses SimSIMD: {USES_SIMSIMD}",
                 f"-- supports half-precision: {USES_NATIVE_F16}",
-                f"-- uses hardware acceletion: {self.hardware_acceleration}",
+                f"-- uses hardware acceleration: {self.hardware_acceleration}",
                 "- state",
                 f"-- size: {self.size:,} vectors",
                 f"-- memory usage: {self.memory_usage:,} bytes",

package/rust/lib.cpp

@@ -23,65 +23,71 @@ template <typename scalar_at> Matches search_(index_dense_t& index, scalar_at co
     return matches;
 }
 
-Index::Index(std::unique_ptr<index_t> index) : index_(std::move(index)) {}
+NativeIndex::NativeIndex(std::unique_ptr<index_t> index) : index_(std::move(index)) {}
 
 // clang-format off
-void Index::add(key_t key, rust::Slice<float const> vec) const { index_->add(key, vec.data()).error.raise(); }
-void Index::add_i8(key_t key, rust::Slice<int8_t const> vec) const { index_->add(key, vec.data()).error.raise(); }
-void Index::add_f16(key_t key, rust::Slice<uint16_t const> vec) const { index_->add(key, (f16_t const*)vec.data()).error.raise(); }
-void Index::add_f32(key_t key, rust::Slice<float const> vec) const { index_->add(key, vec.data()).error.raise(); }
-void Index::add_f64(key_t key, rust::Slice<double const> vec) const { index_->add(key, vec.data()).error.raise(); }
-
-Matches Index::search(rust::Slice<float const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-Matches Index::search_i8(rust::Slice<int8_t const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-Matches Index::search_f16(rust::Slice<uint16_t const> vec, size_t count) const { return search_(*index_, (f16_t const*)vec.data(), count); }
-Matches Index::search_f32(rust::Slice<float const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
-Matches Index::search_f64(rust::Slice<double const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
+void NativeIndex::add_i8(key_t key, rust::Slice<int8_t const> vec) const { index_->add(key, vec.data()).error.raise(); }
+void NativeIndex::add_f16(key_t key, rust::Slice<uint16_t const> vec) const { index_->add(key, (f16_t const*)vec.data()).error.raise(); }
+void NativeIndex::add_f32(key_t key, rust::Slice<float const> vec) const { index_->add(key, vec.data()).error.raise(); }
+void NativeIndex::add_f64(key_t key, rust::Slice<double const> vec) const { index_->add(key, vec.data()).error.raise(); }
+
+Matches NativeIndex::search_i8(rust::Slice<int8_t const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
+Matches NativeIndex::search_f16(rust::Slice<uint16_t const> vec, size_t count) const { return search_(*index_, (f16_t const*)vec.data(), count); }
+Matches NativeIndex::search_f32(rust::Slice<float const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
+Matches NativeIndex::search_f64(rust::Slice<double const> vec, size_t count) const { return search_(*index_, vec.data(), count); }
+
+size_t NativeIndex::get_i8(key_t key, rust::Slice<int8_t> vec) const { return index_->get(key, vec.data(), vec.size() / dimensions()); }
+size_t NativeIndex::get_f16(key_t key, rust::Slice<uint16_t> vec) const { return index_->get(key, (f16_t*)vec.data(), vec.size() / dimensions()); }
+size_t NativeIndex::get_f32(key_t key, rust::Slice<float> vec) const { return index_->get(key, vec.data(), vec.size() / dimensions()); }
+size_t NativeIndex::get_f64(key_t key, rust::Slice<double> vec) const { return index_->get(key, vec.data(), vec.size() / dimensions()); }
 // clang-format on
 
-bool Index::remove(key_t key) const {
+size_t NativeIndex::remove(key_t key) const {
     labeling_result_t result = index_->remove(key);
     result.error.raise();
     return result.completed;
 }
 
-bool Index::rename(key_t from, key_t to) const {
+size_t NativeIndex::rename(key_t from, key_t to) const {
     labeling_result_t result = index_->rename(from, to);
     result.error.raise();
     return result.completed;
 }
 
-bool Index::contains(key_t key) const { return index_->contains(key); }
+size_t NativeIndex::count(key_t key) const { return index_->count(key); }
+bool NativeIndex::contains(key_t key) const { return index_->contains(key); }
 
-void Index::reserve(size_t capacity) const { index_->reserve(capacity); }
+void NativeIndex::reserve(size_t capacity) const { index_->reserve(capacity); }
 
-size_t Index::dimensions() const { return index_->dimensions(); }
-size_t Index::connectivity() const { return index_->connectivity(); }
-size_t Index::size() const { return index_->size(); }
-size_t Index::capacity() const { return index_->capacity(); }
-size_t Index::serialized_length() const { return index_->serialized_length(); }
+size_t NativeIndex::dimensions() const { return index_->dimensions(); }
+size_t NativeIndex::connectivity() const { return index_->connectivity(); }
+size_t NativeIndex::size() const { return index_->size(); }
+size_t NativeIndex::capacity() const { return index_->capacity(); }
+size_t NativeIndex::serialized_length() const { return index_->serialized_length(); }
 
-void Index::save(rust::Str path) const { index_->save(output_file_t(std::string(path).c_str())).error.raise(); }
-void Index::load(rust::Str path) const { index_->load(input_file_t(std::string(path).c_str())).error.raise(); }
-void Index::view(rust::Str path) const { index_->view(memory_mapped_file_t(std::string(path).c_str())).error.raise(); }
+void NativeIndex::save(rust::Str path) const { index_->save(output_file_t(std::string(path).c_str())).error.raise(); }
+void NativeIndex::load(rust::Str path) const { index_->load(input_file_t(std::string(path).c_str())).error.raise(); }
+void NativeIndex::view(rust::Str path) const {
+    index_->view(memory_mapped_file_t(std::string(path).c_str())).error.raise();
+}
 
-void Index::save_to_buffer(rust::Slice<uint8_t> buffer) const {
+void NativeIndex::save_to_buffer(rust::Slice<uint8_t> buffer) const {
     index_->save(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
 }
 
-void Index::load_from_buffer(rust::Slice<uint8_t const> buffer) const {
+void NativeIndex::load_from_buffer(rust::Slice<uint8_t const> buffer) const {
     index_->load(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
 }
 
-void Index::view_from_buffer(rust::Slice<uint8_t const> buffer) const {
+void NativeIndex::view_from_buffer(rust::Slice<uint8_t const> buffer) const {
     index_->view(memory_mapped_file_t((byte_t*)buffer.data(), buffer.size())).error.raise();
 }
 
-std::unique_ptr<Index> wrap(index_t&& index) {
+std::unique_ptr<NativeIndex> wrap(index_t&& index) {
     std::unique_ptr<index_t> punned_ptr;
     punned_ptr.reset(new index_t(std::move(index)));
-    std::unique_ptr<Index> result;
-    result.reset(new Index(std::move(punned_ptr)));
+    std::unique_ptr<NativeIndex> result;
+    result.reset(new NativeIndex(std::move(punned_ptr)));
     return result;
 }
 
@@ -110,10 +116,11 @@ scalar_kind_t rust_to_cpp_scalar(ScalarKind value) {
     }
 }
 
-std::unique_ptr<Index> new_index(IndexOptions const& options) {
+std::unique_ptr<NativeIndex> new_native_index(IndexOptions const& options) {
     metric_kind_t metric_kind = rust_to_cpp_metric(options.metric);
     scalar_kind_t scalar_kind = rust_to_cpp_scalar(options.quantization);
     metric_punned_t metric(options.dimensions, metric_kind, scalar_kind);
     index_dense_config_t config(options.connectivity, options.expansion_add, options.expansion_search);
+    config.multi = options.multi;
     return wrap(index_t::make(metric, config));
 }

package/rust/lib.hpp

@@ -8,7 +8,7 @@
 struct Matches;
 struct IndexOptions;
 
-class Index {
+class NativeIndex {
   public:
     using metric_t = unum::usearch::metric_punned_t;
     using distance_t = unum::usearch::distance_punned_t;
@@ -17,25 +17,29 @@ class Index {
     using search_result_t = typename index_dense_t::search_result_t;
     using key_t = typename index_dense_t::key_t;
 
-    Index(std::unique_ptr<index_dense_t> index);
+    NativeIndex(std::unique_ptr<index_dense_t> index);
 
     void reserve(size_t) const;
 
-    void add(key_t key, rust::Slice<float const> vector) const;
     void add_i8(key_t key, rust::Slice<int8_t const> vector) const;
     void add_f16(key_t key, rust::Slice<uint16_t const> vector) const;
     void add_f32(key_t key, rust::Slice<float const> vector) const;
     void add_f64(key_t key, rust::Slice<double const> vector) const;
 
-    Matches search(rust::Slice<float const> vector, size_t count) const;
     Matches search_i8(rust::Slice<int8_t const> vector, size_t count) const;
     Matches search_f16(rust::Slice<uint16_t const> vector, size_t count) const;
     Matches search_f32(rust::Slice<float const> vector, size_t count) const;
     Matches search_f64(rust::Slice<double const> vector, size_t count) const;
 
-    bool remove(key_t key) const;
+    size_t get_i8(key_t key, rust::Slice<int8_t> vector) const;
+    size_t get_f16(key_t key, rust::Slice<uint16_t> vector) const;
+    size_t get_f32(key_t key, rust::Slice<float> vector) const;
+    size_t get_f64(key_t key, rust::Slice<double> vector) const;
+
+    size_t count(key_t key) const;
+    size_t remove(key_t key) const;
+    size_t rename(key_t from, key_t to) const;
     bool contains(key_t key) const;
-    bool rename(key_t from, key_t to) const;
 
     size_t dimensions() const;
     size_t connectivity() const;
@@ -55,4 +59,4 @@ class Index {
     std::unique_ptr<index_dense_t> index_;
 };
 
-std::unique_ptr<Index> new_index(IndexOptions const& options);
+std::unique_ptr<NativeIndex> new_native_index(IndexOptions const& options);

package/rust/lib.rs

@@ -33,198 +33,331 @@ pub mod ffi {
         connectivity: usize,
         expansion_add: usize,
         expansion_search: usize,
+        multi: bool,
     }
 
     // C++ types and signatures exposed to Rust.
     unsafe extern "C++" {
         include!("lib.hpp");
 
-        /// Represents the USearch index.
-        type Index;
-
-        /// Initializes a new instance of the index with the provided options.
-        ///
-        /// # Arguments
-        ///
-        /// * `options` - A reference to the `IndexOptions` structure containing initialization options.
-        ///
-        /// # Returns
-        ///
-        /// A `Result` which is `Ok` if the index is successfully initialized, or `Err` if an error occurs.
-        pub fn new_index(options: &IndexOptions) -> Result<UniquePtr<Index>>;
-
-        /// Reserves memory for a specified number of incoming vectors.
-        ///
-        /// # Arguments
-        ///
-        /// * `capacity` - The desired total capacity including the current size.
-        pub fn reserve(self: &Index, capacity: usize) -> Result<()>;
-
-        /// Retrieves the number of dimensions in the vectors indexed.
-        pub fn dimensions(self: &Index) -> usize;
-
-        /// Retrieves the connectivity parameter that limits connections-per-node in the graph.
-        pub fn connectivity(self: &Index) -> usize;
-
-        /// Retrieves the current number of vectors in the index.
-        pub fn size(self: &Index) -> usize;
-
-        /// Retrieves the total capacity of the index, including reserved space.
-        pub fn capacity(self: &Index) -> usize;
-
-        /// Reports expected file size after serialization.
-        pub fn serialized_length(self: &Index) -> usize;
-
-        /// Adds a vector with a specified key to the index.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key associated with the vector.
-        /// * `vector` - A slice containing the vector data.
-        fn add<T>(self: &Index, key: u64, vector: &[T]) -> Result<()> {
-            // Use type-based dispatch
-            if std::any::TypeId::of::<T>() == std::any::TypeId::of::<i8>() {
-                add_i8(key, unsafe { std::mem::transmute::<&[T], &[i8]>(vector) })
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f32>() {
-                add_f32(key, unsafe { std::mem::transmute::<&[T], &[f32]>(vector) })
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f64>() {
-                add_f64(key, unsafe { std::mem::transmute::<&[T], &[f64]>(vector) })
-            } else {
-                Err(Box::new("Unsupported type"))
-            }
+        /// Low-level C++ interface, that is further wrapped into the high-level `Index`
+        type NativeIndex;
+
+        pub fn new_native_index(options: &IndexOptions) -> Result<UniquePtr<NativeIndex>>;
+        pub fn reserve(self: &NativeIndex, capacity: usize) -> Result<()>;
+        pub fn dimensions(self: &NativeIndex) -> usize;
+        pub fn connectivity(self: &NativeIndex) -> usize;
+        pub fn size(self: &NativeIndex) -> usize;
+        pub fn capacity(self: &NativeIndex) -> usize;
+        pub fn serialized_length(self: &NativeIndex) -> usize;
+
+        pub fn add_i8(self: &NativeIndex, key: u64, vector: &[i8]) -> Result<()>;
+        pub fn add_f16(self: &NativeIndex, key: u64, vector: &[u16]) -> Result<()>;
+        pub fn add_f32(self: &NativeIndex, key: u64, vector: &[f32]) -> Result<()>;
+        pub fn add_f64(self: &NativeIndex, key: u64, vector: &[f64]) -> Result<()>;
+
+        pub fn search_i8(self: &NativeIndex, query: &[i8], count: usize) -> Result<Matches>;
+        pub fn search_f16(self: &NativeIndex, query: &[u16], count: usize) -> Result<Matches>;
+        pub fn search_f32(self: &NativeIndex, query: &[f32], count: usize) -> Result<Matches>;
+        pub fn search_f64(self: &NativeIndex, query: &[f64], count: usize) -> Result<Matches>;
+
+        pub fn get_i8(self: &NativeIndex, key: u64, buffer: &mut [i8]) -> Result<usize>;
+        pub fn get_f16(self: &NativeIndex, key: u64, buffer: &mut [u16]) -> Result<usize>;
+        pub fn get_f32(self: &NativeIndex, key: u64, buffer: &mut [f32]) -> Result<usize>;
+        pub fn get_f64(self: &NativeIndex, key: u64, buffer: &mut [f64]) -> Result<usize>;
+
+        pub fn remove(self: &NativeIndex, key: u64) -> Result<usize>;
+        pub fn rename(self: &NativeIndex, from: u64, to: u64) -> Result<usize>;
+        pub fn contains(self: &NativeIndex, key: u64) -> bool;
+        pub fn count(self: &NativeIndex, key: u64) -> usize;
+
+        pub fn save(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn load(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn view(self: &NativeIndex, path: &str) -> Result<()>;
+        pub fn save_to_buffer(self: &NativeIndex, buffer: &mut [u8]) -> Result<()>;
+        pub fn load_from_buffer(self: &NativeIndex, buffer: &[u8]) -> Result<()>;
+        pub fn view_from_buffer(self: &NativeIndex, buffer: &[u8]) -> Result<()>;
+    }
+}
+
+pub struct Index {
+    inner: cxx::UniquePtr<ffi::NativeIndex>,
+}
+
+impl Default for ffi::IndexOptions {
+    fn default() -> Self {
+        use crate::ffi::MetricKind;
+        use crate::ffi::ScalarKind;
+        Self {
+            dimensions: 128,
+            metric: MetricKind::IP,
+            quantization: ScalarKind::F32,
+            connectivity: 32,
+            expansion_add: 2,
+            expansion_search: 3,
+            multi: false,
         }
+    }
+}
 
-        pub fn add_i8(self: &Index, key: u64, vector: &[i8]) -> Result<()>;
-        pub fn add_f16(self: &Index, key: u64, vector: &[u16]) -> Result<()>;
-        pub fn add_f32(self: &Index, key: u64, vector: &[f32]) -> Result<()>;
-        pub fn add_f64(self: &Index, key: u64, vector: &[f64]) -> Result<()>;
-
-        /// Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query.
-        ///
-        /// # Arguments
-        ///
-        /// * `query` - A slice containing the query vector data.
-        /// * `count` - The maximum number of neighbors to search for.
-        ///
-        /// # Returns
-        ///
-        /// A `Result` containing the matches found.
-        pub fn search<T>(self: &Index, query: &[T], count: usize) -> Result<Matches> {
-            // Use type-based dispatch
-            if std::any::TypeId::of::<T>() == std::any::TypeId::of::<i8>() {
-                search_i8(unsafe { std::mem::transmute::<&[T], &[i8]>(query) }, count)
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f32>() {
-                search_f32(unsafe { std::mem::transmute::<&[T], &[f32]>(query) }, count)
-            } else if std::any::TypeId::of::<T>() == std::any::TypeId::of::<f64>() {
-                search_f64(unsafe { std::mem::transmute::<&[T], &[f64]>(query) }, count)
-            } else {
-                Err(Box::new("Unsupported type"))
-            }
+pub trait VectorType {
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception>
+    where
+        Self: Sized;
+    fn get(index: &Index, key: u64, buffer: &mut [Self]) -> Result<usize, cxx::Exception>
+    where
+        Self: Sized;
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception>
+    where
+        Self: Sized;
+}
+
+impl VectorType for i8 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_i8(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_i8(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_i8(key, vector)
+    }
+}
+
+impl VectorType for f32 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_f32(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_f32(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_f32(key, vector)
+    }
+}
+
+impl VectorType for f64 {
+    fn search(index: &Index, query: &[Self], count: usize) -> Result<ffi::Matches, cxx::Exception> {
+        index.inner.search_f64(query, count)
+    }
+    fn get(index: &Index, key: u64, vector: &mut [Self]) -> Result<usize, cxx::Exception> {
+        index.inner.get_f64(key, vector)
+    }
+    fn add(index: &Index, key: u64, vector: &[Self]) -> Result<(), cxx::Exception> {
+        index.inner.add_f64(key, vector)
+    }
+}
+
+impl Index {
+    pub fn new(options: &ffi::IndexOptions) -> Result<Self, cxx::Exception> {
+        match ffi::new_native_index(options) {
+            Ok(inner) => Result::Ok(Self { inner }),
+            Err(err) => Err(err),
         }
+    }
+
+    /// Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to the provided query.
+    ///
+    /// # Arguments
+    ///
+    /// * `query` - A slice containing the query vector data.
+    /// * `count` - The maximum number of neighbors to search for.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` containing the matches found.
+    pub fn search<T: VectorType>(
+        self: &Index,
+        query: &[T],
+        count: usize,
+    ) -> Result<ffi::Matches, cxx::Exception> {
+        T::search(self, query, count)
+    }
+
+    /// Adds a vector with a specified key to the index.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key associated with the vector.
+    /// * `vector` - A slice containing the vector data.
+    pub fn add<T: VectorType>(self: &Index, key: u64, vector: &[T]) -> Result<(), cxx::Exception> {
+        T::add(self, key, vector)
+    }
+
+    /// Extracts one or more vectors matching specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key associated with the vector.
+    /// * `vector` - A slice containing the vector data.
+    pub fn get<T: VectorType>(
+        self: &Index,
+        key: u64,
+        vector: &mut [T],
+    ) -> Result<usize, cxx::Exception> {
+        T::get(self, key, vector)
+    }
 
-        pub fn search_i8(self: &Index, query: &[i8], count: usize) -> Result<Matches>;
-        pub fn search_f16(self: &Index, query: &[u16], count: usize) -> Result<Matches>;
-        pub fn search_f32(self: &Index, query: &[f32], count: usize) -> Result<Matches>;
-        pub fn search_f64(self: &Index, query: &[f64], count: usize) -> Result<Matches>;
-
-        /// Removes the vector associated with the given key from the index.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key of the vector to be removed.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the vector is successfully removed, `false` otherwise.
-        pub fn remove(self: &Index, key: u64) -> Result<bool>;
-
-        /// Renames the vector under a certain key.
-        ///
-        /// # Arguments
-        ///
-        /// * `from` - The key of the vector to be renamed.
-        /// * `to` - The new name.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the vector is successfully renamed, `false` otherwise.
-        pub fn rename(self: &Index, from: u64, to: u64) -> Result<bool>;
-
-        /// Checks if the index contains a vector with a specified key.
-        ///
-        /// # Arguments
-        ///
-        /// * `key` - The key to be checked.
-        ///
-        /// # Returns
-        ///
-        /// `true` if the index contains the vector with the given key, `false` otherwise.
-        pub fn contains(self: &Index, key: u64) -> bool;
-
-        /// Saves the index to a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path where the index will be saved.
-        pub fn save(self: &Index, path: &str) -> Result<()>;
-
-        /// Loads the index from a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the index will be loaded.
-        pub fn load(self: &Index, path: &str) -> Result<()>;
-
-        /// Creates a view of the index from a file without loading it into memory.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the view will be created.
-        pub fn view(self: &Index, path: &str) -> Result<()>;
-
-        /// Saves the index to a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path where the index will be saved.
-        pub fn save_to_buffer(self: &Index, buffer: &mut [u8]) -> Result<()>;
-
-        /// Loads the index from a specified file.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the index will be loaded.
-        pub fn load_from_buffer(self: &Index, buffer: &[u8]) -> Result<()>;
-
-        /// Creates a view of the index from a file without loading it into memory.
-        ///
-        /// # Arguments
-        ///
-        /// * `path` - The file path from where the view will be created.
-        pub fn view_from_buffer(self: &Index, buffer: &[u8]) -> Result<()>;
+    /// Reserves memory for a specified number of incoming vectors.
+    ///
+    /// # Arguments
+    ///
+    /// * `capacity` - The desired total capacity including the current size.
+    pub fn reserve(self: &Index, capacity: usize) -> Result<(), cxx::Exception> {
+        self.inner.reserve(capacity)
+    }
 
+    /// Retrieves the number of dimensions in the vectors indexed.
+    pub fn dimensions(self: &Index) -> usize {
+        self.inner.dimensions()
+    }
+
+    /// Retrieves the connectivity parameter that limits connections-per-node in the graph.
+    pub fn connectivity(self: &Index) -> usize {
+        self.inner.connectivity()
+    }
+
+    /// Retrieves the current number of vectors in the index.
+    pub fn size(self: &Index) -> usize {
+        self.inner.size()
+    }
+
+    /// Retrieves the total capacity of the index, including reserved space.
+    pub fn capacity(self: &Index) -> usize {
+        self.inner.capacity()
+    }
+
+    /// Reports expected file size after serialization.
+    pub fn serialized_length(self: &Index) -> usize {
+        self.inner.serialized_length()
+    }
+
+    /// Removes the vector associated with the given key from the index.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key of the vector to be removed.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the vector is successfully removed, `false` otherwise.
+    pub fn remove(self: &Index, key: u64) -> Result<usize, cxx::Exception> {
+        self.inner.remove(key)
+    }
+
+    /// Renames the vector under a certain key.
+    ///
+    /// # Arguments
+    ///
+    /// * `from` - The key of the vector to be renamed.
+    /// * `to` - The new name.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the vector is successfully renamed, `false` otherwise.
+    pub fn rename(self: &Index, from: u64, to: u64) -> Result<usize, cxx::Exception> {
+        self.inner.rename(from, to)
+    }
+
+    /// Checks if the index contains a vector with a specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key to be checked.
+    ///
+    /// # Returns
+    ///
+    /// `true` if the index contains the vector with the given key, `false` otherwise.
+    pub fn contains(self: &Index, key: u64) -> bool {
+        self.inner.contains(key)
+    }
+
+    /// Count the count of vector with the same specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `key` - The key to be checked.
+    ///
+    /// # Returns
+    ///
+    /// Number of vectors found.
+    pub fn count(self: &Index, key: u64) -> usize {
+        self.inner.count(key)
+    }
+
+    /// Saves the index to a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path where the index will be saved.
+    pub fn save(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.save(path)
+    }
+
+    /// Loads the index from a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the index will be loaded.
+    pub fn load(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.load(path)
+    }
+
+    /// Creates a view of the index from a file without loading it into memory.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the view will be created.
+    pub fn view(self: &Index, path: &str) -> Result<(), cxx::Exception> {
+        self.inner.view(path)
+    }
+
+    /// Saves the index to a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path where the index will be saved.
+    pub fn save_to_buffer(self: &Index, buffer: &mut [u8]) -> Result<(), cxx::Exception> {
+        self.inner.save_to_buffer(buffer)
+    }
+
+    /// Loads the index from a specified file.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the index will be loaded.
+    pub fn load_from_buffer(self: &Index, buffer: &[u8]) -> Result<(), cxx::Exception> {
+        self.inner.load_from_buffer(buffer)
+    }
+
+    /// Creates a view of the index from a file without loading it into memory.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path from where the view will be created.
+    pub fn view_from_buffer(self: &Index, buffer: &[u8]) -> Result<(), cxx::Exception> {
+        self.inner.view_from_buffer(buffer)
     }
 }
 
+pub fn new_index(options: &ffi::IndexOptions) -> Result<Index, cxx::Exception> {
+    Index::new(options)
+}
+
 #[cfg(test)]
 mod tests {
-    use crate::ffi::new_index;
     use crate::ffi::IndexOptions;
     use crate::ffi::MetricKind;
-    use crate::ffi::ScalarKind;
+
+    use crate::new_index;
+    use crate::Index;
 
     #[test]
     fn integration() {
-        let mut options = IndexOptions {
-            dimensions: 5,
-            metric: MetricKind::IP,
-            quantization: ScalarKind::F16,
-            connectivity: 0,
-            expansion_add: 0,
-            expansion_search: 0,
-        };
+        let mut options = IndexOptions::default();
+        options.dimensions = 5;
 
-        let index = new_index(&options).unwrap();
+        let index = Index::new(&options).unwrap();
 
         assert!(index.reserve(10).is_ok());
         assert!(index.capacity() >= 10);

package/setup.py

@@ -12,8 +12,11 @@ macros_args = []
 if sys.platform == "linux":
     compile_args.append("-std=c++17")
     compile_args.append("-O3")  # Maximize performance
-    compile_args.append("-g")  # Simplify debugging
     compile_args.append("-Wno-unknown-pragmas")
+    compile_args.append("-fdiagnostics-color=always")
+
+    # Simplify debugging, but the normal `-g` may make builds much longer!
+    compile_args.append("-g1")
 
     macros_args.append(("USEARCH_USE_NATIVE_F16", "0"))
     macros_args.append(("USEARCH_USE_SIMSIMD", "1"))
@@ -27,9 +30,12 @@ if sys.platform == "darwin":
     compile_args.append("-mmacosx-version-min=10.15")
     compile_args.append("-std=c++17")
     compile_args.append("-O3")  # Maximize performance
-    compile_args.append("-g")  # Simplify debugging
+    compile_args.append("-fcolor-diagnostics")
     compile_args.append("-Wno-unknown-pragmas")
 
+    # Simplify debugging, but the normal `-g` may make builds much longer!
+    compile_args.append("-g1")
+
     # Linking OpenMP requires additional preparation in CIBuildWheel
     # macros_args.append(("USEARCH_USE_OPENMP", "1"))
     # compile_args.append("-Xpreprocessor -fopenmp")

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.4.1"
+version="2.5.1"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"