rag-lite-ts 2.0.5 → 2.1.1

package/dist/cli/indexer.js

@@ -11,14 +11,14 @@ import { EXIT_CODES, ConfigurationError } from '../core/config.js';
 async function validateModeConfiguration(options) {
     const mode = options.mode || 'text';
     const model = options.embeddingModel;
-    const rerankingStrategy = options.rerankingStrategy;
     // Define supported models for each mode
     const textModels = [
         'sentence-transformers/all-MiniLM-L6-v2',
         'Xenova/all-mpnet-base-v2'
     ];
     const multimodalModels = [
-        'Xenova/clip-vit-base-patch32'
+        'Xenova/clip-vit-base-patch32',
+        'Xenova/clip-vit-base-patch16'
     ];
     // Validate model compatibility with mode
     if (model) {
@@ -64,35 +64,6 @@ async function validateModeConfiguration(options) {
             }
         }
     }
-    // Validate reranking strategy compatibility with mode
-    if (rerankingStrategy) {
-        const textStrategies = ['cross-encoder', 'disabled'];
-        const multimodalStrategies = ['text-derived', 'metadata', 'disabled'];
-        if (mode === 'text' && !textStrategies.includes(rerankingStrategy)) {
-            throw new ConfigurationError(`Reranking strategy '${rerankingStrategy}' is not supported for text mode.\n` +
-                `\n` +
-                `Supported strategies for text mode:\n` +
-                `  cross-encoder  Use cross-encoder model for reranking (default)\n` +
-                `  disabled       No reranking, use vector similarity only\n` +
-                `\n` +
-                `Examples:\n` +
-                `  raglite ingest <path> --mode text --rerank-strategy cross-encoder\n` +
-                `  raglite ingest <path> --mode text --rerank-strategy disabled\n`, EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        if (mode === 'multimodal' && !multimodalStrategies.includes(rerankingStrategy)) {
-            throw new ConfigurationError(`Reranking strategy '${rerankingStrategy}' is not supported for multimodal mode.\n` +
-                `\n` +
-                `Supported strategies for multimodal mode:\n` +
-                `  text-derived  Convert images to text, then use cross-encoder (default)\n` +
-                `  metadata      Use filename and metadata-based scoring\n` +
-                `  disabled      No reranking, use vector similarity only\n` +
-                `\n` +
-                `Examples:\n` +
-                `  raglite ingest <path> --mode multimodal --rerank-strategy text-derived\n` +
-                `  raglite ingest <path> --mode multimodal --rerank-strategy metadata\n` +
-                `  raglite ingest <path> --mode multimodal --rerank-strategy disabled\n`, EXIT_CODES.INVALID_ARGUMENTS);
-        }
-    }
     // Log the final configuration
     console.log('✅ Mode configuration validated successfully');
     if (mode !== 'text') {
@@ -101,9 +72,6 @@ async function validateModeConfiguration(options) {
     if (model) {
         console.log(`   Model: ${model}`);
     }
-    if (rerankingStrategy) {
-        console.log(`   Reranking: ${rerankingStrategy}`);
-    }
 }
 /**
  * Run document ingestion from CLI
@@ -191,10 +159,6 @@ export async function runIngest(path, options = {}) {
             factoryOptions.mode = options.mode;
             console.log(`Using processing mode: ${options.mode}`);
         }
-        if (options['rerank-strategy']) {
-            factoryOptions.rerankingStrategy = options['rerank-strategy'];
-            console.log(`Using reranking strategy: ${options['rerank-strategy']}`);
-        }
         if (options.rebuildIfNeeded) {
             factoryOptions.forceRebuild = true;
             console.log('Force rebuild enabled due to rebuildIfNeeded option');
@@ -234,7 +198,7 @@ export async function runIngest(path, options = {}) {
                 showProgress: true,
                 maxWaitMs: 15000 // Longer timeout for ingestion
             });
-            const result = await pipeline.ingestPath(resolvedPath);
+            const result = await pipeline.ingestPath(resolvedPath, { mode: factoryOptions.mode });
             // Display final results
             console.log('\n' + '='.repeat(50));
             console.log('INGESTION SUMMARY');

package/dist/cli/search.d.ts

@@ -1,6 +1,6 @@
 /**
  * Run search from CLI
- * @param query - Search query string
+ * @param query - Search query string or image file path
  * @param options - CLI options including top-k and rerank settings
  */
 export declare function runSearch(query: string, options?: Record<string, any>): Promise<void>;

package/dist/cli/search.js

@@ -1,10 +1,36 @@
-import { existsSync } from 'fs';
+import { existsSync, statSync } from 'fs';
+import { extname } from 'path';
 import { SearchFactory } from '../factories/search-factory.js';
 import { withCLIDatabaseAccess, setupCLICleanup } from '../core/cli-database-utils.js';
 import { config, EXIT_CODES, ConfigurationError } from '../core/config.js';
+/**
+ * Detect if query is an image file path
+ * @param query - Query string to check
+ * @returns True if query is a valid image file path
+ */
+function isImageFile(query) {
+    // Check if file exists
+    if (!existsSync(query)) {
+        return false;
+    }
+    // Check if it's a file (not a directory)
+    try {
+        const stats = statSync(query);
+        if (!stats.isFile()) {
+            return false;
+        }
+    }
+    catch {
+        return false;
+    }
+    // Check file extension
+    const ext = extname(query).toLowerCase();
+    const imageExtensions = ['.jpg', '.jpeg', '.png', '.gif', '.webp', '.bmp'];
+    return imageExtensions.includes(ext);
+}
 /**
  * Run search from CLI
- * @param query - Search query string
+ * @param query - Search query string or image file path
  * @param options - CLI options including top-k and rerank settings
  */
 export async function runSearch(query, options = {}) {
@@ -16,14 +42,18 @@ export async function runSearch(query, options = {}) {
             console.error('Error: Search query cannot be empty');
             console.error('');
             console.error('Usage: raglite search <query>');
+            console.error('       raglite search <image-path>');
             console.error('');
             console.error('Examples:');
             console.error('  raglite search "machine learning"');
             console.error('  raglite search "how to install"');
+            console.error('  raglite search ./photo.jpg');
             process.exit(EXIT_CODES.INVALID_ARGUMENTS);
         }
-        // Validate query length
-        if (query.trim().length > 500) {
+        // Detect if query is an image file
+        const isImage = isImageFile(query);
+        // Validate query length for text queries
+        if (!isImage && query.trim().length > 500) {
             console.error('Error: Search query is too long (maximum 500 characters)');
             console.error('');
             console.error('Please use a shorter, more specific query.');
@@ -53,40 +83,102 @@ export async function runSearch(query, options = {}) {
             console.error('If the problem persists, check that your documents were processed correctly.');
             process.exit(EXIT_CODES.INDEX_ERROR);
         }
-        console.log(`Searching for: "${query}"`);
+        // Display search type
+        if (isImage) {
+            console.log(`Searching with image: "${query}"`);
+        }
+        else {
+            console.log(`Searching for: "${query}"`);
+        }
         console.log('');
         // Setup graceful cleanup
         setupCLICleanup(effectiveConfig.db_file);
         // Initialize search engine using polymorphic factory with database protection
         let searchEngine;
+        let embedder;
         try {
             // Create search engine using SearchFactory (auto-detects mode)
             searchEngine = await withCLIDatabaseAccess(effectiveConfig.db_file, () => SearchFactory.create(effectiveConfig.index_file, effectiveConfig.db_file), {
                 commandName: 'Search command',
                 showProgress: true
             });
+            // For image queries, we need to check if the mode supports images
+            if (isImage) {
+                // Get system info to check mode
+                const { ModeDetectionService } = await import('../core/mode-detection-service.js');
+                const modeService = new ModeDetectionService(effectiveConfig.db_file);
+                const systemInfo = await modeService.detectMode();
+                if (systemInfo.mode !== 'multimodal') {
+                    console.error('Error: Image search is only supported in multimodal mode');
+                    console.error('');
+                    console.error('Your database is configured for text-only mode.');
+                    console.error('To enable image search:');
+                    console.error('1. Re-ingest your documents with multimodal mode:');
+                    console.error('   raglite ingest <path> --mode multimodal');
+                    console.error('2. Then search with images:');
+                    console.error('   raglite search ./photo.jpg');
+                    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+                }
+                // Create embedder for image embedding
+                const { createEmbedder } = await import('../core/embedder-factory.js');
+                embedder = await createEmbedder(systemInfo.modelName);
+                // Check if embedder supports images
+                const { supportsImages } = await import('../core/universal-embedder.js');
+                if (!supportsImages(embedder)) {
+                    console.error('Error: The current model does not support image embedding');
+                    console.error('');
+                    console.error(`Model: ${systemInfo.modelName}`);
+                    console.error('Image search requires a multimodal model like CLIP.');
+                    process.exit(EXIT_CODES.MODEL_ERROR);
+                }
+            }
             // Prepare search options
             const searchOptions = {};
             if (options['top-k'] !== undefined) {
                 searchOptions.top_k = options['top-k'];
             }
-            if (options.rerank !== undefined) {
-                searchOptions.rerank = options.rerank;
-            }
-            // Perform search
-            const startTime = Date.now();
-            let results = await searchEngine.search(query, searchOptions);
-            const searchTime = Date.now() - startTime;
-            // Apply content type filter if specified
+            // Set content type filter for search-level filtering
             const contentTypeFilter = options['content-type'];
             if (contentTypeFilter && contentTypeFilter !== 'all') {
-                const originalCount = results.length;
-                results = results.filter(r => r.contentType === contentTypeFilter);
-                if (results.length < originalCount) {
-                    console.log(`Filtered to ${results.length} ${contentTypeFilter} result${results.length === 1 ? '' : 's'} (from ${originalCount} total)`);
-                    console.log('');
+                searchOptions.contentType = contentTypeFilter;
+            }
+            // Phase 2: Disable reranking for image-to-image searches to preserve visual similarity
+            let rerankingForciblyDisabled = false;
+            if (isImage && embedder) {
+                // Force disable reranking for image searches, regardless of user setting
+                searchOptions.rerank = false;
+                rerankingForciblyDisabled = true;
+                // Warn user if they tried to enable reranking for image search
+                if (options.rerank === true) {
+                    console.warn('⚠️  Reranking is disabled for image-to-image search to preserve visual similarity.');
+                    console.warn('   Image-to-image search uses CLIP embeddings for direct visual matching.');
+                    console.warn('   For text-to-image search, use: raglite search "description" --rerank');
+                    console.warn('');
+                }
+            }
+            else {
+                // For text searches, use user setting (defaults to false from Phase 1)
+                if (options.rerank !== undefined) {
+                    searchOptions.rerank = options.rerank;
                 }
             }
+            // Track whether reranking will actually be used in this search
+            const rerankingUsed = searchOptions.rerank === true;
+            // Perform search
+            const startTime = Date.now();
+            let results;
+            if (isImage && embedder) {
+                // Image-based search: embed the image and search with the vector
+                console.log('Embedding image...');
+                const imageEmbedding = await embedder.embedImage(query);
+                console.log('Searching with image embedding...');
+                results = await searchEngine.searchWithVector(imageEmbedding.vector, searchOptions);
+            }
+            else {
+                // Text-based search
+                results = await searchEngine.search(query, searchOptions);
+            }
+            const searchTime = Date.now() - startTime;
             // Display results
             if (results.length === 0) {
                 console.log('No results found.');
@@ -129,13 +221,25 @@ export async function runSearch(query, options = {}) {
                 console.log('─'.repeat(50));
                 console.log(`Search completed in ${searchTime}ms`);
                 console.log(`Searched ${stats.totalChunks} chunks`);
-                if (stats.rerankingEnabled) {
+                if (rerankingUsed) {
                     console.log('Reranking: enabled');
                 }
+                else if (rerankingForciblyDisabled) {
+                    console.log('Reranking: disabled');
+                }
+                else if (stats.rerankingEnabled) {
+                    console.log('Reranking: available (not used)');
+                }
+                else {
+                    console.log('Reranking: disabled');
+                }
             }
         }
         finally {
             // Cleanup resources
+            if (embedder) {
+                await embedder.cleanup();
+            }
             if (searchEngine) {
                 await searchEngine.cleanup();
             }

package/dist/cli.js

@@ -18,61 +18,60 @@ function showVersion() {
  * Display help information
  */
 function showHelp() {
-    console.log(`
-RAG-lite TS v${packageJson.version}
-Local-first TypeScript retrieval engine for semantic search
-
-Usage:
-  raglite <command> [options]
-
-Commands:
-  ingest <path>     Ingest documents from file or directory
-  search <query>    Search indexed documents
-  rebuild           Rebuild the vector index
-  version           Show version information
-  help              Show this help message
-
-Examples:
-  raglite ingest ./docs/           # Ingest all .md/.txt/.docx/.pdf files in docs/
-  raglite ingest ./readme.md       # Ingest single file
-  raglite ingest ./docs/ --model Xenova/all-mpnet-base-v2  # Use higher quality model
-  raglite ingest ./docs/ --mode multimodal  # Enable multimodal processing
-  raglite ingest ./docs/ --mode multimodal --rerank-strategy metadata  # Use metadata reranking
-  raglite ingest ./docs/ --path-strategy relative --path-base /project  # Use relative paths
-  raglite search "machine learning" # Search for documents about machine learning
-  raglite search "API documentation" --top-k 10  # Get top 10 results
-  raglite search "red car" --content-type image  # Search only image results
-
-  raglite rebuild                  # Rebuild the entire index
-
-Options for search:
-  --top-k <number>       Number of results to return (default: 10)
-  --rerank              Enable reranking for better results
-  --no-rerank           Disable reranking
-  --content-type <type> Filter results by content type: 'text', 'image', or 'all' (default: all)
-
-Options for ingest:
-  --model <name>       Use specific embedding model
-  --mode <mode>        Processing mode: 'text' (default) or 'multimodal'
-  --rerank-strategy <strategy>  Reranking strategy for multimodal mode
-  --rebuild-if-needed  Automatically rebuild if model mismatch detected (WARNING: rebuilds entire index)
-  --path-strategy <strategy>  Path storage strategy: 'relative' (default) or 'absolute'
-  --path-base <path>   Base directory for relative paths (defaults to current directory)
-
-Available models:
-  Text mode:
-    sentence-transformers/all-MiniLM-L6-v2  (384 dim, fast, default)
-    Xenova/all-mpnet-base-v2               (768 dim, higher quality)
-  Multimodal mode:
-    Xenova/clip-vit-base-patch32           (512 dim, faster, default)
-    Xenova/clip-vit-base-patch16           (512 dim, more accurate, slower)
-
-Available reranking strategies (multimodal mode):
-  text-derived  Use image-to-text conversion + cross-encoder (default)
-  metadata      Use filename and metadata-based scoring
-  disabled      No reranking, use vector similarity only
-
-For more information, visit: https://github.com/your-repo/rag-lite-ts
+    console.log(`
+RAG-lite TS v${packageJson.version}
+Local-first TypeScript retrieval engine for semantic search
+
+Usage:
+  raglite <command> [options]
+
+Commands:
+  ingest <path>     Ingest documents from file or directory
+  search <query>    Search indexed documents (text or image)
+  rebuild           Rebuild the vector index
+  version           Show version information
+  help              Show this help message
+
+Examples:
+  raglite ingest ./docs/           # Ingest all .md/.txt/.docx/.pdf files in docs/
+  raglite ingest ./readme.md       # Ingest single file
+  raglite ingest ./docs/ --model Xenova/all-mpnet-base-v2  # Use higher quality model
+  raglite ingest ./docs/ --mode multimodal  # Enable multimodal processing
+  raglite ingest ./docs/ --path-strategy relative --path-base /project  # Use relative paths
+  raglite search "machine learning" # Search for documents about machine learning
+  raglite search "API documentation" --top-k 10  # Get top 10 results
+  raglite search "red car" --content-type image  # Search only image results
+  raglite search ./photo.jpg       # Search with image (multimodal mode only)
+  raglite search ./image.png --top-k 5  # Find similar images
+
+  raglite rebuild                  # Rebuild the entire index
+
+Options for search:
+  --top-k <number>       Number of results to return (default: 10)
+  --rerank              Enable reranking for better results
+  --no-rerank           Disable reranking
+  --content-type <type> Filter results by content type: 'text', 'image', or 'all' (default: all)
+
+Options for ingest:
+  --model <name>       Use specific embedding model
+  --mode <mode>        Processing mode: 'text' (default) or 'multimodal'
+  --rebuild-if-needed  Automatically rebuild if model mismatch detected (WARNING: rebuilds entire index)
+  --path-strategy <strategy>  Path storage strategy: 'relative' (default) or 'absolute'
+  --path-base <path>   Base directory for relative paths (defaults to current directory)
+
+Available models:
+  Text mode:
+    sentence-transformers/all-MiniLM-L6-v2  (384 dim, fast, default)
+    Xenova/all-mpnet-base-v2               (768 dim, higher quality)
+  Multimodal mode:
+    Xenova/clip-vit-base-patch32           (512 dim, faster, default)
+    Xenova/clip-vit-base-patch16           (512 dim, more accurate, slower)
+
+Available reranking strategies (multimodal mode):
+  text-derived  Use image-to-text conversion + cross-encoder (default)
+  disabled      No reranking, use vector similarity only
+
+For more information, visit: https://github.com/your-repo/rag-lite-ts
 `);
 }
 /**
@@ -98,9 +97,16 @@ function parseArgs() {
         const arg = args[i];
         if (arg.startsWith('--')) {
             const optionName = arg.slice(2);
-            // Handle boolean flags
+            // Handle boolean flags with optional values
             if (optionName === 'rerank') {
-                options.rerank = true;
+                const nextArg = args[i + 1];
+                if (nextArg && (nextArg === 'true' || nextArg === 'false')) {
+                    options.rerank = nextArg === 'true';
+                    i++; // Skip the next argument as it's the value
+                }
+                else {
+                    options.rerank = true;
+                }
             }
             else if (optionName === 'no-rerank') {
                 options.rerank = false;
@@ -136,6 +142,17 @@ function parseArgs() {
  * Validate command line arguments
  */
 function validateArgs(command, args, options) {
+    // Phase 3: Reject the removed --rerank-strategy option
+    if (options['rerank-strategy'] !== undefined) {
+        console.error('Error: --rerank-strategy option has been removed in this version');
+        console.error('');
+        console.error('Reranking strategy is now automatically selected based on mode:');
+        console.error('  Text mode: cross-encoder (or disabled)');
+        console.error('  Multimodal mode: text-derived (or disabled)');
+        console.error('');
+        console.error('Use --rerank or --no-rerank to control reranking instead.');
+        process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+    }
     switch (command) {
         case 'ingest':
             if (args.length === 0) {
@@ -148,12 +165,10 @@ function validateArgs(command, args, options) {
                 console.error('  raglite ingest ./readme.md       # Ingest single file');
                 console.error('  raglite ingest ./docs/ --model Xenova/all-mpnet-base-v2  # Use higher quality model');
                 console.error('  raglite ingest ./docs/ --mode multimodal  # Enable multimodal processing');
-                console.error('  raglite ingest ./docs/ --mode multimodal --rerank-strategy metadata  # Use metadata reranking');
                 console.error('');
                 console.error('Options:');
                 console.error('  --model <name>         Use specific embedding model');
                 console.error('  --mode <mode>          Processing mode: text (default) or multimodal');
-                console.error('  --rerank-strategy <strategy>  Reranking strategy for multimodal mode');
                 console.error('  --rebuild-if-needed    Automatically rebuild if model mismatch detected');
                 console.error('');
                 console.error('The path can be either a file (.md or .txt) or a directory.');
@@ -165,12 +180,15 @@ function validateArgs(command, args, options) {
                 console.error('Error: search command requires a query argument');
                 console.error('');
                 console.error('Usage: raglite search <query> [options]');
+                console.error('       raglite search <image-path> [options]');
                 console.error('');
                 console.error('Examples:');
                 console.error('  raglite search "machine learning"');
                 console.error('  raglite search "API documentation" --top-k 10');
                 console.error('  raglite search "tutorial" --rerank');
                 console.error('  raglite search "red car" --content-type image');
+                console.error('  raglite search ./photo.jpg              # Image search (multimodal mode)');
+                console.error('  raglite search ./image.png --top-k 5    # Find similar images');
                 console.error('');
                 console.error('Options:');
                 console.error('  --top-k <number>       Number of results to return (default: 10)');
@@ -269,41 +287,6 @@ function validateArgs(command, args, options) {
             process.exit(EXIT_CODES.INVALID_ARGUMENTS);
         }
     }
-    // Validate rerank-strategy option (only for ingest command with multimodal mode)
-    if (options['rerank-strategy'] !== undefined) {
-        if (command !== 'ingest') {
-            console.error(`Error: --rerank-strategy option is only available for the 'ingest' command`);
-            console.error('');
-            console.error('Reranking strategy is configured during ingestion and used automatically during search.');
-            process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        const mode = options.mode || 'text';
-        if (mode !== 'multimodal') {
-            console.error(`Error: --rerank-strategy option is only available in multimodal mode`);
-            console.error('');
-            console.error('To use reranking strategies, specify --mode multimodal');
-            console.error('');
-            console.error('Examples:');
-            console.error('  raglite ingest ./docs/ --mode multimodal --rerank-strategy text-derived');
-            console.error('  raglite ingest ./docs/ --mode multimodal --rerank-strategy metadata');
-            process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-        }
-        const supportedStrategies = ['text-derived', 'metadata', 'disabled'];
-        if (!supportedStrategies.includes(options['rerank-strategy'])) {
-            console.error(`Error: Unsupported reranking strategy '${options['rerank-strategy']}'`);
-            console.error('');
-            console.error('Supported strategies for multimodal mode:');
-            console.error('  text-derived  Convert images to text, then use cross-encoder (default)');
-            console.error('  metadata      Use filename and metadata-based scoring');
-            console.error('  disabled      No reranking, use vector similarity only');
-            console.error('');
-            console.error('Examples:');
-            console.error('  --rerank-strategy text-derived');
-            console.error('  --rerank-strategy metadata');
-            console.error('  --rerank-strategy disabled');
-            process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-        }
-    }
     // Validate model option (only for ingest command)
     if (options.model !== undefined) {
         if (command !== 'ingest') {

package/dist/core/binary-index-format.d.ts

@@ -25,10 +25,19 @@ export interface BinaryIndexData {
         id: number;
         vector: Float32Array;
     }>;
+    hasContentTypeGroups?: boolean;
+    textVectors?: Array<{
+        id: number;
+        vector: Float32Array;
+    }>;
+    imageVectors?: Array<{
+        id: number;
+        vector: Float32Array;
+    }>;
 }
 export declare class BinaryIndexFormat {
     /**
-     * Save index data to binary format
+     * Save index data to binary format (original format for backward compatibility)
      *
      * File structure:
      * - Header (24 bytes): dimensions, maxElements, M, efConstruction, seed, currentSize
@@ -39,7 +48,24 @@ export declare class BinaryIndexFormat {
      */
     static save(indexPath: string, data: BinaryIndexData): Promise<void>;
     /**
-     * Load index data from binary format
+     * Save index data to grouped binary format
+     *
+     * File structure:
+     * - Extended Header (40 bytes):
+     *   - Original 6 fields (24 bytes)
+     *   - hasGroups flag (4 bytes)
+     *   - textOffset (4 bytes)
+     *   - textCount (4 bytes)
+     *   - imageOffset (4 bytes)
+     *   - imageCount (4 bytes)
+     * - Data section: [text vectors...][image vectors...]
+     *
+     * @param indexPath Path to save the binary index file
+     * @param data Index data to serialize
+     */
+    static saveGrouped(indexPath: string, data: BinaryIndexData): Promise<void>;
+    /**
+     * Load index data from binary format (supports both original and grouped formats)
      *
      * Uses zero-copy Float32Array views for efficient loading.
      * Copies the views to ensure data persistence after buffer lifecycle.