usearch 2.10.2 → 2.10.5

package/c/usearch.h

@@ -0,0 +1,356 @@
+#ifndef UNUM_USEARCH_H
+#define UNUM_USEARCH_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef USEARCH_EXPORT
+#if defined(_WIN32) && !defined(__MINGW32__)
+#define USEARCH_EXPORT __declspec(dllexport)
+#else
+#define USEARCH_EXPORT
+#endif
+#endif
+
+#include <stdbool.h> // `bool`
+#include <stddef.h>  // `size_t`
+#include <stdint.h>  // `uint64_t`
+
+USEARCH_EXPORT typedef void* usearch_index_t;
+USEARCH_EXPORT typedef uint64_t usearch_key_t;
+USEARCH_EXPORT typedef float usearch_distance_t;
+
+/**
+ *  @brief  Pointer to a null-terminated error message.
+ *          Returned error messages @b don't need to be deallocated.
+ */
+USEARCH_EXPORT typedef char const* usearch_error_t;
+
+/**
+ *  @brief  Type-punned callback for "metrics" or "distance functions",
+ *          that accepts pointers to two vectors and measures their @b dis-similarity.
+ */
+USEARCH_EXPORT typedef usearch_distance_t (*usearch_metric_t)(void const*, void const*);
+
+/**
+ *  @brief  Enumerator for the most common kinds of `usearch_metric_t`.
+ *          Those are supported out of the box, with SIMD-optimizations for most common hardware.
+ */
+USEARCH_EXPORT typedef enum usearch_metric_kind_t {
+    usearch_metric_unknown_k = 0,
+    usearch_metric_cos_k = 1,
+    usearch_metric_ip_k = 2,
+    usearch_metric_l2sq_k = 3,
+    usearch_metric_haversine_k = 4,
+    usearch_metric_divergence_k = 5,
+    usearch_metric_pearson_k = 6,
+    usearch_metric_jaccard_k = 7,
+    usearch_metric_hamming_k = 8,
+    usearch_metric_tanimoto_k = 9,
+    usearch_metric_sorensen_k = 10,
+} usearch_metric_kind_t;
+
+USEARCH_EXPORT typedef enum usearch_scalar_kind_t {
+    usearch_scalar_unknown_k = 0,
+    usearch_scalar_f32_k = 1,
+    usearch_scalar_f64_k = 2,
+    usearch_scalar_f16_k = 3,
+    usearch_scalar_i8_k = 4,
+    usearch_scalar_b1_k = 5,
+} usearch_scalar_kind_t;
+
+USEARCH_EXPORT typedef struct usearch_init_options_t {
+    /**
+     *  @brief The metric kind used for distance calculation between vectors.
+     */
+    usearch_metric_kind_t metric_kind;
+    /**
+     *  @brief The @b optional custom distance metric function used for distance calculation between vectors.
+     *  If the `metric_kind` is set to `usearch_metric_unknown_k`, this function pointer mustn't be `NULL`.
+     */
+    usearch_metric_t metric;
+    /**
+     *  @brief The scalar kind used for quantization of vector data during indexing.
+     */
+    usearch_scalar_kind_t quantization;
+    /**
+     *  @brief The number of dimensions in the vectors to be indexed.
+     *  Must be defined for most metrics, but can be avoided for `usearch_metric_haversine_k`.
+     */
+    size_t dimensions;
+    /**
+     *  @brief The @b optional connectivity parameter that limits connections-per-node in graph.
+     */
+    size_t connectivity;
+    /**
+     *  @brief The @b optional expansion factor used for index construction when adding vectors.
+     */
+    size_t expansion_add;
+    /**
+     *  @brief The @b optional expansion factor used for index construction during search operations.
+     */
+    size_t expansion_search;
+    /**
+     *  @brief When set allows multiple vectors to map to the same key.
+     */
+    bool multi;
+} usearch_init_options_t;
+
+/**
+ *  @brief Initializes a new instance of the index.
+ *  @param options Pointer to the `usearch_init_options_t` structure containing initialization options.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return A handle to the initialized USearch index, or `NULL` on failure.
+ */
+USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error);
+
+/**
+ *  @brief Frees the resources associated with the index.
+ *  @param[inout] index The handle to the USearch index to be freed.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_free(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reports expected file size after serialization.
+ *  @param[in] index The handle to the USearch index to be serialized.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT size_t usearch_serialized_length(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Saves the index to a file.
+ *  @param[in] index The handle to the USearch index to be serialized.
+ *  @param[in] path The file path where the index will be saved.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_save(usearch_index_t index, char const* path, usearch_error_t* error);
+
+/**
+ *  @brief Loads the index from a file.
+ *  @param[inout] index The handle to the USearch index to be populated from path.
+ *  @param[in] path The file path from where the index will be loaded.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_load(usearch_index_t index, char const* path, usearch_error_t* error);
+
+/**
+ *  @brief Creates a view of the index from a file without copying it into memory.
+ *  @param[inout] index The handle to the USearch index to be populated with a file view.
+ *  @param[in] path The file path from where the view will be created.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_view(usearch_index_t index, char const* path, usearch_error_t* error);
+
+/**
+ *  @brief Loads index metadata from a file.
+ *  @param[in] path The file path from where the index will be loaded.
+ *  @param[out] options Pointer to the `usearch_init_options_t` structure to be populated.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return A handle to the initialized USearch index, or `NULL` on failure.
+ */
+USEARCH_EXPORT void usearch_metadata(char const* path, usearch_init_options_t* options, usearch_error_t* error);
+
+/**
+ *  @brief Saves the index to an in-memory buffer.
+ *  @param[in] index The handle to the USearch index to be serialized.
+ *  @param[in] buffer The in-memory continuous buffer where the index will be saved.
+ *  @param[in] length The length of the buffer in bytes.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_save_buffer(usearch_index_t index, void* buffer, size_t length, usearch_error_t* error);
+
+/**
+ *  @brief Loads the index from an in-memory buffer.
+ *  @param[inout] index The handle to the USearch index to be populated from buffer.
+ *  @param[in] buffer The in-memory continuous buffer from where the index will be loaded.
+ *  @param[in] length The length of the buffer in bytes.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_load_buffer(usearch_index_t index, void const* buffer, size_t length,
+                                        usearch_error_t* error);
+
+/**
+ *  @brief Creates a view of the index from an in-memory buffer without copying it into memory.
+ *  @param[inout] index The handle to the USearch index to be populated with a buffer view.
+ *  @param[in] buffer The in-memory continuous buffer from where the view will be created.
+ *  @param[in] length The length of the buffer in bytes.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_view_buffer(usearch_index_t index, void const* buffer, size_t length,
+                                        usearch_error_t* error);
+
+/**
+ *  @brief Loads index metadata from an in-memory buffer.
+ *  @param[in] buffer The in-memory continuous buffer from where the view will be created.
+ *  @param[out] options Pointer to the `usearch_init_options_t` structure to be populated.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return A handle to the initialized USearch index, or `NULL` on failure.
+ */
+USEARCH_EXPORT void usearch_metadata_buffer(void const* buffer, size_t length, usearch_init_options_t* options,
+                                            usearch_error_t* error);
+
+/**
+ *  @brief Reports the current size (number of vectors) of the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT size_t usearch_size(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reports the current capacity (number of vectors) of the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT size_t usearch_capacity(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reports the current dimensions of the vectors in the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reports the current connectivity of the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t index, usearch_error_t* error);
+
+/**
+ *  @brief Reserves memory for a specified number of incoming vectors.
+ *  @param[inout] index The handle to the USearch index to be resized.
+ *  @param[in] capacity The desired total capacity including current size.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error);
+
+/**
+ *  @brief Adds a vector with a key to the index.
+ *  @param[inout] index The handle to the USearch index to be populated.
+ *  @param[in] key The key associated with the vector.
+ *  @param[in] vector Pointer to the vector data.
+ *  @param[in] vector_kind The scalar type used in the vector data.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_add(              //
+    usearch_index_t index, usearch_key_t key, //
+    void const* vector, usearch_scalar_kind_t vector_kind, usearch_error_t* error);
+
+/**
+ *  @brief Checks if the index contains a vector with a specific key.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] key The key to be checked.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return `true` if the index contains the vector with the given key, `false` otherwise.
+ */
+USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_key_t key, usearch_error_t* error);
+
+/**
+ *  @brief Counts the number of entries in the index under a specific key.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] key The key to be checked.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of vectors found under that key.
+ */
+USEARCH_EXPORT size_t usearch_count(usearch_index_t index, usearch_key_t, usearch_error_t* error);
+
+/**
+ *  @brief Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to query.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] query_vector Pointer to the query vector data.
+ *  @param[in] query_kind The scalar type used in the query vector data.
+ *  @param[in] count Upper bound on the number of neighbors to search, the "k" in "kANN".
+ *  @param[out] keys Output buffer for up to `count` nearest neighbors keys.
+ *  @param[out] distances Output buffer for up to `count` distances to nearest neighbors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of found matches.
+ */
+USEARCH_EXPORT size_t usearch_search(                           //
+    usearch_index_t index,                                      //
+    void const* query_vector, usearch_scalar_kind_t query_kind, //
+    size_t count, usearch_key_t* keys, usearch_distance_t* distances, usearch_error_t* error);
+
+/**
+ *  @brief Retrieves the vector associated with the given key from the index.
+ *  @param[in] index The handle to the USearch index to be queried.
+ *  @param[in] key The key of the vector to retrieve.
+ *  @param[out] vector Pointer to the memory where the vector data will be copied.
+ *  @param[in] count Number of vectors that can be fitted into `vector` for multi-vector entries.
+ *  @param[in] vector_kind The scalar type used in the vector data.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of vectors found under that name and exported to `vector`.
+ */
+USEARCH_EXPORT size_t usearch_get(                          //
+    usearch_index_t index, usearch_key_t key, size_t count, //
+    void* vector, usearch_scalar_kind_t vector_kind, usearch_error_t* error);
+
+/**
+ *  @brief Removes the vector associated with the given key from the index.
+ *  @param[inout] index The handle to the USearch index to be modified.
+ *  @param[in] key The key of the vector to be removed.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of vectors found under that name and dropped from the index.
+ */
+USEARCH_EXPORT size_t usearch_remove(usearch_index_t index, usearch_key_t key, usearch_error_t* error);
+
+/**
+ *  @brief Renames the vector to map to a different key.
+ *  @param[inout] index The handle to the USearch index to be modified.
+ *  @param[in] from The key of the vector to be renamed.
+ *  @param[in] to New key for found entry.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of vectors found under that name and renamed.
+ */
+USEARCH_EXPORT size_t usearch_rename(usearch_index_t index, usearch_key_t from, usearch_key_t to,
+                                     usearch_error_t* error);
+
+/**
+ *  @brief Computes the distance between two equi-dimensional vectors.
+ *  @param[in] vector_first The first vector for comparison.
+ *  @param[in] vector_second The second vector for comparison.
+ *  @param[in] scalar_kind The scalar type used in the vectors.
+ *  @param[in] dimensions The number of dimensions in each vector.
+ *  @param[in] metric_kind The metric kind used for distance calculation between vectors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Distance between given vectors.
+ */
+USEARCH_EXPORT usearch_distance_t usearch_distance(       //
+    void const* vector_first, void const* vector_second,  //
+    usearch_scalar_kind_t scalar_kind, size_t dimensions, //
+    usearch_metric_kind_t metric_kind, usearch_error_t* error);
+
+/**
+ *  @brief Multi-threaded exact nearest neighbors search for equi-dimensional vectors.
+ *  @param[in] dataset Pointer to the first scalar of the dataset matrix.
+ *  @param[in] queries Pointer to the first scalar of the queries matrix.
+ *  @param[in] dataset_size Number of vectors in the `dataset`.
+ *  @param[in] queries_size Number of vectors in the `queries` set.
+ *  @param[in] dataset_stride Number of bytes between starts of consecutive vectors in `dataset`.
+ *  @param[in] queries_stride Number of bytes between starts of consecutive vectors in `queries`.
+ *  @param[in] scalar_kind The scalar type used in the vectors.
+ *  @param[in] dimensions The number of dimensions in each vector.
+ *  @param[in] metric_kind The metric kind used for distance calculation between vectors.
+ *  @param[in] count Upper bound on the number of neighbors to search, the "k" in "kANN".
+ *  @param[in] threads Upper bound for the number of CPU threads to use.
+ *  @param[out] keys Output buffer for up to `count` nearest neighbors keys.
+ *  @param[out] distances Output buffer for up to `count` distances to nearest neighbors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of found matches.
+ */
+USEARCH_EXPORT void usearch_exact_search(                            //
+    void const* dataset, size_t dataset_size, size_t dataset_stride, //
+    void const* queries, size_t queries_size, size_t queries_stride, //
+    usearch_scalar_kind_t scalar_kind, size_t dimensions,            //
+    usearch_metric_kind_t metric_kind, size_t count, size_t threads, //
+    usearch_key_t* keys, size_t keys_stride,                         //
+    usearch_distance_t* distances, size_t distances_stride,          //
+    usearch_error_t* error);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // UNUM_USEARCH_H

package/cmake/clipp.cmake

@@ -0,0 +1,7 @@
+include(FetchContent)
+FetchContent_Declare(
+    clipp
+    GIT_REPOSITORY https://github.com/muellan/clipp
+    GIT_TAG v1.2.3
+)
+FetchContent_MakeAvailable(clipp)

package/cmake/config.cmake.in

@@ -0,0 +1,15 @@
+include(FindPackageHandleStandardArgs)
+set(${CMAKE_FIND_PACKAGE_NAME}_CONFIG ${CMAKE_CURRENT_LIST_FILE})
+find_package_handle_standard_args(@PROJECT_NAME@ CONFIG_MODE)
+
+if(NOT TARGET @PROJECT_NAME@::@USEARCH_TARGET_NAME@)
+    include("${CMAKE_CURRENT_LIST_DIR}/@USEARCH_TARGETS_EXPORT_NAME@.cmake")
+    if((NOT TARGET @USEARCH_TARGET_NAME@) AND
+       (NOT @PROJECT_NAME@_FIND_VERSION OR
+        @PROJECT_NAME@_FIND_VERSION VERSION_LESS 3.2.0))
+        add_library(@USEARCH_TARGET_NAME@ INTERFACE IMPORTED)
+        set_target_properties(@USEARCH_TARGET_NAME@ PROPERTIES
+            INTERFACE_LINK_LIBRARIES @PROJECT_NAME@::@USEARCH_TARGET_NAME@
+        )
+    endif()
+endif()

package/cmake/emscripten.cmake

@@ -0,0 +1,8 @@
+include(FetchContent)
+FetchContent_Declare(
+    emscripten
+    GIT_REPOSITORY https://github.com/emscripten-core/emscripten
+    GIT_TAG main
+)
+FetchContent_MakeAvailable(emscripten)
+include_directories(${emscripten_SOURCE_DIR}/include)

package/cmake/jemalloc.cmake

@@ -0,0 +1,62 @@
+include(ExternalProject)
+set(JEMALLOC_DISABLE_TLS)
+
+if (${USTORE_BUILD_SDK_PYTHON})
+    set(JEMALLOC_DISABLE_TLS --disable-initial-exec-tls)
+endif ()
+
+if (${USTORE_REBUILD_JEMALLOC})
+    set(JEMALLOC_PREFIX_DIR ${CMAKE_BINARY_DIR}/_deps/jemalloc)
+    set(JEMALLOC_SRC_DIR ${JEMALLOC_PREFIX_DIR}/src/jemalloc)
+    set(JEMALLOC_INSTALL_DIR ${JEMALLOC_PREFIX_DIR}/install)
+    set(JEMALLOC_DEPENDENCY jemalloc)
+
+    ExternalProject_Add(
+        jemalloc
+        GIT_REPOSITORY https://github.com/jemalloc/jemalloc.git
+        GIT_TAG 5.3.0
+        PREFIX ${JEMALLOC_PREFIX_DIR}
+        CONFIGURE_COMMAND
+            echo Configuring jemalloc && cd ${JEMALLOC_SRC_DIR} && ./autogen.sh && ./configure
+            --prefix=${JEMALLOC_INSTALL_DIR} --enable-prof ${JEMALLOC_DISABLE_TLS} # --with-jemalloc-prefix=je_
+        BUILD_COMMAND echo Building jemalloc && cd ${JEMALLOC_SRC_DIR} && make install_lib_static install_include
+        INSTALL_COMMAND ""
+        UPDATE_COMMAND ""
+    )
+
+    # Create libjemalloc and libjemalloc_pic targets to be used as dependencies
+    add_library(libjemalloc STATIC IMPORTED GLOBAL)
+    add_library(libjemalloc_pic STATIC IMPORTED GLOBAL)
+
+    set_property(TARGET libjemalloc PROPERTY IMPORTED_LOCATION ${JEMALLOC_INSTALL_DIR}/lib/libjemalloc.a)
+    set_property(TARGET libjemalloc_pic PROPERTY IMPORTED_LOCATION ${JEMALLOC_INSTALL_DIR}/lib/libjemalloc_pic.a)
+
+    link_libraries(-Wl,--no-as-needed)
+    link_libraries(dl ${libjemalloc_pic})
+
+    # Export the include directory path.
+    set(JEMALLOC_SOURCE_DIR ${JEMALLOC_INSTALL_DIR})
+    set(JEMALLOC_LIBRARIES ${JEMALLOC_INSTALL_DIR}/lib/libjemalloc_pic.a ${JEMALLOC_INSTALL_DIR}/lib/libjemalloc.a)
+
+    include_directories(${JEMALLOC_SOURCE_DIR}/include)
+
+else ()
+    find_path(JEMALLOC_ROOT_DIR NAMES include/jemalloc/jemalloc.h)
+
+    find_library(
+        JEMALLOC_LIBRARIES
+        NAMES jemalloc
+        HINTS ${JEMALLOC_ROOT_DIR}/lib
+    )
+
+    find_path(
+        JEMALLOC_INCLUDE_DIR
+        NAMES jemalloc/jemalloc.h
+        HINTS ${JEMALLOC_ROOT_DIR}/include
+    )
+
+    include(FindPackageHandleStandardArgs)
+    find_package_handle_standard_args(JeMalloc DEFAULT_MSG JEMALLOC_LIBRARIES JEMALLOC_INCLUDE_DIR)
+
+    mark_as_advanced(JEMALLOC_ROOT_DIR JEMALLOC_LIBRARIES JEMALLOC_INCLUDE_DIR)
+endif ()

package/cmake/pkg-config.pc.in

@@ -0,0 +1,4 @@
+Name: ${PROJECT_NAME}
+Description: Smaller & Faster Single-File Vector Search Engine from Unum
+Version: ${PROJECT_VERSION}
+Cflags: -I${CMAKE_INSTALL_FULL_INCLUDEDIR}

package/cmake/usearchConfigVersion.cmake.in

@@ -0,0 +1,20 @@
+# This is essentially cmake's BasicConfigVersion-SameMajorVersion.cmake.in but
+# without the 32/64-bit check.  Since USearch is a header-only library, it doesn't
+# matter if it was built on a different platform than what it is used on (see
+# https://github.com/nlohmann/json/issues/1697).
+set(PACKAGE_VERSION "@PROJECT_VERSION@")
+
+if(PACKAGE_VERSION VERSION_LESS PACKAGE_FIND_VERSION)
+  set(PACKAGE_VERSION_COMPATIBLE FALSE)
+else()
+
+  if(PACKAGE_FIND_VERSION_MAJOR STREQUAL "@PROJECT_VERSION_MAJOR@")
+    set(PACKAGE_VERSION_COMPATIBLE TRUE)
+  else()
+    set(PACKAGE_VERSION_COMPATIBLE FALSE)
+  endif()
+
+  if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
+      set(PACKAGE_VERSION_EXACT TRUE)
+  endif()
+endif()

package/cpp/CMakeLists.txt

@@ -0,0 +1,14 @@
+if (USEARCH_BUILD_TEST_CPP)
+    add_executable(test_cpp test.cpp)
+    setup_target(test_cpp)
+    include(CTest)
+    enable_testing()
+    add_test(NAME test_cpp COMMAND test_cpp)
+endif ()
+
+if (USEARCH_BUILD_BENCH_CPP)
+    include(clipp)
+    add_executable(bench_cpp bench.cpp)
+    setup_target(bench_cpp)
+    target_include_directories(bench_cpp PRIVATE ${clipp_SOURCE_DIR}/include)
+endif ()

package/cpp/README.md

@@ -0,0 +1,161 @@
+# USearch for C++
+
+## Installation
+
+To use in a C++ project, copy the `include/usearch/*` headers into your project.
+Alternatively, fetch it with CMake:
+
+```cmake
+FetchContent_Declare(usearch GIT_REPOSITORY https://github.com/unum-cloud/usearch.git)
+FetchContent_MakeAvailable(usearch)
+```
+
+## Quickstart
+
+Once included, the high-level C++11 interface is as simple as it gets: `reserve()`, `add()`, `search()`, `size()`, `capacity()`, `save()`, `load()`, `view()`.
+This covers 90% of use cases.
+
+```cpp
+using namespace unum::usearch;
+
+metric_punned_t metric(256, metric_kind_t::l2sq_k, scalar_kind_t::f32_k);
+
+// If you plan to store more than 4 Billion entries - use `index_dense_big_t`.
+// Or directly instantiate the template variant you need - `index_dense_gt<vector_key_t, internal_id_t>`.
+index_dense_t index = index_dense_t::make(metric);
+float vec[3] = {0.1, 0.3, 0.2};
+
+index.reserve(10); // Pre-allocate memory for 10 vectors
+index.add(42, &vec[0]); // Pass a key and a vector
+auto results = index.search(&vec[0], 5); // Pass a query and limit number of results
+
+for (std::size_t i = 0; i != results.size(); ++i)
+    results[i].element.key, results[i].element.vector, results[i].distance;
+```
+
+Here we:
+
+- define a metric of kind [`metric_kind_t::l2sq_k`](https://unum-cloud.github.io/usearch/cpp/reference.html#_CPPv413metric_kind_t),
+- to be applied to [`scalar_kind_t::f32_k`](https://unum-cloud.github.io/usearch/cpp/reference.html#_CPPv413scalar_kind_t) floating-point vectors,
+- instantiate an [`index_dense_t`](https://unum-cloud.github.io/usearch/cpp/reference.html#_CPPv4I00EN4unum7usearch14index_dense_gtE) index.
+
+The `add` is thread-safe for concurrent index construction.
+It also has an overload for different vector types, casting them under the hood.
+The same applies to the `search`, `get`, `cluster`, and `distance_between` functions.
+
+```cpp
+double vec_double[3] = {0.1, 0.3, 0.2};
+_Float16 vec_half[3] = {0.1, 0.3, 0.2};
+index.add(43, {&vec_double[0], 3});
+index.add(44, {&vec_half[0], 3});
+```
+
+## Serialization
+
+```cpp
+index.save("index.usearch");
+index.load("index.usearch"); // Copying from disk
+index.view("index.usearch"); // Memory-mapping from disk
+```
+
+## Multi-Threading
+
+Most AI, HPC, or Big Data packages use some form of a thread pool.
+Instead of spawning additional threads within USearch, we focus on the thread safety of `add()` function, simplifying resource management.
+
+```cpp
+#pragma omp parallel for
+    for (std::size_t i = 0; i < n; ++i)
+        native.add(key, span_t{vector, dims});
+```
+
+During initialization, we allocate enough temporary memory for all the cores on the machine.
+On the call, the user can supply the identifier of the current thread, making this library easy to integrate with OpenMP and similar tools.
+
+Moreover, you can take advantage of one of the provided "executors" to parallelize the search:
+
+- `executor_openmp_t`, that would use OpenMP under the hood.
+- `executor_stl_t`, that will spawn `std::thread` instances.
+- `dummy_executor_t`, that will run everything sequentially.
+
+## Clustering
+
+Aside from basic Create-Read-Update-Delete (CRUD) operations and search, USearch also supports clustering.
+Once the index is constructed, you can either:
+
+- Identify a cluster to which any external vector belongs, once mapped onto the index.
+- Split the entire index into a set of clusters, each with its own centroid.
+
+For the first, the interface accepts a vector and a "clustering level", which is essentially the index of the HNSW graph layer, in which to search.
+If you pass zero, the traversal will happen in every level except the bottom one.
+Otherwise, the search will be limited to the specified level.
+
+```cpp
+some_scalar_t vector[3] = {0.1, 0.3, 0.2};
+cluster_result_t result = index.cluster(&vector, index.max_level() / 2);
+match_t cluster = result.cluster;
+member_cref_t member = cluster.member;
+distance_t distance = cluster.distance;
+```
+
+If you wish to split the whole structure into clusters, you must provide an iterator over a range of vectors, that will be processed in parallel using the previously described function.
+Unlike the previous function, you don't have to manually specify the level, as the algorithm will pick the best one for you, depending on the number of clusters you want to highlight.
+Aside from that auto-tuning, this function will regroup some of the clusters, if they are too small, and return the final number of clusters.
+
+```cpp
+std::size_t queries_count = queries_end - queries_begin;
+index_dense_clustering_config_t config;
+config.min_clusters = 1000;
+config.max_clusters = 2000;
+config.mode = index_dense_clustering_config_t::merge_smallest_k;
+
+// Outputs:
+vector_key_t cluster_centroids_keys[queries_count];
+distance_t distances_to_cluster_centroids[queries_count];
+executor_default_t thread_pool;
+dummy_progress_t progress_bar;
+
+clustering_result_t result = cluster(
+        queries_begin, queries_end,
+        config,
+        &cluster_centroids_keys, &distances_to_cluster_centroids,
+        thread_pool, progress_bar);
+```
+
+This approach requires basic understanding of templates meta-programming to implement the `queries_begin` and `queries_end` smart-iterators.
+On the bright side, it allows iteratively deepening into a specific cluster.
+
+As in many other bulk-processing APIs, the `executor` and `progress` are optional.
+
+## User-Defined Metrics
+
+In its high-level interface, USearch supports a variety of metrics, including the most popular ones:
+
+- `metric_cos_gt<scalar_t>` for "Cosine" or "Angular" distance.
+- `metric_ip_gt<scalar_t>` for "Inner Product" or "Dot Product" distance.
+- `metric_l2sq_gt<scalar_t>` for the squared "L2" or "Euclidean" distance.
+- `metric_jaccard_gt<scalar_t>` for "Jaccard" distance between two ordered sets of unique elements.
+- `metric_hamming_gt<scalar_t>` for "Hamming" distance, as the number of shared bits in hashes.
+- `metric_tanimoto_gt<scalar_t>` for "Tanimoto" coefficient for bit-strings.
+- `metric_sorensen_gt<scalar_t>` for "Dice-Sorensen" coefficient for bit-strings.
+- `metric_pearson_gt<scalar_t>` for "Pearson" correlation between probability distributions.
+- `metric_haversine_gt<scalar_t>` for "Haversine" or "Great Circle" distance between coordinates used in GIS applications.
+- `metric_divergence_gt<scalar_t>` for the "Jensen Shannon" similarity between probability distributions.
+
+In reality, for most common types, one of the [SimSIMD](https://github.com/ashvardanian/SimSIMD) backends will be triggered, providing hardware-acceleration for most common CPUs.
+
+If you need a different metric, you can implement it yourself and wrap it into a `metric_punned_t`, which is our alternative to the `std::function`.
+Unlike the `std::function`, it is a trivial type, which is important for performance.
+
+## Advanced Interface
+
+If you are proficient in C++ and ready to get your hands dirty, you can use the low-level interface.
+
+```cpp
+template <typename distance_at = default_distance_t,              // `float`
+          typename key_at = default_key_t,                        // `int64_t`, `uuid_t`
+          typename compressed_slot_at = default_slot_t,           // `uint32_t`, `uint40_t`
+          typename dynamic_allocator_at = std::allocator<byte_t>, //
+          typename tape_allocator_at = dynamic_allocator_at>      //
+class index_gt;
+```