@juspay/neurolink 9.23.0 → 9.25.0

package/dist/lib/core/baseProvider.js

@@ -1,9 +1,12 @@
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { generateText } from "ai";
-import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
-import { tracers } from "../telemetry/tracers.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
+import { getMetricsAggregator } from "../observability/metricsAggregator.js";
+import { SpanStatus, SpanType } from "../observability/types/spanTypes.js";
+import { SpanSerializer } from "../observability/utils/spanSerializer.js";
+import { ATTR, tracers } from "../telemetry/index.js";
 import { isAbortError } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
 import { calculateCost } from "../utils/pricing.js";
@@ -11,7 +14,7 @@ import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
-import { hasVideoFrames, executeVideoAnalysis, } from "../utils/videoAnalysisProcessor.js";
+import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -19,7 +22,6 @@ import { StreamHandler } from "./modules/StreamHandler.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import { ToolsManager } from "./modules/ToolsManager.js";
 import { Utilities } from "./modules/Utilities.js";
-const providerTracer = tracers.provider;
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -39,6 +41,8 @@ export class BaseProvider {
     sessionId;
     userId;
     neurolink; // Reference to actual NeuroLink instance for MCP tools
+    /** Trace context propagated from NeuroLink SDK for span hierarchy */
+    _traceContext = null;
     // Composition modules - Single Responsibility Principle
     messageBuilder;
     streamHandler;
@@ -80,10 +84,26 @@ export class BaseProvider {
      * When tools are involved, falls back to generate() with synthetic streaming
      */
     async stream(optionsOrPrompt, analysisSchema) {
-        return providerTracer.startActiveSpan("neurolink.provider.stream", { kind: SpanKind.INTERNAL }, async (span) => {
-            let options = this.normalizeStreamOptions(optionsOrPrompt);
-            span.setAttribute("gen_ai.system", this.providerName || "unknown");
-            span.setAttribute("gen_ai.request.model", this.modelName || options.model || "unknown");
+        let options = this.normalizeStreamOptions(optionsOrPrompt);
+        // Observability: create metrics span for provider.stream
+        const metricsSpan = SpanSerializer.createSpan(SpanType.MODEL_GENERATION, "provider.stream", {
+            "ai.provider": this.providerName || "unknown",
+            "ai.model": this.modelName || options.model || "unknown",
+            "ai.temperature": options.temperature,
+            "ai.max_tokens": options.maxTokens,
+        }, this._traceContext?.parentSpanId, this._traceContext?.traceId);
+        let metricsSpanRecorded = false;
+        // OTEL span for provider-level stream tracing
+        const otelStreamSpan = tracers.provider.startSpan("neurolink.provider.stream", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
+                [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
+                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_PROVIDER]: this.providerName || "unknown",
+            },
+        });
+        try {
             logger.info(`Starting stream`, {
                 provider: this.providerName,
                 hasTools: !options.disableTools && this.supportsTools(),
@@ -94,93 +114,97 @@ export class BaseProvider {
                 temperature: options.temperature,
                 timestamp: Date.now(),
             });
-            try {
-                // ===== EARLY MULTIMODAL DETECTION =====
-                const hasFileInput = !!options.input?.files?.length ||
-                    !!options.input?.videoFiles?.length;
-                if (hasFileInput) {
-                    // ===== VIDEO ANALYSIS DETECTION =====
-                    // Check if video frames are present and handle with fake streaming
-                    const messages = await this.buildMessagesForStream(options);
-                    if (hasVideoFrames(messages)) {
-                        logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
-                            provider: this.providerName,
-                            model: this.modelName,
-                        });
-                        span.setAttribute("neurolink.stream_mode", "fake");
-                        return await this.executeFakeStreaming(options, analysisSchema);
-                    }
-                }
-                // Image generation models don't support real streaming
-                // Force fake streaming for image models to ensure image output is yielded
-                const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
-                if (isImageModel) {
-                    logger.info(`Image model detected, forcing fake streaming`, {
+            // ===== EARLY MULTIMODAL DETECTION =====
+            const hasFileInput = !!options.input?.files?.length || !!options.input?.videoFiles?.length;
+            if (hasFileInput) {
+                // ===== VIDEO ANALYSIS DETECTION =====
+                // Check if video frames are present and handle with fake streaming
+                const messages = await this.buildMessagesForStream(options);
+                if (hasVideoFrames(messages)) {
+                    logger.info(`Video frames detected in stream, using fake streaming for video analysis`, {
                         provider: this.providerName,
                         model: this.modelName,
-                        reason: "Image generation requires fake streaming to yield image output",
                     });
-                    // Skip real streaming, go directly to fake streaming
-                    span.setAttribute("neurolink.stream_mode", "fake");
                     return await this.executeFakeStreaming(options, analysisSchema);
                 }
-                // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
-                // tools (e.g. RAG tools) into options.tools. This way, every provider's
-                // executeStream() can simply use options.tools (or getAllTools() + options.tools)
-                // and get the complete tool set without needing per-provider merge logic.
+            }
+            // CRITICAL: Image generation models don't support real streaming
+            // Force fake streaming for image models to ensure image output is yielded
+            const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
+            if (isImageModel) {
+                logger.info(`Image model detected, forcing fake streaming`, {
+                    provider: this.providerName,
+                    model: this.modelName,
+                    reason: "Image generation requires fake streaming to yield image output",
+                });
+                // Skip real streaming, go directly to fake streaming
+                return await this.executeFakeStreaming(options, analysisSchema);
+            }
+            // Central tool merge: Pre-merge base tools (MCP/built-in) with user-provided
+            // tools (e.g. RAG tools) into options.tools. This way, every provider's
+            // executeStream() can simply use options.tools (or getAllTools() + options.tools)
+            // and get the complete tool set without needing per-provider merge logic.
+            if (!options.disableTools && this.supportsTools()) {
+                const mergedTools = await this.getToolsForStream(options);
+                options = { ...options, tools: mergedTools };
+            }
+            else {
+                options = { ...options, tools: {} };
+            }
+            // CRITICAL FIX: Always prefer real streaming over fake streaming
+            // Try real streaming first, use fake streaming only as fallback
+            try {
+                logger.debug(`Attempting real streaming`, {
+                    provider: this.providerName,
+                    timestamp: Date.now(),
+                });
+                const realStreamResult = await this.executeStream(options, analysisSchema);
+                logger.info(`Real streaming succeeded`, {
+                    provider: this.providerName,
+                    timestamp: Date.now(),
+                });
+                // If real streaming succeeds, return it (with tools support via Vercel AI SDK)
+                return realStreamResult;
+            }
+            catch (realStreamError) {
+                logger.warn(`Real streaming failed for ${this.providerName}, falling back to fake streaming:`, {
+                    error: realStreamError instanceof Error
+                        ? realStreamError.message
+                        : String(realStreamError),
+                    timestamp: Date.now(),
+                });
+                // Fallback to fake streaming only if real streaming fails AND tools are enabled
                 if (!options.disableTools && this.supportsTools()) {
-                    const mergedTools = await this.getToolsForStream(options);
-                    options = { ...options, tools: mergedTools };
+                    return await this.executeFakeStreaming(options, analysisSchema);
                 }
                 else {
-                    options = { ...options, tools: {} };
+                    // If real streaming failed and no tools are enabled, re-throw the original error
+                    logger.error(`Real streaming failed for ${this.providerName}:`, realStreamError);
+                    throw this.handleProviderError(realStreamError);
                 }
-                // CRITICAL FIX: Always prefer real streaming over fake streaming
-                // Try real streaming first, use fake streaming only as fallback
-                try {
-                    logger.debug(`Attempting real streaming`, {
-                        provider: this.providerName,
-                        timestamp: Date.now(),
-                    });
-                    const realStreamResult = await this.executeStream(options, analysisSchema);
-                    logger.info(`Real streaming succeeded`, {
-                        provider: this.providerName,
-                        timestamp: Date.now(),
-                    });
-                    span.setAttribute("neurolink.stream_mode", "real");
-                    // If real streaming succeeds, return it (with tools support via Vercel AI SDK)
-                    return realStreamResult;
-                }
-                catch (realStreamError) {
-                    logger.warn(`Real streaming failed for ${this.providerName}, falling back to fake streaming:`, {
-                        error: realStreamError instanceof Error
-                            ? realStreamError.message
-                            : String(realStreamError),
-                        timestamp: Date.now(),
-                    });
-                    // Fallback to fake streaming only if real streaming fails AND tools are enabled
-                    if (!options.disableTools && this.supportsTools()) {
-                        span.setAttribute("neurolink.stream_mode", "fake");
-                        return await this.executeFakeStreaming(options, analysisSchema);
-                    }
-                    else {
-                        // If real streaming failed and no tools are enabled, re-throw the original error
-                        logger.error(`Real streaming failed for ${this.providerName}:`, realStreamError);
-                        throw this.handleProviderError(realStreamError);
-                    }
-                }
-            }
-            catch (error) {
-                span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-                throw error;
             }
-            finally {
-                span.end();
+        }
+        catch (error) {
+            // Observability: record failed stream span
+            metricsSpanRecorded = true;
+            const endedStreamSpan = SpanSerializer.endSpan(metricsSpan, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
+            getMetricsAggregator().recordSpan(endedStreamSpan);
+            otelStreamSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            otelStreamSpan.end();
+            throw error;
+        }
+        finally {
+            // Observability: record successful stream span (only if not already ended via error path)
+            if (!metricsSpanRecorded) {
+                const endedStreamSpan = SpanSerializer.endSpan(metricsSpan, SpanStatus.OK);
+                getMetricsAggregator().recordSpan(endedStreamSpan);
+                otelStreamSpan.setStatus({ code: SpanStatusCode.OK });
+                otelStreamSpan.end();
             }
-        });
+        }
     }
     /**
      * Execute fake streaming - extracted method for reusability
@@ -468,12 +492,31 @@ export class BaseProvider {
      * for consistency and better performance
      */
     async generate(optionsOrPrompt, _analysisSchema) {
-        return providerTracer.startActiveSpan("neurolink.provider.generate", { kind: SpanKind.INTERNAL }, async (span) => {
-            const options = this.normalizeTextOptions(optionsOrPrompt);
-            this.validateOptions(options);
-            const startTime = Date.now();
-            span.setAttribute("gen_ai.system", this.providerName || "unknown");
-            span.setAttribute("gen_ai.request.model", this.modelName || options.model || "unknown");
+        const options = this.normalizeTextOptions(optionsOrPrompt);
+        this.validateOptions(options);
+        const startTime = Date.now();
+        // Observability: create metrics span for provider.generate
+        const metricsSpan = SpanSerializer.createSpan(SpanType.MODEL_GENERATION, "provider.generate", {
+            "ai.provider": this.providerName || "unknown",
+            "ai.model": this.modelName || options.model || "unknown",
+            "ai.temperature": options.temperature,
+            "ai.max_tokens": options.maxTokens,
+        }, this._traceContext?.parentSpanId, this._traceContext?.traceId);
+        // OTEL span for provider-level generate tracing
+        // Use startActiveSpan pattern via context.with() so child spans become descendants
+        const otelSpan = tracers.provider.startSpan("neurolink.provider.generate", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
+                [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
+                [ATTR.GEN_AI_OPERATION]: "generate",
+                [ATTR.NL_PROVIDER]: this.providerName || "unknown",
+            },
+        });
+        // Set this span as the active context so child spans (GenerationHandler, etc.) become descendants
+        const activeCtx = trace.setSpan(context.active(), otelSpan);
+        let otelSpanEnded = false;
+        return await context.with(activeCtx, async () => {
             try {
                 // ===== VIDEO GENERATION MODE =====
                 // Generate video from image + prompt using Veo 3.1
@@ -647,29 +690,39 @@ export class BaseProvider {
                         });
                     }
                 }
-                // Set token usage on span from the result
+                // Observability: record successful generate span with token/cost data
+                let enrichedGenerateSpan = { ...metricsSpan };
                 if (enhancedResult?.usage) {
-                    span.setAttribute("gen_ai.usage.input_tokens", enhancedResult.usage.input || 0);
-                    span.setAttribute("gen_ai.usage.output_tokens", enhancedResult.usage.output || 0);
-                    // Cost on span so users can query "what did this trace cost?"
+                    enrichedGenerateSpan = SpanSerializer.enrichWithTokenUsage(enrichedGenerateSpan, {
+                        promptTokens: enhancedResult.usage.input || 0,
+                        completionTokens: enhancedResult.usage.output || 0,
+                        totalTokens: enhancedResult.usage.total || 0,
+                    });
                     const cost = calculateCost(this.providerName, this.modelName, {
                         input: enhancedResult.usage.input || 0,
                         output: enhancedResult.usage.output || 0,
                         total: enhancedResult.usage.total || 0,
                     });
-                    span.setAttribute("neurolink.cost", cost ?? 0);
-                }
-                if (enhancedResult?.finishReason) {
-                    span.setAttribute("gen_ai.response.finish_reason", enhancedResult.finishReason);
+                    if (cost && cost > 0) {
+                        enrichedGenerateSpan = SpanSerializer.enrichWithCost(enrichedGenerateSpan, {
+                            totalCost: cost,
+                        });
+                    }
                 }
-                span.setStatus({ code: SpanStatusCode.OK });
+                const endedGenerateSpan = SpanSerializer.endSpan(enrichedGenerateSpan, SpanStatus.OK);
+                getMetricsAggregator().recordSpan(endedGenerateSpan);
                 return await this.enhanceResult(enhancedResult, options, startTime);
             }
             catch (error) {
-                span.setStatus({
+                // Observability: record failed generate span
+                const endedGenerateSpan = SpanSerializer.endSpan(metricsSpan, SpanStatus.ERROR, error instanceof Error ? error.message : String(error));
+                getMetricsAggregator().recordSpan(endedGenerateSpan);
+                otelSpan.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: error instanceof Error ? error.message : String(error),
                 });
+                otelSpan.end();
+                otelSpanEnded = true;
                 // Abort errors are expected when a generation is cancelled — log at info, not error
                 if (isAbortError(error)) {
                     logger.info(`Generate aborted for ${this.providerName}`, {
@@ -682,9 +735,12 @@ export class BaseProvider {
                 throw this.handleProviderError(error);
             }
             finally {
-                span.end();
+                if (!otelSpanEnded) {
+                    otelSpan.setStatus({ code: SpanStatusCode.OK });
+                    otelSpan.end();
+                }
             }
-        });
+        }); // end context.with
     }
     /**
      * Alias for generate method - implements AIProvider interface

package/dist/lib/core/conversationMemoryInitializer.js

@@ -2,9 +2,9 @@
  * Conversation Memory Initializer
  * Provides integration with Redis storage for conversation memory
  */
-import { createConversationMemoryManager, getStorageType, getRedisConfigFromEnv, } from "./conversationMemoryFactory.js";
 import { applyConversationMemoryDefaults } from "../utils/conversationMemory.js";
 import { logger } from "../utils/logger.js";
+import { createConversationMemoryManager, getRedisConfigFromEnv, getStorageType, } from "./conversationMemoryFactory.js";
 /**
  * Initialize conversation memory for NeuroLink
  * This function decides whether to use in-memory or Redis storage
@@ -30,11 +30,14 @@ export async function initializeConversationMemory(config) {
             maxTurnsPerSession: memoryConfig.maxTurnsPerSession,
             enableSummarization: memoryConfig.enableSummarization,
         });
-        // Determine storage type from environment
-        const storageType = getStorageType();
+        // Determine storage type: if redisConfig is passed in the SDK config, use Redis
+        // regardless of STORAGE_TYPE env var. This lets consumers configure Redis via the API.
+        const hasRedisConfig = !!config.conversationMemory?.redisConfig;
+        const storageType = hasRedisConfig ? "redis" : getStorageType();
         logger.debug("[conversationMemoryInitializer] Storage type determined", {
             storageType,
-            fromEnv: !!process.env.STORAGE_TYPE,
+            fromConfig: hasRedisConfig,
+            fromEnv: !hasRedisConfig && !!process.env.STORAGE_TYPE,
         });
         if (storageType === "redis") {
             logger.info("[conversationMemoryInitializer] Initializing Redis-based conversation memory manager");

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

@@ -71,4 +71,6 @@ export declare class ConversationMemoryManager implements IConversationMemoryMan
      * Resets summary pointers since old pointers may reference messages that no longer exist.
      */
     setSessionMessages(sessionId: string, messages: ChatMessage[], userId?: string): Promise<void>;
+    /** Close/shutdown — no-op for in-memory manager (no external connections to release) */
+    close(): Promise<void>;
 }

package/dist/lib/core/conversationMemoryManager.js

@@ -6,11 +6,11 @@ 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 { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
 import { logger } from "../utils/logger.js";
-import { tracers, withSpan } from "../telemetry/index.js";
 export class ConversationMemoryManager {
     sessions = new Map();
     config;
@@ -337,5 +337,9 @@ export class ConversationMemoryManager {
         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
+    }
 }
 //# sourceMappingURL=conversationMemoryManager.js.map

package/dist/lib/core/modules/GenerationHandler.d.ts

@@ -12,9 +12,9 @@
  *
  * @module core/modules/GenerationHandler
  */
-import type { LanguageModelV1, CoreMessage, Tool } from "ai";
+import type { CoreMessage, LanguageModelV1, Tool } from "ai";
 import { generateText } from "ai";
-import type { TextGenerationOptions, EnhancedGenerateResult, AIProviderName, StandardRecord } from "../../types/index.js";
+import type { AIProviderName, EnhancedGenerateResult, StandardRecord, TextGenerationOptions } from "../../types/index.js";
 /**
  * GenerationHandler class - Handles text generation operations for AI providers
  */

package/dist/lib/core/modules/GenerationHandler.js

@@ -12,13 +12,13 @@
  *
  * @module core/modules/GenerationHandler
  */
-import { generateText, Output, NoObjectGeneratedError } from "ai";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { generateText, NoObjectGeneratedError, Output } from "ai";
 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 { withProviderRetry } from "../../utils/providerRetry.js";
+import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
 import { DEFAULT_MAX_STEPS } from "../constants.js";
 const genTracer = tracers.generation;
 /**
@@ -67,8 +67,8 @@ export class GenerationHandler {
         // 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.schema ||
+                options.output?.format === "json" ||
                 options.output?.format === "structured");
         const useStructuredOutput = wantsStructuredOutput &&
             !(isGoogleProvider && shouldUseTools && Object.keys(tools).length > 0);
@@ -166,9 +166,9 @@ export class GenerationHandler {
         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");
+            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);
@@ -452,10 +452,10 @@ export class GenerationHandler {
      * Format the enhanced result
      */
     formatEnhancedResult(generateResult, tools, toolsUsed, toolExecutions, options) {
-        // Structured output check
-        const useStructuredOutput = !!options.schema &&
-            (options.output?.format === "json" ||
-                options.output?.format === "structured");
+        // Structured output check — schema alone is sufficient to activate
+        const useStructuredOutput = !!options.schema ||
+            options.output?.format === "json" ||
+            options.output?.format === "structured";
         let content;
         if (useStructuredOutput) {
             try {

package/dist/lib/evaluation/ragasEvaluator.js

@@ -1,6 +1,8 @@
 import { AIProviderFactory } from "../core/factory.js";
 import { PromptBuilder } from "./prompts.js";
 import { logger } from "../utils/logger.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Implements a RAGAS-style evaluator that uses a "judge" LLM to score the
  * quality of an AI response based on rich, contextual information.
@@ -32,27 +34,45 @@ export class RAGASEvaluator {
      * @returns A promise that resolves to a detailed `EvaluationResult`.
      */
     async evaluate(context) {
-        const startTime = Date.now();
-        const prompt = this.promptBuilder.buildEvaluationPrompt(context, this.promptGenerator);
-        const provider = await AIProviderFactory.createProvider(this.providerName, this.evaluationModel);
-        const result = await provider.generate({
-            input: { text: prompt },
+        const span = SpanSerializer.createSpan(SpanType.EVALUATION, "evaluation.ragas", {
+            "evaluation.dimension": "relevance|accuracy|completeness",
+            "ai.provider": this.providerName,
+            "ai.model": this.evaluationModel,
         });
-        if (!result) {
-            throw new Error("Evaluation generation failed to return a result.");
+        const startTime = Date.now();
+        try {
+            const prompt = this.promptBuilder.buildEvaluationPrompt(context, this.promptGenerator);
+            const provider = await AIProviderFactory.createProvider(this.providerName, this.evaluationModel);
+            const result = await provider.generate({
+                input: { text: prompt },
+            });
+            if (!result) {
+                throw new Error("Evaluation generation failed to return a result.");
+            }
+            const rawEvaluationResponse = result.content;
+            const parsedResult = this.parseEvaluationResponse(rawEvaluationResponse);
+            const evaluationTime = Date.now() - startTime;
+            const finalResult = {
+                ...parsedResult,
+                isPassing: parsedResult.finalScore >= this.threshold, // This will be recalculated, but is needed for the type
+                evaluationModel: this.evaluationModel,
+                evaluationTime,
+                attemptNumber: context.attemptNumber,
+                rawEvaluationResponse,
+            };
+            span.durationMs = Date.now() - startTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+            return finalResult;
+        }
+        catch (error) {
+            span.durationMs = Date.now() - startTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+            endedSpan.statusMessage =
+                error instanceof Error ? error.message : String(error);
+            getMetricsAggregator().recordSpan(endedSpan);
+            throw error;
         }
-        const rawEvaluationResponse = result.content;
-        const parsedResult = this.parseEvaluationResponse(rawEvaluationResponse);
-        const evaluationTime = Date.now() - startTime;
-        const finalResult = {
-            ...parsedResult,
-            isPassing: parsedResult.finalScore >= this.threshold, // This will be recalculated, but is needed for the type
-            evaluationModel: this.evaluationModel,
-            evaluationTime,
-            attemptNumber: context.attemptNumber,
-            rawEvaluationResponse,
-        };
-        return finalResult;
     }
     /**
      * Parses the raw JSON string from the judge LLM into a structured `EvaluationResult` object.

package/dist/lib/evaluation/scoring.js

@@ -1,6 +1,8 @@
 /**
  * @file Contains the logic for mapping raw evaluation results to the structured EvaluationData type.
  */
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
 /**
  * Maps a raw `EvaluationResult` to the structured `EvaluationData` format.
  * This includes calculating derived fields like `isOffTopic` and `alertSeverity`.
@@ -12,25 +14,49 @@
  * @returns A structured `EvaluationData` object.
  */
 export function mapToEvaluationData(evalContext, result, threshold, offTopicThreshold = 5, highSeverityThreshold = 4) {
-    const isPassing = result.finalScore >= threshold;
-    return {
-        relevance: result.relevanceScore,
-        accuracy: result.accuracyScore,
-        completeness: result.completenessScore,
-        overall: result.finalScore,
-        isOffTopic: result.finalScore < offTopicThreshold,
-        alertSeverity: isPassing
-            ? "none"
-            : result.finalScore < highSeverityThreshold
-                ? "high"
-                : "medium",
-        reasoning: result.reasoning,
-        suggestedImprovements: result.suggestedImprovements,
-        evaluationModel: result.evaluationModel,
-        evaluationTime: result.evaluationTime,
-        evaluationAttempt: result.attemptNumber,
-        responseContent: evalContext.aiResponse,
-        queryContent: evalContext.userQuery,
-    };
+    const span = SpanSerializer.createSpan(SpanType.EVALUATION, "evaluation.score", {
+        "evaluation.dimension": "relevance|accuracy|completeness|overall",
+        scores: {
+            relevance: result.relevanceScore,
+            accuracy: result.accuracyScore,
+            completeness: result.completenessScore,
+            overall: result.finalScore,
+        },
+    });
+    const startTime = Date.now();
+    try {
+        const isPassing = result.finalScore >= threshold;
+        const evaluationData = {
+            relevance: result.relevanceScore,
+            accuracy: result.accuracyScore,
+            completeness: result.completenessScore,
+            overall: result.finalScore,
+            isOffTopic: result.finalScore < offTopicThreshold,
+            alertSeverity: isPassing
+                ? "none"
+                : result.finalScore < highSeverityThreshold
+                    ? "high"
+                    : "medium",
+            reasoning: result.reasoning,
+            suggestedImprovements: result.suggestedImprovements,
+            evaluationModel: result.evaluationModel,
+            evaluationTime: result.evaluationTime,
+            evaluationAttempt: result.attemptNumber,
+            responseContent: evalContext.aiResponse,
+            queryContent: evalContext.userQuery,
+        };
+        span.durationMs = Date.now() - startTime;
+        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
+        getMetricsAggregator().recordSpan(endedSpan);
+        return evaluationData;
+    }
+    catch (error) {
+        span.durationMs = Date.now() - startTime;
+        const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+        endedSpan.statusMessage =
+            error instanceof Error ? error.message : String(error);
+        getMetricsAggregator().recordSpan(endedSpan);
+        throw error;
+    }
 }
 //# sourceMappingURL=scoring.js.map

package/dist/lib/features/ppt/index.d.ts

@@ -22,5 +22,5 @@ export { SlideGenerator, createSlideGenerator, generateSlidesFromPlan, PptxGenJS
 export { generatePresentation } from "./presentationOrchestrator.js";
 export { validatePPTGenerationInput, validatePPTOutputOptions, validatePPTProvider, } from "../../utils/parameterValidation.js";
 export type { EnhancedValidationResult as PPTValidationResult } from "../../types/tools.js";
-export { PPT_VALID_PROVIDERS, getEffectivePPTProvider, generateOutputPath, ensureOutputDirectory, normalizeLogoConfig, getLayoutName, getFailureStage, toError, isObject, isLogoConfig, } from "./utils.js";
+export { PPT_VALID_PROVIDERS, getEffectivePPTProvider, generateOutputPath, ensureOutputDirectory, normalizeLogoConfig, getLayoutName, getFailureStage, toError, isObject, isLogoConfig, validateImageBuffer, } from "./utils.js";
 export type { EffectivePPTProviderResult } from "./types.js";