rag-lite-ts 2.2.0 → 2.3.1

package/dist/cjs/cli.js

@@ -6,8 +6,18 @@ import { EXIT_CODES, ConfigurationError } from './core/config.js';
 // Get package.json for version info
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJsonPath = join(__dirname, '..', 'package.json');
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+// When built, CLI is at dist/esm/cli.js, so go up two levels to root
+// When running from source, CLI is at src/cli.ts, so go up one level to root
+const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+let packageJson;
+try {
+    packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+}
+catch {
+    // Fallback: try one level up (for source execution)
+    const fallbackPath = join(__dirname, '..', 'package.json');
+    packageJson = JSON.parse(readFileSync(fallbackPath, 'utf-8'));
+}
 /**
  * Display version information
  */
@@ -28,6 +38,7 @@ Usage:
 Commands:
   ingest <path>     Ingest documents from file or directory
   search <query>    Search indexed documents (text or image)
+  ui                Launch the web interface
   rebuild           Rebuild the vector index
   version           Show version information
   help              Show this help message
@@ -43,6 +54,8 @@ Examples:
   raglite search "red car" --content-type image  # Search only image results
   raglite search ./photo.jpg       # Search with image (multimodal mode only)
   raglite search ./image.png --top-k 5  # Find similar images
+  raglite search "How does auth work?" --generate  # [EXPERIMENTAL] Generate AI response
+  raglite ui                       # Launch web interface
 
   raglite rebuild                  # Rebuild the entire index
 
@@ -52,10 +65,17 @@ Options for search:
   --no-rerank           Disable reranking
   --content-type <type> Filter results by content type: 'text', 'image', or 'all' (default: all)
 
+  [EXPERIMENTAL] AI Response Generation (text mode only):
+  --generate            Generate an AI response from search results
+  --generator <model>   Generator model to use (default: SmolLM2-135M-Instruct)
+  --max-tokens <n>      Maximum tokens to generate (default: 512)
+  --temperature <n>     Sampling temperature 0-1 (default: 0.1)
+  --max-chunks <n>      Maximum chunks for context (default: 3 for 135M, 5 for 360M)
+
 Options for ingest:
   --model <name>       Use specific embedding model
   --mode <mode>        Processing mode: 'text' (default) or 'multimodal'
-  --rebuild-if-needed  Automatically rebuild if model mismatch detected (WARNING: rebuilds entire index)
+  --force-rebuild      Wipe DB+index and rebuild from scratch (DESTRUCTIVE)
   --path-strategy <strategy>  Path storage strategy: 'relative' (default) or 'absolute'
   --path-base <path>   Base directory for relative paths (defaults to current directory)
 
@@ -71,6 +91,12 @@ Available reranking strategies (multimodal mode):
   text-derived  Use image-to-text conversion + cross-encoder (default)
   disabled      No reranking, use vector similarity only
 
+[EXPERIMENTAL] Available generator models:
+  HuggingFaceTB/SmolLM2-135M-Instruct  (balanced, recommended default, uses top 3 chunks)
+  HuggingFaceTB/SmolLM2-360M-Instruct  (higher quality, slower, uses top 5 chunks)
+  
+  Note: Generation requires reranking (--rerank is automatically enabled with --generate)
+
 For more information, visit: https://github.com/your-repo/rag-lite-ts
 `);
 }
@@ -111,8 +137,12 @@ function parseArgs() {
             else if (optionName === 'no-rerank') {
                 options.rerank = false;
             }
-            else if (optionName === 'rebuild-if-needed') {
-                options.rebuildIfNeeded = true;
+            else if (optionName === 'force-rebuild') {
+                options.forceRebuild = true;
+            }
+            else if (optionName === 'generate') {
+                // Handle --generate flag for experimental response generation
+                options.generate = true;
             }
             else if (optionName === 'help') {
                 return { command: 'help', args: [], options: {} };
@@ -124,7 +154,16 @@ function parseArgs() {
                 // Handle options with values
                 const nextArg = args[i + 1];
                 if (nextArg && !nextArg.startsWith('--')) {
-                    options[optionName] = nextArg;
+                    // Parse numeric values for specific options
+                    if (optionName === 'max-tokens' || optionName === 'top-k' || optionName === 'max-chunks') {
+                        options[optionName] = parseInt(nextArg, 10);
+                    }
+                    else if (optionName === 'temperature') {
+                        options[optionName] = parseFloat(nextArg);
+                    }
+                    else {
+                        options[optionName] = nextArg;
+                    }
                     i++; // Skip the next argument as it's the value
                 }
                 else {
@@ -169,7 +208,7 @@ function validateArgs(command, args, options) {
                 console.error('Options:');
                 console.error('  --model <name>         Use specific embedding model');
                 console.error('  --mode <mode>          Processing mode: text (default) or multimodal');
-                console.error('  --rebuild-if-needed    Automatically rebuild if model mismatch detected');
+                console.error('  --force-rebuild        Wipe DB+index and rebuild from scratch (DESTRUCTIVE)');
                 console.error('');
                 console.error('The path can be either a file (.md or .txt) or a directory.');
                 process.exit(EXIT_CODES.INVALID_ARGUMENTS);
@@ -201,6 +240,9 @@ function validateArgs(command, args, options) {
         case 'rebuild':
             // No arguments required
             break;
+        case 'ui':
+            // No arguments required
+            break;
         case 'version':
             // No validation needed
             break;
@@ -412,6 +454,10 @@ async function main() {
                 const { runRebuild } = await import('./cli/indexer.js');
                 await runRebuild();
                 break;
+            case 'ui':
+                const { runUI } = await import('./cli/ui-server.js');
+                await runUI(options);
+                break;
             default:
                 console.error(`Error: Unknown command '${command}'`);
                 process.exit(1);

package/dist/cjs/core/abstract-generator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CORE MODULE — Abstract Base Generator
+ *
+ * Provides model-agnostic base functionality for all generator implementations.
+ * This is an abstract base class, not a concrete implementation.
+ *
+ * ARCHITECTURAL NOTE:
+ * Similar to BaseUniversalEmbedder, this class provides shared infrastructure:
+ * - Model lifecycle management (loading, cleanup, disposal)
+ * - Token budget management
+ * - Error handling with helpful messages
+ * - Common utility methods
+ *
+ * IMPLEMENTATION LAYERS:
+ * - Text: InstructGenerator extends this class (SmolLM2-Instruct)
+ * - Text: CausalLMGenerator extends this class (DistilGPT2)
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import type { ResponseGenerator, GeneratorModelInfo, GeneratorModelType, GenerationRequest, GenerationResult, GeneratorCreationOptions } from './response-generator.js';
+import { GenerationError } from './response-generator.js';
+/**
+ * Abstract base class for response generators
+ * Provides common functionality and lifecycle management
+ */
+export declare abstract class BaseResponseGenerator implements ResponseGenerator {
+    readonly modelName: string;
+    protected _isLoaded: boolean;
+    protected _modelInfo: GeneratorModelInfo;
+    protected _options: GeneratorCreationOptions;
+    constructor(modelName: string, options?: GeneratorCreationOptions);
+    get modelType(): GeneratorModelType;
+    get maxContextLength(): number;
+    get maxOutputLength(): number;
+    isLoaded(): boolean;
+    getModelInfo(): GeneratorModelInfo;
+    /**
+     * Load the model - must be implemented by subclasses
+     */
+    abstract loadModel(): Promise<void>;
+    /**
+     * Generate text using the model - must be implemented by subclasses
+     * @param prompt - The formatted prompt string
+     * @param options - Generation options
+     * @returns Generated text
+     */
+    protected abstract generateText(prompt: string, options: {
+        maxTokens: number;
+        temperature: number;
+        topP: number;
+        topK: number;
+        repetitionPenalty: number;
+        stopSequences: string[];
+    }): Promise<{
+        text: string;
+        promptTokens: number;
+        completionTokens: number;
+        finishReason: 'complete' | 'length' | 'stop_sequence' | 'error';
+    }>;
+    /**
+     * Clean up resources - must be implemented by subclasses
+     */
+    abstract cleanup(): Promise<void>;
+    /**
+     * Generate a response based on query and retrieved chunks
+     * This method orchestrates the generation pipeline
+     */
+    generate(request: GenerationRequest): Promise<GenerationResult>;
+    /**
+     * Validate that the model is loaded before operations
+     */
+    protected ensureLoaded(): void;
+    /**
+     * Clean up response text by removing artifacts
+     */
+    protected cleanResponseText(text: string): string;
+    /**
+     * Log model loading progress
+     */
+    protected logModelLoading(stage: string, details?: string): void;
+    /**
+     * Handle model loading errors with helpful messages
+     */
+    protected handleLoadingError(error: Error): GenerationError;
+}
+/**
+ * Extended options for generator instances
+ */
+export interface GeneratorOptions extends GeneratorCreationOptions {
+    /** Log level for debugging */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+/**
+ * Create generator options with defaults
+ */
+export declare function createGeneratorOptions(options?: Partial<GeneratorOptions>): GeneratorOptions;
+//# sourceMappingURL=abstract-generator.d.ts.map

package/dist/cjs/core/abstract-generator.js

@@ -0,0 +1,222 @@
+/**
+ * CORE MODULE — Abstract Base Generator
+ *
+ * Provides model-agnostic base functionality for all generator implementations.
+ * This is an abstract base class, not a concrete implementation.
+ *
+ * ARCHITECTURAL NOTE:
+ * Similar to BaseUniversalEmbedder, this class provides shared infrastructure:
+ * - Model lifecycle management (loading, cleanup, disposal)
+ * - Token budget management
+ * - Error handling with helpful messages
+ * - Common utility methods
+ *
+ * IMPLEMENTATION LAYERS:
+ * - Text: InstructGenerator extends this class (SmolLM2-Instruct)
+ * - Text: CausalLMGenerator extends this class (DistilGPT2)
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import { GenerationError } from './response-generator.js';
+import { GeneratorRegistry } from './generator-registry.js';
+import { buildPrompt, getDefaultStopSequences } from './prompt-templates.js';
+// =============================================================================
+// BASE GENERATOR ABSTRACT CLASS
+// =============================================================================
+/**
+ * Abstract base class for response generators
+ * Provides common functionality and lifecycle management
+ */
+export class BaseResponseGenerator {
+    modelName;
+    _isLoaded = false;
+    _modelInfo;
+    _options;
+    constructor(modelName, options = {}) {
+        this.modelName = modelName;
+        const modelInfo = GeneratorRegistry.getGeneratorInfo(modelName);
+        if (!modelInfo) {
+            throw new Error(`Generator model '${modelName}' is not supported. ` +
+                `Supported models: ${GeneratorRegistry.getSupportedGenerators().join(', ')}`);
+        }
+        this._modelInfo = modelInfo;
+        this._options = options;
+    }
+    // =============================================================================
+    // PUBLIC INTERFACE IMPLEMENTATION
+    // =============================================================================
+    get modelType() {
+        return this._modelInfo.type;
+    }
+    get maxContextLength() {
+        return this._modelInfo.capabilities.maxContextLength;
+    }
+    get maxOutputLength() {
+        return this._modelInfo.capabilities.defaultMaxOutputTokens;
+    }
+    isLoaded() {
+        return this._isLoaded;
+    }
+    getModelInfo() {
+        return { ...this._modelInfo }; // Return a copy to prevent mutation
+    }
+    // =============================================================================
+    // DEFAULT IMPLEMENTATION
+    // =============================================================================
+    /**
+     * Generate a response based on query and retrieved chunks
+     * This method orchestrates the generation pipeline
+     */
+    async generate(request) {
+        if (!this._isLoaded) {
+            await this.loadModel();
+        }
+        const startTime = Date.now();
+        try {
+            // Get generation parameters with defaults
+            const maxTokens = request.maxTokens ?? this._modelInfo.capabilities.defaultMaxOutputTokens;
+            const temperature = request.temperature ?? this._modelInfo.capabilities.recommendedTemperature;
+            const topP = request.topP ?? 0.9;
+            const topK = request.topK ?? 50;
+            const repetitionPenalty = request.repetitionPenalty ?? 1.1;
+            const stopSequences = request.stopSequences ?? getDefaultStopSequences(this.modelType);
+            // Get max chunks for context (configurable, with model-specific default)
+            const maxChunksForContext = request.maxChunksForContext ??
+                this._modelInfo.capabilities.defaultMaxChunksForContext;
+            // Limit chunks to maxChunksForContext (assumes chunks are already reranked)
+            const totalChunks = request.chunks.length;
+            const limitedChunks = request.chunks.slice(0, maxChunksForContext);
+            if (totalChunks > maxChunksForContext) {
+                console.log(`📊 Using top ${maxChunksForContext} of ${totalChunks} reranked chunks for generation`);
+            }
+            // Build the prompt with context
+            const builtPrompt = buildPrompt({
+                query: request.query,
+                chunks: limitedChunks,
+                modelType: this.modelType,
+                systemPrompt: request.systemPrompt,
+                maxContextLength: this.maxContextLength,
+                reservedOutputTokens: maxTokens,
+                includeSourceAttribution: request.includeSourceAttribution
+            });
+            // Log context info
+            if (builtPrompt.contextInfo.truncated) {
+                console.warn(`⚠️  Context truncated: Only ${builtPrompt.contextInfo.chunksIncluded} of ` +
+                    `${builtPrompt.contextInfo.totalChunks} chunks fit in context window`);
+            }
+            // Generate response
+            const result = await this.generateText(builtPrompt.prompt, {
+                maxTokens,
+                temperature,
+                topP,
+                topK,
+                repetitionPenalty,
+                stopSequences
+            });
+            const generationTimeMs = Date.now() - startTime;
+            // Clean up the response text
+            const cleanedResponse = this.cleanResponseText(result.text);
+            return {
+                response: cleanedResponse,
+                tokensUsed: result.promptTokens + result.completionTokens,
+                truncated: builtPrompt.contextInfo.truncated,
+                modelName: this.modelName,
+                generationTimeMs,
+                metadata: {
+                    promptTokens: result.promptTokens,
+                    completionTokens: result.completionTokens,
+                    chunksIncluded: builtPrompt.contextInfo.chunksIncluded,
+                    totalChunks: totalChunks, // Report original total, not limited
+                    finishReason: result.finishReason
+                }
+            };
+        }
+        catch (error) {
+            const generationTimeMs = Date.now() - startTime;
+            if (error instanceof GenerationError) {
+                throw error;
+            }
+            throw new GenerationError(this.modelName, 'generation', `Generation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    // =============================================================================
+    // PROTECTED HELPER METHODS
+    // =============================================================================
+    /**
+     * Validate that the model is loaded before operations
+     */
+    ensureLoaded() {
+        if (!this._isLoaded) {
+            throw new GenerationError(this.modelName, 'generation', `Model '${this.modelName}' is not loaded. Call loadModel() first.`);
+        }
+    }
+    /**
+     * Clean up response text by removing artifacts
+     */
+    cleanResponseText(text) {
+        let cleaned = text.trim();
+        // Remove common artifacts
+        const artifactsToRemove = [
+            '<|im_end|>',
+            '<|im_start|>',
+            '<|endoftext|>',
+            '<|assistant|>',
+            '<|user|>',
+            '<|system|>'
+        ];
+        for (const artifact of artifactsToRemove) {
+            cleaned = cleaned.split(artifact)[0];
+        }
+        // Remove trailing incomplete sentences (if cut off at max tokens)
+        if (cleaned.length > 0 && !cleaned.match(/[.!?]$/)) {
+            const lastSentenceEnd = Math.max(cleaned.lastIndexOf('.'), cleaned.lastIndexOf('!'), cleaned.lastIndexOf('?'));
+            if (lastSentenceEnd > cleaned.length * 0.5) {
+                cleaned = cleaned.substring(0, lastSentenceEnd + 1);
+            }
+        }
+        return cleaned.trim();
+    }
+    /**
+     * Log model loading progress
+     */
+    logModelLoading(stage, details) {
+        const message = `[${this.modelName}] ${stage}`;
+        if (details) {
+            console.log(`${message}: ${details}`);
+        }
+        else {
+            console.log(message);
+        }
+    }
+    /**
+     * Handle model loading errors with helpful messages
+     */
+    handleLoadingError(error) {
+        const baseMessage = `Failed to load generator model '${this.modelName}': ${error.message}`;
+        // Provide specific guidance based on error type
+        if (error.message.includes('network') || error.message.includes('fetch')) {
+            return new GenerationError(this.modelName, 'loading', `${baseMessage}\n` +
+                `This appears to be a network error. Please check your internet connection ` +
+                `and ensure the model repository is accessible.`, error);
+        }
+        if (error.message.includes('memory') || error.message.includes('OOM')) {
+            return new GenerationError(this.modelName, 'loading', `${baseMessage}\n` +
+                `This appears to be a memory error. The model requires ` +
+                `${this._modelInfo.requirements.minimumMemory}MB. Try closing other applications ` +
+                `or using a smaller model like 'Xenova/distilgpt2'.`, error);
+        }
+        return new GenerationError(this.modelName, 'loading', baseMessage, error);
+    }
+}
+/**
+ * Create generator options with defaults
+ */
+export function createGeneratorOptions(options = {}) {
+    return {
+        timeout: 60000, // 60 seconds
+        enableGPU: false,
+        logLevel: 'info',
+        ...options
+    };
+}
+//# sourceMappingURL=abstract-generator.js.map

package/dist/cjs/core/binary-index-format.js

@@ -27,10 +27,12 @@ export class BinaryIndexFormat {
      * @param data Index data to serialize
      */
     static async save(indexPath, data) {
-        // Calculate total size
+        // Use actual vector count to ensure accurate file size
+        const actualVectorCount = data.vectors.length;
+        // Calculate total size based on actual vectors
         const headerSize = 24; // 6 uint32 fields
         const vectorSize = 4 + (data.dimensions * 4); // id + vector
-        const totalSize = headerSize + (data.currentSize * vectorSize);
+        const totalSize = headerSize + (actualVectorCount * vectorSize);
         const buffer = new ArrayBuffer(totalSize);
         const view = new DataView(buffer);
         let offset = 0;
@@ -45,7 +47,8 @@ export class BinaryIndexFormat {
         offset += 4;
         view.setUint32(offset, data.seed, true);
         offset += 4;
-        view.setUint32(offset, data.currentSize, true);
+        // Write actual vector count in header
+        view.setUint32(offset, actualVectorCount, true);
         offset += 4;
         // Write vectors
         for (const item of data.vectors) {
@@ -187,6 +190,9 @@ export class BinaryIndexFormat {
         const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
         let offset = 0;
         // Read basic header (24 bytes, all little-endian)
+        if (buffer.byteLength < 24) {
+            throw new Error(`Index file too small: expected at least 24 bytes, got ${buffer.byteLength}`);
+        }
         const dimensions = view.getUint32(offset, true);
         offset += 4;
         const maxElements = view.getUint32(offset, true);
@@ -199,10 +205,20 @@ export class BinaryIndexFormat {
         offset += 4;
         const currentSize = view.getUint32(offset, true);
         offset += 4;
-        // Check if this is the extended grouped format (40+ bytes header)
-        const hasGroups = buffer.byteLength >= 40 ? view.getUint32(offset, true) : 0;
-        if (hasGroups === 1 && buffer.byteLength >= 40) {
-            // Load grouped format
+        // Calculate expected size for original format
+        const vectorSize = 4 + (dimensions * 4); // id + vector
+        const expectedOriginalSize = 24 + (currentSize * vectorSize);
+        // Check if this is the extended grouped format (44 bytes header)
+        // Extended header has: 24 bytes basic + 4 bytes hasGroups + 16 bytes for offsets/counts = 44 bytes
+        // Only check for grouped format if file is larger than expected original format size
+        const hasGroups = buffer.byteLength > expectedOriginalSize && buffer.byteLength >= 44 && offset + 4 <= buffer.byteLength
+            ? view.getUint32(offset, true)
+            : 0;
+        if (hasGroups === 1 && buffer.byteLength >= 44) {
+            // Load grouped format - ensure we have enough bytes for extended header
+            if (offset + 20 > buffer.byteLength) {
+                throw new Error(`Index file too small for grouped format: expected at least ${offset + 20} bytes, got ${buffer.byteLength}`);
+            }
             const textOffset = view.getUint32(offset + 4, true);
             const textCount = view.getUint32(offset + 8, true);
             const imageOffset = view.getUint32(offset + 12, true);
@@ -215,14 +231,23 @@ export class BinaryIndexFormat {
                 if (offset % 4 !== 0) {
                     throw new Error(`Offset ${offset} is not 4-byte aligned`);
                 }
+                // Check bounds before reading vector ID
+                if (offset + 4 > buffer.byteLength) {
+                    throw new Error(`Text vector ID at offset ${offset} is outside the bounds of the DataView (buffer size: ${buffer.byteLength})`);
+                }
                 // Read vector ID
                 const id = view.getUint32(offset, true);
                 offset += 4;
+                // Check bounds before reading vector data
+                const vectorDataSize = dimensions * 4;
+                if (offset + vectorDataSize > buffer.byteLength) {
+                    throw new Error(`Text vector data at offset ${offset} would exceed buffer bounds (buffer size: ${buffer.byteLength}, required: ${offset + vectorDataSize})`);
+                }
                 // Zero-copy Float32Array view
                 const vectorView = new Float32Array(buffer.buffer, buffer.byteOffset + offset, dimensions);
                 // Copy to avoid buffer lifecycle issues
                 const vector = new Float32Array(vectorView);
-                offset += dimensions * 4;
+                offset += vectorDataSize;
                 textVectors.push({ id, vector });
             }
             // Load image vectors
@@ -233,14 +258,23 @@ export class BinaryIndexFormat {
                 if (offset % 4 !== 0) {
                     throw new Error(`Offset ${offset} is not 4-byte aligned`);
                 }
+                // Check bounds before reading vector ID
+                if (offset + 4 > buffer.byteLength) {
+                    throw new Error(`Image vector ID at offset ${offset} is outside the bounds of the DataView (buffer size: ${buffer.byteLength})`);
+                }
                 // Read vector ID
                 const id = view.getUint32(offset, true);
                 offset += 4;
+                // Check bounds before reading vector data
+                const vectorDataSize = dimensions * 4;
+                if (offset + vectorDataSize > buffer.byteLength) {
+                    throw new Error(`Image vector data at offset ${offset} would exceed buffer bounds (buffer size: ${buffer.byteLength}, required: ${offset + vectorDataSize})`);
+                }
                 // Zero-copy Float32Array view
                 const vectorView = new Float32Array(buffer.buffer, buffer.byteOffset + offset, dimensions);
                 // Copy to avoid buffer lifecycle issues
                 const vector = new Float32Array(vectorView);
-                offset += dimensions * 4;
+                offset += vectorDataSize;
                 imageVectors.push({ id, vector });
             }
             // Combine all vectors for backward compatibility
@@ -266,14 +300,23 @@ export class BinaryIndexFormat {
                 if (offset % 4 !== 0) {
                     throw new Error(`Offset ${offset} is not 4-byte aligned`);
                 }
+                // Check bounds before reading vector ID
+                if (offset + 4 > buffer.byteLength) {
+                    throw new Error(`Offset ${offset} is outside the bounds of the DataView (buffer size: ${buffer.byteLength})`);
+                }
                 // Read vector ID
                 const id = view.getUint32(offset, true);
                 offset += 4;
+                // Check bounds before reading vector data
+                const vectorDataSize = dimensions * 4;
+                if (offset + vectorDataSize > buffer.byteLength) {
+                    throw new Error(`Vector data at offset ${offset} would exceed buffer bounds (buffer size: ${buffer.byteLength}, required: ${offset + vectorDataSize})`);
+                }
                 // Zero-copy Float32Array view (fast!)
                 const vectorView = new Float32Array(buffer.buffer, buffer.byteOffset + offset, dimensions);
                 // Copy to avoid buffer lifecycle issues
                 const vector = new Float32Array(vectorView);
-                offset += dimensions * 4;
+                offset += vectorDataSize;
                 vectors.push({ id, vector });
             }
             return {

package/dist/cjs/core/db.d.ts

@@ -210,4 +210,60 @@ export declare function updateStorageStats(connection: DatabaseConnection, stats
     filesystemRefs?: number;
     lastCleanup?: Date;
 }): Promise<void>;
+/**
+ * Result of a database reset operation
+ */
+export interface DatabaseResetResult {
+    /** Whether the reset was successful */
+    success: boolean;
+    /** Number of documents deleted */
+    documentsDeleted: number;
+    /** Number of chunks deleted */
+    chunksDeleted: number;
+    /** Number of content metadata entries deleted */
+    contentMetadataDeleted: number;
+    /** Whether system_info was preserved or cleared */
+    systemInfoCleared: boolean;
+    /** Time taken for the reset operation in milliseconds */
+    resetTimeMs: number;
+}
+/**
+ * Options for database reset operation
+ */
+export interface DatabaseResetOptions {
+    /** Whether to preserve system_info (mode, model configuration) - default: false */
+    preserveSystemInfo?: boolean;
+    /** Whether to run VACUUM after deletion to reclaim space - default: true */
+    runVacuum?: boolean;
+}
+/**
+ * Reset the database by deleting all data while keeping the schema intact.
+ * This is a safer alternative to file deletion that avoids file locking issues on Windows.
+ *
+ * This function:
+ * 1. Deletes all rows from chunks, documents, content_metadata tables
+ * 2. Optionally clears system_info (mode/model configuration)
+ * 3. Resets storage_stats counters
+ * 4. Optionally runs VACUUM to reclaim disk space
+ *
+ * @param connection - Database connection object
+ * @param options - Reset options
+ * @returns Promise resolving to reset result statistics
+ *
+ * @example
+ * ```typescript
+ * const db = await openDatabase('./db.sqlite');
+ * const result = await resetDatabase(db, { preserveSystemInfo: false });
+ * console.log(`Deleted ${result.documentsDeleted} documents and ${result.chunksDeleted} chunks`);
+ * ```
+ */
+export declare function resetDatabase(connection: DatabaseConnection, options?: DatabaseResetOptions): Promise<DatabaseResetResult>;
+/**
+ * Check if the database has any data (documents, chunks, or content)
+ * Useful for determining if a reset is needed
+ *
+ * @param connection - Database connection object
+ * @returns Promise resolving to true if database has data, false if empty
+ */
+export declare function hasDatabaseData(connection: DatabaseConnection): Promise<boolean>;
 //# sourceMappingURL=db.d.ts.map