ruvector 0.1.30 → 0.1.31

package/src/core/gnn-wrapper.ts

@@ -0,0 +1,251 @@
+/**
+ * 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
+ */
+
+// Lazy load to avoid import errors if not installed
+let gnnModule: any = null;
+let loadError: Error | null = null;
+
+function getGnnModule() {
+  if (gnnModule) return gnnModule;
+  if (loadError) throw loadError;
+
+  try {
+    gnnModule = require('@ruvector/gnn');
+    return gnnModule;
+  } catch (e: any) {
+    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
+ */
+export function toFloat32Array(input: number[] | Float32Array | Float64Array): Float32Array {
+  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
+ */
+export function toFloat32ArrayBatch(input: (number[] | Float32Array | Float64Array)[]): Float32Array[] {
+  const result = new Array(input.length);
+  for (let i = 0; i < input.length; i++) {
+    result[i] = toFloat32Array(input[i]);
+  }
+  return result;
+}
+
+/**
+ * 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 function differentiableSearch(
+  query: number[] | Float32Array | Float64Array,
+  candidates: (number[] | Float32Array | Float64Array)[],
+  k: number,
+  temperature: number = 1.0
+): DifferentiableSearchResult {
+  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
+ */
+export class RuvectorLayer {
+  private inner: any;
+
+  /**
+   * 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 = 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: number[] | Float32Array,
+    neighborEmbeddings: (number[] | Float32Array)[],
+    edgeWeights: number[] | Float32Array
+  ): Float32Array {
+    return this.inner.forward(
+      toFloat32Array(nodeEmbedding),
+      toFloat32ArrayBatch(neighborEmbeddings),
+      toFloat32Array(edgeWeights)
+    );
+  }
+
+  /**
+   * Serialize the layer to JSON
+   */
+  toJson(): string {
+    return this.inner.toJson();
+  }
+
+  /**
+   * Deserialize the layer from JSON
+   */
+  static fromJson(json: string): RuvectorLayer {
+    const gnn = getGnnModule();
+    const layer = new RuvectorLayer(1, 1, 1, 0); // Dummy constructor
+    layer.inner = gnn.RuvectorLayer.fromJson(json);
+    return layer;
+  }
+}
+
+/**
+ * Tensor compressor with adaptive level selection
+ */
+export class TensorCompress {
+  private inner: any;
+
+  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: number[] | Float32Array, accessFreq: number): string {
+    return this.inner.compress(toFloat32Array(embedding), accessFreq);
+  }
+
+  /**
+   * Decompress a compressed tensor
+   *
+   * @param compressedJson - Compressed tensor JSON
+   * @returns Decompressed embedding
+   */
+  decompress(compressedJson: string): number[] {
+    return this.inner.decompress(compressedJson);
+  }
+}
+
+/**
+ * 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 function hierarchicalForward(
+  query: number[] | Float32Array,
+  layerEmbeddings: (number[] | Float32Array)[][],
+  gnnLayersJson: string[]
+): Float32Array {
+  const gnn = getGnnModule();
+  return gnn.hierarchicalForward(
+    toFloat32Array(query),
+    layerEmbeddings.map(layer => toFloat32ArrayBatch(layer)),
+    gnnLayersJson
+  );
+}
+
+/**
+ * Get compression level for a given access frequency
+ */
+export function getCompressionLevel(accessFreq: number): string {
+  const gnn = getGnnModule();
+  return gnn.getCompressionLevel(accessFreq);
+}
+
+/**
+ * Check if GNN module is available
+ */
+export function isGnnAvailable(): boolean {
+  try {
+    getGnnModule();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export default {
+  differentiableSearch,
+  RuvectorLayer,
+  TensorCompress,
+  hierarchicalForward,
+  getCompressionLevel,
+  isGnnAvailable,
+  // Export conversion helpers for performance optimization
+  toFloat32Array,
+  toFloat32ArrayBatch,
+};

package/src/core/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Core module exports
+ *
+ * These wrappers provide safe, type-flexible interfaces to the underlying
+ * native packages, handling array type conversions automatically.
+ */
+
+export * from './gnn-wrapper';
+export * from './attention-fallbacks';
+export * from './agentdb-fast';
+export * from './sona-wrapper';
+
+// Re-export default objects for convenience
+export { default as gnnWrapper } from './gnn-wrapper';
+export { default as attentionFallbacks } from './attention-fallbacks';
+export { default as agentdbFast } from './agentdb-fast';
+export { default as Sona } from './sona-wrapper';

package/src/core/sona-wrapper.ts

@@ -0,0 +1,367 @@
+/**
+ * SONA Wrapper - Self-Optimizing Neural Architecture
+ *
+ * Provides a safe, flexible interface to @ruvector/sona with:
+ * - Automatic array type conversion (Array <-> Float64Array)
+ * - Graceful handling when sona is not installed
+ * - TypeScript types for all APIs
+ *
+ * SONA Features:
+ * - Micro-LoRA: Ultra-fast rank-1/2 adaptations (~0.1ms)
+ * - Base-LoRA: Deeper adaptations for complex patterns
+ * - EWC++: Elastic Weight Consolidation to prevent catastrophic forgetting
+ * - ReasoningBank: Pattern storage and retrieval
+ * - Trajectory tracking: Record and learn from execution paths
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Array input type - accepts both regular arrays and typed arrays */
+export type ArrayInput = number[] | Float32Array | Float64Array;
+
+/** SONA configuration options */
+export interface SonaConfig {
+  /** Hidden dimension size (required) */
+  hiddenDim: number;
+  /** Embedding dimension (defaults to hiddenDim) */
+  embeddingDim?: number;
+  /** Micro-LoRA rank (1-2, default: 1) */
+  microLoraRank?: number;
+  /** Base LoRA rank (default: 8) */
+  baseLoraRank?: number;
+  /** Micro-LoRA learning rate (default: 0.001) */
+  microLoraLr?: number;
+  /** Base LoRA learning rate (default: 0.0001) */
+  baseLoraLr?: number;
+  /** EWC lambda regularization (default: 1000.0) */
+  ewcLambda?: number;
+  /** Number of pattern clusters (default: 50) */
+  patternClusters?: number;
+  /** Trajectory buffer capacity (default: 10000) */
+  trajectoryCapacity?: number;
+  /** Background learning interval in ms (default: 3600000 = 1 hour) */
+  backgroundIntervalMs?: number;
+  /** Quality threshold for learning (default: 0.5) */
+  qualityThreshold?: number;
+  /** Enable SIMD optimizations (default: true) */
+  enableSimd?: boolean;
+}
+
+/** Learned pattern from ReasoningBank */
+export interface LearnedPattern {
+  /** Pattern identifier */
+  id: string;
+  /** Cluster centroid embedding */
+  centroid: number[];
+  /** Number of trajectories in cluster */
+  clusterSize: number;
+  /** Total weight of trajectories */
+  totalWeight: number;
+  /** Average quality of member trajectories */
+  avgQuality: number;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last access timestamp */
+  lastAccessed: string;
+  /** Total access count */
+  accessCount: number;
+  /** Pattern type */
+  patternType: string;
+}
+
+/** SONA engine statistics */
+export interface SonaStats {
+  trajectoriesRecorded: number;
+  patternsLearned: number;
+  microLoraUpdates: number;
+  baseLoraUpdates: number;
+  ewcConsolidations: number;
+  avgLearningTimeMs: number;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/** Convert any array-like to regular Array (SONA expects number[]) */
+function toArray(input: ArrayInput): number[] {
+  if (Array.isArray(input)) return input;
+  return Array.from(input);
+}
+
+// ============================================================================
+// Lazy Loading
+// ============================================================================
+
+let sonaModule: any = null;
+let sonaLoadError: Error | null = null;
+
+function getSonaModule(): any {
+  if (sonaModule) return sonaModule;
+  if (sonaLoadError) throw sonaLoadError;
+
+  try {
+    sonaModule = require('@ruvector/sona');
+    return sonaModule;
+  } catch (e: any) {
+    sonaLoadError = new Error(
+      `@ruvector/sona is not installed. Install it with:\n` +
+        `  npm install @ruvector/sona\n\n` +
+        `Original error: ${e.message}`
+    );
+    throw sonaLoadError;
+  }
+}
+
+/** Check if sona is available */
+export function isSonaAvailable(): boolean {
+  try {
+    getSonaModule();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// SONA Engine Wrapper
+// ============================================================================
+
+/**
+ * SONA Engine - Self-Optimizing Neural Architecture
+ *
+ * Provides runtime-adaptive learning with:
+ * - Micro-LoRA for instant adaptations
+ * - Base-LoRA for deeper learning
+ * - EWC++ for preventing forgetting
+ * - ReasoningBank for pattern storage
+ *
+ * @example
+ * ```typescript
+ * import { Sona } from 'ruvector';
+ *
+ * // Create engine with hidden dimension
+ * const engine = new Sona.Engine(256);
+ *
+ * // Or with custom config
+ * const engine = Sona.Engine.withConfig({
+ *   hiddenDim: 256,
+ *   microLoraRank: 2,
+ *   patternClusters: 100
+ * });
+ *
+ * // Record a trajectory
+ * const trajId = engine.beginTrajectory([0.1, 0.2, ...]);
+ * engine.addStep(trajId, activations, attentionWeights, 0.8);
+ * engine.endTrajectory(trajId, 0.9);
+ *
+ * // Apply learned adaptations
+ * const adapted = engine.applyMicroLora(input);
+ * ```
+ */
+export class SonaEngine {
+  private _native: any;
+
+  /**
+   * Create a new SONA engine
+   * @param hiddenDim Hidden dimension size (e.g., 256, 512, 768)
+   */
+  constructor(hiddenDim: number) {
+    const mod = getSonaModule();
+    this._native = new mod.SonaEngine(hiddenDim);
+  }
+
+  /**
+   * Create engine with custom configuration
+   * @param config SONA configuration options
+   */
+  static withConfig(config: SonaConfig): SonaEngine {
+    const mod = getSonaModule();
+    const engine = new SonaEngine(config.hiddenDim);
+    // Replace native with configured version
+    engine._native = mod.SonaEngine.withConfig(config);
+    return engine;
+  }
+
+  // -------------------------------------------------------------------------
+  // Trajectory Recording
+  // -------------------------------------------------------------------------
+
+  /**
+   * Begin recording a new trajectory
+   * @param queryEmbedding Initial query embedding
+   * @returns Trajectory ID for subsequent operations
+   */
+  beginTrajectory(queryEmbedding: ArrayInput): number {
+    return this._native.beginTrajectory(toArray(queryEmbedding));
+  }
+
+  /**
+   * Add a step to an active trajectory
+   * @param trajectoryId Trajectory ID from beginTrajectory
+   * @param activations Layer activations
+   * @param attentionWeights Attention weights
+   * @param reward Reward signal for this step (0.0 - 1.0)
+   */
+  addStep(
+    trajectoryId: number,
+    activations: ArrayInput,
+    attentionWeights: ArrayInput,
+    reward: number
+  ): void {
+    this._native.addTrajectoryStep(
+      trajectoryId,
+      toArray(activations),
+      toArray(attentionWeights),
+      reward
+    );
+  }
+
+  /**
+   * Alias for addStep for API compatibility
+   */
+  addTrajectoryStep(
+    trajectoryId: number,
+    activations: ArrayInput,
+    attentionWeights: ArrayInput,
+    reward: number
+  ): void {
+    this.addStep(trajectoryId, activations, attentionWeights, reward);
+  }
+
+  /**
+   * Set the model route for a trajectory
+   * @param trajectoryId Trajectory ID
+   * @param route Model route identifier (e.g., "gpt-4", "claude-3")
+   */
+  setRoute(trajectoryId: number, route: string): void {
+    this._native.setTrajectoryRoute(trajectoryId, route);
+  }
+
+  /**
+   * Add context to a trajectory
+   * @param trajectoryId Trajectory ID
+   * @param contextId Context identifier
+   */
+  addContext(trajectoryId: number, contextId: string): void {
+    this._native.addTrajectoryContext(trajectoryId, contextId);
+  }
+
+  /**
+   * Complete a trajectory and submit for learning
+   * @param trajectoryId Trajectory ID
+   * @param quality Final quality score (0.0 - 1.0)
+   */
+  endTrajectory(trajectoryId: number, quality: number): void {
+    this._native.endTrajectory(trajectoryId, quality);
+  }
+
+  // -------------------------------------------------------------------------
+  // LoRA Transformations
+  // -------------------------------------------------------------------------
+
+  /**
+   * Apply micro-LoRA transformation (ultra-fast, ~0.1ms)
+   * @param input Input vector
+   * @returns Transformed output vector
+   */
+  applyMicroLora(input: ArrayInput): number[] {
+    return this._native.applyMicroLora(toArray(input));
+  }
+
+  /**
+   * Apply base-LoRA transformation to a specific layer
+   * @param layerIdx Layer index
+   * @param input Input vector
+   * @returns Transformed output vector
+   */
+  applyBaseLora(layerIdx: number, input: ArrayInput): number[] {
+    return this._native.applyBaseLora(layerIdx, toArray(input));
+  }
+
+  // -------------------------------------------------------------------------
+  // Learning Control
+  // -------------------------------------------------------------------------
+
+  /**
+   * Run background learning cycle if due
+   * Call this periodically (e.g., every few seconds)
+   * @returns Status message if learning occurred, null otherwise
+   */
+  tick(): string | null {
+    return this._native.tick();
+  }
+
+  /**
+   * Force immediate background learning cycle
+   * @returns Status message with learning results
+   */
+  forceLearn(): string {
+    return this._native.forceLearn();
+  }
+
+  /**
+   * Flush pending instant loop updates
+   */
+  flush(): void {
+    this._native.flush();
+  }
+
+  // -------------------------------------------------------------------------
+  // Pattern Retrieval
+  // -------------------------------------------------------------------------
+
+  /**
+   * Find similar learned patterns to a query
+   * @param queryEmbedding Query embedding
+   * @param k Number of patterns to return
+   * @returns Array of similar patterns
+   */
+  findPatterns(queryEmbedding: ArrayInput, k: number): LearnedPattern[] {
+    return this._native.findPatterns(toArray(queryEmbedding), k);
+  }
+
+  // -------------------------------------------------------------------------
+  // Engine Control
+  // -------------------------------------------------------------------------
+
+  /**
+   * Get engine statistics
+   * @returns Statistics object
+   */
+  getStats(): SonaStats {
+    const statsJson = this._native.getStats();
+    return JSON.parse(statsJson);
+  }
+
+  /**
+   * Enable or disable the engine
+   * @param enabled Whether to enable
+   */
+  setEnabled(enabled: boolean): void {
+    this._native.setEnabled(enabled);
+  }
+
+  /**
+   * Check if engine is enabled
+   */
+  isEnabled(): boolean {
+    return this._native.isEnabled();
+  }
+}
+
+// ============================================================================
+// Convenience Exports
+// ============================================================================
+
+/**
+ * SONA namespace with all exports
+ */
+export const Sona = {
+  Engine: SonaEngine,
+  isAvailable: isSonaAvailable,
+};
+
+export default Sona;

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * ruvector - High-performance vector database for Node.js
+ *
+ * This package automatically detects and uses the best available implementation:
+ * 1. Native (Rust-based, fastest) - if available for your platform
+ * 2. WASM (WebAssembly, universal fallback) - works everywhere
+ *
+ * Also provides safe wrappers for GNN and Attention modules that handle
+ * array type conversions automatically.
+ */
+
+export * from './types';
+
+// Export core wrappers (safe interfaces with automatic type conversion)
+export * from './core';
+export * from './services';
+
+let implementation: any;
+let implementationType: 'native' | 'wasm' = 'wasm';
+
+try {
+  // Try to load native module first
+  implementation = require('@ruvector/core');
+  implementationType = 'native';
+
+  // Verify it's actually working
+  if (typeof implementation.VectorDB !== 'function') {
+    throw new Error('Native module loaded but VectorDB not found');
+  }
+} catch (e: any) {
+  // No WASM fallback available yet
+  throw new Error(
+    `Failed to load ruvector native module.\n` +
+    `Error: ${e.message}\n` +
+    `\nSupported platforms:\n` +
+    `- Linux x64/ARM64\n` +
+    `- macOS Intel/Apple Silicon\n` +
+    `- Windows x64\n` +
+    `\nIf you're on a supported platform, try:\n` +
+    `  npm install --force @ruvector/core`
+  );
+}
+
+/**
+ * Get the current implementation type
+ */
+export function getImplementationType(): 'native' | 'wasm' {
+  return implementationType;
+}
+
+/**
+ * Check if native implementation is being used
+ */
+export function isNative(): boolean {
+  return implementationType === 'native';
+}
+
+/**
+ * Check if WASM implementation is being used
+ */
+export function isWasm(): boolean {
+  return implementationType === 'wasm';
+}
+
+/**
+ * Get version information
+ */
+export function getVersion(): { version: string; implementation: string } {
+  const pkg = require('../package.json');
+  return {
+    version: pkg.version,
+    implementation: implementationType
+  };
+}
+
+// Export the VectorDB class
+export const VectorDB = implementation.VectorDB;
+
+// Export everything from the implementation
+export default implementation;