rag-lite-ts 2.1.0 → 2.2.0

package/dist/{file-processor.js → cjs/file-processor.js}

@@ -188,6 +188,15 @@ async function discoverFilesRecursive(dirPath, options) {
                         // Check file size based on content type
                         const stats = await fs.stat(fullPath);
                         const contentType = getContentType(fullPath);
+                        // Filter by mode: skip incompatible content types
+                        const mode = options.mode || 'text';
+                        if (mode === 'text' && contentType === 'image') {
+                            result.skipped.push({
+                                path: fullPath,
+                                reason: `Image files not supported in text mode. Use --mode multimodal for image processing.`
+                            });
+                            continue;
+                        }
                         // Different size limits for different content types
                         const maxSize = contentType === 'image'
                             ? 50 * 1024 * 1024 // 50MB for images
@@ -250,6 +259,17 @@ export async function discoverFiles(path, options = DEFAULT_FILE_PROCESSOR_OPTIO
                 };
             }
             const contentType = getContentType(resolvedPath);
+            // Filter by mode: skip incompatible content types
+            const mode = options.mode || 'text';
+            if (mode === 'text' && contentType === 'image') {
+                return {
+                    files: [],
+                    skipped: [{
+                            path: resolvedPath,
+                            reason: `Image files not supported in text mode. Use --mode multimodal for image processing.`
+                        }]
+                };
+            }
             // Check file size based on content type
             const maxSize = contentType === 'image'
                 ? 50 * 1024 * 1024 // 50MB for images

package/dist/{index-manager.d.ts → cjs/index-manager.d.ts}

@@ -7,12 +7,16 @@ export interface IndexStats {
 export declare class IndexManager {
     private modelName?;
     private vectorIndex;
+    private textIndex?;
+    private imageIndex?;
     private db;
     private indexPath;
     private dbPath;
     private isInitialized;
     private hashToEmbeddingId;
     private embeddingIdToHash;
+    private groupedEmbeddings?;
+    private vectorIndexOptions;
     constructor(indexPath: string, dbPath: string, dimensions: number, modelName?: string | undefined);
     /**
      * Initialize the index manager and load existing index if available
@@ -30,6 +34,10 @@ export declare class IndexManager {
      * Requirements: 5.3 - When new documents are added THEN system SHALL append new chunks and vectors without rebuilding existing index
      */
     addVectors(embeddings: EmbeddingResult[]): Promise<void>;
+    /**
+     * Add grouped embeddings by content type (for new grouped format)
+     */
+    addGroupedEmbeddings(textEmbeddings: EmbeddingResult[], imageEmbeddings: EmbeddingResult[]): Promise<void>;
     /**
      * Rebuild the entire index from scratch
      * Requirements: 5.2, 5.4 - Create full index rebuild functionality for model changes or document deletions
@@ -68,10 +76,18 @@ export declare class IndexManager {
      * Save the vector index to disk
      */
     saveIndex(): Promise<void>;
+    /**
+     * Create specialized indexes for text and image content when grouped data is available
+     */
+    private createSpecializedIndexes;
+    /**
+     * Save index with content type grouping (for new grouped format)
+     */
+    saveGroupedIndex(textEmbeddings: EmbeddingResult[], imageEmbeddings: EmbeddingResult[]): Promise<void>;
     /**
      * Search for similar vectors
      */
-    search(queryVector: Float32Array, k?: number): {
+    search(queryVector: Float32Array, k?: number, contentType?: 'text' | 'image' | 'combined'): {
         embeddingIds: string[];
         distances: number[];
     };

package/dist/{index-manager.js → cjs/index-manager.js}

@@ -1,26 +1,33 @@
 import { VectorIndex } from './core/vector-index.js';
+import { BinaryIndexFormat } from './core/binary-index-format.js';
 import { openDatabase, getSystemInfo, setSystemInfo } from './core/db.js';
 import { config, getModelDefaults } from './core/config.js';
 export class IndexManager {
     modelName;
     vectorIndex;
+    textIndex;
+    imageIndex;
     db = null;
     indexPath;
     dbPath;
     isInitialized = false;
     hashToEmbeddingId = new Map();
     embeddingIdToHash = new Map();
+    groupedEmbeddings;
+    vectorIndexOptions;
     constructor(indexPath, dbPath, dimensions, modelName) {
         this.modelName = modelName;
         this.indexPath = indexPath;
         this.dbPath = dbPath;
-        // Initialize with provided dimensions from config
-        this.vectorIndex = new VectorIndex(indexPath, {
+        // Store options for creating specialized indexes
+        this.vectorIndexOptions = {
             dimensions: dimensions,
             maxElements: 100000, // Start with 100k capacity
             efConstruction: 200,
             M: 16
-        });
+        };
+        // Initialize with provided dimensions from config
+        this.vectorIndex = new VectorIndex(indexPath, this.vectorIndexOptions);
     }
     /**
      * Initialize the index manager and load existing index if available
@@ -47,6 +54,8 @@ export class IndexManager {
                 // Only try to load existing index if not forcing recreation
                 console.log('Loading existing vector index...');
                 await this.vectorIndex.loadIndex();
+                // Check if the loaded index has grouped data and create specialized indexes
+                await this.createSpecializedIndexes();
             }
             // Always populate the embedding ID mapping from existing database entries
             // This is needed both for new and existing indexes
@@ -55,7 +64,8 @@ export class IndexManager {
                 this.hashEmbeddingId(chunk.embedding_id); // This will populate the mapping
             }
             this.isInitialized = true;
-            console.log(`Index manager initialized with ${this.vectorIndex.getCurrentCount()} vectors`);
+            const vectorCount = this.vectorIndex.getCurrentCount();
+            console.log(`Index manager initialized with ${vectorCount} vectors${this.textIndex && this.imageIndex ? ' (multi-graph mode)' : ''}`);
         }
         catch (error) {
             throw new Error(`Failed to initialize index manager: ${error}`);
@@ -153,6 +163,31 @@ export class IndexManager {
             throw new Error(`Failed to add vectors to index: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
+    /**
+     * Add grouped embeddings by content type (for new grouped format)
+     */
+    async addGroupedEmbeddings(textEmbeddings, imageEmbeddings) {
+        if (!this.isInitialized) {
+            throw new Error('Index manager not initialized');
+        }
+        console.log(`addGroupedEmbeddings: text=${textEmbeddings.length}, image=${imageEmbeddings.length}`);
+        const allEmbeddings = [...textEmbeddings, ...imageEmbeddings];
+        if (allEmbeddings.length === 0) {
+            return;
+        }
+        try {
+            // Store grouped information for later saving
+            this.groupedEmbeddings = { text: textEmbeddings, image: imageEmbeddings };
+            console.log('addGroupedEmbeddings: stored grouped embeddings');
+            // Add all embeddings to the index (maintains current behavior)
+            await this.addVectors(allEmbeddings);
+            console.log('addGroupedEmbeddings: addVectors completed');
+            // The saveIndex method will now use grouped format if groupedEmbeddings exists
+        }
+        catch (error) {
+            throw new Error(`Failed to add grouped embeddings to index: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        }
+    }
     /**
      * Rebuild the entire index from scratch
      * Requirements: 5.2, 5.4 - Create full index rebuild functionality for model changes or document deletions
@@ -349,16 +384,122 @@ export class IndexManager {
         if (!this.isInitialized) {
             throw new Error('Index manager not initialized');
         }
-        await this.vectorIndex.saveIndex();
+        // If we have grouped embeddings, save in grouped format
+        if (this.groupedEmbeddings) {
+            console.log('IndexManager: Saving in grouped format');
+            await this.saveGroupedIndex(this.groupedEmbeddings.text, this.groupedEmbeddings.image);
+            // Clear grouped data after saving
+            this.groupedEmbeddings = undefined;
+        }
+        else {
+            console.log('IndexManager: Saving in standard format');
+            await this.vectorIndex.saveIndex();
+        }
+    }
+    /**
+     * Create specialized indexes for text and image content when grouped data is available
+     */
+    async createSpecializedIndexes() {
+        try {
+            // Load the index data to check if it has grouped information
+            const indexData = await BinaryIndexFormat.load(this.indexPath);
+            if (indexData.hasContentTypeGroups && indexData.textVectors && indexData.imageVectors) {
+                // Only create specialized indexes if we have both text and image vectors
+                // In text-only mode, textVectors would be populated but imageVectors empty
+                // In multimodal mode, both would be populated
+                const hasTextVectors = indexData.textVectors.length > 0;
+                const hasImageVectors = indexData.imageVectors.length > 0;
+                if (hasTextVectors && hasImageVectors) {
+                    console.log('Creating specialized indexes for content type filtering...');
+                    // Create text-only index
+                    this.textIndex = new VectorIndex(`${this.indexPath}.text`, this.vectorIndexOptions);
+                    await this.textIndex.initialize();
+                    this.textIndex.addVectors(indexData.textVectors);
+                    console.log(`✓ Text index created with ${indexData.textVectors.length} vectors`);
+                    // Create image-only index
+                    this.imageIndex = new VectorIndex(`${this.indexPath}.image`, this.vectorIndexOptions);
+                    await this.imageIndex.initialize();
+                    this.imageIndex.addVectors(indexData.imageVectors);
+                    console.log(`✓ Image index created with ${indexData.imageVectors.length} vectors`);
+                    console.log('✓ Specialized indexes ready for content type filtering');
+                }
+                else if (hasTextVectors) {
+                    console.log('Text-only index detected - using combined index for all searches');
+                    // In text-only mode, we don't need specialized indexes
+                    // The combined index (vectorIndex) already contains all text vectors
+                }
+            }
+        }
+        catch (error) {
+            console.warn('Failed to create specialized indexes, falling back to combined index:', error);
+            // Continue without specialized indexes - search will still work with combined index
+        }
+    }
+    /**
+     * Save index with content type grouping (for new grouped format)
+     */
+    async saveGroupedIndex(textEmbeddings, imageEmbeddings) {
+        if (!this.isInitialized) {
+            throw new Error('Index manager not initialized');
+        }
+        console.log(`saveGroupedIndex: text=${textEmbeddings.length}, image=${imageEmbeddings.length}`);
+        // Group vectors by content type
+        const textVectors = textEmbeddings.map((embedding) => ({
+            id: this.hashEmbeddingId(embedding.embedding_id),
+            vector: embedding.vector
+        }));
+        const imageVectors = imageEmbeddings.map((embedding) => ({
+            id: this.hashEmbeddingId(embedding.embedding_id),
+            vector: embedding.vector
+        }));
+        // Get index parameters
+        const options = this.vectorIndex.getOptions();
+        const allVectors = [...textVectors, ...imageVectors];
+        console.log(`saveGroupedIndex: dimensions=${options.dimensions}, totalVectors=${allVectors.length}`);
+        const indexData = {
+            dimensions: options.dimensions,
+            maxElements: options.maxElements,
+            M: options.M || 16,
+            efConstruction: options.efConstruction || 200,
+            seed: options.seed || 100,
+            currentSize: textVectors.length + imageVectors.length,
+            vectors: allVectors, // Required for backward compatibility
+            hasContentTypeGroups: true,
+            textVectors,
+            imageVectors
+        };
+        console.log('saveGroupedIndex: Calling BinaryIndexFormat.saveGrouped');
+        // Save using grouped format
+        await BinaryIndexFormat.saveGrouped(this.indexPath, indexData);
+        console.log(`✓ Saved grouped index with ${textVectors.length} text and ${imageVectors.length} image vectors`);
     }
     /**
      * Search for similar vectors
      */
-    search(queryVector, k = 5) {
+    search(queryVector, k = 5, contentType) {
         if (!this.isInitialized) {
             throw new Error('Index manager not initialized');
         }
-        const results = this.vectorIndex.search(queryVector, k);
+        // Select the appropriate index based on content type
+        let targetIndex;
+        // If we have specialized indexes (multimodal mode), use them for filtering
+        if (this.textIndex && this.imageIndex) {
+            if (contentType === 'text') {
+                targetIndex = this.textIndex;
+            }
+            else if (contentType === 'image') {
+                targetIndex = this.imageIndex;
+            }
+            else {
+                // 'combined' or undefined
+                targetIndex = this.vectorIndex;
+            }
+        }
+        else {
+            // No specialized indexes (text-only mode) - ignore contentType and use combined index
+            targetIndex = this.vectorIndex;
+        }
+        const results = targetIndex.search(queryVector, k);
         // Convert numeric IDs back to embedding IDs
         const embeddingIds = results.neighbors.map(id => this.unhashEmbeddingId(id));
         return {

package/dist/{multimodal → cjs/multimodal}/clip-embedder.js

@@ -338,73 +338,78 @@ export class CLIPEmbedder extends BaseUniversalEmbedder {
         if (!this.textModel || !this.tokenizer) {
             throw new Error('CLIP text model or tokenizer not initialized');
         }
-        // Use the validated CLIPTextModelWithProjection approach (no pixel_values errors)
-        // Tokenize text with CLIP's requirements
-        // The tokenizer handles truncation at 77 TOKENS (not characters)
-        const tokens = await this.tokenizer(processedText, {
-            padding: true,
-            truncation: true,
-            max_length: 77, // CLIP's text sequence length limit (77 tokens)
-            return_tensors: 'pt'
-        });
-        // Log token information for debugging (only in development)
-        if (process.env.NODE_ENV === 'development') {
-            const tokenIds = tokens.input_ids?.data || [];
-            const actualTokenCount = Array.from(tokenIds).filter((id) => id !== 0).length;
-            if (actualTokenCount >= 77) {
-                console.warn(`Text truncated by tokenizer: "${processedText.substring(0, 50)}..." (truncated to 77 tokens)`);
-            }
-        }
-        // Generate text embedding using CLIPTextModelWithProjection
-        const output = await this.textModel(tokens);
-        // Extract embedding from text_embeds (no pixel_values dependency)
-        const embedding = new Float32Array(output.text_embeds.data);
-        // Validate embedding dimensions and values
-        if (embedding.length !== this.dimensions) {
-            throw new Error(`CLIP embedding dimension mismatch: expected ${this.dimensions}, got ${embedding.length}`);
-        }
-        // Validate that all values are finite numbers
-        const invalidValues = Array.from(embedding).filter(val => !isFinite(val) || isNaN(val));
-        if (invalidValues.length > 0) {
-            throw new Error(`CLIP embedding contains ${invalidValues.length} invalid values`);
-        }
-        // Validate embedding quality - should not be all zeros
-        const nonZeroValues = Array.from(embedding).filter(val => Math.abs(val) > 1e-8);
-        if (nonZeroValues.length === 0) {
-            throw new Error('CLIP embedding is all zeros');
-        }
-        // Calculate embedding magnitude before normalization for quality assessment
-        const magnitudeBeforeNorm = Math.sqrt(Array.from(embedding).reduce((sum, val) => sum + val * val, 0));
-        if (magnitudeBeforeNorm < 1e-6) {
-            throw new Error(`CLIP embedding has critically low magnitude: ${magnitudeBeforeNorm.toExponential(3)}`);
-        }
-        // Apply L2-normalization (CLIP models are trained with normalized embeddings)
-        this.normalizeEmbedding(embedding);
-        // Verify normalization was successful
-        const magnitudeAfterNorm = Math.sqrt(Array.from(embedding).reduce((sum, val) => sum + val * val, 0));
-        if (Math.abs(magnitudeAfterNorm - 1.0) > 0.01) {
-            console.warn(`Warning: Embedding normalization may be imprecise (magnitude: ${magnitudeAfterNorm.toFixed(6)})`);
-        }
-        // Log text embedding generation
-        console.log(`[CLIP] Generated text embedding for: "${processedText.substring(0, 30)}${processedText.length > 30 ? '...' : ''}"`);
-        // Generate unique embedding ID
-        const embeddingId = this.generateEmbeddingId(processedText, 'text');
-        return {
-            embedding_id: embeddingId,
-            vector: embedding,
-            contentType: 'text',
-            metadata: {
-                originalText: text,
-                processedText: processedText,
-                textLength: processedText.length,
-                embeddingMagnitudeBeforeNorm: magnitudeBeforeNorm,
-                embeddingMagnitudeAfterNorm: magnitudeAfterNorm,
-                normalized: true,
-                modelName: this.modelName,
-                modelType: this.modelType,
-                dimensions: this.dimensions
+        try {
+            // Use the validated CLIPTextModelWithProjection approach (no pixel_values errors)
+            // Tokenize text with CLIP's requirements
+            // The tokenizer handles truncation at 77 TOKENS (not characters)
+            const tokens = await this.tokenizer(processedText, {
+                padding: true,
+                truncation: true,
+                max_length: 77, // CLIP's text sequence length limit (77 tokens)
+                return_tensors: 'pt'
+            });
+            // Log token information for debugging (only in development)
+            if (process.env.NODE_ENV === 'development') {
+                const tokenIds = tokens.input_ids?.data || [];
+                const actualTokenCount = Array.from(tokenIds).filter((id) => id !== 0).length;
+                if (actualTokenCount >= 77) {
+                    console.warn(`Text truncated by tokenizer: "${processedText.substring(0, 50)}..." (truncated to 77 tokens)`);
+                }
             }
-        };
+            // Generate text embedding using CLIPTextModelWithProjection
+            const output = await this.textModel(tokens);
+            // Extract embedding from text_embeds (no pixel_values dependency)
+            const embedding = new Float32Array(output.text_embeds.data);
+            // Validate embedding dimensions and values
+            if (embedding.length !== this.dimensions) {
+                throw new Error(`CLIP embedding dimension mismatch: expected ${this.dimensions}, got ${embedding.length}`);
+            }
+            // Validate that all values are finite numbers
+            const invalidValues = Array.from(embedding).filter(val => !isFinite(val) || isNaN(val));
+            if (invalidValues.length > 0) {
+                throw new Error(`CLIP embedding contains ${invalidValues.length} invalid values`);
+            }
+            // Validate embedding quality - should not be all zeros
+            const nonZeroValues = Array.from(embedding).filter(val => Math.abs(val) > 1e-8);
+            if (nonZeroValues.length === 0) {
+                throw new Error('CLIP embedding is all zeros');
+            }
+            // Calculate embedding magnitude before normalization for quality assessment
+            const magnitudeBeforeNorm = Math.sqrt(Array.from(embedding).reduce((sum, val) => sum + val * val, 0));
+            if (magnitudeBeforeNorm < 1e-6) {
+                throw new Error(`CLIP embedding has critically low magnitude: ${magnitudeBeforeNorm.toExponential(3)}`);
+            }
+            // Apply L2-normalization (CLIP models are trained with normalized embeddings)
+            this.normalizeEmbedding(embedding);
+            // Verify normalization was successful
+            const magnitudeAfterNorm = Math.sqrt(Array.from(embedding).reduce((sum, val) => sum + val * val, 0));
+            if (Math.abs(magnitudeAfterNorm - 1.0) > 0.01) {
+                console.warn(`Warning: Embedding normalization may be imprecise (magnitude: ${magnitudeAfterNorm.toFixed(6)})`);
+            }
+            // Log text embedding generation
+            console.log(`[CLIP] Generated text embedding for: "${processedText.substring(0, 30)}${processedText.length > 30 ? '...' : ''}"`);
+            // Generate unique embedding ID
+            const embeddingId = this.generateEmbeddingId(processedText, 'text');
+            return {
+                embedding_id: embeddingId,
+                vector: embedding,
+                contentType: 'text',
+                metadata: {
+                    originalText: text,
+                    processedText: processedText,
+                    textLength: processedText.length,
+                    embeddingMagnitudeBeforeNorm: magnitudeBeforeNorm,
+                    embeddingMagnitudeAfterNorm: magnitudeAfterNorm,
+                    normalized: true,
+                    modelName: this.modelName,
+                    modelType: this.modelType,
+                    dimensions: this.dimensions
+                }
+            };
+        }
+        catch (error) {
+            throw error;
+        }
     }
     // =============================================================================
     // IMAGE EMBEDDING METHODS

package/dist/esm/api-errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * User-friendly error classes with actionable suggestions
+ * Requirements: 5.3 - Create user-friendly error classes with actionable suggestions
+ */
+/**
+ * Base class for API errors with actionable suggestions
+ */
+export declare abstract class APIError extends Error {
+    code: string;
+    suggestions: string[];
+    context?: string | undefined;
+    constructor(message: string, code: string, suggestions: string[], context?: string | undefined);
+    /**
+     * Get formatted error message with suggestions
+     */
+    getFormattedMessage(): string;
+    /**
+     * Log the error with proper formatting
+     */
+    logError(): void;
+}
+/**
+ * Ingestion-related errors
+ */
+export declare class IngestionError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Search-related errors
+ */
+export declare class SearchError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Resource management errors
+ */
+export declare class ResourceError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Model compatibility errors
+ */
+export declare class ModelCompatibilityError extends APIError {
+    constructor(message: string, code: string, suggestions: string[], context?: string);
+}
+/**
+ * Error factory for creating user-friendly errors from internal errors
+ * Requirements: 5.3 - Map internal errors to clear guidance
+ */
+export declare class ErrorFactory {
+    /**
+     * Create user-friendly ingestion error from internal error
+     */
+    static createIngestionError(error: unknown, context: string): IngestionError;
+    /**
+     * Create user-friendly search error from internal error
+     */
+    static createSearchError(error: unknown, context: string): SearchError;
+    /**
+     * Create user-friendly resource error from internal error
+     */
+    static createResourceError(error: unknown, context: string): ResourceError;
+}
+/**
+ * Common error scenarios with predefined messages and suggestions
+ * Requirements: 5.3 - Add specific error handling for common scenarios
+ */
+export declare const CommonErrors: {
+    /**
+     * Error when trying to search without running ingestion first
+     */
+    NO_DOCUMENTS_INGESTED: SearchError;
+    /**
+     * Error when model versions don't match
+     */
+    MODEL_VERSION_MISMATCH: ModelCompatibilityError;
+    /**
+     * Error when required files are missing
+     */
+    MISSING_REQUIRED_FILES: SearchError;
+    /**
+     * Error when initialization fails
+     */
+    INITIALIZATION_FAILED: ResourceError;
+};
+/**
+ * Utility function to handle and log errors appropriately
+ */
+export declare function handleAPIError(error: unknown, context: string, operation: 'ingestion' | 'search' | 'resource'): never;
+//# sourceMappingURL=api-errors.d.ts.map