@juspay/neurolink 9.15.0 → 9.16.0

package/dist/core/modules/GenerationHandler.js

@@ -13,9 +13,14 @@
  * @module core/modules/GenerationHandler
  */
 import { generateText, Output, NoObjectGeneratedError } from "ai";
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../../telemetry/tracers.js";
 import { logger } from "../../utils/logger.js";
 import { extractTokenUsage, extractCacheCreationTokens, extractCacheReadTokens, calculateCacheSavingsPercent, } from "../../utils/tokenUtils.js";
+import { withProviderRetry } from "../../utils/providerRetry.js";
+import { calculateCost } from "../../utils/pricing.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
+const genTracer = tracers.generation;
 /**
  * Safely preview-serialize a value for debug logging.
  * Handles undefined, circular references, and non-serializable values.
@@ -59,10 +64,14 @@ export class GenerationHandler {
         const isAnthropicProvider = this.providerName === "anthropic" ||
             this.providerName === "bedrock" ||
             (this.providerName === "vertex" && this.modelName?.startsWith("claude-"));
-        const useStructuredOutput = includeStructuredOutput &&
+        // Gemini 2.5 and earlier cannot use tools + structured JSON output simultaneously.
+        // When both are requested on a Google provider, disable structured output (tools take priority).
+        const wantsStructuredOutput = includeStructuredOutput &&
             !!options.schema &&
             (options.output?.format === "json" ||
                 options.output?.format === "structured");
+        const useStructuredOutput = wantsStructuredOutput &&
+            !(isGoogleProvider && shouldUseTools && Object.keys(tools).length > 0);
         // Annotate the last tool with cache_control so the full tool-definition
         // block becomes a cache breakpoint for Anthropic-family providers.
         // Non-Anthropic providers harmlessly ignore unknown providerOptions.
@@ -98,6 +107,7 @@ export class GenerationHandler {
             }),
             temperature: options.temperature,
             maxTokens: options.maxTokens,
+            maxRetries: 0, // NL11: Disable AI SDK's invisible internal retries; we handle retries with OTel instrumentation
             abortSignal: options.abortSignal,
             ...(useStructuredOutput &&
                 options.schema && {
@@ -153,108 +163,59 @@ export class GenerationHandler {
      * Execute the generation with AI SDK
      */
     async executeGeneration(model, messages, tools, options) {
-        const shouldUseTools = !options.disableTools && this.supportsToolsFn();
-        const useStructuredOutput = !!options.schema &&
-            (options.output?.format === "json" ||
-                options.output?.format === "structured");
-        const requestId = options.requestId ||
-            options.context?.requestId ||
-            "unknown";
-        logger.info("[GenerationHandler] Calling generateText", {
-            requestId,
-            model: model.modelId || "unknown",
-            messageCount: messages.length,
-            toolCount: Object.keys(tools || {}).length,
-            maxSteps: options.maxSteps,
-            temperature: options.temperature,
-        });
-        if (logger.shouldLog("debug")) {
-            try {
-                logger.debug("[Observability] Full generateText parameters", {
-                    requestId,
-                    model: model.modelId || "unknown",
-                    messageCount: messages.length,
-                    messages: messages.map((msg, i) => ({
-                        index: i,
-                        role: msg.role,
-                        contentLength: typeof msg.content === "string"
-                            ? msg.content.length
-                            : safePreview(msg.content).length,
-                        contentPreview: typeof msg.content === "string"
-                            ? msg.content.substring(0, 200)
-                            : "[multimodal]",
-                    })),
-                    toolNames: Object.keys(tools || {}),
-                    toolCount: Object.keys(tools || {}).length,
-                    maxSteps: options.maxSteps,
-                    temperature: options.temperature,
-                    maxTokens: options.maxTokens,
-                });
-            }
-            catch {
-                // Ignore serialization errors in debug logging
-            }
-        }
-        const genStartTime = Date.now();
-        try {
-            const result = await this.callGenerateText(model, messages, tools, options, shouldUseTools, true);
-            logger.info("[GenerationHandler] generateText returned", {
+        return genTracer.startActiveSpan("neurolink.executeGeneration", { kind: SpanKind.INTERNAL }, async (span) => {
+            const shouldUseTools = !options.disableTools && this.supportsToolsFn();
+            const toolCount = Object.keys(tools || {}).length;
+            const useStructuredOutput = !!options.schema &&
+                (options.output?.format === "json" ||
+                    options.output?.format === "structured");
+            span.setAttribute("gen_ai.system", this.providerName || "unknown");
+            span.setAttribute("neurolink.structured_output", useStructuredOutput);
+            span.setAttribute("neurolink.tool_count", toolCount);
+            span.setAttribute("neurolink.message_count", messages.length);
+            span.setAttribute("gen_ai.request.model", model.modelId || this.modelName || "unknown");
+            const requestId = options.requestId ||
+                options.context?.requestId ||
+                "unknown";
+            logger.info("[GenerationHandler] Calling generateText", {
                 requestId,
-                durationMs: Date.now() - genStartTime,
-                finishReason: result.finishReason,
-                steps: result.steps?.length || 1,
-                toolCallsTotal: result.toolCalls?.length || 0,
-                responseChars: result.text?.length || 0,
+                model: model.modelId || "unknown",
+                messageCount: messages.length,
+                toolCount,
+                maxSteps: options.maxSteps,
+                temperature: options.temperature,
             });
             if (logger.shouldLog("debug")) {
-                logger.debug("[Observability] Full LLM response", {
-                    requestId,
-                    finishReason: result.finishReason,
-                    responseTextPreview: result.text?.substring(0, 200) || "",
-                    responseTextLength: result.text?.length || 0,
-                    toolCalls: result.toolCalls?.map((tc) => ({
-                        toolName: tc.toolName,
-                        argsPreview: safePreview(tc.args),
-                    })),
-                    toolResults: result.toolResults?.map((tr) => ({
-                        toolName: tr.toolName,
-                        resultPreview: safePreview(tr.result),
-                    })),
-                    steps: result.steps?.map((step, i) => ({
-                        stepIndex: i,
-                        stepType: step.stepType,
-                        textPreview: step.text?.substring(0, 200),
-                        textLength: step.text?.length || 0,
-                        toolCalls: step.toolCalls?.map((tc) => ({
-                            toolName: tc.toolName,
-                            argsPreview: safePreview(tc.args),
+                try {
+                    logger.debug("[Observability] Full generateText parameters", {
+                        requestId,
+                        model: model.modelId || "unknown",
+                        messageCount: messages.length,
+                        messages: messages.map((msg, i) => ({
+                            index: i,
+                            role: msg.role,
+                            contentLength: typeof msg.content === "string"
+                                ? msg.content.length
+                                : safePreview(msg.content).length,
+                            contentPreview: typeof msg.content === "string"
+                                ? msg.content.substring(0, 200)
+                                : "[multimodal]",
                         })),
-                        toolResults: step.toolResults?.map((tr) => ({
-                            toolName: tr.toolName,
-                            resultPreview: safePreview(tr.result),
-                        })),
-                        finishReason: step.finishReason,
-                    })),
-                    usage: result.usage,
-                    providerMetadata: result.experimental_providerMetadata ||
-                        result.providerMetadata,
-                });
+                        toolNames: Object.keys(tools || {}),
+                        toolCount,
+                        maxSteps: options.maxSteps,
+                        temperature: options.temperature,
+                        maxTokens: options.maxTokens,
+                    });
+                }
+                catch {
+                    // Ignore serialization errors in debug logging
+                }
             }
-            return result;
-        }
-        catch (error) {
-            // If NoObjectGeneratedError is thrown when using schema + tools together,
-            // fall back to generating without experimental_output and extract JSON manually
-            if (error instanceof NoObjectGeneratedError && useStructuredOutput) {
-                logger.debug("[GenerationHandler] NoObjectGeneratedError caught - falling back to manual JSON extraction", {
-                    provider: this.providerName,
-                    model: this.modelName,
-                    error: error.message,
-                });
-                // Retry without experimental_output - the formatEnhancedResult method
-                // will extract JSON from the text response
-                const result = await this.callGenerateText(model, messages, tools, options, shouldUseTools, false);
-                logger.info("[GenerationHandler] generateText returned (fallback)", {
+            const genStartTime = Date.now();
+            try {
+                const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, true), span, "generateText");
+                logger.info("[GenerationHandler] generateText returned", {
                     requestId,
                     durationMs: Date.now() - genStartTime,
                     finishReason: result.finishReason,
@@ -262,11 +223,107 @@ export class GenerationHandler {
                     toolCallsTotal: result.toolCalls?.length || 0,
                     responseChars: result.text?.length || 0,
                 });
+                if (logger.shouldLog("debug")) {
+                    logger.debug("[Observability] LLM response metadata", {
+                        requestId,
+                        responseLength: result.text?.length || 0,
+                        hasToolCalls: !!(result.toolCalls && result.toolCalls.length > 0),
+                        toolCallCount: result.toolCalls?.length || 0,
+                        toolNames: result.toolCalls?.map((tc) => tc.toolName),
+                        finishReason: result.finishReason,
+                        stepCount: result.steps?.length || 0,
+                        steps: result.steps?.map((step, i) => ({
+                            stepIndex: i,
+                            stepType: step.stepType,
+                            textLength: step.text?.length || 0,
+                            toolCallCount: step.toolCalls?.length || 0,
+                            toolNames: step.toolCalls?.map((tc) => tc.toolName),
+                            toolResultCount: step.toolResults?.length || 0,
+                            finishReason: step.finishReason,
+                        })),
+                        usage: result.usage,
+                    });
+                }
+                // Set token usage and completion attributes on span
+                if (result.usage) {
+                    span.setAttribute("gen_ai.usage.input_tokens", result.usage.promptTokens || 0);
+                    span.setAttribute("gen_ai.usage.output_tokens", result.usage.completionTokens || 0);
+                    // Cost on span so users can query "what did this trace cost?"
+                    const cost = calculateCost(this.providerName, this.modelName, {
+                        input: result.usage.promptTokens || 0,
+                        output: result.usage.completionTokens || 0,
+                        total: (result.usage.promptTokens || 0) +
+                            (result.usage.completionTokens || 0),
+                    });
+                    span.setAttribute("neurolink.cost", cost ?? 0);
+                }
+                if (result.finishReason) {
+                    span.setAttribute("gen_ai.response.finish_reason", result.finishReason);
+                }
+                span.setStatus({ code: SpanStatusCode.OK });
                 return result;
             }
-            // Re-throw other errors
-            throw error;
-        }
+            catch (error) {
+                // If NoObjectGeneratedError is thrown when using schema + tools together,
+                // fall back to generating without experimental_output and extract JSON manually
+                if (error instanceof NoObjectGeneratedError && useStructuredOutput) {
+                    span.setAttribute("neurolink.has_fallback", true);
+                    // NLK-GAP-007: Record initial failure event before fallback retry
+                    span.addEvent("retry.initial_failure", {
+                        "error.message": error.message,
+                        "retry.attempt": 1,
+                        "retry.reason": "NoObjectGeneratedError_structured_output_fallback",
+                    });
+                    logger.debug("[GenerationHandler] NoObjectGeneratedError caught - falling back to manual JSON extraction", {
+                        provider: this.providerName,
+                        model: this.modelName,
+                        error: error.message,
+                    });
+                    // Retry without experimental_output - the formatEnhancedResult method
+                    // will extract JSON from the text response
+                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, false), span, "generateText(fallback)");
+                    // NLK-GAP-007: Record recovery event after successful fallback
+                    span.addEvent("retry.recovered", {
+                        "retry.attempts": 2,
+                        "retry.strategy": "structured_output_disabled",
+                    });
+                    span.setAttribute("retry.count", 1);
+                    logger.info("[GenerationHandler] generateText returned (fallback)", {
+                        requestId,
+                        durationMs: Date.now() - genStartTime,
+                        finishReason: result.finishReason,
+                        steps: result.steps?.length || 1,
+                        toolCallsTotal: result.toolCalls?.length || 0,
+                        responseChars: result.text?.length || 0,
+                    });
+                    if (result.usage) {
+                        span.setAttribute("gen_ai.usage.input_tokens", result.usage.promptTokens || 0);
+                        span.setAttribute("gen_ai.usage.output_tokens", result.usage.completionTokens || 0);
+                        const fallbackCost = calculateCost(this.providerName, this.modelName, {
+                            input: result.usage.promptTokens || 0,
+                            output: result.usage.completionTokens || 0,
+                            total: (result.usage.promptTokens || 0) +
+                                (result.usage.completionTokens || 0),
+                        });
+                        span.setAttribute("neurolink.cost", fallbackCost ?? 0);
+                    }
+                    if (result.finishReason) {
+                        span.setAttribute("gen_ai.response.finish_reason", result.finishReason);
+                    }
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return result;
+                }
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                // Re-throw other errors
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /**
      * Extract cache metrics from provider metadata (e.g. Anthropic's providerMetadata.anthropic)
@@ -297,21 +354,23 @@ export class GenerationHandler {
      */
     logGenerationComplete(generateResult) {
         const cacheMetrics = this.extractCacheMetricsFromProviderMetadata(generateResult);
-        logger.debug(`generateText completed`, {
-            provider: this.providerName,
-            model: this.modelName,
-            responseLength: generateResult.text?.length || 0,
-            toolResultsCount: generateResult.toolResults?.length || 0,
-            finishReason: generateResult.finishReason,
-            usage: generateResult.usage,
-            ...(cacheMetrics.cacheCreationTokens !== undefined && {
-                cacheCreationTokens: cacheMetrics.cacheCreationTokens,
-            }),
-            ...(cacheMetrics.cacheReadTokens !== undefined && {
-                cacheReadTokens: cacheMetrics.cacheReadTokens,
-            }),
-            timestamp: Date.now(),
-        });
+        if (logger.shouldLog("debug")) {
+            logger.debug(`generateText completed`, {
+                provider: this.providerName,
+                model: this.modelName,
+                responseLength: generateResult.text?.length || 0,
+                toolResultsCount: generateResult.toolResults?.length || 0,
+                finishReason: generateResult.finishReason,
+                usage: generateResult.usage,
+                ...(cacheMetrics.cacheCreationTokens !== undefined && {
+                    cacheCreationTokens: cacheMetrics.cacheCreationTokens,
+                }),
+                ...(cacheMetrics.cacheReadTokens !== undefined && {
+                    cacheReadTokens: cacheMetrics.cacheReadTokens,
+                }),
+                timestamp: Date.now(),
+            });
+        }
     }
     /**
      * Extract tool information from generation result