usearch 2.11.0 → 2.13.0

package/README.md

@@ -49,7 +49,7 @@ Linux • MacOS • Windows • iOS • WebAssembly •
 
 - ✅ __[10x faster][faster-than-faiss]__ [HNSW][hnsw-algorithm] implementation than [FAISS][faiss].
 - ✅ Simple and extensible [single C++11 header][usearch-header] __library__.
-- ✅ [Trusted](#integrations) by giants like Google and databases like [ClickHouse][clickhouse-docs].
+- ✅ [Trusted](#integrations) by giants like Google and DBs like [ClickHouse][clickhouse-docs] & [DuckDB][duckdb-docs].
 - ✅ [SIMD][simd]-optimized and [user-defined metrics](#user-defined-functions) with JIT compilation.
 - ✅ Hardware-agnostic `f16` & `i8` - [half-precision & quarter-precision support](#memory-efficiency-downcasting-and-quantization).
 - ✅ [View large indexes from disk](#serving-index-from-disk) without loading into RAM.
@@ -67,6 +67,7 @@ Linux • MacOS • Windows • iOS • WebAssembly •
 [simd]: https://en.wikipedia.org/wiki/Single_instruction,_multiple_data
 [faster-than-faiss]: https://www.unum.cloud/blog/2023-11-07-scaling-vector-search-with-intel
 [clickhouse-docs]: https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/annindexes#usearch
+[duckdb-docs]: https://duckdb.org/2024/05/03/vector-similarity-search-vss.html
 
 __Technical Insights__ and related articles:
 
@@ -94,9 +95,10 @@ USearch is compact and broadly compatible without sacrificing performance, prima
 | Supported metrics ²                          |         9 fixed metrics |               any metric |              extendible |
 | Supported languages ³                        |             C++, Python |             10 languages |                portable |
 | Supported ID types ⁴                         |          32-bit, 64-bit |   32-bit, 40-bit, 64-bit |               efficient |
-| Required dependencies ⁵                      |            BLAS, OpenMP |                        - |            light-weight |
-| Bindings ⁶                                   |                    SWIG |                   Native |             low-latency |
-| Python binding size ⁷                        | [~ 10 MB][faiss-weight] | [< 1 MB][usearch-weight] |              deployable |
+| Filtering ⁵                                  |               ban-lists |           any predicates |              composable |
+| Required dependencies ⁶                      |            BLAS, OpenMP |                        - |            light-weight |
+| Bindings ⁷                                   |                    SWIG |                   Native |             low-latency |
+| Python binding size ⁸                        | [~ 10 MB][faiss-weight] | [< 1 MB][usearch-weight] |              deployable |
 
 [sloc]: https://en.wikipedia.org/wiki/Source_lines_of_code
 [faiss-weight]: https://pypi.org/project/faiss-cpu/#files
@@ -107,16 +109,17 @@ USearch is compact and broadly compatible without sacrificing performance, prima
 > ² User-defined metrics allow you to customize your search for various applications, from GIS to creating custom metrics for composite embeddings from multiple AI models or hybrid full-text and semantic search.
 > ³ With USearch, you can reuse the same preconstructed index in various programming languages.
 > ⁴ The 40-bit integer allows you to store 4B+ vectors without allocating 8 bytes for every neighbor reference in the proximity graph.
-> ⁵ Lack of obligatory dependencies makes USearch much more portable.
-> ⁶ Native bindings introduce lower call latencies than more straightforward approaches.
-> ⁷ Lighter bindings make downloads and deployments faster.
+> ⁵ With USearch the index can be combined with arbitrary external containers, like Bloom filters or third-party databases, to filter out irrelevant keys during index traversal.
+> ⁶ Lack of obligatory dependencies makes USearch much more portable.
+> ⁷ Native bindings introduce lower call latencies than more straightforward approaches.
+> ⁸ Lighter bindings make downloads and deployments faster.
 
 [intel-benchmarks]: https://www.unum.cloud/blog/2023-11-07-scaling-vector-search-with-intel
 
 Base functionality is identical to FAISS, and the interface must be familiar if you have ever investigated Approximate Nearest Neighbors search:
 
 ```py
-$ pip install numpy usearch
+# pip install numpy usearch
 
 import numpy as np
 from usearch.index import Index
@@ -134,12 +137,13 @@ assert np.allclose(index[42], vector, atol=0.1) # Ensure high tolerance in mixed
 ```
 
 More settings are always available, and the API is designed to be as flexible as possible.
+The default storage/quantization level is hardware-dependant for efficiency, but `f16` is recommended for most modern CPUs.
 
 ```py
 index = Index(
     ndim=3, # Define the number of dimensions in input vectors
-    metric='cos', # Choose 'l2sq', 'haversine' or other metric, default = 'ip'
-    dtype='f32', # Quantize to 'f16' or 'i8' if needed, default = 'f32'
+    metric='cos', # Choose 'l2sq', 'ip', 'haversine' or other metric, default = 'cos'
+    dtype='f16', # Store as 'f64', 'f32', 'f16', 'i8', 'b1'..., default = None
     connectivity=16, # Optional: Limit number of neighbors per graph node
     expansion_add=128, # Optional: Control the recall of indexing
     expansion_search=64, # Optional: Control the quality of the search
@@ -192,7 +196,7 @@ When compared to FAISS's `IndexFlatL2` in Google Colab, __[USearch may offer up
 - `faiss.IndexFlatL2`: __55.3 ms__.
 - `usearch.index.search`: __2.54 ms__.
 
-## User-Defined Functions
+## User-Defined Metrics
 
 While most vector search packages concentrate on just two metrics, "Inner Product distance" and "Euclidean distance", USearch allows arbitrary user-defined metrics.
 This flexibility allows you to customize your search for various applications, from computing geospatial coordinates with the rare [Haversine][haversine] distance to creating custom metrics for composite embeddings from multiple AI models, like joint image-text embeddings.
@@ -228,6 +232,23 @@ So you can apply it in [obscure][obscure] applications, like searching for simil
 [cppyy]: https://cppyy.readthedocs.io/en/latest/
 [peachpy]: https://github.com/Maratyszcza/PeachPy
 
+## Filtering and Predicate Functions
+
+Sometimes you may want to cross-reference search-results against some external database or filter them based on some criteria.
+In most engines, you'd have to manually perform paging requests, successively filtering the results.
+In USearch you can simply pass a predicate function to the search method, which will be applied directly during graph traversal.
+In Rust that would look like this:
+
+```rust
+let is_odd = |key: Key| key % 2 == 1;
+let query = vec![0.2, 0.1, 0.2, 0.1, 0.3];
+let results = index.filtered_search(&query, 10, is_odd).unwrap();
+assert!(
+    results.keys.iter().all(|&key| key % 2 == 1),
+    "All keys must be odd"
+);
+```
+
 ## Memory Efficiency, Downcasting, and Quantization
 
 Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
@@ -341,41 +362,58 @@ In some cases, like Batch operations, feature parity is meaningless, as the host
 
 ## Application Examples
 
-### USearch + AI = Multi-Modal Semantic Search
-
-[![USearch Semantic Image Search](https://github.com/ashvardanian/usearch-images/raw/main/assets/usearch-images-slow.gif)](https://github.com/ashvardanian/usearch-images)
+### USearch + UForm + UCall = Multimodal Semantic Search
 
 AI has a growing number of applications, but one of the coolest classic ideas is to use it for Semantic Search.
-One can take an encoder model, like the multi-modal [UForm](https://github.com/unum-cloud/uform), and a web-programming framework, like UCall, and build a text-to-image search platform in just 20 lines of Python.
+One can take an encoder model, like the multi-modal [UForm](https://github.com/unum-cloud/uform), and a web-programming framework, like [UCall](https://github.com/unum-cloud/ucall), and build a text-to-image search platform in just 20 lines of Python.
 
 ```python
-import ucall
-import uform
-import usearch
+from ucall import Server
+from uform import get_model, Modality
+from usearch.index import Index
 
 import numpy as np
 import PIL as pil
 
-server = ucall.Server()
-model = uform.get_model('unum-cloud/uform-vl-multilingual')
-index = usearch.index.Index(ndim=256)
+processors, models = get_model('unum-cloud/uform3-image-text-english-small')
+model_text = models[Modality.TEXT_ENCODER]
+model_image = models[Modality.IMAGE_ENCODER]
+processor_text = processors[Modality.TEXT_ENCODER]
+processor_image = processors[Modality.IMAGE_ENCODER]
+
+server = Server()
+index = Index(ndim=256)
 
 @server
 def add(key: int, photo: pil.Image.Image):
-    image = model.preprocess_image(photo)
-    vector = model.encode_image(image).detach().numpy()
+    image = processor_image(photo)
+    vector = model_image(image)
     index.add(key, vector.flatten(), copy=True)
 
 @server
 def search(query: str) -> np.ndarray:
-    tokens = model.preprocess_text(query)
-    vector = model.encode_text(tokens).detach().numpy()
+    tokens = processor_text(query)
+    vector = model_text(tokens)
     matches = index.search(vector.flatten(), 3)
     return matches.keys
 
 server.run()
 ```
 
+Similar experiences can also be imlemented in other languages and on the client side, removing the network latency.
+For Swift and iOS, check out the [`ashvardanian/SwiftSemanticSearch`](https://github.com/ashvardanian/SwiftSemanticSearch) repository.
+
+<table>
+  <tr>
+    <td>
+      <img src="https://github.com/ashvardanian/ashvardanian/blob/master/demos/SwiftSemanticSearch-Dog.gif?raw=true" alt="SwiftSemanticSearch demo Dog">
+    </td>
+    <td>
+      <img src="https://github.com/ashvardanian/ashvardanian/blob/master/demos/SwiftSemanticSearch-Flowers.gif?raw=true" alt="SwiftSemanticSearch demo with Flowers">
+    </td>
+  </tr>
+</table>
+
 A more complete [demo with Streamlit is available on GitHub](https://github.com/ashvardanian/usearch-images).
 We have pre-processed some commonly used datasets, cleaned the images, produced the vectors, and pre-built the index.
 
@@ -427,32 +465,83 @@ That method was used to build the ["USearch Molecules"](https://github.com/ashva
 [smiles]: https://en.wikipedia.org/wiki/Simplified_molecular-input_line-entry_system
 [rdkit-fingerprints]: https://www.rdkit.org/docs/RDKit_Book.html#additional-information-about-the-fingerprints
 
-### USearch + POI Coordinates = GIS Applications... on iOS?
+### USearch + POI Coordinates = GIS Applications
 
-[![USearch Maps with SwiftUI](https://github.com/ashvardanian/SwiftVectorSearch/raw/main/USearch+SwiftUI.gif)](https://github.com/ashvardanian/SwiftVectorSearch)
+Similar to Vector and Molecule search, USearch can be used for Geospatial Information Systems.
+The Haversine distance is available out of the box, but you can also define more complex relationships, like the Vincenty formula, that accounts for the Earth's oblateness.
 
-With Objective-C and Swift iOS bindings, USearch can be easily used in mobile applications.
-The [SwiftVectorSearch](https://github.com/ashvardanian/SwiftVectorSearch) project illustrates how to build a dynamic, real-time search system on iOS.
-In this example, we use 2-dimensional vectors—encoded as latitude and longitude—to find the closest Points of Interest (POIs) on a map.
-The search is based on the Haversine distance metric but can easily be extended to support high-dimensional vectors.
+```py
+from numba import cfunc, types, carray
+import math
+
+# Define the dimension as 2 for latitude and longitude
+ndim = 2
+
+# Signature for the custom metric
+signature = types.float32(
+    types.CPointer(types.float32),
+    types.CPointer(types.float32))
+
+# WGS-84 ellipsoid parameters
+a = 6378137.0  # major axis in meters
+f = 1 / 298.257223563  # flattening
+b = (1 - f) * a  # minor axis
+
+def vincenty_distance(a_ptr, b_ptr):
+    a_array = carray(a_ptr, ndim)
+    b_array = carray(b_ptr, ndim)
+    lat1, lon1, lat2, lon2 = a_array[0], a_array[1], b_array[0], b_array[1]
+    L, U1, U2 = lon2 - lon1, math.atan((1 - f) * math.tan(lat1)), math.atan((1 - f) * math.tan(lat2))
+    sinU1, cosU1, sinU2, cosU2 = math.sin(U1), math.cos(U1), math.sin(U2), math.cos(U2)
+    lambda_, iterLimit = L, 100
+    while iterLimit > 0:
+        iterLimit -= 1
+        sinLambda, cosLambda = math.sin(lambda_), math.cos(lambda_)
+        sinSigma = math.sqrt((cosU2 * sinLambda) ** 2 + (cosU1 * sinU2 - sinU1 * cosU2 * cosLambda) ** 2)
+        if sinSigma == 0: return 0.0  # Co-incident points
+        cosSigma, sigma = sinU1 * sinU2 + cosU1 * cosU2 * cosLambda, math.atan2(sinSigma, cosSigma)
+        sinAlpha, cos2Alpha = cosU1 * cosU2 * sinLambda / sinSigma, 1 - (cosU1 * cosU2 * sinLambda / sinSigma) ** 2
+        cos2SigmaM = cosSigma - 2 * sinU1 * sinU2 / cos2Alpha if not math.isnan(cosSigma - 2 * sinU1 * sinU2 / cos2Alpha) else 0  # Equatorial line
+        C = f / 16 * cos2Alpha * (4 + f * (4 - 3 * cos2Alpha))
+        lambda_, lambdaP = L + (1 - C) * f * (sinAlpha * (sigma + C * sinSigma * (cos2SigmaM + C * cosSigma * (-1 + 2 * cos2SigmaM ** 2)))), lambda_
+        if abs(lambda_ - lambdaP) <= 1e-12: break
+    if iterLimit == 0: return float('nan')  # formula failed to converge
+    u2 = cos2Alpha * (a ** 2 - b ** 2) / (b ** 2)
+    A = 1 + u2 / 16384 * (4096 + u2 * (-768 + u2 * (320 - 175 * u2)))
+    B = u2 / 1024 * (256 + u2 * (-128 + u2 * (74 - 47 * u2)))
+    deltaSigma = B * sinSigma * (cos2SigmaM + B / 4 * (cosSigma * (-1 + 2 * cos2SigmaM ** 2) - B / 6 * cos2SigmaM * (-3 + 4 * sinSigma ** 2) * (-3 + 4 * cos2SigmaM ** 2)))
+    s = b * A * (sigma - deltaSigma)
+    return s / 1000.0  # Distance in kilometers
+
+# Example usage:
+index = Index(ndim=ndim, metric=CompiledMetric(
+    pointer=vincenty_distance.address,
+    kind=MetricKind.Haversine,
+    signature=MetricSignature.ArrayArray,
+))
+```
 
-## Integrations
+## Integrations & Users
 
-- [x] GPTCache: [Python](https://github.com/zilliztech/GPTCache/releases/tag/0.1.29).
+- [x] ClickHouse: [C++](https://github.com/ClickHouse/ClickHouse/pull/53447), [docs](https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/annindexes#usearch).
+- [x] DuckDB: [post](https://duckdb.org/2024/05/03/vector-similarity-search-vss.html).
+- [x] Google: [UniSim](https://github.com/google/unisim), [RetSim](https://arxiv.org/abs/2311.17264) paper.
+- [x] LanternDB: [C++](https://github.com/lanterndata/lantern), [Rust](https://github.com/lanterndata/lantern_extras), [docs](https://lantern.dev/blog/hnsw-index-creation).
 - [x] LangChain: [Python](https://github.com/langchain-ai/langchain/releases/tag/v0.0.257) and [JavaScript](https://github.com/hwchase17/langchainjs/releases/tag/0.0.125).
-- [x] ClickHouse: [C++](https://github.com/ClickHouse/ClickHouse/pull/53447).
 - [x] Microsoft Semantic Kernel: [Python](https://github.com/microsoft/semantic-kernel/releases/tag/python-0.3.9.dev) and C#.
-- [x] LanternDB: [C++](https://github.com/lanterndata/lantern) and [Rust](https://github.com/lanterndata/lantern_extras).
+- [x] GPTCache: [Python](https://github.com/zilliztech/GPTCache/releases/tag/0.1.29).
+- [x] Sentence-Transformers: Python [docs](https://www.sbert.net/docs/package_reference/quantization.html#sentence_transformers.quantization.semantic_search_usearch).
+- [x] Pathway: [Rust](https://github.com/pathwaycom/pathway).
 
 ## Citations
 
-```txt
+```bibtex
 @software{Vardanian_USearch_2023,
 doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.11.0},
+version = {2.13.0},
 year = {2023},
 month = oct,
 }

package/binding.gyp

@@ -25,15 +25,9 @@
                 "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
                 "CLANG_CXX_LIBRARY": "libc++",
                 "MACOSX_DEPLOYMENT_TARGET": "11.0",
-                "OTHER_CFLAGS": [
-                    "-arch arm64",
-                    "-arch x86_64"
-                ],
-                "OTHER_LDFLAGS": [
-                    "-arch arm64",
-                    "-arch x86_64" 
-                ]
-           },
+                "OTHER_CFLAGS": ["-arch arm64", "-arch x86_64"],
+                "OTHER_LDFLAGS": ["-arch arm64", "-arch x86_64"],
+            },
             "msvs_settings": {
                 "VCCLCompilerTool": {
                     "ExceptionHandling": 1,
@@ -47,18 +41,19 @@
                         "cflags_cc": [
                             '<!(if [ "$USEARCH_USE_OPENMP" = "1" ]; then echo \'-fopenmp\'; fi)',
                         ],
-                        "ldflags": [
-                            '<!(if [ "$USEARCH_USE_OPENMP" = "1" ]; then echo \'-lgomp\'; fi)'
-                        ],
+                        "ldflags": ['<!(if [ "$USEARCH_USE_OPENMP" = "1" ]; then echo \'-lgomp\'; fi)'],
                         "defines": [
                             "USEARCH_USE_OPENMP=<!(echo ${USEARCH_USE_OPENMP:-0})",
                             "USEARCH_USE_SIMSIMD=<!(echo ${USEARCH_USE_SIMSIMD:-1})",
                             "USEARCH_USE_FP16LIB=<!(echo ${USEARCH_USE_FP16LIB:-1})",
                             "SIMSIMD_TARGET_NEON=<!(echo ${SIMSIMD_TARGET_NEON:-1})",
+                            "SIMSIMD_TARGET_NEON_BF16=<!(echo ${SIMSIMD_TARGET_NEON_BF16:-0})",
                             "SIMSIMD_TARGET_SVE=<!(echo ${SIMSIMD_TARGET_SVE:-1})",
+                            "SIMSIMD_TARGET_SVE_BF16=<!(echo ${SIMSIMD_TARGET_SVE_BF16:-0})",
                             "SIMSIMD_TARGET_HASWELL=<!(echo ${SIMSIMD_TARGET_HASWELL:-1})",
                             "SIMSIMD_TARGET_SKYLAKE=<!(echo ${SIMSIMD_TARGET_SKYLAKE:-1})",
                             "SIMSIMD_TARGET_ICE=<!(echo ${SIMSIMD_TARGET_ICE:-1})",
+                            "SIMSIMD_TARGET_GENOA=<!(echo ${SIMSIMD_TARGET_GENOA:-1})",
                             "SIMSIMD_TARGET_SAPPHIRE=<!(echo ${SIMSIMD_TARGET_SAPPHIRE:-1})",
                         ],
                     },
@@ -71,10 +66,12 @@
                             "USEARCH_USE_SIMSIMD=<!(echo ${USEARCH_USE_SIMSIMD:-0})",
                             "USEARCH_USE_FP16LIB=<!(echo ${USEARCH_USE_FP16LIB:-1})",
                             "SIMSIMD_TARGET_NEON=<!(echo ${SIMSIMD_TARGET_NEON:-1})",
+                            "SIMSIMD_TARGET_NEON_BF16=<!(echo ${SIMSIMD_TARGET_NEON_BF16:-0})",
                             "SIMSIMD_TARGET_SVE=<!(echo ${SIMSIMD_TARGET_SVE:-0})",
                             "SIMSIMD_TARGET_HASWELL=<!(echo ${SIMSIMD_TARGET_HASWELL:-1})",
                             "SIMSIMD_TARGET_SKYLAKE=<!(echo ${SIMSIMD_TARGET_SKYLAKE:-0})",
                             "SIMSIMD_TARGET_ICE=<!(echo ${SIMSIMD_TARGET_ICE:-0})",
+                            "SIMSIMD_TARGET_GENOA=<!(echo ${SIMSIMD_TARGET_GENOA:-0})",
                             "SIMSIMD_TARGET_SAPPHIRE=<!(echo ${SIMSIMD_TARGET_SAPPHIRE:-0})",
                         ],
                     },
@@ -89,9 +86,11 @@
                             "SIMSIMD_TARGET_SKYLAKE=0",
                             "SIMSIMD_TARGET_ICE=0",
                             "SIMSIMD_TARGET_SAPPHIRE=0",
+                            "SIMSIMD_TARGET_GENOA=0",
                             "SIMSIMD_TARGET_SVE=0",
                             "SIMSIMD_TARGET_HASWELL=0",
                             "SIMSIMD_TARGET_NEON=0",
+                            "SIMSIMD_TARGET_NEON_BF16=0",
                         ],
                     },
                 ],

package/c/README.md

@@ -42,7 +42,7 @@ int main() {
 
     // Search:
     usearch_key_t found_keys[10];
-    float found_distances[10];
+    usearch_distance_t found_distances[10];
     size_t found_count = usearch_search(
         index, &vector[0], usearch_scalar_f32_k, 10, 
         &found_keys[0], &found_distances[0], &error);
@@ -113,7 +113,8 @@ simsimd_distance_t callback(void const* a, void const* b, void* state) {
     // Your custom metric implementation here
 }
 
-usearch_change_metric(index, callback, NULL, usearch_metric_unknown_k, &error);
+void callback_state = NULL;
+usearch_change_metric(index, callback, callback_state, usearch_metric_unknown_k, &error);
 ```
 
 You can always revert back to one of the native metrics by calling:
@@ -133,8 +134,10 @@ int is_odd(usearch_key_t key, void* state) {
     return key % 2;
 }
 
+usearch_key_t found_keys[10];
+usearch_distance_t found_distances[10];
 usearch_filtered_search(
-    index, &vector[0], usearch_scalar_f32_k, 10, 
+    index, &query[0], usearch_scalar_f32_k, 10, 
     &is_odd, NULL, // no state needed for this callback
     &found_keys[0], &found_distances[0], &error);
 ```
@@ -204,6 +207,9 @@ By default, as many of these structures are created as there are logical cores o
 Then, one can construct the index in parallel using many cores using third-party thread-pools or tools like OpenACC and OpenMP.
 
 ```c
+usearch_change_threads_add(index, omp_get_max_threads(), &error);
+usearch_change_threads_search(index, omp_get_max_threads(), &error);
+
 #pragma omp parallel for
 for (size_t i = 0; i < 1000; i++) {
     usearch_add(index, i, &vector[0], usearch_scalar_f32_k, &error);

package/c/lib.cpp

@@ -94,7 +94,7 @@ std::size_t get_(index_dense_t* index, usearch_key_t key, size_t count, void* ve
     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_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!");
+    default: return search_result_t(*index).failed("Unknown scalar kind!");
     }
 }
 
@@ -112,7 +112,7 @@ search_result_t search_(index_dense_t* index, void const* vector, scalar_kind_t
         return index->filtered_search((i8_t const*)vector, n, std::forward<predicate_at>(predicate));
     case scalar_kind_t::b1x8_k:
         return index->filtered_search((b1x8_t const*)vector, n, std::forward<predicate_at>(predicate));
-    default: return search_result_t().failed("Unknown scalar kind!");
+    default: return search_result_t(*index).failed("Unknown scalar kind!");
     }
 }
 
@@ -123,19 +123,32 @@ USEARCH_EXPORT char const* usearch_version(void) {
     int minor = USEARCH_VERSION_MINOR;
     int patch = USEARCH_VERSION_PATCH;
     static char version[32];
-    sprintf(version, "%d.%d.%d", major, minor, patch);
+    std::snprintf(version, sizeof(version), "%d.%d.%d", major, minor, patch);
     return version;
 }
 
 USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error) {
 
-    USEARCH_ASSERT(options && error && "Missing arguments");
+    USEARCH_ASSERT(error && "Missing arguments");
 
-    index_dense_config_t config(options->connectivity, options->expansion_add, options->expansion_search);
+    // The user may want to initialize from a file.
+    // In that case he may pass NULL options, and we will try to load the metadata from the file.
+    if (!options) {
+        index_dense_t* result_ptr = new index_dense_t();
+        if (!result_ptr)
+            *error = "Out of memory!";
+        return result_ptr;
+    }
+
+    index_dense_config_t config;
+    config.connectivity = options->connectivity;
+    config.expansion_add = options->expansion_add;
+    config.expansion_search = options->expansion_search;
     config.multi = options->multi;
+    config.enable_key_lookups = 1;
+
     metric_kind_t metric_kind = metric_kind_to_cpp(options->metric_kind);
     scalar_kind_t scalar_kind = scalar_kind_to_cpp(options->quantization);
-
     metric_punned_t metric = //
         !options->metric ? metric_punned_t::builtin(options->dimensions, metric_kind, scalar_kind)
                          : metric_punned_t::stateless(options->dimensions,                               //
@@ -147,10 +160,18 @@ USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, use
         return NULL;
     }
 
-    index_dense_t index = index_dense_t::make(metric, config);
-    index_dense_t* result_ptr = new index_dense_t(std::move(index));
-    if (!result_ptr || !*result_ptr)
+    using state_result_t = typename index_dense_t::state_result_t;
+    state_result_t state = index_dense_t::make(metric, config);
+    if (!state)
+        *error = state.error.release();
+    index_dense_t* result_ptr = new index_dense_t(std::move(state.index));
+    if (!result_ptr)
         *error = "Out of memory!";
+
+    // Let's immediately make it usable by reserving enough threads for this machine:
+    if (!result_ptr->try_reserve(index_limits_t()))
+        *error = "Out of memory when preparing contexts!";
+
     return result_ptr;
 }
 
@@ -304,6 +325,22 @@ USEARCH_EXPORT void usearch_change_expansion_search(usearch_index_t index, size_
     reinterpret_cast<index_dense_t*>(index)->change_expansion_search(expansion);
 }
 
+USEARCH_EXPORT void usearch_change_threads_add(usearch_index_t index, size_t threads, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
+    index_limits_t limits = index_dense.limits();
+    limits.threads_add = threads;
+    index_dense.try_reserve(limits);
+}
+
+USEARCH_EXPORT void usearch_change_threads_search(usearch_index_t index, size_t threads, usearch_error_t* error) {
+    USEARCH_ASSERT(index && error && "Missing arguments");
+    auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
+    index_limits_t limits = index_dense.limits();
+    limits.threads_search = threads;
+    index_dense.try_reserve(limits);
+}
+
 USEARCH_EXPORT void usearch_change_metric_kind(usearch_index_t index, usearch_metric_kind_t kind,
                                                usearch_error_t* error) {
     USEARCH_ASSERT(index && error && "Missing arguments");
@@ -317,9 +354,9 @@ USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_
     USEARCH_ASSERT(index && error && "Missing arguments");
     auto& index_dense = *reinterpret_cast<index_dense_t*>(index);
     auto metric_punned =
-        state ? metric_punned_t::statefull(reinterpret_cast<std::uintptr_t>(metric),
-                                           reinterpret_cast<std::uintptr_t>(state), metric_kind_to_cpp(kind),
-                                           index_dense.scalar_kind())
+        state ? metric_punned_t::stateful(reinterpret_cast<std::uintptr_t>(metric),
+                                          reinterpret_cast<std::uintptr_t>(state), metric_kind_to_cpp(kind),
+                                          index_dense.scalar_kind())
               : metric_punned_t::stateless(index_dense.dimensions(), reinterpret_cast<std::uintptr_t>(metric),
                                            metric_punned_signature_t::array_array_k, metric_kind_to_cpp(kind),
                                            index_dense.scalar_kind());
@@ -328,7 +365,7 @@ USEARCH_EXPORT void usearch_change_metric(usearch_index_t index, usearch_metric_
 
 USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error) {
     USEARCH_ASSERT(index && error && "Missing arguments");
-    if (!reinterpret_cast<index_dense_t*>(index)->reserve(capacity))
+    if (!reinterpret_cast<index_dense_t*>(index)->try_reserve(capacity))
         *error = "Out of memory!";
 }