rag-lite-ts 1.0.2 → 2.0.0

package/dist/factories/text-factory.js

@@ -5,10 +5,21 @@
  * FACTORY PATTERN BENEFITS:
  * - Abstracts complex initialization (model loading, database setup, index initialization)
  * - Provides simple API for common use cases while preserving access to dependency injection
- * - Handles error recovery and validation
+ * - Clear validation and error handling without fallback mechanisms
  * - Supports different embedding models and configurations
  * - Enables clean separation between simple usage and advanced customization
  *
+ * MODE SELECTION GUIDE:
+ * - Text Mode (default): Optimized for text-only content
+ *   - Uses sentence-transformer models (fast, accurate for text)
+ *   - Images converted to text descriptions
+ *   - Best for: document search, text clustering, semantic similarity
+ *
+ * - Multimodal Mode: Optimized for mixed text/image content
+ *   - Uses CLIP models (unified embedding space)
+ *   - True cross-modal search (text finds images, images find text)
+ *   - Best for: image search, visual QA, multimodal retrieval
+ *
  * USAGE PATTERNS:
  *
  * 1. Simple Search Setup:
@@ -43,15 +54,31 @@
  * const results = await searchEngine.search('query');
  * ```
  *
- * 4. Error Recovery:
+ * 4. Clear Error Handling:
  * ```typescript
- * // Create with automatic fallback options
- * const search = await TextFactoryHelpers.createSearchWithFallback(
+ * // Create with clear validation and error reporting
+ * const search = await TextFactoryHelpers.createSearchWithValidation(
  *   './index.bin',
  *   './db.sqlite',
- *   { enableReranking: true } // Will fallback to disabled if reranking fails
+ *   { enableReranking: true } // Clear errors if issues occur
  * );
  * ```
+ *
+ * 5. Mode Selection:
+ * ```typescript
+ * // Text mode (default) - optimized for text-only content
+ * const textIngestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', {
+ *   mode: 'text',
+ *   embeddingModel: 'sentence-transformers/all-MiniLM-L6-v2'
+ * });
+ *
+ * // Multimodal mode - enables cross-modal search
+ * const multimodalIngestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', {
+ *   mode: 'multimodal',
+ *   embeddingModel: 'Xenova/clip-vit-base-patch32',
+ *   rerankingStrategy: 'text-derived'
+ * });
+ * ```
  */
 import { SearchEngine } from '../core/search.js';
 import { IngestionPipeline } from '../core/ingestion.js';
@@ -63,16 +90,26 @@ import { config, getModelDefaults } from '../core/config.js';
 import { existsSync } from 'fs';
 import { dirname } from 'path';
 import { mkdirSync } from 'fs';
+import { ContentManager } from '../core/content-manager.js';
+import { validateModeModelCompatibilityOrThrow } from '../core/mode-model-validator.js';
+import { createMissingFileError, createInvalidPathError, createFactoryCreationError, createModeMismatchError } from '../core/actionable-error-messages.js';
 /**
  * Factory for creating text-based SearchEngine instances
  * Handles model loading, database initialization, and index setup
  *
  * This factory abstracts the complex initialization process required for text search:
- * 1. Loads and validates text embedding models
- * 2. Optionally loads reranking models with fallback handling
- * 3. Establishes database connections and initializes schema
- * 4. Loads vector indexes with proper model compatibility checking
- * 5. Creates SearchEngine with proper dependency injection
+ * 1. Auto-detects embedding model from database configuration
+ * 2. Validates mode-model compatibility (no fallback mechanisms)
+ * 3. Loads embedding models with clear error reporting
+ * 4. Optionally loads reranking models based on configuration
+ * 5. Establishes database connections and initializes schema
+ * 6. Loads vector indexes with proper model compatibility checking
+ * 7. Creates SearchEngine with proper dependency injection
+ *
+ * Mode Support:
+ * - Automatically detects mode from database (text or multimodal)
+ * - Each mode uses its optimal implementation without fallbacks
+ * - Clear validation ensures mode-model compatibility
  *
  * @example
  * ```typescript
@@ -100,7 +137,7 @@ export class TextSearchFactory {
      * This method handles the complete initialization process:
      * - Validates that required files exist
      * - Loads text embedding model (with lazy initialization)
-     * - Optionally loads reranking model (with graceful fallback)
+     * - Optionally loads reranking model (with clear error reporting)
      * - Opens database connection and initializes schema
      * - Loads vector index with compatibility validation
      * - Creates SearchEngine with dependency injection
@@ -135,18 +172,21 @@ export class TextSearchFactory {
             console.log('🏭 TextSearchFactory: Initializing text search engine...');
             // Validate input paths
             if (!indexPath || !dbPath) {
-                throw new Error('Both indexPath and dbPath are required');
+                throw createInvalidPathError([
+                    { name: 'indexPath', value: indexPath },
+                    { name: 'dbPath', value: dbPath }
+                ], { operationContext: 'TextSearchFactory.create' });
             }
             // Check if required files exist
             if (!existsSync(indexPath)) {
-                throw new Error(`Vector index not found at: ${indexPath}\n` +
-                    'Run ingestion first to create the index, or check the path.\n' +
-                    'Example: const ingestion = await IngestionFactory.create(dbPath, indexPath);');
+                throw createMissingFileError(indexPath, 'index', {
+                    operationContext: 'TextSearchFactory.create'
+                });
             }
             if (!existsSync(dbPath)) {
-                throw new Error(`Database not found at: ${dbPath}\n` +
-                    'Run ingestion first to create the database, or check the path.\n' +
-                    'Example: const ingestion = await IngestionFactory.create(dbPath, indexPath);');
+                throw createMissingFileError(dbPath, 'database', {
+                    operationContext: 'TextSearchFactory.create'
+                });
             }
             // Step 1: Auto-detect embedding model from database
             let embeddingModel = options.embeddingModel;
@@ -180,6 +220,10 @@ export class TextSearchFactory {
                 modelDimensions = modelDefaults.dimensions;
                 console.log(`📊 Using specified embedding model: ${embeddingModel} (${modelDimensions} dimensions)`);
             }
+            // Step 1.5: Validate mode-model compatibility at creation time
+            console.log('🔍 Validating mode-model compatibility...');
+            validateModeModelCompatibilityOrThrow('text', embeddingModel);
+            console.log('✓ Mode-model compatibility validated');
             // Step 2: Initialize embedding function
             console.log('📊 Loading text embedding model...');
             const embedFn = createTextEmbedFunction(embeddingModel, options.batchSize);
@@ -188,17 +232,11 @@ export class TextSearchFactory {
             // Step 3: Initialize reranking function (optional)
             let rerankFn;
             if (options.enableReranking === true) { // Default to disabled for local-first, fast RAG-lite
-                try {
-                    console.log('🔄 Loading text reranking model...');
-                    rerankFn = createTextRerankFunction(options.rerankingModel);
-                    // Test reranking function
-                    await rerankFn('test query', []);
-                    console.log('✓ Text reranking model loaded successfully');
-                }
-                catch (error) {
-                    console.warn(`Failed to load reranking model, continuing without reranking: ${error instanceof Error ? error.message : 'Unknown error'}`);
-                    rerankFn = undefined;
-                }
+                console.log('🔄 Loading text reranking model...');
+                rerankFn = createTextRerankFunction(options.rerankingModel);
+                // Test reranking function - fail clearly if there are issues
+                await rerankFn('test query', []);
+                console.log('✓ Text reranking model loaded successfully');
             }
             else {
                 console.log('🔄 Reranking disabled by default (local-first, fast mode)');
@@ -215,9 +253,14 @@ export class TextSearchFactory {
             const indexManager = new IndexManager(indexPath, dbPath, modelDimensions, embeddingModel);
             await indexManager.initialize();
             console.log('✓ Vector index loaded successfully');
-            // Step 7: Create SearchEngine with dependency injection
-            const searchEngine = new SearchEngine(embedFn, indexManager, db, rerankFn);
-            // Step 8: Validate the setup
+            // Step 7: Create ContentResolver for unified content system
+            console.log('📁 Initializing content resolver...');
+            const { ContentResolver } = await import('../core/content-resolver.js');
+            const contentResolver = new ContentResolver(db);
+            console.log('✓ Content resolver ready');
+            // Step 8: Create SearchEngine with dependency injection
+            const searchEngine = new SearchEngine(embedFn, indexManager, db, rerankFn, contentResolver);
+            // Step 9: Validate the setup
             const stats = await searchEngine.getStats();
             console.log(`✓ Search engine ready: ${stats.totalChunks} chunks indexed, reranking ${stats.rerankingEnabled ? 'enabled' : 'disabled'}`);
             console.log('🎉 TextSearchFactory: Search engine initialized successfully');
@@ -225,7 +268,7 @@ export class TextSearchFactory {
         }
         catch (error) {
             console.error('❌ TextSearchFactory: Failed to create search engine');
-            throw new Error(`TextSearchFactory.create failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            throw createFactoryCreationError('TextSearchFactory', error instanceof Error ? error.message : 'Unknown error', { operationContext: 'search engine creation' });
         }
     }
     /**
@@ -266,10 +309,18 @@ export class TextSearchFactory {
  *
  * This factory abstracts the complex initialization process required for text ingestion:
  * 1. Creates necessary directories if they don't exist
- * 2. Loads and validates text embedding models
- * 3. Establishes database connections and initializes schema
- * 4. Creates or loads vector indexes with proper configuration
- * 5. Creates IngestionPipeline with proper dependency injection
+ * 2. Validates mode-model compatibility (no fallback mechanisms)
+ * 3. Loads and validates embedding models with clear error reporting
+ * 4. Establishes database connections and initializes schema
+ * 5. Stores mode configuration in database for automatic detection
+ * 6. Creates or loads vector indexes with proper configuration
+ * 7. Creates IngestionPipeline with proper dependency injection
+ *
+ * Mode Configuration:
+ * - Text Mode (default): Uses sentence-transformer models for text-only content
+ * - Multimodal Mode: Uses CLIP models for mixed text/image content
+ * - Mode is stored in database and auto-detected during search
+ * - Clear validation prevents mode-model mismatches
  *
  * @example
  * ```typescript
@@ -311,20 +362,39 @@ export class TextIngestionFactory {
      * @param options.chunkSize - Override chunk size (default: from config)
      * @param options.chunkOverlap - Override chunk overlap (default: from config)
      * @param options.forceRebuild - Force rebuild of existing index (default: false)
+     * @param options.contentSystemConfig - Content system configuration options
+     * @param options.contentSystemConfig.contentDir - Content directory path (default: '.raglite/content')
+     * @param options.contentSystemConfig.maxFileSize - Maximum file size in bytes (default: 50MB)
+     * @param options.contentSystemConfig.maxContentDirSize - Maximum content directory size (default: 2GB)
+     * @param options.contentSystemConfig.enableDeduplication - Enable content deduplication (default: true)
+     * @param options.contentSystemConfig.enableStorageTracking - Enable storage tracking (default: true)
      * @returns Promise resolving to configured IngestionPipeline
      * @throws {Error} If initialization fails
      *
      * @example
      * ```typescript
-     * // Create ingestion pipeline
+     * // Create ingestion pipeline with default content system
      * const ingestion = await TextIngestionFactory.create('./my-db.sqlite', './my-index.bin');
      *
+     * // Create with custom content system configuration
+     * const ingestion = await TextIngestionFactory.create('./my-db.sqlite', './my-index.bin', {
+     *   contentSystemConfig: {
+     *     contentDir: './custom-content',
+     *     maxFileSize: 100 * 1024 * 1024, // 100MB
+     *     maxContentDirSize: 5 * 1024 * 1024 * 1024, // 5GB
+     *     enableDeduplication: true
+     *   }
+     * });
+     *
      * // Ingest documents from directory
      * const result = await ingestion.ingestDirectory('./documents');
      * console.log(`Processed ${result.documentsProcessed} documents`);
      *
-     * // Ingest single file
-     * await ingestion.ingestFile('./document.pdf');
+     * // Ingest content from memory (MCP integration)
+     * const contentId = await ingestion.ingestFromMemory(buffer, {
+     *   displayName: 'uploaded-file.pdf',
+     *   contentType: 'application/pdf'
+     * });
      *
      * // Clean up when done
      * await ingestion.cleanup();
@@ -335,7 +405,10 @@ export class TextIngestionFactory {
             console.log('🏭 TextIngestionFactory: Initializing text ingestion pipeline...');
             // Validate input paths
             if (!dbPath || !indexPath) {
-                throw new Error('Both dbPath and indexPath are required');
+                throw createInvalidPathError([
+                    { name: 'dbPath', value: dbPath },
+                    { name: 'indexPath', value: indexPath }
+                ], { operationContext: 'TextIngestionFactory.create' });
             }
             // Ensure directories exist
             const dbDir = dirname(dbPath);
@@ -353,12 +426,35 @@ export class TextIngestionFactory {
             const effectiveBatchSize = options.batchSize ?? modelDefaults.batch_size;
             const effectiveChunkSize = options.chunkSize ?? modelDefaults.chunk_size;
             const effectiveChunkOverlap = options.chunkOverlap ?? modelDefaults.chunk_overlap;
-            // Step 2: Initialize embedding function
-            console.log('📊 Loading text embedding model...');
-            const embedFn = createTextEmbedFunction(options.embeddingModel, effectiveBatchSize);
-            // Test embedding function to ensure it works
-            // Embedding function created successfully (will be tested on first use)
-            console.log('✓ Text embedding function created successfully');
+            // Step 1.5: Validate mode-model compatibility at creation time
+            const effectiveMode = options.mode || 'text';
+            const effectiveModel = options.embeddingModel || config.embedding_model;
+            console.log('🔍 Validating mode-model compatibility...');
+            validateModeModelCompatibilityOrThrow(effectiveMode, effectiveModel);
+            console.log('✓ Mode-model compatibility validated');
+            // Step 2: Initialize embedding function based on mode
+            let embedFn;
+            if (effectiveMode === 'multimodal') {
+                console.log('📊 Loading CLIP embedding model for multimodal mode...');
+                const { createEmbedder } = await import('../core/embedder-factory.js');
+                const clipEmbedder = await createEmbedder(effectiveModel);
+                // Wrap CLIP embedder to match EmbedFunction signature
+                embedFn = async (content, contentType) => {
+                    if (contentType === 'image') {
+                        // Use CLIP image embedding for image content
+                        return await clipEmbedder.embedImage(content);
+                    }
+                    // Use CLIP text embedding for text content
+                    return await clipEmbedder.embedText(content);
+                };
+                console.log('✓ CLIP embedder created for multimodal mode');
+            }
+            else {
+                // Text mode: use sentence-transformer embedder (existing behavior)
+                console.log('📊 Loading text embedding model...');
+                embedFn = createTextEmbedFunction(options.embeddingModel, effectiveBatchSize);
+                console.log('✓ Text embedding function created successfully');
+            }
             // Step 3: Initialize database connection
             console.log('💾 Opening database connection...');
             const db = await openDatabase(dbPath);
@@ -366,13 +462,17 @@ export class TextIngestionFactory {
             const { initializeSchema } = await import('../core/db.js');
             await initializeSchema(db);
             console.log('✓ Database connection established');
+            // Step 3.1: Handle mode storage during ingestion
+            await this.handleModeStorage(db, options, modelDefaults);
             // Step 4: Initialize index manager
             console.log('📇 Initializing vector index...');
             const indexManager = new IndexManager(indexPath, dbPath, modelDefaults.dimensions, options.embeddingModel || config.embedding_model);
             // Check if we need to force recreation due to model change
             let forceRecreate = false;
             if (options.forceRebuild && existsSync(indexPath) && existsSync(dbPath)) {
-                // Check if model has changed during rebuild
+                // When forceRebuild is true, always force recreation to handle any model/dimension mismatches
+                forceRecreate = true;
+                // Check if model has changed during rebuild for logging purposes
                 const { getStoredModelInfo } = await import('../core/db.js');
                 const tempDb = await openDatabase(dbPath);
                 try {
@@ -381,7 +481,9 @@ export class TextIngestionFactory {
                     if (storedModel && storedModel.modelName !== currentModel) {
                         console.log(`🔄 Model change detected: ${storedModel.modelName} → ${currentModel}`);
                         console.log(`🔄 Dimensions change: ${storedModel.dimensions} → ${modelDefaults.dimensions}`);
-                        forceRecreate = true;
+                    }
+                    else if (storedModel && storedModel.dimensions !== modelDefaults.dimensions) {
+                        console.log(`🔄 Dimension mismatch detected: ${storedModel.dimensions} → ${modelDefaults.dimensions}`);
                     }
                 }
                 finally {
@@ -411,18 +513,30 @@ export class TextIngestionFactory {
                 await indexManager.initialize();
             }
             console.log('✓ Vector index ready');
-            // Step 4: Create IngestionPipeline with dependency injection and chunk configuration
+            // Step 5: Create ContentManager for unified content system
+            console.log('📁 Initializing content management system...');
+            const contentSystemConfig = await this.validateAndPrepareContentSystemConfig(options.contentSystemConfig);
+            const contentManager = new ContentManager(db, contentSystemConfig);
+            console.log('✓ Content management system ready');
+            // Step 6: Create IngestionPipeline with dependency injection and chunk configuration
             const chunkConfig = {
                 chunkSize: effectiveChunkSize,
                 chunkOverlap: effectiveChunkOverlap
             };
-            const ingestionPipeline = new IngestionPipeline(embedFn, indexManager, db, chunkConfig);
+            const ingestionPipeline = new IngestionPipeline(embedFn, indexManager, db, chunkConfig, contentManager);
             console.log('🎉 TextIngestionFactory: Ingestion pipeline initialized successfully');
             return ingestionPipeline;
         }
         catch (error) {
             console.error('❌ TextIngestionFactory: Failed to create ingestion pipeline');
-            throw new Error(`TextIngestionFactory.create failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            // Preserve custom error messages for model mismatch and mode mismatch
+            if (error instanceof Error && (error.message.includes('Model mismatch') ||
+                error.message.includes('Mode mismatch') ||
+                error.message.includes('--force-rebuild') ||
+                error.message.includes('--rebuild-if-needed'))) {
+                throw error; // Re-throw custom validation errors as-is
+            }
+            throw createFactoryCreationError('TextIngestionFactory', error instanceof Error ? error.message : 'Unknown error', { operationContext: 'ingestion pipeline creation' });
         }
     }
     /**
@@ -436,6 +550,164 @@ export class TextIngestionFactory {
         const indexPath = config.index_file || './index.bin';
         return this.create(dbPath, indexPath, options);
     }
+    /**
+     * Handles mode storage during ingestion
+     * Creates or validates system info based on the provided mode and options
+     * @private
+     */
+    static async handleModeStorage(db, options, modelDefaults) {
+        const { getSystemInfo, setSystemInfo } = await import('../core/db.js');
+        // Determine the effective mode and model
+        const effectiveMode = options.mode || 'text';
+        const effectiveModel = options.embeddingModel || config.embedding_model;
+        const effectiveRerankingStrategy = options.rerankingStrategy || 'cross-encoder';
+        // Determine model type based on model name
+        let modelType;
+        if (effectiveModel.includes('clip')) {
+            modelType = 'clip';
+        }
+        else {
+            modelType = 'sentence-transformer';
+        }
+        // Determine supported content types based on mode
+        const supportedContentTypes = effectiveMode === 'multimodal' ? ['text', 'image'] : ['text'];
+        try {
+            // Check if system info already exists
+            const existingSystemInfo = await getSystemInfo(db);
+            if (existingSystemInfo) {
+                // Validate mode consistency for subsequent ingestions
+                if (existingSystemInfo.mode !== effectiveMode) {
+                    console.warn(`⚠️  Mode mismatch detected!`);
+                    console.warn(`   Database mode: ${existingSystemInfo.mode}`);
+                    console.warn(`   Requested mode: ${effectiveMode}`);
+                    if (options.forceRebuild) {
+                        console.log('🔄 Force rebuild enabled, updating mode configuration...');
+                        await this.updateSystemInfo(db, effectiveMode, effectiveModel, modelType, modelDefaults, effectiveRerankingStrategy, supportedContentTypes);
+                    }
+                    else {
+                        throw createModeMismatchError(existingSystemInfo.mode, effectiveMode, { operationContext: 'TextIngestionFactory.create' });
+                    }
+                }
+                else if (existingSystemInfo.modelName !== effectiveModel) {
+                    // Model change within the same mode
+                    console.log(`🔄 Model change detected: ${existingSystemInfo.modelName} → ${effectiveModel}`);
+                    if (options.forceRebuild) {
+                        console.log('🔄 Force rebuild enabled, updating model configuration...');
+                        await this.updateSystemInfo(db, effectiveMode, effectiveModel, modelType, modelDefaults, effectiveRerankingStrategy, supportedContentTypes);
+                    }
+                    else {
+                        // Create a specific error message for model mismatch with rebuild suggestions
+                        const errorMessage = [
+                            `❌ Model mismatch: Database is configured for '${existingSystemInfo.modelName}', but '${effectiveModel}' was requested.`,
+                            '',
+                            '🛠️  How to fix this:',
+                            '   1. Use --force-rebuild to change models:',
+                            '      raglite ingest <path> --model ' + effectiveModel + ' --force-rebuild',
+                            '',
+                            '   2. Or use --rebuild-if-needed for automatic handling:',
+                            '      raglite ingest <path> --model ' + effectiveModel + ' --rebuild-if-needed',
+                            '',
+                            '   3. Or continue using the existing model:',
+                            '      raglite ingest <path>  # Uses ' + existingSystemInfo.modelName,
+                            '',
+                            '🔍 Model switching requires rebuilding the vector index because different models',
+                            '   produce embeddings with different dimensions and characteristics.'
+                        ].join('\n');
+                        throw new Error(errorMessage);
+                    }
+                }
+                else {
+                    console.log(`✅ Mode consistency validated: ${effectiveMode} mode with ${effectiveModel}`);
+                }
+            }
+            else {
+                // First ingestion - create system info
+                console.log(`🔧 First ingestion detected, storing system configuration...`);
+                console.log(`   Mode: ${effectiveMode}`);
+                console.log(`   Model: ${effectiveModel} (${modelType})`);
+                console.log(`   Dimensions: ${modelDefaults.dimensions}`);
+                console.log(`   Reranking: ${effectiveRerankingStrategy}`);
+                console.log(`   Content types: ${supportedContentTypes.join(', ')}`);
+                await this.updateSystemInfo(db, effectiveMode, effectiveModel, modelType, modelDefaults, effectiveRerankingStrategy, supportedContentTypes);
+                console.log('✅ System configuration stored successfully');
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && (error.message.includes('Mode mismatch') || error.message.includes('Model mismatch'))) {
+                throw error; // Re-throw validation errors with custom messages
+            }
+            console.error('❌ Failed to handle mode storage:', error);
+            throw new Error(`Mode storage failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
+    /**
+     * Updates system info in the database
+     * @private
+     */
+    static async updateSystemInfo(db, mode, modelName, modelType, modelDefaults, rerankingStrategy, supportedContentTypes) {
+        const { setSystemInfo } = await import('../core/db.js');
+        await setSystemInfo(db, {
+            mode,
+            modelName,
+            modelType,
+            modelDimensions: modelDefaults.dimensions,
+            modelVersion: '1.0.0', // TODO: Get actual version from model
+            supportedContentTypes,
+            rerankingStrategy: rerankingStrategy,
+            rerankingModel: undefined,
+            rerankingConfig: undefined
+        });
+    }
+    /**
+     * Validates and prepares content system configuration
+     * @private
+     */
+    static async validateAndPrepareContentSystemConfig(userConfig) {
+        // Default configuration
+        const defaultConfig = {
+            contentDir: '.raglite/content',
+            maxFileSize: 50 * 1024 * 1024, // 50MB
+            maxContentDirSize: 2 * 1024 * 1024 * 1024, // 2GB
+            enableDeduplication: true,
+            enableStorageTracking: true
+        };
+        // Merge with user configuration
+        const config = { ...defaultConfig, ...userConfig };
+        // Validate content directory path
+        if (!config.contentDir || typeof config.contentDir !== 'string') {
+            throw new Error('Content directory path must be a non-empty string');
+        }
+        // Validate file size limits
+        if (config.maxFileSize && (typeof config.maxFileSize !== 'number' || config.maxFileSize <= 0)) {
+            throw new Error('Maximum file size must be a positive number');
+        }
+        if (config.maxContentDirSize && (typeof config.maxContentDirSize !== 'number' || config.maxContentDirSize <= 0)) {
+            throw new Error('Maximum content directory size must be a positive number');
+        }
+        // Validate that maxFileSize is not larger than maxContentDirSize
+        if (config.maxFileSize && config.maxContentDirSize && config.maxFileSize > config.maxContentDirSize) {
+            throw new Error('Maximum file size cannot be larger than maximum content directory size');
+        }
+        // Validate boolean options
+        if (config.enableDeduplication !== undefined && typeof config.enableDeduplication !== 'boolean') {
+            throw new Error('enableDeduplication must be a boolean value');
+        }
+        if (config.enableStorageTracking !== undefined && typeof config.enableStorageTracking !== 'boolean') {
+            throw new Error('enableStorageTracking must be a boolean value');
+        }
+        // Create content directory if it doesn't exist
+        try {
+            const { promises: fs } = await import('fs');
+            await fs.mkdir(config.contentDir, { recursive: true });
+            // Verify directory is writable
+            await fs.access(config.contentDir, (await import('fs')).constants.W_OK);
+            console.log(`✓ Content directory validated: ${config.contentDir}`);
+        }
+        catch (error) {
+            throw new Error(`Failed to create or access content directory '${config.contentDir}': ${error instanceof Error ? error.message : 'Unknown error'}. Please check permissions and path validity.`);
+        }
+        return config;
+    }
 }
 /**
  * Convenience factory to create both search and ingestion instances
@@ -548,9 +820,9 @@ export class TextRAGFactory {
  * const { searchOptions, ingestionOptions } = TextFactoryHelpers.getRecommendedConfig('quality');
  * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', searchOptions);
  *
- * // Create with automatic error recovery
- * const search = await TextFactoryHelpers.createSearchWithFallback('./index.bin', './db.sqlite', {
- *   enableReranking: true // Will fallback to disabled if reranking fails
+ * // Create with clear validation and error reporting
+ * const search = await TextFactoryHelpers.createSearchWithValidation('./index.bin', './db.sqlite', {
+ *   enableReranking: true // Will fail clearly if reranking has issues
  * });
  * ```
  */
@@ -581,16 +853,14 @@ export class TextFactoryHelpers {
      */
     static validateSearchFiles(indexPath, dbPath) {
         if (!existsSync(indexPath)) {
-            throw new Error(`Vector index not found: ${indexPath}\n` +
-                'Run ingestion first: raglite ingest <directory>\n' +
-                'Or use: const ingestion = await IngestionFactory.create(dbPath, indexPath);\n' +
-                'Or check if the path is correct.');
+            throw createMissingFileError(indexPath, 'index', {
+                operationContext: 'search file validation'
+            });
         }
         if (!existsSync(dbPath)) {
-            throw new Error(`Database not found: ${dbPath}\n` +
-                'Run ingestion first: raglite ingest <directory>\n' +
-                'Or use: const ingestion = await IngestionFactory.create(dbPath, indexPath);\n' +
-                'Or check if the path is correct.');
+            throw createMissingFileError(dbPath, 'database', {
+                operationContext: 'search file validation'
+            });
         }
     }
     /**
@@ -664,56 +934,35 @@ export class TextFactoryHelpers {
         }
     }
     /**
-     * Create a search engine with automatic error recovery
+     * Create a search engine with clear error reporting
      *
-     * This method attempts to create a search engine with the provided options,
-     * and if that fails, it tries again with fallback options (primarily
-     * disabling reranking, which is a common source of initialization failures).
-     * This provides a more robust way to create search engines in environments
-     * where reranking models might not be available or might fail to load.
+     * This method creates a search engine with the provided options and fails
+     * clearly if there are any issues, providing actionable error messages.
      *
      * @param indexPath - Path to vector index file
      * @param dbPath - Path to database file
-     * @param options - Initial options to try
-     * @returns Promise resolving to SearchEngine (possibly with fallback options)
-     * @throws {Error} If both original and fallback creation attempts fail
+     * @param options - Configuration options
+     * @returns Promise resolving to SearchEngine
+     * @throws {Error} If creation fails with clear error message
      *
      * @example
      * ```typescript
-     * // Try to create with reranking, fallback to without if it fails
-     * const search = await TextFactoryHelpers.createSearchWithFallback(
+     * // Create search engine with clear error handling
+     * const search = await TextFactoryHelpers.createSearchWithValidation(
      *   './index.bin',
      *   './db.sqlite',
      *   { enableReranking: true, topK: 20 }
      * );
      *
-     * // The search engine will work even if reranking model fails to load
      * const results = await search.search('query');
      * console.log(`Search created successfully with ${results.length} results`);
      * ```
      */
-    static async createSearchWithFallback(indexPath, dbPath, options = {}) {
-        try {
-            // Try with original options
-            return await TextSearchFactory.create(indexPath, dbPath, options);
-        }
-        catch (error) {
-            console.warn(`Initial search creation failed, trying fallback options: ${error instanceof Error ? error.message : 'Unknown error'}`);
-            // Try with reranking disabled as fallback
-            const fallbackOptions = {
-                ...options,
-                enableReranking: false
-            };
-            try {
-                return await TextSearchFactory.create(indexPath, dbPath, fallbackOptions);
-            }
-            catch (fallbackError) {
-                console.error('Fallback search creation also failed');
-                throw new Error(`Failed to create search engine with both original and fallback options:\n` +
-                    `Original error: ${error instanceof Error ? error.message : 'Unknown error'}\n` +
-                    `Fallback error: ${fallbackError instanceof Error ? fallbackError.message : 'Unknown error'}`);
-            }
-        }
+    static async createSearchWithValidation(indexPath, dbPath, options = {}) {
+        // Validate files first
+        this.validateSearchFiles(indexPath, dbPath);
+        // Create with clear error reporting
+        return await TextSearchFactory.create(indexPath, dbPath, options);
     }
 }
 //# sourceMappingURL=text-factory.js.map