agentic-flow 2.0.6 → 3.0.0-alpha.1

package/dist/packages/agentdb/src/backends/LearningBackend.d.ts

@@ -0,0 +1,148 @@
+/**
+ * LearningBackend Interface - GNN self-learning capabilities (Optional)
+ *
+ * Provides Graph Neural Network (GNN) based learning for query enhancement
+ * and adaptive pattern recognition. Available when @ruvector/gnn is installed.
+ *
+ * Features:
+ * - Query enhancement using attention mechanisms
+ * - Automatic learning from search patterns
+ * - Model persistence and versioning
+ */
+/**
+ * Learning backend configuration
+ */
+export interface LearningConfig {
+    /** Enable learning features */
+    enabled: boolean;
+    /** Input dimension (must match vector dimension) */
+    inputDim: number;
+    /** Output dimension (defaults to inputDim) */
+    outputDim?: number;
+    /** Number of attention heads for GNN */
+    heads?: number;
+    /** Learning rate for training */
+    learningRate?: number;
+    /** Batch size for training */
+    batchSize?: number;
+    /** Path for model persistence */
+    modelPath?: string;
+    /** Auto-train interval in seconds (0 = disabled) */
+    autoTrainInterval?: number;
+}
+/**
+ * Training sample for supervised learning
+ */
+export interface TrainingSample {
+    /** Input embedding */
+    embedding: Float32Array;
+    /** Label or class (for classification) */
+    label: number;
+    /** Sample weight (importance) */
+    weight?: number;
+    /** Additional context for learning */
+    context?: Record<string, any>;
+}
+/**
+ * Training result metrics
+ */
+export interface TrainingResult {
+    /** Number of training epochs completed */
+    epochs: number;
+    /** Final loss value */
+    finalLoss: number;
+    /** Improvement percentage from initial loss */
+    improvement: number;
+    /** Training duration in milliseconds */
+    duration: number;
+    /** Additional metrics */
+    metrics?: Record<string, number>;
+}
+/**
+ * Learning backend statistics
+ */
+export interface LearningStats {
+    /** Whether learning is enabled */
+    enabled: boolean;
+    /** Number of samples collected */
+    samplesCollected: number;
+    /** Timestamp of last training (null if never trained) */
+    lastTrainingTime: number | null;
+    /** Current model version */
+    modelVersion: number;
+    /** Average training loss */
+    avgLoss?: number;
+    /** Model accuracy (if applicable) */
+    accuracy?: number;
+}
+/**
+ * LearningBackend - Optional GNN-based learning interface
+ *
+ * Implementations:
+ * - RuVectorLearning: Native Rust GNN with @ruvector/gnn
+ * - MockLearningBackend: No-op implementation for testing
+ */
+export interface LearningBackend {
+    /**
+     * Enhance query vector using GNN attention mechanism
+     *
+     * Takes a query vector and its k-nearest neighbors, applies graph attention,
+     * and returns an enhanced query vector with better semantic representation.
+     *
+     * @param query - Query vector to enhance
+     * @param neighbors - Neighbor vectors for context
+     * @param weights - Importance weights for each neighbor (0-1)
+     * @returns Enhanced query vector
+     */
+    enhance(query: Float32Array, neighbors: Float32Array[], weights: number[]): Float32Array;
+    /**
+     * Add a training sample for future learning
+     *
+     * Samples are accumulated and used during the next training cycle.
+     *
+     * @param sample - Training sample with embedding and label
+     */
+    addSample(sample: TrainingSample): void;
+    /**
+     * Train the model on accumulated samples
+     *
+     * @param options - Training options (epochs, etc.)
+     * @returns Training result with metrics
+     */
+    train(options?: {
+        epochs?: number;
+    }): Promise<TrainingResult>;
+    /**
+     * Clear accumulated training samples
+     */
+    clearSamples(): void;
+    /**
+     * Save trained model to disk
+     *
+     * @param path - File path to save the model
+     * @returns Promise that resolves when model is saved
+     */
+    saveModel(path: string): Promise<void>;
+    /**
+     * Load trained model from disk
+     *
+     * @param path - File path to load the model from
+     * @returns Promise that resolves when model is loaded
+     */
+    loadModel(path: string): Promise<void>;
+    /**
+     * Get learning statistics and metadata
+     *
+     * @returns Current statistics of the learning backend
+     */
+    getStats(): LearningStats;
+    /**
+     * Reset learning state (clear samples, reset model)
+     */
+    reset(): void;
+}
+/**
+ * Type guard to check if an object implements LearningBackend
+ */
+export declare function isLearningBackend(obj: any): obj is LearningBackend;
+//# sourceMappingURL=LearningBackend.d.ts.map

package/dist/packages/agentdb/src/backends/LearningBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningBackend.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/LearningBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,OAAO,EAAE,OAAO,CAAC;IAEjB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IAEjB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,iCAAiC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,sBAAsB;IACtB,SAAS,EAAE,YAAY,CAAC;IAExB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IAEd,iCAAiC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IAEf,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAElB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IAEpB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IAEjB,yBAAyB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;IAEjB,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,yDAAyD;IACzD,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC,4BAA4B;IAC5B,YAAY,EAAE,MAAM,CAAC;IAErB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAK9B;;;;;;;;;;OAUG;IACH,OAAO,CACL,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,YAAY,EAAE,EACzB,OAAO,EAAE,MAAM,EAAE,GAChB,YAAY,CAAC;IAMhB;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAAC;IAExC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE9D;;OAEG;IACH,YAAY,IAAI,IAAI,CAAC;IAMrB;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAMvC;;;;OAIG;IACH,QAAQ,IAAI,aAAa,CAAC;IAE1B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,eAAe,CAalE"}

package/dist/packages/agentdb/src/backends/LearningBackend.js

@@ -0,0 +1,27 @@
+/**
+ * LearningBackend Interface - GNN self-learning capabilities (Optional)
+ *
+ * Provides Graph Neural Network (GNN) based learning for query enhancement
+ * and adaptive pattern recognition. Available when @ruvector/gnn is installed.
+ *
+ * Features:
+ * - Query enhancement using attention mechanisms
+ * - Automatic learning from search patterns
+ * - Model persistence and versioning
+ */
+/**
+ * Type guard to check if an object implements LearningBackend
+ */
+export function isLearningBackend(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        typeof obj.enhance === 'function' &&
+        typeof obj.addSample === 'function' &&
+        typeof obj.train === 'function' &&
+        typeof obj.clearSamples === 'function' &&
+        typeof obj.saveModel === 'function' &&
+        typeof obj.loadModel === 'function' &&
+        typeof obj.getStats === 'function' &&
+        typeof obj.reset === 'function');
+}
+//# sourceMappingURL=LearningBackend.js.map

package/dist/packages/agentdb/src/backends/LearningBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningBackend.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/LearningBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuLH;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;QACnC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU;QAC/B,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU;QACtC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;QACnC,OAAO,GAAG,CAAC,SAAS,KAAK,UAAU;QACnC,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;QAClC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,CAChC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * LearningBackend Interface - GNN self-learning capabilities (Optional)\n *\n * Provides Graph Neural Network (GNN) based learning for query enhancement\n * and adaptive pattern recognition. Available when @ruvector/gnn is installed.\n *\n * Features:\n * - Query enhancement using attention mechanisms\n * - Automatic learning from search patterns\n * - Model persistence and versioning\n */\n\n/**\n * Learning backend configuration\n */\nexport interface LearningConfig {\n  /** Enable learning features */\n  enabled: boolean;\n\n  /** Input dimension (must match vector dimension) */\n  inputDim: number;\n\n  /** Output dimension (defaults to inputDim) */\n  outputDim?: number;\n\n  /** Number of attention heads for GNN */\n  heads?: number;\n\n  /** Learning rate for training */\n  learningRate?: number;\n\n  /** Batch size for training */\n  batchSize?: number;\n\n  /** Path for model persistence */\n  modelPath?: string;\n\n  /** Auto-train interval in seconds (0 = disabled) */\n  autoTrainInterval?: number;\n}\n\n/**\n * Training sample for supervised learning\n */\nexport interface TrainingSample {\n  /** Input embedding */\n  embedding: Float32Array;\n\n  /** Label or class (for classification) */\n  label: number;\n\n  /** Sample weight (importance) */\n  weight?: number;\n\n  /** Additional context for learning */\n  context?: Record<string, any>;\n}\n\n/**\n * Training result metrics\n */\nexport interface TrainingResult {\n  /** Number of training epochs completed */\n  epochs: number;\n\n  /** Final loss value */\n  finalLoss: number;\n\n  /** Improvement percentage from initial loss */\n  improvement: number;\n\n  /** Training duration in milliseconds */\n  duration: number;\n\n  /** Additional metrics */\n  metrics?: Record<string, number>;\n}\n\n/**\n * Learning backend statistics\n */\nexport interface LearningStats {\n  /** Whether learning is enabled */\n  enabled: boolean;\n\n  /** Number of samples collected */\n  samplesCollected: number;\n\n  /** Timestamp of last training (null if never trained) */\n  lastTrainingTime: number | null;\n\n  /** Current model version */\n  modelVersion: number;\n\n  /** Average training loss */\n  avgLoss?: number;\n\n  /** Model accuracy (if applicable) */\n  accuracy?: number;\n}\n\n/**\n * LearningBackend - Optional GNN-based learning interface\n *\n * Implementations:\n * - RuVectorLearning: Native Rust GNN with @ruvector/gnn\n * - MockLearningBackend: No-op implementation for testing\n */\nexport interface LearningBackend {\n  // ============================================================================\n  // GNN Operations\n  // ============================================================================\n\n  /**\n   * Enhance query vector using GNN attention mechanism\n   *\n   * Takes a query vector and its k-nearest neighbors, applies graph attention,\n   * and returns an enhanced query vector with better semantic representation.\n   *\n   * @param query - Query vector to enhance\n   * @param neighbors - Neighbor vectors for context\n   * @param weights - Importance weights for each neighbor (0-1)\n   * @returns Enhanced query vector\n   */\n  enhance(\n    query: Float32Array,\n    neighbors: Float32Array[],\n    weights: number[]\n  ): Float32Array;\n\n  // ============================================================================\n  // Training\n  // ============================================================================\n\n  /**\n   * Add a training sample for future learning\n   *\n   * Samples are accumulated and used during the next training cycle.\n   *\n   * @param sample - Training sample with embedding and label\n   */\n  addSample(sample: TrainingSample): void;\n\n  /**\n   * Train the model on accumulated samples\n   *\n   * @param options - Training options (epochs, etc.)\n   * @returns Training result with metrics\n   */\n  train(options?: { epochs?: number }): Promise<TrainingResult>;\n\n  /**\n   * Clear accumulated training samples\n   */\n  clearSamples(): void;\n\n  // ============================================================================\n  // Persistence\n  // ============================================================================\n\n  /**\n   * Save trained model to disk\n   *\n   * @param path - File path to save the model\n   * @returns Promise that resolves when model is saved\n   */\n  saveModel(path: string): Promise<void>;\n\n  /**\n   * Load trained model from disk\n   *\n   * @param path - File path to load the model from\n   * @returns Promise that resolves when model is loaded\n   */\n  loadModel(path: string): Promise<void>;\n\n  // ============================================================================\n  // Stats\n  // ============================================================================\n\n  /**\n   * Get learning statistics and metadata\n   *\n   * @returns Current statistics of the learning backend\n   */\n  getStats(): LearningStats;\n\n  /**\n   * Reset learning state (clear samples, reset model)\n   */\n  reset(): void;\n}\n\n/**\n * Type guard to check if an object implements LearningBackend\n */\nexport function isLearningBackend(obj: any): obj is LearningBackend {\n  return (\n    typeof obj === 'object' &&\n    obj !== null &&\n    typeof obj.enhance === 'function' &&\n    typeof obj.addSample === 'function' &&\n    typeof obj.train === 'function' &&\n    typeof obj.clearSamples === 'function' &&\n    typeof obj.saveModel === 'function' &&\n    typeof obj.loadModel === 'function' &&\n    typeof obj.getStats === 'function' &&\n    typeof obj.reset === 'function'\n  );\n}\n"]}

package/dist/packages/agentdb/src/backends/VectorBackend.d.ts

@@ -0,0 +1,121 @@
+/**
+ * VectorBackend - Unified interface for vector database backends
+ *
+ * Provides abstraction over different vector search implementations
+ * (RuVector, hnswlib-node) for AgentDB v2.
+ *
+ * Design:
+ * - String-based IDs for all operations (backends handle label mapping internally)
+ * - Consistent SearchResult format across backends
+ * - Save/load with metadata persistence
+ * - Backend-specific optimizations hidden behind interface
+ */
+export interface VectorConfig {
+    /** Vector dimension (e.g., 384, 768, 1536) */
+    dimension?: number;
+    /** Alias for dimension (backward compatibility) */
+    dimensions?: number;
+    /** Distance metric: 'cosine', 'l2' (Euclidean), 'ip' (inner product) */
+    metric: 'cosine' | 'l2' | 'ip';
+    /** Maximum number of elements (default: 100000) */
+    maxElements?: number;
+    /** HNSW M parameter - connections per layer (default: 16) */
+    M?: number;
+    /** HNSW efConstruction - build quality (default: 200) */
+    efConstruction?: number;
+    /** HNSW efSearch - search quality (default: 100) */
+    efSearch?: number;
+}
+export interface SearchResult {
+    /** String ID of the vector */
+    id: string;
+    /** Raw distance value from backend */
+    distance: number;
+    /** Normalized similarity (0-1, higher is more similar) */
+    similarity: number;
+    /** Optional metadata attached to vector */
+    metadata?: Record<string, any>;
+}
+export interface SearchOptions {
+    /** Minimum similarity threshold (0-1) */
+    threshold?: number;
+    /** Override efSearch for this query */
+    efSearch?: number;
+    /** Metadata filters (post-filtering) */
+    filter?: Record<string, any>;
+}
+export interface VectorStats {
+    /** Number of vectors in index */
+    count: number;
+    /** Vector dimension */
+    dimension: number;
+    /** Distance metric */
+    metric: string;
+    /** Backend name */
+    backend: 'ruvector' | 'hnswlib';
+    /** Memory usage in bytes (0 if not available) */
+    memoryUsage: number;
+}
+/**
+ * VectorBackend - Interface for vector search implementations
+ *
+ * All backends must:
+ * 1. Accept string IDs and handle label mapping internally
+ * 2. Normalize distances to similarities (0-1 range)
+ * 3. Support save/load with metadata persistence
+ * 4. Provide stats for monitoring
+ */
+export interface VectorBackend {
+    /** Backend name for detection and logging */
+    readonly name: 'ruvector' | 'hnswlib';
+    /**
+     * Insert a single vector with optional metadata
+     * @param id - Unique string identifier
+     * @param embedding - Vector as Float32Array
+     * @param metadata - Optional metadata to store with vector
+     */
+    insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;
+    /**
+     * Insert multiple vectors in batch (more efficient)
+     * @param items - Array of {id, embedding, metadata?}
+     */
+    insertBatch(items: Array<{
+        id: string;
+        embedding: Float32Array;
+        metadata?: Record<string, any>;
+    }>): void;
+    /**
+     * Search for k-nearest neighbors
+     * @param query - Query vector
+     * @param k - Number of results
+     * @param options - Search options (threshold, efSearch, filters)
+     * @returns Sorted results (most similar first)
+     */
+    search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
+    /**
+     * Remove a vector by ID
+     * @param id - Vector ID to remove
+     * @returns true if removed, false if not found
+     */
+    remove(id: string): boolean;
+    /**
+     * Get backend statistics
+     * @returns Stats object with count, dimension, backend name, etc.
+     */
+    getStats(): VectorStats;
+    /**
+     * Save index to disk
+     * @param path - File path (backend adds extensions as needed)
+     */
+    save(path: string): Promise<void>;
+    /**
+     * Load index from disk
+     * @param path - File path (backend looks for associated files)
+     */
+    load(path: string): Promise<void>;
+    /**
+     * Close and cleanup resources
+     */
+    close(): void;
+}
+//# sourceMappingURL=VectorBackend.d.ts.map

package/dist/packages/agentdb/src/backends/VectorBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorBackend.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/VectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,wEAAwE;IACxE,MAAM,EAAE,QAAQ,GAAG,IAAI,GAAG,IAAI,CAAC;IAE/B,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6DAA6D;IAC7D,CAAC,CAAC,EAAE,MAAM,CAAC;IAEX,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IAEX,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IAEjB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IAEnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IAEd,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAElB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,mBAAmB;IACnB,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAEhC,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAElF;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC;QACvB,EAAE,EAAE,MAAM,CAAC;QACX,SAAS,EAAE,YAAY,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAChC,CAAC,GAAG,IAAI,CAAC;IAEV;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE,CAAC;IAEhF;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B;;;OAGG;IACH,QAAQ,IAAI,WAAW,CAAC;IAExB;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElC;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/packages/agentdb/src/backends/VectorBackend.js

@@ -0,0 +1,14 @@
+/**
+ * VectorBackend - Unified interface for vector database backends
+ *
+ * Provides abstraction over different vector search implementations
+ * (RuVector, hnswlib-node) for AgentDB v2.
+ *
+ * Design:
+ * - String-based IDs for all operations (backends handle label mapping internally)
+ * - Consistent SearchResult format across backends
+ * - Save/load with metadata persistence
+ * - Backend-specific optimizations hidden behind interface
+ */
+export {};
+//# sourceMappingURL=VectorBackend.js.map

package/dist/packages/agentdb/src/backends/VectorBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorBackend.js","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/VectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG","sourcesContent":["/**\n * VectorBackend - Unified interface for vector database backends\n *\n * Provides abstraction over different vector search implementations\n * (RuVector, hnswlib-node) for AgentDB v2.\n *\n * Design:\n * - String-based IDs for all operations (backends handle label mapping internally)\n * - Consistent SearchResult format across backends\n * - Save/load with metadata persistence\n * - Backend-specific optimizations hidden behind interface\n */\n\nexport interface VectorConfig {\n  /** Vector dimension (e.g., 384, 768, 1536) */\n  dimension?: number;\n  /** Alias for dimension (backward compatibility) */\n  dimensions?: number;\n\n  /** Distance metric: 'cosine', 'l2' (Euclidean), 'ip' (inner product) */\n  metric: 'cosine' | 'l2' | 'ip';\n\n  /** Maximum number of elements (default: 100000) */\n  maxElements?: number;\n\n  /** HNSW M parameter - connections per layer (default: 16) */\n  M?: number;\n\n  /** HNSW efConstruction - build quality (default: 200) */\n  efConstruction?: number;\n\n  /** HNSW efSearch - search quality (default: 100) */\n  efSearch?: number;\n}\n\nexport interface SearchResult {\n  /** String ID of the vector */\n  id: string;\n\n  /** Raw distance value from backend */\n  distance: number;\n\n  /** Normalized similarity (0-1, higher is more similar) */\n  similarity: number;\n\n  /** Optional metadata attached to vector */\n  metadata?: Record<string, any>;\n}\n\nexport interface SearchOptions {\n  /** Minimum similarity threshold (0-1) */\n  threshold?: number;\n\n  /** Override efSearch for this query */\n  efSearch?: number;\n\n  /** Metadata filters (post-filtering) */\n  filter?: Record<string, any>;\n}\n\nexport interface VectorStats {\n  /** Number of vectors in index */\n  count: number;\n\n  /** Vector dimension */\n  dimension: number;\n\n  /** Distance metric */\n  metric: string;\n\n  /** Backend name */\n  backend: 'ruvector' | 'hnswlib';\n\n  /** Memory usage in bytes (0 if not available) */\n  memoryUsage: number;\n}\n\n/**\n * VectorBackend - Interface for vector search implementations\n *\n * All backends must:\n * 1. Accept string IDs and handle label mapping internally\n * 2. Normalize distances to similarities (0-1 range)\n * 3. Support save/load with metadata persistence\n * 4. Provide stats for monitoring\n */\nexport interface VectorBackend {\n  /** Backend name for detection and logging */\n  readonly name: 'ruvector' | 'hnswlib';\n\n  /**\n   * Insert a single vector with optional metadata\n   * @param id - Unique string identifier\n   * @param embedding - Vector as Float32Array\n   * @param metadata - Optional metadata to store with vector\n   */\n  insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;\n\n  /**\n   * Insert multiple vectors in batch (more efficient)\n   * @param items - Array of {id, embedding, metadata?}\n   */\n  insertBatch(items: Array<{\n    id: string;\n    embedding: Float32Array;\n    metadata?: Record<string, any>;\n  }>): void;\n\n  /**\n   * Search for k-nearest neighbors\n   * @param query - Query vector\n   * @param k - Number of results\n   * @param options - Search options (threshold, efSearch, filters)\n   * @returns Sorted results (most similar first)\n   */\n  search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];\n\n  /**\n   * Remove a vector by ID\n   * @param id - Vector ID to remove\n   * @returns true if removed, false if not found\n   */\n  remove(id: string): boolean;\n\n  /**\n   * Get backend statistics\n   * @returns Stats object with count, dimension, backend name, etc.\n   */\n  getStats(): VectorStats;\n\n  /**\n   * Save index to disk\n   * @param path - File path (backend adds extensions as needed)\n   */\n  save(path: string): Promise<void>;\n\n  /**\n   * Load index from disk\n   * @param path - File path (backend looks for associated files)\n   */\n  load(path: string): Promise<void>;\n\n  /**\n   * Close and cleanup resources\n   */\n  close(): void;\n}\n"]}

package/dist/packages/agentdb/src/backends/factory.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Backend Factory - Automatic Backend Detection and Selection
+ *
+ * Detects available vector backends and creates appropriate instances.
+ * Priority: RuVector (native/WASM) > HNSWLib (Node.js)
+ *
+ * Features:
+ * - Automatic detection of @ruvector packages
+ * - Native vs WASM detection for RuVector
+ * - GNN and Graph capabilities detection
+ * - Graceful fallback to HNSWLib
+ * - Clear error messages for missing dependencies
+ */
+import type { VectorBackend, VectorConfig } from './VectorBackend.js';
+import { GuardedVectorBackend, ProofDeniedError } from './ruvector/GuardedVectorBackend.js';
+import { MutationGuard } from '../security/MutationGuard.js';
+import { AttestationLog } from '../security/AttestationLog.js';
+export type BackendType = 'auto' | 'ruvector' | 'hnswlib';
+export interface BackendDetection {
+    available: 'ruvector' | 'hnswlib' | 'none';
+    ruvector: {
+        core: boolean;
+        gnn: boolean;
+        graph: boolean;
+        native: boolean;
+        graphTransformer: boolean;
+    };
+    hnswlib: boolean;
+}
+/**
+ * Detect available vector backends
+ */
+export declare function detectBackends(): Promise<BackendDetection>;
+/**
+ * Create vector backend with automatic detection
+ *
+ * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'
+ * @param config - Vector configuration
+ * @returns Initialized VectorBackend instance
+ */
+export declare function createBackend(type: BackendType, config: VectorConfig): Promise<VectorBackend>;
+/**
+ * Get recommended backend type based on environment
+ */
+export declare function getRecommendedBackend(): Promise<BackendType>;
+/**
+ * Check if a specific backend is available
+ */
+export declare function isBackendAvailable(backend: 'ruvector' | 'hnswlib'): Promise<boolean>;
+/**
+ * Get installation instructions for a backend
+ */
+export declare function getInstallCommand(backend: 'ruvector' | 'hnswlib'): string;
+export { GuardedVectorBackend, ProofDeniedError };
+/**
+ * Create a proof-gated vector backend (ADR-060)
+ *
+ * Wraps a standard VectorBackend with MutationGuard to require
+ * cryptographic proofs for all mutating operations. Optionally
+ * attaches an AttestationLog when a database handle is provided.
+ *
+ * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'
+ * @param config - Vector configuration with optional database handle
+ * @returns Object containing the guarded backend, guard, and optional log
+ */
+export declare function createGuardedBackend(type: BackendType, config: VectorConfig & {
+    database?: any;
+    enableProofs?: boolean;
+}): Promise<{
+    backend: GuardedVectorBackend;
+    guard: MutationGuard;
+    log: AttestationLog | null;
+}>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/packages/agentdb/src/backends/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../../../packages/agentdb/src/backends/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGtE,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAC5F,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;IAC3C,QAAQ,EAAE;QACR,IAAI,EAAE,OAAO,CAAC;QACd,GAAG,EAAE,OAAO,CAAC;QACb,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,EAAE,OAAO,CAAC;QAChB,gBAAgB,EAAE,OAAO,CAAC;KAC3B,CAAC;IACF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAsGhE;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,aAAa,CAAC,CA+ExB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,WAAW,CAAC,CAUlE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAQ1F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAIzE;AAGD,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,YAAY,GAAG;IAAE,QAAQ,CAAC,EAAE,GAAG,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAChE,OAAO,CAAC;IAAE,OAAO,EAAE,oBAAoB,CAAC;IAAC,KAAK,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,CAAC,CA0B9F"}