rag-lite-ts 2.3.0 → 2.3.1

package/dist/esm/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/esm/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/esm/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/esm/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/esm/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rag-lite-ts",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Local-first TypeScript retrieval engine with Chameleon Multimodal Architecture for semantic search over text and image content",
   "type": "module",
   "main": "./dist/cjs/index.js",