@juspay/neurolink 8.3.0 → 8.4.1

package/dist/core/modules/StreamHandler.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { 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";
+/**
+ * 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 validation = validateStreamOpts(options);
+        if (!validation.isValid) {
+            const summary = createValidationSummary(validation);
+            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);
+        }
+        // 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`,
+                ]);
+            }
+        }
+    }
+    /**
+     * Create text stream transformation - consolidates identical logic from 7/10 providers
+     */
+    createTextStream(result) {
+        return (async function* () {
+            for await (const chunk of result.textStream) {
+                yield { content: chunk };
+            }
+        })();
+    }
+    /**
+     * 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) {
+        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;
+        }
+    }
+    /**
+     * 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/core/modules/TelemetryHandler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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 type { AIProviderName, EnhancedGenerateResult, TextGenerationOptions, AnalyticsData } from "../../types/index.js";
+import type { EvaluationData } from "../../types/index.js";
+import type { StreamOptions } from "../../types/streamTypes.js";
+import type { NeuroLink } from "../../neurolink.js";
+/**
+ * TelemetryHandler class - Handles analytics and telemetry for AI providers
+ */
+export declare class TelemetryHandler {
+    private readonly providerName;
+    private readonly modelName;
+    private readonly neurolink?;
+    constructor(providerName: AIProviderName, modelName: string, neurolink?: NeuroLink | undefined);
+    /**
+     * Create analytics for a generation result
+     */
+    createAnalytics(result: EnhancedGenerateResult, responseTime: number, context?: Record<string, unknown>): Promise<AnalyticsData>;
+    /**
+     * Create evaluation for a generation result
+     */
+    createEvaluation(result: EnhancedGenerateResult, options: TextGenerationOptions): Promise<EvaluationData>;
+    /**
+     * Record performance metrics for a generation
+     */
+    recordPerformanceMetrics(usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | undefined, responseTime: number): Promise<void>;
+    /**
+     * Calculate actual cost based on token usage and provider configuration
+     */
+    calculateActualCost(usage: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    }): Promise<number>;
+    /**
+     * Get telemetry configuration for streaming/generation
+     */
+    getStreamTelemetryConfig(options: StreamOptions | TextGenerationOptions, operationType?: "stream" | "generate"): {
+        isEnabled: boolean;
+        functionId?: string;
+        metadata?: Record<string, string | number | boolean>;
+    } | undefined;
+    /**
+     * Handle tool execution storage if available
+     */
+    handleToolExecutionStorage(toolCalls: unknown[], toolResults: unknown[], options: TextGenerationOptions | StreamOptions, currentTime: Date): Promise<void>;
+}

package/dist/core/modules/TelemetryHandler.js

@@ -0,0 +1,170 @@
+/**
+ * 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 { logger } from "../../utils/logger.js";
+import { nanoid } from "nanoid";
+import { modelConfig } from "../modelConfiguration.js";
+import { recordProviderPerformanceFromMetrics, getPerformanceOptimizedProvider, } from "../evaluationProviders.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 actualCost = await this.calculateActualCost(usage || { promptTokens: 0, completionTokens: 0, totalTokens: 0 });
+            recordProviderPerformanceFromMetrics(this.providerName, {
+                responseTime,
+                tokensGenerated: usage?.totalTokens || 0,
+                cost: actualCost,
+                success: true,
+            });
+            const optimizedProvider = getPerformanceOptimizedProvider("speed");
+            logger.debug(`🚀 Performance recorded for ${this.providerName}:`, {
+                responseTime: `${responseTime}ms`,
+                tokens: usage?.totalTokens || 0,
+                estimatedCost: `$${actualCost.toFixed(6)}`,
+                recommendedSpeedProvider: optimizedProvider?.provider || "none",
+            });
+        }
+        catch (perfError) {
+            logger.warn("⚠️ Performance recording failed:", perfError);
+        }
+    }
+    /**
+     * Calculate actual cost based on token usage and provider configuration
+     */
+    async calculateActualCost(usage) {
+        try {
+            const costInfo = modelConfig.getCostInfo(this.providerName, this.modelName);
+            if (!costInfo) {
+                return 0; // No cost info available
+            }
+            const promptTokens = usage?.promptTokens || 0;
+            const completionTokens = usage?.completionTokens || 0;
+            // 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
+        }
+    }
+    /**
+     * Get telemetry configuration for streaming/generation
+     */
+    getStreamTelemetryConfig(options, operationType = "stream") {
+        // Check if telemetry is enabled via NeuroLink observability config
+        if (!this.neurolink?.isTelemetryEnabled()) {
+            return undefined;
+        }
+        const functionId = `${this.providerName}-${operationType}-${nanoid()}`;
+        const metadata = {
+            provider: this.providerName,
+            model: this.modelName,
+            toolsEnabled: !options.disableTools,
+            neurolink: true,
+        };
+        // 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,
+        };
+    }
+    /**
+     * 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);
+        }
+    }
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Tools Manager Module
+ *
+ * Handles all tool registration, discovery, and execution for AI providers.
+ * Extracted from BaseProvider to follow Single Responsibility Principle.
+ *
+ * Responsibilities:
+ * - Tool registration (direct, custom, MCP, external MCP)
+ * - Tool discovery and aggregation
+ * - Tool creation from definitions and schemas
+ * - Tool executor setup
+ * - Session context management for MCP tools
+ * - Event emission wrapping for tool execution
+ *
+ * @module core/modules/ToolsManager
+ */
+import type { Tool } from "ai";
+import { z } from "zod";
+import type { AIProviderName } from "../../types/index.js";
+import type { NeuroLink } from "../../neurolink.js";
+/**
+ * Utility functions interface for ToolsManager
+ */
+export interface ToolUtilities {
+    isZodSchema?: (schema: unknown) => boolean;
+    convertToolResult?: (result: unknown) => Promise<unknown>;
+    createPermissiveZodSchema?: () => z.ZodSchema;
+    fixSchemaForOpenAIStrictMode?: (schema: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * ToolsManager class - Handles all tool management operations
+ */
+export declare class ToolsManager {
+    private readonly providerName;
+    private readonly directTools;
+    private readonly neurolink?;
+    private readonly utilities?;
+    protected mcpTools?: Record<string, Tool>;
+    protected customTools?: Map<string, unknown>;
+    protected toolExecutor?: (toolName: string, params: unknown) => Promise<unknown>;
+    protected sessionId?: string;
+    protected userId?: string;
+    constructor(providerName: AIProviderName, directTools: Record<string, unknown>, neurolink?: NeuroLink | undefined, utilities?: ToolUtilities | undefined);
+    /**
+     * Set session context for MCP tools
+     */
+    setSessionContext(sessionId?: string, userId?: string): void;
+    /**
+     * Set up tool executor for a provider to enable actual tool execution
+     * @param sdk - The NeuroLinkSDK instance for tool execution
+     * @param functionTag - Function name for logging
+     */
+    setupToolExecutor(sdk: {
+        customTools: Map<string, unknown>;
+        executeTool: (toolName: string, params: unknown) => Promise<unknown>;
+    }, functionTag: string): void;
+    /**
+     * Get all available tools - direct tools are ALWAYS available
+     * MCP tools are added when available (without blocking)
+     */
+    getAllTools(): Promise<Record<string, Tool>>;
+    /**
+     * Get direct tools (built-in agent tools)
+     */
+    getDirectTools(): Record<string, unknown>;
+    /**
+     * Get MCP tools
+     */
+    getMCPTools(): Record<string, Tool> | undefined;
+    /**
+     * Get custom tools
+     */
+    getCustomTools(): Map<string, unknown> | undefined;
+    /**
+     * Process direct tools with event emission wrapping
+     */
+    private processDirectTools;
+    /**
+     * Process custom tools from setupToolExecutor
+     */
+    private processCustomTools;
+    /**
+     * Process MCP tools integration
+     */
+    private processMCPTools;
+    /**
+     * Process external MCP tools
+     */
+    private processExternalMCPTools;
+    /**
+     * Create a custom tool from tool definition
+     */
+    private createCustomToolFromDefinition;
+    /**
+     * Create an external MCP tool
+     */
+    private createExternalMCPTool;
+}