agentdb 1.6.0 → 2.0.0-alpha.1

package/dist/src/backends/GraphBackend.d.ts

@@ -0,0 +1,196 @@
+/**
+ * GraphBackend Interface - Graph database capabilities (Optional)
+ *
+ * Provides property graph storage and Cypher-like query capabilities.
+ * Available when @ruvector/graph-node is installed.
+ *
+ * Features:
+ * - Node and relationship management
+ * - Cypher query execution
+ * - Graph traversal and pattern matching
+ * - Integration with vector search
+ */
+/**
+ * Graph node representation
+ */
+export interface GraphNode {
+    /** Unique node identifier */
+    id: string;
+    /** Node labels (types) */
+    labels: string[];
+    /** Node properties */
+    properties: Record<string, any>;
+    /** Optional vector embedding for hybrid search */
+    embedding?: Float32Array;
+}
+/**
+ * Graph relationship representation
+ */
+export interface GraphRelationship {
+    /** Unique relationship identifier */
+    id: string;
+    /** Source node ID */
+    from: string;
+    /** Target node ID */
+    to: string;
+    /** Relationship type */
+    type: string;
+    /** Relationship properties */
+    properties?: Record<string, any>;
+}
+/**
+ * Cypher query result
+ */
+export interface QueryResult {
+    /** Result rows */
+    rows: Record<string, any>[];
+    /** Result columns */
+    columns: string[];
+    /** Number of rows returned */
+    count: number;
+    /** Query execution time in milliseconds */
+    executionTime: number;
+}
+/**
+ * Graph traversal options
+ */
+export interface TraversalOptions {
+    /** Maximum traversal depth */
+    maxDepth?: number;
+    /** Relationship types to follow (empty = all) */
+    relationshipTypes?: string[];
+    /** Node label filter */
+    nodeLabels?: string[];
+    /** Direction: 'outgoing', 'incoming', 'both' */
+    direction?: 'outgoing' | 'incoming' | 'both';
+}
+/**
+ * Graph statistics
+ */
+export interface GraphStats {
+    /** Total number of nodes */
+    nodeCount: number;
+    /** Total number of relationships */
+    relationshipCount: number;
+    /** Node label distribution */
+    nodeLabelCounts: Record<string, number>;
+    /** Relationship type distribution */
+    relationshipTypeCounts: Record<string, number>;
+    /** Estimated memory usage in bytes */
+    memoryUsage: number;
+}
+/**
+ * GraphBackend - Optional graph database interface
+ *
+ * Implementations:
+ * - RuVectorGraph: Native Rust graph with @ruvector/graph-node
+ * - MockGraphBackend: No-op implementation for testing
+ */
+export interface GraphBackend {
+    /**
+     * Execute a Cypher query
+     *
+     * @param cypher - Cypher query string
+     * @param params - Query parameters
+     * @returns Query result with rows and metadata
+     */
+    execute(cypher: string, params?: Record<string, any>): Promise<QueryResult>;
+    /**
+     * Create a new node
+     *
+     * @param labels - Node labels (types)
+     * @param properties - Node properties
+     * @returns Created node ID
+     */
+    createNode(labels: string[], properties: Record<string, any>): Promise<string>;
+    /**
+     * Get a node by ID
+     *
+     * @param id - Node identifier
+     * @returns Node or null if not found
+     */
+    getNode(id: string): Promise<GraphNode | null>;
+    /**
+     * Update node properties
+     *
+     * @param id - Node identifier
+     * @param properties - Properties to update
+     * @returns True if updated, false if not found
+     */
+    updateNode(id: string, properties: Record<string, any>): Promise<boolean>;
+    /**
+     * Delete a node and its relationships
+     *
+     * @param id - Node identifier
+     * @returns True if deleted, false if not found
+     */
+    deleteNode(id: string): Promise<boolean>;
+    /**
+     * Create a relationship between nodes
+     *
+     * @param from - Source node ID
+     * @param to - Target node ID
+     * @param type - Relationship type
+     * @param properties - Optional relationship properties
+     * @returns Created relationship ID
+     */
+    createRelationship(from: string, to: string, type: string, properties?: Record<string, any>): Promise<string>;
+    /**
+     * Get a relationship by ID
+     *
+     * @param id - Relationship identifier
+     * @returns Relationship or null if not found
+     */
+    getRelationship(id: string): Promise<GraphRelationship | null>;
+    /**
+     * Delete a relationship
+     *
+     * @param id - Relationship identifier
+     * @returns True if deleted, false if not found
+     */
+    deleteRelationship(id: string): Promise<boolean>;
+    /**
+     * Traverse the graph from a starting node
+     *
+     * @param startId - Starting node ID
+     * @param pattern - Traversal pattern (e.g., "()-[:RELATES_TO]->(:Entity)")
+     * @param options - Traversal options
+     * @returns Array of nodes found during traversal
+     */
+    traverse(startId: string, pattern: string, options?: TraversalOptions): Promise<GraphNode[]>;
+    /**
+     * Find shortest path between two nodes
+     *
+     * @param fromId - Source node ID
+     * @param toId - Target node ID
+     * @param options - Traversal options
+     * @returns Array of nodes representing the path, or empty if no path exists
+     */
+    shortestPath(fromId: string, toId: string, options?: TraversalOptions): Promise<GraphNode[]>;
+    /**
+     * Find nodes similar to a query vector within a graph context
+     *
+     * Combines vector similarity search with graph structure
+     *
+     * @param query - Query vector
+     * @param k - Number of results
+     * @param contextNodeId - Optional context node for graph-based filtering
+     * @returns Array of nodes sorted by similarity
+     */
+    vectorSearch(query: Float32Array, k: number, contextNodeId?: string): Promise<GraphNode[]>;
+    /**
+     * Get graph statistics
+     *
+     * @returns Current statistics of the graph
+     */
+    getStats(): GraphStats;
+    /**
+     * Clear the entire graph
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Type guard to check if an object implements GraphBackend
+ */
+export declare function isGraphBackend(obj: any): obj is GraphBackend;
+//# sourceMappingURL=GraphBackend.d.ts.map

package/dist/src/backends/GraphBackend.d.ts.map

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

package/dist/src/backends/GraphBackend.js

@@ -0,0 +1,33 @@
+/**
+ * GraphBackend Interface - Graph database capabilities (Optional)
+ *
+ * Provides property graph storage and Cypher-like query capabilities.
+ * Available when @ruvector/graph-node is installed.
+ *
+ * Features:
+ * - Node and relationship management
+ * - Cypher query execution
+ * - Graph traversal and pattern matching
+ * - Integration with vector search
+ */
+/**
+ * Type guard to check if an object implements GraphBackend
+ */
+export function isGraphBackend(obj) {
+    return (typeof obj === 'object' &&
+        obj !== null &&
+        typeof obj.execute === 'function' &&
+        typeof obj.createNode === 'function' &&
+        typeof obj.getNode === 'function' &&
+        typeof obj.updateNode === 'function' &&
+        typeof obj.deleteNode === 'function' &&
+        typeof obj.createRelationship === 'function' &&
+        typeof obj.getRelationship === 'function' &&
+        typeof obj.deleteRelationship === 'function' &&
+        typeof obj.traverse === 'function' &&
+        typeof obj.shortestPath === 'function' &&
+        typeof obj.vectorSearch === 'function' &&
+        typeof obj.getStats === 'function' &&
+        typeof obj.clear === 'function');
+}
+//# sourceMappingURL=GraphBackend.js.map

package/dist/src/backends/GraphBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GraphBackend.js","sourceRoot":"","sources":["../../../src/backends/GraphBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiQH;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACZ,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,UAAU,KAAK,UAAU;QACpC,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,UAAU,KAAK,UAAU;QACpC,OAAO,GAAG,CAAC,UAAU,KAAK,UAAU;QACpC,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU;QAC5C,OAAO,GAAG,CAAC,eAAe,KAAK,UAAU;QACzC,OAAO,GAAG,CAAC,kBAAkB,KAAK,UAAU;QAC5C,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;QAClC,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU;QACtC,OAAO,GAAG,CAAC,YAAY,KAAK,UAAU;QACtC,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;QAClC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU,CAChC,CAAC;AACJ,CAAC"}

package/dist/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/src/backends/LearningBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningBackend.d.ts","sourceRoot":"","sources":["../../../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/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/src/backends/LearningBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LearningBackend.js","sourceRoot":"","sources":["../../../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"}

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

@@ -0,0 +1,119 @@
+/**
+ * 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;
+    /** 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/src/backends/VectorBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorBackend.d.ts","sourceRoot":"","sources":["../../../src/backends/VectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAElB,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/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/src/backends/VectorBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VectorBackend.js","sourceRoot":"","sources":["../../../src/backends/VectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/backends/detector.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Backend Detection - Auto-detect available vector backends
+ *
+ * Detection priority:
+ * 1. RuVector (@ruvector/core) - preferred for performance
+ * 2. HNSWLib (hnswlib-node) - stable fallback
+ *
+ * Additional features detected:
+ * - @ruvector/gnn - GNN learning capabilities
+ * - @ruvector/graph-node - Graph database capabilities
+ */
+/**
+ * Backend type identifier
+ */
+export type BackendType = 'ruvector' | 'hnswlib' | 'auto';
+/**
+ * Platform information
+ */
+export interface PlatformInfo {
+    /** Operating system */
+    platform: NodeJS.Platform;
+    /** CPU architecture */
+    arch: string;
+    /** Combined platform identifier (e.g., 'linux-x64', 'darwin-arm64') */
+    combined: string;
+}
+/**
+ * Backend detection result
+ */
+export interface DetectionResult {
+    /** Detected backend type */
+    backend: 'ruvector' | 'hnswlib';
+    /** Available feature flags */
+    features: {
+        /** GNN learning available */
+        gnn: boolean;
+        /** Graph database available */
+        graph: boolean;
+        /** Compression available */
+        compression: boolean;
+    };
+    /** Platform information */
+    platform: PlatformInfo;
+    /** Whether native bindings are available (vs WASM fallback) */
+    native: boolean;
+    /** Version information */
+    versions?: {
+        core?: string;
+        gnn?: string;
+        graph?: string;
+    };
+}
+/**
+ * Detect available vector backend and features
+ *
+ * @returns Detection result with backend type and available features
+ */
+export declare function detectBackend(): Promise<DetectionResult>;
+/**
+ * Validate requested backend is available
+ *
+ * @param requested - Requested backend type
+ * @param detected - Detected backend from auto-detection
+ * @throws Error if requested backend is not available
+ */
+export declare function validateBackend(requested: BackendType, detected: DetectionResult): void;
+/**
+ * Get recommended backend for a given use case
+ *
+ * @param useCase - Use case identifier
+ * @returns Recommended backend type
+ */
+export declare function getRecommendedBackend(useCase: string): BackendType;
+/**
+ * Format detection result for display
+ *
+ * @param result - Detection result
+ * @returns Formatted string for console output
+ */
+export declare function formatDetectionResult(result: DetectionResult): string;
+//# sourceMappingURL=detector.d.ts.map

package/dist/src/backends/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../../src/backends/detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAE1B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IAEb,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4BAA4B;IAC5B,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IAEhC,8BAA8B;IAC9B,QAAQ,EAAE;QACR,6BAA6B;QAC7B,GAAG,EAAE,OAAO,CAAC;QAEb,+BAA+B;QAC/B,KAAK,EAAE,OAAO,CAAC;QAEf,4BAA4B;QAC5B,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IAEF,2BAA2B;IAC3B,QAAQ,EAAE,YAAY,CAAC;IAEvB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;IAEhB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE;QACT,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAaD;;;;GAIG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,eAAe,CAAC,CAoC9D;AA6ED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EACtB,QAAQ,EAAE,eAAe,GACxB,IAAI,CAoBN;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CAelE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CA4BrE"}