@juspay/neurolink 7.30.0 → 7.31.0

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

@@ -5,6 +5,7 @@ import type { EvaluationData } from "../index.js";
 import type { TokenUsage } from "./providers.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
 import type { ChatMessage } from "./conversationTypes.js";
+import type { MiddlewareFactoryOptions } from "../types/middlewareTypes.js";
 /**
  * Interface for tool execution calls (AI SDK compatible)
  */
@@ -111,6 +112,7 @@ export interface StreamOptions {
         fallbackToGenerate?: boolean;
     };
     conversationMessages?: ChatMessage[];
+    middleware?: MiddlewareFactoryOptions;
 }
 /**
  * Stream function result interface - Primary output format for streaming

package/dist/lib/utils/conversationMemoryUtils.js

@@ -2,7 +2,7 @@
  * Conversation Memory Utilities
  * Handles configuration merging and conversation memory operations
  */
-import { getConversationMemoryDefaults, } from "../config/conversationMemoryConfig.js";
+import { getConversationMemoryDefaults } from "../config/conversationMemoryConfig.js";
 import { logger } from "./logger.js";
 /**
  * Apply conversation memory defaults to user configuration

package/dist/lib/utils/logger.d.ts

@@ -1,15 +1,38 @@
 /**
  * NeuroLink Unified Logger Utility
  *
- * Centralized logging for the entire NeuroLink ecosystem
- * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable
- * Migrated from MCP logging with enhanced features
+ * Centralized logging for the entire NeuroLink ecosystem.
+ * Provides structured logging with different severity levels and consistent formatting.
+ * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable.
+ * Maintains compatibility with MCP logging while providing enhanced features.
+ *
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Log history retention with configurable limits
+ * - Conditional logging based on environment settings
+ * - Structured data support for complex objects
+ * - Tabular data display
+ */
+/**
+ * Represents the available logging severity levels.
+ * - debug: Detailed information for debugging purposes
+ * - info: General information about system operation
+ * - warn: Potential issues that don't prevent operation
+ * - error: Critical issues that may cause failures
  */
 export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Represents a single log entry in the logging system.
+ * Each entry contains metadata about the log event along with the actual message.
+ */
 interface LogEntry {
+    /** The severity level of the log entry */
     level: LogLevel;
+    /** The text message to be logged */
     message: string;
+    /** When the log entry was created */
     timestamp: Date;
+    /** Optional additional data associated with the log entry (objects, arrays, etc.) */
     data?: unknown;
 }
 declare class NeuroLinkLogger {
@@ -18,8 +41,33 @@ declare class NeuroLinkLogger {
     private maxLogs;
     private isDebugMode;
     constructor();
+    /**
+     * Sets the minimum log level that will be processed and output.
+     * Log messages with a level lower than this will be ignored.
+     *
+     * @param level - The minimum log level to process ("debug", "info", "warn", or "error")
+     */
     setLogLevel(level: LogLevel): void;
+    /**
+     * Determines whether a message with the given log level should be processed.
+     * This method considers both the configured log level and the current debug mode.
+     *
+     * Logic:
+     * 1. If not in debug mode, only error messages are allowed
+     * 2. If in debug mode, messages at or above the configured log level are allowed
+     *
+     * @param level - The log level to check
+     * @returns True if a message with this level should be logged, false otherwise
+     */
     shouldLog(level: LogLevel): boolean;
+    /**
+     * Generates a standardized prefix for log messages.
+     * The prefix includes a timestamp and the log level in a consistent format.
+     *
+     * @param timestamp - ISO string representation of the log timestamp
+     * @param level - The log level for this message
+     * @returns Formatted prefix string like "[2025-08-18T13:45:30.123Z] [NEUROLINK:ERROR]"
+     */
     private getLogPrefix;
     /**
      * Outputs a log entry to the console based on the log level.
@@ -30,12 +78,64 @@ declare class NeuroLinkLogger {
      * @param data - Optional additional data to log.
      */
     private outputToConsole;
+    /**
+     * Core internal logging method that handles:
+     * 1. Creating log entries with consistent format
+     * 2. Storing entries in the log history
+     * 3. Managing log rotation to prevent memory issues
+     * 4. Outputting formatted logs to the console
+     *
+     * This is the central method called by all specific logging methods (debug, info, etc.)
+     *
+     * @param level - The severity level for this log entry
+     * @param message - The message text to log
+     * @param data - Optional additional context data to include
+     */
     private log;
+    /**
+     * Logs a message at the debug level.
+     * Used for detailed troubleshooting information.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     debug(message: string, data?: unknown): void;
+    /**
+     * Logs a message at the info level.
+     * Used for general information about system operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     info(message: string, data?: unknown): void;
+    /**
+     * Logs a message at the warn level.
+     * Used for potentially problematic situations that don't prevent operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     warn(message: string, data?: unknown): void;
+    /**
+     * Logs a message at the error level.
+     * Used for critical issues that may cause failures.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     error(message: string, data?: unknown): void;
+    /**
+     * Retrieves stored log entries, optionally filtered by log level.
+     * Returns a copy of the log entries to prevent external modification.
+     *
+     * @param level - Optional log level to filter by
+     * @returns Array of log entries, either all or filtered by level
+     */
     getLogs(level?: LogLevel): LogEntry[];
+    /**
+     * Removes all stored log entries.
+     * Useful for testing or when log history is no longer needed.
+     */
     clearLogs(): void;
     /**
      * Logs messages unconditionally using `console.log`.
@@ -44,16 +144,48 @@ declare class NeuroLinkLogger {
      * It bypasses the structured logging mechanism and should only be used when
      * unstructured, unconditional logging is required.
      *
+     * Use with caution in production environments as it outputs to the console
+     * regardless of the current log level or debug mode settings.
+     *
+     * Use cases:
+     * - Critical system information that must always be visible
+     * - Status messages during initialization before logging is fully configured
+     * - Debugging in environments where normal logging might be suppressed
+     *
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args: unknown[]): void;
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
-     * @param data - The data to display in table format
+     * Similar to the `always` method, this bypasses log level checks and
+     * will display data regardless of current logging settings.
+     *
+     * Important differences from other logging methods:
+     * - Does NOT store entries in the log history
+     * - Does NOT use the structured logging format with timestamps and prefixes
+     * - Outputs directly to console without additional formatting
+     *
+     * Particularly useful for:
+     * - Displaying structured data in a readable format during debugging
+     * - Showing configuration options and their current values
+     * - Presenting comparison data between different system states
+     * - Performance metrics and timing data
+     *
+     * @param data - The data to display in table format. Can be an array of objects or an object with key-value pairs.
      */
     table(data: unknown): void;
 }
+/**
+ * Main unified logger export that provides a simplified API for logging.
+ * This is the primary interface that should be used by application code.
+ *
+ * Features:
+ * - Convenient logging methods (debug, info, warn, error)
+ * - Unconditional logging (always, table)
+ * - Log level control and configuration
+ * - Log history management
+ */
 export declare const logger: {
     debug: (...args: unknown[]) => void;
     info: (...args: unknown[]) => void;
@@ -65,11 +197,39 @@ export declare const logger: {
     getLogs: (level?: LogLevel) => LogEntry[];
     clearLogs: () => void;
 };
+/**
+ * MCP compatibility exports - all use the same unified logger instance.
+ * These exports maintain backward compatibility with code that expects
+ * separate loggers for different MCP components, while actually using
+ * the same underlying logger instance.
+ */
 export declare const mcpLogger: NeuroLinkLogger;
 export declare const autoDiscoveryLogger: NeuroLinkLogger;
 export declare const registryLogger: NeuroLinkLogger;
 export declare const unifiedRegistryLogger: NeuroLinkLogger;
+/**
+ * Sets the global log level for all MCP-related logging.
+ * This function provides a convenient way to adjust logging verbosity
+ * for all MCP components at once.
+ *
+ * @param level - The log level to set ("debug", "info", "warn", or "error")
+ */
 export declare function setGlobalMCPLogLevel(level: LogLevel): void;
+/**
+ * Export LogLevel enum for runtime use.
+ * Provides type-safe log level constants for use in application code.
+ *
+ * Example usage:
+ * ```
+ * import { logger, LogLevels } from './logger';  // Import from your project's path
+ *
+ * // Using the LogLevels constants (recommended for type safety):
+ * logger.setLogLevel(LogLevels.debug);
+ *
+ * // Or directly using string values:
+ * logger.setLogLevel('debug');
+ * ```
+ */
 export declare const LogLevels: {
     readonly debug: "debug";
     readonly info: "info";

package/dist/lib/utils/logger.js

@@ -1,9 +1,17 @@
 /**
  * NeuroLink Unified Logger Utility
  *
- * Centralized logging for the entire NeuroLink ecosystem
- * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable
- * Migrated from MCP logging with enhanced features
+ * Centralized logging for the entire NeuroLink ecosystem.
+ * Provides structured logging with different severity levels and consistent formatting.
+ * Supports both CLI --debug flag and NEUROLINK_DEBUG environment variable.
+ * Maintains compatibility with MCP logging while providing enhanced features.
+ *
+ * Features:
+ * - Multiple log levels (debug, info, warn, error)
+ * - Log history retention with configurable limits
+ * - Conditional logging based on environment settings
+ * - Structured data support for complex objects
+ * - Tabular data display
  */
 // Pre-computed uppercase log levels for performance optimization
 const UPPERCASE_LOG_LEVELS = {
@@ -28,9 +36,26 @@ class NeuroLinkLogger {
             this.logLevel = envLevel;
         }
     }
+    /**
+     * Sets the minimum log level that will be processed and output.
+     * Log messages with a level lower than this will be ignored.
+     *
+     * @param level - The minimum log level to process ("debug", "info", "warn", or "error")
+     */
     setLogLevel(level) {
         this.logLevel = level;
     }
+    /**
+     * Determines whether a message with the given log level should be processed.
+     * This method considers both the configured log level and the current debug mode.
+     *
+     * Logic:
+     * 1. If not in debug mode, only error messages are allowed
+     * 2. If in debug mode, messages at or above the configured log level are allowed
+     *
+     * @param level - The log level to check
+     * @returns True if a message with this level should be logged, false otherwise
+     */
     shouldLog(level) {
         // Dynamic debug mode check to handle CLI middleware timing
         const currentDebugMode = process.argv.includes("--debug") ||
@@ -42,6 +67,14 @@ class NeuroLinkLogger {
         const levels = ["debug", "info", "warn", "error"];
         return levels.indexOf(level) >= levels.indexOf(this.logLevel);
     }
+    /**
+     * Generates a standardized prefix for log messages.
+     * The prefix includes a timestamp and the log level in a consistent format.
+     *
+     * @param timestamp - ISO string representation of the log timestamp
+     * @param level - The log level for this message
+     * @returns Formatted prefix string like "[2025-08-18T13:45:30.123Z] [NEUROLINK:ERROR]"
+     */
     getLogPrefix(timestamp, level) {
         return `[${timestamp}] [NEUROLINK:${UPPERCASE_LOG_LEVELS[level]}]`;
     }
@@ -67,6 +100,19 @@ class NeuroLinkLogger {
             logMethod(prefix, message);
         }
     }
+    /**
+     * Core internal logging method that handles:
+     * 1. Creating log entries with consistent format
+     * 2. Storing entries in the log history
+     * 3. Managing log rotation to prevent memory issues
+     * 4. Outputting formatted logs to the console
+     *
+     * This is the central method called by all specific logging methods (debug, info, etc.)
+     *
+     * @param level - The severity level for this log entry
+     * @param message - The message text to log
+     * @param data - Optional additional context data to include
+     */
     log(level, message, data) {
         if (!this.shouldLog(level)) {
             return;
@@ -88,24 +134,63 @@ class NeuroLinkLogger {
         const prefix = this.getLogPrefix(timestamp, level);
         this.outputToConsole(level, prefix, message, data);
     }
+    /**
+     * Logs a message at the debug level.
+     * Used for detailed troubleshooting information.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     debug(message, data) {
         this.log("debug", message, data);
     }
+    /**
+     * Logs a message at the info level.
+     * Used for general information about system operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     info(message, data) {
         this.log("info", message, data);
     }
+    /**
+     * Logs a message at the warn level.
+     * Used for potentially problematic situations that don't prevent operation.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     warn(message, data) {
         this.log("warn", message, data);
     }
+    /**
+     * Logs a message at the error level.
+     * Used for critical issues that may cause failures.
+     *
+     * @param message - The message to log
+     * @param data - Optional additional context data
+     */
     error(message, data) {
         this.log("error", message, data);
     }
+    /**
+     * Retrieves stored log entries, optionally filtered by log level.
+     * Returns a copy of the log entries to prevent external modification.
+     *
+     * @param level - Optional log level to filter by
+     * @returns Array of log entries, either all or filtered by level
+     */
     getLogs(level) {
         if (level) {
             return this.logs.filter((log) => log.level === level);
         }
         return [...this.logs];
     }
+    /**
+     * Removes all stored log entries.
+     * Useful for testing or when log history is no longer needed.
+     */
     clearLogs() {
         this.logs = [];
     }
@@ -116,6 +201,14 @@ class NeuroLinkLogger {
      * It bypasses the structured logging mechanism and should only be used when
      * unstructured, unconditional logging is required.
      *
+     * Use with caution in production environments as it outputs to the console
+     * regardless of the current log level or debug mode settings.
+     *
+     * Use cases:
+     * - Critical system information that must always be visible
+     * - Status messages during initialization before logging is fully configured
+     * - Debugging in environments where normal logging might be suppressed
+     *
      * @param args - The arguments to log. These are passed directly to `console.log`.
      */
     always(...args) {
@@ -124,15 +217,41 @@ class NeuroLinkLogger {
     /**
      * Displays tabular data unconditionally using `console.table`.
      *
-     * @param data - The data to display in table format
+     * Similar to the `always` method, this bypasses log level checks and
+     * will display data regardless of current logging settings.
+     *
+     * Important differences from other logging methods:
+     * - Does NOT store entries in the log history
+     * - Does NOT use the structured logging format with timestamps and prefixes
+     * - Outputs directly to console without additional formatting
+     *
+     * Particularly useful for:
+     * - Displaying structured data in a readable format during debugging
+     * - Showing configuration options and their current values
+     * - Presenting comparison data between different system states
+     * - Performance metrics and timing data
+     *
+     * @param data - The data to display in table format. Can be an array of objects or an object with key-value pairs.
      */
     table(data) {
         console.table(data);
     }
 }
-// Export singleton instance
+// Export singleton instance to ensure consistent logging across the application
 const neuroLinkLogger = new NeuroLinkLogger();
-// Helper function to process arguments with minimal overhead
+/**
+ * Helper function to process logger arguments with minimal overhead.
+ * Handles variable argument patterns and ensures safe serialization of objects.
+ *
+ * This function:
+ * 1. Extracts the first argument as the message
+ * 2. Handles serialization of non-string first arguments
+ * 3. Collects remaining arguments as additional data
+ * 4. Passes the processed arguments to the actual logging method
+ *
+ * @param args - Array of arguments passed to the logger
+ * @param logMethod - Function that will perform the actual logging
+ */
 function processLoggerArgs(args, logMethod) {
     if (args.length === 0) {
         return;
@@ -149,7 +268,16 @@ function processLoggerArgs(args, logMethod) {
     const data = args.length === 2 ? args[1] : args.length > 2 ? args.slice(1) : undefined;
     logMethod(message, data);
 }
-// Main unified logger export
+/**
+ * Main unified logger export that provides a simplified API for logging.
+ * This is the primary interface that should be used by application code.
+ *
+ * Features:
+ * - Convenient logging methods (debug, info, warn, error)
+ * - Unconditional logging (always, table)
+ * - Log level control and configuration
+ * - Log history management
+ */
 export const logger = {
     debug: (...args) => {
         if (neuroLinkLogger.shouldLog("debug")) {
@@ -182,16 +310,41 @@ export const logger = {
     getLogs: (level) => neuroLinkLogger.getLogs(level),
     clearLogs: () => neuroLinkLogger.clearLogs(),
 };
-// MCP compatibility exports - all use the same unified logger
+/**
+ * MCP compatibility exports - all use the same unified logger instance.
+ * These exports maintain backward compatibility with code that expects
+ * separate loggers for different MCP components, while actually using
+ * the same underlying logger instance.
+ */
 export const mcpLogger = neuroLinkLogger;
 export const autoDiscoveryLogger = neuroLinkLogger;
 export const registryLogger = neuroLinkLogger;
 export const unifiedRegistryLogger = neuroLinkLogger;
-// Global log level setter
+/**
+ * Sets the global log level for all MCP-related logging.
+ * This function provides a convenient way to adjust logging verbosity
+ * for all MCP components at once.
+ *
+ * @param level - The log level to set ("debug", "info", "warn", or "error")
+ */
 export function setGlobalMCPLogLevel(level) {
     neuroLinkLogger.setLogLevel(level);
 }
-// Export LogLevel enum for runtime use
+/**
+ * Export LogLevel enum for runtime use.
+ * Provides type-safe log level constants for use in application code.
+ *
+ * Example usage:
+ * ```
+ * import { logger, LogLevels } from './logger';  // Import from your project's path
+ *
+ * // Using the LogLevels constants (recommended for type safety):
+ * logger.setLogLevel(LogLevels.debug);
+ *
+ * // Or directly using string values:
+ * logger.setLogLevel('debug');
+ * ```
+ */
 export const LogLevels = {
     debug: "debug",
     info: "info",

package/dist/lib/utils/providerUtils.js

@@ -14,21 +14,24 @@ import { ProviderHealthChecker } from "./providerHealth.js";
 export async function getBestProvider(requestedProvider) {
     // Check requested provider FIRST - explicit user choice overrides defaults
     if (requestedProvider && requestedProvider !== "auto") {
-        // For explicit provider requests, check health first
+        // For explicit provider requests, ALWAYS honor the request
+        // Never override explicit provider selection with health-based fallbacks
+        logger.debug(`[getBestProvider] Using explicitly requested provider: ${requestedProvider}`);
+        // Optional health check for logging purposes only
         try {
             const health = await ProviderHealthChecker.checkProviderHealth(requestedProvider, { includeConnectivityTest: false, cacheResults: true });
             if (health.isHealthy) {
-                logger.debug(`[getBestProvider] Using healthy explicitly requested provider: ${requestedProvider}`);
-                return requestedProvider;
+                logger.debug(`[getBestProvider] Explicitly requested provider ${requestedProvider} is healthy`);
             }
             else {
-                logger.warn(`[getBestProvider] Requested provider ${requestedProvider} is unhealthy, finding alternative`, { error: health.error });
+                logger.warn(`[getBestProvider] Explicitly requested provider ${requestedProvider} may have issues, but using anyway`, { error: health.error });
             }
         }
         catch (error) {
-            logger.warn(`[getBestProvider] Health check failed for ${requestedProvider}, using anyway`, { error: error instanceof Error ? error.message : String(error) });
-            return requestedProvider; // Return anyway for explicit requests
+            logger.warn(`[getBestProvider] Health check failed for explicitly requested provider ${requestedProvider}, using anyway`, { error: error instanceof Error ? error.message : String(error) });
         }
+        // ALWAYS return the explicitly requested provider
+        return requestedProvider;
     }
     // Use health checker to get best available provider
     const healthyProvider = await ProviderHealthChecker.getBestHealthyProvider();

package/dist/middleware/builtin/analytics.d.ts

@@ -1,4 +1,4 @@
-import type { NeuroLinkMiddleware } from "../types.js";
+import type { NeuroLinkMiddleware } from "../../types/middlewareTypes.js";
 /**
  * Create analytics middleware for tracking AI model usage
  * Collects metrics on token usage, response times, and model performance

package/dist/middleware/builtin/guardrails.d.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV1 } from "ai";
-import type { NeuroLinkMiddleware } from "../types.js";
+import type { NeuroLinkMiddleware } from "../../types/middlewareTypes.js";
 /**
  * Configuration for the Guardrails middleware.
  */

package/dist/middleware/factory.d.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV1 } from "ai";
-import type { MiddlewareContext, MiddlewareConfig, MiddlewareFactoryOptions, MiddlewareChainStats, MiddlewarePreset, NeuroLinkMiddleware, MiddlewareRegistrationOptions } from "./types.js";
+import type { MiddlewareContext, MiddlewareConfig, MiddlewareFactoryOptions, MiddlewareChainStats, MiddlewarePreset, NeuroLinkMiddleware, MiddlewareRegistrationOptions } from "../types/middlewareTypes.js";
 import { MiddlewareRegistry } from "./registry.js";
 /**
  * Middleware factory for creating and applying middleware chains.

package/dist/middleware/index.d.ts

@@ -6,7 +6,7 @@
  * of language models with features like analytics, guardrails, caching, and more.
  */
 import { MiddlewareFactory } from "./factory.js";
-export type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareConditions, MiddlewareRegistrationOptions, MiddlewareExecutionResult, MiddlewareChainStats, MiddlewarePreset, MiddlewareFactoryOptions, BuiltInMiddlewareType, } from "./types.js";
+export type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareConditions, MiddlewareRegistrationOptions, MiddlewareExecutionResult, MiddlewareChainStats, MiddlewarePreset, MiddlewareFactoryOptions, BuiltInMiddlewareType, } from "../types/middlewareTypes.js";
 export type { LanguageModelV1Middleware } from "ai";
 export { MiddlewareFactory };
 export default MiddlewareFactory;

package/dist/middleware/registry.d.ts

@@ -1,5 +1,5 @@
 import type { LanguageModelV1Middleware } from "ai";
-import type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareRegistrationOptions, MiddlewareExecutionResult } from "./types.js";
+import type { NeuroLinkMiddleware, MiddlewareConfig, MiddlewareContext, MiddlewareRegistrationOptions, MiddlewareExecutionResult } from "../types/middlewareTypes.js";
 /**
  * Manages the registration, configuration, and execution of middleware for a single factory instance.
  */