@juspay/neurolink 8.19.0 → 8.20.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [8.20.0](https://github.com/juspay/neurolink/compare/v8.19.1...v8.20.0) (2025-12-22)
+
+### Features
+
+- **(memory):** Implement token based summarization ([ffdc902](https://github.com/juspay/neurolink/commit/ffdc902f534c97a5aff38d7de419021fcabcd791))
+
+## [8.19.1](https://github.com/juspay/neurolink/compare/v8.19.0...v8.19.1) (2025-12-20)
+
+### Bug Fixes
+
+- **(files):** comprehensive extension-less file detection with fallback parsing (FD-018) ([7e9dbc7](https://github.com/juspay/neurolink/commit/7e9dbc78df48f6df051c7845824977f360f8feee))
+
 ## [8.19.0](https://github.com/juspay/neurolink/compare/v8.18.0...v8.19.0) (2025-12-18)
 
 ### Features

package/dist/adapters/providerImageAdapter.d.ts

@@ -60,4 +60,16 @@ export declare class ProviderImageAdapter {
      * Get all vision-capable providers
      */
     static getVisionProviders(): string[];
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images: Array<Buffer | string>, pdfPages?: number | null): number;
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray: Array<{
+        pageCount?: number | null;
+    }> | undefined): number;
 }

package/dist/adapters/providerImageAdapter.js

@@ -416,13 +416,19 @@ export class ProviderImageAdapter {
                     adaptedPayload = this.formatForOpenAI(text, images);
                     break;
                 case "litellm":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // LiteLLM uses same format as OpenAI but validate with litellm provider name
+                    this.validateImageCount(images.length, "litellm");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "mistral":
-                    adaptedPayload = this.formatForOpenAI(text, images);
+                    // Mistral uses same format as OpenAI but validate with mistral provider name
+                    this.validateImageCount(images.length, "mistral");
+                    adaptedPayload = this.formatForOpenAI(text, images, true);
                     break;
                 case "bedrock":
-                    adaptedPayload = this.formatForAnthropic(text, images);
+                    // Bedrock uses same format as Anthropic but validate with bedrock provider name
+                    this.validateImageCount(images.length, "bedrock");
+                    adaptedPayload = this.formatForAnthropic(text, images, true);
                     break;
                 default:
                     throw new Error(`Vision not supported for provider: ${provider}`);
@@ -666,4 +672,25 @@ export class ProviderImageAdapter {
     static getVisionProviders() {
         return Object.keys(VISION_CAPABILITIES);
     }
+    /**
+     * Count total "images" in a message (actual images + PDF pages)
+     * PDF pages count toward image limits for providers
+     */
+    static countImagesInMessage(images, pdfPages) {
+        const imageCount = images?.length || 0;
+        const pageCount = pdfPages ?? 0;
+        return imageCount + pageCount;
+    }
+    /**
+     * Extract page count from PDF metadata array
+     * Returns total pages across all PDFs
+     */
+    static countImagesInPages(pdfMetadataArray) {
+        if (!pdfMetadataArray || pdfMetadataArray.length === 0) {
+            return 0;
+        }
+        return pdfMetadataArray.reduce((total, pdf) => {
+            return total + (pdf.pageCount ?? 0);
+        }, 0);
+    }
 }

package/dist/cli/loop/optionsSchema.js

@@ -61,5 +61,9 @@ export const textGenerationOptionsSchema = {
         type: "string",
         description: "Context about tools/MCPs used in the interaction.",
     },
+    enableSummarization: {
+        type: "boolean",
+        description: "Enable or disable automatic conversation summarization for this request.",
+    },
 };
 //# sourceMappingURL=optionsSchema.js.map

package/dist/config/conversationMemory.d.ts

@@ -20,12 +20,28 @@ export declare const MESSAGES_PER_TURN = 2;
  * Used to enhance system prompts when conversation history exists
  */
 export declare const CONVERSATION_INSTRUCTIONS = "\n\nIMPORTANT: You are continuing an ongoing conversation. The previous messages in this conversation contain important context including:\n- Names, personal information, and preferences shared by the user\n- Projects, tasks, and topics discussed previously  \n- Any decisions, agreements, or conclusions reached\n\nAlways reference and build upon this conversation history when relevant. If the user asks about information mentioned earlier in the conversation, refer to those previous messages to provide accurate, contextual responses.";
+/**
+ * Percentage of model context window to use for conversation memory threshold
+ * Default: 80% of model's context window
+ */
+export declare const MEMORY_THRESHOLD_PERCENTAGE = 0.8;
+/**
+ * Fallback token threshold if model context unknown
+ */
+export declare const DEFAULT_FALLBACK_THRESHOLD = 50000;
+/**
+ * Ratio of threshold to keep as recent unsummarized messages
+ * When summarization triggers, this percentage of tokens from the end
+ * are preserved as detailed messages, while older content gets summarized.
+ */
+export declare const RECENT_MESSAGES_RATIO = 0.3;
 /**
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
-export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\n\nSTRUCTURED OUTPUT REQUIREMENT:\nYou MUST respond with ONLY a valid JSON object that matches the provided schema.\n- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like \"Excellent!\", \"Sure!\", \"Here is the result:\", etc.)\n- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)\n- Do NOT wrap the JSON in markdown code blocks\n- Output ONLY the raw JSON object, starting with { and ending with }\n- Ensure the JSON is valid and parseable";
+export declare const STRUCTURED_OUTPUT_INSTRUCTIONS = "\nOutput ONLY valid JSON. No markdown, text, or decorations\u2014ever.\n\nFORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.\n\nREQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.\n\nIF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.\n\nWRONG: ```json\n{\"field\": \"value\"}\n```\nWRONG: Based on the data, here's the result: {\"field\": \"value\"}\nCORRECT: {\"field\": \"value\"}\n\nYour entire response = raw JSON object. Nothing else.";
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)

package/dist/config/conversationMemory.js

@@ -26,20 +26,43 @@ IMPORTANT: You are continuing an ongoing conversation. The previous messages in
 - Any decisions, agreements, or conclusions reached
 
 Always reference and build upon this conversation history when relevant. If the user asks about information mentioned earlier in the conversation, refer to those previous messages to provide accurate, contextual responses.`;
+/**
+ * Percentage of model context window to use for conversation memory threshold
+ * Default: 80% of model's context window
+ */
+export const MEMORY_THRESHOLD_PERCENTAGE = 0.8;
+/**
+ * Fallback token threshold if model context unknown
+ */
+export const DEFAULT_FALLBACK_THRESHOLD = 50000;
+/**
+ * Ratio of threshold to keep as recent unsummarized messages
+ * When summarization triggers, this percentage of tokens from the end
+ * are preserved as detailed messages, while older content gets summarized.
+ */
+export const RECENT_MESSAGES_RATIO = 0.3;
 /**
  * Structured output instructions for JSON/structured output mode
  * Used to ensure AI providers output only valid JSON without conversational filler
  * This addresses the issue where models add text like "Excellent!" before JSON output
+ * and the case where tools are used but final output must still be pure JSON
  */
 export const STRUCTURED_OUTPUT_INSTRUCTIONS = `
+Output ONLY valid JSON. No markdown, text, or decorations—ever.
+
+FORBIDDEN: markdown code blocks, text before/after JSON, explanations, preambles, summaries, conversational text about tools.
 
-STRUCTURED OUTPUT REQUIREMENT:
-You MUST respond with ONLY a valid JSON object that matches the provided schema.
-- Do NOT include any text before the JSON (no greetings, acknowledgments, or preamble like "Excellent!", "Sure!", "Here is the result:", etc.)
-- Do NOT include any text after the JSON (no explanations, summaries, or follow-up comments)
-- Do NOT wrap the JSON in markdown code blocks
-- Output ONLY the raw JSON object, starting with { and ending with }
-- Ensure the JSON is valid and parseable`;
+REQUIRED: response starts with { and ends with }, valid JSON only, no additional characters.
+
+IF YOU CALLED TOOLS: Incorporate data directly into the JSON structure. Do NOT explain what you did.
+
+WRONG: \`\`\`json
+{"field": "value"}
+\`\`\`
+WRONG: Based on the data, here's the result: {"field": "value"}
+CORRECT: {"field": "value"}
+
+Your entire response = raw JSON object. Nothing else.`;
 /**
  * Get default configuration values for conversation memory
  * Reads environment variables when called (not at module load time)
@@ -48,12 +71,16 @@ export function getConversationMemoryDefaults() {
     return {
         enabled: process.env.NEUROLINK_MEMORY_ENABLED === "true",
         maxSessions: Number(process.env.NEUROLINK_MEMORY_MAX_SESSIONS) || DEFAULT_MAX_SESSIONS,
+        enableSummarization: process.env.NEUROLINK_SUMMARIZATION_ENABLED !== "false",
+        tokenThreshold: process.env.NEUROLINK_TOKEN_THRESHOLD
+            ? Number(process.env.NEUROLINK_TOKEN_THRESHOLD)
+            : undefined,
+        summarizationProvider: process.env.NEUROLINK_SUMMARIZATION_PROVIDER || "vertex",
+        summarizationModel: process.env.NEUROLINK_SUMMARIZATION_MODEL || "gemini-2.5-flash",
+        // Deprecated (for backward compatibility)
         maxTurnsPerSession: Number(process.env.NEUROLINK_MEMORY_MAX_TURNS_PER_SESSION) ||
             DEFAULT_MAX_TURNS_PER_SESSION,
-        enableSummarization: process.env.NEUROLINK_SUMMARIZATION_ENABLED === "true",
         summarizationThresholdTurns: Number(process.env.NEUROLINK_SUMMARIZATION_THRESHOLD_TURNS) || 20,
         summarizationTargetTurns: Number(process.env.NEUROLINK_SUMMARIZATION_TARGET_TURNS) || 10,
-        summarizationProvider: process.env.NEUROLINK_SUMMARIZATION_PROVIDER || "vertex",
-        summarizationModel: process.env.NEUROLINK_SUMMARIZATION_MODEL || "gemini-2.5-flash",
     };
 }

package/dist/core/baseProvider.js

@@ -327,18 +327,21 @@ export class BaseProvider {
             // This is optimal for simple read-aloud scenarios
             if (options.tts?.enabled && !options.tts?.useAiResponse) {
                 const textToSynthesize = options.prompt ?? options.input?.text ?? "";
-                const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                // Build base result structure - common to both paths
                 const baseResult = {
                     content: textToSynthesize,
-                    audio: ttsResult,
                     provider: options.provider ?? this.providerName,
                     model: this.modelName,
-                    usage: {
-                        input: 0,
-                        output: 0,
-                        total: 0,
-                    },
+                    usage: { input: 0, output: 0, total: 0 },
                 };
+                try {
+                    const ttsResult = await TTSProcessor.synthesize(textToSynthesize, options.provider ?? this.providerName, options.tts);
+                    baseResult.audio = ttsResult;
+                }
+                catch (ttsError) {
+                    logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
+                    // baseResult remains without audio - graceful degradation
+                }
                 // Call enhanceResult for consistency - enables analytics/evaluation for TTS-only requests
                 return await this.enhanceResult(baseResult, options, startTime);
             }
@@ -359,12 +362,19 @@ export class BaseProvider {
                 const provider = options.provider ?? this.providerName;
                 // Validate AI response and provider before synthesis
                 if (aiResponse && provider) {
-                    const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
-                    // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
-                    enhancedResult = {
-                        ...enhancedResult,
-                        audio: ttsResult,
-                    };
+                    try {
+                        const ttsResult = await TTSProcessor.synthesize(aiResponse, provider, options.tts);
+                        // Add audio to enhanced result (TTSProcessor already includes latency in metadata)
+                        enhancedResult = {
+                            ...enhancedResult,
+                            audio: ttsResult,
+                        };
+                    }
+                    catch (ttsError) {
+                        // Log TTS error but continue with text-only result
+                        logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
+                        // enhancedResult remains unchanged (no audio field added)
+                    }
                 }
                 else {
                     logger.warn(`TTS synthesis skipped despite being enabled`, {

package/dist/core/conversationMemoryFactory.js

@@ -14,10 +14,7 @@ export function createConversationMemoryManager(config, storageType = "memory",
         config: {
             enabled: config.enabled,
             maxSessions: config.maxSessions,
-            maxTurnsPerSession: config.maxTurnsPerSession,
             enableSummarization: config.enableSummarization,
-            summarizationThresholdTurns: config.summarizationThresholdTurns,
-            summarizationTargetTurns: config.summarizationTargetTurns,
             summarizationProvider: config.summarizationProvider,
             summarizationModel: config.summarizationModel,
         },

package/dist/core/conversationMemoryInitializer.js

@@ -62,15 +62,7 @@ export async function initializeConversationMemory(config) {
                     "RedisConversationMemoryManager",
                 hasConfig: !!redisMemoryManager?.config,
             });
-            logger.info("[conversationMemoryInitializer] Redis conversation memory manager created successfully", {
-                configSource,
-                host: redisConfig.host || "localhost",
-                port: redisConfig.port || 6379,
-                keyPrefix: redisConfig.keyPrefix || "neurolink:conversation:",
-                maxSessions: memoryConfig.maxSessions,
-                maxTurnsPerSession: memoryConfig.maxTurnsPerSession,
-                managerType: redisMemoryManager?.constructor?.name,
-            });
+            logger.info("[conversationMemoryInitializer] Redis conversation memory manager created successfully");
             // Perform basic validation
             if (redisMemoryManager?.constructor?.name !==
                 "RedisConversationMemoryManager") {

package/dist/core/conversationMemoryManager.d.ts

@@ -2,11 +2,15 @@
  * Conversation Memory Manager for NeuroLink
  * Handles in-memory conversation storage, session management, and context injection
  */
-import type { ConversationMemoryConfig, SessionMemory, ConversationMemoryStats, ChatMessage } from "../types/conversation.js";
+import type { ConversationMemoryConfig, SessionMemory, ConversationMemoryStats, ChatMessage, StoreConversationTurnOptions } from "../types/conversation.js";
 export declare class ConversationMemoryManager {
     private sessions;
     config: ConversationMemoryConfig;
     private isInitialized;
+    /**
+     * Track sessions currently being summarized to prevent race conditions
+     */
+    private summarizationInProgress;
     constructor(config: ConversationMemoryConfig);
     /**
      * Initialize the memory manager
@@ -14,19 +18,38 @@ export declare class ConversationMemoryManager {
     initialize(): Promise<void>;
     /**
      * Store a conversation turn for a session
-     * ULTRA-OPTIMIZED: Direct ChatMessage[] storage with zero conversion overhead
+     * TOKEN-BASED: Validates message size and triggers summarization based on tokens
+     */
+    storeConversationTurn(options: StoreConversationTurnOptions): Promise<void>;
+    /**
+     * Validate and prepare a message before adding to session
+     * Truncates if message exceeds token limit
+     */
+    private validateAndPrepareMessage;
+    /**
+     * Check if summarization is needed based on token count
      */
-    storeConversationTurn(sessionId: string, userId: string | undefined, userMessage: string, aiResponse: string, _startTimeStamp: Date | undefined): Promise<void>;
+    private checkAndSummarize;
     /**
-     * Build context messages for AI prompt injection (ULTRA-OPTIMIZED)
-     * Returns pre-stored message array with zero conversion overhead
+     * Estimate total tokens for a list of messages
+     */
+    private estimateTokens;
+    /**
+     * Build context messages for AI prompt injection (TOKEN-BASED)
+     * Returns messages from pointer onwards (or all if no pointer)
      * Now consistently async to match Redis implementation
      */
     buildContextMessages(sessionId: string): Promise<ChatMessage[]>;
     getSession(sessionId: string): SessionMemory | undefined;
-    createSummarySystemMessage(content: string): ChatMessage;
-    private _summarizeSession;
-    private _createSummarizationPrompt;
+    createSummarySystemMessage(content: string, summarizesFrom?: string, summarizesTo?: string): ChatMessage;
+    /**
+     * Token-based summarization (pointer-based, non-destructive)
+     */
+    private summarizeSessionTokenBased;
+    /**
+     * Find split index to keep recent messages within target token count
+     */
+    private findSplitIndexByTokens;
     private ensureInitialized;
     private createNewSession;
     private enforceSessionLimit;