@robthepcguy/rag-vault 1.0.0

package/dist/utils/logger.d.ts

@@ -0,0 +1,36 @@
+interface LogMeta {
+    [key: string]: unknown;
+}
+/**
+ * Logger utility with structured output
+ *
+ * All output goes to stderr to avoid interfering with MCP stdio transport.
+ * Use this instead of console.log/console.error directly.
+ *
+ * @internal - This is for internal use only, not part of public API.
+ * Currently exported for future migration of console.error() calls.
+ *
+ * @example
+ * logger.info('Server started', { port: 3000 })
+ * logger.error('Failed to process', { error: err.message })
+ */
+export declare const logger: {
+    /**
+     * Debug-level logging (only when DEBUG=true or LOG_LEVEL=debug)
+     */
+    debug(message: string, meta?: LogMeta): void;
+    /**
+     * Info-level logging for normal operations
+     */
+    info(message: string, meta?: LogMeta): void;
+    /**
+     * Warning-level logging for potential issues
+     */
+    warn(message: string, meta?: LogMeta): void;
+    /**
+     * Error-level logging for failures
+     */
+    error(message: string, meta?: LogMeta): void;
+};
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAKA,UAAU,OAAO;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAsBD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,MAAM;IACjB;;OAEG;mBACY,MAAM,SAAS,OAAO,GAAG,IAAI;IAM5C;;OAEG;kBACW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3C;;OAEG;kBACW,MAAM,SAAS,OAAO,GAAG,IAAI;IAI3C;;OAEG;mBACY,MAAM,SAAS,OAAO,GAAG,IAAI;CAG7C,CAAA"}

package/dist/utils/logger.js

@@ -0,0 +1,64 @@
+"use strict";
+// Centralized logging utility
+// Provides structured logging with levels and optional metadata
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+/**
+ * Format a log message with optional metadata
+ */
+function formatMessage(level, message, meta) {
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+    if (meta && Object.keys(meta).length > 0) {
+        return `${prefix} ${message} ${JSON.stringify(meta)}`;
+    }
+    return `${prefix} ${message}`;
+}
+/**
+ * Check if debug logging is enabled
+ */
+function isDebugEnabled() {
+    return process.env['DEBUG'] === 'true' || process.env['LOG_LEVEL'] === 'debug';
+}
+/**
+ * Logger utility with structured output
+ *
+ * All output goes to stderr to avoid interfering with MCP stdio transport.
+ * Use this instead of console.log/console.error directly.
+ *
+ * @internal - This is for internal use only, not part of public API.
+ * Currently exported for future migration of console.error() calls.
+ *
+ * @example
+ * logger.info('Server started', { port: 3000 })
+ * logger.error('Failed to process', { error: err.message })
+ */
+exports.logger = {
+    /**
+     * Debug-level logging (only when DEBUG=true or LOG_LEVEL=debug)
+     */
+    debug(message, meta) {
+        if (isDebugEnabled()) {
+            console.error(formatMessage('debug', message, meta));
+        }
+    },
+    /**
+     * Info-level logging for normal operations
+     */
+    info(message, meta) {
+        console.error(formatMessage('info', message, meta));
+    },
+    /**
+     * Warning-level logging for potential issues
+     */
+    warn(message, meta) {
+        console.error(formatMessage('warn', message, meta));
+    },
+    /**
+     * Error-level logging for failures
+     */
+    error(message, meta) {
+        console.error(formatMessage('error', message, meta));
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":";AAAA,8BAA8B;AAC9B,gEAAgE;;;AAQhE;;GAEG;AACH,SAAS,aAAa,CAAC,KAAe,EAAE,OAAe,EAAE,IAAc;IACrE,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IAC1C,MAAM,MAAM,GAAG,IAAI,SAAS,MAAM,KAAK,CAAC,WAAW,EAAE,GAAG,CAAA;IAExD,IAAI,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzC,OAAO,GAAG,MAAM,IAAI,OAAO,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAA;IACvD,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,OAAO,EAAE,CAAA;AAC/B,CAAC;AAED;;GAEG;AACH,SAAS,cAAc;IACrB,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,KAAK,OAAO,CAAA;AAChF,CAAC;AAED;;;;;;;;;;;;GAYG;AACU,QAAA,MAAM,GAAG;IACpB;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,cAAc,EAAE,EAAE,CAAC;YACrB,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;QACtD,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;IACrD,CAAC;IAED;;OAEG;IACH,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;IACrD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAA;IACtD,CAAC;CACF,CAAA"}

package/dist/utils/math.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Calculate cosine similarity between two vectors.
+ *
+ * Cosine similarity measures the cosine of the angle between two vectors,
+ * ranging from -1 (opposite) to 1 (identical), with 0 being orthogonal.
+ *
+ * @param vec1 - First vector
+ * @param vec2 - Second vector
+ * @returns Cosine similarity value between -1 and 1, or 0 if vectors are invalid
+ *
+ * @example
+ * ```typescript
+ * const similarity = cosineSimilarity([1, 0, 0], [1, 0, 0]) // 1.0 (identical)
+ * const orthogonal = cosineSimilarity([1, 0, 0], [0, 1, 0]) // 0.0 (orthogonal)
+ * const opposite = cosineSimilarity([1, 0, 0], [-1, 0, 0])  // -1.0 (opposite)
+ * ```
+ */
+export declare function cosineSimilarity(vec1: number[], vec2: number[]): number;
+/**
+ * Calculate the dot product of two vectors.
+ *
+ * @param vec1 - First vector
+ * @param vec2 - Second vector
+ * @returns Dot product value, or 0 if vectors have different lengths
+ */
+export declare function dotProduct(vec1: number[], vec2: number[]): number;
+/**
+ * Calculate the Euclidean norm (L2 norm) of a vector.
+ *
+ * @param vec - Input vector
+ * @returns Euclidean norm (magnitude) of the vector
+ */
+export declare function euclideanNorm(vec: number[]): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBvE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAWjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,CAMnD"}

package/dist/utils/math.js

@@ -0,0 +1,73 @@
+"use strict";
+// Mathematical utility functions for vector operations
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cosineSimilarity = cosineSimilarity;
+exports.dotProduct = dotProduct;
+exports.euclideanNorm = euclideanNorm;
+/**
+ * Calculate cosine similarity between two vectors.
+ *
+ * Cosine similarity measures the cosine of the angle between two vectors,
+ * ranging from -1 (opposite) to 1 (identical), with 0 being orthogonal.
+ *
+ * @param vec1 - First vector
+ * @param vec2 - Second vector
+ * @returns Cosine similarity value between -1 and 1, or 0 if vectors are invalid
+ *
+ * @example
+ * ```typescript
+ * const similarity = cosineSimilarity([1, 0, 0], [1, 0, 0]) // 1.0 (identical)
+ * const orthogonal = cosineSimilarity([1, 0, 0], [0, 1, 0]) // 0.0 (orthogonal)
+ * const opposite = cosineSimilarity([1, 0, 0], [-1, 0, 0])  // -1.0 (opposite)
+ * ```
+ */
+function cosineSimilarity(vec1, vec2) {
+    if (vec1.length !== vec2.length || vec1.length === 0) {
+        return 0;
+    }
+    let dotProduct = 0;
+    let norm1 = 0;
+    let norm2 = 0;
+    for (let i = 0; i < vec1.length; i++) {
+        const v1 = vec1[i] ?? 0;
+        const v2 = vec2[i] ?? 0;
+        dotProduct += v1 * v2;
+        norm1 += v1 * v1;
+        norm2 += v2 * v2;
+    }
+    const denominator = Math.sqrt(norm1) * Math.sqrt(norm2);
+    if (denominator === 0)
+        return 0;
+    return dotProduct / denominator;
+}
+/**
+ * Calculate the dot product of two vectors.
+ *
+ * @param vec1 - First vector
+ * @param vec2 - Second vector
+ * @returns Dot product value, or 0 if vectors have different lengths
+ */
+function dotProduct(vec1, vec2) {
+    if (vec1.length !== vec2.length) {
+        return 0;
+    }
+    let result = 0;
+    for (let i = 0; i < vec1.length; i++) {
+        result += (vec1[i] ?? 0) * (vec2[i] ?? 0);
+    }
+    return result;
+}
+/**
+ * Calculate the Euclidean norm (L2 norm) of a vector.
+ *
+ * @param vec - Input vector
+ * @returns Euclidean norm (magnitude) of the vector
+ */
+function euclideanNorm(vec) {
+    let sum = 0;
+    for (const v of vec) {
+        sum += v * v;
+    }
+    return Math.sqrt(sum);
+}
+//# sourceMappingURL=math.js.map

package/dist/utils/math.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.js","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":";AAAA,uDAAuD;;AAmBvD,4CAqBC;AASD,gCAWC;AAQD,sCAMC;AAxED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,gBAAgB,CAAC,IAAc,EAAE,IAAc;IAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,IAAI,KAAK,GAAG,CAAC,CAAA;IACb,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACvB,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;QACvB,UAAU,IAAI,EAAE,GAAG,EAAE,CAAA;QACrB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAA;QAChB,KAAK,IAAI,EAAE,GAAG,EAAE,CAAA;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACvD,IAAI,WAAW,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAE/B,OAAO,UAAU,GAAG,WAAW,CAAA;AACjC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,IAAc,EAAE,IAAc;IACvD,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,CAAC,CAAA;IACV,CAAC;IAED,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IAC3C,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,GAAa;IACzC,IAAI,GAAG,GAAG,CAAC,CAAA;IACX,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;QACpB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACvB,CAAC"}

package/dist/utils/process-handlers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Register a cleanup callback for graceful shutdown
+ *
+ * Callbacks are executed in order when SIGTERM or SIGINT is received.
+ *
+ * @param callback - Cleanup function to execute on shutdown
+ */
+export declare function onShutdown(callback: () => void | Promise<void>): void;
+/**
+ * Setup global process error handlers
+ *
+ * Handles:
+ * - unhandledRejection: Logs promise rejection and exits
+ * - uncaughtException: Logs exception and exits
+ *
+ * @param exitCode - Exit code to use on error (default: 1)
+ */
+export declare function setupProcessHandlers(exitCode?: number): void;
+/**
+ * Setup graceful shutdown handlers for SIGTERM and SIGINT
+ *
+ * Executes all registered cleanup callbacks before exiting.
+ * Use onShutdown() to register cleanup functions.
+ */
+export declare function setupGracefulShutdown(): void;
+//# sourceMappingURL=process-handlers.d.ts.map

package/dist/utils/process-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-handlers.d.ts","sourceRoot":"","sources":["../../src/utils/process-handlers.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,SAAI,GAAG,IAAI,CAUvD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CA2B5C"}

package/dist/utils/process-handlers.js

@@ -0,0 +1,69 @@
+"use strict";
+// Shared process error handlers
+// Used by both MCP server (src/index.ts) and Web server (src/web/index.ts)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.onShutdown = onShutdown;
+exports.setupProcessHandlers = setupProcessHandlers;
+exports.setupGracefulShutdown = setupGracefulShutdown;
+/** Cleanup callbacks registered for graceful shutdown */
+const cleanupCallbacks = [];
+/**
+ * Register a cleanup callback for graceful shutdown
+ *
+ * Callbacks are executed in order when SIGTERM or SIGINT is received.
+ *
+ * @param callback - Cleanup function to execute on shutdown
+ */
+function onShutdown(callback) {
+    cleanupCallbacks.push(callback);
+}
+/**
+ * Setup global process error handlers
+ *
+ * Handles:
+ * - unhandledRejection: Logs promise rejection and exits
+ * - uncaughtException: Logs exception and exits
+ *
+ * @param exitCode - Exit code to use on error (default: 1)
+ */
+function setupProcessHandlers(exitCode = 1) {
+    process.on('unhandledRejection', (reason, promise) => {
+        console.error('Unhandled Rejection at:', promise, 'reason:', reason);
+        process.exit(exitCode);
+    });
+    process.on('uncaughtException', (error) => {
+        console.error('Uncaught Exception:', error);
+        process.exit(exitCode);
+    });
+}
+/**
+ * Setup graceful shutdown handlers for SIGTERM and SIGINT
+ *
+ * Executes all registered cleanup callbacks before exiting.
+ * Use onShutdown() to register cleanup functions.
+ */
+function setupGracefulShutdown() {
+    let isShuttingDown = false;
+    const shutdown = async (signal) => {
+        if (isShuttingDown) {
+            console.error('Shutdown already in progress...');
+            return;
+        }
+        isShuttingDown = true;
+        console.error(`Received ${signal}, shutting down gracefully...`);
+        // Execute cleanup callbacks
+        for (const callback of cleanupCallbacks) {
+            try {
+                await callback();
+            }
+            catch (error) {
+                console.error('Error during cleanup:', error);
+            }
+        }
+        console.error('Shutdown complete');
+        process.exit(0);
+    };
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('SIGINT', () => shutdown('SIGINT'));
+}
+//# sourceMappingURL=process-handlers.js.map

package/dist/utils/process-handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-handlers.js","sourceRoot":"","sources":["../../src/utils/process-handlers.ts"],"names":[],"mappings":";AAAA,gCAAgC;AAChC,2EAA2E;;AAY3E,gCAEC;AAWD,oDAUC;AAQD,sDA2BC;AApED,yDAAyD;AACzD,MAAM,gBAAgB,GAAsC,EAAE,CAAA;AAE9D;;;;;;GAMG;AACH,SAAgB,UAAU,CAAC,QAAoC;IAC7D,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;AACjC,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,oBAAoB,CAAC,QAAQ,GAAG,CAAC;IAC/C,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,yBAAyB,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;QACpE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACxB,CAAC,CAAC,CAAA;IAEF,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE;QACxC,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAA;QAC3C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACxB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB;IACnC,IAAI,cAAc,GAAG,KAAK,CAAA;IAE1B,MAAM,QAAQ,GAAG,KAAK,EAAE,MAAc,EAAiB,EAAE;QACvD,IAAI,cAAc,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAA;YAChD,OAAM;QACR,CAAC;QACD,cAAc,GAAG,IAAI,CAAA;QAErB,OAAO,CAAC,KAAK,CAAC,YAAY,MAAM,+BAA+B,CAAC,CAAA;QAEhE,4BAA4B;QAC5B,KAAK,MAAM,QAAQ,IAAI,gBAAgB,EAAE,CAAC;YACxC,IAAI,CAAC;gBACH,MAAM,QAAQ,EAAE,CAAA;YAClB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,uBAAuB,EAAE,KAAK,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAA;QAClC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC,CAAA;IAED,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAA;IAChD,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAA;AAChD,CAAC"}

package/dist/vectordb/index.d.ts

@@ -0,0 +1,210 @@
+export { DatabaseError } from '../errors/index.js';
+/**
+ * Grouping mode for quality filtering
+ * - 'similar': Only return the most similar group (stops at first distance jump)
+ * - 'related': Include related groups (stops at second distance jump)
+ */
+export type GroupingMode = 'similar' | 'related';
+/**
+ * VectorStore configuration
+ */
+export interface VectorStoreConfig {
+    /** LanceDB database path */
+    dbPath: string;
+    /** Table name */
+    tableName: string;
+    /** Maximum distance threshold for filtering results (optional) */
+    maxDistance?: number;
+    /** Grouping mode for quality filtering (optional) */
+    grouping?: GroupingMode;
+    /**
+     * Hybrid weight: controls how strongly BM25 boosts candidates from vector search.
+     * 0 = no keyword boost (vector-only), higher values increase keyword match influence.
+     * Default: 0.6
+     */
+    hybridWeight?: number;
+}
+/**
+ * Document metadata
+ */
+export interface DocumentMetadata {
+    /** File name */
+    fileName: string;
+    /** File size in bytes */
+    fileSize: number;
+    /** File type (extension) */
+    fileType: string;
+}
+/**
+ * Vector chunk
+ */
+export interface VectorChunk {
+    /** Chunk ID (UUID) */
+    id: string;
+    /** File path (absolute) */
+    filePath: string;
+    /** Chunk index (zero-based) */
+    chunkIndex: number;
+    /** Chunk text */
+    text: string;
+    /** Embedding vector (dimension depends on model) */
+    vector: number[];
+    /** Metadata */
+    metadata: DocumentMetadata;
+    /** Ingestion timestamp (ISO 8601 format) */
+    timestamp: string;
+}
+/**
+ * Search result
+ */
+export interface SearchResult {
+    /** File path */
+    filePath: string;
+    /** Chunk index */
+    chunkIndex: number;
+    /** Chunk text */
+    text: string;
+    /**
+     * Distance score (lower = more similar).
+     * Uses dot product on normalized embeddings (equivalent to cosine distance).
+     * Range: [0, 2] where 0 = identical, 1 = orthogonal, 2 = opposite.
+     */
+    score: number;
+    /** Metadata */
+    metadata: DocumentMetadata;
+}
+/**
+ * Vector storage class using LanceDB
+ *
+ * Responsibilities:
+ * - LanceDB operations (insert, delete, search)
+ * - Transaction handling (atomicity of delete→insert)
+ * - Metadata management
+ *
+ * FTS Circuit Breaker:
+ * - Tracks FTS failures (max 3 before disabling)
+ * - Auto-recovers after 5-minute cooldown
+ * - Prevents permanent FTS disable from transient errors
+ */
+export declare class VectorStore {
+    private db;
+    private table;
+    private readonly config;
+    private ftsEnabled;
+    private ftsFailureCount;
+    private ftsLastFailure;
+    /** Mutex to prevent race conditions in circuit breaker state transitions */
+    private circuitBreakerResetting;
+    constructor(config: VectorStoreConfig);
+    /**
+     * Check if FTS should be attempted (circuit breaker logic)
+     * - Returns false if max failures reached and cooldown not elapsed
+     * - Resets failure count after successful cooldown period
+     * - Uses mutex to prevent race conditions during reset
+     */
+    private shouldAttemptFts;
+    /**
+     * Record FTS failure (circuit breaker)
+     */
+    private recordFtsFailure;
+    /**
+     * Record FTS success (resets circuit breaker)
+     */
+    private recordFtsSuccess;
+    /**
+     * Initialize LanceDB and create table
+     */
+    initialize(): Promise<void>;
+    /**
+     * Delete all chunks for specified file path
+     *
+     * @param filePath - File path (absolute)
+     */
+    deleteChunks(filePath: string): Promise<void>;
+    /**
+     * Batch insert vector chunks
+     *
+     * @param chunks - Array of vector chunks
+     */
+    insertChunks(chunks: VectorChunk[]): Promise<void>;
+    /**
+     * Ensure FTS index exists for hybrid search
+     * Creates ngram-based index if it doesn't exist, drops old versions
+     * @throws DatabaseError if index creation fails (Fail-Fast principle)
+     */
+    private ensureFtsIndex;
+    /**
+     * Rebuild FTS index after data changes (insert/delete)
+     * LanceDB OSS requires explicit optimize() call to update FTS index
+     * Also cleans up old index versions to prevent storage bloat
+     */
+    private rebuildFtsIndex;
+    /**
+     * Apply grouping algorithm to filter results by detecting group boundaries.
+     *
+     * Uses statistical threshold (mean + k*std) to identify significant gaps (group boundaries).
+     * - 'similar': Returns only the first group (cuts at first boundary)
+     * - 'related': Returns up to 2 groups (cuts at second boundary)
+     *
+     * @param results - Search results sorted by distance (ascending)
+     * @param mode - Grouping mode ('similar' = 1 group, 'related' = 2 groups)
+     * @returns Filtered results
+     */
+    private applyGrouping;
+    /**
+     * Execute vector search with quality filtering
+     * Architecture: Semantic search → Filter (maxDistance, grouping) → Keyword boost
+     *
+     * This "prefetch then rerank" approach ensures:
+     * - maxDistance and grouping work on meaningful vector distances
+     * - Keyword matching acts as a boost, not a replacement for semantic similarity
+     *
+     * @param queryVector - Query vector (dimension depends on model)
+     * @param queryText - Optional query text for keyword boost (BM25)
+     * @param limit - Number of results to retrieve (default 10)
+     * @returns Array of search results (sorted by distance ascending, filtered by quality settings)
+     */
+    search(queryVector: number[], queryText?: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Apply keyword boost to rerank vector search results
+     * Uses multiplicative formula: final_distance = distance / (1 + keyword_normalized * weight)
+     *
+     * This proportional boost ensures:
+     * - Keyword matches improve ranking without dominating semantic similarity
+     * - Documents without keyword matches keep their original vector distance
+     * - Higher weight = stronger influence of keyword matching
+     *
+     * @param vectorResults - Results from vector search (already filtered by maxDistance/grouping)
+     * @param ftsResults - Raw FTS results with BM25 scores
+     * @param weight - Boost weight (0-1, from hybridWeight config)
+     */
+    private applyKeywordBoost;
+    /**
+     * Get list of ingested files
+     *
+     * @returns Array of file information
+     */
+    listFiles(): Promise<{
+        filePath: string;
+        chunkCount: number;
+        timestamp: string;
+    }[]>;
+    /**
+     * Close the database connection and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Get system status
+     *
+     * @returns System status information
+     */
+    getStatus(): Promise<{
+        documentCount: number;
+        chunkCount: number;
+        memoryUsage: number;
+        uptime: number;
+        ftsIndexEnabled: boolean;
+        searchMode: 'hybrid' | 'vector-only';
+    }>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/vectordb/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectordb/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAqElD;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,CAAA;AAEhD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qDAAqD;IACrD,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,eAAe;IACf,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,kBAAkB;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,eAAe;IACf,QAAQ,EAAE,gBAAgB,CAAA;CAC3B;AAkED;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,cAAc,CAAsB;IAC5C,4EAA4E;IAC5E,OAAO,CAAC,uBAAuB,CAAQ;gBAE3B,MAAM,EAAE,iBAAiB;IAIrC;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IA0BxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAcxB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2BjC;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkDnD;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiCxD;;;;OAIG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,eAAe;IAY7B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,aAAa;IA2CrB;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAqE5F;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iBAAiB;IA0CzB;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAyCzF;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC;QACzB,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,eAAe,EAAE,OAAO,CAAA;QACxB,UAAU,EAAE,QAAQ,GAAG,aAAa,CAAA;KACrC,CAAC;CA2CH"}