@juspay/neurolink 7.11.1 → 7.13.0

package/dist/lib/context/ContextManager.js

@@ -0,0 +1,102 @@
+import { logger } from "../utils/logger.js";
+import { formatHistoryToString } from "./utils.js";
+/**
+ * Manages conversation context, automatically summarizing it when it
+ * exceeds a specified word count limit.
+ */
+export class ContextManager {
+    static SUMMARIZATION_FAILED_WARNING = "[System Warning: Context summarization failed. Conversation history has been truncated.]";
+    static SUMMARIZATION_EMPTY_WARNING = "[System Warning: Context summarization failed to return valid content. Conversation history has been truncated.]";
+    history;
+    wordCount;
+    internalGenerator;
+    config;
+    constructor(generatorFunction, config, initialContext = "This is the start of the conversation.") {
+        this.internalGenerator = generatorFunction;
+        this.config = config;
+        const initialMessage = { role: "system", content: initialContext };
+        initialMessage.wordCount = this.config.estimateWordCount([initialMessage]);
+        this.history = [initialMessage];
+        this.wordCount = initialMessage.wordCount;
+    }
+    async addTurn(role, message) {
+        const newMessage = { role, content: message };
+        newMessage.wordCount = this.config.estimateWordCount([newMessage]);
+        this.history.push(newMessage);
+        this.wordCount += newMessage.wordCount;
+        logger.info(`[ContextManager] Current word count: ${this.wordCount} / ${this.config.highWaterMarkWords}`);
+        if (this.wordCount > this.config.highWaterMarkWords) {
+            await this._summarize();
+        }
+    }
+    /**
+     * Formats the history including the latest user turn for the prompt, without modifying the permanent history.
+     */
+    getContextForPrompt(role, message) {
+        const tempHistory = [...this.history, { role, content: message }];
+        return formatHistoryToString(tempHistory);
+    }
+    getCurrentContext() {
+        // Format the history into a single string for the provider prompt
+        return formatHistoryToString(this.history);
+    }
+    async _summarize() {
+        try {
+            const prompt = this.config.getSummarizationPrompt(this.history, this.config.lowWaterMarkWords);
+            // Construct options for the internal method, bypassing the main 'generate' entry point
+            const textOptions = {
+                prompt,
+                provider: this.config.summarizationProvider,
+                model: this.config.summarizationModel,
+                // Ensure summarization does not trigger more context management or tools
+                disableTools: true,
+            };
+            // Call the internal generation function directly to avoid recursion
+            const result = await this.internalGenerator(textOptions);
+            if (typeof result.content === "string" && result.content.length > 0) {
+                // Replace the history with a single system message containing the summary
+                const newHistory = [{ role: "system", content: result.content }];
+                this.history = newHistory;
+                this.wordCount = this.config.estimateWordCount(this.history);
+                logger.info(`[ContextManager] Summarization complete. New history length: ${this.wordCount} words.`);
+            }
+            else {
+                logger.warn("[ContextManager] Summarization returned empty or non-string content; truncating history as a fallback.");
+                this._truncateHistory(this.config.lowWaterMarkWords);
+                this.history.unshift({ role: "system", content: ContextManager.SUMMARIZATION_EMPTY_WARNING });
+                this.wordCount = this.config.estimateWordCount(this.history);
+            }
+            logger.debug(`[ContextManager] New history: ${JSON.stringify(this.history)}`);
+        }
+        catch (error) {
+            logger.error("Context summarization failed:", { error });
+            // Fallback strategy: truncate the history to the target word count.
+            this._truncateHistory(this.config.lowWaterMarkWords);
+            this.history.unshift({ role: "system", content: ContextManager.SUMMARIZATION_FAILED_WARNING });
+            this.wordCount = this.config.estimateWordCount(this.history);
+        }
+    }
+    /**
+     * Truncates the history to a specific word count, preserving the most recent messages.
+     */
+    _truncateHistory(wordLimit) {
+        if (this.wordCount <= wordLimit) {
+            return;
+        }
+        let runningCount = 0;
+        let sliceIndex = this.history.length;
+        for (let i = this.history.length - 1; i >= 0; i--) {
+            let wordCount = this.history[i].wordCount;
+            if (wordCount === undefined) {
+                logger.warn(`[ContextManager] Word count cache missing for message at index ${i}. Recalculating.`);
+                wordCount = this.config.estimateWordCount([this.history[i]]);
+            }
+            runningCount += wordCount;
+            if (runningCount > wordLimit) {
+                sliceIndex = i + 1;
+                break;
+            }
+        }
+        this.history = this.history.slice(sliceIndex);
+    }
+}

package/dist/lib/context/config.d.ts

@@ -0,0 +1,5 @@
+import type { ContextManagerConfig } from "./types.js";
+/**
+ * Default configuration for the ContextManager.
+ */
+export declare const defaultContextConfig: ContextManagerConfig;

package/dist/lib/context/config.js

@@ -0,0 +1,38 @@
+import { formatHistoryToString } from "./utils.js";
+/**
+ * Estimates the word count of a conversation history.
+ */
+function estimateWordCount(history) {
+    if (!history || history.length === 0) {
+        return 0;
+    }
+    return history.reduce((acc, msg) => acc + (msg.content.trim().split(/\s+/).filter(word => word.length > 0).length || 0), 0);
+}
+/**
+ * Generates the default prompt for summarization.
+ */
+function getDefaultSummarizationPrompt(history, wordLimit) {
+    const formattedHistory = formatHistoryToString(history);
+    return `
+You are a context summarization AI. Your task is to condense the following conversation history for another AI assistant.
+The summary must be a concise, third-person narrative that retains all critical information. Pay special attention to retaining 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.
+Please keep the summary under ${wordLimit} words.
+
+Conversation History to Summarize:
+---
+${formattedHistory}
+---
+`.trim();
+}
+/**
+ * Default configuration for the ContextManager.
+ */
+export const defaultContextConfig = {
+    highWaterMarkWords: 3000,
+    lowWaterMarkWords: 800,
+    summarizationModel: "gemini-2.5-flash",
+    summarizationProvider: "googlevertex",
+    getSummarizationPrompt: getDefaultSummarizationPrompt,
+    estimateWordCount: estimateWordCount,
+};

package/dist/lib/context/types.d.ts

@@ -0,0 +1,20 @@
+export interface ChatMessage {
+    /** Role of the message sender */
+    role: "user" | "assistant" | "system";
+    /** Content of the message */
+    content: string;
+    /** Cached word count for performance */
+    wordCount?: number;
+}
+/**
+ * Defines the configuration for the ContextManager.
+ * This allows for easy customization of the summarization behavior.
+ */
+export interface ContextManagerConfig {
+    highWaterMarkWords: number;
+    lowWaterMarkWords: number;
+    summarizationModel: string;
+    summarizationProvider: string;
+    getSummarizationPrompt: (history: ChatMessage[], wordLimit: number) => string;
+    estimateWordCount: (history: ChatMessage[]) => number;
+}

package/dist/lib/context/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/context/utils.d.ts

@@ -0,0 +1,7 @@
+import type { ChatMessage } from "./types.js";
+/**
+ * Formats a chat history array into a single string for use in a prompt.
+ * @param history The array of ChatMessage objects.
+ * @returns A formatted string representing the conversation.
+ */
+export declare function formatHistoryToString(history: ChatMessage[]): string;

package/dist/lib/context/utils.js

@@ -0,0 +1,8 @@
+/**
+ * Formats a chat history array into a single string for use in a prompt.
+ * @param history The array of ChatMessage objects.
+ * @returns A formatted string representing the conversation.
+ */
+export function formatHistoryToString(history) {
+    return history.map(msg => `${msg.role}: ${msg.content}`).join('\n\n');
+}

package/dist/lib/core/baseProvider.js

@@ -4,6 +4,7 @@ import { directAgentTools } from "../agent/directTools.js";
 import { getSafeMaxTokens } from "../utils/tokenLimits.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 /**
  * Validates if a result contains a valid toolsObject structure
  * @param result - The result object to validate
@@ -162,10 +163,11 @@ export class BaseProvider {
             logger.debug(`[BaseProvider.generate] Tools for ${this.providerName}: ${Object.keys(tools).join(", ")}`);
             // EVERY provider uses Vercel AI SDK - no exceptions
             const model = await this.getAISDKModel(); // This method is now REQUIRED
+            // Build proper message array with conversation history
+            const messages = buildMessagesArray(options);
             const result = await generateText({
                 model,
-                prompt: options.prompt || options.input?.text || "",
-                system: options.systemPrompt,
+                messages: messages,
                 tools,
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools ? "auto" : "none",

package/dist/lib/core/conversationMemoryManager.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Conversation Memory Manager for NeuroLink
+ * Handles in-memory conversation storage, session management, and context injection
+ */
+import type { ConversationMemoryConfig, ConversationMemoryStats, ChatMessage } from "../types/conversationTypes.js";
+export declare class ConversationMemoryManager {
+    private sessions;
+    private config;
+    private isInitialized;
+    constructor(config: ConversationMemoryConfig);
+    /**
+     * Initialize the memory manager
+     */
+    initialize(): Promise<void>;
+    /**
+     * Store a conversation turn for a session
+     * ULTRA-OPTIMIZED: Direct ChatMessage[] storage with zero conversion overhead
+     */
+    storeConversationTurn(sessionId: string, userId: string | undefined, userMessage: string, aiResponse: string): Promise<void>;
+    /**
+     * Build context messages for AI prompt injection (ULTRA-OPTIMIZED)
+     * Returns pre-stored message array with zero conversion overhead
+     */
+    buildContextMessages(sessionId: string): ChatMessage[];
+    /**
+     * Get memory statistics (simplified for pure in-memory storage)
+     * ULTRA-OPTIMIZED: Calculate turns from message count (each turn = MESSAGES_PER_TURN messages)
+     */
+    getStats(): Promise<ConversationMemoryStats>;
+    /**
+     * Clear all conversations for a specific session
+     */
+    clearSession(sessionId: string): Promise<boolean>;
+    /**
+     * Clear all conversations (reset memory)
+     */
+    clearAllSessions(): Promise<void>;
+    private ensureInitialized;
+    private createNewSession;
+    private enforceSessionLimit;
+}

package/dist/lib/core/conversationMemoryManager.js

@@ -0,0 +1,152 @@
+/**
+ * Conversation Memory Manager for NeuroLink
+ * Handles in-memory conversation storage, session management, and context injection
+ */
+import { ConversationMemoryError } from "../types/conversationTypes.js";
+import { DEFAULT_MAX_TURNS_PER_SESSION, DEFAULT_MAX_SESSIONS, MESSAGES_PER_TURN } from "../config/conversationMemoryConfig.js";
+import { logger } from "../utils/logger.js";
+export class ConversationMemoryManager {
+    sessions = new Map();
+    config;
+    isInitialized = false;
+    constructor(config) {
+        // Trust that config is already complete from applyConversationMemoryDefaults()
+        this.config = config;
+    }
+    /**
+     * Initialize the memory manager
+     */
+    async initialize() {
+        if (this.isInitialized) {
+            return;
+        }
+        try {
+            this.isInitialized = true;
+            logger.info("ConversationMemoryManager initialized", {
+                storage: "in-memory",
+                maxSessions: this.config.maxSessions,
+                maxTurnsPerSession: this.config.maxTurnsPerSession,
+            });
+        }
+        catch (error) {
+            throw new ConversationMemoryError("Failed to initialize conversation memory", "CONFIG_ERROR", { error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    /**
+     * Store a conversation turn for a session
+     * ULTRA-OPTIMIZED: Direct ChatMessage[] storage with zero conversion overhead
+     */
+    async storeConversationTurn(sessionId, userId, userMessage, aiResponse) {
+        await this.ensureInitialized();
+        try {
+            // Get or create session
+            let session = this.sessions.get(sessionId);
+            if (!session) {
+                session = this.createNewSession(sessionId, userId);
+                this.sessions.set(sessionId, session);
+            }
+            // ULTRA-OPTIMIZED: Direct message storage - no intermediate objects
+            session.messages.push({ role: "user", content: userMessage }, { role: "assistant", content: aiResponse });
+            session.lastActivity = Date.now();
+            // Enforce per-session turn limit (each turn = MESSAGES_PER_TURN messages: user + assistant)
+            const maxMessages = (this.config.maxTurnsPerSession || DEFAULT_MAX_TURNS_PER_SESSION) * MESSAGES_PER_TURN;
+            if (session.messages.length > maxMessages) {
+                session.messages = session.messages.slice(-maxMessages);
+            }
+            // Enforce global session limit
+            this.enforceSessionLimit();
+            logger.debug("Conversation turn stored", {
+                sessionId,
+                messageCount: session.messages.length,
+                turnCount: session.messages.length / MESSAGES_PER_TURN, // Each turn = MESSAGES_PER_TURN messages
+                userMessageLength: userMessage.length,
+                aiResponseLength: aiResponse.length,
+            });
+        }
+        catch (error) {
+            throw new ConversationMemoryError(`Failed to store conversation turn for session ${sessionId}`, "STORAGE_ERROR", {
+                sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Build context messages for AI prompt injection (ULTRA-OPTIMIZED)
+     * Returns pre-stored message array with zero conversion overhead
+     */
+    buildContextMessages(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session || session.messages.length === 0) {
+            return [];
+        }
+        // ULTRA-OPTIMIZED: Direct return - no processing needed!
+        return session.messages;
+    }
+    /**
+     * Get memory statistics (simplified for pure in-memory storage)
+     * ULTRA-OPTIMIZED: Calculate turns from message count (each turn = MESSAGES_PER_TURN messages)
+     */
+    async getStats() {
+        await this.ensureInitialized();
+        const sessions = Array.from(this.sessions.values());
+        const totalTurns = sessions.reduce((sum, session) => sum + session.messages.length / MESSAGES_PER_TURN, 0);
+        return {
+            totalSessions: sessions.length,
+            totalTurns,
+        };
+    }
+    /**
+     * Clear all conversations for a specific session
+     */
+    async clearSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (!session) {
+            return false;
+        }
+        // Remove from memory
+        this.sessions.delete(sessionId);
+        logger.info("Session cleared", { sessionId });
+        return true;
+    }
+    /**
+     * Clear all conversations (reset memory)
+     */
+    async clearAllSessions() {
+        const sessionIds = Array.from(this.sessions.keys());
+        // Clear memory
+        this.sessions.clear();
+        logger.info("All sessions cleared", { clearedCount: sessionIds.length });
+    }
+    // Private methods
+    async ensureInitialized() {
+        if (!this.isInitialized) {
+            await this.initialize();
+        }
+    }
+    createNewSession(sessionId, userId) {
+        return {
+            sessionId,
+            userId,
+            messages: [],
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+        };
+    }
+    enforceSessionLimit() {
+        const maxSessions = this.config.maxSessions || DEFAULT_MAX_SESSIONS;
+        if (this.sessions.size <= maxSessions) {
+            return;
+        }
+        // Sort sessions by last activity (oldest first)
+        const sessions = Array.from(this.sessions.entries()).sort(([, a], [, b]) => a.lastActivity - b.lastActivity);
+        // Remove oldest sessions
+        const sessionsToRemove = sessions.slice(0, sessions.length - maxSessions);
+        for (const [sessionId] of sessionsToRemove) {
+            this.sessions.delete(sessionId);
+        }
+        logger.debug("Session limit enforced", {
+            removedSessions: sessionsToRemove.length,
+            remainingSessions: this.sessions.size,
+        });
+    }
+}

package/dist/lib/core/types.d.ts

@@ -3,6 +3,7 @@ import type { Schema, Tool } from "ai";
 import type { GenerateResult } from "../types/generateTypes.js";
 import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
 import type { JsonValue } from "../types/common.js";
+import type { ChatMessage } from "../types/conversationTypes.js";
 export interface TextGenerationResult {
     content: string;
     provider?: string;
@@ -150,6 +151,7 @@ export interface TextGenerationOptions {
         role: string;
         content: string;
     }>;
+    conversationMessages?: ChatMessage[];
 }
 /**
  * Analytics data for usage tracking

package/dist/lib/neurolink.d.ts

@@ -11,6 +11,7 @@ import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { SimpleTool } from "./sdk/toolRegistration.js";
 import type { InMemoryMCPServerConfig } from "./types/mcpTypes.js";
 import { EventEmitter } from "events";
+import type { ConversationMemoryConfig } from "./types/conversationTypes.js";
 export interface ProviderStatus {
     provider: string;
     status: "working" | "failed" | "not-configured";
@@ -40,9 +41,11 @@ export interface MCPServerInfo {
     hasServer: boolean;
     metadata?: unknown;
 }
+import type { ContextManagerConfig } from "./context/types.js";
 export declare class NeuroLink {
     private mcpInitialized;
     private emitter;
+    private contextManager;
     private customTools;
     private inMemoryServers;
     private toolCircuitBreakers;
@@ -55,7 +58,10 @@ export declare class NeuroLink {
      * @param success - Whether the tool execution was successful
      */
     private emitToolEndEvent;
-    constructor();
+    private conversationMemory?;
+    constructor(config?: {
+        conversationMemory?: Partial<ConversationMemoryConfig>;
+    });
     /**
      * Initialize MCP registry with enhanced error handling and resource cleanup
      * Uses isolated async context to prevent hanging
@@ -65,6 +71,21 @@ export declare class NeuroLink {
      * MAIN ENTRY POINT: Enhanced generate method with new function signature
      * Replaces both generateText and legacy methods
      */
+    /**
+     * Extracts the original prompt text from the provided input.
+     * If a string is provided, it returns the string directly.
+     * If a GenerateOptions object is provided, it returns the input text from the object.
+     * @param optionsOrPrompt The prompt input, either as a string or a GenerateOptions object.
+     * @returns The original prompt text as a string.
+     */
+    private _extractOriginalPrompt;
+    /**
+     * Enables automatic context summarization for the NeuroLink instance.
+     * Once enabled, the instance will maintain conversation history and
+     * automatically summarize it when it exceeds token limits.
+     * @param config Optional configuration to override default summarization settings.
+     */
+    enableContextSummarization(config?: Partial<ContextManagerConfig>): void;
     generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method
@@ -75,9 +96,11 @@ export declare class NeuroLink {
      * REDESIGNED INTERNAL GENERATION - NO CIRCULAR DEPENDENCIES
      *
      * This method implements a clean fallback chain:
-     * 1. Try MCP-enhanced generation if available
-     * 2. Fall back to direct provider generation
-     * 3. No recursive calls - each method has a specific purpose
+     * 1. Initialize conversation memory if enabled
+     * 2. Inject conversation history into prompt
+     * 3. Try MCP-enhanced generation if available
+     * 4. Fall back to direct provider generation
+     * 5. Store conversation turn for future context
      */
     private generateTextInternal;
     /**
@@ -367,6 +390,18 @@ export declare class NeuroLink {
             recommendations: string[];
         }>;
     };
+    /**
+     * Get conversation memory statistics (public API)
+     */
+    getConversationStats(): Promise<import("./types/conversationTypes.js").ConversationMemoryStats>;
+    /**
+     * Clear conversation history for a specific session (public API)
+     */
+    clearConversationSession(sessionId: string): Promise<boolean>;
+    /**
+     * Clear all conversation history (public API)
+     */
+    clearAllConversations(): Promise<void>;
 }
 export declare const neurolink: NeuroLink;
 export default neurolink;