@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/core/modules/MessageBuilder.js

@@ -0,0 +1,273 @@
+/**
+ * Message Builder Module
+ *
+ * Handles all message construction logic for AI providers.
+ * Extracted from BaseProvider to follow Single Responsibility Principle.
+ *
+ * Responsibilities:
+ * - Building messages from text generation options
+ * - Building messages from stream options
+ * - Multimodal input detection
+ * - Message format conversion (to ModelMessage[])
+ *
+ * @module core/modules/MessageBuilder
+ */
+import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
+import { logger } from "../../utils/logger.js";
+import { buildMessagesArray, buildMultimodalMessagesArray, } from "../../utils/messageBuilder.js";
+/**
+ * Compute total content length across all messages for span attributes.
+ */
+function computeTotalContentLength(messages) {
+    let total = 0;
+    for (const msg of messages) {
+        if (typeof msg.content === "string") {
+            total += msg.content.length;
+        }
+        else if (Array.isArray(msg.content)) {
+            for (const part of msg.content) {
+                if ("text" in part &&
+                    typeof part.text === "string") {
+                    total += part.text.length;
+                }
+            }
+        }
+    }
+    return total;
+}
+/**
+ * Check whether input contains multimodal content (images, files, PDFs, CSVs).
+ */
+function detectMultimodal(opts) {
+    const input = opts.input;
+    const hasImages = !!input?.images?.length;
+    const hasContent = !!input?.content?.length;
+    const hasCSVFiles = !!input?.csvFiles?.length;
+    const hasPdfFiles = !!input?.pdfFiles?.length;
+    const hasFiles = !!input?.files?.length;
+    return {
+        isMultimodal: hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles,
+        hasImages,
+        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles,
+    };
+}
+/**
+ * MessageBuilder class - Handles message construction for AI providers
+ */
+export class MessageBuilder {
+    providerName;
+    modelName;
+    constructor(providerName, modelName) {
+        this.providerName = providerName;
+        this.modelName = modelName;
+    }
+    /**
+     * Build messages array for generation
+     * Detects multimodal input and routes to appropriate message builder
+     */
+    async buildMessages(options) {
+        return withSpan({
+            name: "neurolink.message.build",
+            tracer: tracers.sdk,
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+                [ATTR.NL_MODEL]: this.modelName,
+            },
+        }, async (span) => {
+            const { isMultimodal, hasImages, hasFiles } = detectMultimodal(options);
+            span.setAttribute(ATTR.MSG_IS_MULTIMODAL, isMultimodal);
+            let messages;
+            if (isMultimodal) {
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    logger.debug("Detected multimodal input, using multimodal message builder");
+                }
+                const input = options.input;
+                const multimodalOptions = {
+                    input: {
+                        text: options.prompt || options.input?.text || "",
+                        images: input?.images,
+                        content: input?.content,
+                        csvFiles: input?.csvFiles,
+                        pdfFiles: input?.pdfFiles,
+                        files: input?.files,
+                    },
+                    csvOptions: options.csvOptions,
+                    provider: options.provider,
+                    model: options.model,
+                    temperature: options.temperature,
+                    maxTokens: options.maxTokens,
+                    systemPrompt: options.systemPrompt,
+                    enableAnalytics: options.enableAnalytics,
+                    enableEvaluation: options.enableEvaluation,
+                    context: options.context,
+                    conversationHistory: options.conversationMessages,
+                    schema: options.schema,
+                    output: options.output,
+                    fileRegistry: options.fileRegistry,
+                };
+                messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+            }
+            else {
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    logger.debug("No multimodal input detected, using standard message builder");
+                }
+                messages = await buildMessagesArray(options);
+            }
+            // Convert messages to Vercel AI SDK format
+            // Preserve providerOptions (e.g. Anthropic cache_control) through conversion
+            const coreMessages = messages.map((msg) => {
+                const providerOptions = msg
+                    .providerOptions;
+                if (typeof msg.content === "string") {
+                    return {
+                        role: msg.role,
+                        content: msg.content,
+                        ...(providerOptions && { providerOptions }),
+                    };
+                }
+                else {
+                    return {
+                        role: msg.role,
+                        content: msg.content.map((item) => {
+                            const itemProviderOptions = item.providerOptions;
+                            if (item.type === "text") {
+                                return {
+                                    type: "text",
+                                    text: item.text || "",
+                                    ...(itemProviderOptions && {
+                                        providerOptions: itemProviderOptions,
+                                    }),
+                                };
+                            }
+                            else if (item.type === "image") {
+                                return {
+                                    type: "image",
+                                    image: item.image || "",
+                                    ...(itemProviderOptions && {
+                                        providerOptions: itemProviderOptions,
+                                    }),
+                                };
+                            }
+                            return item;
+                        }),
+                        ...(providerOptions && { providerOptions }),
+                    };
+                }
+            });
+            span.setAttribute(ATTR.MSG_COUNT, coreMessages.length);
+            span.setAttribute(ATTR.MSG_HAS_IMAGES, hasImages);
+            span.setAttribute(ATTR.MSG_HAS_FILES, hasFiles);
+            span.setAttribute(ATTR.MSG_HAS_SYSTEM_PROMPT, !!options.systemPrompt);
+            span.setAttribute(ATTR.MSG_TOTAL_CONTENT_LENGTH, computeTotalContentLength(coreMessages));
+            return coreMessages;
+        });
+    }
+    /**
+     * Build messages array for streaming operations
+     * This is a protected helper method that providers can use to build messages
+     * with automatic multimodal detection, eliminating code duplication
+     *
+     * @param options - Stream options or text generation options
+     * @returns Promise resolving to ModelMessage array ready for AI SDK
+     */
+    async buildMessagesForStream(options) {
+        return withSpan({
+            name: "neurolink.message.build_for_stream",
+            tracer: tracers.sdk,
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+                [ATTR.NL_MODEL]: this.modelName,
+            },
+        }, async (span) => {
+            const { isMultimodal, hasImages, hasFiles } = detectMultimodal(options);
+            span.setAttribute(ATTR.MSG_IS_MULTIMODAL, isMultimodal);
+            let messages;
+            if (isMultimodal) {
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    logger.debug(`${this.providerName}: Detected multimodal input, using multimodal message builder`);
+                }
+                const input = options.input;
+                const multimodalOptions = {
+                    input: {
+                        text: options.prompt ||
+                            options.input?.text ||
+                            "",
+                        images: input?.images,
+                        content: input?.content,
+                        csvFiles: input?.csvFiles,
+                        pdfFiles: input?.pdfFiles,
+                        files: input?.files,
+                    },
+                    csvOptions: options.csvOptions,
+                    provider: options.provider,
+                    model: options.model,
+                    temperature: options.temperature,
+                    maxTokens: options.maxTokens,
+                    systemPrompt: options.systemPrompt,
+                    enableAnalytics: options.enableAnalytics,
+                    enableEvaluation: options.enableEvaluation,
+                    context: options.context,
+                    conversationHistory: options
+                        .conversationMessages,
+                    schema: options.schema,
+                    output: options.output,
+                    fileRegistry: options.fileRegistry,
+                };
+                messages = await buildMultimodalMessagesArray(multimodalOptions, this.providerName, this.modelName);
+            }
+            else {
+                if (process.env.NEUROLINK_DEBUG === "true") {
+                    logger.debug(`${this.providerName}: No multimodal input detected, using standard message builder`);
+                }
+                messages = await buildMessagesArray(options);
+            }
+            // Convert messages to Vercel AI SDK format
+            // Preserve providerOptions (e.g. Anthropic cache_control) through conversion
+            const coreMessages = messages.map((msg) => {
+                const providerOptions = msg
+                    .providerOptions;
+                if (typeof msg.content === "string") {
+                    return {
+                        role: msg.role,
+                        content: msg.content,
+                        ...(providerOptions && { providerOptions }),
+                    };
+                }
+                else {
+                    return {
+                        role: msg.role,
+                        content: msg.content.map((item) => {
+                            const itemProviderOptions = item.providerOptions;
+                            if (item.type === "text") {
+                                return {
+                                    type: "text",
+                                    text: item.text || "",
+                                    ...(itemProviderOptions && {
+                                        providerOptions: itemProviderOptions,
+                                    }),
+                                };
+                            }
+                            else if (item.type === "image") {
+                                return {
+                                    type: "image",
+                                    image: item.image || "",
+                                    ...(itemProviderOptions && {
+                                        providerOptions: itemProviderOptions,
+                                    }),
+                                };
+                            }
+                            return item;
+                        }),
+                        ...(providerOptions && { providerOptions }),
+                    };
+                }
+            });
+            span.setAttribute(ATTR.MSG_COUNT, coreMessages.length);
+            span.setAttribute(ATTR.MSG_HAS_IMAGES, hasImages);
+            span.setAttribute(ATTR.MSG_HAS_FILES, hasFiles);
+            span.setAttribute(ATTR.MSG_HAS_SYSTEM_PROMPT, !!options.systemPrompt);
+            span.setAttribute(ATTR.MSG_TOTAL_CONTENT_LENGTH, computeTotalContentLength(coreMessages));
+            return coreMessages;
+        });
+    }
+}

package/dist/client/core/modules/StreamHandler.js

@@ -0,0 +1,185 @@
+/**
+ * Stream Handler Module
+ *
+ * Handles streaming-related validation, result creation, and analytics.
+ * Extracted from BaseProvider to follow Single Responsibility Principle.
+ *
+ * Responsibilities:
+ * - Stream options validation
+ * - Text stream creation
+ * - Stream result formatting
+ * - Stream analytics creation
+ *
+ * @module core/modules/StreamHandler
+ */
+import { trace, context as otelContext, SpanStatusCode, } from "@opentelemetry/api";
+import { tracers, ATTR, withSpan } from "../../telemetry/index.js";
+import { logger } from "../../utils/logger.js";
+import { validateStreamOptions as validateStreamOpts, ValidationError, createValidationSummary, } from "../../utils/parameterValidation.js";
+import { STEP_LIMITS } from "../constants.js";
+import { createAnalytics } from "../analytics.js";
+import { nanoid } from "nanoid";
+import { NoOutputGeneratedError } from "ai";
+/**
+ * StreamHandler class - Handles streaming operations for AI providers
+ */
+export class StreamHandler {
+    providerName;
+    modelName;
+    constructor(providerName, modelName) {
+        this.providerName = providerName;
+        this.modelName = modelName;
+    }
+    /**
+     * Validate stream options - consolidates validation from 7/10 providers
+     */
+    validateStreamOptions(options) {
+        const span = tracers.stream.startSpan("neurolink.stream.validate", {
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+                [ATTR.NL_MODEL]: this.modelName,
+                "stream.has_max_steps": options.maxSteps !== undefined,
+            },
+        });
+        try {
+            const validation = validateStreamOpts(options);
+            if (!validation.isValid) {
+                const summary = createValidationSummary(validation);
+                span.setAttribute("stream.validation_errors", validation.errors?.length ?? 0);
+                throw new ValidationError(`Stream options validation failed: ${summary}`, "options", "VALIDATION_FAILED", validation.suggestions);
+            }
+            // Log warnings if any
+            if (validation.warnings.length > 0) {
+                logger.warn("Stream options validation warnings:", validation.warnings);
+                span.addEvent("stream.validation.warnings", {
+                    "warning.count": validation.warnings.length,
+                    warnings: validation.warnings.join("; ").substring(0, 500),
+                });
+            }
+            // Additional BaseProvider-specific validation
+            if (options.maxSteps !== undefined) {
+                if (options.maxSteps < STEP_LIMITS.min ||
+                    options.maxSteps > STEP_LIMITS.max) {
+                    throw new ValidationError(`maxSteps must be between ${STEP_LIMITS.min} and ${STEP_LIMITS.max}`, "maxSteps", "OUT_OF_RANGE", [
+                        `Use a value between ${STEP_LIMITS.min} and ${STEP_LIMITS.max} for optimal performance`,
+                    ]);
+                }
+            }
+        }
+        catch (error) {
+            span.recordException(error instanceof Error ? error : new Error(String(error)));
+            // NLK-GAP-006 fix: set error status alongside recordException
+            span.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Create text stream transformation - consolidates identical logic from 7/10 providers
+     * Tracks TTFC (Time To First Chunk), chunk count, and total bytes streamed.
+     */
+    createTextStream(result) {
+        const providerName = this.providerName;
+        return (async function* () {
+            let chunkCount = 0;
+            let totalBytes = 0;
+            const streamStart = Date.now();
+            let firstChunkTime;
+            try {
+                for await (const chunk of result.textStream) {
+                    chunkCount++;
+                    totalBytes += chunk.length;
+                    if (!firstChunkTime) {
+                        firstChunkTime = Date.now();
+                        const activeSpan = trace.getSpan(otelContext.active());
+                        if (activeSpan) {
+                            activeSpan.addEvent("stream.first_chunk", {
+                                "stream.ttfc_ms": firstChunkTime - streamStart,
+                                "stream.provider": providerName,
+                            });
+                        }
+                    }
+                    yield { content: chunk };
+                }
+            }
+            catch (error) {
+                // AI SDK v6 throws NoOutputGeneratedError when the stream produces no output
+                // (e.g. empty response, model refusal with no text). Treat as an empty stream
+                // rather than crashing the process with an unhandled rejection.
+                if (NoOutputGeneratedError.isInstance(error)) {
+                    logger.warn(`${providerName}: Stream produced no output (NoOutputGeneratedError), returning empty stream`);
+                }
+                else {
+                    throw error;
+                }
+            }
+            // Record completion metrics on the active span
+            const activeSpan = trace.getSpan(otelContext.active());
+            if (activeSpan) {
+                activeSpan.addEvent("stream.complete", {
+                    "stream.chunk_count": chunkCount,
+                    "stream.total_bytes": totalBytes,
+                    "stream.duration_ms": Date.now() - streamStart,
+                    "stream.ttfc_ms": firstChunkTime ? firstChunkTime - streamStart : -1,
+                });
+            }
+        })();
+    }
+    /**
+     * Create standardized stream result - consolidates result structure
+     */
+    createStreamResult(stream, additionalProps = {}) {
+        return {
+            stream,
+            provider: this.providerName,
+            model: this.modelName,
+            ...additionalProps,
+        };
+    }
+    /**
+     * Create stream analytics - consolidates analytics from 4/10 providers
+     */
+    async createStreamAnalytics(result, startTime, options) {
+        return withSpan({
+            name: "neurolink.stream.analytics",
+            tracer: tracers.stream,
+            attributes: {
+                [ATTR.NL_PROVIDER]: this.providerName,
+                [ATTR.NL_MODEL]: this.modelName,
+                [ATTR.NL_STREAM_MODE]: true,
+            },
+        }, async (span) => {
+            try {
+                const durationMs = Date.now() - startTime;
+                span.setAttribute("stream.duration_ms", durationMs);
+                const analytics = createAnalytics(this.providerName, this.modelName, result, durationMs, {
+                    requestId: `${this.providerName}-stream-${nanoid()}`,
+                    streamingMode: true,
+                    ...options.context,
+                });
+                return analytics;
+            }
+            catch (error) {
+                logger.warn(`Analytics creation failed for ${this.providerName}:`, error);
+                return undefined;
+            }
+        });
+    }
+    /**
+     * Validate streaming-only options (called before executeStream)
+     * Simpler validation for options object structure
+     */
+    validateStreamOptionsOnly(options) {
+        if (!options.input) {
+            throw new ValidationError("Stream options must include input", "input", "MISSING_REQUIRED", ["Provide options.input with text content"]);
+        }
+        if (!options.input.text && !options.input.images?.length) {
+            throw new ValidationError("Stream input must include either text or images", "input", "MISSING_REQUIRED", ["Provide options.input.text or options.input.images"]);
+        }
+    }
+}

package/dist/client/core/modules/TelemetryHandler.js

@@ -0,0 +1,203 @@
+/**
+ * Telemetry Handler Module
+ *
+ * Handles analytics, evaluation, performance metrics, and telemetry configuration.
+ * Extracted from BaseProvider to follow Single Responsibility Principle.
+ *
+ * Responsibilities:
+ * - Analytics creation and tracking
+ * - Evaluation generation
+ * - Performance metrics recording
+ * - Cost calculation
+ * - Telemetry configuration
+ *
+ * @module core/modules/TelemetryHandler
+ */
+import { nanoid } from "nanoid";
+import { logger } from "../../utils/logger.js";
+import { recordProviderPerformanceFromMetrics } from "../evaluationProviders.js";
+import { modelConfig } from "../modelConfiguration.js";
+import { TelemetryService } from "../../telemetry/telemetryService.js";
+import { calculateCost, hasPricing } from "../../utils/pricing.js";
+import { getLangfuseContext } from "../../services/server/ai/observability/instrumentation.js";
+/**
+ * TelemetryHandler class - Handles analytics and telemetry for AI providers
+ */
+export class TelemetryHandler {
+    providerName;
+    modelName;
+    neurolink;
+    constructor(providerName, modelName, neurolink) {
+        this.providerName = providerName;
+        this.modelName = modelName;
+        this.neurolink = neurolink;
+    }
+    /**
+     * Create analytics for a generation result
+     */
+    async createAnalytics(result, responseTime, context) {
+        const { createAnalytics } = await import("../analytics.js");
+        return createAnalytics(this.providerName, this.modelName, result, responseTime, context);
+    }
+    /**
+     * Create evaluation for a generation result
+     */
+    async createEvaluation(result, options) {
+        const { evaluateResponse } = await import("../evaluation.js");
+        const context = {
+            userQuery: options.prompt || options.input?.text || "Generated response",
+            aiResponse: result.content,
+            context: options.context,
+            primaryDomain: options.evaluationDomain,
+            assistantRole: "AI assistant",
+            conversationHistory: options.conversationHistory?.map((msg) => ({
+                role: msg.role,
+                content: msg.content,
+            })),
+            toolUsage: options.toolUsageContext
+                ? [
+                    {
+                        toolName: options.toolUsageContext,
+                        input: {},
+                        output: {},
+                        executionTime: 0,
+                    },
+                ]
+                : undefined,
+            expectedOutcome: options.expectedOutcome,
+            evaluationCriteria: options.evaluationCriteria,
+        };
+        const evaluation = await evaluateResponse(context);
+        return evaluation;
+    }
+    /**
+     * Record performance metrics for a generation
+     */
+    async recordPerformanceMetrics(usage, responseTime) {
+        try {
+            const totalTokens = (usage?.inputTokens || 0) + (usage?.outputTokens || 0);
+            const actualCost = await this.calculateActualCost(usage || { inputTokens: 0, outputTokens: 0 });
+            recordProviderPerformanceFromMetrics(this.providerName, {
+                responseTime,
+                tokensGenerated: totalTokens,
+                cost: actualCost,
+                success: true,
+            });
+            // Wire TelemetryService metrics so OTEL counters/histograms are populated
+            TelemetryService.getInstance().recordAIRequest(this.providerName, this.modelName, totalTokens, responseTime, actualCost > 0 ? actualCost : undefined);
+            logger.debug(`Performance recorded for ${this.providerName}`, {
+                responseTime: `${responseTime}ms`,
+                tokens: totalTokens,
+                estimatedCost: `$${actualCost.toFixed(6)}`,
+            });
+        }
+        catch (perfError) {
+            logger.warn("⚠️ Performance recording failed:", perfError);
+        }
+    }
+    /**
+     * Calculate actual cost based on token usage and provider configuration.
+     *
+     * Uses the per-model pricing table first (which has accurate rates for
+     * specific models like Claude on Vertex AI), then falls back to the
+     * provider-level default cost from modelConfiguration.
+     *
+     * Previously this only used modelConfig.getCostInfo() which returns
+     * provider-level defaults (e.g. Gemini rates for the "vertex" provider),
+     * causing a ~1,780x under-estimate when the actual model was Claude Sonnet
+     * on Vertex AI ($0.000060 vs $0.106895 for the same request).
+     */
+    async calculateActualCost(usage) {
+        try {
+            const promptTokens = usage?.inputTokens || 0;
+            const completionTokens = usage?.outputTokens || 0;
+            // Try the per-model pricing table first (includes correct rates for
+            // Claude on Vertex, cache token rates, etc.)
+            if (hasPricing(this.providerName, this.modelName)) {
+                return calculateCost(this.providerName, this.modelName, {
+                    input: promptTokens,
+                    output: completionTokens,
+                    total: promptTokens + completionTokens,
+                });
+            }
+            // Fall back to provider-level default cost from configuration system
+            const costInfo = modelConfig.getCostInfo(this.providerName, this.modelName);
+            if (!costInfo) {
+                return 0; // No cost info available
+            }
+            // Calculate cost per 1K tokens
+            const inputCost = (promptTokens / 1000) * costInfo.input;
+            const outputCost = (completionTokens / 1000) * costInfo.output;
+            return inputCost + outputCost;
+        }
+        catch (error) {
+            logger.debug(`Cost calculation failed for ${this.providerName}:`, error);
+            return 0; // Fallback to 0 on any error
+        }
+    }
+    /**
+     * Create telemetry configuration for Vercel AI SDK experimental_telemetry
+     * This enables automatic OpenTelemetry tracing when telemetry is enabled
+     */
+    getTelemetryConfig(options, operationType = "stream") {
+        // Check if telemetry is enabled via NeuroLink observability config
+        if (!this.neurolink?.isTelemetryEnabled()) {
+            return undefined;
+        }
+        const context = options.context;
+        const langfuseContext = getLangfuseContext();
+        const traceName = context?.traceName ?? langfuseContext?.traceName;
+        const userId = context?.userId ?? langfuseContext?.userId;
+        const functionId = traceName ? traceName : userId ? userId : "guest";
+        const metadata = {
+            ...(context?.metadata || {}),
+            provider: this.providerName,
+            model: this.modelName,
+            toolsEnabled: !options.disableTools,
+            neurolink: true,
+            operationType,
+            originalProvider: this.providerName,
+        };
+        // Add sessionId if available
+        if ("sessionId" in options && options.sessionId) {
+            const sessionId = options.sessionId;
+            if (typeof sessionId === "string" ||
+                typeof sessionId === "number" ||
+                typeof sessionId === "boolean") {
+                metadata.sessionId = sessionId;
+            }
+        }
+        return {
+            isEnabled: true,
+            functionId,
+            metadata,
+            recordInputs: process.env.NEUROLINK_RECORD_INPUTS?.toLowerCase() !== "false",
+            recordOutputs: true,
+        };
+    }
+    /**
+     * Handle tool execution storage if available
+     */
+    async handleToolExecutionStorage(toolCalls, toolResults, options, currentTime) {
+        // Check if tools are not empty
+        const hasToolData = (toolCalls && toolCalls.length > 0) ||
+            (toolResults && toolResults.length > 0);
+        // Check if NeuroLink instance is available and has tool execution storage
+        const hasStorageAvailable = this.neurolink?.isToolExecutionStorageAvailable();
+        // Early return if storage is not available or no tool data
+        if (!hasStorageAvailable || !hasToolData || !this.neurolink) {
+            return;
+        }
+        const sessionId = options.context?.sessionId ||
+            options.sessionId ||
+            `session-${nanoid()}`;
+        const userId = options.context?.userId ||
+            options.userId;
+        try {
+            await this.neurolink.storeToolExecutions(sessionId, userId, toolCalls, toolResults, currentTime);
+        }
+        catch (error) {
+            logger.warn("Failed to store tool executions:", error);
+        }
+    }
+}