Add: Clustering and multiple vectors per key

.github/workflows/prerelease.yml

@@ -66,7 +66,7 @@ jobs:
       - name: Build locally
         run: python -m pip install .
       - name: Test with PyTest
-        run: pytest python/scripts/test.py
+        run: pytest python/scripts/
 
 
   test_python_37:
@@ -95,7 +95,7 @@ jobs:
         run: python -m pip install .
 
       - name: Test with PyTest
-        run: pytest python/scripts/test.py
+        run: pytest python/scripts/
 
 
   test_javascript:
@@ -122,22 +122,6 @@ jobs:
           toolchain: stable
           override: true
 
-  test_golang:
-    name: Test GoLang
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v3
-    - run: git submodule update --init --recursive
-    - name: Set up Go
-      uses: actions/setup-go@v4
-      with:
-        go-version: '1.15'
-    - name: Build C library for cGo
-      run: |
-        make -C ./c libusearch_c.so
-        mv ./c/libusearch_c.so ./golang/libusearch_c.so
-        cd golang && ls && go test -v
-
   test_java:
     name: Test Java
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -319,7 +319,7 @@ jobs:
         run: |
               sudo apt update && 
               sudo apt install -y doxygen graphviz dia git && 
-              pip install sphinx sphinx-js breathe furo m2r2 sphinxcontrib-googleanalytics==0.2.dev20220708 sphinxcontrib-jquery && 
+              pip install sphinx==7.1.2 sphinx-js breathe furo m2r2 sphinxcontrib-googleanalytics==0.2.dev20220708 sphinxcontrib-jquery && 
               npm install -g jsdoc
       - name: Install USearch from PyPi
         run: pip install usearch

.github/workflows/update_version.sh

@@ -9,5 +9,5 @@ echo $1 > VERSION &&
     sed -i "s/^\(#define USEARCH_VERSION_MINOR \).*/\1$(echo "$1" | cut -d. -f2)/" ./include/usearch/index.hpp &&
     sed -i "s/^\(#define USEARCH_VERSION_PATCH \).*/\1$(echo "$1" | cut -d. -f3)/" ./include/usearch/index.hpp &&
     sed -i "s/<version>[0-9]\+\.[0-9]\+\.[0-9]\+/<version>$1/" README.md &&
-    sed -i "s/version = {0\.[0-9]\+\.[0-9]\+}/version = {$1}/" README.md &&
+    sed -i "s/version = {[0-9]\+\.[0-9]\+\.[0-9]\+}/version = {$1}/" README.md &&
     sed -i "s/version=\".*\"/version=\"$1\"/" wasmer.toml

.gitmodules

@@ -3,7 +3,4 @@
 	url = https://github.com/ashvardanian/simsimd
 [submodule "fp16"]
 	path = fp16
-	url = https://github.com/maratyszcza/fp16
-[submodule "robin-map"]
-	path = robin-map
-	url = https://github.com/tessil/robin-map
+	url = https://github.com/maratyszcza/fp16

Package.swift

@@ -19,20 +19,21 @@ let package = Package(
             cxxSettings: [
                 .headerSearchPath("../include/"),
                 .headerSearchPath("../fp16/include/"),
-                .headerSearchPath("../robin-map/include/"),
                 .headerSearchPath("../simismd/include/")
             ]
         ),
         .target(
             name: "USearch",
             dependencies: ["USearchObjective"],
             path: "swift",
+            exclude: ["README.md", "Test.swift"],
             sources: ["USearch.swift", "Index+Sugar.swift"]
         ),
         .testTarget(
             name: "USearchTests",
             dependencies: ["USearch"],
             path: "swift",
+            exclude: ["USearch.swift", "Index+Sugar.swift", "README.md"],
             sources: ["Test.swift"]
         )
     ],

README.md

@@ -319,10 +319,10 @@ matches = index.search(fingerprints, 10)
 
 ## Integrations
 
-- [x] GPT-Cache.
-- [x] LangChain.
-- [ ] ClickHouse.
-- [ ] Microsoft Semantic Kernel.
+- [x] GPTCache: [Python](https://github.com/zilliztech/GPTCache/releases/tag/0.1.29).
+- [x] LangChain: [Python](https://github.com/langchain-ai/langchain/releases/tag/v0.0.257) and [JavaScipt](https://github.com/hwchase17/langchainjs/releases/tag/0.0.125).
+- [ ] Microsoft Semantic Kernel: [Python](https://github.com/microsoft/semantic-kernel/pull/2358) and C#.
+- [ ] ClickHouse: C++.
 
 ## Citations
 
@@ -332,8 +332,8 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {0.13.0},
-year = {2022}
+version = {1.0.0},
+year = {2022},
 month = jun,
 }
 ```

binding.gyp

@@ -2,32 +2,36 @@
     "targets": [
         {
             "target_name": "usearch",
-            "sources": [
-                "javascript/lib.cpp"
-            ],
+            "sources": ["javascript/lib.cpp"],
             "include_dirs": [
                 "<!@(node -p \"require('node-addon-api').include\")",
                 "include",
                 "fp16/include",
-                "robin-map/include",
-                "simsimd/include"
+                "simsimd/include",
+            ],
+            "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
+            "cflags": [
+                "-fexceptions",
+                "-Wno-unknown-pragmas",
+                "-Wno-maybe-uninitialized",
             ],
-            "dependencies": [
-                "<!(node -p \"require('node-addon-api').gyp\")"
+            "cflags_cc": [
+                "-fexceptions",
+                "-Wno-unknown-pragmas",
+                "-Wno-maybe-uninitialized",
+                "-std=c++11",
             ],
-            "cflags": ["-fexceptions", "-Wno-unknown-pragmas", "-Wno-maybe-uninitialized"],
-            "cflags_cc": ["-fexceptions", "-Wno-unknown-pragmas", "-Wno-maybe-uninitialized", "-std=c++11"],
             "xcode_settings": {
                 "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
                 "CLANG_CXX_LIBRARY": "libc++",
-                "MACOSX_DEPLOYMENT_TARGET": "10.15"
+                "MACOSX_DEPLOYMENT_TARGET": "10.15",
             },
             "msvs_settings": {
                 "VCCLCompilerTool": {
                     "ExceptionHandling": 1,
-                    "AdditionalOptions": ["-std:c++11"]
+                    "AdditionalOptions": ["-std:c++11"],
                 }
-            }
+            },
         }
     ]
 }

build.gradle

@@ -45,7 +45,7 @@ model {
                         include "**/*.cpp"
                     }
                     exportedHeaders {
-                        srcDirs "include", "fp16/include", "robin-map/include", "simsimd/include", "${Jvm.current().javaHome}/include"
+                        srcDirs "include", "fp16/include", "simsimd/include", "${Jvm.current().javaHome}/include"
                     }
                 }
             }

build.rs

@@ -6,7 +6,6 @@ fn main() {
         .include("include")
         .include("rust")
         .include("fp16/include")
-        .include("robin-map/include")
         .include("simsimd/include")
         .compile("usearch");
 

c/CMakeLists.txt

@@ -3,7 +3,6 @@
 set(USEARCH_PUNNED_INCLUDE_DIRS
     "${CMAKE_CURRENT_SOURCE_DIR}/../include"
     "${CMAKE_CURRENT_SOURCE_DIR}/../fp16/include"
-    "${CMAKE_CURRENT_SOURCE_DIR}/../robin-map/include"
     "${CMAKE_CURRENT_SOURCE_DIR}/../simsimd/include"
     "${CMAKE_CURRENT_SOURCE_DIR}/"
 )

c/lib.cpp

@@ -58,13 +58,13 @@ add_result_t add_(index_dense_t* index, usearch_key_t key, void const* vector, s
     }
 }
 
-bool get_(index_dense_t* index, usearch_key_t key, void* vector, scalar_kind_t kind) {
+bool get_(index_dense_t* index, usearch_key_t key, size_t count, void* vector, scalar_kind_t kind) {
     switch (kind) {
-    case scalar_kind_t::f32_k: return index->get(key, (f32_t*)vector);
-    case scalar_kind_t::f64_k: return index->get(key, (f64_t*)vector);
-    case scalar_kind_t::f16_k: return index->get(key, (f16_t*)vector);
-    case scalar_kind_t::i8_k: return index->get(key, (i8_bits_t*)vector);
-    case scalar_kind_t::b1x8_k: return index->get(key, (b1x8_t*)vector);
+    case scalar_kind_t::f32_k: return index->get(key, (f32_t*)vector, count);
+    case scalar_kind_t::f64_k: return index->get(key, (f64_t*)vector, count);
+    case scalar_kind_t::f16_k: return index->get(key, (f16_t*)vector, count);
+    case scalar_kind_t::i8_k: return index->get(key, (i8_bits_t*)vector, count);
+    case scalar_kind_t::b1x8_k: return index->get(key, (b1x8_t*)vector, count);
     default: return search_result_t().failed("Unknown scalar kind!");
     }
 }
@@ -87,6 +87,7 @@ USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, use
     assert(options && error);
 
     index_dense_config_t config(options->connectivity, options->expansion_add, options->expansion_search);
+    config.multi = options->multi;
     metric_kind_t metric_kind = to_native_metric(options->metric_kind);
     scalar_kind_t scalar_kind = to_native_scalar(options->quantization);
 
@@ -167,9 +168,14 @@ USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_key_t key, u
     return reinterpret_cast<index_dense_t*>(index)->contains(key);
 }
 
+USEARCH_EXPORT size_t usearch_count(usearch_index_t index, usearch_key_t key, usearch_error_t*) {
+    assert(index);
+    return reinterpret_cast<index_dense_t*>(index)->count(key);
+}
+
 USEARCH_EXPORT size_t usearch_search(                                                            //
     usearch_index_t index, void const* vector, usearch_scalar_kind_t kind, size_t results_limit, //
-    usearch_key_t* found_labels, usearch_distance_t* found_distances, usearch_error_t* error) {
+    usearch_key_t* found_keys, usearch_distance_t* found_distances, usearch_error_t* error) {
 
     assert(index && vector && error);
     search_result_t result =
@@ -179,23 +185,33 @@ USEARCH_EXPORT size_t usearch_search(
         return 0;
     }
 
-    return result.dump_to(found_labels, found_distances);
+    return result.dump_to(found_keys, found_distances);
 }
 
-USEARCH_EXPORT bool usearch_get(              //
-    usearch_index_t index, usearch_key_t key, //
-    void* vector, usearch_scalar_kind_t kind, usearch_error_t*) {
+USEARCH_EXPORT size_t usearch_get(                          //
+    usearch_index_t index, usearch_key_t key, size_t count, //
+    void* vectors, usearch_scalar_kind_t kind, usearch_error_t*) {
 
-    assert(index && vector);
-    return get_(reinterpret_cast<index_dense_t*>(index), key, vector, to_native_scalar(kind));
+    assert(index && vectors);
+    return get_(reinterpret_cast<index_dense_t*>(index), key, count, vectors, to_native_scalar(kind));
 }
 
-USEARCH_EXPORT bool usearch_remove(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
+USEARCH_EXPORT size_t usearch_remove(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
 
     assert(index && error);
     labeling_result_t result = reinterpret_cast<index_dense_t*>(index)->remove(key);
     if (!result)
         *error = result.error.release();
     return result.completed;
 }
+
+USEARCH_EXPORT size_t usearch_rename(usearch_index_t index, usearch_key_t from, usearch_key_t to,
+                                     usearch_error_t* error) {
+
+    assert(index && error);
+    labeling_result_t result = reinterpret_cast<index_dense_t*>(index)->rename(from, to);
+    if (!result)
+        *error = result.error.release();
+    return result.completed;
+}
 }

c/usearch.h

@@ -83,6 +83,10 @@ USEARCH_EXPORT typedef struct usearch_init_options_t {
      *  @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;
 
 /**
@@ -151,39 +155,58 @@ USEARCH_EXPORT void usearch_add(        //
  */
 USEARCH_EXPORT bool usearch_contains(usearch_index_t, usearch_key_t, usearch_error_t* error);
 
+/**
+ *  @brief Counts the number of entries in the index under a specific key.
+ *  @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, usearch_key_t, usearch_error_t* error);
+
 /**
  *  @brief Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to query.
  *  @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] results_limit Upper bound on the number of neighbors to search, the "k" in "kANN".
- *  @param[out] found_keys Output buffer for up to `results_limit` nearest neighbors keys.
- *  @param[out] found_distances Output buffer for up to `results_limit` distances to nearest neighbors.
+ *  @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, void const* query_vector, usearch_scalar_kind_t query_kind, size_t results_limit, //
-    usearch_key_t* found_keys, usearch_distance_t* found_distances, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_search(                           //
+    usearch_index_t,                                            //
+    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] 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 `true` if the vector is successfully retrieved, `false` if the vector is not found.
+ *  @return Number of vectors found under that name and exported to `vector`.
  */
-USEARCH_EXPORT bool usearch_get(        //
-    usearch_index_t, usearch_key_t key, //
+USEARCH_EXPORT size_t usearch_get(                    //
+    usearch_index_t, 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[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 `true` if the vector is successfully removed, `false` if the vector is not found.
+ *  @return Number of vectors found under that name and dropped from the index.
+ */
+USEARCH_EXPORT size_t usearch_remove(usearch_index_t, usearch_key_t key, usearch_error_t* error);
+
+/**
+ *  @brief Renames the vector to map to a different key.
+ *  @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 bool usearch_remove(usearch_index_t, usearch_key_t key, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_rename(usearch_index_t, usearch_key_t from, usearch_key_t to, usearch_error_t* error);
 
 #ifdef __cplusplus
 }