@airoom/nextmin-node 2.0.1 → 2.0.3

package/dist/services/LocalAIService.d.ts

@@ -0,0 +1,34 @@
+export declare class LocalAIService {
+    private static llamaInstance;
+    private static modelInstance;
+    private static contextInstance;
+    private static activeSessions;
+    private static cleanupInterval;
+    constructor(localModelPath?: string);
+    private static initCleanupTimer;
+    /**
+     * Lazily loads the Llama model and context into memory to ensure fast response times
+     * and avoid reading the multi-gigabyte GGUF model file from disk repeatedly.
+     */
+    private getLlamaModelAndContext;
+    /**
+     * Simple TF-IDF local search on scraped pages stored in .nextmin/scraped-pages
+     */
+    /**
+     * Simple TF-IDF local search on scraped pages stored in .nextmin/scraped-pages
+     * with smart paragraph-based chunking and path boosting.
+     */
+    private localSearch;
+    /**
+     * Generates chat answer using local node-llama-cpp execution.
+     */
+    generateAnswer(history: Array<{
+        role: string;
+        content: string;
+    }>, currentMessage: string, systemPromptText?: string, localModelPath?: string, threads?: number, threadId?: string, onTextChunk?: (chunk: string) => void): Promise<string>;
+    /**
+     * Prewarm helper to load the model and context in the background
+     */
+    prewarm(localModelPath?: string, threads?: number): Promise<void>;
+    private importLlamaCpp;
+}

package/dist/services/LocalAIService.js

@@ -0,0 +1,471 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAIService = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const Logger_1 = __importDefault(require("../utils/Logger"));
+class LocalAIService {
+    constructor(localModelPath) {
+        // Constructor kept for signature compatibility
+    }
+    static initCleanupTimer() {
+        if (LocalAIService.cleanupInterval)
+            return;
+        LocalAIService.cleanupInterval = setInterval(() => {
+            const now = Date.now();
+            const TTL = 10 * 60 * 1000; // 10 minutes
+            for (const [threadId, entry] of LocalAIService.activeSessions.entries()) {
+                if (now - entry.lastAccessed > TTL) {
+                    try {
+                        const seq = entry.sequence || entry.session?.contextSequence || entry.session;
+                        if (seq && typeof seq.dispose === 'function') {
+                            seq.dispose();
+                        }
+                        Logger_1.default.info('LocalAIService', `Disposed inactive chat sequence for thread: ${threadId}`);
+                    }
+                    catch (err) {
+                        Logger_1.default.warn('LocalAIService', `Failed to dispose inactive sequence for thread: ${threadId}`, err);
+                    }
+                    LocalAIService.activeSessions.delete(threadId);
+                }
+            }
+        }, 60000);
+        if (LocalAIService.cleanupInterval?.unref) {
+            LocalAIService.cleanupInterval.unref();
+        }
+    }
+    /**
+     * Lazily loads the Llama model and context into memory to ensure fast response times
+     * and avoid reading the multi-gigabyte GGUF model file from disk repeatedly.
+     */
+    async getLlamaModelAndContext(localModelPath, threads) {
+        if (LocalAIService.modelInstance && LocalAIService.contextInstance) {
+            return { model: LocalAIService.modelInstance, context: LocalAIService.contextInstance };
+        }
+        Logger_1.default.info('LocalAIService', 'Initializing node-llama-cpp and loading model/context...');
+        const modelPath = localModelPath || process.env.LOCAL_MODEL_PATH || path_1.default.join(process.cwd(), 'model', 'gemma-4-E2B-it-Q3_K_M.gguf');
+        if (!fs_1.default.existsSync(modelPath)) {
+            throw new Error(`Local model not found at: ${modelPath}. Please place the Gemma GGUF model file at this location.`);
+        }
+        try {
+            const { getLlama } = await this.importLlamaCpp();
+            const llama = await getLlama({
+                gpu: false
+            });
+            LocalAIService.llamaInstance = llama;
+            const model = await llama.loadModel({
+                modelPath: modelPath
+            });
+            LocalAIService.modelInstance = model;
+            Logger_1.default.info('LocalAIService', `Model loaded successfully from ${modelPath}`);
+            const threadCount = threads || parseInt(process.env.LLAMA_THREADS || '3', 10);
+            const context = await model.createContext({
+                threads: threadCount,
+                contextSize: 4096,
+                sequences: 2
+            });
+            LocalAIService.contextInstance = context;
+            Logger_1.default.info('LocalAIService', `Context created successfully with ${threadCount} threads and 2 sequence slots.`);
+            return { model, context };
+        }
+        catch (err) {
+            Logger_1.default.error('LocalAIService', 'Failed to initialize node-llama-cpp or load the model/context', err);
+            throw err;
+        }
+    }
+    /**
+     * Simple TF-IDF local search on scraped pages stored in .nextmin/scraped-pages
+     */
+    /**
+     * Simple TF-IDF local search on scraped pages stored in .nextmin/scraped-pages
+     * with smart paragraph-based chunking and path boosting.
+     */
+    async localSearch(query, limit = 6) {
+        const dir = path_1.default.join(process.cwd(), '.nextmin', 'scraped-pages');
+        if (!fs_1.default.existsSync(dir)) {
+            Logger_1.default.warn('LocalAIService', `Scraped pages directory does not exist at ${dir}`);
+            return '';
+        }
+        const files = fs_1.default.readdirSync(dir).filter(f => f.endsWith('.txt'));
+        if (files.length === 0) {
+            Logger_1.default.warn('LocalAIService', 'No scraped pages found for local search.');
+            return '';
+        }
+        // Helper to tokenize and normalize words (supports Unicode/Bengali characters)
+        const tokenize = (text) => {
+            return text
+                .toLowerCase()
+                .replace(/[^\p{L}\p{M}\p{N}\s-]/gu, ' ')
+                .split(/[\s_]+/)
+                .filter(w => w.length > 2);
+        };
+        // Fuzzy-normalize the query: fix common typos and aliases for known product terms.
+        // Simple edit-distance check: if a word is within 1-2 chars of a known term, correct it.
+        const knownTerms = ['nextmin', 'nextmin-node', 'nextmin-react', 'nmadapter'];
+        const normalizeQuery = (q) => {
+            return q.replace(/\b\w+\b/g, (word) => {
+                const lower = word.toLowerCase();
+                for (const term of knownTerms) {
+                    if (lower === term)
+                        return word; // exact match, keep
+                    // Simple typo check: same length ±1, and share most chars
+                    if (Math.abs(lower.length - term.length) <= 1) {
+                        let mismatches = 0;
+                        const shorter = lower.length < term.length ? lower : term;
+                        const longer = lower.length < term.length ? term : lower;
+                        let si = 0;
+                        for (let li = 0; li < longer.length && si < shorter.length; li++) {
+                            if (longer[li] !== shorter[si]) {
+                                mismatches++;
+                            }
+                            else {
+                                si++;
+                            }
+                        }
+                        mismatches += (longer.length - si); // remaining unmatched chars
+                        if (mismatches <= 2 && shorter.length >= 5)
+                            return term; // correct to known term
+                    }
+                }
+                return word;
+            });
+        };
+        const normalizedQuery = normalizeQuery(query);
+        if (normalizedQuery !== query) {
+            Logger_1.default.info('LocalAIService', `Query normalized: "${query}" → "${normalizedQuery}"`);
+        }
+        const queryTokens = tokenize(normalizedQuery);
+        if (queryTokens.length === 0)
+            return '';
+        const chunks = [];
+        const termDocCount = new Map();
+        // 1. Process files into semantic chunks
+        for (const file of files) {
+            try {
+                const rawContent = fs_1.default.readFileSync(path_1.default.join(dir, file), 'utf-8');
+                // Decode HTML entities so scraped text is clean for TF-IDF and LLM context
+                let content = rawContent
+                    .replace(/&amp;/g, '&')
+                    .replace(/&lt;/g, '<')
+                    .replace(/&gt;/g, '>')
+                    .replace(/&quot;/g, '"')
+                    .replace(/&#39;/g, "'")
+                    .replace(/&nbsp;/g, ' ');
+                // Clean repeating header menu and footer disclaimer to keep context 100% focused on page content
+                content = content.replace(/\[Home\]\(\/\)[\s\S]*?open navigation menu/gi, '');
+                content = content.replace(/Disclaimer: Information on Doctors24[\s\S]*/gi, '');
+                let name = file.replace(/^page-/, '').replace(/\.txt$/, '');
+                if (name.startsWith('_'))
+                    name = name.slice(1);
+                const urlPath = '/' + name.replace(/_/g, '/');
+                // Tokenize path name and boost it (3x weight multiplier)
+                const pathTokens = tokenize(name.replace(/_/g, ' '));
+                const boostedPathTokens = [];
+                for (const token of pathTokens) {
+                    boostedPathTokens.push(token, token, token);
+                }
+                // Split by paragraphs
+                const paragraphs = content.split(/\n\s*\n+/);
+                let currentChunkText = '';
+                const saveChunk = (text) => {
+                    const cleanText = text.trim();
+                    if (cleanText.length < 20)
+                        return;
+                    const bodyTokens = tokenize(cleanText);
+                    const chunkTokens = [...bodyTokens, ...boostedPathTokens];
+                    chunks.push({
+                        file,
+                        urlPath,
+                        content: cleanText,
+                        tokens: chunkTokens,
+                        length: chunkTokens.length
+                    });
+                };
+                for (const para of paragraphs) {
+                    const cleanPara = para.trim();
+                    if (!cleanPara)
+                        continue;
+                    // Group smaller paragraphs to make substantial chunks of 800-1200 chars
+                    if (currentChunkText.length + cleanPara.length < 1000) {
+                        currentChunkText += (currentChunkText ? '\n\n' : '') + cleanPara;
+                    }
+                    else {
+                        if (currentChunkText) {
+                            saveChunk(currentChunkText);
+                        }
+                        currentChunkText = cleanPara;
+                    }
+                }
+                if (currentChunkText) {
+                    saveChunk(currentChunkText);
+                }
+            }
+            catch (err) {
+                // Skip unreadable files
+            }
+        }
+        const totalChunks = chunks.length;
+        if (totalChunks === 0)
+            return '';
+        // 2. Count document frequency of each token in the chunk corpus
+        for (const chunk of chunks) {
+            const uniqueTokens = new Set(chunk.tokens);
+            for (const token of uniqueTokens) {
+                termDocCount.set(token, (termDocCount.get(token) || 0) + 1);
+            }
+        }
+        // 3. Compute TF-IDF score for each chunk
+        const scores = [];
+        for (const chunk of chunks) {
+            let score = 0;
+            for (const token of queryTokens) {
+                const tf = chunk.tokens.filter(t => t === token).length;
+                if (tf > 0) {
+                    const docFreq = termDocCount.get(token) || 1;
+                    const idf = Math.log(1 + totalChunks / docFreq);
+                    score += tf * idf;
+                }
+            }
+            if (score > 0) {
+                // Normalize score by square root of length to prevent long chunk bias
+                const normScore = score / Math.sqrt(chunk.length + 1);
+                // Match ratio check using only INFORMATIVE query tokens (high IDF).
+                // Tokens appearing in >50% of all chunks (like "nextmin" in every nav bar)
+                // are corpus stop-words and should not count toward relevance matching.
+                const bodyTokenSet = new Set(tokenize(chunk.content));
+                const informativeQueryTokens = [...new Set(queryTokens)].filter(t => {
+                    const docFreq = termDocCount.get(t) || 0;
+                    return docFreq > 0 && docFreq / totalChunks < 0.5; // appears in <50% of chunks
+                });
+                // If there are no informative tokens in the query (e.g. pure greeting),
+                // let it through — the greeting check handles that case later.
+                if (informativeQueryTokens.length === 0) {
+                    scores.push({ chunk, score: normScore });
+                    continue;
+                }
+                const matchedCount = informativeQueryTokens.filter(t => bodyTokenSet.has(t)).length;
+                const matchRatio = matchedCount / informativeQueryTokens.length;
+                // Require either 2+ informative token matches, OR ≥50% match ratio (for short queries).
+                // Single coincidental matches (e.g. "price" in an API code example) don't count.
+                const meetsThreshold = matchedCount >= 2 || (informativeQueryTokens.length <= 2 && matchRatio >= 0.5);
+                if (meetsThreshold) {
+                    scores.push({ chunk, score: normScore });
+                }
+            }
+        }
+        // 4. Sort, apply minimum score threshold, and return top chunks
+        scores.sort((a, b) => b.score - a.score);
+        // Minimum relevance threshold: if the best chunk score is too low,
+        // none of the content is actually relevant to this query — return empty
+        // so the caller can show the friendly fallback message instead.
+        const MIN_SCORE_THRESHOLD = 0.15;
+        const relevantScores = scores.filter(s => s.score >= MIN_SCORE_THRESHOLD);
+        if (relevantScores.length === 0) {
+            Logger_1.default.info('LocalAIService', `RAG: no chunks above threshold (${MIN_SCORE_THRESHOLD}) for query: "${query}". Best score: ${scores[0]?.score.toFixed(4) ?? 'none'}`);
+            return '';
+        }
+        const topMatches = relevantScores.slice(0, limit);
+        Logger_1.default.info('LocalAIService', `RAG retrieved ${topMatches.length} relevant chunks for query: "${query}"`);
+        topMatches.forEach((m, i) => {
+            Logger_1.default.info('LocalAIService', `  Chunk ${i + 1}: score=${m.score.toFixed(4)} page=${m.chunk.urlPath} snippet="${m.chunk.content.slice(0, 80).replace(/\n/g, ' ')}..."`);
+        });
+        const contextParts = [];
+        // Limit to top 3 chunks and truncate each to 600 chars to stay within Gemma's context window
+        for (const match of topMatches.slice(0, 3)) {
+            const c = match.chunk;
+            const truncated = c.content.length > 600 ? c.content.slice(0, 600) + '...' : c.content;
+            contextParts.push(`SOURCE PAGE: ${c.urlPath}\n${truncated}`);
+        }
+        return contextParts.join('\n\n');
+    }
+    /**
+     * Generates chat answer using local node-llama-cpp execution.
+     */
+    async generateAnswer(history, currentMessage, systemPromptText, localModelPath, threads, threadId, onTextChunk) {
+        try {
+            // Get all previous user messages from history
+            const userHistory = history.filter(h => h.role === 'user').map(h => h.content);
+            const searchQuery = userHistory.length > 0
+                ? `${userHistory[userHistory.length - 1]} ${currentMessage}`
+                : currentMessage;
+            // 1. Perform local TF-IDF matching on the scraped pages for context using the context-aware query
+            const context = await this.localSearch(searchQuery);
+            // If no context found, check if it's a greeting/chit-chat first.
+            // Greetings still get a warm LLM reply; substantive questions get a friendly fallback.
+            if (!context) {
+                const lowerMsg = currentMessage.toLowerCase().trim();
+                const isGreeting = /^(hi|hello|hey|howdy|hiya|yo|sup|good\s+(morning|afternoon|evening|day)|how are you|what can you do|who are you|what('s| is) up)/.test(lowerMsg);
+                if (!isGreeting) {
+                    Logger_1.default.warn('LocalAIService', `No context found for query: "${currentMessage}". Returning friendly fallback.`);
+                    return "Thanks for asking! 😊 I don't have enough information on that just yet, but we're working on it. Please check back soon or visit our website for the latest details!";
+                }
+                Logger_1.default.info('LocalAIService', `No context for greeting query: "${currentMessage}". Routing to LLM.`);
+            }
+            // Build system prompt that grounds the model in the retrieved context
+            const contextBlock = context
+                ? `\n\n===== RELEVANT WEBSITE CONTENT =====\n${context}\n===== END OF WEBSITE CONTENT =====`
+                : '';
+            // Build standard RAG guidelines to prevent link hallucinations and force descriptions
+            const ragInstructions = `
+CRITICAL RAG INSTRUCTIONS:
+- Base your answers on the website content provided and the system instructions.
+- STRICT URL FORMATTING RULES:
+  * For any link, you MUST use the exact path from the SOURCE PAGE line (which will always start with "/"). Example: If the source page is "SOURCE PAGE: /some-path", the link MUST be exactly "[base-url]/some-path". Do NOT change, nest, or modify the prefix or structure.
+  * DO NOT make up or guess any URL paths or slugs. Only use the exact path provided in the "SOURCE PAGE: [path]" line.
+- Do not guess, make up, or hallucinate any URL paths, details, or names that are not explicitly shown in the website content or defined in the system instructions.
+- When suggesting a page, section, or link, always write a short description first to explain it before sharing the link. Do not output raw links.
+- Only output up to 3-5 highly relevant links.
+- If the user asks for a specific URL, check if it's in the website content or system instructions. If it is, output it directly.`;
+            const baseSystemPrompt = systemPromptText || `You are a helpful website assistant. Answer questions using the website content provided.`;
+            const systemWithContext = `${baseSystemPrompt}\n\n${ragInstructions}${contextBlock}`;
+            // 2. Build the user prompt — inject context at message level too so Gemma/Llama can't miss it
+            const userPrompt = context
+                ? `Using the website content provided in the system instructions, answer this question:\n\n${currentMessage}`
+                : currentMessage;
+            // 3. Initialize/fetch Llama model and context
+            const { context: contextInstance } = await this.getLlamaModelAndContext(localModelPath, threads);
+            const useCache = !!threadId;
+            let sequence;
+            let tempSequence = null;
+            if (useCache && LocalAIService.activeSessions.has(threadId)) {
+                const entry = LocalAIService.activeSessions.get(threadId);
+                sequence = entry.sequence;
+                if (entry.session && !sequence) {
+                    sequence = entry.session.contextSequence;
+                }
+                entry.sequence = sequence;
+                delete entry.session;
+                entry.lastAccessed = Date.now();
+                Logger_1.default.info('LocalAIService', `Reusing existing chat sequence for thread: ${threadId}`);
+            }
+            else {
+                const MAX_SEQUENCES = 2;
+                if (useCache && LocalAIService.activeSessions.size >= MAX_SEQUENCES) {
+                    let oldestThreadId = null;
+                    let oldestTime = Infinity;
+                    for (const [tid, entry] of LocalAIService.activeSessions.entries()) {
+                        if (entry.lastAccessed < oldestTime) {
+                            oldestTime = entry.lastAccessed;
+                            oldestThreadId = tid;
+                        }
+                    }
+                    if (oldestThreadId) {
+                        try {
+                            const entry = LocalAIService.activeSessions.get(oldestThreadId);
+                            const seqToDispose = entry.sequence || entry.session?.contextSequence || entry.session;
+                            if (seqToDispose && typeof seqToDispose.dispose === 'function') {
+                                seqToDispose.dispose();
+                            }
+                            Logger_1.default.info('LocalAIService', `Evicted oldest active sequence ${oldestThreadId} to free a sequence slot.`);
+                        }
+                        catch (err) {
+                            Logger_1.default.warn('LocalAIService', `Failed to dispose evicted sequence ${oldestThreadId}`, err);
+                        }
+                        LocalAIService.activeSessions.delete(oldestThreadId);
+                    }
+                }
+                sequence = contextInstance.getSequence();
+                if (!useCache) {
+                    tempSequence = sequence;
+                }
+                if (useCache) {
+                    LocalAIService.activeSessions.set(threadId, { sequence, lastAccessed: Date.now() });
+                    Logger_1.default.info('LocalAIService', `Created new chat sequence for thread: ${threadId}`);
+                }
+            }
+            const { LlamaChatSession } = await this.importLlamaCpp();
+            const session = new LlamaChatSession({
+                contextSequence: sequence,
+                systemPrompt: systemWithContext
+            });
+            // 4. Format history for node-llama-cpp v3
+            const llamaHistory = [];
+            let tempUserText = '';
+            for (const msg of history) {
+                if (msg.role === 'user') {
+                    tempUserText = msg.content;
+                }
+                else if (msg.role === 'model' || msg.role === 'assistant') {
+                    if (tempUserText) {
+                        llamaHistory.push({ role: 'user', text: tempUserText });
+                        tempUserText = '';
+                    }
+                    llamaHistory.push({ role: 'model', response: [msg.content] });
+                }
+            }
+            if (llamaHistory.length > 0) {
+                session.setChatHistory(llamaHistory);
+            }
+            // Extract frontend/base URL to guide link formatting
+            const baseUrl = process.env.FRONTEND_URL ? process.env.FRONTEND_URL.replace(/\/$/, '') : 'https://doctors24.bd';
+            // Build the final prompt — context goes DIRECTLY in the message for maximum reliability.
+            const finalPrompt = context
+                ? `Here is the relevant website content:\n\n${context}\n\n---\n\nAnswer the following question naturally, conversationally, and informatively as our support agent. Provide a helpful description or summary first to explain the content before sharing any links. Do not just output the URL on its own. 
+
+IMPORTANT ROUTING & LINK RULES:
+1. When mentioning any page, section, or link from the website content, you MUST format it as a full clickable URL using the base URL "${baseUrl}".
+2. Use the exact path provided in the SOURCE PAGE line. For example, if it says "SOURCE PAGE: /some-path", the URL MUST be exactly "${baseUrl}/some-path". Do NOT modify the path prefixes, names, or slugs.
+
+Question: ${currentMessage}`
+                : currentMessage;
+            Logger_1.default.info('LocalAIService', `In-process prompt to model: "${currentMessage}"`);
+            let response;
+            try {
+                response = await session.prompt(finalPrompt, {
+                    onTextChunk: onTextChunk || undefined,
+                    temperature: 0.7,
+                    repeatPenalty: {
+                        penalty: 1.15
+                    }
+                });
+            }
+            catch (promptErr) {
+                if (tempSequence) {
+                    tempSequence.dispose();
+                }
+                Logger_1.default.warn('LocalAIService', `Model returned empty/error output: ${promptErr.message}. Using friendly fallback.`);
+                return "Thanks for asking! 😊 I don't have enough information on that just yet, but we're working on it. Please check back soon or visit our website for the latest details!";
+            }
+            // Guard: if response is empty string, also return fallback
+            if (!response || !response.trim()) {
+                if (tempSequence) {
+                    tempSequence.dispose();
+                }
+                Logger_1.default.warn('LocalAIService', 'Model returned empty response. Using friendly fallback.');
+                return "Thanks for asking! 😊 I don't have enough information on that just yet, but we're working on it. Please check back soon or visit our website for the latest details!";
+            }
+            // 5. Dispose temporary sequence to prevent RAM memory leaks if not caching
+            if (tempSequence) {
+                tempSequence.dispose();
+            }
+            return response;
+        }
+        catch (err) {
+            Logger_1.default.error('LocalAIService', 'Failed to generate answer from local model', err);
+            throw err;
+        }
+    }
+    /**
+     * Prewarm helper to load the model and context in the background
+     */
+    async prewarm(localModelPath, threads) {
+        try {
+            await this.getLlamaModelAndContext(localModelPath, threads);
+        }
+        catch (err) {
+            Logger_1.default.warn('LocalAIService', 'Prewarm failed to load model/context', err);
+        }
+    }
+    async importLlamaCpp() {
+        return eval('import("node-llama-cpp")');
+    }
+}
+exports.LocalAIService = LocalAIService;
+LocalAIService.llamaInstance = null;
+LocalAIService.modelInstance = null;
+LocalAIService.contextInstance = null;
+LocalAIService.activeSessions = new Map();
+LocalAIService.cleanupInterval = null;

package/dist/services/OpenAIService.d.ts

@@ -0,0 +1,16 @@
+export declare class OpenAIService {
+    private static getConfigPath;
+    private static readOpenAIMetadata;
+    private static writeOpenAIMetadata;
+    /**
+     * Syncs local scraped text files to the OpenAI Vector Store.
+     * Uses parallel file uploads and batch attachments to optimize speed.
+     */
+    syncFilesToVectorStore(force?: boolean): Promise<void>;
+    /**
+     * Generates a streaming answer from OpenAI Responses API.
+     * Note: For user chat queries, we DO NOT retry on 429 because we want to fail-fast
+     * and fall back to the local Gemma offline model immediately without blocking.
+     */
+    generateAnswerStream(localThreadId: string, message: string, systemPrompt: string, onTextChunk: (chunk: string) => void, disableFileSearch?: boolean): Promise<string>;
+}