@juspay/neurolink 8.19.0 → 8.20.0

package/dist/types/conversation.d.ts

@@ -11,14 +11,10 @@ export type ConversationMemoryConfig = {
     enabled: boolean;
     /** Maximum number of sessions to keep in memory (default: 50) */
     maxSessions?: number;
-    /** Maximum number of conversation turns to keep per session (default: 20) */
-    maxTurnsPerSession?: number;
     /** Enable automatic summarization */
     enableSummarization?: boolean;
-    /** Turn count to trigger summarization */
-    summarizationThresholdTurns?: number;
-    /** Target turn count for the summary */
-    summarizationTargetTurns?: number;
+    /** Token threshold to trigger summarization (optional - defaults to 80% of model context) */
+    tokenThreshold?: number;
     /** Provider to use for summarization */
     summarizationProvider?: string;
     /** Model to use for summarization */
@@ -29,6 +25,12 @@ export type ConversationMemoryConfig = {
     mem0Config?: Mem0Config;
     /** Redis configuration (optional) - overrides environment variables */
     redisConfig?: RedisStorageConfig;
+    /** @deprecated Use tokenThreshold instead - Maximum number of conversation turns to keep per session (default: 20) */
+    maxTurnsPerSession?: number;
+    /** @deprecated Use tokenThreshold instead - Turn count to trigger summarization */
+    summarizationThresholdTurns?: number;
+    /** @deprecated Use tokenThreshold instead - Target turn count for the summary */
+    summarizationTargetTurns?: number;
 };
 /**
  * Complete memory for a conversation session
@@ -47,6 +49,16 @@ export type SessionMemory = {
     createdAt: number;
     /** When this session was last active */
     lastActivity: number;
+    /** Pointer to last summarized message ID (NEW - for token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override (NEW - for token-based memory) */
+    tokenThreshold?: number;
+    /** Cached token count for performance (NEW - for token-based memory) */
+    lastTokenCount?: number;
+    /** When token count was last calculated (NEW - for token-based memory) */
+    lastCountedAt?: number;
     /** Optional session metadata */
     metadata?: {
         /** User role or permissions */
@@ -70,13 +82,13 @@ export type ConversationMemoryStats = {
  * Chat message format for conversation history
  */
 export type ChatMessage = {
+    /** Unique message identifier (required for token-based memory) */
+    id: string;
     /** Role/type of the message */
     role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
     /** Content of the message */
     content: string;
-    /** Message ID (optional) - for new format */
-    id?: string;
-    /** Timestamp (optional) - for new format */
+    /** Timestamp (ISO string) */
     timestamp?: string;
     /** Tool name (optional) - for tool_call/tool_result messages */
     tool?: string;
@@ -90,6 +102,17 @@ export type ChatMessage = {
         type?: string;
         error?: string;
     };
+    /** Message metadata (NEW - for token-based memory) */
+    metadata?: {
+        /** Is this a summary message? */
+        isSummary?: boolean;
+        /** First message ID that this summary covers */
+        summarizesFrom?: string;
+        /** Last message ID that this summary covers */
+        summarizesTo?: string;
+        /** Was this message truncated due to token limits? */
+        truncated?: boolean;
+    };
 };
 /**
  * Multimodal message types - Re-exported from multimodal.ts
@@ -152,6 +175,18 @@ export type SessionIdentifier = {
     sessionId: string;
     userId?: string;
 };
+/**
+ * Options for storing a conversation turn
+ */
+export type StoreConversationTurnOptions = {
+    sessionId: string;
+    userId?: string;
+    userMessage: string;
+    aiResponse: string;
+    startTimeStamp?: Date;
+    providerDetails?: ProviderDetails;
+    enableSummarization?: boolean;
+};
 /**
  * Lightweight session metadata for efficient session listing
  * Contains only essential information without heavy message arrays
@@ -179,6 +214,16 @@ export type ConversationBase = {
     createdAt: string;
     /** When this conversation was last updated */
     updatedAt: string;
+    /** Pointer to last summarized message (token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override */
+    tokenThreshold?: number;
+    /** Cached token count for efficiency */
+    lastTokenCount?: number;
+    /** Timestamp of last token count */
+    lastCountedAt?: number;
 };
 /**
  * Redis conversation storage object format
@@ -250,3 +295,7 @@ export type RedisStorageConfig = {
         [key: string]: string | number | boolean | undefined;
     };
 };
+export type ProviderDetails = {
+    provider: string;
+    model: string;
+};

package/dist/types/generateTypes.d.ts

@@ -350,6 +350,7 @@ export type TextGenerationOptions = {
         formatStyle?: "raw" | "markdown" | "json";
         includeHeaders?: boolean;
     };
+    enableSummarization?: boolean;
 };
 /**
  * Text generation result (consolidated from core types)

package/dist/types/sdkTypes.d.ts

@@ -22,4 +22,4 @@ export type { Unknown, UnknownRecord, UnknownArray, JsonValue, JsonObject, JsonA
 export type { EvaluationData, EvaluationContext, EnhancedEvaluationResult, EvaluationRequest, EvaluationCriteria, } from "./evaluation.js";
 export type { TaskType, TaskClassification, ClassificationScores, ClassificationStats, ClassificationValidation, } from "./taskClassificationTypes.js";
 export type { DomainType, DomainConfig, DomainTemplate, DomainConfigOptions, DomainEvaluationCriteria, DomainValidationRule, } from "./domainTypes.js";
-export type { ConversationMemoryConfig, SessionMemory, ConversationMemoryStats, ChatMessage, MessageContent, MultimodalChatMessage, ConversationMemoryEvents, ConversationMemoryError, SessionIdentifier, SessionMetadata, RedisConversationObject, RedisStorageConfig, } from "./conversation.js";
+export type { ConversationMemoryConfig, SessionMemory, ChatMessage, MessageContent, MultimodalChatMessage, ConversationMemoryEvents, ConversationMemoryError, SessionIdentifier, SessionMetadata, RedisConversationObject, RedisStorageConfig, } from "./conversation.js";

package/dist/types/streamTypes.d.ts

@@ -299,6 +299,7 @@ export type StreamOptions = {
     };
     conversationMessages?: ChatMessage[];
     middleware?: MiddlewareFactoryOptions;
+    enableSummarization?: boolean;
 };
 /**
  * Stream function result type - Primary output format for streaming

package/dist/utils/conversationMemory.d.ts

@@ -2,7 +2,7 @@
  * Conversation Memory Utilities
  * Handles configuration merging and conversation memory operations
  */
-import type { ConversationMemoryConfig, ChatMessage } from "../types/conversation.js";
+import type { ConversationMemoryConfig, ChatMessage, SessionMemory } from "../types/conversation.js";
 import type { ConversationMemoryManager } from "../core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "../core/redisConversationMemoryManager.js";
 import type { TextGenerationOptions, TextGenerationResult } from "../types/generateTypes.js";
@@ -20,3 +20,45 @@ export declare function getConversationMessages(conversationMemory: Conversation
  * Saves user messages and AI responses for conversation memory
  */
 export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined): Promise<void>;
+/**
+ * Build context messages from pointer onwards (token-based memory)
+ * Returns summary message (if exists) + all messages after the summarized pointer
+ * @param session - Session memory with pointer
+ * @returns Context messages to send to LLM
+ */
+export declare function buildContextFromPointer(session: SessionMemory): ChatMessage[];
+/**
+ * Create summarization prompt from message history
+ * Used by both in-memory and Redis conversation managers
+ * @param history - Messages to summarize
+ * @param previousSummary - Optional previous summary to build upon
+ */
+export declare function createSummarizationPrompt(history: ChatMessage[], previousSummary?: string): string;
+/**
+ * Calculate token threshold based on model's output token limit
+ * Uses existing provider token limits as proxy for context window
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @returns Token threshold (80% of model's token limit)
+ */
+export declare function calculateTokenThreshold(provider: string, model: string): number;
+/**
+ * Get effective token threshold for a session
+ * Priority: session override > env var > model-based (80%) > fallback
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @param envOverride - Environment variable override
+ * @param sessionOverride - Per-session token threshold override
+ * @returns Effective token threshold
+ */
+export declare function getEffectiveTokenThreshold(provider: string, model: string, envOverride?: number, sessionOverride?: number): number;
+/**
+ * Generate summary using configured provider and model
+ * Centralized summarization logic used by both ConversationMemoryManager and RedisConversationMemoryManager
+ * @param messages - Messages to summarize
+ * @param config - Conversation memory configuration containing provider/model settings
+ * @param previousSummary - Optional previous summary to build upon
+ * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @returns Summary text or null if generation fails
+ */
+export declare function generateSummary(messages: ChatMessage[], config: ConversationMemoryConfig, logPrefix?: string, previousSummary?: string): Promise<string | null>;

package/dist/utils/conversationMemory.js

@@ -2,8 +2,10 @@
  * Conversation Memory Utilities
  * Handles configuration merging and conversation memory operations
  */
-import { getConversationMemoryDefaults } from "../config/conversationMemory.js";
+import { getConversationMemoryDefaults, MEMORY_THRESHOLD_PERCENTAGE, DEFAULT_FALLBACK_THRESHOLD, } from "../config/conversationMemory.js";
+import { TokenUtils } from "../constants/tokens.js";
 import { logger } from "./logger.js";
+import { NeuroLink } from "../neurolink.js";
 /**
  * Apply conversation memory defaults to user configuration
  * Merges user config with environment variables and default values
@@ -34,8 +36,8 @@ export async function getConversationMessages(conversationMemory, options) {
     try {
         // Extract userId from context
         const userId = options.context?.userId;
-        // Remove duplicate summarization logic - it should be handled in ConversationMemoryManager
-        const messages = await conversationMemory.buildContextMessages(sessionId, userId);
+        const enableSummarization = options.enableSummarization ?? undefined;
+        const messages = await conversationMemory.buildContextMessages(sessionId, userId, enableSummarization);
         logger.debug("[conversationMemoryUtils] Conversation messages retrieved successfully", {
             sessionId,
             messageCount: messages.length,
@@ -100,9 +102,24 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         return;
     }
     const userMessage = originalOptions.originalPrompt || originalOptions.prompt || "";
-    const aiResponse = result.content;
+    const aiResponse = result.content ?? "";
+    let providerDetails = undefined;
+    if (result.provider && result.model) {
+        providerDetails = {
+            provider: result.provider,
+            model: result.model,
+        };
+    }
     try {
-        await conversationMemory.storeConversationTurn(sessionId, userId, userMessage, aiResponse, startTimeStamp);
+        await conversationMemory.storeConversationTurn({
+            sessionId,
+            userId,
+            userMessage,
+            aiResponse,
+            startTimeStamp,
+            providerDetails,
+            enableSummarization: originalOptions.enableSummarization,
+        });
         logger.debug("[conversationMemoryUtils] Conversation turn stored successfully", {
             sessionId,
             userId,
@@ -121,3 +138,162 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         });
     }
 }
+/**
+ * Build context messages from pointer onwards (token-based memory)
+ * Returns summary message (if exists) + all messages after the summarized pointer
+ * @param session - Session memory with pointer
+ * @returns Context messages to send to LLM
+ */
+export function buildContextFromPointer(session) {
+    if (!session.summarizedUpToMessageId || !session.summarizedMessage) {
+        return session.messages;
+    }
+    // find a better way to wirte this
+    const pointerIndex = session.messages.findIndex((msg) => msg.id === session.summarizedUpToMessageId);
+    if (pointerIndex === -1) {
+        logger.warn("Pointer message not found, returning all messages", {
+            sessionId: session.sessionId,
+            pointer: session.summarizedUpToMessageId,
+            totalMessages: session.messages.length,
+        });
+        return session.messages;
+    }
+    const messagesAfterPointer = session.messages.slice(pointerIndex + 1);
+    // Construct context: summary message + recent messages
+    const summaryMessage = {
+        id: `summary-${session.summarizedUpToMessageId}`,
+        role: "system",
+        content: `Previous conversation summary: ${session.summarizedMessage}`,
+        timestamp: new Date().toISOString(),
+        metadata: {
+            isSummary: true,
+            summarizesTo: session.summarizedUpToMessageId,
+        },
+    };
+    logger.debug("Building context with summary", {
+        sessionId: session.sessionId,
+        pointerIndex,
+        messagesAfterPointer: messagesAfterPointer.length,
+        totalMessages: session.messages.length,
+        summaryLength: session.summarizedMessage.length,
+    });
+    return [summaryMessage, ...messagesAfterPointer];
+}
+/**
+ * Create summarization prompt from message history
+ * Used by both in-memory and Redis conversation managers
+ * @param history - Messages to summarize
+ * @param previousSummary - Optional previous summary to build upon
+ */
+export function createSummarizationPrompt(history, previousSummary) {
+    const formattedHistory = history
+        .map((msg) => `${msg.role}: ${msg.content}`)
+        .join("\n\n");
+    const previousSummarySection = previousSummary
+        ? `Previous Summary:
+---
+${previousSummary}
+---
+
+`
+        : "";
+    return `
+You are a context summarization AI. Your task is to condense the following conversation history for another AI assistant.
+${previousSummary ? "Build upon the previous summary and incorporate the new conversation turns below." : ""}
+The summary must be a concise, third-person narrative that retains all critical information, including key entities, technical details, decisions made, and any specific dates or times mentioned.
+Ensure the summary flows logically and is ready to be used as context for the next turn in the conversation.
+
+${previousSummarySection}Conversation History to Summarize:
+---
+${formattedHistory}
+---
+`.trim();
+}
+/**
+ * Calculate token threshold based on model's output token limit
+ * Uses existing provider token limits as proxy for context window
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @returns Token threshold (80% of model's token limit)
+ */
+export function calculateTokenThreshold(provider, model) {
+    try {
+        // Get model's token limit from existing TokenUtils
+        const modelTokenLimit = TokenUtils.getProviderTokenLimit(provider, model);
+        // Return 80% of token limit for conversation memory
+        // This is conservative since output limits are typically smaller than input limits
+        return Math.floor(modelTokenLimit * MEMORY_THRESHOLD_PERCENTAGE);
+    }
+    catch (error) {
+        logger.warn("Failed to calculate model threshold, using fallback", {
+            provider,
+            model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return DEFAULT_FALLBACK_THRESHOLD;
+    }
+}
+/**
+ * Get effective token threshold for a session
+ * Priority: session override > env var > model-based (80%) > fallback
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @param envOverride - Environment variable override
+ * @param sessionOverride - Per-session token threshold override
+ * @returns Effective token threshold
+ */
+export function getEffectiveTokenThreshold(provider, model, envOverride, sessionOverride) {
+    // Priority 1: Session-level override
+    if (sessionOverride && sessionOverride > 0) {
+        return sessionOverride;
+    }
+    // Priority 2: Environment variable override
+    if (envOverride && envOverride > 0) {
+        return envOverride;
+    }
+    // Priority 3: Model-based calculation (80% of context window)
+    try {
+        return calculateTokenThreshold(provider, model);
+    }
+    catch (error) {
+        logger.warn("Failed to calculate effective threshold, using fallback", {
+            provider,
+            model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        // Priority 4: Fallback for unknown models
+        return DEFAULT_FALLBACK_THRESHOLD;
+    }
+}
+/**
+ * Generate summary using configured provider and model
+ * Centralized summarization logic used by both ConversationMemoryManager and RedisConversationMemoryManager
+ * @param messages - Messages to summarize
+ * @param config - Conversation memory configuration containing provider/model settings
+ * @param previousSummary - Optional previous summary to build upon
+ * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @returns Summary text or null if generation fails
+ */
+export async function generateSummary(messages, config, logPrefix = "[ConversationMemory]", previousSummary) {
+    const summarizationPrompt = createSummarizationPrompt(messages, previousSummary);
+    const summarizer = new NeuroLink({
+        conversationMemory: { enabled: false },
+    });
+    try {
+        if (!config.summarizationProvider || !config.summarizationModel) {
+            logger.error(`${logPrefix} Missing summarization provider`);
+            return null;
+        }
+        const summaryResult = await summarizer.generate({
+            input: { text: summarizationPrompt },
+            provider: config.summarizationProvider,
+            model: config.summarizationModel,
+            disableTools: true,
+        });
+        return summaryResult.content || null;
+    }
+    catch (error) {
+        logger.error(`${logPrefix} Error generating summary`, { error });
+        return null;
+    }
+}

package/dist/utils/conversationMemoryUtils.js

@@ -58,8 +58,23 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
     if (typeof sessionId !== "string" || !sessionId) {
         return;
     }
+    let providerDetails = undefined;
+    if (result.provider && result.model) {
+        providerDetails = {
+            provider: result.provider,
+            model: result.model,
+        };
+    }
     try {
-        await conversationMemory.storeConversationTurn(sessionId, userId, originalOptions.originalPrompt || originalOptions.prompt || "", result.content, startTimeStamp);
+        await conversationMemory.storeConversationTurn({
+            sessionId,
+            userId,
+            userMessage: originalOptions.originalPrompt || originalOptions.prompt || "",
+            aiResponse: result.content,
+            startTimeStamp,
+            providerDetails,
+            enableSummarization: originalOptions.enableSummarization,
+        });
         logger.debug("Conversation turn stored", {
             sessionId,
             userId,

package/dist/utils/fileDetector.d.ts

@@ -31,6 +31,31 @@ export declare class FileDetector {
      * @returns Processed file result with type and content
      */
     static detectAndProcess(input: FileInput, options?: FileDetectorOptions): Promise<FileProcessingResult>;
+    /**
+     * Try fallback parsing for a specific file type
+     * Used when file detection returns "unknown" but we want to try parsing anyway
+     */
+    private static tryFallbackParsing;
+    /**
+     * Check if content is valid text (UTF-8, mostly printable)
+     */
+    private static isValidText;
+    /**
+     * Guess the MIME type for text content based on content patterns
+     */
+    private static guessTextMimeType;
+    /**
+     * Strict YAML detection for guessTextMimeType
+     * Similar to ContentHeuristicStrategy but requires at least 2 indicators
+     * to avoid false positives from simple key: value patterns
+     */
+    private static looksLikeYAMLStrict;
+    /**
+     * Strict XML detection for guessTextMimeType
+     * Ensures content has proper XML declaration or valid tag structure with closing tags
+     * Prevents false positives from arbitrary content starting with <
+     */
+    private static looksLikeXMLStrict;
     /**
      * Detect file type using multi-strategy approach
      * Stops at first strategy with confidence >= threshold (default: 80%)