rag-lite-ts 2.0.3 → 2.0.4

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

@@ -1,560 +0,0 @@
-/**
- * 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. Simple Search Setup:
- * ```typescript
- * // Create search engine with defaults
- * const search = await TextSearchFactory.create('./index.bin', './db.sqlite');
- * const results = await search.search('query');
- * ```
- *
- * 2. Custom Configuration:
- * ```typescript
- * // Create with custom options
- * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', {
- *   embeddingModel: 'all-MiniLM-L6-v2',
- *   enableReranking: true,
- *   topK: 20
- * });
- * ```
- *
- * 3. Complete RAG System:
- * ```typescript
- * // Create both ingestion and search
- * const { searchEngine, ingestionPipeline } = await TextRAGFactory.createBoth(
- *   './index.bin',
- *   './db.sqlite'
- * );
- *
- * // Ingest documents
- * await ingestionPipeline.ingestDirectory('./docs');
- *
- * // Search documents
- * const results = await searchEngine.search('query');
- * ```
- *
- * 4. Clear Error Handling:
- * ```typescript
- * // Create with clear validation and error reporting
- * const search = await TextFactoryHelpers.createSearchWithValidation(
- *   './index.bin',
- *   './db.sqlite',
- *   { 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';
-/**
- * Options for text search factory
- */
-export interface TextSearchOptions {
-    /** Embedding model name override */
-    embeddingModel?: string;
-    /** Embedding batch size override */
-    batchSize?: number;
-    /** Reranking model name override */
-    rerankingModel?: string;
-    /** Whether to enable reranking (default: true) */
-    enableReranking?: boolean;
-    /** 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
- */
-export interface TextIngestionOptions {
-    /** Embedding model name override */
-    embeddingModel?: string;
-    /** Embedding batch size override */
-    batchSize?: number;
-    /** Chunk size override */
-    chunkSize?: number;
-    /** Chunk overlap override */
-    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. 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
- * // Basic usage
- * const search = await TextSearchFactory.create('./index.bin', './db.sqlite');
- * const results = await search.search('What is machine learning?');
- *
- * // With custom configuration
- * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', {
- *   embeddingModel: 'all-MiniLM-L6-v2',
- *   enableReranking: true,
- *   topK: 15
- * });
- *
- * // With defaults (uses config file paths)
- * const search = await TextSearchFactory.createWithDefaults({
- *   enableReranking: false // Faster search
- * });
- * ```
- */
-export declare class TextSearchFactory {
-    /**
-     * Create a SearchEngine configured for text search
-     *
-     * This method handles the complete initialization process:
-     * - Validates that required files exist
-     * - Loads text embedding model (with lazy initialization)
-     * - 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
-     * - Validates the complete setup
-     *
-     * @param indexPath - Path to the vector index file (must exist)
-     * @param dbPath - Path to the SQLite database file (must 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.rerankingModel - Override reranking model (default: from config)
-     * @param options.enableReranking - Enable/disable reranking (default: true)
-     * @param options.topK - Number of results to return (default: from config)
-     * @returns Promise resolving to configured SearchEngine
-     * @throws {Error} If required files don't exist or initialization fails
-     *
-     * @example
-     * ```typescript
-     * // Create search engine for existing index
-     * const search = await TextSearchFactory.create('./my-index.bin', './my-db.sqlite');
-     *
-     * // Search with the created engine
-     * const results = await search.search('artificial intelligence');
-     * console.log(`Found ${results.length} results`);
-     *
-     * // Clean up when done
-     * await search.cleanup();
-     * ```
-     */
-    static create(indexPath: string, dbPath: string, options?: TextSearchOptions): Promise<SearchEngine>;
-    /**
-     * Create a SearchEngine with automatic path resolution
-     * Uses default paths from configuration (config.index_file, config.db_file)
-     *
-     * This is a convenience method that uses the default file paths from the configuration,
-     * making it easy to create a search engine without specifying paths explicitly.
-     *
-     * @param options - Optional configuration overrides
-     * @param options.embeddingModel - Override embedding model
-     * @param options.enableReranking - Enable/disable reranking
-     * @param options.topK - Number of results to return
-     * @returns Promise resolving to configured SearchEngine
-     * @throws {Error} If default files don't exist or initialization fails
-     *
-     * @example
-     * ```typescript
-     * // Use default paths from config
-     * const search = await TextSearchFactory.createWithDefaults();
-     *
-     * // Use defaults with custom options
-     * const search = await TextSearchFactory.createWithDefaults({
-     *   enableReranking: false,
-     *   topK: 5
-     * });
-     * ```
-     */
-    static createWithDefaults(options?: TextSearchOptions): Promise<SearchEngine>;
-}
-/**
- * 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 TextIngestionFactory.create('./db.sqlite', './index.bin');
- * await ingestion.ingestDirectory('./documents');
- *
- * // With custom configuration
- * const ingestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', {
- *   embeddingModel: 'all-MiniLM-L6-v2',
- *   chunkSize: 512,
- *   chunkOverlap: 50,
- *   forceRebuild: true
- * });
- *
- * // With defaults
- * const ingestion = await TextIngestionFactory.createWithDefaults({
- *   batchSize: 32 // Faster processing
- * });
- * ```
- */
-export declare class TextIngestionFactory {
-    /**
-     * 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 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 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 create(dbPath: string, indexPath: string, options?: TextIngestionOptions): Promise<IngestionPipeline>;
-    /**
-     * 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 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
- * Useful for applications that need both capabilities with shared configuration
- *
- * This factory creates a complete RAG (Retrieval-Augmented Generation) system
- * by initializing both ingestion and search capabilities with shared resources.
- * The ingestion pipeline is created first to handle directory creation and
- * initial setup, then the search engine is created to use the same resources.
- *
- * @example
- * ```typescript
- * // Create complete RAG system
- * const { searchEngine, ingestionPipeline } = await TextRAGFactory.createBoth(
- *   './index.bin',
- *   './db.sqlite'
- * );
- *
- * // First, ingest some documents
- * await ingestionPipeline.ingestDirectory('./knowledge-base');
- *
- * // Then search the ingested content
- * const results = await searchEngine.search('What is the main topic?');
- *
- * // Clean up both instances
- * await Promise.all([
- *   searchEngine.cleanup(),
- *   ingestionPipeline.cleanup()
- * ]);
- * ```
- */
-export declare class TextRAGFactory {
-    /**
-     * Create both SearchEngine and IngestionPipeline instances
-     *
-     * This method creates a complete RAG system by:
-     * 1. Creating an ingestion pipeline (handles directory creation)
-     * 2. Creating a search engine (uses the same database and index)
-     * 3. Ensuring both instances use compatible configurations
-     *
-     * The ingestion pipeline is created first because it handles directory
-     * creation and initial setup, while the search engine requires existing
-     * files to validate the setup.
-     *
-     * @param indexPath - Path to the vector index file
-     * @param dbPath - Path to the SQLite database file
-     * @param searchOptions - Optional search configuration
-     * @param searchOptions.enableReranking - Enable reranking for better results
-     * @param searchOptions.topK - Number of search results to return
-     * @param ingestionOptions - Optional ingestion configuration
-     * @param ingestionOptions.chunkSize - Size of text chunks for processing
-     * @param ingestionOptions.forceRebuild - Force rebuild of existing index
-     * @returns Promise resolving to both configured instances
-     * @throws {Error} If initialization of either component fails
-     *
-     * @example
-     * ```typescript
-     * // Create with custom options for both components
-     * const { searchEngine, ingestionPipeline } = await TextRAGFactory.createBoth(
-     *   './index.bin',
-     *   './db.sqlite',
-     *   { enableReranking: true, topK: 15 }, // Search options
-     *   { chunkSize: 512, forceRebuild: true } // Ingestion options
-     * );
-     *
-     * // Use the complete system
-     * await ingestionPipeline.ingestDirectory('./docs');
-     * const results = await searchEngine.search('machine learning');
-     * ```
-     */
-    static createBoth(indexPath: string, dbPath: string, searchOptions?: TextSearchOptions, ingestionOptions?: TextIngestionOptions): Promise<{
-        searchEngine: SearchEngine;
-        ingestionPipeline: IngestionPipeline;
-    }>;
-    /**
-     * Create both instances with default paths
-     * @param searchOptions - Optional search configuration
-     * @param ingestionOptions - Optional ingestion configuration
-     * @returns Promise resolving to both instances
-     */
-    static createBothWithDefaults(searchOptions?: TextSearchOptions, ingestionOptions?: TextIngestionOptions): Promise<{
-        searchEngine: SearchEngine;
-        ingestionPipeline: IngestionPipeline;
-    }>;
-}
-/**
- * Helper functions for common factory patterns and error recovery
- *
- * This class provides utility functions that support the main factory classes
- * with validation, configuration recommendations, and error recovery patterns.
- * These helpers enable more robust factory usage and better error handling.
- *
- * @example
- * ```typescript
- * // Validate files before creating search engine
- * try {
- *   TextFactoryHelpers.validateSearchFiles('./index.bin', './db.sqlite');
- *   const search = await TextSearchFactory.create('./index.bin', './db.sqlite');
- * } catch (error) {
- *   console.error('Files not ready for search:', error.message);
- * }
- *
- * // Get recommended configuration for different use cases
- * const { searchOptions, ingestionOptions } = TextFactoryHelpers.getRecommendedConfig('quality');
- * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', searchOptions);
- *
- * // 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
- * });
- * ```
- */
-export declare class TextFactoryHelpers {
-    /**
-     * Validate that required files exist for search operations
-     *
-     * This method checks that both the vector index and database files exist
-     * and provides helpful error messages with suggestions for resolution.
-     * Use this before attempting to create a search engine to get better
-     * error messages than the generic file not found errors.
-     *
-     * @param indexPath - Path to vector index file
-     * @param dbPath - Path to database file
-     * @throws {Error} If either file doesn't exist, with helpful resolution steps
-     *
-     * @example
-     * ```typescript
-     * // Validate before creating search engine
-     * try {
-     *   TextFactoryHelpers.validateSearchFiles('./index.bin', './db.sqlite');
-     *   console.log('Files are ready for search');
-     * } catch (error) {
-     *   console.error('Search files not ready:', error.message);
-     *   // Error message includes suggestions like "Run ingestion first"
-     * }
-     * ```
-     */
-    static validateSearchFiles(indexPath: string, dbPath: string): void;
-    /**
-     * Get recommended configuration for different use cases
-     *
-     * This method provides pre-configured options optimized for different
-     * performance vs quality trade-offs. Use these as starting points
-     * and adjust based on your specific requirements.
-     *
-     * @param useCase - The intended use case scenario
-     * @param useCase.fast - Optimized for speed (no reranking, smaller chunks)
-     * @param useCase.balanced - Good balance of speed and quality (default)
-     * @param useCase.quality - Optimized for best results (reranking enabled, larger chunks)
-     * @returns Recommended configuration for both search and ingestion
-     *
-     * @example
-     * ```typescript
-     * // Get configuration for quality-focused use case
-     * const { searchOptions, ingestionOptions } = TextFactoryHelpers.getRecommendedConfig('quality');
-     *
-     * // Create instances with recommended settings
-     * const ingestion = await TextIngestionFactory.create('./db.sqlite', './index.bin', ingestionOptions);
-     * const search = await TextSearchFactory.create('./index.bin', './db.sqlite', searchOptions);
-     *
-     * // Or use with RAG factory
-     * const { searchEngine, ingestionPipeline } = await TextRAGFactory.createBoth(
-     *   './index.bin',
-     *   './db.sqlite',
-     *   searchOptions,
-     *   ingestionOptions
-     * );
-     * ```
-     */
-    static getRecommendedConfig(useCase: 'fast' | 'balanced' | 'quality'): {
-        searchOptions: TextSearchOptions;
-        ingestionOptions: TextIngestionOptions;
-    };
-    /**
-     * Create a search engine with clear error reporting
-     *
-     * 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 - Configuration options
-     * @returns Promise resolving to SearchEngine
-     * @throws {Error} If creation fails with clear error message
-     *
-     * @example
-     * ```typescript
-     * // Create search engine with clear error handling
-     * const search = await TextFactoryHelpers.createSearchWithValidation(
-     *   './index.bin',
-     *   './db.sqlite',
-     *   { enableReranking: true, topK: 20 }
-     * );
-     *
-     * const results = await search.search('query');
-     * console.log(`Search created successfully with ${results.length} results`);
-     * ```
-     */
-    static createSearchWithValidation(indexPath: string, dbPath: string, options?: TextSearchOptions): Promise<SearchEngine>;
-}
-//# sourceMappingURL=text-factory.d.ts.map