ruvector 0.1.38 → 0.1.39

package/dist/core/sona-wrapper.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sona = exports.SonaEngine = void 0;
+exports.isSonaAvailable = isSonaAvailable;
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/** Convert any array-like to regular Array (SONA expects number[]) */
+function toArray(input) {
+    if (Array.isArray(input))
+        return input;
+    return Array.from(input);
+}
+// ============================================================================
+// Lazy Loading
+// ============================================================================
+let sonaModule = null;
+let sonaLoadError = null;
+function getSonaModule() {
+    if (sonaModule)
+        return sonaModule;
+    if (sonaLoadError)
+        throw sonaLoadError;
+    try {
+        sonaModule = require('@ruvector/sona');
+        return sonaModule;
+    }
+    catch (e) {
+        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 */
+function isSonaAvailable() {
+    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);
+ * ```
+ */
+class SonaEngine {
+    /**
+     * Create a new SONA engine
+     * @param hiddenDim Hidden dimension size (e.g., 256, 512, 768)
+     */
+    constructor(hiddenDim) {
+        const mod = getSonaModule();
+        this._native = new mod.SonaEngine(hiddenDim);
+    }
+    /**
+     * Create engine with custom configuration
+     * @param config SONA configuration options
+     */
+    static withConfig(config) {
+        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) {
+        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, activations, attentionWeights, reward) {
+        this._native.addTrajectoryStep(trajectoryId, toArray(activations), toArray(attentionWeights), reward);
+    }
+    /**
+     * Alias for addStep for API compatibility
+     */
+    addTrajectoryStep(trajectoryId, activations, attentionWeights, reward) {
+        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, route) {
+        this._native.setTrajectoryRoute(trajectoryId, route);
+    }
+    /**
+     * Add context to a trajectory
+     * @param trajectoryId Trajectory ID
+     * @param contextId Context identifier
+     */
+    addContext(trajectoryId, contextId) {
+        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, quality) {
+        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) {
+        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, input) {
+        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() {
+        return this._native.tick();
+    }
+    /**
+     * Force immediate background learning cycle
+     * @returns Status message with learning results
+     */
+    forceLearn() {
+        return this._native.forceLearn();
+    }
+    /**
+     * Flush pending instant loop updates
+     */
+    flush() {
+        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, k) {
+        return this._native.findPatterns(toArray(queryEmbedding), k);
+    }
+    // -------------------------------------------------------------------------
+    // Engine Control
+    // -------------------------------------------------------------------------
+    /**
+     * Get engine statistics
+     * @returns Statistics object
+     */
+    getStats() {
+        const statsJson = this._native.getStats();
+        return JSON.parse(statsJson);
+    }
+    /**
+     * Enable or disable the engine
+     * @param enabled Whether to enable
+     */
+    setEnabled(enabled) {
+        this._native.setEnabled(enabled);
+    }
+    /**
+     * Check if engine is enabled
+     */
+    isEnabled() {
+        return this._native.isEnabled();
+    }
+}
+exports.SonaEngine = SonaEngine;
+// ============================================================================
+// Convenience Exports
+// ============================================================================
+/**
+ * SONA namespace with all exports
+ */
+exports.Sona = {
+    Engine: SonaEngine,
+    isAvailable: isSonaAvailable,
+};
+exports.default = exports.Sona;

package/dist/index.d.ts

@@ -1,95 +1,100 @@
 /**
- * Vector database types compatible with both NAPI and WASM backends
+ * 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.
  */
-
-interface Vector {
-  id: string;
-  values: number[];
-  metadata?: Record<string, any>;
-}
-
-interface SearchResult {
-  id: string;
-  score: number;
-  metadata?: Record<string, any>;
-}
-
-interface IndexStats {
-  vectorCount: number;
-  dimension: number;
-  indexType: string;
-  memoryUsage?: number;
-}
-
-interface CreateIndexOptions {
-  dimension: number;
-  metric?: 'cosine' | 'euclidean' | 'dot';
-  indexType?: 'flat' | 'hnsw';
-  hnswConfig?: {
-    m?: number;
-    efConstruction?: number;
-  };
-}
-
-interface SearchOptions {
-  k?: number;
-  ef?: number;
-  filter?: Record<string, any>;
-}
-
-interface BatchInsertOptions {
-  batchSize?: number;
-  progressCallback?: (progress: number) => void;
-}
-
+export * from './types';
+export * from './core';
+export * from './services';
+declare let implementation: any;
 /**
- * Backend information
+ * Get the current implementation type
  */
-interface BackendInfo {
-  type: 'native' | 'wasm';
-  version: string;
-  features: string[];
-}
-
+export declare function getImplementationType(): 'native' | 'wasm';
 /**
- * rUvector - High-performance vector database
- *
- * Smart loader that tries native bindings first, falls back to WASM
+ * Check if native implementation is being used
  */
-
+export declare function isNative(): boolean;
 /**
- * VectorIndex class that wraps the backend
+ * Check if WASM implementation is being used
  */
-declare class VectorIndex {
-    private index;
-    constructor(options: CreateIndexOptions);
-    insert(vector: Vector): Promise<void>;
-    insertBatch(vectors: Vector[], options?: BatchInsertOptions): Promise<void>;
-    search(query: number[], options?: SearchOptions): Promise<SearchResult[]>;
-    get(id: string): Promise<Vector | null>;
-    delete(id: string): Promise<boolean>;
-    stats(): Promise<IndexStats>;
-    save(path: string): Promise<void>;
-    static load(path: string): Promise<VectorIndex>;
-    clear(): Promise<void>;
-    optimize(): Promise<void>;
-}
+export declare function isWasm(): boolean;
 /**
- * Utility functions
+ * Get version information
  */
-declare const Utils: {
-    cosineSimilarity(a: number[], b: number[]): number;
-    euclideanDistance(a: number[], b: number[]): number;
-    normalize(vector: number[]): number[];
-    randomVector(dimension: number): number[];
+export declare function getVersion(): {
+    version: string;
+    implementation: string;
 };
 /**
- * Get backend information
+ * Wrapper class that automatically handles metadata JSON conversion
  */
-declare function getBackendInfo(): BackendInfo;
-/**
- * Check if native bindings are available
- */
-declare function isNativeAvailable(): boolean;
-
-export { type BackendInfo, type BatchInsertOptions, type CreateIndexOptions, type IndexStats, type SearchOptions, type SearchResult, Utils, type Vector, VectorIndex, VectorIndex as default, getBackendInfo, isNativeAvailable };
+declare class VectorDBWrapper {
+    private db;
+    constructor(options: {
+        dimensions: number;
+        storagePath?: string;
+        distanceMetric?: string;
+        hnswConfig?: any;
+    });
+    /**
+     * Insert a vector with optional metadata (objects are auto-converted to JSON)
+     */
+    insert(entry: {
+        id?: string;
+        vector: Float32Array | number[];
+        metadata?: Record<string, any>;
+    }): Promise<string>;
+    /**
+     * Insert multiple vectors in batch
+     */
+    insertBatch(entries: Array<{
+        id?: string;
+        vector: Float32Array | number[];
+        metadata?: Record<string, any>;
+    }>): Promise<string[]>;
+    /**
+     * Search for similar vectors (metadata is auto-parsed from JSON)
+     */
+    search(query: {
+        vector: Float32Array | number[];
+        k: number;
+        filter?: Record<string, any>;
+        efSearch?: number;
+    }): Promise<Array<{
+        id: string;
+        score: number;
+        vector?: Float32Array;
+        metadata?: Record<string, any>;
+    }>>;
+    /**
+     * Get a vector by ID (metadata is auto-parsed from JSON)
+     */
+    get(id: string): Promise<{
+        id?: string;
+        vector: Float32Array;
+        metadata?: Record<string, any>;
+    } | null>;
+    /**
+     * Delete a vector by ID
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Get the number of vectors in the database
+     */
+    len(): Promise<number>;
+    /**
+     * Check if the database is empty
+     */
+    isEmpty(): Promise<boolean>;
+}
+export declare const VectorDb: typeof VectorDBWrapper;
+export declare const VectorDB: typeof VectorDBWrapper;
+export declare const NativeVectorDb: any;
+export default implementation;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,SAAS,CAAC;AAGxB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAE3B,QAAA,IAAI,cAAc,EAAE,GAAG,CAAC;AA0BxB;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;GAEG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAMxE;AAED;;GAEG;AACH,cAAM,eAAe;IACnB,OAAO,CAAC,EAAE,CAAM;gBAEJ,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,GAAG,CAAA;KAAE;IAI5G;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IActH;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUtI;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,CAAC,CAAC;IAuB1N;;OAEG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAW5G;;OAEG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;CAGlC;AAGD,eAAO,MAAM,QAAQ,wBAAkB,CAAC;AACxC,eAAO,MAAM,QAAQ,wBAAkB,CAAC;AAGxC,eAAO,MAAM,cAAc,KAA0B,CAAC;AAGtD,eAAe,cAAc,CAAC"}