@juspay/neurolink 9.32.0 → 9.33.0

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

@@ -1,273 +0,0 @@
-/**
- * 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

@@ -1,185 +0,0 @@
-/**
- * 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

@@ -1,203 +0,0 @@
-/**
- * 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);
-        }
-    }
-}