@juspay/neurolink 7.24.1 → 7.25.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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";
@@ -357,6 +358,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 +506,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/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";
@@ -357,6 +358,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 +506,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/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/lib/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/middleware/builtin/analytics.d.ts

@@ -0,0 +1,16 @@
+import type { NeuroLinkMiddleware } from "../types.js";
+/**
+ * Create analytics middleware for tracking AI model usage
+ * Collects metrics on token usage, response times, and model performance
+ */
+export declare function createAnalyticsMiddleware(): NeuroLinkMiddleware;
+/**
+ * Get collected metrics from analytics middleware
+ * Note: This is a utility function for accessing metrics
+ */
+export declare function getAnalyticsMetrics(): Map<string, Record<string, unknown>>;
+/**
+ * Clear collected metrics from analytics middleware
+ * Note: This is a utility function for clearing metrics
+ */
+export declare function clearAnalyticsMetrics(): void;

package/dist/lib/middleware/builtin/analytics.js

@@ -0,0 +1,130 @@
+import { logger } from "../../utils/logger.js";
+/**
+ * Create analytics middleware for tracking AI model usage
+ * Collects metrics on token usage, response times, and model performance
+ */
+export function createAnalyticsMiddleware() {
+    const requestMetrics = new Map();
+    const metadata = {
+        id: "analytics",
+        name: "Analytics Tracking",
+        description: "Tracks token usage, response times, and model performance metrics",
+        priority: 100, // High priority to ensure analytics are captured
+        defaultEnabled: true,
+    };
+    const middleware = {
+        wrapGenerate: async ({ doGenerate, params }) => {
+            const requestId = `analytics-${Date.now()}`;
+            const startTime = Date.now();
+            logger.debug(`[AnalyticsMiddleware] Starting request tracking`, {
+                requestId,
+                hasPrompt: !!params.prompt,
+            });
+            try {
+                // Execute the generation
+                const result = await doGenerate();
+                // Calculate metrics
+                const responseTime = Date.now() - startTime;
+                const analytics = {
+                    requestId,
+                    responseTime,
+                    timestamp: new Date().toISOString(),
+                    usage: {
+                        inputTokens: result.usage?.promptTokens || 0,
+                        outputTokens: result.usage?.completionTokens || 0,
+                        totalTokens: (result.usage?.promptTokens || 0) +
+                            (result.usage?.completionTokens || 0),
+                    },
+                };
+                // Store metrics for potential retrieval
+                requestMetrics.set(requestId, analytics);
+                logger.debug(`[AnalyticsMiddleware] Request completed`, analytics);
+                // Add analytics to the result
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const updatedResult = { ...result };
+                if (!updatedResult.experimental_providerMetadata) {
+                    updatedResult.experimental_providerMetadata = {};
+                }
+                if (!updatedResult.experimental_providerMetadata.neurolink) {
+                    updatedResult.experimental_providerMetadata.neurolink = {};
+                }
+                updatedResult.experimental_providerMetadata.neurolink.analytics =
+                    analytics;
+                return updatedResult;
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                logger.error(`[AnalyticsMiddleware] Request failed`, {
+                    requestId,
+                    responseTime,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        },
+        wrapStream: async ({ doStream, params }) => {
+            const requestId = `analytics-stream-${Date.now()}`;
+            const startTime = Date.now();
+            logger.debug(`[AnalyticsMiddleware] Starting stream tracking`, {
+                requestId,
+                hasPrompt: !!params.prompt,
+            });
+            try {
+                const result = await doStream();
+                const streamAnalytics = {
+                    requestId,
+                    startTime,
+                    timestamp: new Date().toISOString(),
+                    streamingMode: true,
+                };
+                requestMetrics.set(requestId, streamAnalytics);
+                // The 'result' is a stream, so we can't directly modify it.
+                // Analytics for streams are typically handled after the stream is consumed.
+                // For this middleware, we'll log the start and rely on other mechanisms
+                // to capture the end-to-end stream metrics if needed.
+                // We will pass a new property in the `rawResponse`
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                const updatedResult = { ...result };
+                if (!updatedResult.rawResponse) {
+                    updatedResult.rawResponse = {};
+                }
+                if (!updatedResult.rawResponse.neurolink) {
+                    updatedResult.rawResponse.neurolink = {};
+                }
+                updatedResult.rawResponse.neurolink.analytics = streamAnalytics;
+                return updatedResult;
+            }
+            catch (error) {
+                const responseTime = Date.now() - startTime;
+                logger.error(`[AnalyticsMiddleware] Stream failed`, {
+                    requestId,
+                    responseTime,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                throw error;
+            }
+        },
+    };
+    // Return the NeuroLinkMiddleware with metadata
+    return {
+        ...middleware,
+        metadata,
+    };
+}
+/**
+ * Get collected metrics from analytics middleware
+ * Note: This is a utility function for accessing metrics
+ */
+export function getAnalyticsMetrics() {
+    // This would need to be implemented with a global registry
+    // For now, return empty map
+    return new Map();
+}
+/**
+ * Clear collected metrics from analytics middleware
+ * Note: This is a utility function for clearing metrics
+ */
+export function clearAnalyticsMetrics() {
+    // This would need to be implemented with a global registry
+    // For now, do nothing
+}

package/dist/lib/middleware/factory.d.ts

@@ -0,0 +1,54 @@
+import type { LanguageModelV1 } from "ai";
+import type { MiddlewareContext, MiddlewareConfig, MiddlewareFactoryOptions, MiddlewareChainStats } from "./types.js";
+/**
+ * Middleware factory for creating and applying middleware chains
+ */
+export declare class MiddlewareFactory {
+    /**
+     * Apply middleware to a language model
+     */
+    static applyMiddleware(model: LanguageModelV1, context: MiddlewareContext, options?: MiddlewareFactoryOptions): LanguageModelV1;
+    /**
+     * Build middleware configuration from factory options
+     */
+    private static buildMiddlewareConfig;
+    /**
+     * Get preset configuration
+     */
+    private static getPresetConfig;
+    /**
+     * Get built-in preset configurations
+     */
+    private static getBuiltInPresets;
+    /**
+     * Create middleware context from provider and options
+     */
+    static createContext(provider: string, model: string, options?: Record<string, unknown>, session?: {
+        sessionId?: string;
+        userId?: string;
+    }): MiddlewareContext;
+    /**
+     * Validate middleware configuration
+     */
+    static validateConfig(config: Record<string, MiddlewareConfig>): {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Get available presets
+     */
+    static getAvailablePresets(): Array<{
+        name: string;
+        description: string;
+        middleware: string[];
+    }>;
+    /**
+     * Get middleware chain statistics
+     */
+    static getChainStats(context: MiddlewareContext, config: Record<string, MiddlewareConfig>): MiddlewareChainStats;
+    /**
+     * Create a middleware-enabled model factory function
+     */
+    static createModelFactory(baseModelFactory: () => Promise<LanguageModelV1>, defaultOptions?: MiddlewareFactoryOptions): (context: MiddlewareContext, options?: MiddlewareFactoryOptions) => Promise<LanguageModelV1>;
+}