rag-lite-ts 2.0.3 → 2.0.5

package/dist/factories/ingestion-factory.js

@@ -0,0 +1,475 @@
+/**
+ * Factory functions for creating text-specific search and ingestion instances
+ * Handles complex initialization logic while providing clean API for common use cases
+ *
+ * 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
+ * - 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. Mode Selection:
+ * ```typescript
+ * // Text mode (default) - optimized for text-only content
+ * const textIngestion = await IngestionFactory.create('./db.sqlite', './index.bin', {
+ *   mode: 'text',
+ *   embeddingModel: 'sentence-transformers/all-MiniLM-L6-v2'
+ * });
+ *
+ * // Multimodal mode - enables cross-modal search
+ * const multimodalIngestion = await IngestionFactory.create('./db.sqlite', './index.bin', {
+ *   mode: 'multimodal',
+ *   embeddingModel: 'Xenova/clip-vit-base-patch32',
+ *   rerankingStrategy: 'text-derived'
+ * });
+ * ```
+ */
+import { IngestionPipeline } from '../core/ingestion.js';
+import { IndexManager } from '../index-manager.js';
+import { openDatabase } from '../core/db.js';
+import { createTextEmbedFunction } from '../text/embedder.js';
+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 { createInvalidPathError, createFactoryCreationError, createModeMismatchError } from '../core/actionable-error-messages.js';
+/**
+ * Factory for creating text-based IngestionPipeline instances
+ * Handles model loading, database initialization, and index setup
+ *
+ * This factory abstracts the complex initialization process required for text ingestion:
+ * 1. Creates necessary directories if they don't exist
+ * 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
+ * // Basic usage
+ * const ingestion = await IngestionFactory.create('./db.sqlite', './index.bin');
+ * await ingestion.ingestDirectory('./documents');
+ *
+ * // With custom configuration
+ * const ingestion = await IngestionFactory.create('./db.sqlite', './index.bin', {
+ *   embeddingModel: 'all-MiniLM-L6-v2',
+ *   chunkSize: 512,
+ *   chunkOverlap: 50,
+ *   forceRebuild: true
+ * });
+ *
+ * // With defaults
+ * const ingestion = await IngestionFactory.createWithDefaults({
+ *   batchSize: 32 // Faster processing
+ * });
+ * ```
+ */
+export class IngestionFactory {
+    /**
+     * Create an IngestionPipeline configured for text ingestion
+     *
+     * This method handles the complete initialization process:
+     * - Creates necessary directories if they don't exist
+     * - Loads text embedding model (with lazy initialization)
+     * - Opens database connection and initializes schema
+     * - Creates or loads vector index (with force rebuild option)
+     * - Creates IngestionPipeline with dependency injection
+     * - Validates the complete setup
+     *
+     * @param dbPath - Path to the SQLite database file (will be created if doesn't exist)
+     * @param indexPath - Path to the vector index file (will be created if doesn't exist)
+     * @param options - Optional configuration overrides
+     * @param options.embeddingModel - Override embedding model (default: from config)
+     * @param options.batchSize - Override embedding batch size (default: from config)
+     * @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 with default content system
+     * const ingestion = await IngestionFactory.create('./my-db.sqlite', './my-index.bin');
+     *
+     * // Create with custom content system configuration
+     * const ingestion = await IngestionFactory.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 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();
+     * ```
+     */
+    static async create(dbPath, indexPath, options = {}) {
+        try {
+            console.log('🏭 IngestionFactory: Initializing text ingestion pipeline...');
+            // Validate input paths
+            if (!dbPath || !indexPath) {
+                throw createInvalidPathError([
+                    { name: 'dbPath', value: dbPath },
+                    { name: 'indexPath', value: indexPath }
+                ], { operationContext: 'IngestionFactory.create' });
+            }
+            // Ensure directories exist
+            const dbDir = dirname(dbPath);
+            const indexDir = dirname(indexPath);
+            if (!existsSync(dbDir)) {
+                console.log(`📁 Creating database directory: ${dbDir}`);
+                mkdirSync(dbDir, { recursive: true });
+            }
+            if (!existsSync(indexDir)) {
+                console.log(`📁 Creating index directory: ${indexDir}`);
+                mkdirSync(indexDir, { recursive: true });
+            }
+            // Step 1: Determine effective mode and select appropriate default model
+            const effectiveMode = options.mode || 'text';
+            // Step 1.5: Select model based on mode if not explicitly provided
+            let effectiveModel;
+            if (options.embeddingModel) {
+                // Use explicitly provided model
+                effectiveModel = options.embeddingModel;
+            }
+            else {
+                // Select default model based on mode
+                if (effectiveMode === 'multimodal') {
+                    const { DEFAULT_MODELS } = await import('../core/model-registry.js');
+                    effectiveModel = DEFAULT_MODELS['clip'];
+                    console.log(`📊 No model specified for multimodal mode, using default: ${effectiveModel}`);
+                }
+                else {
+                    effectiveModel = config.embedding_model;
+                }
+            }
+            // Step 2: Get model-specific defaults and merge with options
+            const modelDefaults = getModelDefaults(effectiveModel);
+            const effectiveBatchSize = options.batchSize ?? modelDefaults.batch_size;
+            const effectiveChunkSize = options.chunkSize ?? modelDefaults.chunk_size;
+            const effectiveChunkOverlap = options.chunkOverlap ?? modelDefaults.chunk_overlap;
+            // Step 3: Validate mode-model compatibility at creation time
+            console.log('🔍 Validating mode-model compatibility...');
+            validateModeModelCompatibilityOrThrow(effectiveMode, effectiveModel);
+            console.log('✓ Mode-model compatibility validated');
+            // Step 4: 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);
+            // Initialize database schema if needed
+            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, effectiveModel);
+            // Step 5: Initialize index manager
+            console.log('📇 Initializing vector index...');
+            const indexManager = new IndexManager(indexPath, dbPath, modelDefaults.dimensions, effectiveModel);
+            // Check if we need to force recreation due to model change
+            let forceRecreate = false;
+            if (options.forceRebuild && existsSync(indexPath) && existsSync(dbPath)) {
+                // 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 { getSystemInfo } = await import('../core/db.js');
+                const tempDb = await openDatabase(dbPath);
+                try {
+                    const systemInfo = await getSystemInfo(tempDb);
+                    if (systemInfo && systemInfo.modelName && systemInfo.modelName !== effectiveModel) {
+                        console.log(`🔄 Model change detected: ${systemInfo.modelName} → ${effectiveModel}`);
+                        console.log(`🔄 Dimensions change: ${systemInfo.modelDimensions} → ${modelDefaults.dimensions}`);
+                    }
+                    else if (systemInfo && systemInfo.modelDimensions && systemInfo.modelDimensions !== modelDefaults.dimensions) {
+                        console.log(`🔄 Dimension mismatch detected: ${systemInfo.modelDimensions} → ${modelDefaults.dimensions}`);
+                    }
+                }
+                finally {
+                    await tempDb.close();
+                }
+            }
+            // Handle force rebuild or create new index
+            if (options.forceRebuild || !existsSync(indexPath)) {
+                if (options.forceRebuild && existsSync(indexPath)) {
+                    console.log('🔄 Force rebuild requested, recreating index...');
+                }
+                else {
+                    console.log('📇 Creating new vector index...');
+                }
+                // Initialize with skipModelCheck and forceRecreate for rebuilds
+                await indexManager.initialize(options.forceRebuild, forceRecreate);
+                // Update stored model info when rebuilding or creating new index
+                if (options.forceRebuild || forceRecreate) {
+                    const { setSystemInfo } = await import('../core/db.js');
+                    await setSystemInfo(db, {
+                        modelName: effectiveModel,
+                        modelDimensions: modelDefaults.dimensions
+                    });
+                    console.log(`✓ Updated stored model info: ${effectiveModel} (${modelDefaults.dimensions} dimensions)`);
+                }
+            }
+            else {
+                // Load existing index
+                await indexManager.initialize();
+            }
+            console.log('✓ Vector index ready');
+            // 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, contentManager);
+            console.log('🎉 IngestionFactory: Ingestion pipeline initialized successfully');
+            return ingestionPipeline;
+        }
+        catch (error) {
+            console.error('❌ IngestionFactory: Failed to create ingestion pipeline');
+            // 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('IngestionFactory', error instanceof Error ? error.message : 'Unknown error', { operationContext: 'ingestion pipeline creation' });
+        }
+    }
+    /**
+     * Create an IngestionPipeline with automatic path resolution
+     * Uses default paths based on current working directory
+     * @param options - Optional configuration overrides
+     * @returns Promise resolving to configured IngestionPipeline
+     */
+    static async createWithDefaults(options = {}) {
+        const dbPath = config.db_file || './database.sqlite';
+        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, effectiveModel) {
+        const { getSystemInfo, setSystemInfo } = await import('../core/db.js');
+        // Determine the effective mode and reranking strategy
+        const effectiveMode = options.mode || 'text';
+        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: 'IngestionFactory.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;
+    }
+}
+//# sourceMappingURL=ingestion-factory.js.map

package/dist/{core/polymorphic-search-factory.d.ts → factories/search-factory.d.ts}

@@ -12,7 +12,7 @@
  * automatically detected during search - no manual configuration needed.
  */
 import '../dom-polyfills.js';
-import { SearchEngine } from './search.js';
+import { SearchEngine } from '../core/search.js';
 import type { SystemInfo, ModeType } from '../types.js';
 /**
  * Factory for creating search engines with automatic mode detection
@@ -33,7 +33,7 @@ import type { SystemInfo, ModeType } from '../types.js';
  *   - True cross-modal search capabilities
  *   - Text queries find images, image queries find text
  */
-export declare class PolymorphicSearchFactory {
+export declare class SearchFactory {
     /**
      * Create a SearchEngine with automatic mode detection and configuration
      *
@@ -66,7 +66,7 @@ export declare class PolymorphicSearchFactory {
      * @example
      * ```typescript
      * // Automatic mode detection and engine creation
-     * const search = await PolymorphicSearchFactory.create('./index.bin', './db.sqlite');
+     * const search = await SearchFactory.create('./index.bin', './db.sqlite');
      *
      * // Search works based on detected mode:
      * // Text mode: fast text similarity search
@@ -110,7 +110,7 @@ export declare class PolymorphicSearchFactory {
 }
 /**
  * Quick function to create a search engine with automatic mode detection
- * Convenience wrapper around PolymorphicSearchFactory.create
+ * Convenience wrapper around SearchFactory.create
  *
  * @param indexPath - Path to the vector index file
  * @param dbPath - Path to the database file
@@ -118,11 +118,11 @@ export declare class PolymorphicSearchFactory {
  *
  * @example
  * ```typescript
- * const search = await createPolymorphicSearchEngine('./index.bin', './db.sqlite');
+ * const search = await createSearchEngine('./index.bin', './db.sqlite');
  * const results = await search.search('query');
  * ```
  */
-export declare function createPolymorphicSearchEngine(indexPath: string, dbPath: string): Promise<SearchEngine>;
+export declare function createSearchEngine(indexPath: string, dbPath: string): Promise<SearchEngine>;
 /**
  * Check what mode a database is configured for
  * Convenience function for inspecting database configuration
@@ -151,4 +151,4 @@ export declare function detectSearchEngineMode(dbPath: string): Promise<ModeType
  * ```
  */
 export declare function getSearchEngineInfo(dbPath: string): Promise<SystemInfo>;
-//# sourceMappingURL=polymorphic-search-factory.d.ts.map
+//# sourceMappingURL=search-factory.d.ts.map

package/dist/{core/polymorphic-search-factory.js → factories/search-factory.js}

@@ -13,15 +13,15 @@
  */
 // Ensure DOM polyfills are set up before any transformers.js usage
 import '../dom-polyfills.js';
-import { SearchEngine } from './search.js';
-import { ModeDetectionService } from './mode-detection-service.js';
+import { SearchEngine } from '../core/search.js';
+import { ModeDetectionService } from '../core/mode-detection-service.js';
 import { IndexManager } from '../index-manager.js';
-import { DatabaseConnectionManager } from './database-connection-manager.js';
-import { createEmbedder } from './embedder-factory.js';
-import { ContentResolver } from './content-resolver.js';
-import { validateModeModelCompatibilityOrThrow } from './mode-model-validator.js';
-import { createMissingFileError } from './actionable-error-messages.js';
-import { handleError, ErrorCategory, ErrorSeverity, createError } from './error-handler.js';
+import { DatabaseConnectionManager } from '../core/database-connection-manager.js';
+import { createEmbedder } from '../core/embedder-factory.js';
+import { ContentResolver } from '../core/content-resolver.js';
+import { validateModeModelCompatibilityOrThrow } from '../core/mode-model-validator.js';
+import { createMissingFileError } from '../core/actionable-error-messages.js';
+import { handleError, ErrorCategory, ErrorSeverity, createError } from '../core/error-handler.js';
 import { existsSync } from 'fs';
 // =============================================================================
 // POLYMORPHIC SEARCH FACTORY
@@ -45,7 +45,7 @@ import { existsSync } from 'fs';
  *   - True cross-modal search capabilities
  *   - Text queries find images, image queries find text
  */
-export class PolymorphicSearchFactory {
+export class SearchFactory {
     /**
      * Create a SearchEngine with automatic mode detection and configuration
      *
@@ -78,7 +78,7 @@ export class PolymorphicSearchFactory {
      * @example
      * ```typescript
      * // Automatic mode detection and engine creation
-     * const search = await PolymorphicSearchFactory.create('./index.bin', './db.sqlite');
+     * const search = await SearchFactory.create('./index.bin', './db.sqlite');
      *
      * // Search works based on detected mode:
      * // Text mode: fast text similarity search
@@ -90,7 +90,7 @@ export class PolymorphicSearchFactory {
      */
     static async create(indexPath, dbPath) {
         try {
-            console.log('🎭 PolymorphicSearchFactory: Initializing search engine with mode detection...');
+            console.log('🎭 SearchFactory: Initializing search engine with mode detection...');
             // Step 1: Validate input paths
             if (!indexPath || !dbPath) {
                 throw createError.validation('Both indexPath and dbPath are required');
@@ -206,7 +206,7 @@ export class PolymorphicSearchFactory {
                 return undefined;
             }
             // Use lazy loading to avoid loading reranking dependencies unless needed
-            const { LazyRerankerLoader } = await import('./lazy-dependency-loader.js');
+            const { LazyRerankerLoader } = await import('../core/lazy-dependency-loader.js');
             // For text mode, use cross-encoder reranking
             if (strategy === 'cross-encoder') {
                 return LazyRerankerLoader.loadTextReranker();
@@ -228,7 +228,7 @@ export class PolymorphicSearchFactory {
                 return undefined;
             }
             // Use lazy loading to avoid loading multimodal dependencies unless needed
-            const { LazyDependencyManager } = await import('./lazy-dependency-loader.js');
+            const { LazyDependencyManager } = await import('../core/lazy-dependency-loader.js');
             // Load the appropriate reranker based on strategy
             return LazyDependencyManager.loadReranker(strategy);
         }
@@ -246,12 +246,12 @@ export class PolymorphicSearchFactory {
     static validateRequiredFiles(indexPath, dbPath) {
         if (!existsSync(indexPath)) {
             throw createMissingFileError(indexPath, 'index', {
-                operationContext: 'PolymorphicSearchFactory.create'
+                operationContext: 'SearchFactory.create'
             });
         }
         if (!existsSync(dbPath)) {
             throw createMissingFileError(dbPath, 'database', {
-                operationContext: 'PolymorphicSearchFactory.create'
+                operationContext: 'SearchFactory.create'
             });
         }
     }
@@ -262,7 +262,7 @@ export class PolymorphicSearchFactory {
     static enhanceCreationError(error, indexPath, dbPath) {
         if (error instanceof Error) {
             // Add context about the operation that failed
-            let enhancedMessage = `PolymorphicSearchFactory.create failed: ${error.message}`;
+            let enhancedMessage = `SearchFactory.create failed: ${error.message}`;
             // Provide specific guidance based on error type
             if (error.message.includes('ENOENT')) {
                 enhancedMessage += '\n\n💡 Make sure both the vector index and database files exist.';
@@ -283,7 +283,7 @@ export class PolymorphicSearchFactory {
             }
             return new Error(enhancedMessage);
         }
-        return new Error(`PolymorphicSearchFactory.create failed: Unknown error`);
+        return new Error(`SearchFactory.create failed: Unknown error`);
     }
 }
 // =============================================================================
@@ -291,7 +291,7 @@ export class PolymorphicSearchFactory {
 // =============================================================================
 /**
  * Quick function to create a search engine with automatic mode detection
- * Convenience wrapper around PolymorphicSearchFactory.create
+ * Convenience wrapper around SearchFactory.create
  *
  * @param indexPath - Path to the vector index file
  * @param dbPath - Path to the database file
@@ -299,12 +299,12 @@ export class PolymorphicSearchFactory {
  *
  * @example
  * ```typescript
- * const search = await createPolymorphicSearchEngine('./index.bin', './db.sqlite');
+ * const search = await createSearchEngine('./index.bin', './db.sqlite');
  * const results = await search.search('query');
  * ```
  */
-export async function createPolymorphicSearchEngine(indexPath, dbPath) {
-    return PolymorphicSearchFactory.create(indexPath, dbPath);
+export async function createSearchEngine(indexPath, dbPath) {
+    return SearchFactory.create(indexPath, dbPath);
 }
 /**
  * Check what mode a database is configured for
@@ -341,4 +341,4 @@ export async function getSearchEngineInfo(dbPath) {
     const modeService = new ModeDetectionService(dbPath);
     return modeService.detectMode();
 }
-//# sourceMappingURL=polymorphic-search-factory.js.map
+//# sourceMappingURL=search-factory.js.map