@juspay/neurolink 9.15.0 → 9.16.0

package/dist/core/modules/MessageBuilder.js

@@ -12,8 +12,45 @@
  *
  * @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
  */
@@ -29,93 +66,101 @@ export class MessageBuilder {
      * Detects multimodal input and routes to appropriate message builder
      */
     async buildMessages(options) {
-        const hasMultimodalInput = (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 hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles;
-        };
-        let messages;
-        if (hasMultimodalInput(options)) {
-            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
-        return messages.map((msg) => {
-            const providerOptions = msg
-                .providerOptions;
-            if (typeof msg.content === "string") {
-                return {
-                    role: msg.role,
-                    content: msg.content,
-                    ...(providerOptions && { providerOptions }),
+        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 {
-                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 }),
-                };
+                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;
         });
     }
     /**
@@ -127,97 +172,104 @@ export class MessageBuilder {
      * @returns Promise resolving to CoreMessage array ready for AI SDK
      */
     async buildMessagesForStream(options) {
-        // Detect multimodal input
-        const hasMultimodalInput = (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 hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles;
-        };
-        let messages;
-        if (hasMultimodalInput(options)) {
-            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
-        return messages.map((msg) => {
-            const providerOptions = msg
-                .providerOptions;
-            if (typeof msg.content === "string") {
-                return {
-                    role: msg.role,
-                    content: msg.content,
-                    ...(providerOptions && { providerOptions }),
+        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 {
-                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 }),
-                };
+                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/core/modules/StreamHandler.d.ts

@@ -28,6 +28,7 @@ export declare class StreamHandler {
     validateStreamOptions(options: StreamOptions): void;
     /**
      * 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: {
         textStream: AsyncIterable<string>;

package/dist/core/modules/StreamHandler.js

@@ -12,6 +12,8 @@
  *
  * @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";
@@ -31,33 +33,87 @@ export class StreamHandler {
      * Validate stream options - consolidates validation from 7/10 providers
      */
     validateStreamOptions(options) {
-        const validation = validateStreamOpts(options);
-        if (!validation.isValid) {
-            const summary = createValidationSummary(validation);
-            throw new ValidationError(`Stream options validation failed: ${summary}`, "options", "VALIDATION_FAILED", validation.suggestions);
+        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`,
+                    ]);
+                }
+            }
         }
-        // Log warnings if any
-        if (validation.warnings.length > 0) {
-            logger.warn("Stream options validation warnings:", validation.warnings);
+        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;
         }
-        // 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`,
-                ]);
-            }
+        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;
             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 };
             }
+            // 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,
+                });
+            }
         })();
     }
     /**
@@ -75,18 +131,30 @@ export class StreamHandler {
      * Create stream analytics - consolidates analytics from 4/10 providers
      */
     async createStreamAnalytics(result, startTime, options) {
-        try {
-            const analytics = createAnalytics(this.providerName, this.modelName, result, Date.now() - startTime, {
-                requestId: `${this.providerName}-stream-${nanoid()}`,
-                streamingMode: true,
-                ...options.context,
-            });
-            return analytics;
-        }
-        catch (error) {
-            logger.warn(`Analytics creation failed for ${this.providerName}:`, error);
-            return undefined;
-        }
+        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)

package/dist/core/modules/TelemetryHandler.d.ts

@@ -41,7 +41,16 @@ export declare class TelemetryHandler {
         totalTokens: number;
     } | undefined, responseTime: number): Promise<void>;
     /**
-     * Calculate actual cost based on token usage and provider configuration
+     * 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).
      */
     calculateActualCost(usage: {
         promptTokens?: number;