rag-lite-ts 1.0.1 → 1.0.2

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

@@ -0,0 +1,466 @@
+/**
+ * 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
+ * - Handles error recovery and validation
+ * - Supports different embedding models and configurations
+ * - Enables clean separation between simple usage and advanced customization
+ *
+ * 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. Error Recovery:
+ * ```typescript
+ * // Create with automatic fallback options
+ * const search = await TextFactoryHelpers.createSearchWithFallback(
+ *   './index.bin',
+ *   './db.sqlite',
+ *   { enableReranking: true } // Will fallback to disabled if reranking fails
+ * );
+ * ```
+ */
+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;
+}
+/**
+ * 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;
+}
+/**
+ * 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
+ *
+ * @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 graceful fallback)
+     * - 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. 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
+ *
+ * @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)
+     * @returns Promise resolving to configured IngestionPipeline
+     * @throws {Error} If initialization fails
+     *
+     * @example
+     * ```typescript
+     * // Create ingestion pipeline
+     * const ingestion = await TextIngestionFactory.create('./my-db.sqlite', './my-index.bin');
+     *
+     * // Ingest documents from directory
+     * const result = await ingestion.ingestDirectory('./documents');
+     * console.log(`Processed ${result.documentsProcessed} documents`);
+     *
+     * // Ingest single file
+     * await ingestion.ingestFile('./document.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>;
+}
+/**
+ * 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 automatic error recovery
+ * const search = await TextFactoryHelpers.createSearchWithFallback('./index.bin', './db.sqlite', {
+ *   enableReranking: true // Will fallback to disabled if reranking fails
+ * });
+ * ```
+ */
+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 automatic error recovery
+     *
+     * 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.
+     *
+     * @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
+     *
+     * @example
+     * ```typescript
+     * // Try to create with reranking, fallback to without if it fails
+     * const search = await TextFactoryHelpers.createSearchWithFallback(
+     *   './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>;
+}
+//# sourceMappingURL=text-factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"text-factory.d.ts","sourceRoot":"","sources":["../../src/factories/text-factory.ts"],"names":[],"mappings":"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"}