usearch 2.21.3 → 2.25.0

package/numkong/numkong.gypi

@@ -0,0 +1,104 @@
+# NumKong GYP include for downstream native addons.
+#
+# Usage in your binding.gyp:
+#
+#   {
+#     "includes": ["<!(node -p \"require.resolve('numkong/numkong.gypi')\")"],
+#     "targets": [{
+#       "target_name": "my_addon",
+#       "dependencies": ["numkong_lib"],
+#       "sources": ["my_addon.c"],
+#     }]
+#   }
+#
+{
+    "variables": {
+        "numkong_root%": "<!(node -e \"try{console.log(require('path').dirname(require.resolve('numkong/package.json')))}catch{console.log('numkong')}\")",
+    },
+    "targets": [
+        {
+            "target_name": "numkong_lib",
+            "type": "static_library",
+            "actions": [
+                {
+                    "action_name": "numkong_probe",
+                    "inputs": ["<(numkong_root)/probes/probe.js"],
+                    "outputs": ["<!(node -e \"console.log(require('path').resolve('<(numkong_root)','nk_probes.h'))\")"],
+                    "action": ["node", "<(numkong_root)/probes/probe.js"],
+                    "message": "Probing ISA capabilities for NumKong",
+                },
+            ],
+            "sources": [
+                "<(numkong_root)/c/numkong.c",
+                "<(numkong_root)/c/dispatch_f64.c",
+                "<(numkong_root)/c/dispatch_f32.c",
+                "<(numkong_root)/c/dispatch_f16.c",
+                "<(numkong_root)/c/dispatch_bf16.c",
+                "<(numkong_root)/c/dispatch_i8.c",
+                "<(numkong_root)/c/dispatch_u8.c",
+                "<(numkong_root)/c/dispatch_u1.c",
+                "<(numkong_root)/c/dispatch_e4m3.c",
+                "<(numkong_root)/c/dispatch_e5m2.c",
+                "<(numkong_root)/c/dispatch_other.c",
+                "<(numkong_root)/c/dispatch_f64c.c",
+                "<(numkong_root)/c/dispatch_f32c.c",
+                "<(numkong_root)/c/dispatch_f16c.c",
+                "<(numkong_root)/c/dispatch_bf16c.c",
+                "<(numkong_root)/c/dispatch_i16.c",
+                "<(numkong_root)/c/dispatch_i32.c",
+                "<(numkong_root)/c/dispatch_i64.c",
+                "<(numkong_root)/c/dispatch_u16.c",
+                "<(numkong_root)/c/dispatch_u32.c",
+                "<(numkong_root)/c/dispatch_u64.c",
+                "<(numkong_root)/c/dispatch_i4.c",
+                "<(numkong_root)/c/dispatch_u4.c",
+                "<(numkong_root)/c/dispatch_e2m3.c",
+                "<(numkong_root)/c/dispatch_e3m2.c",
+            ],
+            "include_dirs": [
+                "<(numkong_root)/include",
+            ],
+            "defines": [
+                "NK_NATIVE_F16=0",
+                "NK_NATIVE_BF16=0",
+                "NK_DYNAMIC_DISPATCH=1",
+            ],
+            "cflags": [
+                "-std=c11",
+                "-O3",
+                "-Wno-unknown-pragmas",
+                "-Wno-maybe-uninitialized",
+                "-Wno-cast-function-type",
+                "-Wno-switch",
+                "-Wno-psabi",
+                "-include",
+                "<!(node -e \"console.log(require('path').resolve('<(numkong_root)','nk_probes.h'))\")",
+            ],
+            "msvs_settings": {
+                "VCCLCompilerTool": {
+                    "ForcedIncludeFiles": [
+                        "<!(node -e \"console.log(require('path').resolve('<(numkong_root)','nk_probes.h'))\")",
+                    ],
+                    "AdditionalOptions": [
+                        "/Zc:preprocessor"
+                    ],
+                },
+            },
+            "conditions": [
+                [
+                    "OS=='mac'",
+                    {
+                        "xcode_settings": {
+                            "MACOSX_DEPLOYMENT_TARGET": "11.0",
+                        },
+                    },
+                ],
+            ],
+            "direct_dependent_settings": {
+                "include_dirs": [
+                    "<(numkong_root)/include",
+                ],
+            },
+        },
+    ],
+}

package/numkong/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "numkong",
+  "version": "7.5.0",
+  "description": "Portable mixed-precision math, linear-algebra, & retrieval library with 2000+ SIMD kernels for x86, Arm, RISC-V, LoongArch, Power, & WebAssembly",
+  "homepage": "https://github.com/ashvardanian/NumKong",
+  "author": "Ash Vardanian",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ashvardanian/NumKong"
+  },
+  "keywords": [
+    "vector",
+    "distance",
+    "similarity",
+    "search",
+    "ai",
+    "math",
+    "avx2",
+    "avx512",
+    "neon",
+    "sve",
+    "arm",
+    "x86",
+    "simd",
+    "f16"
+  ],
+  "scripts": {
+    "preinstall": "node probes/probe.js",
+    "install": "node-gyp-build",
+    "build-js": "rm -fr javascript/dist/* && tsc -p javascript/tsconfig-esm.json && tsc -p javascript/tsconfig-cjs.json && cp javascript/dist-package-esm.json javascript/dist/esm/package.json && cp javascript/dist-package-cjs.json javascript/dist/cjs/package.json",
+    "build-browser": "esbuild javascript/dist/esm/numkong-browser.js --bundle --format=esm --platform=browser --target=es2022 --outfile=build-wasm/numkong-bundle.js",
+    "test": "node --test ./test/test.mjs",
+    "test:bun": "bun test ./test/test.mjs",
+    "test:deno": "deno test -A --no-check",
+    "test:wasm:emscripten": "NK_RUNTIME=emscripten node --test test/test-wasm.mjs",
+    "test:wasm:emscripten64": "NK_RUNTIME=emscripten64 node --test test/test-wasm.mjs",
+    "test:wasm:wasi": "NK_RUNTIME=wasi-node node --test test/test-wasm.mjs",
+    "test:wasm:browser": "npx playwright test",
+    "test:wasm:all": "npm run test:wasm:emscripten && npm run test:wasm:emscripten64 && npm run test:wasm:wasi && npm run test:wasm:browser",
+    "bench": "node bench/bench.mjs",
+    "bench:native": "NK_RUNTIME=native node bench/bench.mjs",
+    "bench:emscripten": "NK_RUNTIME=emscripten node bench/bench.mjs",
+    "bench:wasi": "NK_RUNTIME=wasi node bench/bench.mjs",
+    "bench:browser": "node bench/bench.mjs --browser",
+    "bench:all": "npm run bench:native && npm run bench:emscripten && npm run bench:wasi && npm run bench:browser",
+    "bench:report": "node bench/bench.mjs --report"
+  },
+  "main": "javascript/dist/cjs/numkong.js",
+  "module": "javascript/dist/esm/numkong.js",
+  "exports": {
+    ".": {
+      "import": "./javascript/dist/esm/numkong.js",
+      "require": "./javascript/dist/cjs/numkong.js"
+    },
+    "./wasm": {
+      "import": "./wasm/numkong.js",
+      "types": "./wasm/numkong.d.ts"
+    },
+    "./numkong.gypi": "./numkong.gypi",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "bindings": "^1.5.0",
+    "node-addon-api": "^8.5.0",
+    "node-gyp-build": "^4.8.4"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.0",
+    "@types/bindings": "^1.5.5",
+    "@types/node": "^24.10.0",
+    "node-gyp": "^11.5.0",
+    "playwright": "^1.58.0",
+    "http-server": "^14.1.1",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.3",
+    "benchmark": "^2.1.4",
+    "mathjs": "^14.9.0",
+    "usearch": "^2.21.0"
+  },
+  "files": [
+    "c/",
+    "include/",
+    "javascript/dist/",
+    "javascript/*.ts",
+    "javascript/*.json",
+    "javascript/*.c",
+    "probes/",
+    "wasm/",
+    "binding.gyp",
+    "numkong.gypi",
+    "LICENSE"
+  ],
+  "prettier": {
+    "printWidth": 120
+  },
+  "optionalDependencies": {
+    "@numkong/darwin-arm64": "7.5.0",
+    "@numkong/darwin-x64": "7.5.0",
+    "@numkong/linux-arm64": "7.5.0",
+    "@numkong/linux-x64": "7.5.0",
+    "@numkong/win32-arm64": "7.5.0",
+    "@numkong/win32-x64": "7.5.0"
+  }
+}

package/numkong/probes/arm_neon.c

@@ -0,0 +1,8 @@
+/* NumKong ISA probe: NEON (AArch64 baseline SIMD) */
+#include <arm_neon.h>
+int main(void) {
+    float32x4_t a = vdupq_n_f32(1.0f);
+    float32x4_t b = vdupq_n_f32(2.0f);
+    float32x4_t c = vaddq_f32(a, b);
+    return vgetq_lane_f32(c, 0) > 0.0f ? 0 : 1;
+}

package/numkong/probes/arm_neon_bfdot.c

@@ -0,0 +1,9 @@
+/* NumKong ISA probe: NEON BF16 (ARMv8.6-A bfloat16 dot product) */
+#include <arm_neon.h>
+int main(void) {
+    bfloat16x8_t a = vdupq_n_bf16(1.0f);
+    bfloat16x8_t b = vdupq_n_bf16(2.0f);
+    float32x4_t c = vdupq_n_f32(0.0f);
+    c = vbfdotq_f32(c, a, b);
+    return vgetq_lane_f32(c, 0) > 0.0f ? 0 : 1;
+}

package/numkong/probes/arm_neon_fhm.c

@@ -0,0 +1,9 @@
+/* NumKong ISA probe: NEON FHM (ARMv8.2-A FP16 fused multiply-add) */
+#include <arm_neon.h>
+int main(void) {
+    float16x8_t a = vdupq_n_f16(1.0f);
+    float16x8_t b = vdupq_n_f16(2.0f);
+    float32x4_t c = vdupq_n_f32(0.0f);
+    c = vfmlalq_low_f16(c, a, b);
+    return vgetq_lane_f32(c, 0) > 0.0f ? 0 : 1;
+}

package/numkong/probes/arm_neon_half.c

@@ -0,0 +1,8 @@
+/* NumKong ISA probe: NEON F16 (ARMv8.2-A half-precision) */
+#include <arm_neon.h>
+int main(void) {
+    float16x8_t a = vdupq_n_f16(1.0f);
+    float16x8_t b = vdupq_n_f16(2.0f);
+    float16x8_t c = vaddq_f16(a, b);
+    return vgetq_lane_f16(c, 0) > 0.0f ? 0 : 1;
+}

package/numkong/probes/arm_neon_sdot.c

@@ -0,0 +1,9 @@
+/* NumKong ISA probe: NEON SDOT (ARMv8.2-A dot product) */
+#include <arm_neon.h>
+int main(void) {
+    int8x16_t a = vdupq_n_s8(1);
+    int8x16_t b = vdupq_n_s8(2);
+    int32x4_t c = vdupq_n_s32(0);
+    c = vdotq_s32(c, a, b);
+    return vgetq_lane_s32(c, 0) > 0 ? 0 : 1;
+}

package/numkong/probes/arm_neonfp8.c

@@ -0,0 +1,9 @@
+/* NumKong ISA probe: NEON FP8 (fp8dot4) */
+#include <arm_neon.h>
+int test_neonfp8(void) {
+    mfloat8x16_t a = vreinterpretq_mf8_u8(vdupq_n_u8(0));
+    float32x4_t acc = vdupq_n_f32(0.0f);
+    acc = vdot_f32_mf8_fpm(acc, a, a, 0);
+    return vgetq_lane_f32(acc, 0) == 0.0f ? 0 : 1;
+}
+int main(void) { return test_neonfp8(); }

package/numkong/probes/arm_sme.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME (Scalable Matrix Extension) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_sme(void) {
+    svfloat32_t a = svdup_f32(1.0f);
+    svbool_t p = svptrue_b32();
+    svmopa_za32_f32_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_sme(); }

package/numkong/probes/arm_sme2.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME2 */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME2)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_sme2(void) {
+    svfloat32_t a = svdup_f32(1.0f);
+    svbool_t p = svptrue_b32();
+    svmopa_za32_f32_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_sme2(); }

package/numkong/probes/arm_sme2p1.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME2P1 */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME2)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_sme2p1(void) {
+    svfloat32_t a = svdup_f32(1.0f);
+    svbool_t p = svptrue_b32();
+    svmopa_za32_f32_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_sme2p1(); }

package/numkong/probes/arm_sme_bf16.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME BF16 (BFloat16 outer product) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_smebf16(void) {
+    svbfloat16_t a = svdup_bf16(0.0f);
+    svbool_t p = svptrue_b16();
+    svmopa_za32_bf16_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_smebf16(); }

package/numkong/probes/arm_sme_bi32.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME BI32 (boolean/integer 32-bit outer product) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME2)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_smebi32(void) {
+    svuint32_t a = svdup_u32(1);
+    svbool_t p = svptrue_b32();
+    svbmopa_za32_u32_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_smebi32(); }

package/numkong/probes/arm_sme_f64.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME F64 (FEAT_SME_F64F64) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_smef64(void) {
+    svfloat64_t a = svdup_f64(1.0);
+    svbool_t p = svptrue_b64();
+    svmopa_za64_f64_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_smef64(); }

package/numkong/probes/arm_sme_fa64.c

@@ -0,0 +1,14 @@
+/* NumKong ISA probe: SME FA64 (FEAT_SME_FA64, full SVE2 in streaming mode) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_locally_streaming int test_smefa64(void) {
+    svfloat32_t a = svdup_f32(1.0f);
+    return (int)svaddv_f32(svptrue_b32(), a) > 0 ? 0 : 1;
+}
+int main(void) { return test_smefa64(); }

package/numkong/probes/arm_sme_half.c

@@ -0,0 +1,16 @@
+/* NumKong ISA probe: SME F16 (FEAT_SME_F16F16) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("za") __arm_locally_streaming int test_smehalf(void) {
+    svfloat16_t a = svdup_f16((__fp16)1.0f);
+    svbool_t p = svptrue_b16();
+    svmopa_za32_f16_m(0, p, p, a, a);
+    return 0;
+}
+int main(void) { return test_smehalf(); }

package/numkong/probes/arm_sme_lut2.c

@@ -0,0 +1,15 @@
+/* NumKong ISA probe: SME LUT2 (FEAT_SME_LUTv2) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if !defined(__ARM_FEATURE_SME2)
+#error "Feature not available"
+#endif
+#include <arm_sme.h>
+__arm_new("zt0") __arm_locally_streaming int test_smelut2(void) {
+    svuint8_t idx = svdup_u8(0);
+    svuint8_t r = svluti2_lane_zt_u8(0, idx, 0);
+    return (int)svaddv_u8(svptrue_b8(), r) == 0 ? 0 : 1;
+}
+int main(void) { return test_smelut2(); }

package/numkong/probes/arm_sve.c

@@ -0,0 +1,18 @@
+/* NumKong ISA probe: SVE (Scalable Vector Extension) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_sve(void) {
+    svfloat32_t z = svdup_f32(1.0f);
+    return (int)svaddv_f32(svptrue_b32(), z);
+}
+int main(void) { return test_sve() > 0 ? 0 : 1; }

package/numkong/probes/arm_sve2.c

@@ -0,0 +1,20 @@
+/* NumKong ISA probe: SVE2 */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE2)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_sve2(void) {
+    svint32_t a = svdup_s32(2);
+    svint32_t b = svdup_s32(3);
+    svint32_t c = svmul_s32_z(svptrue_b32(), a, b);
+    return (int)svaddv_s32(svptrue_b32(), c) > 0 ? 0 : 1;
+}
+int main(void) { return test_sve2(); }

package/numkong/probes/arm_sve2p1.c

@@ -0,0 +1,18 @@
+/* NumKong ISA probe: SVE2P1 */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE2)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_sve2p1(void) {
+    svfloat32_t a = svdup_f32(1.0f);
+    return (int)svaddv_f32(svptrue_b32(), a) > 0 ? 0 : 1;
+}
+int main(void) { return test_sve2p1(); }

package/numkong/probes/arm_sve_bfdot.c

@@ -0,0 +1,20 @@
+/* NumKong ISA probe: SVE BF16 (FEAT_BF16 dot-product) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_svebfdot(void) {
+    svfloat32_t acc = svdup_f32(0.0f);
+    svbfloat16_t a = svdup_bf16(0.0f);
+    acc = svbfdot_f32(acc, a, a);
+    return (int)svaddv_f32(svptrue_b32(), acc) == 0 ? 0 : 1;
+}
+int main(void) { return test_svebfdot(); }

package/numkong/probes/arm_sve_half.c

@@ -0,0 +1,18 @@
+/* NumKong ISA probe: SVE F16 (half-precision) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_svehalf(void) {
+    svfloat16_t z = svdup_f16((__fp16)1.0f);
+    return (int)svaddv_f16(svptrue_b16(), z);
+}
+int main(void) { return test_svehalf() > 0 ? 0 : 1; }

package/numkong/probes/arm_sve_sdot.c

@@ -0,0 +1,21 @@
+/* NumKong ISA probe: SVE I8 signed-dot (FEAT_SVEDot) */
+#if defined(_WIN32)
+#error "SVE/SME not supported on Windows ARM"
+#endif
+
+#if defined(__APPLE__) && defined(__aarch64__)
+#error "SVE not available on Apple Silicon"
+#endif
+
+#if !defined(__ARM_FEATURE_SVE)
+#error "Feature not available"
+#endif
+#include <arm_sve.h>
+int test_svesdot(void) {
+    svint32_t acc = svdup_s32(0);
+    svint8_t a = svdup_s8(1);
+    svint8_t b = svdup_s8(1);
+    acc = svdot_s32(acc, a, b);
+    return (int)svaddv_s32(svptrue_b32(), acc) >= 0 ? 0 : 1;
+}
+int main(void) { return test_svesdot(); }

package/numkong/probes/loongarch_lasx.c

@@ -0,0 +1,12 @@
+/* NumKong ISA probe: LoongArch LASX (256-bit SIMD) */
+#if !defined(__loongarch_asx)
+#error "Feature not available"
+#endif
+#include <lasxintrin.h>
+int main(void) {
+    __m256i a = __lasx_xvreplgr2vr_w(1);
+    __m256i b = __lasx_xvreplgr2vr_w(2);
+    __m256i c = __lasx_xvadd_w(a, b);
+    int r = __lasx_xvpickve2gr_w(c, 0);
+    return r == 3 ? 0 : 1;
+}

package/numkong/probes/power_vsx.c

@@ -0,0 +1,12 @@
+/* NumKong ISA probe: Power VSX (POWER9+ 128-bit SIMD) */
+#if !defined(__VSX__)
+#error "Feature not available"
+#endif
+#include <altivec.h>
+int main(void) {
+    __vector float a = vec_splats(1.0f);
+    __vector float b = vec_splats(2.0f);
+    __vector float c = vec_madd(a, b, a);
+    /* vec_extract requires POWER9+ */
+    return vec_extract(c, 0) == 3.0f ? 0 : 1;
+}