ruvector 0.1.38 → 0.1.40

package/dist/core/attention-fallbacks.js

@@ -0,0 +1,361 @@
+"use strict";
+/**
+ * Attention Fallbacks - Safe wrapper around @ruvector/attention with automatic array conversion
+ *
+ * This wrapper handles the array type conversion automatically, allowing users
+ * to pass either regular arrays or Float32Arrays.
+ *
+ * @ruvector/attention requires Float32Array inputs.
+ * This wrapper handles the conversion automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MoEAttention = exports.LocalGlobalAttention = exports.LinearAttention = exports.HyperbolicAttention = exports.FlashAttention = exports.MultiHeadAttention = void 0;
+exports.projectToPoincareBall = projectToPoincareBall;
+exports.poincareDistance = poincareDistance;
+exports.mobiusAddition = mobiusAddition;
+exports.expMap = expMap;
+exports.logMap = logMap;
+exports.isAttentionAvailable = isAttentionAvailable;
+exports.getAttentionVersion = getAttentionVersion;
+// Lazy load to avoid import errors if not installed
+let attentionModule = null;
+let loadError = null;
+function getAttentionModule() {
+    if (attentionModule)
+        return attentionModule;
+    if (loadError)
+        throw loadError;
+    try {
+        attentionModule = require('@ruvector/attention');
+        return attentionModule;
+    }
+    catch (e) {
+        loadError = new Error(`@ruvector/attention is not installed or failed to load: ${e.message}\n` +
+            `Install with: npm install @ruvector/attention`);
+        throw loadError;
+    }
+}
+/**
+ * Convert any array-like input to Float32Array
+ */
+function toFloat32Array(input) {
+    if (input instanceof Float32Array) {
+        return input;
+    }
+    return new Float32Array(input);
+}
+/**
+ * Convert nested arrays to Float32Arrays
+ */
+function toFloat32Arrays(inputs) {
+    return inputs.map(arr => toFloat32Array(arr));
+}
+/**
+ * Convert Float32Array result back to regular array if needed
+ */
+function fromFloat32Array(input) {
+    return Array.from(input);
+}
+/**
+ * Multi-head attention mechanism
+ *
+ * This wrapper automatically converts array inputs to Float32Array.
+ */
+class MultiHeadAttention {
+    /**
+     * Create a new multi-head attention instance
+     *
+     * @param dim - Embedding dimension (must be divisible by numHeads)
+     * @param numHeads - Number of attention heads
+     */
+    constructor(dim, numHeads) {
+        const attention = getAttentionModule();
+        this.inner = new attention.MultiHeadAttention(dim, numHeads);
+        this.dim = dim;
+        this.numHeads = numHeads;
+    }
+    /**
+     * Compute multi-head attention
+     *
+     * @param query - Query vector
+     * @param keys - Array of key vectors
+     * @param values - Array of value vectors
+     * @returns Attention output
+     *
+     * @example
+     * ```typescript
+     * const mha = new MultiHeadAttention(64, 4);
+     *
+     * // Works with regular arrays
+     * const result1 = mha.compute([...64 values], [[...64], [...64]], [[...64], [...64]]);
+     *
+     * // Also works with Float32Array
+     * const q = new Float32Array(64);
+     * const k = [new Float32Array(64)];
+     * const v = [new Float32Array(64)];
+     * const result2 = mha.compute(q, k, v);
+     * ```
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    /**
+     * Compute and return raw Float32Array (faster, no conversion)
+     */
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+    get headDim() {
+        return this.dim / this.numHeads;
+    }
+}
+exports.MultiHeadAttention = MultiHeadAttention;
+/**
+ * Flash attention with tiled computation
+ */
+class FlashAttention {
+    /**
+     * Create a new flash attention instance
+     *
+     * @param dim - Embedding dimension
+     * @param blockSize - Block size for tiled computation (default: 512)
+     */
+    constructor(dim, blockSize = 512) {
+        const attention = getAttentionModule();
+        this.inner = new attention.FlashAttention(dim, blockSize);
+        this.dim = dim;
+        this.blockSize = blockSize;
+    }
+    /**
+     * Compute flash attention
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+}
+exports.FlashAttention = FlashAttention;
+/**
+ * Hyperbolic attention in Poincare ball model
+ */
+class HyperbolicAttention {
+    /**
+     * Create a new hyperbolic attention instance
+     *
+     * @param dim - Embedding dimension
+     * @param curvature - Hyperbolic curvature (typically 1.0)
+     */
+    constructor(dim, curvature = 1.0) {
+        const attention = getAttentionModule();
+        this.inner = new attention.HyperbolicAttention(dim, curvature);
+        this.dim = dim;
+        this.curvature = curvature;
+    }
+    /**
+     * Compute hyperbolic attention
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+}
+exports.HyperbolicAttention = HyperbolicAttention;
+/**
+ * Linear attention (Performer-style) with O(n) complexity
+ */
+class LinearAttention {
+    /**
+     * Create a new linear attention instance
+     *
+     * @param dim - Embedding dimension
+     * @param numFeatures - Number of random features
+     */
+    constructor(dim, numFeatures) {
+        const attention = getAttentionModule();
+        this.inner = new attention.LinearAttention(dim, numFeatures);
+        this.dim = dim;
+        this.numFeatures = numFeatures;
+    }
+    /**
+     * Compute linear attention
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+}
+exports.LinearAttention = LinearAttention;
+/**
+ * Local-global attention (Longformer-style)
+ */
+class LocalGlobalAttention {
+    /**
+     * Create a new local-global attention instance
+     *
+     * @param dim - Embedding dimension
+     * @param localWindow - Size of local attention window
+     * @param globalTokens - Number of global attention tokens
+     */
+    constructor(dim, localWindow, globalTokens) {
+        const attention = getAttentionModule();
+        this.inner = new attention.LocalGlobalAttention(dim, localWindow, globalTokens);
+        this.dim = dim;
+        this.localWindow = localWindow;
+        this.globalTokens = globalTokens;
+    }
+    /**
+     * Compute local-global attention
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+}
+exports.LocalGlobalAttention = LocalGlobalAttention;
+/**
+ * Mixture of Experts attention
+ */
+class MoEAttention {
+    /**
+     * Create a new MoE attention instance
+     *
+     * @param config - MoE configuration
+     */
+    constructor(config) {
+        const attention = getAttentionModule();
+        this.inner = new attention.MoEAttention({
+            dim: config.dim,
+            num_experts: config.numExperts,
+            top_k: config.topK,
+            expert_capacity: config.expertCapacity ?? 1.25,
+        });
+        this.config = config;
+    }
+    /**
+     * Create with simple parameters
+     */
+    static simple(dim, numExperts, topK) {
+        return new MoEAttention({ dim, numExperts, topK });
+    }
+    /**
+     * Compute MoE attention
+     */
+    compute(query, keys, values) {
+        const raw = this.inner.compute(toFloat32Array(query), toFloat32Arrays(keys), toFloat32Arrays(values));
+        return {
+            values: fromFloat32Array(raw),
+            raw
+        };
+    }
+    computeRaw(query, keys, values) {
+        return this.inner.compute(query, keys, values);
+    }
+}
+exports.MoEAttention = MoEAttention;
+// Hyperbolic math utilities
+/**
+ * Project a vector into the Poincare ball
+ */
+function projectToPoincareBall(vector, curvature = 1.0) {
+    const attention = getAttentionModule();
+    const result = attention.projectToPoincareBall(toFloat32Array(vector), curvature);
+    return fromFloat32Array(result);
+}
+/**
+ * Compute hyperbolic (Poincare) distance between two points
+ */
+function poincareDistance(a, b, curvature = 1.0) {
+    const attention = getAttentionModule();
+    return attention.poincareDistance(toFloat32Array(a), toFloat32Array(b), curvature);
+}
+/**
+ * Mobius addition in hyperbolic space
+ */
+function mobiusAddition(a, b, curvature = 1.0) {
+    const attention = getAttentionModule();
+    const result = attention.mobiusAddition(toFloat32Array(a), toFloat32Array(b), curvature);
+    return fromFloat32Array(result);
+}
+/**
+ * Exponential map from tangent space to hyperbolic space
+ */
+function expMap(base, tangent, curvature = 1.0) {
+    const attention = getAttentionModule();
+    const result = attention.expMap(toFloat32Array(base), toFloat32Array(tangent), curvature);
+    return fromFloat32Array(result);
+}
+/**
+ * Logarithmic map from hyperbolic space to tangent space
+ */
+function logMap(base, point, curvature = 1.0) {
+    const attention = getAttentionModule();
+    const result = attention.logMap(toFloat32Array(base), toFloat32Array(point), curvature);
+    return fromFloat32Array(result);
+}
+/**
+ * Check if attention module is available
+ */
+function isAttentionAvailable() {
+    try {
+        getAttentionModule();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get attention module version
+ */
+function getAttentionVersion() {
+    try {
+        const attention = getAttentionModule();
+        return attention.version?.() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+exports.default = {
+    MultiHeadAttention,
+    FlashAttention,
+    HyperbolicAttention,
+    LinearAttention,
+    LocalGlobalAttention,
+    MoEAttention,
+    projectToPoincareBall,
+    poincareDistance,
+    mobiusAddition,
+    expMap,
+    logMap,
+    isAttentionAvailable,
+    getAttentionVersion,
+};

package/dist/core/gnn-wrapper.d.ts

@@ -0,0 +1,143 @@
+/**
+ * GNN Wrapper - Safe wrapper around @ruvector/gnn with automatic array conversion
+ *
+ * This wrapper handles the array type conversion automatically, allowing users
+ * to pass either regular arrays or Float32Arrays.
+ *
+ * The native @ruvector/gnn requires Float32Array for maximum performance.
+ * This wrapper converts any input type to Float32Array automatically.
+ *
+ * Performance Tips:
+ * - Pass Float32Array directly for zero-copy performance
+ * - Use toFloat32Array/toFloat32ArrayBatch for pre-conversion
+ * - Avoid repeated conversions in hot paths
+ */
+/**
+ * Convert any array-like input to Float32Array (native requires Float32Array)
+ * Optimized paths:
+ * - Float32Array: zero-copy return
+ * - Float64Array: efficient typed array copy
+ * - Array: direct Float32Array construction
+ */
+export declare function toFloat32Array(input: number[] | Float32Array | Float64Array): Float32Array;
+/**
+ * Convert array of arrays to array of Float32Arrays
+ */
+export declare function toFloat32ArrayBatch(input: (number[] | Float32Array | Float64Array)[]): Float32Array[];
+/**
+ * Search result from differentiable search
+ */
+export interface DifferentiableSearchResult {
+    /** Indices of top-k candidates */
+    indices: number[];
+    /** Soft weights for top-k candidates */
+    weights: number[];
+}
+/**
+ * Differentiable search using soft attention mechanism
+ *
+ * This wrapper automatically converts Float32Array inputs to regular arrays.
+ *
+ * @param query - Query vector (array or Float32Array)
+ * @param candidates - List of candidate vectors (arrays or Float32Arrays)
+ * @param k - Number of top results to return
+ * @param temperature - Temperature for softmax (lower = sharper, higher = smoother)
+ * @returns Search result with indices and soft weights
+ *
+ * @example
+ * ```typescript
+ * import { differentiableSearch } from 'ruvector/core/gnn-wrapper';
+ *
+ * // Works with regular arrays (auto-converted to Float32Array)
+ * const result1 = differentiableSearch([1, 0, 0], [[1, 0, 0], [0, 1, 0]], 2, 1.0);
+ *
+ * // For best performance, use Float32Array directly (zero-copy)
+ * const query = new Float32Array([1, 0, 0]);
+ * const candidates = [new Float32Array([1, 0, 0]), new Float32Array([0, 1, 0])];
+ * const result2 = differentiableSearch(query, candidates, 2, 1.0);
+ * ```
+ */
+export declare function differentiableSearch(query: number[] | Float32Array | Float64Array, candidates: (number[] | Float32Array | Float64Array)[], k: number, temperature?: number): DifferentiableSearchResult;
+/**
+ * GNN Layer for HNSW topology
+ */
+export declare class RuvectorLayer {
+    private inner;
+    /**
+     * Create a new Ruvector GNN layer
+     *
+     * @param inputDim - Dimension of input node embeddings
+     * @param hiddenDim - Dimension of hidden representations
+     * @param heads - Number of attention heads
+     * @param dropout - Dropout rate (0.0 to 1.0)
+     */
+    constructor(inputDim: number, hiddenDim: number, heads: number, dropout?: number);
+    /**
+     * Forward pass through the GNN layer
+     *
+     * @param nodeEmbedding - Current node's embedding
+     * @param neighborEmbeddings - Embeddings of neighbor nodes
+     * @param edgeWeights - Weights of edges to neighbors
+     * @returns Updated node embedding as Float32Array
+     */
+    forward(nodeEmbedding: number[] | Float32Array, neighborEmbeddings: (number[] | Float32Array)[], edgeWeights: number[] | Float32Array): Float32Array;
+    /**
+     * Serialize the layer to JSON
+     */
+    toJson(): string;
+    /**
+     * Deserialize the layer from JSON
+     */
+    static fromJson(json: string): RuvectorLayer;
+}
+/**
+ * Tensor compressor with adaptive level selection
+ */
+export declare class TensorCompress {
+    private inner;
+    constructor();
+    /**
+     * Compress an embedding based on access frequency
+     *
+     * @param embedding - Input embedding vector
+     * @param accessFreq - Access frequency (0.0 to 1.0)
+     * @returns Compressed tensor as JSON string
+     */
+    compress(embedding: number[] | Float32Array, accessFreq: number): string;
+    /**
+     * Decompress a compressed tensor
+     *
+     * @param compressedJson - Compressed tensor JSON
+     * @returns Decompressed embedding
+     */
+    decompress(compressedJson: string): number[];
+}
+/**
+ * Hierarchical forward pass through GNN layers
+ *
+ * @param query - Query vector
+ * @param layerEmbeddings - Embeddings organized by layer
+ * @param gnnLayersJson - JSON array of serialized GNN layers
+ * @returns Final embedding after hierarchical processing as Float32Array
+ */
+export declare function hierarchicalForward(query: number[] | Float32Array, layerEmbeddings: (number[] | Float32Array)[][], gnnLayersJson: string[]): Float32Array;
+/**
+ * Get compression level for a given access frequency
+ */
+export declare function getCompressionLevel(accessFreq: number): string;
+/**
+ * Check if GNN module is available
+ */
+export declare function isGnnAvailable(): boolean;
+declare const _default: {
+    differentiableSearch: typeof differentiableSearch;
+    RuvectorLayer: typeof RuvectorLayer;
+    TensorCompress: typeof TensorCompress;
+    hierarchicalForward: typeof hierarchicalForward;
+    getCompressionLevel: typeof getCompressionLevel;
+    isGnnAvailable: typeof isGnnAvailable;
+    toFloat32Array: typeof toFloat32Array;
+    toFloat32ArrayBatch: typeof toFloat32ArrayBatch;
+};
+export default _default;
+//# sourceMappingURL=gnn-wrapper.d.ts.map

package/dist/core/gnn-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gnn-wrapper.d.ts","sourceRoot":"","sources":["../../src/core/gnn-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,GAAG,YAAY,CAK1F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC,EAAE,GAAG,YAAY,EAAE,CAMrG;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,kCAAkC;IAClC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,wCAAwC;IACxC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,EAC7C,UAAU,EAAE,CAAC,MAAM,EAAE,GAAG,YAAY,GAAG,YAAY,CAAC,EAAE,EACtD,CAAC,EAAE,MAAM,EACT,WAAW,GAAE,MAAY,GACxB,0BAA0B,CAQ5B;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAM;IAEnB;;;;;;;OAOG;gBACS,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,MAAY;IAKrF;;;;;;;OAOG;IACH,OAAO,CACL,aAAa,EAAE,MAAM,EAAE,GAAG,YAAY,EACtC,kBAAkB,EAAE,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAC/C,WAAW,EAAE,MAAM,EAAE,GAAG,YAAY,GACnC,YAAY;IAQf;;OAEG;IACH,MAAM,IAAI,MAAM;IAIhB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa;CAM7C;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAM;;IAOnB;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIxE;;;;;OAKG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE;CAG7C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EAAE,GAAG,YAAY,EAC9B,eAAe,EAAE,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,EAAE,EAAE,EAC9C,aAAa,EAAE,MAAM,EAAE,GACtB,YAAY,CAOd;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAOxC;;;;;;;;;;;AAED,wBAUE"}