agentdb 1.6.1 → 2.0.0-alpha.2

package/dist/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/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/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/backends/VectorBackend.js.map

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

package/dist/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/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"}

package/dist/backends/detector.js

@@ -0,0 +1,192 @@
+/**
+ * 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
+ */
+/**
+ * Detect available vector backend and features
+ *
+ * @returns Detection result with backend type and available features
+ */
+export async function detectBackend() {
+    // Get platform information
+    const platform = getPlatformInfo();
+    // Check for RuVector (preferred)
+    const ruvectorAvailable = await checkRuVector();
+    if (ruvectorAvailable.available) {
+        return {
+            backend: 'ruvector',
+            features: {
+                gnn: ruvectorAvailable.gnn,
+                graph: ruvectorAvailable.graph,
+                compression: true, // RuVector always supports compression
+            },
+            platform,
+            native: ruvectorAvailable.native,
+            versions: {
+                core: ruvectorAvailable.version,
+            },
+        };
+    }
+    // Fallback to HNSWLib
+    const hnswlibNative = await checkHnswlib();
+    return {
+        backend: 'hnswlib',
+        features: {
+            gnn: false,
+            graph: false,
+            compression: false,
+        },
+        platform,
+        native: hnswlibNative,
+    };
+}
+/**
+ * Check RuVector availability and features
+ */
+async function checkRuVector() {
+    try {
+        // Try to import @ruvector/core
+        const core = await import('@ruvector/core');
+        // Check if native bindings are available
+        const native = core.isNative?.() ?? false;
+        // Get version (if available)
+        const version = core.version ?? 'unknown';
+        // Check for GNN support
+        let gnn = false;
+        try {
+            await import('@ruvector/gnn');
+            gnn = true;
+        }
+        catch {
+            // GNN not available
+        }
+        // Check for Graph support
+        let graph = false;
+        try {
+            await import('@ruvector/graph-node');
+            graph = true;
+        }
+        catch {
+            // Graph not available
+        }
+        return {
+            available: true,
+            native,
+            gnn,
+            graph,
+            version,
+        };
+    }
+    catch (error) {
+        // RuVector not available
+        return {
+            available: false,
+            native: false,
+            gnn: false,
+            graph: false,
+        };
+    }
+}
+/**
+ * Check HNSWLib availability
+ */
+async function checkHnswlib() {
+    try {
+        // Try to import hnswlib-node
+        await import('hnswlib-node');
+        return true;
+    }
+    catch (error) {
+        console.warn('[AgentDB] HNSWLib not available:', error);
+        return false;
+    }
+}
+/**
+ * Get platform information
+ */
+function getPlatformInfo() {
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        combined: `${process.platform}-${process.arch}`,
+    };
+}
+/**
+ * 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 function validateBackend(requested, detected) {
+    if (requested === 'auto') {
+        // Auto-detection always succeeds
+        return;
+    }
+    if (requested === 'ruvector' && detected.backend !== 'ruvector') {
+        throw new Error('RuVector backend requested but not available.\n' +
+            'Install with: npm install @ruvector/core\n' +
+            'See: https://github.com/ruvnet/ruvector');
+    }
+    if (requested === 'hnswlib' && detected.backend !== 'hnswlib') {
+        throw new Error('HNSWLib backend requested but not available.\n' +
+            'Install with: npm install hnswlib-node');
+    }
+}
+/**
+ * Get recommended backend for a given use case
+ *
+ * @param useCase - Use case identifier
+ * @returns Recommended backend type
+ */
+export function getRecommendedBackend(useCase) {
+    const useCaseLower = useCase.toLowerCase();
+    // RuVector recommended for advanced features
+    if (useCaseLower.includes('learning') ||
+        useCaseLower.includes('gnn') ||
+        useCaseLower.includes('graph') ||
+        useCaseLower.includes('compression')) {
+        return 'ruvector';
+    }
+    // Auto-detection for general use
+    return 'auto';
+}
+/**
+ * Format detection result for display
+ *
+ * @param result - Detection result
+ * @returns Formatted string for console output
+ */
+export function formatDetectionResult(result) {
+    const lines = [];
+    lines.push('📊 Backend Detection Results:');
+    lines.push('');
+    lines.push(`  Backend:     ${result.backend}`);
+    lines.push(`  Platform:    ${result.platform.combined}`);
+    lines.push(`  Native:      ${result.native ? '✅' : '❌ (using WASM)'}`);
+    lines.push(`  GNN:         ${result.features.gnn ? '✅' : '❌'}`);
+    lines.push(`  Graph:       ${result.features.graph ? '✅' : '❌'}`);
+    lines.push(`  Compression: ${result.features.compression ? '✅' : '❌'}`);
+    if (result.versions?.core) {
+        lines.push(`  Version:     ${result.versions.core}`);
+    }
+    lines.push('');
+    // Add recommendations
+    if (result.backend === 'hnswlib') {
+        lines.push('💡 Tip: Install @ruvector/core for 150x faster performance');
+        lines.push('   npm install @ruvector/core');
+    }
+    else if (!result.features.gnn) {
+        lines.push('💡 Tip: Install @ruvector/gnn for adaptive learning');
+        lines.push('   npm install @ruvector/gnn');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=detector.js.map

package/dist/backends/detector.js.map

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

package/dist/backends/factory.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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';
+export type BackendType = 'auto' | 'ruvector' | 'hnswlib';
+export interface BackendDetection {
+    available: 'ruvector' | 'hnswlib' | 'none';
+    ruvector: {
+        core: boolean;
+        gnn: boolean;
+        graph: boolean;
+        native: 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;
+//# sourceMappingURL=factory.d.ts.map

package/dist/backends/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/backends/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAItE,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;KACjB,CAAC;IACF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA6DhE;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,aAAa,CAAC,CAgDxB;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"}

package/dist/backends/factory.js

@@ -0,0 +1,161 @@
+/**
+ * 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 { RuVectorBackend } from './ruvector/RuVectorBackend.js';
+import { HNSWLibBackend } from './hnswlib/HNSWLibBackend.js';
+/**
+ * Detect available vector backends
+ */
+export async function detectBackends() {
+    const result = {
+        available: 'none',
+        ruvector: {
+            core: false,
+            gnn: false,
+            graph: false,
+            native: false
+        },
+        hnswlib: false
+    };
+    // Check RuVector packages (main package or scoped packages)
+    try {
+        // Try main ruvector package first
+        const ruvector = await import('ruvector');
+        result.ruvector.core = true;
+        result.ruvector.gnn = true; // Main package includes GNN
+        result.ruvector.graph = true; // Main package includes Graph
+        result.ruvector.native = ruvector.isNative?.() ?? false;
+        result.available = 'ruvector';
+    }
+    catch {
+        // Try scoped packages as fallback
+        try {
+            const core = await import('@ruvector/core');
+            result.ruvector.core = true;
+            result.ruvector.native = core.isNative?.() ?? false;
+            result.available = 'ruvector';
+            // Check optional packages
+            try {
+                await import('@ruvector/gnn');
+                result.ruvector.gnn = true;
+            }
+            catch {
+                // GNN not installed - this is optional
+            }
+            try {
+                await import('@ruvector/graph-node');
+                result.ruvector.graph = true;
+            }
+            catch {
+                // Graph not installed - this is optional
+            }
+        }
+        catch {
+            // RuVector not installed - will try fallback
+        }
+    }
+    // Check HNSWLib
+    try {
+        await import('hnswlib-node');
+        result.hnswlib = true;
+        if (result.available === 'none') {
+            result.available = 'hnswlib';
+        }
+    }
+    catch {
+        // HNSWLib not installed
+    }
+    return result;
+}
+/**
+ * Create vector backend with automatic detection
+ *
+ * @param type - Backend type: 'auto', 'ruvector', or 'hnswlib'
+ * @param config - Vector configuration
+ * @returns Initialized VectorBackend instance
+ */
+export async function createBackend(type, config) {
+    const detection = await detectBackends();
+    let backend;
+    // Handle explicit backend selection
+    if (type === 'ruvector') {
+        if (!detection.ruvector.core) {
+            throw new Error('RuVector not available.\n' +
+                'Install with: npm install @ruvector/core\n' +
+                'Optional GNN support: npm install @ruvector/gnn\n' +
+                'Optional Graph support: npm install @ruvector/graph-node');
+        }
+        backend = new RuVectorBackend(config);
+    }
+    else if (type === 'hnswlib') {
+        if (!detection.hnswlib) {
+            throw new Error('HNSWLib not available.\n' +
+                'Install with: npm install hnswlib-node');
+        }
+        backend = new HNSWLibBackend(config);
+    }
+    else {
+        // Auto-detect best available backend
+        if (detection.ruvector.core) {
+            backend = new RuVectorBackend(config);
+            console.log(`[AgentDB] Using RuVector backend (${detection.ruvector.native ? 'native' : 'WASM'})`);
+        }
+        else if (detection.hnswlib) {
+            backend = new HNSWLibBackend(config);
+            console.log('[AgentDB] Using HNSWLib backend (fallback)');
+        }
+        else {
+            throw new Error('No vector backend available.\n' +
+                'Install one of:\n' +
+                '  - npm install @ruvector/core (recommended)\n' +
+                '  - npm install hnswlib-node (fallback)');
+        }
+    }
+    // Initialize the backend
+    await backend.initialize();
+    return backend;
+}
+/**
+ * Get recommended backend type based on environment
+ */
+export async function getRecommendedBackend() {
+    const detection = await detectBackends();
+    if (detection.ruvector.core) {
+        return 'ruvector';
+    }
+    else if (detection.hnswlib) {
+        return 'hnswlib';
+    }
+    else {
+        return 'auto'; // Will throw error in createBackend
+    }
+}
+/**
+ * Check if a specific backend is available
+ */
+export async function isBackendAvailable(backend) {
+    const detection = await detectBackends();
+    if (backend === 'ruvector') {
+        return detection.ruvector.core;
+    }
+    return detection.hnswlib;
+}
+/**
+ * Get installation instructions for a backend
+ */
+export function getInstallCommand(backend) {
+    return backend === 'ruvector'
+        ? 'npm install ruvector'
+        : 'npm install hnswlib-node';
+}
+//# sourceMappingURL=factory.js.map

package/dist/backends/factory.js.map

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