rag-lite-ts 2.2.0 → 2.3.1

package/dist/esm/cli/search.js

@@ -132,7 +132,7 @@ export async function runSearch(query, options = {}) {
                     process.exit(EXIT_CODES.MODEL_ERROR);
                 }
             }
-            // Prepare search options
+            // Prepare search options (with generation support)
             const searchOptions = {};
             if (options['top-k'] !== undefined) {
                 searchOptions.top_k = options['top-k'];
@@ -164,9 +164,60 @@ export async function runSearch(query, options = {}) {
             }
             // Track whether reranking will actually be used in this search
             const rerankingUsed = searchOptions.rerank === true;
+            // Handle generation options (experimental, text mode only)
+            const generateResponse = options.generate === true;
+            const generatorModel = options.generator;
+            const maxGenerationTokens = options['max-tokens'];
+            const generationTemperature = options.temperature;
+            const maxChunksForContext = options['max-chunks'];
+            // Generation only supported in text mode
+            if (generateResponse && isImage) {
+                console.warn('⚠️  [EXPERIMENTAL] Generation is only supported for text searches.');
+                console.warn('   Image search results will be returned without generation.');
+                console.warn('');
+            }
+            // Generation requires reranking - enable it automatically
+            let rerankingEnabledForGeneration = false;
+            if (generateResponse && !isImage && !searchOptions.rerank) {
+                searchOptions.rerank = true;
+                rerankingEnabledForGeneration = true;
+                console.log('📋 Reranking automatically enabled (required for generation)');
+            }
+            // Set up generator if generation is requested (text mode only)
+            let generateFn;
+            if (generateResponse && !isImage) {
+                try {
+                    console.log('🤖 [EXPERIMENTAL] Initializing response generator...');
+                    const { createGenerateFunctionFromModel, getDefaultGeneratorModel } = await import('../factories/generator-factory.js');
+                    const { getDefaultMaxChunksForContext } = await import('../core/generator-registry.js');
+                    const modelToUse = generatorModel || getDefaultGeneratorModel();
+                    const defaultChunks = getDefaultMaxChunksForContext(modelToUse) || 3;
+                    console.log(`   Model: ${modelToUse}`);
+                    console.log(`   Max chunks for context: ${maxChunksForContext || defaultChunks} (default: ${defaultChunks})`);
+                    generateFn = await createGenerateFunctionFromModel(modelToUse);
+                    searchEngine.setGenerateFunction(generateFn);
+                    console.log('✅ Generator initialized');
+                    console.log('');
+                }
+                catch (error) {
+                    console.error('❌ [EXPERIMENTAL] Failed to initialize generator:', error instanceof Error ? error.message : 'Unknown error');
+                    console.error('   Continuing without generation...');
+                    console.error('');
+                }
+            }
+            // Set generation options if generator is ready
+            if (generateFn && generateResponse && !isImage) {
+                searchOptions.generateResponse = true;
+                searchOptions.generationOptions = {
+                    maxTokens: maxGenerationTokens,
+                    temperature: generationTemperature,
+                    maxChunksForContext: maxChunksForContext
+                };
+            }
             // Perform search
             const startTime = Date.now();
             let results;
+            let generationResult;
             if (isImage && embedder) {
                 // Image-based search: embed the image and search with the vector
                 console.log('Embedding image...');
@@ -174,8 +225,14 @@ export async function runSearch(query, options = {}) {
                 console.log('Searching with image embedding...');
                 results = await searchEngine.searchWithVector(imageEmbedding.vector, searchOptions);
             }
+            else if (generateResponse && generateFn) {
+                // Text-based search with generation
+                const searchResult = await searchEngine.searchWithGeneration(query, searchOptions);
+                results = searchResult.results;
+                generationResult = searchResult.generation;
+            }
             else {
-                // Text-based search
+                // Standard text-based search
                 results = await searchEngine.search(query, searchOptions);
             }
             const searchTime = Date.now() - startTime;
@@ -216,6 +273,21 @@ export async function runSearch(query, options = {}) {
                     }
                     console.log('');
                 });
+                // Display generated response if available (experimental)
+                if (generationResult) {
+                    console.log('─'.repeat(50));
+                    console.log('🤖 Generated Response [EXPERIMENTAL]');
+                    console.log(`Model: ${generationResult.modelUsed}`);
+                    console.log('─'.repeat(50));
+                    console.log('');
+                    console.log(generationResult.response);
+                    console.log('');
+                    console.log('─'.repeat(50));
+                    console.log(`⏱️  Generation: ${(generationResult.generationTimeMs / 1000).toFixed(1)}s | ` +
+                        `📊 ${generationResult.tokensUsed} tokens | ` +
+                        `📄 ${generationResult.chunksUsedForContext} chunks used` +
+                        (generationResult.truncated ? ' (context truncated)' : ''));
+                }
                 // Show search statistics
                 const stats = await searchEngine.getStats();
                 console.log('─'.repeat(50));
@@ -233,6 +305,9 @@ export async function runSearch(query, options = {}) {
                 else {
                     console.log('Reranking: disabled');
                 }
+                if (generationResult) {
+                    console.log('Generation: enabled [EXPERIMENTAL]');
+                }
             }
         }
         finally {

package/dist/esm/cli/ui-server.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Launch the UI server
+ */
+export declare function runUI(options?: any): Promise<void>;
+//# sourceMappingURL=ui-server.d.ts.map

package/dist/esm/cli/ui-server.js

@@ -0,0 +1,152 @@
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { spawn } from 'child_process';
+import fs from 'fs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Get the project root directory
+ * When built, CLI is at dist/esm/cli/ui-server.js, so go up 3 levels
+ * When running from source, CLI is at src/cli/ui-server.ts, so go up 2 levels
+ */
+function getProjectRoot() {
+    // Try going up 3 levels first (for built version)
+    const builtPath = join(__dirname, '../../..');
+    if (fs.existsSync(join(builtPath, 'package.json'))) {
+        return builtPath;
+    }
+    // Fallback: go up 2 levels (for source execution)
+    return join(__dirname, '../..');
+}
+/**
+ * Launch the UI server
+ */
+export async function runUI(options = {}) {
+    const port = options.port || 3000;
+    const backendPort = options.backendPort || 3001;
+    console.log('🚀 Launching RAG-lite TS UI...');
+    // Resolve UI paths from project root
+    const projectRoot = getProjectRoot();
+    const backendBuiltPath = join(projectRoot, 'ui', 'backend', 'dist', 'index.js');
+    const backendSourcePath = join(projectRoot, 'ui', 'backend', 'src', 'index.ts');
+    const frontendBuiltPath = join(projectRoot, 'ui', 'frontend', 'dist');
+    const frontendSourcePath = join(projectRoot, 'ui', 'frontend');
+    // Check if built files exist
+    const useBuiltBackend = fs.existsSync(backendBuiltPath);
+    const useBuiltFrontend = fs.existsSync(frontendBuiltPath);
+    if (!useBuiltBackend && !fs.existsSync(backendSourcePath)) {
+        console.error(`❌ UI backend not found at: ${backendSourcePath}`);
+        console.error('   Make sure the UI is set up in the ui/ directory.');
+        process.exit(1);
+    }
+    if (!useBuiltFrontend && !fs.existsSync(frontendSourcePath)) {
+        console.error(`❌ UI frontend not found at: ${frontendSourcePath}`);
+        console.error('   Make sure the UI is set up in the ui/ directory.');
+        process.exit(1);
+    }
+    // Pass the working directory where 'raglite ui' was called to the backend
+    const workingDir = process.cwd();
+    // Built mode: single server on port (UI + API). Dev mode: backend on backendPort, frontend on port.
+    const effectiveBackendPort = useBuiltFrontend ? port : backendPort;
+    console.log(`📡 Starting backend on port ${effectiveBackendPort}...`);
+    // Start backend server - use built version if available
+    const backendCommand = useBuiltBackend ? 'node' : 'npx';
+    const backendArgs = useBuiltBackend
+        ? [backendBuiltPath]
+        : ['tsx', backendSourcePath];
+    const backendProcess = spawn(backendCommand, backendArgs, {
+        stdio: 'pipe',
+        env: {
+            ...process.env,
+            PORT: effectiveBackendPort.toString(),
+            RAG_WORKING_DIR: workingDir,
+            UI_FRONTEND_DIST: useBuiltFrontend ? frontendBuiltPath : undefined
+        },
+        shell: true
+    });
+    backendProcess.on('error', (err) => {
+        console.error('❌ Failed to start backend process:', err);
+        process.exit(1);
+    });
+    // Forward backend output with prefix
+    backendProcess.stdout?.on('data', (data) => {
+        process.stdout.write(`[Backend] ${data}`);
+    });
+    backendProcess.stderr?.on('data', (data) => {
+        process.stderr.write(`[Backend] ${data}`);
+    });
+    // Only start frontend dev server if built version doesn't exist
+    let frontendProcess = null;
+    if (!useBuiltFrontend) {
+        console.log(`🎨 Starting frontend dev server on port ${port}...`);
+        frontendProcess = spawn('npm', ['run', 'dev'], {
+            cwd: frontendSourcePath,
+            stdio: 'pipe',
+            env: {
+                ...process.env,
+                VITE_API_URL: `http://localhost:${effectiveBackendPort}`
+            },
+            shell: true
+        });
+        frontendProcess.on('error', (err) => {
+            console.error('❌ Failed to start frontend process:', err);
+            backendProcess.kill();
+            process.exit(1);
+        });
+        // Forward frontend output with prefix
+        frontendProcess.stdout?.on('data', (data) => {
+            process.stdout.write(`[Frontend] ${data}`);
+        });
+        frontendProcess.stderr?.on('data', (data) => {
+            process.stderr.write(`[Frontend] ${data}`);
+        });
+    }
+    else {
+        console.log(`🎨 Using built frontend from ${frontendBuiltPath}`);
+        console.log(`   Frontend will be served by backend on port ${effectiveBackendPort}`);
+    }
+    // Wait a bit for servers to start
+    await new Promise(resolve => setTimeout(resolve, 2000));
+    console.log(`\n✨ UI Access:`);
+    if (useBuiltFrontend) {
+        console.log(`   Frontend & Backend: http://localhost:${port}`);
+    }
+    else {
+        console.log(`   Frontend: http://localhost:${port}`);
+        console.log(`   Backend:  http://localhost:${effectiveBackendPort}`);
+    }
+    console.log(`\n💡 Press Ctrl+C to stop both servers\n`);
+    // Keep the process alive and handle cleanup
+    return new Promise((resolve) => {
+        const cleanup = () => {
+            console.log('\n🛑 Shutting down servers...');
+            backendProcess.kill();
+            if (frontendProcess) {
+                frontendProcess.kill();
+            }
+            resolve();
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        // Handle process exits
+        backendProcess.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                console.error(`\n❌ Backend process exited with code ${code}`);
+                if (frontendProcess) {
+                    frontendProcess.kill();
+                }
+                resolve();
+            }
+        });
+        if (frontendProcess) {
+            frontendProcess.on('exit', (code) => {
+                if (code !== 0 && code !== null) {
+                    console.error(`\n❌ Frontend process exited with code ${code}`);
+                    backendProcess.kill();
+                    resolve();
+                }
+            });
+        }
+    });
+}
+//# sourceMappingURL=ui-server.js.map

package/dist/esm/cli.js

@@ -6,8 +6,18 @@ import { EXIT_CODES, ConfigurationError } from './core/config.js';
 // Get package.json for version info
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const packageJsonPath = join(__dirname, '..', 'package.json');
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+// When built, CLI is at dist/esm/cli.js, so go up two levels to root
+// When running from source, CLI is at src/cli.ts, so go up one level to root
+const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+let packageJson;
+try {
+    packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+}
+catch {
+    // Fallback: try one level up (for source execution)
+    const fallbackPath = join(__dirname, '..', 'package.json');
+    packageJson = JSON.parse(readFileSync(fallbackPath, 'utf-8'));
+}
 /**
  * Display version information
  */
@@ -28,6 +38,7 @@ Usage:
 Commands:
   ingest <path>     Ingest documents from file or directory
   search <query>    Search indexed documents (text or image)
+  ui                Launch the web interface
   rebuild           Rebuild the vector index
   version           Show version information
   help              Show this help message
@@ -43,6 +54,8 @@ Examples:
   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 search "How does auth work?" --generate  # [EXPERIMENTAL] Generate AI response
+  raglite ui                       # Launch web interface
 
   raglite rebuild                  # Rebuild the entire index
 
@@ -52,10 +65,17 @@ Options for search:
   --no-rerank           Disable reranking
   --content-type <type> Filter results by content type: 'text', 'image', or 'all' (default: all)
 
+  [EXPERIMENTAL] AI Response Generation (text mode only):
+  --generate            Generate an AI response from search results
+  --generator <model>   Generator model to use (default: SmolLM2-135M-Instruct)
+  --max-tokens <n>      Maximum tokens to generate (default: 512)
+  --temperature <n>     Sampling temperature 0-1 (default: 0.1)
+  --max-chunks <n>      Maximum chunks for context (default: 3 for 135M, 5 for 360M)
+
 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)
+  --force-rebuild      Wipe DB+index and rebuild from scratch (DESTRUCTIVE)
   --path-strategy <strategy>  Path storage strategy: 'relative' (default) or 'absolute'
   --path-base <path>   Base directory for relative paths (defaults to current directory)
 
@@ -71,6 +91,12 @@ Available reranking strategies (multimodal mode):
   text-derived  Use image-to-text conversion + cross-encoder (default)
   disabled      No reranking, use vector similarity only
 
+[EXPERIMENTAL] Available generator models:
+  HuggingFaceTB/SmolLM2-135M-Instruct  (balanced, recommended default, uses top 3 chunks)
+  HuggingFaceTB/SmolLM2-360M-Instruct  (higher quality, slower, uses top 5 chunks)
+  
+  Note: Generation requires reranking (--rerank is automatically enabled with --generate)
+
 For more information, visit: https://github.com/your-repo/rag-lite-ts
 `);
 }
@@ -111,8 +137,12 @@ function parseArgs() {
             else if (optionName === 'no-rerank') {
                 options.rerank = false;
             }
-            else if (optionName === 'rebuild-if-needed') {
-                options.rebuildIfNeeded = true;
+            else if (optionName === 'force-rebuild') {
+                options.forceRebuild = true;
+            }
+            else if (optionName === 'generate') {
+                // Handle --generate flag for experimental response generation
+                options.generate = true;
             }
             else if (optionName === 'help') {
                 return { command: 'help', args: [], options: {} };
@@ -124,7 +154,16 @@ function parseArgs() {
                 // Handle options with values
                 const nextArg = args[i + 1];
                 if (nextArg && !nextArg.startsWith('--')) {
-                    options[optionName] = nextArg;
+                    // Parse numeric values for specific options
+                    if (optionName === 'max-tokens' || optionName === 'top-k' || optionName === 'max-chunks') {
+                        options[optionName] = parseInt(nextArg, 10);
+                    }
+                    else if (optionName === 'temperature') {
+                        options[optionName] = parseFloat(nextArg);
+                    }
+                    else {
+                        options[optionName] = nextArg;
+                    }
                     i++; // Skip the next argument as it's the value
                 }
                 else {
@@ -169,7 +208,7 @@ function validateArgs(command, args, options) {
                 console.error('Options:');
                 console.error('  --model <name>         Use specific embedding model');
                 console.error('  --mode <mode>          Processing mode: text (default) or multimodal');
-                console.error('  --rebuild-if-needed    Automatically rebuild if model mismatch detected');
+                console.error('  --force-rebuild        Wipe DB+index and rebuild from scratch (DESTRUCTIVE)');
                 console.error('');
                 console.error('The path can be either a file (.md or .txt) or a directory.');
                 process.exit(EXIT_CODES.INVALID_ARGUMENTS);
@@ -201,6 +240,9 @@ function validateArgs(command, args, options) {
         case 'rebuild':
             // No arguments required
             break;
+        case 'ui':
+            // No arguments required
+            break;
         case 'version':
             // No validation needed
             break;
@@ -412,6 +454,10 @@ async function main() {
                 const { runRebuild } = await import('./cli/indexer.js');
                 await runRebuild();
                 break;
+            case 'ui':
+                const { runUI } = await import('./cli/ui-server.js');
+                await runUI(options);
+                break;
             default:
                 console.error(`Error: Unknown command '${command}'`);
                 process.exit(1);

package/dist/esm/core/abstract-generator.d.ts

@@ -0,0 +1,97 @@
+/**
+ * CORE MODULE — Abstract Base Generator
+ *
+ * Provides model-agnostic base functionality for all generator implementations.
+ * This is an abstract base class, not a concrete implementation.
+ *
+ * ARCHITECTURAL NOTE:
+ * Similar to BaseUniversalEmbedder, this class provides shared infrastructure:
+ * - Model lifecycle management (loading, cleanup, disposal)
+ * - Token budget management
+ * - Error handling with helpful messages
+ * - Common utility methods
+ *
+ * IMPLEMENTATION LAYERS:
+ * - Text: InstructGenerator extends this class (SmolLM2-Instruct)
+ * - Text: CausalLMGenerator extends this class (DistilGPT2)
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import type { ResponseGenerator, GeneratorModelInfo, GeneratorModelType, GenerationRequest, GenerationResult, GeneratorCreationOptions } from './response-generator.js';
+import { GenerationError } from './response-generator.js';
+/**
+ * Abstract base class for response generators
+ * Provides common functionality and lifecycle management
+ */
+export declare abstract class BaseResponseGenerator implements ResponseGenerator {
+    readonly modelName: string;
+    protected _isLoaded: boolean;
+    protected _modelInfo: GeneratorModelInfo;
+    protected _options: GeneratorCreationOptions;
+    constructor(modelName: string, options?: GeneratorCreationOptions);
+    get modelType(): GeneratorModelType;
+    get maxContextLength(): number;
+    get maxOutputLength(): number;
+    isLoaded(): boolean;
+    getModelInfo(): GeneratorModelInfo;
+    /**
+     * Load the model - must be implemented by subclasses
+     */
+    abstract loadModel(): Promise<void>;
+    /**
+     * Generate text using the model - must be implemented by subclasses
+     * @param prompt - The formatted prompt string
+     * @param options - Generation options
+     * @returns Generated text
+     */
+    protected abstract generateText(prompt: string, options: {
+        maxTokens: number;
+        temperature: number;
+        topP: number;
+        topK: number;
+        repetitionPenalty: number;
+        stopSequences: string[];
+    }): Promise<{
+        text: string;
+        promptTokens: number;
+        completionTokens: number;
+        finishReason: 'complete' | 'length' | 'stop_sequence' | 'error';
+    }>;
+    /**
+     * Clean up resources - must be implemented by subclasses
+     */
+    abstract cleanup(): Promise<void>;
+    /**
+     * Generate a response based on query and retrieved chunks
+     * This method orchestrates the generation pipeline
+     */
+    generate(request: GenerationRequest): Promise<GenerationResult>;
+    /**
+     * Validate that the model is loaded before operations
+     */
+    protected ensureLoaded(): void;
+    /**
+     * Clean up response text by removing artifacts
+     */
+    protected cleanResponseText(text: string): string;
+    /**
+     * Log model loading progress
+     */
+    protected logModelLoading(stage: string, details?: string): void;
+    /**
+     * Handle model loading errors with helpful messages
+     */
+    protected handleLoadingError(error: Error): GenerationError;
+}
+/**
+ * Extended options for generator instances
+ */
+export interface GeneratorOptions extends GeneratorCreationOptions {
+    /** Log level for debugging */
+    logLevel?: 'debug' | 'info' | 'warn' | 'error' | 'silent';
+}
+/**
+ * Create generator options with defaults
+ */
+export declare function createGeneratorOptions(options?: Partial<GeneratorOptions>): GeneratorOptions;
+//# sourceMappingURL=abstract-generator.d.ts.map