@juspay/neurolink 7.24.0 → 7.25.0

package/dist/lib/types/errors.js

@@ -0,0 +1,60 @@
+/**
+ * Base error class for all NeuroLink-specific errors.
+ * This allows for easy identification of errors thrown by the SDK.
+ */
+export class BaseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = this.constructor.name;
+    }
+}
+/**
+ * Thrown when a provider encounters a generic error.
+ */
+export class ProviderError extends BaseError {
+    provider;
+    constructor(message, provider) {
+        super(provider ? `[${provider}] ${message}` : message);
+        this.provider = provider;
+    }
+}
+/**
+ * Thrown for authentication-related errors, such as invalid or missing API keys.
+ */
+export class AuthenticationError extends ProviderError {
+    constructor(message, provider) {
+        super(message, provider);
+    }
+}
+/**
+ * Thrown for authorization errors, where the user does not have permission.
+ */
+export class AuthorizationError extends ProviderError {
+    constructor(message, provider) {
+        super(message, provider);
+    }
+}
+/**
+ * Thrown for network-related issues, such as connectivity problems or timeouts.
+ */
+export class NetworkError extends ProviderError {
+    constructor(message, provider) {
+        super(message, provider);
+    }
+}
+/**
+ * Thrown when an API rate limit has been exceeded.
+ */
+export class RateLimitError extends ProviderError {
+    constructor(message, provider) {
+        super(message, provider);
+    }
+}
+/**
+ * Thrown when a specified model is not found or is invalid for the provider.
+ */
+export class InvalidModelError extends ProviderError {
+    constructor(message, provider) {
+        super(message, provider);
+    }
+}

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>;
+}

package/dist/middleware/factory.js

@@ -0,0 +1,289 @@
+import { wrapLanguageModel } from "ai";
+import { middlewareRegistry } from "./registry.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Middleware factory for creating and applying middleware chains
+ */
+export class MiddlewareFactory {
+    /**
+     * Apply middleware to a language model
+     */
+    static applyMiddleware(model, context, options = {}) {
+        const startTime = Date.now();
+        try {
+            // Build middleware configuration
+            const middlewareConfig = this.buildMiddlewareConfig(options);
+            // Build middleware chain
+            const middlewareChain = middlewareRegistry.buildChain(context, middlewareConfig);
+            if (middlewareChain.length === 0) {
+                logger.debug("No middleware to apply", { provider: context.provider });
+                return model;
+            }
+            logger.debug(`Applying ${middlewareChain.length} middleware to model`, {
+                provider: context.provider,
+                model: context.model,
+                middlewareCount: middlewareChain.length,
+            });
+            // Apply middleware using AI SDK's wrapLanguageModel
+            // Cast to the expected AI SDK middleware type
+            const wrappedModel = wrapLanguageModel({
+                model,
+                middleware: middlewareChain,
+            });
+            const processingTime = Date.now() - startTime;
+            logger.debug("Middleware applied successfully", {
+                provider: context.provider,
+                middlewareCount: middlewareChain.length,
+                processingTime,
+            });
+            return wrappedModel;
+        }
+        catch (error) {
+            logger.error("Failed to apply middleware", {
+                provider: context.provider,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            // Return original model on error to maintain functionality
+            return model;
+        }
+    }
+    /**
+     * Build middleware configuration from factory options
+     */
+    static buildMiddlewareConfig(options) {
+        const config = {};
+        // Start with all registered middleware
+        const allMiddleware = middlewareRegistry.list();
+        for (const middleware of allMiddleware) {
+            // Default configuration
+            config[middleware.metadata.id] = {
+                enabled: middleware.metadata.defaultEnabled || false,
+                config: {},
+            };
+        }
+        // Apply preset configuration if specified
+        if (options.preset) {
+            const presetConfig = this.getPresetConfig(options.preset);
+            if (presetConfig) {
+                Object.assign(config, presetConfig);
+            }
+        }
+        // Apply explicit middleware configurations
+        if (options.middlewareConfig) {
+            for (const [middlewareId, middlewareConfig] of Object.entries(options.middlewareConfig)) {
+                config[middlewareId] = {
+                    ...config[middlewareId],
+                    ...middlewareConfig,
+                };
+            }
+        }
+        // Apply enabled middleware list
+        if (options.enabledMiddleware) {
+            for (const middlewareId of options.enabledMiddleware) {
+                if (config[middlewareId]) {
+                    config[middlewareId].enabled = true;
+                }
+            }
+        }
+        // Apply disabled middleware list
+        if (options.disabledMiddleware) {
+            for (const middlewareId of options.disabledMiddleware) {
+                if (config[middlewareId]) {
+                    config[middlewareId].enabled = false;
+                }
+            }
+        }
+        return config;
+    }
+    /**
+     * Get preset configuration
+     */
+    static getPresetConfig(presetName) {
+        const presets = this.getBuiltInPresets();
+        return presets[presetName] || null;
+    }
+    /**
+     * Get built-in preset configurations
+     */
+    static getBuiltInPresets() {
+        return {
+            // Development preset - logging and basic analytics
+            development: {
+                logging: { enabled: true },
+                analytics: { enabled: true },
+            },
+            // Production preset - analytics, caching, rate limiting
+            production: {
+                analytics: { enabled: true },
+                caching: { enabled: true },
+                rateLimit: { enabled: true },
+                retry: { enabled: true },
+            },
+            // Security preset - guardrails and content filtering
+            security: {
+                guardrails: { enabled: true },
+                logging: { enabled: true },
+                rateLimit: { enabled: true },
+            },
+            // Performance preset - caching and optimization
+            performance: {
+                caching: { enabled: true },
+                retry: { enabled: true },
+                timeout: { enabled: true },
+            },
+            // Enterprise preset - all middleware enabled
+            enterprise: {
+                analytics: { enabled: true },
+                guardrails: { enabled: true },
+                logging: { enabled: true },
+                caching: { enabled: true },
+                rateLimit: { enabled: true },
+                retry: { enabled: true },
+                timeout: { enabled: true },
+            },
+            // Minimal preset - only essential middleware
+            minimal: {
+                analytics: { enabled: true },
+            },
+        };
+    }
+    /**
+     * Create middleware context from provider and options
+     */
+    static createContext(provider, model, options = {}, session) {
+        return {
+            provider,
+            model,
+            options,
+            session,
+            metadata: {
+                timestamp: Date.now(),
+                requestId: `${provider}-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+            },
+        };
+    }
+    /**
+     * Validate middleware configuration
+     */
+    static validateConfig(config) {
+        const errors = [];
+        const warnings = [];
+        for (const [middlewareId, middlewareConfig] of Object.entries(config)) {
+            // Check if middleware is registered
+            if (!middlewareRegistry.has(middlewareId)) {
+                errors.push(`Middleware '${middlewareId}' is not registered`);
+                continue;
+            }
+            // Validate configuration structure
+            if (middlewareConfig.enabled !== undefined &&
+                typeof middlewareConfig.enabled !== "boolean") {
+                errors.push(`Middleware '${middlewareId}' enabled property must be boolean`);
+            }
+            if (middlewareConfig.config &&
+                typeof middlewareConfig.config !== "object") {
+                errors.push(`Middleware '${middlewareId}' config property must be an object`);
+            }
+            // Check for potential conflicts
+            if (middlewareConfig.conditions?.providers &&
+                middlewareConfig.conditions.providers.length === 0) {
+                warnings.push(`Middleware '${middlewareId}' has empty providers condition`);
+            }
+        }
+        return {
+            isValid: errors.length === 0,
+            errors,
+            warnings,
+        };
+    }
+    /**
+     * Get available presets
+     */
+    static getAvailablePresets() {
+        return [
+            {
+                name: "development",
+                description: "Logging and basic analytics for development",
+                middleware: ["logging", "analytics"],
+            },
+            {
+                name: "production",
+                description: "Optimized for production with caching and rate limiting",
+                middleware: ["analytics", "caching", "rateLimit", "retry"],
+            },
+            {
+                name: "security",
+                description: "Enhanced security with guardrails and monitoring",
+                middleware: ["guardrails", "logging", "rateLimit"],
+            },
+            {
+                name: "performance",
+                description: "Optimized for performance with caching and retries",
+                middleware: ["caching", "retry", "timeout"],
+            },
+            {
+                name: "enterprise",
+                description: "Full enterprise feature set with all middleware",
+                middleware: [
+                    "analytics",
+                    "guardrails",
+                    "logging",
+                    "caching",
+                    "rateLimit",
+                    "retry",
+                    "timeout",
+                ],
+            },
+            {
+                name: "minimal",
+                description: "Minimal overhead with only essential features",
+                middleware: ["analytics"],
+            },
+        ];
+    }
+    /**
+     * Get middleware chain statistics
+     */
+    static getChainStats(context, config) {
+        const chain = middlewareRegistry.buildChain(context, config);
+        const stats = middlewareRegistry.getAggregatedStats();
+        const results = {};
+        let totalExecutionTime = 0;
+        let appliedMiddleware = 0;
+        for (const [middlewareId, middlewareStats] of Object.entries(stats)) {
+            if (config[middlewareId]?.enabled) {
+                results[middlewareId] = {
+                    applied: true,
+                    executionTime: middlewareStats.averageExecutionTime,
+                };
+                totalExecutionTime += middlewareStats.averageExecutionTime;
+                appliedMiddleware++;
+            }
+        }
+        return {
+            totalMiddleware: chain.length,
+            appliedMiddleware,
+            totalExecutionTime,
+            results,
+        };
+    }
+    /**
+     * Create a middleware-enabled model factory function
+     */
+    static createModelFactory(baseModelFactory, defaultOptions = {}) {
+        return async (context, options = {}) => {
+            // Get base model
+            const baseModel = await baseModelFactory();
+            // Merge options
+            const _mergedOptions = {
+                ...defaultOptions,
+                ...options,
+                middlewareConfig: {
+                    ...defaultOptions.middlewareConfig,
+                    ...options.middlewareConfig,
+                },
+            };
+            // Apply middleware
+            return this.applyMiddleware(baseModel, context, _mergedOptions);
+        };
+    }
+}

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