numkong 7.0.0

package/javascript/dist/esm/numkong.js

@@ -0,0 +1,452 @@
+/**
+ * @fileoverview NumKong - Portable mixed-precision BLAS-like vector math library
+ *
+ * NumKong provides SIMD-accelerated distance metrics and vector operations for
+ * x86, ARM, RISC-V, and WASM platforms. The library automatically detects and uses
+ * the best available SIMD instruction set at runtime.
+ *
+ * @module numkong
+ * @author Ash Vardanian
+ *
+ * @example
+ * ```typescript
+ * import { dot, euclidean, Float16Array } from 'numkong';
+ *
+ * // Auto-detected types
+ * const a = new Float32Array([1, 2, 3]);
+ * const b = new Float32Array([4, 5, 6]);
+ * dot(a, b);        // 32
+ * euclidean(a, b);  // 5.196...
+ *
+ * // Custom types with explicit dtype
+ * const c = new Float16Array([1, 2, 3]);
+ * const d = new Float16Array([4, 5, 6]);
+ * dot(c, d, DType.F16); // 32
+ * ```
+ */
+import build from "node-gyp-build";
+import * as path from "node:path";
+import { existsSync } from "node:fs";
+import { getFileName, getRoot } from "bindings";
+import { setConversionFunctions, Float16Array, BFloat16Array, E4M3Array, E5M2Array, BinaryArray, TensorBase, VectorBase, VectorView, Vector, MatrixBase, Matrix, PackedMatrix, DType, dtypeToString, outputDtype } from "./types.js";
+let compiled;
+try {
+    let builddir = getBuildDir(getDirName());
+    compiled = build(builddir);
+    // Initialize conversion functions for types.ts
+    setConversionFunctions({
+        castF16ToF32: compiled.castF16ToF32,
+        castF32ToF16: compiled.castF32ToF16,
+        castBF16ToF32: compiled.castBF16ToF32,
+        castF32ToBF16: compiled.castF32ToBF16,
+        castE4M3ToF32: compiled.castE4M3ToF32,
+        castF32ToE4M3: compiled.castF32ToE4M3,
+        castE5M2ToF32: compiled.castE5M2ToF32,
+        castF32ToE5M2: compiled.castF32ToE5M2,
+        cast: compiled.cast,
+    });
+}
+catch (e) {
+    // Native addon not available
+    // For WASM usage, import the Emscripten module directly (see test/test-wasm.mjs)
+    throw new Error("NumKong native addon not found. Build with `npm run build` or use WASM " +
+        "by importing the Emscripten module directly. See test/test-wasm.mjs for examples.");
+}
+/**
+ * CPU capability bit masks in chronological order (by first commercial silicon).
+ * Use these with getCapabilities() to check for specific SIMD support.
+ */
+export const Capability = {
+    SERIAL: 1n << 0n, // Always: Fallback
+    NEON: 1n << 1n, // 2013: ARM NEON
+    HASWELL: 1n << 2n, // 2013: Intel AVX2
+    SKYLAKE: 1n << 3n, // 2017: Intel AVX-512
+    NEONHALF: 1n << 4n, // 2017: ARM NEON FP16
+    NEONSDOT: 1n << 5n, // 2017: ARM NEON i8 dot
+    NEONFHM: 1n << 6n, // 2018: ARM NEON FP16 FML
+    ICELAKE: 1n << 7n, // 2019: Intel AVX-512 VNNI
+    GENOA: 1n << 8n, // 2020: Intel/AMD AVX-512 BF16
+    NEONBFDOT: 1n << 9n, // 2020: ARM NEON BF16
+    SVE: 1n << 10n, // 2020: ARM SVE
+    SVEHALF: 1n << 11n, // 2020: ARM SVE FP16
+    SVESDOT: 1n << 12n, // 2020: ARM SVE i8 dot
+    SIERRA: 1n << 13n, // 2021: Intel AVX2+VNNI
+    SVEBFDOT: 1n << 14n, // 2021: ARM SVE BF16
+    SVE2: 1n << 15n, // 2022: ARM SVE2
+    V128RELAXED: 1n << 16n, // 2022: WASM Relaxed SIMD
+    SAPPHIRE: 1n << 17n, // 2023: Intel AVX-512 FP16
+    SAPPHIREAMX: 1n << 18n, // 2023: Intel Sapphire AMX
+    RVV: 1n << 19n, // 2023: RISC-V Vector
+    RVVHALF: 1n << 20n, // 2023: RISC-V Zvfh
+    RVVBF16: 1n << 21n, // 2023: RISC-V Zvfbfwma
+    GRANITEAMX: 1n << 22n, // 2024: Intel Granite AMX FP16
+    TURIN: 1n << 23n, // 2024: AMD Turin AVX-512 CD
+    SME: 1n << 24n, // 2024: ARM SME
+    SME2: 1n << 25n, // 2024: ARM SME2
+    SMEF64: 1n << 26n, // 2024: ARM SME F64
+    SMEFA64: 1n << 27n, // 2024: ARM SME FA64
+    SVE2P1: 1n << 28n, // 2025+: ARM SVE2.1
+    SME2P1: 1n << 29n, // 2025+: ARM SME2.1
+    SMEHALF: 1n << 30n, // 2025+: ARM SME F16F16
+    SMEBF16: 1n << 31n, // 2025+: ARM SME B16B16
+    SMELUT2: 1n << 32n, // 2025+: ARM SME LUTv2
+    RVVBB: 1n << 33n, // 2025+: RISC-V Zvbb
+};
+export { Float16Array, BFloat16Array, E4M3Array, E5M2Array, BinaryArray, TensorBase, VectorBase, VectorView, Vector, MatrixBase, Matrix, PackedMatrix, outputDtype };
+/** Convert a single FP16 value (as uint16 bits) to FP32 */
+export const castF16ToF32 = compiled.castF16ToF32;
+/** Convert a single FP32 value to FP16 (returns uint16 bits) */
+export const castF32ToF16 = compiled.castF32ToF16;
+/** Convert a single BF16 value (as uint16 bits) to FP32 */
+export const castBF16ToF32 = compiled.castBF16ToF32;
+/** Convert a single FP32 value to BF16 (returns uint16 bits) */
+export const castF32ToBF16 = compiled.castF32ToBF16;
+/** Convert a single E4M3 value (as uint8 bits) to FP32 */
+export const castE4M3ToF32 = compiled.castE4M3ToF32;
+/** Convert a single FP32 value to E4M3 (returns uint8 bits) */
+export const castF32ToE4M3 = compiled.castF32ToE4M3;
+/** Convert a single E5M2 value (as uint8 bits) to FP32 */
+export const castE5M2ToF32 = compiled.castE5M2ToF32;
+/** Convert a single FP32 value to E5M2 (returns uint8 bits) */
+export const castF32ToE5M2 = compiled.castF32ToE5M2;
+/** Bulk conversion between different numeric types (modifies destination array in-place) */
+export const cast = compiled.cast;
+export { DType };
+/**
+ * Extract a TypedArray from a TensorBase for the N-API backend.
+ *
+ * The native backend doesn't benefit from zero-copy TensorBase (Node.js TypedArrays
+ * already share process memory), but accepting TensorBase keeps the API uniform.
+ */
+function unwrapTensor(input) {
+    switch (input.dtype) {
+        case DType.F64: return { arr: new Float64Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+        case DType.F32: return { arr: new Float32Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+        case DType.F16:
+        case DType.BF16: return { arr: new Uint16Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+        case DType.I8: return { arr: new Int8Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+        case DType.U8:
+        case DType.U1: return { arr: new Uint8Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+        default: return { arr: new Uint8Array(input.buffer, input.byteOffset, input.length), dtype: input.dtype };
+    }
+}
+/**
+ * Returns the runtime-detected SIMD capabilities as a bitmask.
+ *
+ * The bitmask includes flags for various SIMD instruction sets like AVX2, AVX-512,
+ * ARM NEON, ARM SVE, ARM SME, RISC-V Vector, and WASM SIMD extensions.
+ * Use with Capability constants to check for specific instruction sets.
+ *
+ * @returns {bigint} Bitmask of capability flags (use with Capability constants)
+ *
+ * @example
+ * ```ts
+ * import { getCapabilities, Capability } from 'numkong';
+ *
+ * const caps = getCapabilities();
+ * console.log(`Capabilities: 0x${caps.toString(16)}`);
+ *
+ * // Check for specific SIMD support
+ * if (caps & Capability.HASWELL) {
+ *   console.log('AVX2 available');
+ * }
+ * ```
+ */
+export const getCapabilities = () => {
+    return compiled.getCapabilities();
+};
+/**
+ * Checks if a specific SIMD capability is available at runtime.
+ *
+ * This is a convenience wrapper around getCapabilities() that tests for a single capability.
+ *
+ * @param {bigint} cap - Capability flag to check (from Capability constants)
+ * @returns {boolean} True if the capability is available, false otherwise
+ *
+ * @example
+ * ```ts
+ * import { hasCapability, Capability } from 'numkong';
+ *
+ * if (hasCapability(Capability.HASWELL)) {
+ *   console.log('Intel AVX2 (Haswell) available');
+ * }
+ * if (hasCapability(Capability.NEON)) {
+ *   console.log('ARM NEON available');
+ * }
+ * if (hasCapability(Capability.V128RELAXED)) {
+ *   console.log('WASM Relaxed SIMD available');
+ * }
+ * ```
+ */
+export const hasCapability = (cap) => {
+    return (getCapabilities() & cap) !== 0n;
+};
+export function sqeuclidean(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.sqeuclidean(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.sqeuclidean(a, b, dtypeToString(dtype)) : compiled.sqeuclidean(a, b);
+}
+export function euclidean(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.euclidean(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.euclidean(a, b, dtypeToString(dtype)) : compiled.euclidean(a, b);
+}
+export function angular(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.angular(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.angular(a, b, dtypeToString(dtype)) : compiled.angular(a, b);
+}
+export function inner(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.inner(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.inner(a, b, dtypeToString(dtype)) : compiled.inner(a, b);
+}
+export function dot(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.dot(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.dot(a, b, dtypeToString(dtype)) : compiled.dot(a, b);
+}
+/**
+ * Computes the bitwise Hamming distance between two vectors.
+ *
+ * Both vectors are treated as bit-packed (u1 dtype), where each byte contains 8 bits.
+ * Use toBinary() to convert numeric arrays to bit-packed format.
+ *
+ * @param {Uint8Array | BinaryArray} a - The first bit-packed vector.
+ * @param {Uint8Array | BinaryArray} b - The second bit-packed vector.
+ * @returns {number} The Hamming distance (number of differing bits) between vectors a and b.
+ */
+export const hamming = (a, b) => {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.hamming(u.arr, v.arr);
+    }
+    return compiled.hamming(a, b);
+};
+/**
+ * Computes the bitwise Jaccard distance between two vectors.
+ *
+ * Both vectors are treated as bit-packed (u1 dtype), where each byte contains 8 bits.
+ * Use toBinary() to convert numeric arrays to bit-packed format.
+ *
+ * @param {Uint8Array | BinaryArray} a - The first bit-packed vector.
+ * @param {Uint8Array | BinaryArray} b - The second bit-packed vector.
+ * @returns {number} The Jaccard distance (1 - Jaccard similarity) between vectors a and b.
+ */
+export const jaccard = (a, b) => {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.jaccard(u.arr, v.arr);
+    }
+    return compiled.jaccard(a, b);
+};
+export function kullbackleibler(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.kullbackleibler(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.kullbackleibler(a, b, dtypeToString(dtype)) : compiled.kullbackleibler(a, b);
+}
+export function jensenshannon(a, b, dtype) {
+    if (a instanceof TensorBase) {
+        const u = unwrapTensor(a), v = unwrapTensor(b);
+        return compiled.jensenshannon(u.arr, v.arr, dtypeToString(u.dtype));
+    }
+    return dtype !== undefined ? compiled.jensenshannon(a, b, dtypeToString(dtype)) : compiled.jensenshannon(a, b);
+}
+/**
+ * Quantizes a numeric vector into a bit-packed binary representation.
+ *
+ * Converts each element to a single bit: 1 for positive values, 0 for non-positive values.
+ * The bits are packed into bytes (8 bits per byte) in big-endian bit order within each byte.
+ * This is the required format for hamming() and jaccard() distance functions.
+ *
+ * @param {Float32Array | Float64Array | Int8Array} vector - The vector to quantize and pack.
+ * @returns {Uint8Array} A bit-packed array where each byte contains 8 binary values.
+ *
+ * @example
+ * ```ts
+ * const vec = new Float32Array([1.5, -2.3, 0.0, 3.1, -1.0, 2.0, 0.5, -0.5]);
+ * const binary = toBinary(vec);
+ * // Result: Uint8Array([0b10010110]) = [0x96]
+ * //   bits: [1, 0, 0, 1, 0, 1, 1, 0] for elements [+, -, 0, +, -, +, +, -]
+ *
+ * // Use with Hamming distance
+ * const a = toBinary(new Float32Array([1, 2, 3]));
+ * const b = toBinary(new Float32Array([1, -2, 3]));
+ * const dist = hamming(a, b); // Counts differing bits
+ * ```
+ */
+export const toBinary = (vector) => {
+    const byteLength = Math.ceil(vector.length / 8);
+    const packedVector = new Uint8Array(byteLength);
+    for (let i = 0; i < vector.length; i++) {
+        if (vector[i] > 0) {
+            const byteIndex = Math.floor(i / 8);
+            const bitPosition = 7 - (i % 8);
+            packedVector[byteIndex] |= (1 << bitPosition);
+        }
+    }
+    return packedVector;
+};
+/**
+ * Extract a TypedArray from a Matrix for passing to the N-API backend.
+ */
+function unwrapMatrix(matrix) {
+    switch (matrix.dtype) {
+        case DType.F64: return { array: new Float64Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+        case DType.F32: return { array: new Float32Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+        case DType.F16:
+        case DType.BF16: return { array: new Uint16Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+        case DType.I8: return { array: new Int8Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+        case DType.U8: return { array: new Uint8Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+        default: return { array: new Uint8Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols), dtype: matrix.dtype };
+    }
+}
+/**
+ * Extract a result TypedArray from a Matrix matching its output dtype.
+ */
+function unwrapResultMatrix(matrix) {
+    switch (matrix.dtype) {
+        case DType.F64: return new Float64Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols);
+        case DType.F32: return new Float32Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols);
+        case DType.I32: return new Int32Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols);
+        case DType.U32: return new Uint32Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols);
+        default: return new Float64Array(matrix.buffer, matrix.byteOffset, matrix.rows * matrix.cols);
+    }
+}
+/**
+ * Query the packed buffer byte count for a given matrix shape and dtype.
+ */
+export function dotsPackedSize(width, depth, dtype) {
+    return compiled.dotsPackedSize(width, depth, dtypeToString(dtype));
+}
+/**
+ * Pack a Matrix for use with packed GEMM-like operations.
+ */
+export function dotsPack(matrix) {
+    const { array, dtype } = unwrapMatrix(matrix);
+    const result = compiled.dotsPack(array, matrix.rows, matrix.cols, matrix.rowStride, dtypeToString(dtype));
+    return new PackedMatrix(result.buffer, result.width, result.depth, matrix.dtype, result.byteLength);
+}
+function packedOperation(compiledName, family, a, packed, out) {
+    if (a.cols !== packed.depth) {
+        throw new Error(`Matrix cols (${a.cols}) must match packed depth (${packed.depth})`);
+    }
+    const outDtype = outputDtype(family, a.dtype);
+    if (!out) {
+        out = new Matrix(a.rows, packed.width, outDtype);
+    }
+    const aUnwrapped = unwrapMatrix(a);
+    const resultArray = unwrapResultMatrix(out);
+    compiled[compiledName](aUnwrapped.array, packed.buffer, resultArray, a.rows, packed.width, a.cols, a.rowStride, out.rowStride, dtypeToString(a.dtype));
+    return out;
+}
+function symmetricOperation(compiledName, family, vectors, out, rowStart = 0, rowCount) {
+    const count = rowCount ?? vectors.rows - rowStart;
+    const outDtype = outputDtype(family, vectors.dtype);
+    if (!out) {
+        out = new Matrix(vectors.rows, vectors.rows, outDtype);
+    }
+    const vectorsUnwrapped = unwrapMatrix(vectors);
+    const resultArray = unwrapResultMatrix(out);
+    compiled[compiledName](vectorsUnwrapped.array, resultArray, vectors.rows, vectors.cols, vectors.rowStride, out.rowStride, rowStart, count, dtypeToString(vectors.dtype));
+    return out;
+}
+export function dotsPacked(a, packed, out) {
+    return packedOperation('dotsPacked', 'dots', a, packed, out);
+}
+export function angularsPacked(a, packed, out) {
+    return packedOperation('angularsPacked', 'angulars', a, packed, out);
+}
+export function euclideansPacked(a, packed, out) {
+    return packedOperation('euclideansPacked', 'euclideans', a, packed, out);
+}
+export function dotsSymmetric(vectors, out, options) {
+    return symmetricOperation('dotsSymmetric', 'dots', vectors, out, options?.rowStart ?? 0, options?.rowCount);
+}
+export function angularsSymmetric(vectors, out, options) {
+    return symmetricOperation('angularsSymmetric', 'angulars', vectors, out, options?.rowStart ?? 0, options?.rowCount);
+}
+export function euclideansSymmetric(vectors, out, options) {
+    return symmetricOperation('euclideansSymmetric', 'euclideans', vectors, out, options?.rowStart ?? 0, options?.rowCount);
+}
+export default {
+    dot,
+    inner,
+    sqeuclidean,
+    euclidean,
+    angular,
+    hamming,
+    jaccard,
+    kullbackleibler,
+    jensenshannon,
+    toBinary,
+    Float16Array,
+    BFloat16Array,
+    E4M3Array,
+    E5M2Array,
+    BinaryArray,
+    TensorBase,
+    VectorBase,
+    VectorView,
+    Vector,
+    MatrixBase,
+    Matrix,
+    PackedMatrix,
+    castF16ToF32,
+    castF32ToF16,
+    castBF16ToF32,
+    castF32ToBF16,
+    castE4M3ToF32,
+    castF32ToE4M3,
+    castE5M2ToF32,
+    castF32ToE5M2,
+    cast,
+    dotsPack,
+    dotsPacked,
+    angularsPacked,
+    euclideansPacked,
+    dotsSymmetric,
+    angularsSymmetric,
+    euclideansSymmetric,
+    dotsPackedSize,
+    outputDtype,
+};
+/**
+ * Finds the directory where the native build of the numkong module is located.
+ * @param {string} dir - The directory to start the search from.
+ */
+function getBuildDir(dir) {
+    if (existsSync(path.join(dir, "build")))
+        return dir;
+    if (existsSync(path.join(dir, "prebuilds")))
+        return dir;
+    if (path.basename(dir) === ".next") {
+        // special case for next.js on custom node (not vercel)
+        const sideways = path.join(dir, "..", "node_modules", "numkong");
+        if (existsSync(sideways))
+            return getBuildDir(sideways);
+    }
+    if (dir === "/")
+        throw new Error("Could not find native build for numkong");
+    return getBuildDir(path.join(dir, ".."));
+}
+function getDirName() {
+    try {
+        if (__dirname)
+            return __dirname;
+    }
+    catch (e) { }
+    return getRoot(getFileName());
+}

package/javascript/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+    "type": "module"
+}