@juspay/neurolink 7.24.1 → 7.26.0

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

@@ -0,0 +1,58 @@
+/**
+ * NeuroLink Middleware System
+ *
+ * This module provides a comprehensive middleware system for NeuroLink that integrates
+ * with the AI SDK's wrapLanguageModel functionality. It allows for modular enhancement
+ * of language models with features like analytics, guardrails, caching, and more.
+ */
+import type { NeuroLinkMiddleware, MiddlewareRegistrationOptions, MiddlewareConfig } from "./types.js";
+export type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareConditions, MiddlewareRegistrationOptions, MiddlewareExecutionResult, MiddlewareChainStats, MiddlewarePreset, MiddlewareFactoryOptions, BuiltInMiddlewareType, } from "./types.js";
+export type { LanguageModelV1Middleware } from "ai";
+export { MiddlewareRegistry, middlewareRegistry } from "./registry.js";
+export { MiddlewareFactory } from "./factory.js";
+/**
+ * Convenience function to register a middleware
+ */
+export declare function registerMiddleware(middleware: NeuroLinkMiddleware, options?: MiddlewareRegistrationOptions): void;
+/**
+ * Convenience function to unregister a middleware
+ */
+export declare function unregisterMiddleware(middlewareId: string): boolean;
+/**
+ * Convenience function to get all registered middleware
+ */
+export declare function listMiddleware(): NeuroLinkMiddleware[];
+/**
+ * Convenience function to check if a middleware is registered
+ */
+export declare function hasMiddleware(middlewareId: string): boolean;
+/**
+ * Convenience function to get middleware execution statistics
+ */
+export declare function getMiddlewareStats(): Record<string, {
+    totalExecutions: number;
+    successfulExecutions: number;
+    failedExecutions: number;
+    averageExecutionTime: number;
+    lastExecutionTime: number;
+}>;
+/**
+ * Convenience function to clear middleware execution statistics
+ */
+export declare function clearMiddlewareStats(middlewareId?: string): void;
+/**
+ * Convenience function to get available middleware presets
+ */
+export declare function getAvailablePresets(): Array<{
+    name: string;
+    description: string;
+    middleware: string[];
+}>;
+/**
+ * Convenience function to validate middleware configuration
+ */
+export declare function validateMiddlewareConfig(config: Record<string, MiddlewareConfig>): {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+};

package/dist/lib/middleware/index.js

@@ -0,0 +1,67 @@
+/**
+ * NeuroLink Middleware System
+ *
+ * This module provides a comprehensive middleware system for NeuroLink that integrates
+ * with the AI SDK's wrapLanguageModel functionality. It allows for modular enhancement
+ * of language models with features like analytics, guardrails, caching, and more.
+ */
+import { middlewareRegistry } from "./registry.js";
+import { MiddlewareFactory } from "./factory.js";
+// Registry for managing middleware
+export { MiddlewareRegistry, middlewareRegistry } from "./registry.js";
+// Factory for creating and applying middleware chains
+export { MiddlewareFactory } from "./factory.js";
+// Re-export built-in middleware when they're implemented
+// export { analyticsMiddleware } from './built-in/analytics.js';
+// export { guardrailsMiddleware } from './built-in/guardrails.js';
+// export { loggingMiddleware } from './built-in/logging.js';
+// export { cachingMiddleware } from './built-in/caching.js';
+// export { rateLimitMiddleware } from './built-in/rateLimit.js';
+/**
+ * Convenience function to register a middleware
+ */
+export function registerMiddleware(middleware, options) {
+    middlewareRegistry.register(middleware, options);
+}
+/**
+ * Convenience function to unregister a middleware
+ */
+export function unregisterMiddleware(middlewareId) {
+    return middlewareRegistry.unregister(middlewareId);
+}
+/**
+ * Convenience function to get all registered middleware
+ */
+export function listMiddleware() {
+    return middlewareRegistry.list();
+}
+/**
+ * Convenience function to check if a middleware is registered
+ */
+export function hasMiddleware(middlewareId) {
+    return middlewareRegistry.has(middlewareId);
+}
+/**
+ * Convenience function to get middleware execution statistics
+ */
+export function getMiddlewareStats() {
+    return middlewareRegistry.getAggregatedStats();
+}
+/**
+ * Convenience function to clear middleware execution statistics
+ */
+export function clearMiddlewareStats(middlewareId) {
+    middlewareRegistry.clearStats(middlewareId);
+}
+/**
+ * Convenience function to get available middleware presets
+ */
+export function getAvailablePresets() {
+    return MiddlewareFactory.getAvailablePresets();
+}
+/**
+ * Convenience function to validate middleware configuration
+ */
+export function validateMiddlewareConfig(config) {
+    return MiddlewareFactory.validateConfig(config);
+}

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

@@ -0,0 +1,78 @@
+import type { LanguageModelV1Middleware } from "ai";
+import type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareRegistrationOptions, MiddlewareExecutionResult } from "./types.js";
+/**
+ * Global middleware registry for NeuroLink
+ * Manages registration, configuration, and execution of middleware
+ */
+export declare class MiddlewareRegistry {
+    private middleware;
+    private globalConfigs;
+    private executionStats;
+    /**
+     * Register a middleware
+     */
+    register(middleware: NeuroLinkMiddleware, options?: MiddlewareRegistrationOptions): void;
+    /**
+     * Unregister a middleware
+     */
+    unregister(middlewareId: string): boolean;
+    /**
+     * Get a registered middleware
+     */
+    get(middlewareId: string): NeuroLinkMiddleware | undefined;
+    /**
+     * List all registered middleware
+     */
+    list(): NeuroLinkMiddleware[];
+    /**
+     * Get middleware IDs sorted by priority
+     */
+    getSortedIds(): string[];
+    /**
+     * Build middleware chain based on configuration
+     */
+    buildChain(context: MiddlewareContext, config?: Record<string, MiddlewareConfig>): LanguageModelV1Middleware[];
+    /**
+     * Determine if middleware should be applied based on conditions
+     */
+    private shouldApplyMiddleware;
+    /**
+     * Configure middleware with runtime configuration
+     */
+    private configureMiddleware;
+    /**
+     * Record middleware execution statistics
+     */
+    private recordExecution;
+    /**
+     * Get execution statistics for a middleware
+     */
+    getExecutionStats(middlewareId: string): MiddlewareExecutionResult[];
+    /**
+     * Get aggregated statistics for all middleware
+     */
+    getAggregatedStats(): Record<string, {
+        totalExecutions: number;
+        successfulExecutions: number;
+        failedExecutions: number;
+        averageExecutionTime: number;
+        lastExecutionTime: number;
+    }>;
+    /**
+     * Clear execution statistics
+     */
+    clearStats(middlewareId?: string): void;
+    /**
+     * Check if a middleware is registered
+     */
+    has(middlewareId: string): boolean;
+    /**
+     * Get the number of registered middleware
+     */
+    size(): number;
+    /**
+     * Clear all registered middleware
+     */
+    clear(): void;
+}
+export declare const middlewareRegistry: MiddlewareRegistry;

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;