usearch 2.9.1 → 2.10.0

package/README.md

@@ -30,19 +30,18 @@ Spatial • Binary • Probabilistic • User-Defined Metrics
 <a href="https://unum-cloud.github.io/usearch/swift">Swift</a> •
 <a href="https://unum-cloud.github.io/usearch/csharp">C#</a> •
 <a href="https://unum-cloud.github.io/usearch/golang">GoLang</a> •
-<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a> •
-<a href="https://unum-cloud.github.io/usearch/sqlite">SQLite3</a>
+<a href="https://unum-cloud.github.io/usearch/wolfram">Wolfram</a>
 <br/>
-Linux • MacOS • Windows • iOS • WebAssembly
+Linux • MacOS • Windows • iOS • WebAssembly •
+<a href="https://unum-cloud.github.io/usearch/sqlite">SQLite3</a>
 </p>
 
 <div align="center">
-<a href="https://pepy.tech/project/usearch"> <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/usearch?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=USearch%20Python%20installs"> </a>
-<a href="https://www.npmjs.com/package/usearch"> <img alt="NPM" src="https://img.shields.io/npm/dy/usearch?label=NPM%20installs"> </a>
-<a href="https://crates.io/crates/usearch"> <img alt="Crate" src="https://img.shields.io/crates/d/usearch?label=Crate%20installs"> </a>
-<a href="https://www.nuget.org/packages/Cloud.Unum.USearch"> <img alt="NuGet" src="https://img.shields.io/nuget/dt/Cloud.Unum.USearch?label=NuGet%20installs"> </a>
-<a href="https://central.sonatype.com/artifact/cloud.unum/usearch/overview"> <img alt="Maven" src="https://img.shields.io/nexus/r/cloud.unum/usearch?server=https%3A%2F%2Fs01.oss.sonatype.org%2F&label=Maven%20version"> </a>
-<a href="https://hub.docker.com/r/unum/usearch"> <img alt="Docker" src="https://img.shields.io/docker/pulls/unum/usearch?label=Docker%20installs"> </a>
+<a href="https://pepy.tech/project/usearch"> <img alt="PyPI" src="https://static.pepy.tech/personalized-badge/usearch?period=total&units=abbreviation&left_color=black&right_color=blue&left_text=Python%20PyPi%20installs"> </a>
+<a href="https://www.npmjs.com/package/usearch"> <img alt="NPM" src="https://img.shields.io/npm/dy/usearch?label=JavaScript%20NPM%20installs"> </a>
+<a href="https://crates.io/crates/usearch"> <img alt="Crate" src="https://img.shields.io/crates/d/usearch?label=Rust%20Crate%20installs"> </a>
+<a href="https://www.nuget.org/packages/Cloud.Unum.USearch"> <img alt="NuGet" src="https://img.shields.io/nuget/dt/Cloud.Unum.USearch?label=CSharp%20NuGet%20installs"> </a>
+<a href="https://central.sonatype.com/artifact/cloud.unum/usearch/overview"> <img alt="Maven" src="https://img.shields.io/nexus/r/cloud.unum/usearch?server=https%3A%2F%2Fs01.oss.sonatype.org%2F&label=Java%20Maven%20version"> </a>
 <img alt="GitHub code size in bytes" src="https://img.shields.io/github/languages/code-size/unum-cloud/usearch?label=Repo%20size">
 </div>
 
@@ -50,18 +49,16 @@ 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__.
-- ✅ Compatible with a dozen programming languages out of the box.
 - ✅ [Trusted](#integrations) by giants like Google and databases like [ClickHouse][clickhouse-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.
 - ✅ Heterogeneous lookups, renaming/relabeling, and on-the-fly deletions.
-- ✅ Variable dimensionality vectors for unique applications, including search over compressed data.
 - ✅ Binary Tanimoto and Sorensen coefficients for [Genomics and Chemistry applications](#usearch--rdkit--molecular-search).
 - ✅ Space-efficient point-clouds with `uint40_t`, accommodating 4B+ size.
-- ✅ Compatible with OpenMP and custom "executors" for fine-grained control over CPU utilization.
-- ✅ Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters.
+- ✅ Compatible with OpenMP and custom "executors" for fine-grained parallelism.
 - ✅ [Semantic Search](#usearch--ai--multi-modal-semantic-search) and [Joins](#joins-one-to-one-one-to-many-and-many-to-many-mappings).
+- 🔄 Near-real-time [clustering and sub-clustering](#clustering) for Tens or Millions of clusters.
 
 [faiss]: https://github.com/facebookresearch/faiss
 [usearch-header]: https://github.com/unum-cloud/usearch/blob/main/include/usearch/index.hpp
@@ -133,7 +130,7 @@ matches = index.search(vector, 10)
 
 assert matches[0].key == 42
 assert matches[0].distance <= 0.001
-assert np.allclose(index[42], vector)
+assert np.allclose(index[42], vector, atol=0.1) # Ensure high tolerance in mixed-precision comparisons
 ```
 
 More settings are always available, and the API is designed to be as flexible as possible.
@@ -195,6 +192,44 @@ 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
+
+While most vector search packages concentrate on just a few metrics - "Inner Product distance" and "Euclidean distance," USearch extends this list to include any 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.
+
+![USearch: Vector Search Approaches](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-approaches-white.png?raw=true)
+
+Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn't require vectors to be identical in length.
+They only have to be comparable.
+So you can apply it in [obscure][obscure] applications, like searching for similar sets or fuzzy text matching, using [GZip][gzip-similarity] as a distance function.
+
+> Read more about [JIT and UDF in USearch Python SDK](https://unum-cloud.github.io/usearch/python#user-defined-metrics-and-jit-in-python).
+
+[haversine]: https://ashvardanian.com/posts/abusing-vector-search#geo-spatial-indexing
+[obscure]: https://ashvardanian.com/posts/abusing-vector-search
+[gzip-similarity]: https://twitter.com/LukeGessler/status/1679211291292889100?s=20
+
+## Memory Efficiency, Downcasting, and Quantization
+
+Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
+Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
+Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
+The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `f16_t`, `i8_t`, and single-bit representations.
+You can use the following command to check, if hardware acceleration is enabled:
+
+```sh
+$ python -c 'from usearch.index import Index; print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)'
+> sapphire
+$ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tanimoto").hardware_acceleration)'
+> ice
+```
+
+Using smaller numeric types will save you RAM needed to store the vectors, but you can also compress the neighbors lists forming our proximity graphs.
+By default, 32-bit `uint32_t` is used to enumerate those, which is not enough if you need to address over 4 Billion entries.
+For such cases we provide a custom `uint40_t` type, that will still be 37.5% more space-efficient than the commonly used 8-byte integers, and will scale up to 1 Trillion entries.
+
+![USearch uint40_t support](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-neighbor-types.png?raw=true)
+
 ## `Indexes` for Multi-Index Lookups
 
 For larger workloads targeting billions or even trillions of vectors, parallel multi-index lookups become invaluable.
@@ -267,43 +302,6 @@ pairs: dict = men.join(women, max_proposals=0, exact=False)
 
 > Read more in the post: [Combinatorial Stable Marriages for Semantic Search 💍](https://ashvardanian.com/posts/searching-stable-marriages)
 
-## User-Defined Functions
-
-While most vector search packages concentrate on just a few metrics - "Inner Product distance" and "Euclidean distance," USearch extends this list to include any 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.
-
-![USearch: Vector Search Approaches](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-approaches-white.png?raw=true)
-
-Unlike older approaches indexing high-dimensional spaces, like KD-Trees and Locality Sensitive Hashing, HNSW doesn't require vectors to be identical in length.
-They only have to be comparable.
-So you can apply it in [obscure][obscure] applications, like searching for similar sets or fuzzy text matching, using [GZip][gzip-similarity] as a distance function.
-
-> Read more about [JIT and UDF in USearch Python SDK](https://unum-cloud.github.io/usearch/python#user-defined-metrics-and-jit-in-python).
-
-[haversine]: https://ashvardanian.com/posts/abusing-vector-search#geo-spatial-indexing
-[obscure]: https://ashvardanian.com/posts/abusing-vector-search
-[gzip-similarity]: https://twitter.com/LukeGessler/status/1679211291292889100?s=20
-
-## Memory Efficiency, Downcasting, and Quantization
-
-Training a quantization model and dimension-reduction is a common approach to accelerate vector search.
-Those, however, are only sometimes reliable, can significantly affect the statistical properties of your data, and require regular adjustments if your distribution shifts.
-Instead, we have focused on high-precision arithmetic over low-precision downcasted vectors.
-The same index, and `add` and `search` operations will automatically down-cast or up-cast between `f64_t`, `f32_t`, `f16_t`, `i8_t`, and single-bit representations.
-You can use the following command to check, if hardware acceleration is enabled:
-
-```sh
-$ python -c 'from usearch.index import Index; print(Index(ndim=768, metric="cos", dtype="f16").hardware_acceleration)'
-> avx512+f16
-$ python -c 'from usearch.index import Index; print(Index(ndim=166, metric="tanimoto").hardware_acceleration)'
-> avx512+popcnt
-```
-
-Using smaller numeric types will save you RAM needed to store the vectors, but you can also compress the neighbors lists forming our proximity graphs.
-By default, 32-bit `uint32_t` is used to enumerate those, which is not enough if you need to address over 4 Billion entries.
-For such cases we provide a custom `uint40_t` type, that will still be 37.5% more space-efficient than the commonly used 8-byte integers, and will scale up to 1 Trillion entries.
-
-![USearch uint40_t support](https://github.com/unum-cloud/usearch/blob/main/assets/usearch-neighbor-types.png?raw=true)
 
 ## Functionality
 
@@ -434,7 +432,7 @@ doi = {10.5281/zenodo.7949416},
 author = {Vardanian, Ash},
 title = {{USearch by Unum Cloud}},
 url = {https://github.com/unum-cloud/usearch},
-version = {2.9.1},
+version = {2.10.0},
 year = {2023},
 month = oct,
 }

package/javascript/{types → dist/cjs}/usearch.d.ts

@@ -1,4 +1,87 @@
-export class Index {
+type Vector = Float32Array | Float64Array | Int8Array;
+type Matrix = Vector[];
+type VectorOrMatrix = Vector | Matrix;
+/**
+ * Enumeration representing the various metric kinds used to measure the distance between vectors in the index.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum MetricKind {
+    Unknown = "unknown",
+    Cos = "cos",
+    IP = "ip",
+    L2sq = "l2sq",
+    Haversine = "haversine",
+    Divergence = "divergence",
+    Pearson = "pearson",
+    Jaccard = "jaccard",
+    Hamming = "hamming",
+    Tanimoto = "tanimoto",
+    Sorensen = "sorensen"
+}
+/**
+ * Enumeration representing the various scalar kinds used to define the type of scalar values in vectors.
+ * @enum {string}
+ * @readonly
+ */
+export declare enum ScalarKind {
+    Unknown = "unknown",
+    F32 = "f32",
+    F64 = "f64",
+    F16 = "f16",
+    I8 = "i8",
+    B1 = "b1"
+}
+/**
+ * Represents a set of search results.
+ */
+export declare class Matches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    /**
+     * Constructs a Matches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array);
+}
+/**
+ * Represents a set of batched search results.
+ */
+export declare class BatchMatches {
+    keys: BigUint64Array;
+    distances: Float32Array;
+    counts: BigUint64Array;
+    k: number;
+    /**
+     * Constructs a BatchMatches object.
+     *
+     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
+     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
+     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
+     * @param {number} k - The limit for search results per query in the batch.
+     */
+    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: number);
+    /**
+     * Retrieves a Matches object at the specified index in the batch.
+     *
+     * @param {number} i - The index at which to retrieve the Matches object.
+     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
+     */
+    get(i: number): Matches;
+}
+export interface IndexCongif {
+    dimensions: number;
+    metric: MetricKind;
+    quantization: ScalarKind;
+    connectivity: number;
+    expansion_add: number;
+    expansion_search: number;
+    multi: boolean;
+}
+export declare class Index {
+    #private;
     /**
      * Constructs a new index.
      *
@@ -11,16 +94,7 @@ export class Index {
      * @param {boolean} [multi=false] - Optional, default is false.
      * @throws Will throw an error if any of the parameters are of incorrect type or invalid value.
      */
-    constructor(dimensionsOrConfigs: number | {
-        dimensions: number;
-        metric: MetricKind;
-        quantization: ScalarKind;
-        connectivity: number;
-        expansion_add: number;
-        expansion_search: number;
-        multi: boolean;
-    }, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
-    _compiledIndex: any;
+    constructor(dimensionsOrConfigs: number | bigint | IndexCongif, metric?: MetricKind, quantization?: ScalarKind, connectivity?: number, expansion_add?: number, expansion_search?: number, multi?: boolean);
     /**
      * Add vectors to the index.
      *
@@ -43,7 +117,7 @@ export class Index {
      * @throws Will throw an error if the length of keys doesn't match the number of vectors
      *         or if it's not a single key.
      */
-    add(keys: bigint | bigint[] | BigUint64Array, vectors: Float32Array | Float64Array | Int8Array): void;
+    add(keys: bigint | bigint[] | BigUint64Array, vectors: Vector): void;
     /**
      * Perform a k-nearest neighbor search on the index.
      *
@@ -59,13 +133,13 @@ export class Index {
      * query vector. If there are not enough results for a query, the result array is
      * padded with -1s.
      *
-     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of arrays.
+     * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} vectors - Input matrix representing query vectors, can be a TypedArray or an array of TypedArray.
      * @param {number} k - The number of nearest neighbors to search for each query vector.
      * @return {Matches|BatchMatches} - Search results for one or more queries, containing keys, distances, and counts of the matches found.
      * @throws Will throw an error if `k` is not a positive integer or if the size of the vectors is not a multiple of dimensions.
-     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of arrays) or if its flattened size is not a multiple of dimensions.
+     * @throws Will throw an error if `vectors` is not a valid input type (TypedArray or an array of TypedArray) or if its flattened size is not a multiple of dimensions.
      */
-    search(vectors: Float32Array | Float64Array | Int8Array | Array<Array<number>>, k: number): Matches | BatchMatches;
+    search(vectors: VectorOrMatrix, k: number): Matches | BatchMatches;
     /**
      * Verifies the presence of one or more keys in the index.
      *
@@ -135,103 +209,4 @@ export class Index {
      */
     view(path: string): void;
 }
-/**
- * *
- */
-export type MetricKind = string;
-export namespace MetricKind {
-    let Unknown: string;
-    let Cos: string;
-    let IP: string;
-    let L2sq: string;
-    let Haversine: string;
-    let Divergence: string;
-    let Pearson: string;
-    let Jaccard: string;
-    let Hamming: string;
-    let Tanimoto: string;
-    let Sorensen: string;
-}
-/**
- * *
- */
-export type ScalarKind = string;
-export namespace ScalarKind {
-    let Unknown_1: string;
-    export { Unknown_1 as Unknown };
-    export let F32: string;
-    export let F64: string;
-    export let F16: string;
-    export let I8: string;
-    export let B1: string;
-}
-/**
- * Represents a set of search results.
- */
-export class Matches {
-    /**
-     * Constructs a Matches object.
-     *
-     * @param {BigUint64Array} keys - The keys of the nearest neighbors found.
-     * @param {Float32Array} distances - The distances of the nearest neighbors found.
-     */
-    constructor(keys: BigUint64Array, distances: Float32Array);
-    keys: BigUint64Array;
-    distances: Float32Array;
-}
-/**
- * Represents a set of batched search results.
- */
-export class BatchMatches {
-    /**
-     * Constructs a BatchMatches object.
-     *
-     * @param {BigUint64Array} keys - The keys of the nearest neighbors found in the batch.
-     * @param {Float32Array} distances - The distances of the nearest neighbors found in the batch.
-     * @param {BigUint64Array} counts - The number of neighbors found for each query in the batch.
-     * @param {bigint} k - The limit for search results per query in the batch.
-     */
-    constructor(keys: BigUint64Array, distances: Float32Array, counts: BigUint64Array, k: bigint);
-    keys: BigUint64Array;
-    distances: Float32Array;
-    counts: BigUint64Array;
-    k: bigint;
-    /**
-     * Retrieves a Matches object at the specified index in the batch.
-     *
-     * @param {number} i - The index at which to retrieve the Matches object.
-     * @returns {Matches} - A Matches object representing the search results at the specified index in the batch.
-     */
-    get(i: number): Matches;
-}
-/**
- * Performs an exact search on the given dataset to find the best matching vectors for each query.
- *
- * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} dataset - The dataset containing vectors to be searched. It can be a TypedArray or an array of arrays.
- * @param {Float32Array|Float64Array|Int8Array|Array<Array<number>>} queries - The queries containing vectors to search for in the dataset. It can be a TypedArray or an array of arrays.
- * @param {number} dimensions - The dimensionality of the vectors in both the dataset and the queries. It defines the number of elements in each vector.
- * @param {number} count - The number of nearest neighbors to return for each query. If the dataset contains fewer vectors than the specified count, the result will contain only the available vectors.
- * @param {MetricKind} metric - The distance metric to be used for the search.
- * @return {Matches|BatchMatches} - Returns a `Matches` or `BatchMatches` object containing the results of the search.
- * @throws Will throw an error if `dimensions` and `count` are not positive integers.
- * @throws Will throw an error if `metric` is not a valid MetricKind.
- * @throws Will throw an error if `dataset` and `queries` are not valid input types (TypedArray or an array of arrays).
- * @throws Will throw an error if the sizes of the flattened `dataset` and `queries` are not multiples of `dimensions`.
- * @throws Will throw an error if `count` is greater than the number of vectors in the `dataset`.
- *
- * @example
- * const dataset = [[1.0, 2.0], [3.0, 4.0]]; // Two vectors: [1.0, 2.0] and [3.0, 4.0]
- * const queries = [[1.5, 2.5]]; // One vector: [1.5, 2.5]
- * const dimensions = 2; // The number of elements in each vector.
- * const count = 1; // The number of nearest neighbors to return for each query.
- * const metric = MetricKind.IP; // Using the Inner Product distance metric.
- *
- * const result = exactSearch(dataset, queries, dimensions, count, metric);
- * // result might be:
- * // {
- * //    keys: BigUint64Array [ 1n ],
- * //    distances: Float32Array [ some_value ],
- * // }
- */
-export function exactSearch(dataset: Float32Array | Float64Array | Int8Array | Array<Array<number>>, queries: Float32Array | Float64Array | Int8Array | Array<Array<number>>, dimensions: number, count: number, metric: MetricKind): Matches | BatchMatches;
-//# sourceMappingURL=usearch.d.ts.map
+export {};