ruvector 0.2.23 → 0.2.25

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"}

package/dist/core/gnn-wrapper.js

@@ -0,0 +1,213 @@
+"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.
+ *
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TensorCompress = exports.RuvectorLayer = void 0;
+exports.toFloat32Array = toFloat32Array;
+exports.toFloat32ArrayBatch = toFloat32ArrayBatch;
+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 Float32Array (native requires Float32Array)
+ * Optimized paths:
+ * - Float32Array: zero-copy return
+ * - Float64Array: efficient typed array copy
+ * - Array: direct Float32Array construction
+ */
+function toFloat32Array(input) {
+    if (input instanceof Float32Array)
+        return input;
+    if (input instanceof Float64Array)
+        return new Float32Array(input);
+    if (Array.isArray(input))
+        return new Float32Array(input);
+    return new Float32Array(Array.from(input));
+}
+/**
+ * Convert array of arrays to array of Float32Arrays
+ */
+function toFloat32ArrayBatch(input) {
+    const result = new Array(input.length);
+    for (let i = 0; i < input.length; i++) {
+        result[i] = toFloat32Array(input[i]);
+    }
+    return result;
+}
+/**
+ * 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);
+ * ```
+ */
+function differentiableSearch(query, candidates, k, temperature = 1.0) {
+    const gnn = getGnnModule();
+    // Convert to Float32Array (native Rust expects Float32Array for performance)
+    const queryFloat32 = toFloat32Array(query);
+    const candidatesFloat32 = toFloat32ArrayBatch(candidates);
+    return gnn.differentiableSearch(queryFloat32, candidatesFloat32, 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 as Float32Array
+     */
+    forward(nodeEmbedding, neighborEmbeddings, edgeWeights) {
+        return this.inner.forward(toFloat32Array(nodeEmbedding), toFloat32ArrayBatch(neighborEmbeddings), toFloat32Array(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(toFloat32Array(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 as Float32Array
+ */
+function hierarchicalForward(query, layerEmbeddings, gnnLayersJson) {
+    const gnn = getGnnModule();
+    return gnn.hierarchicalForward(toFloat32Array(query), layerEmbeddings.map(layer => toFloat32ArrayBatch(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,
+    // Export conversion helpers for performance optimization
+    toFloat32Array,
+    toFloat32ArrayBatch,
+};

package/dist/core/graph-algorithms.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Graph Algorithms - MinCut, Spectral Clustering, Community Detection
+ *
+ * Provides graph partitioning and clustering algorithms for:
+ * - Code module detection
+ * - Dependency clustering
+ * - Architecture analysis
+ * - Refactoring suggestions
+ */
+export interface Graph {
+    nodes: string[];
+    edges: Array<{
+        from: string;
+        to: string;
+        weight?: number;
+    }>;
+    adjacency: Map<string, Map<string, number>>;
+}
+export interface Partition {
+    groups: string[][];
+    cutWeight: number;
+    modularity: number;
+}
+export interface SpectralResult {
+    clusters: Map<string, number>;
+    eigenvalues: number[];
+    coordinates: Map<string, number[]>;
+}
+/**
+ * Build adjacency representation from edges
+ */
+export declare function buildGraph(nodes: string[], edges: Array<{
+    from: string;
+    to: string;
+    weight?: number;
+}>): Graph;
+/**
+ * Minimum Cut (Stoer-Wagner algorithm)
+ *
+ * Finds the minimum weight cut that partitions the graph into two parts.
+ * Useful for finding loosely coupled module boundaries.
+ */
+export declare function minCut(graph: Graph): Partition;
+/**
+ * Spectral Clustering (using power iteration)
+ *
+ * Uses graph Laplacian eigenvectors for clustering.
+ * Good for finding natural clusters in code dependencies.
+ */
+export declare function spectralClustering(graph: Graph, k?: number): SpectralResult;
+/**
+ * Louvain Community Detection
+ *
+ * Greedy modularity optimization for finding communities.
+ * Good for detecting natural module boundaries.
+ */
+export declare function louvainCommunities(graph: Graph): Map<string, number>;
+/**
+ * Calculate modularity of a partition
+ */
+export declare function calculateModularity(graph: Graph, partition: string[][]): number;
+/**
+ * Find bridges (edges whose removal disconnects components)
+ */
+export declare function findBridges(graph: Graph): Array<{
+    from: string;
+    to: string;
+}>;
+/**
+ * Find articulation points (nodes whose removal disconnects components)
+ */
+export declare function findArticulationPoints(graph: Graph): string[];
+declare const _default: {
+    buildGraph: typeof buildGraph;
+    minCut: typeof minCut;
+    spectralClustering: typeof spectralClustering;
+    louvainCommunities: typeof louvainCommunities;
+    calculateModularity: typeof calculateModularity;
+    findBridges: typeof findBridges;
+    findArticulationPoints: typeof findArticulationPoints;
+};
+export default _default;
+//# sourceMappingURL=graph-algorithms.d.ts.map

package/dist/core/graph-algorithms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-algorithms.d.ts","sourceRoot":"","sources":["../../src/core/graph-algorithms.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAC1D,KAAK,CAiBP;AAED;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAwG9C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,GAAE,MAAU,GAAG,cAAc,CA0G9E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAiGpE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAgC/E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAsC7E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CA+C7D;;;;;;;;;;AA+FD,wBAQE"}