usearch 0.11.1 → 0.12.1

package/python/lib.cpp

@@ -29,19 +29,20 @@ using py_shape_t = py::array::ShapeContainer;
 using label_t = Py_ssize_t;
 using distance_t = punned_distance_t;
 using id_t = std::uint32_t;
-using punned_t = punned_gt<label_t, id_t>;
 
-struct punned_py_t : public punned_t {
-    using native_t = punned_t;
+using punned_index_t = punned_gt<label_t, id_t>;
+using punned_add_result_t = typename punned_index_t::add_result_t;
+using punned_search_result_t = typename punned_index_t::search_result_t;
+
+struct punned_index_py_t : public punned_index_t {
+    using native_t = punned_index_t;
     using native_t::add;
     using native_t::capacity;
     using native_t::reserve;
     using native_t::search;
     using native_t::size;
 
-    std::vector<char> ascii_normalization_buffer_;
-
-    punned_py_t(native_t&& base) : native_t(std::move(base)) {}
+    punned_index_py_t(native_t&& base) : native_t(std::move(base)) {}
 };
 
 using set_member_t = std::uint32_t;
@@ -59,33 +60,53 @@ struct sets_index_py_t : public sets_index_t {
     sets_index_py_t(native_t&& base) : native_t(std::move(base)) {}
 };
 
-using hash_word_t = std::uint64_t;
-using hash_index_t = index_gt<bit_hamming_gt<hash_word_t>, label_t, id_t, hash_word_t>;
-static constexpr std::size_t bits_per_hash_word_k = sizeof(hash_word_t) * CHAR_BIT;
+using bits_numpy_word_t = std::uint8_t;
+using bits_native_word_t = std::uint64_t;
+using bits_distance_t = float;
+using bits_metric_t =
+    std::function<bits_distance_t(bits_native_word_t const*, bits_native_word_t const*, std::size_t, std::size_t)>;
+using bits_index_t = index_gt<bits_metric_t, label_t, id_t, bits_native_word_t>;
+using bits_add_result_t = typename bits_index_t::add_result_t;
+using bits_search_result_t = typename bits_index_t::search_result_t;
+
+static constexpr std::size_t bits_per_hash_numpy_word_k = sizeof(bits_numpy_word_t) * CHAR_BIT;
+static constexpr std::size_t bits_per_hash_native_word_k = sizeof(bits_native_word_t) * CHAR_BIT;
 
-struct hash_index_py_t : public hash_index_t {
-    using native_t = hash_index_t;
+struct bits_index_py_t : public bits_index_t {
+    using native_t = bits_index_t;
     using native_t::add;
     using native_t::capacity;
+    using native_t::limits;
     using native_t::reserve;
     using native_t::search;
     using native_t::size;
 
-    std::vector<hash_word_t> buffer_;
-    std::size_t words_;
     std::size_t bits_;
+    std::size_t numpy_words_;
+    std::size_t native_words_;
+    std::vector<bits_native_word_t> word_aligned_buffer_;
 
-    hash_index_py_t(native_t&& base) : native_t(std::move(base)) {}
-
-    hash_index_py_t(config_t config, std::size_t bits) : hash_index_t(config) {
-        words_ = divide_round_up<bits_per_hash_word_k>(bits);
-        bits_ = words_ * bits_per_hash_word_k;
-        buffer_.resize(words_);
-    }
+    bits_index_py_t(native_t&& base) : native_t(std::move(base)) {}
 
-    span_gt<hash_word_t const> buffer() const noexcept { return {buffer_.data(), buffer_.size()}; }
+    bits_index_py_t(index_config_t config, std::size_t bits, bits_metric_t metric)
+        : bits_index_t(config, metric), bits_(bits),                         //
+          numpy_words_(divide_round_up<bits_per_hash_numpy_word_k>(bits)),   //
+          native_words_(divide_round_up<bits_per_hash_native_word_k>(bits)), //
+          word_aligned_buffer_(native_words_* index_limits_t{}.threads()) {}
 };
 
+bits_metric_t bits_metric(common_metric_kind_t kind) {
+    switch (kind) {
+    case common_metric_kind_t::bitwise_hamming_k:
+        return bits_metric_t(bitwise_hamming_gt<bits_native_word_t, bits_distance_t>{});
+    case common_metric_kind_t::bitwise_tanimoto_k:
+        return bits_metric_t(bitwise_tanimoto_gt<bits_native_word_t, bits_distance_t>{});
+    case common_metric_kind_t::bitwise_sorensen_k:
+        return bits_metric_t(bitwise_sorensen_gt<bits_native_word_t, bits_distance_t>{});
+    default: throw std::invalid_argument("Not a bitwise metric!"); return {};
+    }
+}
+
 template <typename scalar_at> punned_stateful_metric_t udf(std::size_t metric_uintptr) {
     return [metric_uintptr](byte_t const* a_bytes, byte_t const* b_bytes, std::size_t n, std::size_t m) -> distance_t {
         using metric_t = punned_distance_t (*)(scalar_at const*, scalar_at const*, std::size_t, std::size_t);
@@ -105,71 +126,59 @@ punned_stateful_metric_t udf(std::size_t metric_uintptr, accuracy_t accuracy) {
     }
 }
 
-static punned_py_t make_index(      //
-    std::size_t dimensions,         //
-    std::size_t capacity,           //
-    std::string const& scalar_type, //
-    std::string const& metric,      //
-    std::size_t connectivity,       //
-    std::size_t expansion_add,      //
-    std::size_t expansion_search,   //
-    std::size_t metric_uintptr,     //
+static punned_index_py_t make_index( //
+    std::size_t dimensions,          //
+    std::string const& scalar_type,  //
+    common_metric_kind_t metric,     //
+    std::size_t connectivity,        //
+    std::size_t expansion_add,       //
+    std::size_t expansion_search,    //
+    std::size_t metric_uintptr,      //
     bool tune) {
 
-    config_t config;
+    index_config_t config;
     config.expansion_add = expansion_add;
     config.expansion_search = expansion_search;
     config.connectivity = connectivity;
-    config.max_elements = capacity;
-    config.max_threads_add = std::thread::hardware_concurrency();
-    config.max_threads_search = std::thread::hardware_concurrency();
 
     if (tune)
-        config = punned_t::optimize(config);
+        config = punned_index_t::optimize(config);
 
     accuracy_t accuracy = accuracy_from_name(scalar_type.c_str(), scalar_type.size());
     if (metric_uintptr)
-        return punned_t::udf(dimensions, udf(metric_uintptr, accuracy), accuracy, config);
+        return punned_index_t::udf(dimensions, udf(metric_uintptr, accuracy), accuracy, config);
     else
-        return index_from_name<punned_t>(metric.c_str(), metric.size(), dimensions, accuracy, config);
+        return punned_index_t(make_punned<punned_index_t>(metric, dimensions, accuracy, config));
 }
 
 static std::unique_ptr<sets_index_py_t> make_sets_index( //
-    std::size_t capacity,                                //
     std::size_t connectivity,                            //
     std::size_t expansion_add,                           //
     std::size_t expansion_search                         //
 ) {
-    config_t config;
+    index_config_t config;
     config.expansion_add = expansion_add;
     config.expansion_search = expansion_search;
     config.connectivity = connectivity;
-    config.max_elements = capacity;
-    config.max_threads_add = 1;
-    config.max_threads_search = 1;
 
     return std::unique_ptr<sets_index_py_t>(new sets_index_py_t(sets_index_t(config)));
 }
 
-static std::unique_ptr<hash_index_py_t> make_hash_index( //
+static std::unique_ptr<bits_index_py_t> make_hash_index( //
     std::size_t bits,                                    //
-    std::size_t capacity,                                //
+    common_metric_kind_t metric,                         //
     std::size_t connectivity,                            //
     std::size_t expansion_add,                           //
     std::size_t expansion_search                         //
 ) {
-    config_t config;
+    index_config_t config;
     config.expansion_add = expansion_add;
     config.expansion_search = expansion_search;
     config.connectivity = connectivity;
-    config.max_elements = capacity;
-    config.max_threads_add = 1;
-    config.max_threads_search = 1;
-
-    return std::unique_ptr<hash_index_py_t>(new hash_index_py_t(config, bits));
+    return std::unique_ptr<bits_index_py_t>(new bits_index_py_t(config, bits, bits_metric(metric)));
 }
 
-static void add_one_to_index(punned_py_t& index, label_t label, py::buffer vector, bool copy, std::size_t) {
+static void add_one_to_index(punned_index_py_t& index, label_t label, py::buffer vector, bool copy, std::size_t) {
 
     py::buffer_info vector_info = vector.request();
     if (vector_info.ndim != 1)
@@ -188,22 +197,22 @@ static void add_one_to_index(punned_py_t& index, label_t label, py::buffer vecto
 
     // https://docs.python.org/3/library/struct.html#format-characters
     if (vector_info.format == "c" || vector_info.format == "b")
-        index.add(label, reinterpret_cast<f8_bits_t const*>(vector_data), config);
+        index.add(label, reinterpret_cast<f8_bits_t const*>(vector_data), config).error.raise();
     else if (vector_info.format == "e")
-        index.add(label, reinterpret_cast<f16_bits_t const*>(vector_data), config);
+        index.add(label, reinterpret_cast<f16_bits_t const*>(vector_data), config).error.raise();
     else if (vector_info.format == "f" || vector_info.format == "f4" || vector_info.format == "<f4")
-        index.add(label, reinterpret_cast<float const*>(vector_data), config);
+        index.add(label, reinterpret_cast<float const*>(vector_data), config).error.raise();
     else if (vector_info.format == "d" || vector_info.format == "f8" || vector_info.format == "<f8")
-        index.add(label, reinterpret_cast<double const*>(vector_data), config);
+        index.add(label, reinterpret_cast<double const*>(vector_data), config).error.raise();
     else
         throw std::invalid_argument("Incompatible scalars in the vector!");
 }
 
-static void add_many_to_index(                                 //
-    punned_py_t& index, py::buffer labels, py::buffer vectors, //
+static void add_many_to_index(                                       //
+    punned_index_py_t& index, py::buffer labels, py::buffer vectors, //
     bool copy, std::size_t threads) {
 
-    if (index.config().max_threads_add < threads)
+    if (index.limits().threads_add < threads)
         throw std::invalid_argument("Can't use that many threads!");
 
     py::buffer_info labels_info = labels.request();
@@ -242,7 +251,7 @@ static void add_many_to_index(                                 //
             label_t label = *reinterpret_cast<label_t const*>(labels_data + task_idx * labels_info.strides[0]);
             f8_bits_t const* vector =
                 reinterpret_cast<f8_bits_t const*>(vectors_data + task_idx * vectors_info.strides[0]);
-            index.add(label, vector, config);
+            index.add(label, vector, config).error.raise();
         });
     else if (vectors_info.format == "e")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -252,7 +261,7 @@ static void add_many_to_index(                                 //
             label_t label = *reinterpret_cast<label_t const*>(labels_data + task_idx * labels_info.strides[0]);
             f16_bits_t const* vector =
                 reinterpret_cast<f16_bits_t const*>(vectors_data + task_idx * vectors_info.strides[0]);
-            index.add(label, vector, config);
+            index.add(label, vector, config).error.raise();
         });
     else if (vectors_info.format == "f" || vectors_info.format == "f4" || vectors_info.format == "<f4")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -261,7 +270,7 @@ static void add_many_to_index(                                 //
             config.thread = thread_idx;
             label_t label = *reinterpret_cast<label_t const*>(labels_data + task_idx * labels_info.strides[0]);
             float const* vector = reinterpret_cast<float const*>(vectors_data + task_idx * vectors_info.strides[0]);
-            index.add(label, vector, config);
+            index.add(label, vector, config).error.raise();
         });
     else if (vectors_info.format == "d" || vectors_info.format == "f8" || vectors_info.format == "<f8")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -270,13 +279,64 @@ static void add_many_to_index(                                 //
             config.thread = thread_idx;
             label_t label = *reinterpret_cast<label_t const*>(labels_data + task_idx * labels_info.strides[0]);
             double const* vector = reinterpret_cast<double const*>(vectors_data + task_idx * vectors_info.strides[0]);
-            index.add(label, vector, config);
+            index.add(label, vector, config).error.raise();
         });
     else
         throw std::invalid_argument("Incompatible scalars in the vectors matrix!");
 }
 
-static py::tuple search_one_in_index(punned_py_t& index, py::buffer vector, std::size_t wanted, bool exact) {
+static void add_many_to_bits_index(                                //
+    bits_index_py_t& index, py::buffer labels, py::buffer vectors, //
+    bool copy, std::size_t threads) {
+
+    if (index.limits().threads_add < threads)
+        throw std::invalid_argument("Can't use that many threads!");
+
+    py::buffer_info labels_info = labels.request();
+    py::buffer_info vectors_info = vectors.request();
+
+    if (labels_info.format != py::format_descriptor<label_t>::format())
+        throw std::invalid_argument("Incompatible label type!");
+
+    if (labels_info.ndim != 1)
+        throw std::invalid_argument("Labels must be placed in a single-dimensional array!");
+
+    if (vectors_info.ndim != 2)
+        throw std::invalid_argument("Expects a matrix of vectors to add!");
+
+    Py_ssize_t labels_count = labels_info.shape[0];
+    Py_ssize_t vectors_count = vectors_info.shape[0];
+    Py_ssize_t vectors_dimensions = vectors_info.shape[1];
+    if (vectors_dimensions != static_cast<Py_ssize_t>(index.numpy_words_))
+        throw std::invalid_argument("The number of vector dimensions doesn't match!");
+
+    if (labels_count != vectors_count)
+        throw std::invalid_argument("Number of labels and vectors must match!");
+
+    if (index.size() + vectors_count >= index.capacity())
+        index.reserve(ceil2(index.size() + vectors_count));
+
+    char const* vectors_data = reinterpret_cast<char const*>(vectors_info.ptr);
+    char const* labels_data = reinterpret_cast<char const*>(labels_info.ptr);
+
+    // https://docs.python.org/3/library/struct.html#format-characters
+    if (vectors_info.format != "B")
+        throw std::invalid_argument("Incompatible scalars in the vectors matrix!");
+
+    multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
+        add_config_t config;
+        config.store_vector = copy;
+        config.thread = thread_idx;
+        label_t label = *reinterpret_cast<label_t const*>(labels_data + task_idx * labels_info.strides[0]);
+        bits_numpy_word_t const* vector =
+            reinterpret_cast<bits_numpy_word_t const*>(vectors_data + task_idx * vectors_info.strides[0]);
+        bits_native_word_t* vector_words = index.word_aligned_buffer_.data() + index.native_words_ * thread_idx;
+        std::memcpy(vector_words, vector, vectors_dimensions);
+        index.add(label, {vector_words, index.native_words_}, config).error.raise();
+    });
+}
+
+static py::tuple search_one_in_index(punned_index_py_t& index, py::buffer vector, std::size_t wanted, bool exact) {
 
     py::buffer_info vector_info = vector.request();
     Py_ssize_t vector_dimensions = vector_info.shape[0];
@@ -294,23 +354,23 @@ static py::tuple search_one_in_index(punned_py_t& index, py::buffer vector, std:
     config.exact = exact;
 
     // https://docs.python.org/3/library/struct.html#format-characters
-    if (vector_info.format == "c" || vector_info.format == "b")
-        count = index //
-                    .search(reinterpret_cast<f8_bits_t const*>(vector_data), wanted, config)
-                    .dump_to(&labels_py1d(0), &distances_py1d(0));
-    else if (vector_info.format == "e")
-        count = index //
-                    .search(reinterpret_cast<f16_bits_t const*>(vector_data), wanted, config)
-                    .dump_to(&labels_py1d(0), &distances_py1d(0));
-    else if (vector_info.format == "f" || vector_info.format == "f4" || vector_info.format == "<f4")
-        count = index //
-                    .search(reinterpret_cast<float const*>(vector_data), wanted, config)
-                    .dump_to(&labels_py1d(0), &distances_py1d(0));
-    else if (vector_info.format == "d" || vector_info.format == "f8" || vector_info.format == "<f8")
-        count = index //
-                    .search(reinterpret_cast<double const*>(vector_data), wanted, config)
-                    .dump_to(&labels_py1d(0), &distances_py1d(0));
-    else
+    if (vector_info.format == "c" || vector_info.format == "b") {
+        punned_search_result_t result = index.search(reinterpret_cast<f8_bits_t const*>(vector_data), wanted, config);
+        result.error.raise();
+        count = result.dump_to(&labels_py1d(0), &distances_py1d(0));
+    } else if (vector_info.format == "e") {
+        punned_search_result_t result = index.search(reinterpret_cast<f16_bits_t const*>(vector_data), wanted, config);
+        result.error.raise();
+        count = result.dump_to(&labels_py1d(0), &distances_py1d(0));
+    } else if (vector_info.format == "f" || vector_info.format == "f4" || vector_info.format == "<f4") {
+        punned_search_result_t result = index.search(reinterpret_cast<float const*>(vector_data), wanted, config);
+        result.error.raise();
+        count = result.dump_to(&labels_py1d(0), &distances_py1d(0));
+    } else if (vector_info.format == "d" || vector_info.format == "f8" || vector_info.format == "<f8") {
+        punned_search_result_t result = index.search(reinterpret_cast<double const*>(vector_data), wanted, config);
+        result.error.raise();
+        count = result.dump_to(&labels_py1d(0), &distances_py1d(0));
+    } else
         throw std::invalid_argument("Incompatible scalars in the query vector!");
 
     labels_py.resize(py_shape_t{static_cast<Py_ssize_t>(count)});
@@ -333,12 +393,12 @@ static py::tuple search_one_in_index(punned_py_t& index, py::buffer vector, std:
  *      3. array with match counts.
  */
 static py::tuple search_many_in_index( //
-    punned_py_t& index, py::buffer vectors, std::size_t wanted, bool exact, std::size_t threads) {
+    punned_index_py_t& index, py::buffer vectors, std::size_t wanted, bool exact, std::size_t threads) {
 
     if (wanted == 0)
         return py::tuple(3);
 
-    if (index.config().max_threads_add < threads)
+    if (index.limits().threads_add < threads)
         throw std::invalid_argument("Can't use that many threads!");
 
     py::buffer_info vectors_info = vectors.request();
@@ -367,8 +427,10 @@ static py::tuple search_many_in_index( //
             config.thread = thread_idx;
             config.exact = exact;
             f8_bits_t const* vector = (f8_bits_t const*)(vectors_data + task_idx * vectors_info.strides[0]);
-            counts_py1d(task_idx) = static_cast<Py_ssize_t>(
-                index.search(vector, wanted, config).dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
+            punned_search_result_t result = index.search(vector, wanted, config);
+            result.error.raise();
+            counts_py1d(task_idx) =
+                static_cast<Py_ssize_t>(result.dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
         });
     else if (vectors_info.format == "e")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -376,8 +438,10 @@ static py::tuple search_many_in_index( //
             config.thread = thread_idx;
             config.exact = exact;
             f16_bits_t const* vector = (f16_bits_t const*)(vectors_data + task_idx * vectors_info.strides[0]);
-            counts_py1d(task_idx) = static_cast<Py_ssize_t>(
-                index.search(vector, wanted, config).dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
+            punned_search_result_t result = index.search(vector, wanted, config);
+            result.error.raise();
+            counts_py1d(task_idx) =
+                static_cast<Py_ssize_t>(result.dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
         });
     else if (vectors_info.format == "f" || vectors_info.format == "f4" || vectors_info.format == "<f4")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -385,8 +449,10 @@ static py::tuple search_many_in_index( //
             config.thread = thread_idx;
             config.exact = exact;
             float const* vector = (float const*)(vectors_data + task_idx * vectors_info.strides[0]);
-            counts_py1d(task_idx) = static_cast<Py_ssize_t>(
-                index.search(vector, wanted, config).dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
+            punned_search_result_t result = index.search(vector, wanted, config);
+            result.error.raise();
+            counts_py1d(task_idx) =
+                static_cast<Py_ssize_t>(result.dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
         });
     else if (vectors_info.format == "d" || vectors_info.format == "f8" || vectors_info.format == "<f8")
         multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
@@ -394,8 +460,10 @@ static py::tuple search_many_in_index( //
             config.thread = thread_idx;
             config.exact = exact;
             double const* vector = (double const*)(vectors_data + task_idx * vectors_info.strides[0]);
-            counts_py1d(task_idx) = static_cast<Py_ssize_t>(
-                index.search(vector, wanted, config).dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
+            punned_search_result_t result = index.search(vector, wanted, config);
+            result.error.raise();
+            counts_py1d(task_idx) =
+                static_cast<Py_ssize_t>(result.dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
         });
     else
         throw std::invalid_argument("Incompatible scalars in the query matrix!");
@@ -407,10 +475,74 @@ static py::tuple search_many_in_index( //
     return results;
 }
 
+/**
+ *  @param vectors Matrix of vectors to search for.
+ *  @param wanted Number of matches per request.
+ *
+ *  @return Tuple with:
+ *      1. matrix of neighbors,
+ *      2. matrix of distances,
+ *      3. array with match counts.
+ */
+static py::tuple search_many_in_bits_index( //
+    bits_index_py_t& index, py::buffer vectors, std::size_t wanted, bool exact, std::size_t threads) {
+
+    if (wanted == 0)
+        return py::tuple(3);
+
+    if (index.limits().threads_add < threads)
+        throw std::invalid_argument("Can't use that many threads!");
+
+    py::buffer_info vectors_info = vectors.request();
+    // if (vectors_info.ndim == 1)
+    //     return search_one_in_index(index, vectors, wanted, exact);
+    if (vectors_info.ndim != 2)
+        throw std::invalid_argument("Expects a matrix of vectors to add!");
+
+    Py_ssize_t vectors_count = vectors_info.shape[0];
+    Py_ssize_t vectors_dimensions = vectors_info.shape[1];
+    char const* vectors_data = reinterpret_cast<char const*>(vectors_info.ptr);
+    if (vectors_dimensions != static_cast<Py_ssize_t>(index.numpy_words_))
+        throw std::invalid_argument("The number of vector dimensions doesn't match!");
+
+    py::array_t<label_t> labels_py({vectors_count, static_cast<Py_ssize_t>(wanted)});
+    py::array_t<distance_t> distances_py({vectors_count, static_cast<Py_ssize_t>(wanted)});
+    py::array_t<Py_ssize_t> counts_py(vectors_count);
+    auto labels_py2d = labels_py.mutable_unchecked<2>();
+    auto distances_py2d = distances_py.mutable_unchecked<2>();
+    auto counts_py1d = counts_py.mutable_unchecked<1>();
+
+    // https://docs.python.org/3/library/struct.html#format-characters
+    if (vectors_info.format != "B")
+        throw std::invalid_argument("Incompatible scalars in the query matrix!");
+
+    multithreaded(threads, vectors_count, [&](std::size_t thread_idx, std::size_t task_idx) {
+        search_config_t config;
+        config.thread = thread_idx;
+        config.exact = exact;
+
+        bits_numpy_word_t const* vector =
+            reinterpret_cast<bits_numpy_word_t const*>(vectors_data + task_idx * vectors_info.strides[0]);
+        bits_native_word_t* vector_words = index.word_aligned_buffer_.data() + index.native_words_ * thread_idx;
+        std::memcpy(vector_words, vector, vectors_dimensions);
+
+        bits_search_result_t result = index.search({vector_words, index.native_words_}, wanted, config);
+        result.error.raise();
+        counts_py1d(task_idx) =
+            static_cast<Py_ssize_t>(result.dump_to(&labels_py2d(task_idx, 0), &distances_py2d(task_idx, 0)));
+    });
+
+    py::tuple results(3);
+    results[0] = labels_py;
+    results[1] = distances_py;
+    results[2] = counts_py;
+    return results;
+}
+
 // clang-format off
-template <typename index_at> void save_index(index_at const& index, std::string const& path) { index.save(path.c_str()); }
-template <typename index_at> void load_index(index_at& index, std::string const& path) { index.load(path.c_str()); }
-template <typename index_at> void view_index(index_at& index, std::string const& path) { index.view(path.c_str()); }
+template <typename index_at> void save_index(index_at const& index, std::string const& path) { index.save(path.c_str()).error.raise(); }
+template <typename index_at> void load_index(index_at& index, std::string const& path) { index.load(path.c_str()).error.raise(); }
+template <typename index_at> void view_index(index_at& index, std::string const& path) { index.view(path.c_str()).error.raise(); }
 template <typename index_at> void clear_index(index_at& index) { index.clear(); }
 template <typename index_at> std::size_t get_expansion_add(index_at const &index) { return index.config().expansion_add; }
 template <typename index_at> std::size_t get_expansion_search(index_at const &index) { return index.config().expansion_search; }
@@ -442,9 +574,9 @@ void validate_set(py::array_t<set_member_t> const& set) {
         throw std::invalid_argument("Set must be deduplicated!");
 }
 
-inline std::uint64_t hash_ror64(std::uint64_t v, int r) noexcept { return (v >> r) | (v << (64 - r)); }
+inline bits_native_word_t hash_ror64(bits_native_word_t v, int r) noexcept { return (v >> r) | (v << (64 - r)); }
 
-inline std::uint64_t hash(std::uint64_t v) noexcept {
+inline bits_native_word_t hash(bits_native_word_t v) noexcept {
     v ^= hash_ror64(v, 25) ^ hash_ror64(v, 50);
     v *= 0xA24BAED4963EE407UL;
     v ^= hash_ror64(v, 24) ^ hash_ror64(v, 49);
@@ -453,34 +585,71 @@ inline std::uint64_t hash(std::uint64_t v) noexcept {
 }
 
 template <typename scalar_at>
-inline void hash_typed_buffer(hash_index_py_t& index, py::buffer_info const& vector_info) noexcept {
-    char const* vector_data = reinterpret_cast<char const*>(vector_info.ptr);
-    Py_ssize_t vector_dimensions = vector_info.shape[0];
-    Py_ssize_t vector_stride = vector_info.strides[0];
-    std::memset(index.buffer_.data(), 0, index.words_ * sizeof(hash_word_t));
+void hash_typed_row(                                                             //
+    byte_t const* scalars, std::size_t scalar_stride, std::size_t scalars_count, //
+    bits_numpy_word_t* hashes, std::size_t bits) noexcept {
+
+    std::size_t words = divide_round_up<8>(bits);
+    for (std::size_t i = 0; i != scalars_count; ++i) {
+        scalar_at scalar;
+        std::memcpy(&scalar, scalars + i * scalar_stride, sizeof(scalar_at));
+        bits_native_word_t scalar_hash = hash(scalar);
+        hashes[scalar_hash & (words - 1)] |= std::uint8_t(1) << (scalar_hash % 8);
+    }
+}
 
-    for (std::size_t i = 0; i != static_cast<std::size_t>(vector_dimensions); ++i) {
-        scalar_at scalar = *reinterpret_cast<scalar_at const*>(vector_data + i * vector_stride);
-        std::uint64_t scalar_hash = hash(scalar);
-        index.buffer_[scalar_hash % index.words_] |= hash_word_t(1) << (scalar_hash % bits_per_hash_word_k);
+#if 0
+template <typename scalar_at>
+py::array_t<bits_numpy_word_t> hash_typed_buffer(py::buffer_info const& info, std::size_t bits) {
+    byte_t const* data = reinterpret_cast<byte_t const*>(info.ptr);
+    Py_ssize_t elements_per_row = info.shape[0];
+    Py_ssize_t elements_stride = info.strides[0];
+    Py_ssize_t words_per_row = divide_round_up<std::size_t>(bits, 8);
+
+    if (info.ndim == 2) {
+        Py_ssize_t rows_count = info.shape[1];
+        Py_ssize_t rows_stride = info.strides[1];
+        auto hashes_shape = py_shape_t{rows_count, words_per_row};
+        auto hashes_py = py::array_t<bits_numpy_word_t>(hashes_shape);
+        auto hashes_proxy = hashes_py.mutable_unchecked<2>();
+
+        for (Py_ssize_t i = 0; i != rows_count; ++i)
+            hash_typed_row(                                                                                 //
+                data + i * rows_stride, hashes_proxy.stride(1), static_cast<std::size_t>(elements_per_row), //
+                &hashes_proxy(i, 0), bits);
+
+        return hashes_py;
+    } else {
+        auto hashes_shape = py_shape_t{words_per_row};
+        auto hashes_py = py::array_t<bits_numpy_word_t>(hashes_shape);
+        auto hashes_proxy = hashes_py.mutable_unchecked<1>();
+
+        hash_typed_row(                                                               //
+            data, hashes_info.strides[0], static_cast<std::size_t>(elements_per_row), //
+            &hashes_proxy(0), bits);
+
+        return hashes_py;
     }
 }
 
-void hash_buffer(hash_index_py_t& index, py::buffer vector) {
+py::array_t<bits_numpy_word_t> hash_buffer(py::buffer vector, std::size_t bits) {
+    if (std::bitset<64>(bits).count() == 1)
+        throw std::invalid_argument("Number of bits must be a power of two!");
     py::buffer_info info = vector.request();
-    if (info.ndim != 1)
-        throw std::invalid_argument("Array can't be multi-dimensional!");
+    if (info.ndim > 2)
+        throw std::invalid_argument("Only one or two-dimensional arrays are supported!");
 
     // https://docs.python.org/3/library/struct.html#format-characters
     if (info.format == "h" || info.format == "H")
-        return hash_typed_buffer<std::uint16_t>(index, info);
+        return hash_typed_buffer<std::uint16_t>(info, bits);
     else if (info.format == "i" || info.format == "I" || info.format == "l" || info.format == "L")
-        return hash_typed_buffer<std::uint32_t>(index, info);
+        return hash_typed_buffer<std::uint32_t>(info, bits);
     else if (info.format == "q" || info.format == "Q" || info.format == "n" || info.format == "N")
-        return hash_typed_buffer<std::uint64_t>(index, info);
+        return hash_typed_buffer<std::uint64_t>(info, bits);
     else
         throw std::invalid_argument("Array elements must be 16, 32, or 64 bit hashable integers!");
 }
+#endif
 
 PYBIND11_MODULE(compiled, m) {
     m.doc() = "Smaller & Faster Single-File Vector Search Engine from Unum";
@@ -489,14 +658,25 @@ PYBIND11_MODULE(compiled, m) {
     m.attr("DEFAULT_EXPANSION_ADD") = py::int_(default_expansion_add());
     m.attr("DEFAULT_EXPANSION_SEARCH") = py::int_(default_expansion_search());
 
-    auto i = py::class_<punned_py_t>(m, "Index");
+    py::enum_<common_metric_kind_t>(m, "MetricKind")
+        .value("Unknown", common_metric_kind_t::unknown_k)
+        .value("IP", common_metric_kind_t::ip_k)
+        .value("Cos", common_metric_kind_t::cos_k)
+        .value("L2sq", common_metric_kind_t::l2sq_k)
+        .value("Haversine", common_metric_kind_t::haversine_k)
+        .value("Pearson", common_metric_kind_t::pearson_k)
+        .value("Jaccard", common_metric_kind_t::jaccard_k)
+        .value("BitwiseHamming", common_metric_kind_t::bitwise_hamming_k)
+        .value("BitwiseTanimoto", common_metric_kind_t::bitwise_tanimoto_k)
+        .value("BitwiseSorensen", common_metric_kind_t::bitwise_sorensen_k);
+
+    auto i = py::class_<punned_index_py_t>(m, "Index");
 
     i.def(py::init(&make_index),                                    //
           py::kw_only(),                                            //
           py::arg("ndim") = 0,                                      //
-          py::arg("capacity") = 0,                                  //
           py::arg("dtype") = std::string("f32"),                    //
-          py::arg("metric") = std::string("ip"),                    //
+          py::arg("metric") = common_metric_kind_t::ip_k,           //
           py::arg("connectivity") = default_connectivity(),         //
           py::arg("expansion_add") = default_expansion_add(),       //
           py::arg("expansion_search") = default_expansion_search(), //
@@ -530,29 +710,69 @@ PYBIND11_MODULE(compiled, m) {
         py::arg("threads") = 0           //
     );
 
-    i.def("__len__", &punned_py_t::size);
-    i.def_property_readonly("size", &punned_py_t::size);
-    i.def_property_readonly("ndim", &punned_py_t::dimensions);
-    i.def_property_readonly("connectivity", &punned_py_t::connectivity);
-    i.def_property_readonly("capacity", &punned_py_t::capacity);
+    i.def("__len__", &punned_index_py_t::size);
+    i.def_property_readonly("size", &punned_index_py_t::size);
+    i.def_property_readonly("ndim", &punned_index_py_t::dimensions);
+    i.def_property_readonly("connectivity", &punned_index_py_t::connectivity);
+    i.def_property_readonly("capacity", &punned_index_py_t::capacity);
     i.def_property_readonly( //
-        "dtype", [](punned_py_t const& index) -> std::string { return accuracy_name(index.accuracy()); });
-    i.def_property_readonly("memory_usage", &punned_py_t::memory_usage);
+        "dtype", [](punned_index_py_t const& index) -> std::string { return accuracy_name(index.accuracy()); });
+    i.def_property_readonly("memory_usage", &punned_index_py_t::memory_usage);
+
+    i.def_property("expansion_add", &get_expansion_add<punned_index_py_t>, &punned_index_py_t::change_expansion_add);
+    i.def_property("expansion_search", &get_expansion_search<punned_index_py_t>,
+                   &punned_index_py_t::change_expansion_search);
+
+    i.def("save", &save_index<punned_index_py_t>, py::arg("path"));
+    i.def("load", &load_index<punned_index_py_t>, py::arg("path"));
+    i.def("view", &view_index<punned_index_py_t>, py::arg("path"));
+    i.def("clear", &clear_index<punned_index_py_t>);
+
+    auto bi = py::class_<bits_index_py_t>(m, "BitsIndex");
+
+    bi.def(                                                          //
+        py::init(&make_hash_index),                                  //
+        py::kw_only(),                                               //
+        py::arg("bits"),                                             //
+        py::arg("metric") = common_metric_kind_t::bitwise_hamming_k, //
+        py::arg("connectivity") = default_connectivity(),            //
+        py::arg("expansion_add") = default_expansion_add(),          //
+        py::arg("expansion_search") = default_expansion_search()     //
+    );
+
+    bi.def( //
+        "add",
+        &add_many_to_bits_index, //
+        py::arg("label"),        //
+        py::arg("array"),        //
+        py::kw_only(),           //
+        py::arg("copy") = true,  //
+        py::arg("threads") = 0   //
+    );
 
-    i.def_property("expansion_add", &get_expansion_add<punned_py_t>, &punned_py_t::change_expansion_add);
-    i.def_property("expansion_search", &get_expansion_search<punned_py_t>, &punned_py_t::change_expansion_search);
+    bi.def(                                   //
+        "search", &search_many_in_bits_index, //
+        py::arg("query"),                     //
+        py::arg("count") = 10,                //
+        py::arg("exact") = false,             //
+        py::arg("threads") = 0                //
+    );
+
+    bi.def("__len__", &bits_index_py_t::size);
+    bi.def_property_readonly("size", &bits_index_py_t::size);
+    bi.def_property_readonly("connectivity", &bits_index_py_t::connectivity);
+    bi.def_property_readonly("capacity", &bits_index_py_t::capacity);
 
-    i.def("save", &save_index<punned_py_t>, py::arg("path"));
-    i.def("load", &load_index<punned_py_t>, py::arg("path"));
-    i.def("view", &view_index<punned_py_t>, py::arg("path"));
-    i.def("clear", &clear_index<punned_py_t>);
+    bi.def("save", &save_index<bits_index_py_t>, py::arg("path"));
+    bi.def("load", &load_index<bits_index_py_t>, py::arg("path"));
+    bi.def("view", &view_index<bits_index_py_t>, py::arg("path"));
+    bi.def("clear", &clear_index<bits_index_py_t>);
 
     auto si = py::class_<sets_index_py_t>(m, "SetsIndex");
 
     si.def(                                                      //
         py::init(&make_sets_index),                              //
         py::kw_only(),                                           //
-        py::arg("capacity") = 0,                                 //
         py::arg("connectivity") = default_connectivity(),        //
         py::arg("expansion_add") = default_expansion_add(),      //
         py::arg("expansion_search") = default_expansion_search() //
@@ -565,10 +785,11 @@ PYBIND11_MODULE(compiled, m) {
             if (index.size() + 1 >= index.capacity())
                 index.reserve(ceil2(index.size() + 1));
             auto proxy = set.unchecked<1>();
-            auto view = set_view_t{proxy.data(0), static_cast<std::size_t>(proxy.shape(0))};
+            auto view = set_view_t{&proxy(0), static_cast<std::size_t>(proxy.shape(0))};
+
             add_config_t config;
             config.store_vector = copy;
-            index.add(label, view, config);
+            index.add(label, view, config).error.raise();
         },                     //
         py::arg("label"),      //
         py::arg("set"),        //
@@ -581,10 +802,12 @@ PYBIND11_MODULE(compiled, m) {
         [](sets_index_py_t& index, py::array_t<set_member_t> set, std::size_t count) -> py::array_t<label_t> {
             validate_set(set);
             auto proxy = set.unchecked<1>();
-            auto view = set_view_t{proxy.data(0), static_cast<std::size_t>(proxy.shape(0))};
+            auto view = set_view_t{&proxy(0), static_cast<std::size_t>(proxy.shape(0))};
             auto labels_py = py::array_t<label_t>(py_shape_t{static_cast<Py_ssize_t>(count)});
             auto labels_proxy = labels_py.mutable_unchecked<1>();
-            auto found = index.search(view, count).dump_to(&labels_proxy(0), nullptr);
+            auto result = index.search(view, count);
+            result.error.raise();
+            auto found = result.dump_to(&labels_proxy(0));
             labels_py.resize(py_shape_t{static_cast<Py_ssize_t>(found)});
             return labels_py;
         },
@@ -601,54 +824,4 @@ PYBIND11_MODULE(compiled, m) {
     si.def("load", &load_index<sets_index_py_t>, py::arg("path"));
     si.def("view", &view_index<sets_index_py_t>, py::arg("path"));
     si.def("clear", &clear_index<sets_index_py_t>);
-
-    auto hi = py::class_<hash_index_py_t>(m, "HashIndex");
-
-    hi.def(                                                      //
-        py::init(&make_hash_index),                              //
-        py::kw_only(),                                           //
-        py::arg("bits"),                                         //
-        py::arg("capacity") = 0,                                 //
-        py::arg("connectivity") = default_connectivity(),        //
-        py::arg("expansion_add") = default_expansion_add(),      //
-        py::arg("expansion_search") = default_expansion_search() //
-    );
-
-    hi.def( //
-        "add",
-        [](hash_index_py_t& index, label_t label, py::buffer array) {
-            if (index.size() + 1 >= index.capacity())
-                index.reserve(ceil2(index.size() + 1));
-            hash_buffer(index, array);
-            index.add(label, index.buffer());
-        },                //
-        py::arg("label"), //
-        py::arg("array")  //
-    );
-
-    hi.def( //
-        "search",
-        [](hash_index_py_t& index, py::buffer array, std::size_t count) -> py::array_t<label_t> {
-            if (index.size() + 1 >= index.capacity())
-                index.reserve(ceil2(index.size() + 1));
-            hash_buffer(index, array);
-            auto labels_py = py::array_t<label_t>(py_shape_t{static_cast<Py_ssize_t>(count)});
-            auto labels_proxy = labels_py.mutable_unchecked<1>();
-            auto found = index.search(index.buffer(), count).dump_to(&labels_proxy(0), nullptr);
-            labels_py.resize(py_shape_t{static_cast<Py_ssize_t>(found)});
-            return labels_py;
-        },
-        py::arg("array"),     //
-        py::arg("count") = 10 //
-    );
-
-    hi.def("__len__", &hash_index_py_t::size);
-    hi.def_property_readonly("size", &hash_index_py_t::size);
-    hi.def_property_readonly("connectivity", &hash_index_py_t::connectivity);
-    hi.def_property_readonly("capacity", &hash_index_py_t::capacity);
-
-    hi.def("save", &save_index<hash_index_py_t>, py::arg("path"));
-    hi.def("load", &load_index<hash_index_py_t>, py::arg("path"));
-    hi.def("view", &view_index<hash_index_py_t>, py::arg("path"));
-    hi.def("clear", &clear_index<hash_index_py_t>);
 }