@juspay/neurolink 7.24.1 → 7.26.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [7.26.0](https://github.com/juspay/neurolink/compare/v7.25.0...v7.26.0) (2025-08-21)
+
+### Features
+
+- **(core):** implement provider performance metrics and optimization system ([caa68e7](https://github.com/juspay/neurolink/commit/caa68e7fd44d5a15dd48605063b093279b6f82ae))
+
+## [7.25.0](https://github.com/juspay/neurolink/compare/v7.24.1...v7.25.0) (2025-08-21)
+
+### Features
+
+- **(middleware):** add custom middleware development guide ([ffd0343](https://github.com/juspay/neurolink/commit/ffd0343a589b267a5b8349a06cdfe2664a942e4c))
+
 ## [7.24.1](https://github.com/juspay/neurolink/compare/v7.24.0...v7.24.1) (2025-08-21)
 
 ## [7.24.0](https://github.com/juspay/neurolink/compare/v7.23.0...v7.24.0) (2025-08-20)

package/dist/core/baseProvider.d.ts

@@ -63,6 +63,19 @@ export declare abstract class BaseProvider implements AIProvider {
      * Returns the Vercel AI SDK model instance for this provider
      */
     protected abstract getAISDKModel(): LanguageModelV1 | Promise<LanguageModelV1>;
+    /**
+     * Get AI SDK model with middleware applied
+     * This method wraps the base model with any configured middleware
+     */
+    protected getAISDKModelWithMiddleware(options?: TextGenerationOptions | StreamOptions): Promise<LanguageModelV1>;
+    /**
+     * Extract middleware options from generation options
+     */
+    private extractMiddlewareOptions;
+    /**
+     * Determine if middleware should be skipped for this request
+     */
+    private shouldSkipMiddleware;
     /**
      * Get all available tools - direct tools are ALWAYS available
      * MCP tools are added when available (without blocking)

package/dist/core/baseProvider.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MiddlewareFactory } from "../middleware/factory.js";
 import { logger } from "../utils/logger.js";
 import { DEFAULT_MAX_STEPS, STEP_LIMITS } from "../core/constants.js";
 import { directAgentTools } from "../agent/directTools.js";
@@ -8,6 +9,8 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
 import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
 import { validateStreamOptions as validateStreamOpts, validateTextGenerationOptions, ValidationError, createValidationSummary, } from "../utils/parameterValidation.js";
+import { recordProviderPerformanceFromMetrics, getPerformanceOptimizedProvider, } from "./evaluationProviders.js";
+import { modelConfig } from "./modelConfiguration.js";
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -181,6 +184,46 @@ export class BaseProvider {
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || 8192,
             });
+            const responseTime = Date.now() - startTime;
+            try {
+                // Calculate actual cost based on token usage and provider configuration
+                const calculateActualCost = () => {
+                    try {
+                        const costInfo = modelConfig.getCostInfo(this.providerName, this.modelName);
+                        if (!costInfo) {
+                            return 0; // No cost info available
+                        }
+                        const promptTokens = result.usage?.promptTokens || 0;
+                        const completionTokens = result.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
+                    }
+                };
+                const actualCost = calculateActualCost();
+                recordProviderPerformanceFromMetrics(this.providerName, {
+                    responseTime,
+                    tokensGenerated: result.usage?.totalTokens || 0,
+                    cost: actualCost,
+                    success: true,
+                });
+                // Show what the system learned (updated to include cost)
+                const optimizedProvider = getPerformanceOptimizedProvider("speed");
+                logger.debug(`🚀 Performance recorded for ${this.providerName}:`, {
+                    responseTime: `${responseTime}ms`,
+                    tokens: result.usage?.totalTokens || 0,
+                    estimatedCost: `$${actualCost.toFixed(6)}`,
+                    recommendedSpeedProvider: optimizedProvider?.provider || "none",
+                });
+            }
+            catch (perfError) {
+                logger.warn("⚠️ Performance recording failed:", perfError);
+            }
             // Extract tool names from tool calls for tracking
             // AI SDK puts tool calls in steps array for multi-step generation
             const toolsUsed = [];
@@ -357,6 +400,83 @@ export class BaseProvider {
             evaluation: result.evaluation,
         };
     }
+    /**
+     * Get AI SDK model with middleware applied
+     * This method wraps the base model with any configured middleware
+     */
+    async getAISDKModelWithMiddleware(options = {}) {
+        // Get the base model
+        const baseModel = await this.getAISDKModel();
+        // Check if middleware should be applied
+        const middlewareOptions = this.extractMiddlewareOptions(options);
+        if (!middlewareOptions || this.shouldSkipMiddleware(options)) {
+            return baseModel;
+        }
+        try {
+            // Create middleware context
+            const context = MiddlewareFactory.createContext(this.providerName, this.modelName, options, {
+                sessionId: this.sessionId,
+                userId: this.userId,
+            });
+            // Apply middleware to the model
+            const wrappedModel = MiddlewareFactory.applyMiddleware(baseModel, context, middlewareOptions);
+            logger.debug(`Applied middleware to ${this.providerName} model`, {
+                provider: this.providerName,
+                model: this.modelName,
+                hasMiddleware: true,
+            });
+            return wrappedModel;
+        }
+        catch (error) {
+            logger.warn(`Failed to apply middleware to ${this.providerName}, using base model`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Return base model on middleware failure to maintain functionality
+            return baseModel;
+        }
+    }
+    /**
+     * Extract middleware options from generation options
+     */
+    extractMiddlewareOptions(options) {
+        // Check for middleware configuration in options
+        const optionsRecord = options;
+        const middlewareConfig = optionsRecord.middlewareConfig;
+        const enabledMiddleware = optionsRecord.enabledMiddleware;
+        const disabledMiddleware = optionsRecord.disabledMiddleware;
+        const preset = optionsRecord.middlewarePreset;
+        // If no middleware configuration is present, return null
+        if (!middlewareConfig &&
+            !enabledMiddleware &&
+            !disabledMiddleware &&
+            !preset) {
+            return null;
+        }
+        return {
+            middlewareConfig,
+            enabledMiddleware,
+            disabledMiddleware,
+            preset,
+            global: {
+                collectStats: true,
+                continueOnError: true,
+            },
+        };
+    }
+    /**
+     * Determine if middleware should be skipped for this request
+     */
+    shouldSkipMiddleware(options) {
+        // Skip middleware if explicitly disabled
+        if (options.disableMiddleware === true) {
+            return true;
+        }
+        // Skip middleware for tool-disabled requests to avoid conflicts
+        if (options.disableTools === true) {
+            return true;
+        }
+        return false;
+    }
     // ===================
     // TOOL MANAGEMENT
     // ===================
@@ -428,7 +548,7 @@ export class BaseProvider {
                                         timestamp: new Date().toISOString(),
                                         params: params,
                                         // Keep it simple - just indicate an error occurred
-                                        message: `Error calling ${toolName}: ${error instanceof Error ? error.message : String(error)}`
+                                        message: `Error calling ${toolName}: ${error instanceof Error ? error.message : String(error)}`,
                                     };
                                 }
                             },

package/dist/core/evaluationProviders.d.ts

@@ -32,3 +32,29 @@ export declare function isProviderAvailable(providerName: string): boolean;
  * Get the best available provider based on preference
  */
 export declare function getBestAvailableProvider(preferCheap?: boolean): ProviderModelConfig | null;
+/**
+ Record actual provider performance for optimization
+ */
+export declare function recordProviderPerformanceFromMetrics(providerName: string, metrics: {
+    responseTime: number;
+    tokensGenerated: number;
+    cost: number;
+    success: boolean;
+}): void;
+/**
+ * Get performance-optimized provider based on real metrics
+ */
+export declare function getPerformanceOptimizedProvider(priority?: "speed" | "cost" | "reliability"): ProviderModelConfig | null;
+export declare function getProviderPerformanceAnalytics(): Record<string, {
+    avgResponseTime: number;
+    successRate: number;
+    tokenThroughput: number;
+    costEfficiency: number;
+    recommendation: string;
+    sampleCount: number;
+}>;
+/**
+ * Reset performance metrics for a provider or all providers.
+ * @param providerName - (Optional) The name of the provider to reset. If omitted, resets all providers.
+ */
+export declare function resetProviderMetrics(providerName?: string): void;

package/dist/core/evaluationProviders.js

@@ -1,4 +1,11 @@
 import { modelConfig } from "./modelConfiguration.js";
+const PERFORMANCE_THRESHOLDS = {
+    EXCELLENT_SUCCESS_RATE: 0.95,
+    EXCELLENT_RESPONSE_TIME_MS: 2000,
+    GOOD_SUCCESS_RATE: 0.9,
+    FAIR_SUCCESS_RATE: 0.8,
+};
+const providerMetrics = new Map();
 /**
  * Convert new configuration format to legacy format for backwards compatibility
  */
@@ -101,3 +108,156 @@ export function getBestAvailableProvider(preferCheap = true) {
     const sortedProviders = sortProvidersByPreference(availableProviders, preferCheap);
     return sortedProviders[0];
 }
+/**
+ Record actual provider performance for optimization
+ */
+export function recordProviderPerformanceFromMetrics(providerName, metrics) {
+    const existing = providerMetrics.get(providerName) || {
+        responseTime: [],
+        successRate: 0,
+        tokenThroughput: 0,
+        costEfficiency: 0,
+        lastUpdated: new Date(),
+        sampleCount: 0,
+    };
+    // Keep rolling window of last 50 response times
+    existing.responseTime.push(metrics.responseTime);
+    if (existing.responseTime.length > 50) {
+        existing.responseTime.shift();
+    }
+    // Update success rate
+    const totalSamples = existing.sampleCount + 1;
+    existing.successRate =
+        (existing.successRate * existing.sampleCount + (metrics.success ? 1 : 0)) /
+            totalSamples;
+    // Update throughput (tokens per second)
+    if (metrics.responseTime > 0) {
+        const tokensPerSecond = metrics.tokensGenerated / (metrics.responseTime / 1000);
+        existing.tokenThroughput =
+            (existing.tokenThroughput * existing.sampleCount + tokensPerSecond) /
+                totalSamples;
+    }
+    // If responseTime is 0, skip updating tokenThroughput for this sample
+    // but still update other metrics
+    // Update cost efficiency (tokens per dollar)
+    if (metrics.cost > 0) {
+        const tokensPerDollar = metrics.tokensGenerated / metrics.cost;
+        existing.costEfficiency =
+            (existing.costEfficiency * existing.sampleCount + tokensPerDollar) /
+                totalSamples;
+    }
+    existing.sampleCount = totalSamples;
+    existing.lastUpdated = new Date();
+    providerMetrics.set(providerName, existing);
+}
+/**
+ * Get performance-optimized provider based on real metrics
+ */
+export function getPerformanceOptimizedProvider(priority = "speed") {
+    const availableProviders = getAvailableProviders();
+    if (availableProviders.length === 0) {
+        return null;
+    }
+    // Score providers based on real performance data
+    const scoredProviders = availableProviders.map((provider) => {
+        const metrics = providerMetrics.get(provider.provider);
+        if (!metrics || metrics.sampleCount < 3) {
+            // Fall back to static performance ratings for providers without data
+            return {
+                provider,
+                score: getStaticPerformanceScore(provider, priority),
+                metrics: null,
+            };
+        }
+        let score = 0;
+        switch (priority) {
+            case "speed": {
+                const avgResponseTime = metrics.responseTime.reduce((a, b) => a + b, 0) /
+                    metrics.responseTime.length;
+                score =
+                    metrics.tokenThroughput * 0.6 +
+                        (5000 / Math.max(avgResponseTime, 100)) * 0.4;
+                break;
+            }
+            case "cost": {
+                score = metrics.costEfficiency * 0.7 + metrics.successRate * 0.3;
+                break;
+            }
+            case "reliability": {
+                score = metrics.successRate * 0.8 + (metrics.sampleCount / 100) * 0.2;
+                break;
+            }
+        }
+        return { provider, score, metrics };
+    });
+    // Sort by score and return best
+    scoredProviders.sort((a, b) => b.score - a.score);
+    return scoredProviders[0].provider;
+}
+/**
+ * Helper function for providers without performance data
+ */
+function getStaticPerformanceScore(provider, priority) {
+    switch (priority) {
+        case "speed": {
+            const speedScore = provider.performance?.speed || 1;
+            return speedScore;
+        }
+        case "cost": {
+            const costScore = provider.performance?.cost || 1;
+            return costScore;
+        }
+        case "reliability": {
+            const qualityScore = provider.performance?.quality || 1;
+            return qualityScore;
+        }
+        default: {
+            throw new Error(`Invalid priority: "${priority}". Must be one of: speed, cost, reliability`);
+        }
+    }
+}
+export function getProviderPerformanceAnalytics() {
+    const analytics = {};
+    for (const [providerName, metrics] of providerMetrics.entries()) {
+        if (metrics.sampleCount === 0) {
+            continue;
+        }
+        const avgResponseTime = metrics.responseTime.reduce((a, b) => a + b, 0) /
+            metrics.responseTime.length;
+        let recommendation = "";
+        if (metrics.successRate > PERFORMANCE_THRESHOLDS.EXCELLENT_SUCCESS_RATE &&
+            avgResponseTime < PERFORMANCE_THRESHOLDS.EXCELLENT_RESPONSE_TIME_MS) {
+            recommendation = "Excellent - Recommended for production";
+        }
+        else if (metrics.successRate > PERFORMANCE_THRESHOLDS.GOOD_SUCCESS_RATE) {
+            recommendation = "Good - Suitable for most tasks";
+        }
+        else if (metrics.successRate > PERFORMANCE_THRESHOLDS.FAIR_SUCCESS_RATE) {
+            recommendation = "Fair - Monitor closely";
+        }
+        else {
+            recommendation = "Poor - Consider alternative providers";
+        }
+        analytics[providerName] = {
+            avgResponseTime,
+            successRate: metrics.successRate,
+            tokenThroughput: metrics.tokenThroughput,
+            costEfficiency: metrics.costEfficiency,
+            recommendation,
+            sampleCount: metrics.sampleCount,
+        };
+    }
+    return analytics;
+}
+/**
+ * Reset performance metrics for a provider or all providers.
+ * @param providerName - (Optional) The name of the provider to reset. If omitted, resets all providers.
+ */
+export function resetProviderMetrics(providerName) {
+    if (providerName) {
+        providerMetrics.delete(providerName);
+    }
+    else {
+        providerMetrics.clear();
+    }
+}

package/dist/index.d.ts

@@ -18,6 +18,9 @@ export { getBestProvider, getAvailableProviders, isValidProvider, } from "./util
 export { NeuroLink } from "./neurolink.js";
 export type { ProviderStatus, MCPStatus } from "./neurolink.js";
 export type { MCPServerInfo } from "./types/mcpTypes.js";
+export type { NeuroLinkMiddleware, MiddlewareContext, MiddlewareFactoryOptions, } from "./middleware/types.js";
+export { MiddlewareRegistry, MiddlewareFactory } from "./middleware/index.js";
+export { createAnalyticsMiddleware } from "./middleware/builtin/analytics.js";
 export declare const VERSION = "1.0.0";
 /**
  * Quick start factory function

package/dist/index.js

@@ -16,6 +16,8 @@ export { BedrockModels, OpenAIModels, VertexModels, DEFAULT_PROVIDER_CONFIGS, }
 export { getBestProvider, getAvailableProviders, isValidProvider, } from "./utils/providerUtils.js";
 // Main NeuroLink wrapper class and diagnostic types
 export { NeuroLink } from "./neurolink.js";
+export { MiddlewareRegistry, MiddlewareFactory } from "./middleware/index.js";
+export { createAnalyticsMiddleware } from "./middleware/builtin/analytics.js";
 // Version
 export const VERSION = "1.0.0";
 /**

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

@@ -63,6 +63,19 @@ export declare abstract class BaseProvider implements AIProvider {
      * Returns the Vercel AI SDK model instance for this provider
      */
     protected abstract getAISDKModel(): LanguageModelV1 | Promise<LanguageModelV1>;
+    /**
+     * Get AI SDK model with middleware applied
+     * This method wraps the base model with any configured middleware
+     */
+    protected getAISDKModelWithMiddleware(options?: TextGenerationOptions | StreamOptions): Promise<LanguageModelV1>;
+    /**
+     * Extract middleware options from generation options
+     */
+    private extractMiddlewareOptions;
+    /**
+     * Determine if middleware should be skipped for this request
+     */
+    private shouldSkipMiddleware;
     /**
      * Get all available tools - direct tools are ALWAYS available
      * MCP tools are added when available (without blocking)

package/dist/lib/core/baseProvider.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { MiddlewareFactory } from "../middleware/factory.js";
 import { logger } from "../utils/logger.js";
 import { DEFAULT_MAX_STEPS, STEP_LIMITS } from "../core/constants.js";
 import { directAgentTools } from "../agent/directTools.js";
@@ -8,6 +9,8 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { buildMessagesArray } from "../utils/messageBuilder.js";
 import { getKeysAsString, getKeyCount } from "../utils/transformationUtils.js";
 import { validateStreamOptions as validateStreamOpts, validateTextGenerationOptions, ValidationError, createValidationSummary, } from "../utils/parameterValidation.js";
+import { recordProviderPerformanceFromMetrics, getPerformanceOptimizedProvider, } from "./evaluationProviders.js";
+import { modelConfig } from "./modelConfiguration.js";
 /**
  * Abstract base class for all AI providers
  * Tools are integrated as first-class citizens - always available by default
@@ -181,6 +184,46 @@ export class BaseProvider {
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || 8192,
             });
+            const responseTime = Date.now() - startTime;
+            try {
+                // Calculate actual cost based on token usage and provider configuration
+                const calculateActualCost = () => {
+                    try {
+                        const costInfo = modelConfig.getCostInfo(this.providerName, this.modelName);
+                        if (!costInfo) {
+                            return 0; // No cost info available
+                        }
+                        const promptTokens = result.usage?.promptTokens || 0;
+                        const completionTokens = result.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
+                    }
+                };
+                const actualCost = calculateActualCost();
+                recordProviderPerformanceFromMetrics(this.providerName, {
+                    responseTime,
+                    tokensGenerated: result.usage?.totalTokens || 0,
+                    cost: actualCost,
+                    success: true,
+                });
+                // Show what the system learned (updated to include cost)
+                const optimizedProvider = getPerformanceOptimizedProvider("speed");
+                logger.debug(`🚀 Performance recorded for ${this.providerName}:`, {
+                    responseTime: `${responseTime}ms`,
+                    tokens: result.usage?.totalTokens || 0,
+                    estimatedCost: `$${actualCost.toFixed(6)}`,
+                    recommendedSpeedProvider: optimizedProvider?.provider || "none",
+                });
+            }
+            catch (perfError) {
+                logger.warn("⚠️ Performance recording failed:", perfError);
+            }
             // Extract tool names from tool calls for tracking
             // AI SDK puts tool calls in steps array for multi-step generation
             const toolsUsed = [];
@@ -357,6 +400,83 @@ export class BaseProvider {
             evaluation: result.evaluation,
         };
     }
+    /**
+     * Get AI SDK model with middleware applied
+     * This method wraps the base model with any configured middleware
+     */
+    async getAISDKModelWithMiddleware(options = {}) {
+        // Get the base model
+        const baseModel = await this.getAISDKModel();
+        // Check if middleware should be applied
+        const middlewareOptions = this.extractMiddlewareOptions(options);
+        if (!middlewareOptions || this.shouldSkipMiddleware(options)) {
+            return baseModel;
+        }
+        try {
+            // Create middleware context
+            const context = MiddlewareFactory.createContext(this.providerName, this.modelName, options, {
+                sessionId: this.sessionId,
+                userId: this.userId,
+            });
+            // Apply middleware to the model
+            const wrappedModel = MiddlewareFactory.applyMiddleware(baseModel, context, middlewareOptions);
+            logger.debug(`Applied middleware to ${this.providerName} model`, {
+                provider: this.providerName,
+                model: this.modelName,
+                hasMiddleware: true,
+            });
+            return wrappedModel;
+        }
+        catch (error) {
+            logger.warn(`Failed to apply middleware to ${this.providerName}, using base model`, {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Return base model on middleware failure to maintain functionality
+            return baseModel;
+        }
+    }
+    /**
+     * Extract middleware options from generation options
+     */
+    extractMiddlewareOptions(options) {
+        // Check for middleware configuration in options
+        const optionsRecord = options;
+        const middlewareConfig = optionsRecord.middlewareConfig;
+        const enabledMiddleware = optionsRecord.enabledMiddleware;
+        const disabledMiddleware = optionsRecord.disabledMiddleware;
+        const preset = optionsRecord.middlewarePreset;
+        // If no middleware configuration is present, return null
+        if (!middlewareConfig &&
+            !enabledMiddleware &&
+            !disabledMiddleware &&
+            !preset) {
+            return null;
+        }
+        return {
+            middlewareConfig,
+            enabledMiddleware,
+            disabledMiddleware,
+            preset,
+            global: {
+                collectStats: true,
+                continueOnError: true,
+            },
+        };
+    }
+    /**
+     * Determine if middleware should be skipped for this request
+     */
+    shouldSkipMiddleware(options) {
+        // Skip middleware if explicitly disabled
+        if (options.disableMiddleware === true) {
+            return true;
+        }
+        // Skip middleware for tool-disabled requests to avoid conflicts
+        if (options.disableTools === true) {
+            return true;
+        }
+        return false;
+    }
     // ===================
     // TOOL MANAGEMENT
     // ===================
@@ -428,7 +548,7 @@ export class BaseProvider {
                                         timestamp: new Date().toISOString(),
                                         params: params,
                                         // Keep it simple - just indicate an error occurred
-                                        message: `Error calling ${toolName}: ${error instanceof Error ? error.message : String(error)}`
+                                        message: `Error calling ${toolName}: ${error instanceof Error ? error.message : String(error)}`,
                                     };
                                 }
                             },

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

@@ -32,3 +32,29 @@ export declare function isProviderAvailable(providerName: string): boolean;
  * Get the best available provider based on preference
  */
 export declare function getBestAvailableProvider(preferCheap?: boolean): ProviderModelConfig | null;
+/**
+ Record actual provider performance for optimization
+ */
+export declare function recordProviderPerformanceFromMetrics(providerName: string, metrics: {
+    responseTime: number;
+    tokensGenerated: number;
+    cost: number;
+    success: boolean;
+}): void;
+/**
+ * Get performance-optimized provider based on real metrics
+ */
+export declare function getPerformanceOptimizedProvider(priority?: "speed" | "cost" | "reliability"): ProviderModelConfig | null;
+export declare function getProviderPerformanceAnalytics(): Record<string, {
+    avgResponseTime: number;
+    successRate: number;
+    tokenThroughput: number;
+    costEfficiency: number;
+    recommendation: string;
+    sampleCount: number;
+}>;
+/**
+ * Reset performance metrics for a provider or all providers.
+ * @param providerName - (Optional) The name of the provider to reset. If omitted, resets all providers.
+ */
+export declare function resetProviderMetrics(providerName?: string): void;