@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/core/conversationMemoryManager.js

@@ -0,0 +1,344 @@
+/**
+ * Conversation Memory Manager for NeuroLink
+ * Handles in-memory conversation storage, session management, and context injection
+ */
+import { randomUUID } from "crypto";
+import { DEFAULT_MAX_SESSIONS, MEMORY_THRESHOLD_PERCENTAGE, MESSAGES_PER_TURN, } from "../config/conversationMemory.js";
+import { TokenUtils } from "../constants/tokens.js";
+import { SummarizationEngine } from "../context/summarizationEngine.js";
+import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
+import { tracers, withSpan } from "../telemetry/index.js";
+import { ConversationMemoryError } from "../types/conversation.js";
+import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
+import { logger } from "../utils/logger.js";
+export class ConversationMemoryManager {
+    sessions = new Map();
+    config;
+    isInitialized = false;
+    summarizationEngine = new SummarizationEngine();
+    /**
+     * Track sessions currently being summarized to prevent race conditions
+     */
+    summarizationInProgress = new Set();
+    constructor(config) {
+        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),
+            });
+        }
+    }
+    /** Whether this memory manager can persist data (always true for in-memory within process) */
+    get canPersist() {
+        return true;
+    }
+    /** Whether Redis client is configured (always false for in-memory) */
+    get isRedisConfigured() {
+        return false;
+    }
+    /** Get health status for monitoring */
+    getHealthStatus() {
+        return {
+            initialized: this.isInitialized,
+            connected: false,
+        };
+    }
+    /**
+     * Store a conversation turn for a session
+     * TOKEN-BASED: Validates message size and triggers summarization based on tokens
+     */
+    async storeConversationTurn(options) {
+        return withSpan({
+            name: "neurolink.memory.storeTurn",
+            tracer: tracers.memory,
+            attributes: {
+                "memory.type": "in-memory",
+                "session.id": options.sessionId,
+                "memory.operation": "store_turn",
+            },
+        }, async (span) => {
+            await this.ensureInitialized();
+            try {
+                // Get or create session
+                let session = this.sessions.get(options.sessionId);
+                if (!session) {
+                    session = this.createNewSession(options.sessionId, options.userId);
+                    this.sessions.set(options.sessionId, session);
+                }
+                const tokenThreshold = options.providerDetails
+                    ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, session.tokenThreshold)
+                    : this.config.tokenThreshold || 50000;
+                const userMsg = await this.validateAndPrepareMessage(options.userMessage, "user", tokenThreshold);
+                const assistantMsg = await this.validateAndPrepareMessage(options.aiResponse, "assistant", tokenThreshold);
+                if (options.events && options.events.length > 0) {
+                    assistantMsg.events = options.events;
+                }
+                session.messages.push(userMsg, assistantMsg);
+                session.lastActivity = Date.now();
+                // Store API-reported token counts if available
+                if (options.tokenUsage) {
+                    session.lastApiTokenCount = options.tokenUsage;
+                }
+                span.setAttribute("memory.message_count", session.messages.length);
+                const shouldSummarize = options.enableSummarization !== undefined
+                    ? options.enableSummarization
+                    : this.config.enableSummarization;
+                if (shouldSummarize) {
+                    // Only trigger summarization if not already in progress for this session
+                    if (!this.summarizationInProgress.has(options.sessionId)) {
+                        // Capture the current Langfuse ALS context before setImmediate,
+                        // which breaks automatic AsyncLocalStorage propagation and would
+                        // otherwise cause orphaned traces in Langfuse.
+                        const summarizeWithContext = runWithCurrentLangfuseContext(async () => {
+                            try {
+                                await this.checkAndSummarize(session, tokenThreshold, options.requestId);
+                            }
+                            catch (error) {
+                                logger.error("Background summarization failed", {
+                                    sessionId: session.sessionId,
+                                    requestId: options.requestId,
+                                    error: error instanceof Error ? error.message : String(error),
+                                });
+                            }
+                        });
+                        setImmediate(summarizeWithContext);
+                    }
+                    else {
+                        logger.debug("[ConversationMemoryManager] Summarization already in progress, skipping", {
+                            sessionId: options.sessionId,
+                        });
+                    }
+                }
+                this.enforceSessionLimit();
+            }
+            catch (error) {
+                throw new ConversationMemoryError(`Failed to store conversation turn for session ${options.sessionId}`, "STORAGE_ERROR", {
+                    sessionId: options.sessionId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        });
+    }
+    /**
+     * Validate and prepare a message before adding to session
+     * Truncates if message exceeds token limit
+     */
+    async validateAndPrepareMessage(content, role, threshold) {
+        const id = randomUUID();
+        const tokenCount = TokenUtils.estimateTokenCount(content);
+        const maxMessageSize = Math.floor(threshold * MEMORY_THRESHOLD_PERCENTAGE);
+        if (tokenCount > maxMessageSize) {
+            const truncated = TokenUtils.truncateToTokenLimit(content, maxMessageSize);
+            logger.warn("Message truncated due to token limit", {
+                id,
+                role,
+                originalTokens: tokenCount,
+                threshold,
+                truncatedTo: maxMessageSize,
+            });
+            return {
+                id,
+                role,
+                content: truncated,
+                timestamp: new Date().toISOString(),
+                metadata: {
+                    truncated: true,
+                },
+            };
+        }
+        return {
+            id,
+            role,
+            content,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Check if summarization is needed based on token count
+     */
+    async checkAndSummarize(session, threshold, requestId) {
+        // Acquire lock - if already in progress, skip
+        if (this.summarizationInProgress.has(session.sessionId)) {
+            logger.debug("[ConversationMemoryManager] Summarization already in progress, skipping", {
+                sessionId: session.sessionId,
+            });
+            return;
+        }
+        this.summarizationInProgress.add(session.sessionId);
+        try {
+            await this.summarizationEngine.checkAndSummarize(session, threshold, this.config, "[ConversationMemory]", requestId);
+        }
+        catch (error) {
+            logger.error("Token counting or summarization failed", {
+                sessionId: session.sessionId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        finally {
+            // Release lock when done
+            this.summarizationInProgress.delete(session.sessionId);
+        }
+    }
+    /**
+     * Estimate total tokens for a list of messages
+     */
+    estimateTokens(messages) {
+        return messages.reduce((total, msg) => {
+            let msgTokens = TokenUtils.estimateTokenCount(msg.content);
+            if (msg.events && Array.isArray(msg.events) && msg.events.length > 0) {
+                const eventsJson = JSON.stringify(msg.events);
+                msgTokens += TokenUtils.estimateTokenCount(eventsJson);
+            }
+            return total + msgTokens;
+        }, 0);
+    }
+    /**
+     * 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
+     */
+    async buildContextMessages(sessionId, _userId, _enableSummarization, requestId) {
+        return withSpan({
+            name: "neurolink.memory.buildContext",
+            tracer: tracers.memory,
+            attributes: {
+                "memory.type": "in-memory",
+                "session.id": sessionId,
+                "memory.operation": "build_context",
+            },
+        }, async (span) => {
+            const session = this.sessions.get(sessionId);
+            const messages = session
+                ? buildContextFromPointer(session, requestId)
+                : [];
+            span.setAttribute("memory.message_count", messages.length);
+            return messages;
+        });
+    }
+    getSession(sessionId, _userId) {
+        return this.sessions.get(sessionId);
+    }
+    createSummarySystemMessage(content, summarizesFrom, summarizesTo) {
+        return {
+            id: `summary-${randomUUID()}`,
+            role: "system",
+            content: `Summary of previous conversation turns:\n\n${content}`,
+            timestamp: new Date().toISOString(),
+            metadata: {
+                isSummary: true,
+                summarizesFrom,
+                summarizesTo,
+            },
+        };
+    }
+    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;
+        }
+        const sessions = Array.from(this.sessions.entries()).sort(([, a], [, b]) => a.lastActivity - b.lastActivity);
+        const sessionsToRemove = sessions.slice(0, this.sessions.size - maxSessions);
+        for (const [sessionId] of sessionsToRemove) {
+            this.sessions.delete(sessionId);
+        }
+    }
+    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,
+        };
+    }
+    async clearSession(sessionId) {
+        return withSpan({
+            name: "neurolink.memory.clear",
+            tracer: tracers.memory,
+            attributes: {
+                "memory.type": "in-memory",
+                "session.id": sessionId,
+                "memory.operation": "clear_session",
+            },
+        }, async (span) => {
+            const session = this.sessions.get(sessionId);
+            if (!session) {
+                span.setAttribute("memory.session_found", false);
+                return false;
+            }
+            this.sessions.delete(sessionId);
+            span.setAttribute("memory.session_found", true);
+            logger.info("Session cleared", { sessionId });
+            return true;
+        });
+    }
+    async clearAllSessions() {
+        const sessionIds = Array.from(this.sessions.keys());
+        this.sessions.clear();
+        logger.info("All sessions cleared", { clearedCount: sessionIds.length });
+    }
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     * Returns a deep copy to prevent external mutation of internal state.
+     */
+    async getSessionMessages(sessionId, _userId) {
+        await this.ensureInitialized();
+        const session = this.sessions.get(sessionId);
+        return session ? session.messages.map((msg) => ({ ...msg })) : [];
+    }
+    /**
+     * Replace the entire messages array for a session.
+     * Creates the session if it does not exist.
+     * Resets summary pointers since old pointers may reference messages that no longer exist.
+     */
+    async setSessionMessages(sessionId, messages, userId) {
+        await this.ensureInitialized();
+        let session = this.sessions.get(sessionId);
+        if (!session) {
+            session = this.createNewSession(sessionId, userId);
+            this.sessions.set(sessionId, session);
+            this.enforceSessionLimit();
+        }
+        session.messages = [...messages];
+        session.summarizedUpToMessageId = undefined;
+        session.summarizedMessage = undefined;
+        session.lastTokenCount = undefined;
+        session.lastCountedAt = undefined;
+        session.lastActivity = Date.now();
+    }
+    /** Close/shutdown — no-op for in-memory manager (no external connections to release) */
+    async close() {
+        // In-memory manager has nothing to close
+    }
+}

package/dist/client/core/dynamicModels.js

@@ -0,0 +1,358 @@
+import { z } from "zod";
+import { isAbortError } from "../utils/errorHandling.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Model configuration schema for validation
+ */
+const ModelConfigSchema = z.object({
+    id: z.string(),
+    displayName: z.string(),
+    capabilities: z.array(z.string()),
+    deprecated: z.boolean(),
+    pricing: z.object({
+        input: z.number(),
+        output: z.number(),
+    }),
+    contextWindow: z.number(),
+    releaseDate: z.string(),
+});
+const ModelRegistrySchema = z.object({
+    version: z.string(),
+    lastUpdated: z.string(),
+    models: z.record(z.string(), z.record(z.string(), ModelConfigSchema)),
+    aliases: z.record(z.string(), z.string()).optional(),
+    defaults: z.record(z.string(), z.string()).optional(),
+});
+/**
+ * Dynamic Model Provider
+ * Loads and manages model configurations from external sources
+ */
+export class DynamicModelProvider {
+    static instance;
+    modelRegistry = null;
+    lastFetch = 0;
+    CACHE_DURATION = 5 * 60 * 1000; // 5 minutes
+    constructor() { }
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new DynamicModelProvider();
+        }
+        return this.instance;
+    }
+    /**
+     * Initialize the model registry from multiple sources with timeout handling
+     * Addresses hanging issues when localhost:3001 is not running or GitHub URLs timeout
+     */
+    async initialize() {
+        const sources = [
+            {
+                url: process.env.MODEL_CONFIG_URL || "http://localhost:3001/api/v1/models",
+                timeout: 3000, // 3s for localhost
+                name: "local-server",
+            },
+            {
+                url: `https://raw.githubusercontent.com/${process.env.MODEL_CONFIG_GITHUB_REPO || "juspay/neurolink"}/${process.env.MODEL_CONFIG_GITHUB_BRANCH || "release"}/config/models.json`,
+                timeout: 5000, // 5s for GitHub
+                name: "github-raw",
+            },
+            {
+                url: "./config/models.json",
+                timeout: 1000, // 1s for local file
+                name: "local-file",
+            },
+        ];
+        const errors = [];
+        for (const source of sources) {
+            try {
+                logger.debug(`[DynamicModelProvider] Attempting to load from: ${source.url} (timeout: ${source.timeout}ms)`);
+                const config = await this.loadFromSourceWithTimeout(source.url, source.timeout);
+                // Validate the configuration
+                const validatedConfig = ModelRegistrySchema.parse(config);
+                this.modelRegistry = validatedConfig;
+                this.lastFetch = Date.now();
+                logger.info(`[DynamicModelProvider] Successfully loaded model registry from: ${source.name}`, {
+                    source: source.url,
+                    modelCount: this.getTotalModelCount(),
+                    providerCount: Object.keys(validatedConfig.models).length,
+                    loadTime: `<${source.timeout}ms`,
+                });
+                return; // Success, stop trying other sources
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                errors.push({ source: source.name, error: errorMessage });
+                logger.warn(`[DynamicModelProvider] Failed to load from ${source.name} (${source.url}):`, {
+                    error: errorMessage,
+                    timeout: source.timeout,
+                });
+                continue;
+            }
+        }
+        // Log all failures for debugging
+        logger.warn(`[DynamicModelProvider] All model configuration sources failed`, { errors });
+        throw new Error(`Failed to load model configuration from all source. Attempted: ${errors.map((e) => e.source).join(", ")}`);
+    }
+    /**
+     * Load configuration from a source with timeout handling
+     * Prevents hanging when local servers are down or network requests timeout
+     */
+    async loadFromSourceWithTimeout(source, timeoutMs) {
+        if (source.startsWith("http")) {
+            // Setup timeout and abort controller
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                // Add health check for localhost before attempting full request
+                if (source.includes("localhost") || source.includes("127.0.0.1")) {
+                    await this.healthCheckLocalhost(source, Math.min(timeoutMs, 1000));
+                }
+                const response = await fetch(source, {
+                    headers: {
+                        "User-Agent": "NeuroLink/1.0 (+https://github.com/juspay/neurolink)",
+                        Accept: "application/json",
+                        "Cache-Control": "no-cache",
+                    },
+                    signal: controller.signal,
+                });
+                clearTimeout(timeoutId);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+                }
+                const data = await response.json();
+                return data;
+            }
+            catch (error) {
+                clearTimeout(timeoutId);
+                if (isAbortError(error)) {
+                    throw new Error(`Request timeout after ${timeoutMs}ms`, {
+                        cause: error,
+                    });
+                }
+                throw error;
+            }
+        }
+        else {
+            // Load from local file with timeout (for very large files)
+            return new Promise((resolve, reject) => {
+                const timeoutId = setTimeout(() => {
+                    reject(new Error(`File read timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+                (async () => {
+                    try {
+                        const fs = await import("fs");
+                        const path = await import("path");
+                        const fullPath = path.resolve(source);
+                        // Check if file exists first
+                        if (!fs.existsSync(fullPath)) {
+                            throw new Error(`File not found: ${fullPath}`);
+                        }
+                        const content = fs.readFileSync(fullPath, "utf8");
+                        const data = JSON.parse(content);
+                        clearTimeout(timeoutId);
+                        resolve(data);
+                    }
+                    catch (error) {
+                        clearTimeout(timeoutId);
+                        reject(error);
+                    }
+                })();
+            });
+        }
+    }
+    /**
+     * Quick health check for localhost endpoints
+     * Prevents hanging on non-responsive local servers
+     */
+    async healthCheckLocalhost(url, timeoutMs) {
+        const healthUrl = url.replace(/\/api\/.*$/, "/health") || `${url}/health`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetch(healthUrl, {
+                method: "HEAD", // Lightweight request
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            // Don't throw on 404 - the main endpoint might still work
+            if (response.status >= 500) {
+                throw new Error(`Server error: ${response.status}`);
+            }
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (isAbortError(error)) {
+                throw new Error(`Localhost health check timeout - server may not be running`, { cause: error });
+            }
+            // For connection refused, throw a more specific error
+            if (error instanceof Error && error.message.includes("ECONNREFUSED")) {
+                throw new Error(`Localhost server not running at ${url}`, {
+                    cause: error,
+                });
+            }
+            // For other errors, let the main request handle them
+            logger.debug(`Health check failed for ${url}, proceeding with main request`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Get all available models for a provider
+     */
+    getModelsForProvider(provider) {
+        this.ensureInitialized();
+        return this.modelRegistry?.models[provider] || {};
+    }
+    /**
+     * Resolve a model by provider and model hint
+     */
+    resolveModel(provider, modelHint) {
+        this.ensureInitialized();
+        const providerModels = this.getModelsForProvider(provider);
+        if (!modelHint) {
+            // Use default model for provider
+            const defaultModel = this.modelRegistry?.defaults?.[provider];
+            return defaultModel ? providerModels[defaultModel] : null;
+        }
+        // Check for exact match
+        if (providerModels[modelHint]) {
+            return providerModels[modelHint];
+        }
+        // Check aliases
+        const aliasTarget = this.modelRegistry?.aliases?.[modelHint];
+        if (aliasTarget) {
+            const [aliasProvider, aliasModel] = aliasTarget.split("/");
+            return this.resolveModel(aliasProvider, aliasModel);
+        }
+        // Fuzzy matching (partial string match)
+        const fuzzyMatch = Object.keys(providerModels).find((key) => key.toLowerCase().includes(modelHint.toLowerCase()) ||
+            modelHint.toLowerCase().includes(key.toLowerCase()));
+        return fuzzyMatch ? providerModels[fuzzyMatch] : null;
+    }
+    /**
+     * Search models by capabilities
+     */
+    searchByCapability(capability, options = {}) {
+        this.ensureInitialized();
+        const results = [];
+        if (!this.modelRegistry) {
+            return results;
+        }
+        for (const [providerName, models] of Object.entries(this.modelRegistry.models)) {
+            if (options.provider && providerName !== options.provider) {
+                continue;
+            }
+            for (const [modelName, modelConfig] of Object.entries(models)) {
+                if (options.excludeDeprecated && modelConfig.deprecated) {
+                    continue;
+                }
+                if (options.maxPrice && modelConfig.pricing.input > options.maxPrice) {
+                    continue;
+                }
+                if (!modelConfig.capabilities.includes(capability)) {
+                    continue;
+                }
+                results.push({
+                    provider: providerName,
+                    model: modelName,
+                    config: modelConfig,
+                });
+            }
+        }
+        // Sort by price (cheapest first)
+        return results.sort((a, b) => a.config.pricing.input - b.config.pricing.input);
+    }
+    /**
+     * Get the best model for a specific use case
+     */
+    getBestModelFor(useCase) {
+        this.ensureInitialized();
+        switch (useCase) {
+            case "coding":
+                return (this.searchByCapability("functionCalling", {
+                    excludeDeprecated: true,
+                })[0] || null);
+            case "analysis":
+                return (this.searchByCapability("analysis", { excludeDeprecated: true })[0] ||
+                    null);
+            case "vision":
+                return (this.searchByCapability("vision", { excludeDeprecated: true })[0] ||
+                    null);
+            case "fastest":
+                // Return cheapest as proxy for fastest (usually correlates)
+                return (this.getAllModels()
+                    .filter((m) => !m.config.deprecated)
+                    .sort((a, b) => a.config.pricing.input - b.config.pricing.input)[0] || null);
+            case "cheapest":
+                return (this.getAllModels()
+                    .filter((m) => !m.config.deprecated)
+                    .sort((a, b) => a.config.pricing.input - b.config.pricing.input)[0] || null);
+            default:
+                return null;
+        }
+    }
+    /**
+     * Get all models across all providers
+     */
+    getAllModels() {
+        this.ensureInitialized();
+        const results = [];
+        if (!this.modelRegistry) {
+            return results;
+        }
+        for (const [providerName, models] of Object.entries(this.modelRegistry.models)) {
+            for (const [modelName, modelConfig] of Object.entries(models)) {
+                results.push({
+                    provider: providerName,
+                    model: modelName,
+                    config: modelConfig,
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Get total number of models
+     */
+    getTotalModelCount() {
+        if (!this.modelRegistry) {
+            return 0;
+        }
+        return Object.values(this.modelRegistry.models).reduce((total, providerModels) => total + Object.keys(providerModels).length, 0);
+    }
+    /**
+     * Check if cache needs refresh
+     */
+    needsRefresh() {
+        return Date.now() - this.lastFetch > this.CACHE_DURATION;
+    }
+    /**
+     * Force refresh the model registry
+     */
+    async refresh() {
+        this.modelRegistry = null;
+        await this.initialize();
+    }
+    /**
+     * Ensure the registry is initialized
+     */
+    ensureInitialized() {
+        if (!this.modelRegistry) {
+            throw new Error("Model registry not initialized. Call initialize() first.");
+        }
+    }
+    /**
+     * Get registry metadata
+     */
+    getMetadata() {
+        if (!this.modelRegistry) {
+            return null;
+        }
+        return {
+            version: this.modelRegistry.version,
+            lastUpdated: this.modelRegistry.lastUpdated,
+            modelCount: this.getTotalModelCount(),
+        };
+    }
+}
+// Export singleton instance
+export const dynamicModelProvider = DynamicModelProvider.getInstance();