rag-lite-ts 1.0.2 → 2.0.0

package/dist/core/validation-messages.js

@@ -0,0 +1,334 @@
+/**
+ * CORE MODULE — Validation Messages and Error Descriptions
+ * Comprehensive error messages and user guidance for model validation
+ * Provides helpful, actionable error messages with troubleshooting steps
+ */
+import { ModelRegistry } from './model-registry.js';
+// =============================================================================
+// ERROR MESSAGE TEMPLATES
+// =============================================================================
+/**
+ * Error message templates for different validation scenarios
+ */
+export const ERROR_MESSAGES = {
+    MODEL_NOT_FOUND: (modelName, suggestions) => ({
+        title: `Model '${modelName}' not found`,
+        description: `The specified model is not supported by the Chameleon architecture.`,
+        details: [
+            `Model '${modelName}' is not in the supported models registry.`,
+            `This could be due to a typo in the model name or the model not being compatible with transformers.js.`
+        ],
+        suggestions: suggestions.length > 0 ? [
+            `Did you mean one of these models?`,
+            ...suggestions.map(s => `  • ${s}`)
+        ] : [
+            `Available models:`,
+            ...ModelRegistry.getSupportedModels().map(s => `  • ${s}`)
+        ],
+        actions: [
+            `Check the model name for typos`,
+            `Use 'ModelRegistry.getSupportedModels()' to see all available models`,
+            `Visit the documentation for the latest supported models list`
+        ]
+    }),
+    TRANSFORMERS_VERSION_INCOMPATIBLE: (modelName, required, current) => ({
+        title: `Transformers.js version incompatible`,
+        description: `Model '${modelName}' requires a newer version of transformers.js.`,
+        details: [
+            `Required version: ${required}`,
+            `Current version: ${current}`,
+            `The model uses features not available in the current transformers.js version.`
+        ],
+        suggestions: [
+            `Upgrade transformers.js to the latest version:`,
+            `  npm install @huggingface/transformers@latest`,
+            ``,
+            `Or install a specific compatible version:`,
+            `  npm install @huggingface/transformers@${required.replace(/[>=<~^]/g, '')}`
+        ],
+        actions: [
+            `Update your package.json dependencies`,
+            `Run npm install to update transformers.js`,
+            `Restart your application after updating`
+        ]
+    }),
+    INSUFFICIENT_MEMORY: (modelName, required, available) => ({
+        title: `Insufficient memory for model`,
+        description: `Model '${modelName}' requires more memory than available.`,
+        details: [
+            `Required memory: ${required}MB`,
+            `Available memory: ${available}MB`,
+            `Shortfall: ${required - available}MB`
+        ],
+        suggestions: [
+            `Consider using a smaller model variant:`,
+            ...ModelRegistry.getSupportedModels().filter(name => {
+                const info = ModelRegistry.getModelInfo(name);
+                return info &&
+                    info.requirements.minimumMemory &&
+                    info.requirements.minimumMemory <= available;
+            }).map(name => `  • ${name}`),
+            ``,
+            `Or increase available memory by:`,
+            `  • Closing other applications`,
+            `  • Increasing Node.js memory limit: --max-old-space-size=${required + 512}`,
+            `  • Using a machine with more RAM`
+        ],
+        actions: [
+            `Free up system memory`,
+            `Choose a more memory-efficient model`,
+            `Consider using model quantization if available`
+        ]
+    }),
+    PLATFORM_UNSUPPORTED: (modelName, currentPlatform, supportedPlatforms) => ({
+        title: `Platform not supported`,
+        description: `Model '${modelName}' is not supported on ${currentPlatform}.`,
+        details: [
+            `Current platform: ${currentPlatform}`,
+            `Supported platforms: ${supportedPlatforms.join(', ')}`,
+            `The model may use platform-specific features or optimizations.`
+        ],
+        suggestions: [
+            `Try running on a supported platform:`,
+            ...supportedPlatforms.map(platform => `  • ${platform}`),
+            ``,
+            `Or use a platform-agnostic model:`,
+            ...ModelRegistry.getSupportedModels().filter(name => {
+                const info = ModelRegistry.getModelInfo(name);
+                return info &&
+                    info.requirements.platformSupport &&
+                    info.requirements.platformSupport.includes(currentPlatform);
+            }).slice(0, 3).map(name => `  • ${name}`)
+        ],
+        actions: [
+            `Switch to a supported platform`,
+            `Use a different model that supports your platform`,
+            `Check if there are platform-specific installation instructions`
+        ]
+    }),
+    FEATURES_MISSING: (modelName, missingFeatures) => ({
+        title: `Required features not available`,
+        description: `Model '${modelName}' requires features not available in current transformers.js version.`,
+        details: [
+            `Missing features: ${missingFeatures.join(', ')}`,
+            `These features are required for the model to function properly.`
+        ],
+        suggestions: [
+            `Upgrade transformers.js to get missing features:`,
+            `  npm install @huggingface/transformers@latest`,
+            ``,
+            `Or use a model that doesn't require these features:`,
+            ...ModelRegistry.getSupportedModels().filter(name => {
+                const info = ModelRegistry.getModelInfo(name);
+                return info &&
+                    (!info.requirements.requiredFeatures ||
+                        info.requirements.requiredFeatures.every(f => !missingFeatures.includes(f)));
+            }).slice(0, 3).map(name => `  • ${name}`)
+        ],
+        actions: [
+            `Update transformers.js to the latest version`,
+            `Check the transformers.js changelog for feature availability`,
+            `Use an alternative model with fewer feature requirements`
+        ]
+    }),
+    CONTENT_TYPE_UNSUPPORTED: (contentType, modelName, supportedTypes) => ({
+        title: `Content type not supported`,
+        description: `Model '${modelName}' does not support '${contentType}' content.`,
+        details: [
+            `Requested content type: ${contentType}`,
+            `Supported content types: ${supportedTypes.join(', ')}`,
+            `The model was not trained to handle this type of content.`
+        ],
+        suggestions: [
+            `Use a model that supports '${contentType}' content:`,
+            ...ModelRegistry.getModelsByContentType(contentType).slice(0, 3).map(name => `  • ${name}`),
+            ``,
+            `Or convert your content to a supported type:`,
+            ...supportedTypes.map(type => `  • Convert to ${type}`)
+        ],
+        actions: [
+            `Choose a multimodal model for mixed content types`,
+            `Preprocess your content to match supported types`,
+            `Use separate models for different content types`
+        ]
+    })
+};
+// =============================================================================
+// WARNING MESSAGE TEMPLATES
+// =============================================================================
+/**
+ * Warning message templates for non-critical issues
+ */
+export const WARNING_MESSAGES = {
+    HIGH_MEMORY_USAGE: (modelName, memoryMB) => ({
+        title: `High memory usage`,
+        message: `Model '${modelName}' requires ${memoryMB}MB of memory, which may impact performance.`,
+        suggestions: [
+            `Monitor system memory usage during operation`,
+            `Consider using a smaller model variant if performance is affected`,
+            `Ensure sufficient swap space is available`
+        ]
+    }),
+    LIMITED_BATCH_SIZE: (modelName, maxBatchSize) => ({
+        title: `Limited batch processing`,
+        message: `Model '${modelName}' supports maximum batch size of ${maxBatchSize}.`,
+        suggestions: [
+            `Use smaller batch sizes for optimal performance`,
+            `Process large datasets in smaller chunks`,
+            `Consider parallel processing with multiple model instances`
+        ]
+    }),
+    EXPERIMENTAL_FEATURES: (modelName, features) => ({
+        title: `Experimental features in use`,
+        message: `Model '${modelName}' uses experimental features: ${features.join(', ')}.`,
+        suggestions: [
+            `Test thoroughly before using in production`,
+            `Monitor for unexpected behavior or errors`,
+            `Have fallback options ready`,
+            `Check for updates that may stabilize these features`
+        ]
+    }),
+    PERFORMANCE_IMPACT: (modelName, reason) => ({
+        title: `Potential performance impact`,
+        message: `Model '${modelName}' may have reduced performance: ${reason}.`,
+        suggestions: [
+            `Monitor processing times and resource usage`,
+            `Consider using GPU acceleration if available`,
+            `Optimize batch sizes for your use case`,
+            `Profile your application to identify bottlenecks`
+        ]
+    })
+};
+// =============================================================================
+// MESSAGE FORMATTING UTILITIES
+// =============================================================================
+/**
+ * Format an error message for console output
+ */
+export function formatErrorMessage(error) {
+    const lines = [];
+    lines.push(`❌ ${error.title}`);
+    lines.push('');
+    lines.push(error.description);
+    if (error.details.length > 0) {
+        lines.push('');
+        lines.push('Details:');
+        error.details.forEach(detail => lines.push(`  ${detail}`));
+    }
+    if (error.suggestions.length > 0) {
+        lines.push('');
+        lines.push('Suggestions:');
+        error.suggestions.forEach(suggestion => lines.push(`  ${suggestion}`));
+    }
+    if (error.actions.length > 0) {
+        lines.push('');
+        lines.push('Actions:');
+        error.actions.forEach((action, index) => lines.push(`  ${index + 1}. ${action}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a warning message for console output
+ */
+export function formatWarningMessage(warning) {
+    const lines = [];
+    lines.push(`⚠️  ${warning.title}`);
+    lines.push('');
+    lines.push(warning.message);
+    if (warning.suggestions.length > 0) {
+        lines.push('');
+        lines.push('Suggestions:');
+        warning.suggestions.forEach(suggestion => lines.push(`  • ${suggestion}`));
+    }
+    return lines.join('\n');
+}
+/**
+ * Create a comprehensive error message for model validation failure
+ */
+export function createValidationErrorMessage(modelName, errorType, context = {}) {
+    switch (errorType) {
+        case 'not_found':
+            return formatErrorMessage(ERROR_MESSAGES.MODEL_NOT_FOUND(modelName, context.suggestions || []));
+        case 'version_incompatible':
+            return formatErrorMessage(ERROR_MESSAGES.TRANSFORMERS_VERSION_INCOMPATIBLE(modelName, context.required || 'unknown', context.current || 'unknown'));
+        case 'insufficient_memory':
+            return formatErrorMessage(ERROR_MESSAGES.INSUFFICIENT_MEMORY(modelName, context.required || 0, context.available || 0));
+        case 'platform_unsupported':
+            return formatErrorMessage(ERROR_MESSAGES.PLATFORM_UNSUPPORTED(modelName, context.currentPlatform || 'unknown', context.supportedPlatforms || []));
+        case 'features_missing':
+            return formatErrorMessage(ERROR_MESSAGES.FEATURES_MISSING(modelName, context.missingFeatures || []));
+        case 'content_type_unsupported':
+            return formatErrorMessage(ERROR_MESSAGES.CONTENT_TYPE_UNSUPPORTED(context.contentType || 'unknown', modelName, context.supportedTypes || []));
+        default:
+            return `❌ Validation failed for model '${modelName}': ${errorType}`;
+    }
+}
+/**
+ * Create helpful suggestions based on model type and use case
+ */
+export function createModelSuggestions(modelType, contentTypes, memoryLimit) {
+    const suggestions = [];
+    if (modelType === 'sentence-transformer') {
+        suggestions.push('For text-only tasks, sentence-transformers are most efficient');
+        suggestions.push('all-MiniLM-L6-v2 offers the best balance of speed and accuracy');
+        suggestions.push('all-mpnet-base-v2 provides higher accuracy but uses more memory');
+    }
+    if (modelType === 'clip') {
+        suggestions.push('CLIP models support both text and image content');
+        suggestions.push('clip-vit-base-patch32 is recommended for most use cases');
+        suggestions.push('patch16 variants are more accurate but slower');
+    }
+    if (contentTypes?.includes('image')) {
+        suggestions.push('Multimodal content requires CLIP models');
+        suggestions.push('Ensure images are in supported formats (jpg, png, webp)');
+        suggestions.push('Consider image preprocessing for better results');
+    }
+    if (memoryLimit && memoryLimit < 1024) {
+        suggestions.push('Low memory environments should use smaller models');
+        suggestions.push('Consider model quantization to reduce memory usage');
+        suggestions.push('Process content in smaller batches');
+    }
+    return suggestions;
+}
+/**
+ * Get troubleshooting steps for common issues
+ */
+export function getTroubleshootingSteps(issue) {
+    const steps = {
+        'model_loading_failed': [
+            'Check internet connection for model download',
+            'Verify model name spelling and availability',
+            'Ensure sufficient disk space for model cache',
+            'Try clearing the model cache and re-downloading',
+            'Check transformers.js version compatibility'
+        ],
+        'out_of_memory': [
+            'Reduce batch size for processing',
+            'Use a smaller model variant',
+            'Increase Node.js memory limit with --max-old-space-size',
+            'Close other memory-intensive applications',
+            'Consider using model quantization'
+        ],
+        'slow_performance': [
+            'Use GPU acceleration if available',
+            'Optimize batch sizes for your hardware',
+            'Consider using a smaller, faster model',
+            'Profile your code to identify bottlenecks',
+            'Use appropriate hardware for your model size'
+        ],
+        'compatibility_issues': [
+            'Update transformers.js to the latest version',
+            'Check model requirements against your environment',
+            'Verify platform compatibility (Node.js vs browser)',
+            'Test with a known working model first',
+            'Check for conflicting dependencies'
+        ]
+    };
+    return steps[issue] || [
+        'Check the documentation for your specific issue',
+        'Search for similar issues in the project repository',
+        'Ensure all dependencies are up to date',
+        'Try with a minimal test case to isolate the problem'
+    ];
+}
+//# sourceMappingURL=validation-messages.js.map

package/dist/core/vector-index.js

@@ -5,6 +5,7 @@
 import { readFileSync, writeFileSync, existsSync } from 'fs';
 import { JSDOM } from 'jsdom';
 import { ErrorCategory, ErrorSeverity, safeExecute } from './error-handler.js';
+import { createMissingFileError, createDimensionMismatchError } from './actionable-error-messages.js';
 // Set up browser-like environment for hnswlib-wasm
 if (typeof window === 'undefined') {
     const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
@@ -103,7 +104,9 @@ export class VectorIndex {
      */
     async loadIndex() {
         if (!existsSync(this.indexPath)) {
-            throw new Error(`Index file not found: ${this.indexPath}`);
+            throw createMissingFileError(this.indexPath, 'index', {
+                operationContext: 'VectorIndex.loadIndex'
+            });
         }
         try {
             // Load the hnswlib module
@@ -162,11 +165,7 @@ export class VectorIndex {
                 if (stored.vectors && stored.vectors.length > 0) {
                     console.log(`   Actual vector length: ${stored.vectors[0].vector.length}`);
                 }
-                throw new Error(`Vector dimension mismatch!\n` +
-                    `Index was created with ${stored.dimensions} dimensions\n` +
-                    `Current model expects ${this.options.dimensions} dimensions\n` +
-                    `This indicates the embedding model has changed.\n` +
-                    `Please rebuild the index with the current model.`);
+                throw createDimensionMismatchError(this.options.dimensions, stored.dimensions, 'vector index loading', { operationContext: 'VectorIndex.loadIndex' });
             }
             // Update options from stored data
             this.options.maxElements = stored.maxElements || this.options.maxElements;
@@ -227,7 +226,7 @@ export class VectorIndex {
             throw new Error('Index not initialized');
         }
         if (vector.length !== this.options.dimensions) {
-            throw new Error(`Vector dimension mismatch: expected ${this.options.dimensions}, got ${vector.length}`);
+            throw createDimensionMismatchError(this.options.dimensions, vector.length, 'vector addition', { operationContext: 'VectorIndex.addVector' });
         }
         try {
             this.index.addPoint(vector, embeddingId, false);
@@ -255,7 +254,7 @@ export class VectorIndex {
             throw new Error('Index not initialized');
         }
         if (queryVector.length !== this.options.dimensions) {
-            throw new Error(`Query vector dimension mismatch: expected ${this.options.dimensions}, got ${queryVector.length}`);
+            throw createDimensionMismatchError(this.options.dimensions, queryVector.length, 'vector search', { operationContext: 'VectorIndex.search' });
         }
         if (this.currentSize === 0) {
             return { neighbors: [], distances: [] };

package/dist/factories/index.d.ts

@@ -36,7 +36,7 @@
  * ```
  */
 export { TextSearchFactory, TextIngestionFactory, TextRAGFactory, TextFactoryHelpers } from './text-factory.js';
-export type { TextSearchOptions, TextIngestionOptions } from './text-factory.js';
+export type { TextSearchOptions, TextIngestionOptions, ContentSystemConfig } from './text-factory.js';
 export { TextSearchFactory as SearchFactory } from './text-factory.js';
 export { TextIngestionFactory as IngestionFactory } from './text-factory.js';
 export { TextRAGFactory as RAGFactory } from './text-factory.js';

package/dist/factories/text-factory.d.ts

@@ -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';
@@ -70,6 +97,21 @@ export interface TextSearchOptions {
     /** Top-k results to return (default: from config) */
     topK?: number;
 }
+/**
+ * Content system configuration options
+ */
+export interface ContentSystemConfig {
+    /** Content directory path (default: '.raglite/content') */
+    contentDir?: string;
+    /** Maximum file size in bytes (default: 50MB) */
+    maxFileSize?: number;
+    /** Maximum content directory size in bytes (default: 2GB) */
+    maxContentDirSize?: number;
+    /** Enable content deduplication (default: true) */
+    enableDeduplication?: boolean;
+    /** Enable storage tracking (default: true) */
+    enableStorageTracking?: boolean;
+}
 /**
  * Options for text ingestion factory
  */
@@ -84,17 +126,30 @@ export interface TextIngestionOptions {
     chunkOverlap?: number;
     /** Whether to force rebuild the index */
     forceRebuild?: boolean;
+    /** Mode for the ingestion pipeline (text or multimodal) */
+    mode?: 'text' | 'multimodal';
+    /** Reranking strategy for multimodal mode */
+    rerankingStrategy?: 'cross-encoder' | 'text-derived' | 'metadata' | 'hybrid' | 'disabled';
+    /** Content system configuration */
+    contentSystemConfig?: ContentSystemConfig;
 }
 /**
  * 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
@@ -122,7 +177,7 @@ export declare 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
@@ -187,10 +242,18 @@ export declare 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
@@ -232,20 +295,39 @@ export declare 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();
@@ -259,6 +341,22 @@ export declare class TextIngestionFactory {
      * @returns Promise resolving to configured IngestionPipeline
      */
     static createWithDefaults(options?: TextIngestionOptions): Promise<IngestionPipeline>;
+    /**
+     * Handles mode storage during ingestion
+     * Creates or validates system info based on the provided mode and options
+     * @private
+     */
+    private static handleModeStorage;
+    /**
+     * Updates system info in the database
+     * @private
+     */
+    private static updateSystemInfo;
+    /**
+     * Validates and prepares content system configuration
+     * @private
+     */
+    private static validateAndPrepareContentSystemConfig;
 }
 /**
  * Convenience factory to create both search and ingestion instances
@@ -365,9 +463,9 @@ export declare 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
  * });
  * ```
  */
@@ -433,34 +531,30 @@ export declare class TextFactoryHelpers {
         ingestionOptions: TextIngestionOptions;
     };
     /**
-     * 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 createSearchWithFallback(indexPath: string, dbPath: string, options?: TextSearchOptions): Promise<SearchEngine>;
+    static createSearchWithValidation(indexPath: string, dbPath: string, options?: TextSearchOptions): Promise<SearchEngine>;
 }
 //# sourceMappingURL=text-factory.d.ts.map