ruvector 0.1.26 → 0.1.28

package/dist/core/attention-fallbacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attention-fallbacks.d.ts","sourceRoot":"","sources":["../../src/core/attention-fallbacks.ts"],"names":[],"mappings":"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"}

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,124 @@
+/**
+ * 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.
+ *
+ * @ruvector/gnn requires regular JavaScript arrays, NOT Float32Array.
+ * This wrapper handles the conversion automatically.
+ */
+/**
+ * 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
+ * const result1 = differentiableSearch([1, 0, 0], [[1, 0, 0], [0, 1, 0]], 2, 1.0);
+ *
+ * // Also works with Float32Array
+ * 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
+     */
+    forward(nodeEmbedding: number[] | Float32Array, neighborEmbeddings: (number[] | Float32Array)[], edgeWeights: number[] | Float32Array): number[];
+    /**
+     * 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
+ */
+export declare function hierarchicalForward(query: number[] | Float32Array, layerEmbeddings: (number[] | Float32Array)[][], gnnLayersJson: string[]): number[];
+/**
+ * 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;
+};
+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;;;;;;;;GAQG;AAuCH;;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,MAAM,EAAE;IAQX;;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,MAAM,EAAE,CAOV;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAOxC;;;;;;;;;AAED,wBAOE"}

package/dist/core/gnn-wrapper.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * 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.
+ *
+ * @ruvector/gnn requires regular JavaScript arrays, NOT Float32Array.
+ * This wrapper handles the conversion automatically.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TensorCompress = exports.RuvectorLayer = void 0;
+exports.differentiableSearch = differentiableSearch;
+exports.hierarchicalForward = hierarchicalForward;
+exports.getCompressionLevel = getCompressionLevel;
+exports.isGnnAvailable = isGnnAvailable;
+// Lazy load to avoid import errors if not installed
+let gnnModule = null;
+let loadError = null;
+function getGnnModule() {
+    if (gnnModule)
+        return gnnModule;
+    if (loadError)
+        throw loadError;
+    try {
+        gnnModule = require('@ruvector/gnn');
+        return gnnModule;
+    }
+    catch (e) {
+        loadError = new Error(`@ruvector/gnn is not installed or failed to load: ${e.message}\n` +
+            `Install with: npm install @ruvector/gnn`);
+        throw loadError;
+    }
+}
+/**
+ * Convert any array-like input to a regular JavaScript array
+ */
+function toArray(input) {
+    if (Array.isArray(input)) {
+        return input;
+    }
+    return Array.from(input);
+}
+/**
+ * Convert nested arrays/typed arrays to regular JavaScript arrays
+ */
+function toNestedArray(input) {
+    return input.map(arr => toArray(arr));
+}
+/**
+ * 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
+ * const result1 = differentiableSearch([1, 0, 0], [[1, 0, 0], [0, 1, 0]], 2, 1.0);
+ *
+ * // Also works with Float32Array
+ * 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);
+ * ```
+ */
+function differentiableSearch(query, candidates, k, temperature = 1.0) {
+    const gnn = getGnnModule();
+    // Convert to regular arrays (required by @ruvector/gnn)
+    const queryArray = toArray(query);
+    const candidatesArray = toNestedArray(candidates);
+    return gnn.differentiableSearch(queryArray, candidatesArray, k, temperature);
+}
+/**
+ * GNN Layer for HNSW topology
+ */
+class RuvectorLayer {
+    /**
+     * 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, hiddenDim, heads, dropout = 0.1) {
+        const gnn = getGnnModule();
+        this.inner = new gnn.RuvectorLayer(inputDim, hiddenDim, heads, dropout);
+    }
+    /**
+     * 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
+     */
+    forward(nodeEmbedding, neighborEmbeddings, edgeWeights) {
+        return this.inner.forward(toArray(nodeEmbedding), toNestedArray(neighborEmbeddings), toArray(edgeWeights));
+    }
+    /**
+     * Serialize the layer to JSON
+     */
+    toJson() {
+        return this.inner.toJson();
+    }
+    /**
+     * Deserialize the layer from JSON
+     */
+    static fromJson(json) {
+        const gnn = getGnnModule();
+        const layer = new RuvectorLayer(1, 1, 1, 0); // Dummy constructor
+        layer.inner = gnn.RuvectorLayer.fromJson(json);
+        return layer;
+    }
+}
+exports.RuvectorLayer = RuvectorLayer;
+/**
+ * Tensor compressor with adaptive level selection
+ */
+class TensorCompress {
+    constructor() {
+        const gnn = getGnnModule();
+        this.inner = new gnn.TensorCompress();
+    }
+    /**
+     * 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, accessFreq) {
+        return this.inner.compress(toArray(embedding), accessFreq);
+    }
+    /**
+     * Decompress a compressed tensor
+     *
+     * @param compressedJson - Compressed tensor JSON
+     * @returns Decompressed embedding
+     */
+    decompress(compressedJson) {
+        return this.inner.decompress(compressedJson);
+    }
+}
+exports.TensorCompress = TensorCompress;
+/**
+ * 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
+ */
+function hierarchicalForward(query, layerEmbeddings, gnnLayersJson) {
+    const gnn = getGnnModule();
+    return gnn.hierarchicalForward(toArray(query), layerEmbeddings.map(layer => toNestedArray(layer)), gnnLayersJson);
+}
+/**
+ * Get compression level for a given access frequency
+ */
+function getCompressionLevel(accessFreq) {
+    const gnn = getGnnModule();
+    return gnn.getCompressionLevel(accessFreq);
+}
+/**
+ * Check if GNN module is available
+ */
+function isGnnAvailable() {
+    try {
+        getGnnModule();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+exports.default = {
+    differentiableSearch,
+    RuvectorLayer,
+    TensorCompress,
+    hierarchicalForward,
+    getCompressionLevel,
+    isGnnAvailable,
+};