rag-lite-ts 2.3.0 → 2.3.1

package/dist/cjs/text/generators/causal-lm-generator.js

@@ -0,0 +1,197 @@
+/**
+ * TEXT IMPLEMENTATION — Causal LM Generator for DistilGPT2
+ *
+ * Implements ResponseGenerator interface for causal language models.
+ * Supports Xenova/distilgpt2 for fast, basic text generation.
+ *
+ * Features:
+ * - Simple prompt formatting (no chat template)
+ * - Fast generation with smaller model
+ * - Streaming generation support
+ * - Resource management via ResourceManager
+ *
+ * Note: Causal LM models don't support system prompts, so responses
+ * may be less focused than instruction-tuned models.
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import '../../dom-polyfills.js';
+import { BaseResponseGenerator } from '../../core/abstract-generator.js';
+import { GenerationError } from '../../core/response-generator.js';
+import { getResourceManager } from '../../core/resource-manager.js';
+import { config } from '../../core/config.js';
+// =============================================================================
+// CAUSAL LM GENERATOR IMPLEMENTATION
+// =============================================================================
+/**
+ * Causal LM generator implementation for DistilGPT2
+ *
+ * Uses causal language models that generate text based on simple prompts.
+ * Faster but may produce less focused responses than instruct models.
+ */
+export class CausalLMGenerator extends BaseResponseGenerator {
+    pipeline = null;
+    tokenizer = null;
+    resourceManager = getResourceManager();
+    resourceId;
+    constructor(modelName, options = {}) {
+        super(modelName, options);
+        // Validate model is a causal-lm model
+        if (this.modelType !== 'causal-lm') {
+            throw new Error(`CausalLMGenerator requires a causal-lm model, but '${modelName}' is type '${this.modelType}'`);
+        }
+    }
+    // =============================================================================
+    // MODEL LIFECYCLE
+    // =============================================================================
+    /**
+     * Load the causal LM model using transformers.js
+     */
+    async loadModel() {
+        if (this._isLoaded && this.pipeline) {
+            return;
+        }
+        try {
+            this.logModelLoading('Loading causal LM generator model');
+            // Ensure DOM polyfills
+            if (typeof globalThis.self === 'undefined') {
+                globalThis.self = globalThis;
+            }
+            // Dynamic import transformers.js
+            const { pipeline, AutoTokenizer } = await import('@huggingface/transformers');
+            // Load tokenizer first for token counting
+            this.logModelLoading('Loading tokenizer');
+            this.tokenizer = await AutoTokenizer.from_pretrained(this.modelName, {
+                cache_dir: this._options.cachePath || config.model_cache_path
+            });
+            // Load text generation pipeline
+            this.logModelLoading('Loading text generation pipeline');
+            this.pipeline = await pipeline('text-generation', this.modelName, {
+                cache_dir: this._options.cachePath || config.model_cache_path,
+                dtype: 'fp32'
+            });
+            // Register with resource manager
+            this.resourceId = this.resourceManager.registerModel(this.pipeline, this.modelName, 'generator');
+            this._isLoaded = true;
+            this.logModelLoading('Model loaded successfully');
+        }
+        catch (error) {
+            this._isLoaded = false;
+            throw this.handleLoadingError(error);
+        }
+    }
+    /**
+     * Clean up model resources
+     */
+    async cleanup() {
+        try {
+            if (this.resourceId) {
+                await this.resourceManager.cleanupResource(this.resourceId);
+                this.resourceId = undefined;
+            }
+            // Clear references
+            this.pipeline = null;
+            this.tokenizer = null;
+            this._isLoaded = false;
+            // Force GC if available
+            if (global.gc) {
+                global.gc();
+            }
+            this.logModelLoading('Resources cleaned up');
+        }
+        catch (error) {
+            console.warn(`Cleanup error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            this.pipeline = null;
+            this.tokenizer = null;
+            this._isLoaded = false;
+        }
+    }
+    // =============================================================================
+    // GENERATION IMPLEMENTATION
+    // =============================================================================
+    /**
+     * Generate text using the causal LM model
+     */
+    async generateText(prompt, options) {
+        this.ensureLoaded();
+        try {
+            // Count prompt tokens
+            const promptTokens = await this.countTokens(prompt);
+            // Generate - GPT2 uses return_full_text differently
+            const result = await this.pipeline(prompt, {
+                max_new_tokens: options.maxTokens,
+                temperature: Math.max(0.1, options.temperature), // GPT2 needs temp > 0
+                top_p: options.topP,
+                top_k: options.topK,
+                repetition_penalty: options.repetitionPenalty,
+                do_sample: true,
+                return_full_text: true, // GPT2 needs full text
+                pad_token_id: this.tokenizer?.eos_token_id // GPT2 uses eos as pad
+            });
+            // Extract generated text (remove prompt)
+            let generatedText = result[0]?.generated_text || '';
+            if (generatedText.startsWith(prompt)) {
+                generatedText = generatedText.substring(prompt.length);
+            }
+            // Process stop sequences
+            let finalText = generatedText;
+            let finishReason = 'complete';
+            for (const stopSeq of options.stopSequences) {
+                const stopIndex = finalText.indexOf(stopSeq);
+                if (stopIndex !== -1) {
+                    finalText = finalText.substring(0, stopIndex);
+                    finishReason = 'stop_sequence';
+                    break;
+                }
+            }
+            // Count completion tokens
+            const completionTokens = await this.countTokens(finalText);
+            // Check if we hit max tokens
+            if (completionTokens >= options.maxTokens - 5) {
+                finishReason = 'length';
+            }
+            return {
+                text: finalText,
+                promptTokens,
+                completionTokens,
+                finishReason
+            };
+        }
+        catch (error) {
+            throw new GenerationError(this.modelName, 'generation', `Text generation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Generate text with streaming output
+     */
+    async *generateStream(request) {
+        // For now, fall back to non-streaming and yield the full response
+        // TODO: Implement true streaming when transformers.js supports it better
+        const result = await this.generate(request);
+        yield result.response;
+    }
+    // =============================================================================
+    // HELPER METHODS
+    // =============================================================================
+    /**
+     * Count tokens in a text string
+     */
+    async countTokens(text) {
+        if (!this.tokenizer) {
+            // Fallback to estimation
+            return Math.ceil(text.length / 4);
+        }
+        try {
+            const encoded = await this.tokenizer(text, {
+                return_tensors: false,
+                padding: false,
+                truncation: false
+            });
+            return encoded.input_ids?.length || Math.ceil(text.length / 4);
+        }
+        catch {
+            return Math.ceil(text.length / 4);
+        }
+    }
+}
+//# sourceMappingURL=causal-lm-generator.js.map

package/dist/cjs/text/generators/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * TEXT GENERATORS — Export Module
+ *
+ * Provides text generation capabilities for RAG response synthesis.
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+export { InstructGenerator } from './instruct-generator.js';
+export { CausalLMGenerator } from './causal-lm-generator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/text/generators/index.js

@@ -0,0 +1,10 @@
+/**
+ * TEXT GENERATORS — Export Module
+ *
+ * Provides text generation capabilities for RAG response synthesis.
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+export { InstructGenerator } from './instruct-generator.js';
+export { CausalLMGenerator } from './causal-lm-generator.js';
+//# sourceMappingURL=index.js.map

package/dist/cjs/text/generators/instruct-generator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * TEXT IMPLEMENTATION — Instruct Generator for SmolLM2-Instruct Models
+ *
+ * Implements ResponseGenerator interface for instruction-tuned models.
+ * Supports SmolLM2-135M-Instruct and SmolLM2-360M-Instruct.
+ *
+ * Features:
+ * - Chat template formatting with system/user/assistant roles
+ * - Streaming generation support
+ * - Proper stop sequence handling
+ * - Resource management via ResourceManager
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import '../../dom-polyfills.js';
+import { BaseResponseGenerator, type GeneratorOptions } from '../../core/abstract-generator.js';
+/**
+ * Instruct generator implementation for SmolLM2-Instruct models
+ *
+ * Uses instruction-tuned models that understand chat templates with
+ * system, user, and assistant roles for better response quality.
+ */
+export declare class InstructGenerator extends BaseResponseGenerator {
+    private pipeline;
+    private tokenizer;
+    private resourceManager;
+    private resourceId?;
+    constructor(modelName: string, options?: GeneratorOptions);
+    /**
+     * Load the instruct model using transformers.js
+     */
+    loadModel(): Promise<void>;
+    /**
+     * Clean up model resources
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Generate text using the instruct model
+     */
+    protected 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';
+    }>;
+    /**
+     * Generate text with streaming output
+     */
+    generateStream(request: import('../../core/response-generator.js').GenerationRequest): AsyncIterable<string>;
+    /**
+     * Count tokens in a text string
+     */
+    private countTokens;
+}
+//# sourceMappingURL=instruct-generator.d.ts.map

package/dist/cjs/text/generators/instruct-generator.js

@@ -0,0 +1,192 @@
+/**
+ * TEXT IMPLEMENTATION — Instruct Generator for SmolLM2-Instruct Models
+ *
+ * Implements ResponseGenerator interface for instruction-tuned models.
+ * Supports SmolLM2-135M-Instruct and SmolLM2-360M-Instruct.
+ *
+ * Features:
+ * - Chat template formatting with system/user/assistant roles
+ * - Streaming generation support
+ * - Proper stop sequence handling
+ * - Resource management via ResourceManager
+ *
+ * @experimental This feature is experimental and may change in future versions.
+ */
+import '../../dom-polyfills.js';
+import { BaseResponseGenerator } from '../../core/abstract-generator.js';
+import { GenerationError } from '../../core/response-generator.js';
+import { getResourceManager } from '../../core/resource-manager.js';
+import { config } from '../../core/config.js';
+// =============================================================================
+// INSTRUCT GENERATOR IMPLEMENTATION
+// =============================================================================
+/**
+ * Instruct generator implementation for SmolLM2-Instruct models
+ *
+ * Uses instruction-tuned models that understand chat templates with
+ * system, user, and assistant roles for better response quality.
+ */
+export class InstructGenerator extends BaseResponseGenerator {
+    pipeline = null;
+    tokenizer = null;
+    resourceManager = getResourceManager();
+    resourceId;
+    constructor(modelName, options = {}) {
+        super(modelName, options);
+        // Validate model is an instruct model
+        if (this.modelType !== 'instruct') {
+            throw new Error(`InstructGenerator requires an instruct model, but '${modelName}' is type '${this.modelType}'`);
+        }
+    }
+    // =============================================================================
+    // MODEL LIFECYCLE
+    // =============================================================================
+    /**
+     * Load the instruct model using transformers.js
+     */
+    async loadModel() {
+        if (this._isLoaded && this.pipeline) {
+            return;
+        }
+        try {
+            this.logModelLoading('Loading instruct generator model');
+            // Ensure DOM polyfills
+            if (typeof globalThis.self === 'undefined') {
+                globalThis.self = globalThis;
+            }
+            // Dynamic import transformers.js
+            const { pipeline, AutoTokenizer } = await import('@huggingface/transformers');
+            // Load tokenizer first for token counting
+            this.logModelLoading('Loading tokenizer');
+            this.tokenizer = await AutoTokenizer.from_pretrained(this.modelName, {
+                cache_dir: this._options.cachePath || config.model_cache_path
+            });
+            // Load text generation pipeline
+            this.logModelLoading('Loading text generation pipeline');
+            this.pipeline = await pipeline('text-generation', this.modelName, {
+                cache_dir: this._options.cachePath || config.model_cache_path,
+                dtype: 'fp32'
+            });
+            // Register with resource manager
+            this.resourceId = this.resourceManager.registerModel(this.pipeline, this.modelName, 'generator');
+            this._isLoaded = true;
+            this.logModelLoading('Model loaded successfully');
+        }
+        catch (error) {
+            this._isLoaded = false;
+            throw this.handleLoadingError(error);
+        }
+    }
+    /**
+     * Clean up model resources
+     */
+    async cleanup() {
+        try {
+            if (this.resourceId) {
+                await this.resourceManager.cleanupResource(this.resourceId);
+                this.resourceId = undefined;
+            }
+            // Clear references
+            this.pipeline = null;
+            this.tokenizer = null;
+            this._isLoaded = false;
+            // Force GC if available
+            if (global.gc) {
+                global.gc();
+            }
+            this.logModelLoading('Resources cleaned up');
+        }
+        catch (error) {
+            console.warn(`Cleanup error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            this.pipeline = null;
+            this.tokenizer = null;
+            this._isLoaded = false;
+        }
+    }
+    // =============================================================================
+    // GENERATION IMPLEMENTATION
+    // =============================================================================
+    /**
+     * Generate text using the instruct model
+     */
+    async generateText(prompt, options) {
+        this.ensureLoaded();
+        try {
+            // Count prompt tokens
+            const promptTokens = await this.countTokens(prompt);
+            // Generate
+            const result = await this.pipeline(prompt, {
+                max_new_tokens: options.maxTokens,
+                temperature: options.temperature,
+                top_p: options.topP,
+                top_k: options.topK,
+                repetition_penalty: options.repetitionPenalty,
+                do_sample: options.temperature > 0,
+                return_full_text: false,
+                pad_token_id: this.tokenizer?.pad_token_id,
+                eos_token_id: this.tokenizer?.eos_token_id
+            });
+            // Extract generated text
+            const generatedText = result[0]?.generated_text || '';
+            // Process stop sequences
+            let finalText = generatedText;
+            let finishReason = 'complete';
+            for (const stopSeq of options.stopSequences) {
+                const stopIndex = finalText.indexOf(stopSeq);
+                if (stopIndex !== -1) {
+                    finalText = finalText.substring(0, stopIndex);
+                    finishReason = 'stop_sequence';
+                    break;
+                }
+            }
+            // Count completion tokens
+            const completionTokens = await this.countTokens(finalText);
+            // Check if we hit max tokens
+            if (completionTokens >= options.maxTokens - 5) {
+                finishReason = 'length';
+            }
+            return {
+                text: finalText,
+                promptTokens,
+                completionTokens,
+                finishReason
+            };
+        }
+        catch (error) {
+            throw new GenerationError(this.modelName, 'generation', `Text generation failed: ${error instanceof Error ? error.message : 'Unknown error'}`, error instanceof Error ? error : undefined);
+        }
+    }
+    /**
+     * Generate text with streaming output
+     */
+    async *generateStream(request) {
+        // For now, fall back to non-streaming and yield the full response
+        // TODO: Implement true streaming when transformers.js supports it better
+        const result = await this.generate(request);
+        yield result.response;
+    }
+    // =============================================================================
+    // HELPER METHODS
+    // =============================================================================
+    /**
+     * Count tokens in a text string
+     */
+    async countTokens(text) {
+        if (!this.tokenizer) {
+            // Fallback to estimation
+            return Math.ceil(text.length / 4);
+        }
+        try {
+            const encoded = await this.tokenizer(text, {
+                return_tensors: false,
+                padding: false,
+                truncation: false
+            });
+            return encoded.input_ids?.length || Math.ceil(text.length / 4);
+        }
+        catch {
+            return Math.ceil(text.length / 4);
+        }
+    }
+}
+//# sourceMappingURL=instruct-generator.js.map

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.js

@@ -54,6 +54,7 @@ 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
@@ -64,6 +65,13 @@ 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'
@@ -83,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
 `);
 }
@@ -126,6 +140,10 @@ function parseArgs() {
             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: {} };
             }
@@ -136,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 {