@juspay/neurolink 7.24.1 → 7.25.0

package/dist/lib/middleware/registry.js

@@ -0,0 +1,283 @@
+import { logger } from "../utils/logger.js";
+/**
+ * Global middleware registry for NeuroLink
+ * Manages registration, configuration, and execution of middleware
+ */
+export class MiddlewareRegistry {
+    middleware = new Map();
+    globalConfigs = new Map();
+    executionStats = new Map();
+    /**
+     * Register a middleware
+     */
+    register(middleware, options = {}) {
+        const { replace = false, defaultEnabled = false, globalConfig } = options;
+        // Check if middleware already exists
+        if (this.middleware.has(middleware.metadata.id) && !replace) {
+            throw new Error(`Middleware with ID '${middleware.metadata.id}' already exists. Use replace: true to override.`);
+        }
+        // Set default enabled state
+        if (middleware.metadata.defaultEnabled === undefined) {
+            middleware.metadata.defaultEnabled = defaultEnabled;
+        }
+        // Store middleware
+        this.middleware.set(middleware.metadata.id, middleware);
+        // Store global configuration if provided
+        if (globalConfig) {
+            this.globalConfigs.set(middleware.metadata.id, globalConfig);
+        }
+        logger.debug(`Middleware registered: ${middleware.metadata.id}`, {
+            name: middleware.metadata.name,
+            priority: middleware.metadata.priority || 0,
+            defaultEnabled: middleware.metadata.defaultEnabled,
+        });
+    }
+    /**
+     * Unregister a middleware
+     */
+    unregister(middlewareId) {
+        const removed = this.middleware.delete(middlewareId);
+        this.globalConfigs.delete(middlewareId);
+        this.executionStats.delete(middlewareId);
+        if (removed) {
+            logger.debug(`Middleware unregistered: ${middlewareId}`);
+        }
+        return removed;
+    }
+    /**
+     * Get a registered middleware
+     */
+    get(middlewareId) {
+        return this.middleware.get(middlewareId);
+    }
+    /**
+     * List all registered middleware
+     */
+    list() {
+        return Array.from(this.middleware.values());
+    }
+    /**
+     * Get middleware IDs sorted by priority
+     */
+    getSortedIds() {
+        return Array.from(this.middleware.values())
+            .sort((a, b) => (b.metadata.priority || 0) - (a.metadata.priority || 0))
+            .map((m) => m.metadata.id);
+    }
+    /**
+     * Build middleware chain based on configuration
+     */
+    buildChain(context, config = {}) {
+        const chain = [];
+        const sortedIds = this.getSortedIds();
+        for (const middlewareId of sortedIds) {
+            const middleware = this.middleware.get(middlewareId);
+            if (!middleware) {
+                continue;
+            }
+            const middlewareConfig = config[middlewareId];
+            const globalConfig = this.globalConfigs.get(middlewareId);
+            // Determine if middleware should be applied
+            const shouldApply = this.shouldApplyMiddleware(middleware, middlewareConfig, context);
+            if (shouldApply) {
+                // Create configured middleware instance
+                const configuredMiddleware = this.configureMiddleware(middleware, middlewareConfig, globalConfig, context);
+                chain.push(configuredMiddleware);
+                logger.debug(`Added middleware to chain: ${middlewareId}`, {
+                    priority: middleware.metadata.priority || 0,
+                    chainLength: chain.length,
+                });
+            }
+        }
+        return chain;
+    }
+    /**
+     * Determine if middleware should be applied based on conditions
+     */
+    shouldApplyMiddleware(middleware, config, context) {
+        // Check if explicitly disabled
+        if (config?.enabled === false) {
+            return false;
+        }
+        // Check if explicitly enabled or default enabled
+        const isEnabled = config?.enabled === true ||
+            (config?.enabled === undefined && middleware.metadata.defaultEnabled);
+        if (!isEnabled) {
+            return false;
+        }
+        // Check conditions
+        const conditions = config?.conditions;
+        if (!conditions) {
+            return true;
+        }
+        // Check provider conditions
+        if (conditions.providers &&
+            !conditions.providers.includes(context.provider)) {
+            return false;
+        }
+        // Check model conditions
+        if (conditions.models && !conditions.models.includes(context.model)) {
+            return false;
+        }
+        // Check option conditions
+        if (conditions.options) {
+            for (const [key, value] of Object.entries(conditions.options)) {
+                if (context.options[key] !== value) {
+                    return false;
+                }
+            }
+        }
+        // Check custom condition
+        if (conditions.custom && !conditions.custom(context)) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Configure middleware with runtime configuration
+     */
+    configureMiddleware(middleware, config, globalConfig, context) {
+        // Merge configurations: global < middleware config < runtime config
+        const mergedConfig = {
+            ...globalConfig,
+            ...config?.config,
+        };
+        // Create wrapper that tracks execution
+        const wrappedMiddleware = {};
+        if (middleware.transformParams) {
+            wrappedMiddleware.transformParams = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.transformParams(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        if (middleware.wrapGenerate) {
+            wrappedMiddleware.wrapGenerate = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.wrapGenerate(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        if (middleware.wrapStream) {
+            wrappedMiddleware.wrapStream = async (args) => {
+                const startTime = Date.now();
+                try {
+                    const result = await middleware.wrapStream(args);
+                    this.recordExecution(middleware.metadata.id, startTime, true);
+                    return result;
+                }
+                catch (error) {
+                    this.recordExecution(middleware.metadata.id, startTime, false, error);
+                    throw error;
+                }
+            };
+        }
+        return wrappedMiddleware;
+    }
+    /**
+     * Record middleware execution statistics
+     */
+    recordExecution(middlewareId, startTime, success, error) {
+        const executionTime = Date.now() - startTime;
+        const result = {
+            applied: true,
+            executionTime,
+            error,
+        };
+        if (!this.executionStats.has(middlewareId)) {
+            this.executionStats.set(middlewareId, []);
+        }
+        const stats = this.executionStats.get(middlewareId) || [];
+        stats.push(result);
+        // Keep only last 100 executions per middleware
+        if (stats.length > 100) {
+            stats.shift();
+        }
+        if (error) {
+            logger.warn(`Middleware execution failed: ${middlewareId}`, {
+                executionTime,
+                error: error.message,
+            });
+        }
+        else {
+            logger.debug(`Middleware executed: ${middlewareId}`, {
+                executionTime,
+                success,
+            });
+        }
+    }
+    /**
+     * Get execution statistics for a middleware
+     */
+    getExecutionStats(middlewareId) {
+        return this.executionStats.get(middlewareId) || [];
+    }
+    /**
+     * Get aggregated statistics for all middleware
+     */
+    getAggregatedStats() {
+        const stats = {};
+        for (const [middlewareId, executions] of this.executionStats.entries()) {
+            const successful = executions.filter((e) => !e.error).length;
+            const failed = executions.filter((e) => e.error).length;
+            const totalTime = executions.reduce((sum, e) => sum + e.executionTime, 0);
+            const lastExecution = executions[executions.length - 1];
+            stats[middlewareId] = {
+                totalExecutions: executions.length,
+                successfulExecutions: successful,
+                failedExecutions: failed,
+                averageExecutionTime: executions.length > 0 ? totalTime / executions.length : 0,
+                lastExecutionTime: lastExecution?.executionTime || 0,
+            };
+        }
+        return stats;
+    }
+    /**
+     * Clear execution statistics
+     */
+    clearStats(middlewareId) {
+        if (middlewareId) {
+            this.executionStats.delete(middlewareId);
+        }
+        else {
+            this.executionStats.clear();
+        }
+    }
+    /**
+     * Check if a middleware is registered
+     */
+    has(middlewareId) {
+        return this.middleware.has(middlewareId);
+    }
+    /**
+     * Get the number of registered middleware
+     */
+    size() {
+        return this.middleware.size;
+    }
+    /**
+     * Clear all registered middleware
+     */
+    clear() {
+        this.middleware.clear();
+        this.globalConfigs.clear();
+        this.executionStats.clear();
+        logger.debug("All middleware cleared from registry");
+    }
+}
+// Global middleware registry instance
+export const middlewareRegistry = new MiddlewareRegistry();

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

@@ -0,0 +1,144 @@
+import type { LanguageModelV1Middleware } from "ai";
+import type { JsonValue } from "../types/common.js";
+/**
+ * Metadata interface for NeuroLink middleware
+ * Provides additional information about middleware without affecting execution
+ */
+export interface NeuroLinkMiddlewareMetadata {
+    /** Unique identifier for the middleware */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of what the middleware does */
+    description?: string;
+    /** Priority for ordering (higher = earlier in chain) */
+    priority?: number;
+    /** Whether this middleware is enabled by default */
+    defaultEnabled?: boolean;
+    /** Configuration schema for the middleware */
+    configSchema?: Record<string, unknown>;
+}
+/**
+ * NeuroLink middleware with metadata
+ * Combines standard AI SDK middleware with NeuroLink-specific metadata
+ */
+export interface NeuroLinkMiddleware extends LanguageModelV1Middleware {
+    /** Middleware metadata */
+    readonly metadata: NeuroLinkMiddlewareMetadata;
+}
+/**
+ * Middleware configuration options
+ */
+export interface MiddlewareConfig {
+    /** Whether the middleware is enabled */
+    enabled?: boolean;
+    /** Middleware-specific configuration */
+    config?: Record<string, JsonValue>;
+    /** Conditions under which to apply this middleware */
+    conditions?: MiddlewareConditions;
+}
+/**
+ * Conditions for applying middleware
+ */
+export interface MiddlewareConditions {
+    /** Apply only to specific providers */
+    providers?: string[];
+    /** Apply only to specific models */
+    models?: string[];
+    /** Apply only when certain options are present */
+    options?: Record<string, unknown>;
+    /** Custom condition function */
+    custom?: (context: MiddlewareContext) => boolean;
+}
+/**
+ * Context passed to middleware for decision making
+ */
+export interface MiddlewareContext {
+    /** Provider name */
+    provider: string;
+    /** Model name */
+    model: string;
+    /** Request options */
+    options: Record<string, unknown>;
+    /** Session information */
+    session?: {
+        sessionId?: string;
+        userId?: string;
+    };
+    /** Additional metadata */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Middleware registration options
+ */
+export interface MiddlewareRegistrationOptions {
+    /** Whether to replace existing middleware with same ID */
+    replace?: boolean;
+    /** Whether to enable the middleware by default */
+    defaultEnabled?: boolean;
+    /** Global configuration for the middleware */
+    globalConfig?: Record<string, JsonValue>;
+}
+/**
+ * Middleware execution result
+ */
+export interface MiddlewareExecutionResult {
+    /** Whether the middleware was applied */
+    applied: boolean;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Any errors that occurred */
+    error?: Error;
+    /** Additional metadata from the middleware */
+    metadata?: Record<string, JsonValue>;
+}
+/**
+ * Middleware chain execution statistics
+ */
+export interface MiddlewareChainStats {
+    /** Total number of middleware in the chain */
+    totalMiddleware: number;
+    /** Number of middleware that were applied */
+    appliedMiddleware: number;
+    /** Total execution time for the chain */
+    totalExecutionTime: number;
+    /** Individual middleware execution results */
+    results: Record<string, MiddlewareExecutionResult>;
+}
+/**
+ * Built-in middleware types
+ */
+export type BuiltInMiddlewareType = "analytics" | "guardrails" | "logging" | "caching" | "rateLimit" | "retry" | "timeout";
+/**
+ * Middleware preset configurations
+ */
+export interface MiddlewarePreset {
+    /** Preset name */
+    name: string;
+    /** Description of the preset */
+    description: string;
+    /** Middleware configurations in the preset */
+    middleware: Record<string, MiddlewareConfig>;
+}
+/**
+ * Factory options for middleware
+ */
+export interface MiddlewareFactoryOptions {
+    /** Enable specific middleware */
+    enabledMiddleware?: string[];
+    /** Disable specific middleware */
+    disabledMiddleware?: string[];
+    /** Middleware configurations */
+    middlewareConfig?: Record<string, MiddlewareConfig>;
+    /** Use a preset configuration */
+    preset?: string;
+    /** Global middleware settings */
+    global?: {
+        /** Maximum execution time for middleware chain */
+        maxExecutionTime?: number;
+        /** Whether to continue on middleware errors */
+        continueOnError?: boolean;
+        /** Whether to collect execution statistics */
+        collectStats?: boolean;
+    };
+}

package/dist/lib/middleware/types.js

@@ -0,0 +1 @@
+export {};

package/dist/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/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/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>;
+}