@juspay/neurolink 9.5.3 → 9.6.0

package/dist/lib/core/redisConversationMemoryManager.js

@@ -3,13 +3,13 @@
  * Redis-based implementation of conversation storage with same interface as ConversationMemoryManager
  */
 import { randomUUID } from "crypto";
+import { MESSAGES_PER_TURN } from "../config/conversationMemory.js";
+import { SummarizationEngine } from "../context/summarizationEngine.js";
+import { NeuroLink } from "../neurolink.js";
 import { ConversationMemoryError } from "../types/conversation.js";
-import { MESSAGES_PER_TURN, RECENT_MESSAGES_RATIO, } from "../config/conversationMemory.js";
+import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { logger } from "../utils/logger.js";
-import { NeuroLink } from "../neurolink.js";
-import { createRedisClient, getSessionKey, getUserSessionsKey, getNormalizedConfig, serializeConversation, deserializeConversation, scanKeys, } from "../utils/redis.js";
-import { TokenUtils } from "../constants/tokens.js";
-import { buildContextFromPointer, getEffectiveTokenThreshold, generateSummary, } from "../utils/conversationMemory.js";
+import { createRedisClient, deserializeConversation, getNormalizedConfig, getSessionKey, getUserSessionsKey, scanKeys, serializeConversation, } from "../utils/redis.js";
 /**
  * Redis-based implementation of the ConversationMemoryManager
  * Uses the same interface but stores data in Redis
@@ -17,6 +17,7 @@ import { buildContextFromPointer, getEffectiveTokenThreshold, generateSummary, }
 export class RedisConversationMemoryManager {
     config;
     isInitialized = false;
+    summarizationEngine = new SummarizationEngine();
     redisConfig;
     redisClient = null;
     /**
@@ -76,7 +77,47 @@ export class RedisConversationMemoryManager {
                     port: this.redisConfig.port,
                 },
             });
-            throw new ConversationMemoryError("Failed to initialize Redis conversation memory", "CONFIG_ERROR", { error: error instanceof Error ? error.message : String(error) });
+            throw new ConversationMemoryError("Failed to initialize Redis conversation memory", "CONFIG_ERROR", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Get session by ID, reconstructing a SessionMemory from Redis storage.
+     */
+    async getSession(sessionId, userId) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            return undefined;
+        }
+        try {
+            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+            const conversationData = await this.redisClient.get(redisKey);
+            const conversation = deserializeConversation(conversationData || null);
+            if (!conversation) {
+                return undefined;
+            }
+            return {
+                sessionId: conversation.sessionId,
+                userId: conversation.userId,
+                messages: conversation.messages,
+                summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                summarizedMessage: conversation.summarizedMessage,
+                tokenThreshold: conversation.tokenThreshold,
+                lastTokenCount: conversation.lastTokenCount,
+                lastCountedAt: conversation.lastCountedAt,
+                lastApiTokenCount: conversation.lastApiTokenCount,
+                createdAt: new Date(conversation.createdAt).getTime(),
+                lastActivity: new Date(conversation.updatedAt).getTime(),
+            };
+        }
+        catch (error) {
+            logger.error("[RedisConversationMemoryManager] Failed to get session", {
+                sessionId,
+                userId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return undefined;
         }
     }
     /**
@@ -300,6 +341,10 @@ export class RedisConversationMemoryManager {
                 events: options.events || undefined,
             };
             conversation.messages.push(assistantMsg);
+            // Store API-reported token counts if available
+            if (options.tokenUsage) {
+                conversation.lastApiTokenCount = options.tokenUsage;
+            }
             logger.info("[RedisConversationMemoryManager] Added new messages", {
                 sessionId: conversation.sessionId,
                 userId: conversation.userId,
@@ -359,7 +404,6 @@ export class RedisConversationMemoryManager {
     async checkAndSummarize(conversation, threshold, sessionId, userId) {
         const normalizedUserId = userId || "randomUser";
         const summarizationKey = `${sessionId}:${normalizedUserId}`;
-        // Acquire lock - if already in progress, skip
         if (this.summarizationInProgress.has(summarizationKey)) {
             logger.debug("[RedisConversationMemoryManager] Summarization already in progress, skipping", {
                 sessionId,
@@ -381,12 +425,20 @@ export class RedisConversationMemoryManager {
                 createdAt: new Date(conversation.createdAt).getTime(),
                 lastActivity: new Date(conversation.updatedAt).getTime(),
             };
-            const contextMessages = buildContextFromPointer(session);
-            const tokenCount = this.estimateTokens(contextMessages);
-            conversation.lastTokenCount = tokenCount;
-            conversation.lastCountedAt = Date.now();
-            if (tokenCount >= threshold) {
-                await this.summarizeSessionTokenBased(conversation, threshold, sessionId, userId);
+            const summarized = await this.summarizationEngine.checkAndSummarize(session, threshold, this.config, "[RedisConversationMemoryManager]");
+            conversation.lastTokenCount = session.lastTokenCount;
+            conversation.lastCountedAt = session.lastCountedAt;
+            if (summarized) {
+                conversation.summarizedUpToMessageId = session.summarizedUpToMessageId;
+                conversation.summarizedMessage = session.summarizedMessage;
+                if (this.redisClient) {
+                    const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                    const serializedData = serializeConversation(conversation);
+                    await this.redisClient.set(redisKey, serializedData);
+                    if (this.redisConfig.ttl > 0) {
+                        await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                    }
+                }
             }
         }
         catch (error) {
@@ -396,71 +448,9 @@ export class RedisConversationMemoryManager {
             });
         }
         finally {
-            // Release lock when done
             this.summarizationInProgress.delete(summarizationKey);
         }
     }
-    /**
-     * Estimate total tokens for a list of messages
-     */
-    estimateTokens(messages) {
-        return messages.reduce((total, msg) => {
-            return total + TokenUtils.estimateTokenCount(msg.content);
-        }, 0);
-    }
-    /**
-     * Token-based summarization (pointer-based, non-destructive)
-     */
-    async summarizeSessionTokenBased(conversation, threshold, sessionId, userId) {
-        const startIndex = conversation.summarizedUpToMessageId
-            ? conversation.messages.findIndex((m) => m.id === conversation.summarizedUpToMessageId) + 1
-            : 0;
-        const recentMessages = conversation.messages.slice(startIndex);
-        if (recentMessages.length === 0) {
-            return;
-        }
-        // We only want to include user, assistant, and system messages in summarization
-        const filteredRecentMessages = recentMessages.filter((msg) => msg.role !== "tool_call" && msg.role !== "tool_result");
-        const targetRecentTokens = threshold * RECENT_MESSAGES_RATIO;
-        const splitIndex = await this.findSplitIndexByTokens(filteredRecentMessages, targetRecentTokens);
-        const messagesToSummarize = filteredRecentMessages.slice(0, splitIndex);
-        if (messagesToSummarize.length === 0) {
-            return;
-        }
-        const summary = await generateSummary(messagesToSummarize, this.config, "[RedisConversationMemoryManager]", conversation.summarizedMessage);
-        if (!summary) {
-            logger.warn(`[RedisConversationMemoryManager] Summary generation failed for session ${conversation.sessionId}`);
-            return;
-        }
-        const lastSummarized = messagesToSummarize[messagesToSummarize.length - 1];
-        conversation.summarizedUpToMessageId = lastSummarized.id;
-        conversation.summarizedMessage = summary;
-        if (this.redisClient) {
-            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-            const serializedData = serializeConversation(conversation);
-            await this.redisClient.set(redisKey, serializedData);
-            if (this.redisConfig.ttl > 0) {
-                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
-            }
-        }
-    }
-    /**
-     * Find split index to keep recent messages within target token count
-     */
-    async findSplitIndexByTokens(messages, targetRecentTokens) {
-        let recentTokens = 0;
-        let splitIndex = messages.length;
-        for (let i = messages.length - 1; i >= 0; i--) {
-            const msgTokens = TokenUtils.estimateTokenCount(messages[i].content);
-            if (recentTokens + msgTokens > targetRecentTokens) {
-                splitIndex = i + 1;
-                break;
-            }
-            recentTokens += msgTokens;
-        }
-        // Ensure we're summarizing at least something
-        return Math.max(1, splitIndex);
-    }
     /**
      * Build context messages for AI prompt injection (TOKEN-BASED)
      * Returns messages from pointer onwards (or all if no pointer)
@@ -625,7 +615,10 @@ export class RedisConversationMemoryManager {
         }
         await this.ensureInitialized();
         if (!this.redisClient) {
-            logger.warn("[RedisConversationMemoryManager] Redis client not available for getUserSessionObject", { userId, sessionId });
+            logger.warn("[RedisConversationMemoryManager] Redis client not available for getUserSessionObject", {
+                userId,
+                sessionId,
+            });
             return null;
         }
         try {
@@ -903,8 +896,6 @@ User message: "${userMessage}`;
                             ? sessionError.message
                             : String(sessionError),
                     });
-                    // Continue with other sessions even if one fails
-                    continue;
                 }
             }
             return results;

package/dist/lib/factories/providerFactory.d.ts

@@ -10,11 +10,11 @@ type ProviderConstructor = {
 /**
  * Provider registration entry
  */
-interface ProviderRegistration {
+type ProviderRegistration = {
     constructor: ProviderConstructor;
     defaultModel?: string;
     aliases?: string[];
-}
+};
 /**
  * True Factory Pattern implementation for AI Providers
  * Uses registration-based approach to eliminate switch statements

package/dist/lib/files/fileReferenceRegistry.d.ts

@@ -0,0 +1,276 @@
+/**
+ * File Reference Registry
+ *
+ * Central registry for managing file references in on-demand processing mode.
+ * Files are registered with lightweight metadata and previews. Full content
+ * is processed on-demand when the LLM requests it via tools.
+ *
+ * This module is the core of the file reference architecture, replacing
+ * the previous "load everything upfront" pattern for files that exceed
+ * the tiny/small size tiers.
+ *
+ * @module files/fileReferenceRegistry
+ */
+import type { FileSource } from "../types/fileTypes.js";
+import type { FileExtractionParams, FileExtractionResult, FileReadResult, FileReference, FileRegistrationOptions, FileRegistryOptions, FileSearchResult, SizeTier } from "./types.js";
+/**
+ * Registry for managing file references with on-demand processing.
+ *
+ * Design decisions:
+ * - One instance per NeuroLink SDK instance (not global singleton)
+ * - File buffers persisted to temp dir for later streaming access
+ * - LRU eviction when maxFiles exceeded
+ * - Thread-safe via sequential async operations (Node.js single-threaded)
+ *
+ * @example
+ * ```typescript
+ * const registry = new FileReferenceRegistry();
+ * const ref = await registry.register(buffer, {
+ *   filename: 'report.xlsx',
+ * });
+ * console.log(ref.sizeTier);      // 'medium'
+ * console.log(ref.preview);       // First 2000 chars of processed content
+ * console.log(ref.estimatedTokens); // Type-aware estimate
+ *
+ * // Later, LLM requests specific section
+ * const section = await registry.readSection(ref.id, 1, 50, 5000);
+ * ```
+ */
+export declare class FileReferenceRegistry {
+    private files;
+    private tempDir;
+    private maxFiles;
+    private maxTempBytes;
+    private defaultPreviewChars;
+    private currentTempBytes;
+    private tempDirCreated;
+    constructor(options?: FileRegistryOptions);
+    /**
+     * Register a file from a Buffer.
+     *
+     * This is the primary registration method. It performs lightweight analysis:
+     * 1. Detect file type from magic bytes (first 1KB)
+     * 2. Determine size tier
+     * 3. Extract preview (first N chars of text, or metadata for binary)
+     * 4. Persist buffer to temp directory for later streaming access
+     *
+     * Total time: ~1-5ms for most files (no full processing).
+     *
+     * @param buffer - File content as Buffer
+     * @param source - How the file was provided ('buffer', 'url', 'path', 'datauri')
+     * @param options - Registration options
+     * @returns FileReference with metadata and preview
+     */
+    register(buffer: Buffer, source?: FileSource, options?: FileRegistrationOptions): Promise<FileReference>;
+    /**
+     * Register a file from a file path on disk.
+     *
+     * Does NOT read the entire file — only reads the first 1KB for type detection
+     * and preview. The file path is stored for later streaming access.
+     *
+     * @param filePath - Absolute path to the file
+     * @param options - Registration options
+     * @returns FileReference with metadata and preview
+     */
+    registerFromPath(filePath: string, options?: FileRegistrationOptions): Promise<FileReference>;
+    /**
+     * Get a file reference by ID.
+     * Updates lastAccessedAt for LRU tracking.
+     */
+    get(id: string): FileReference | undefined;
+    /**
+     * Get a file reference by ID or filename.
+     * Tries ID lookup first, then falls back to filename match.
+     * This handles the common case where an LLM uses the filename
+     * instead of the UUID when calling file tools.
+     *
+     * @param idOrName - UUID or filename to search for
+     * @returns File reference if found, undefined otherwise
+     */
+    getByIdOrFilename(idOrName: string): FileReference | undefined;
+    /**
+     * Ensure a file has been processed (binary content extracted to text).
+     *
+     * For text files this is a no-op. For binary files (PDF, XLSX, video, etc.)
+     * this triggers on-demand processing if it hasn't happened yet. After this
+     * call, ref.processedContent and ref.preview contain extracted text.
+     *
+     * Used by file tools (get_file_preview) to ensure the preview contains
+     * real content instead of placeholder metadata strings.
+     */
+    ensureProcessed(fileId: string): Promise<void>;
+    /**
+     * Extract targeted content from a registered file.
+     *
+     * This is the core dispatch method for the `extract_file_content` tool.
+     * Routes extraction to the appropriate processor based on file type and
+     * the parameters provided.
+     *
+     * @param params - Extraction parameters (file_id + type-specific options)
+     * @returns Extraction result with text and/or images
+     */
+    extractContent(params: FileExtractionParams): Promise<FileExtractionResult>;
+    private extractVideoTargeted;
+    private extractPdfTargeted;
+    private extractExcelTargeted;
+    private extractPptxTargeted;
+    private extractArchiveTargeted;
+    private extractAudioTargeted;
+    private extractTextTargeted;
+    /**
+     * List all registered files.
+     * Returns a lightweight summary suitable for the LLM.
+     */
+    list(): FileReference[];
+    /**
+     * Generate a formatted table of all registered files for the LLM.
+     */
+    listFormatted(): string;
+    /**
+     * Read a section of a registered file.
+     *
+     * Uses StreamingReader for memory-efficient access.
+     *
+     * @param fileId - File reference ID
+     * @param startLine - Starting line (1-indexed)
+     * @param endLine - Ending line (1-indexed)
+     * @param tokenBudget - Maximum tokens to return
+     * @param provider - Provider name for token estimation
+     * @returns FileReadResult
+     */
+    readSection(fileId: string, startLine?: number, endLine?: number, tokenBudget?: number, provider?: string): Promise<FileReadResult>;
+    /**
+     * Search within a registered file.
+     *
+     * @param fileId - File reference ID
+     * @param pattern - Search pattern (string or regex)
+     * @param maxMatches - Maximum matches to return
+     * @returns FileSearchResult
+     */
+    search(fileId: string, pattern: string, maxMatches?: number): Promise<FileSearchResult>;
+    /**
+     * Search within in-memory content (for tiny files without temp paths).
+     */
+    private static searchInMemory;
+    /**
+     * Store a summary for a file reference.
+     */
+    setSummary(fileId: string, summary: string): void;
+    /**
+     * Remove a file reference and clean up its temp file.
+     */
+    remove(fileId: string): Promise<boolean>;
+    /**
+     * Clear all file references and clean up temp directory.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of registered files.
+     */
+    get size(): number;
+    /**
+     * Generate the preview text for the initial prompt.
+     *
+     * Returns a compact summary of all registered files that uses ~50-100 tokens
+     * per file instead of full content. The LLM can use file tools to access
+     * more content as needed.
+     *
+     * @returns Formatted string for prompt injection
+     */
+    generatePromptPreview(): Promise<string>;
+    /**
+     * Get type-specific extraction hints for the LLM prompt.
+     * Tells the LLM what parameters it can use with extract_file_content.
+     */
+    static getExtractionHint(type: string, sizeStr: string): string | null;
+    /**
+     * Classify a file into a size tier based on byte size.
+     */
+    static classifySizeTier(sizeBytes: number): SizeTier;
+    /**
+     * Process a binary file on-demand, extracting text content via the
+     * appropriate processor. This bridges the gap between the lazy registration
+     * path (which stores raw binary) and the LLM read tools (which need text).
+     *
+     * Called lazily on first readSection() or search() for non-text files.
+     * Results are cached in ref.processedContent for subsequent reads.
+     */
+    private processFileOnDemand;
+    /**
+     * Extract text from a PDF buffer using pdf-parse v2 (pdfjs-dist under the hood).
+     *
+     * Handles compressed streams (FlateDecode), CMap-encoded text, modern PDFs,
+     * and most text-based PDF formats. For scanned/image-only PDFs where no text
+     * can be extracted, falls back to a descriptive message.
+     */
+    private extractPdfText;
+    /**
+     * Extract text content from an Excel file using ExcelProcessor.
+     */
+    private extractExcelText;
+    /**
+     * Extract text content from a Word document using WordProcessor.
+     */
+    private extractWordText;
+    /**
+     * Extract text from a PowerPoint file using PptxProcessor.
+     */
+    private extractPptxText;
+    /**
+     * Extract metadata and content from a video file using VideoProcessor.
+     */
+    private extractVideoContent;
+    /**
+     * Extract metadata and content from an audio file using AudioProcessor.
+     */
+    private extractAudioContent;
+    /**
+     * Extract file listing from an archive using ArchiveProcessor.
+     */
+    private extractArchiveContent;
+    /**
+     * Extract a preview from a buffer.
+     * For text: first N characters.
+     * For binary: type-specific metadata.
+     */
+    private extractPreview;
+    /**
+     * Detect file type from buffer magic bytes and extension.
+     */
+    private detectType;
+    /**
+     * Detect file type from extension alone.
+     */
+    private detectTypeFromExtension;
+    /**
+     * Whether a file type contains readable text content.
+     * For "unknown" types, optionally checks the buffer for valid UTF-8 text.
+     */
+    private isTextType;
+    /**
+     * Heuristic check: does a buffer look like valid text content?
+     * Checks the first 512 bytes for mostly printable ASCII/UTF-8 characters.
+     * Returns true if >90% of bytes are printable (ASCII 0x20-0x7E, tab, newline, CR).
+     */
+    private static looksLikeText;
+    /**
+     * Guess MIME type from file type and extension.
+     */
+    private guessMimeType;
+    /**
+     * Guess file extension from magic bytes.
+     */
+    private guessExtension;
+    /**
+     * Persist a buffer to the temp directory.
+     */
+    private persistToTemp;
+    /**
+     * Evict the least recently used file reference.
+     */
+    private evictLRU;
+    /**
+     * Format byte size as human-readable string.
+     */
+    private formatSize;
+}