@juspay/neurolink 7.28.1 → 7.29.1

package/dist/middleware/index.js

@@ -5,63 +5,9 @@
  * 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 types and classes
 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);
-}
+export { MiddlewareFactory };
+// Export the factory as the default export for clean, direct usage
+export default MiddlewareFactory;

package/dist/middleware/registry.d.ts

@@ -1,8 +1,7 @@
 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
+ * Manages the registration, configuration, and execution of middleware for a single factory instance.
  */
 export declare class MiddlewareRegistry {
     private middleware;
@@ -75,4 +74,3 @@ export declare class MiddlewareRegistry {
      */
     clear(): void;
 }
-export declare const middlewareRegistry: MiddlewareRegistry;

package/dist/middleware/registry.js

@@ -1,7 +1,6 @@
 import { logger } from "../utils/logger.js";
 /**
- * Global middleware registry for NeuroLink
- * Manages registration, configuration, and execution of middleware
+ * Manages the registration, configuration, and execution of middleware for a single factory instance.
  */
 export class MiddlewareRegistry {
     middleware = new Map();
@@ -143,7 +142,9 @@ export class MiddlewareRegistry {
             ...config?.config,
         };
         // Create wrapper that tracks execution
-        const wrappedMiddleware = {};
+        const wrappedMiddleware = {
+            metadata: middleware.metadata,
+        };
         if (middleware.transformParams) {
             wrappedMiddleware.transformParams = async (args) => {
                 const startTime = Date.now();
@@ -279,5 +280,3 @@ export class MiddlewareRegistry {
         logger.debug("All middleware cleared from registry");
     }
 }
-// Global middleware registry instance
-export const middlewareRegistry = new MiddlewareRegistry();

package/dist/middleware/types.d.ts

@@ -118,12 +118,14 @@ export interface MiddlewarePreset {
     /** Description of the preset */
     description: string;
     /** Middleware configurations in the preset */
-    middleware: Record<string, MiddlewareConfig>;
+    config: Record<string, MiddlewareConfig>;
 }
 /**
  * Factory options for middleware
  */
 export interface MiddlewareFactoryOptions {
+    /** Custom middleware to register on initialization */
+    middleware?: NeuroLinkMiddleware[];
     /** Enable specific middleware */
     enabledMiddleware?: string[];
     /** Disable specific middleware */

package/dist/neurolink.d.ts

@@ -57,6 +57,34 @@ export declare class NeuroLink {
      */
     private emitToolEndEvent;
     private conversationMemory?;
+    /**
+     * Creates a new NeuroLink instance for AI text generation with MCP tool integration.
+     *
+     * @param config - Optional configuration object
+     * @param config.conversationMemory - Configuration for conversation memory features
+     * @param config.conversationMemory.enabled - Whether to enable conversation memory (default: false)
+     * @param config.conversationMemory.maxSessions - Maximum number of concurrent sessions (default: 100)
+     * @param config.conversationMemory.maxTurnsPerSession - Maximum conversation turns per session (default: 50)
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const neurolink = new NeuroLink();
+     *
+     * // With conversation memory
+     * const neurolink = new NeuroLink({
+     *   conversationMemory: {
+     *     enabled: true,
+     *     maxSessions: 50,
+     *     maxTurnsPerSession: 20
+     *   }
+     * });
+     * ```
+     *
+     * @throws {Error} When provider registry setup fails
+     * @throws {Error} When conversation memory initialization fails (if enabled)
+     * @throws {Error} When external server manager initialization fails
+     */
     constructor(config?: {
         conversationMemory?: Partial<ConversationMemoryConfig>;
     });
@@ -84,6 +112,54 @@ export declare class NeuroLink {
      * @param config Optional configuration to override default summarization settings.
      */
     enableContextSummarization(config?: Partial<ContextManagerConfig>): void;
+    /**
+     * Generate AI content using the best available provider with MCP tool integration.
+     * This is the primary method for text generation with full feature support.
+     *
+     * @param optionsOrPrompt - Either a string prompt or a comprehensive GenerateOptions object
+     * @param optionsOrPrompt.input - Input configuration object
+     * @param optionsOrPrompt.input.text - The text prompt to send to the AI (required)
+     * @param optionsOrPrompt.provider - AI provider to use ('auto', 'openai', 'anthropic', etc.)
+     * @param optionsOrPrompt.model - Specific model to use (e.g., 'gpt-4', 'claude-3-opus')
+     * @param optionsOrPrompt.temperature - Randomness in response (0.0 = deterministic, 2.0 = very random)
+     * @param optionsOrPrompt.maxTokens - Maximum tokens in response
+     * @param optionsOrPrompt.systemPrompt - System message to set AI behavior
+     * @param optionsOrPrompt.disableTools - Whether to disable MCP tool usage
+     * @param optionsOrPrompt.enableAnalytics - Whether to include usage analytics
+     * @param optionsOrPrompt.enableEvaluation - Whether to include response quality evaluation
+     * @param optionsOrPrompt.context - Additional context for the request
+     * @param optionsOrPrompt.evaluationDomain - Domain for specialized evaluation
+     * @param optionsOrPrompt.toolUsageContext - Context for tool usage decisions
+     *
+     * @returns Promise resolving to GenerateResult with content, usage data, and optional analytics
+     *
+     * @example
+     * ```typescript
+     * // Simple usage with string prompt
+     * const result = await neurolink.generate("What is artificial intelligence?");
+     * console.log(result.content);
+     *
+     * // Advanced usage with options
+     * const result = await neurolink.generate({
+     *   input: { text: "Explain quantum computing" },
+     *   provider: "openai",
+     *   model: "gpt-4",
+     *   temperature: 0.7,
+     *   maxTokens: 500,
+     *   enableAnalytics: true,
+     *   enableEvaluation: true,
+     *   context: { domain: "science", level: "intermediate" }
+     * });
+     *
+     * // Access analytics and evaluation data
+     * console.log(result.analytics?.usage);
+     * console.log(result.evaluation?.relevance);
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When conversation memory operations fail (if enabled)
+     */
     generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method
@@ -128,13 +204,230 @@ export declare class NeuroLink {
      */
     streamText(prompt: string, options?: Partial<StreamOptions>): Promise<AsyncIterable<string>>;
     /**
-     * PRIMARY METHOD: Stream content using AI (recommended for new code)
-     * Future-ready for multi-modal capabilities with current text focus
+     * Stream AI-generated content in real-time using the best available provider.
+     * This method provides real-time streaming of AI responses with full MCP tool integration.
+     *
+     * @param options - Stream configuration options
+     * @param options.input - Input configuration object
+     * @param options.input.text - The text prompt to send to the AI (required)
+     * @param options.provider - AI provider to use ('auto', 'openai', 'anthropic', etc.)
+     * @param options.model - Specific model to use (e.g., 'gpt-4', 'claude-3-opus')
+     * @param options.temperature - Randomness in response (0.0 = deterministic, 2.0 = very random)
+     * @param options.maxTokens - Maximum tokens in response
+     * @param options.systemPrompt - System message to set AI behavior
+     * @param options.disableTools - Whether to disable MCP tool usage
+     * @param options.enableAnalytics - Whether to include usage analytics
+     * @param options.enableEvaluation - Whether to include response quality evaluation
+     * @param options.context - Additional context for the request
+     * @param options.evaluationDomain - Domain for specialized evaluation
+     *
+     * @returns Promise resolving to StreamResult with an async iterable stream
+     *
+     * @example
+     * ```typescript
+     * // Basic streaming usage
+     * const result = await neurolink.stream({
+     *   input: { text: "Tell me a story about space exploration" }
+     * });
+     *
+     * // Consume the stream
+     * for await (const chunk of result.stream) {
+     *   process.stdout.write(chunk.content);
+     * }
+     *
+     * // Advanced streaming with options
+     * const result = await neurolink.stream({
+     *   input: { text: "Explain machine learning" },
+     *   provider: "openai",
+     *   model: "gpt-4",
+     *   temperature: 0.7,
+     *   enableAnalytics: true,
+     *   context: { domain: "education", audience: "beginners" }
+     * });
+     *
+     * // Access metadata and analytics
+     * console.log(result.provider);
+     * console.log(result.analytics?.usage);
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When conversation memory operations fail (if enabled)
      */
     stream(options: StreamOptions): Promise<StreamResult>;
     /**
-     * Get the EventEmitter to listen to NeuroLink events
-     * @returns EventEmitter instance
+     * Get the EventEmitter instance to listen to NeuroLink events for real-time monitoring and debugging.
+     * This method provides access to the internal event system that emits events during AI generation,
+     * tool execution, streaming, and other operations for comprehensive observability.
+     *
+     * @returns EventEmitter instance that emits various NeuroLink operation events
+     *
+     * @example
+     * ```typescript
+     * // Basic event listening setup
+     * const neurolink = new NeuroLink();
+     * const emitter = neurolink.getEventEmitter();
+     *
+     * // Listen to generation events
+     * emitter.on('generation:start', (event) => {
+     *   console.log(`Generation started with provider: ${event.provider}`);
+     *   console.log(`Started at: ${new Date(event.timestamp)}`);
+     * });
+     *
+     * emitter.on('generation:end', (event) => {
+     *   console.log(`Generation completed in ${event.responseTime}ms`);
+     *   console.log(`Tools used: ${event.toolsUsed?.length || 0}`);
+     * });
+     *
+     * // Listen to streaming events
+     * emitter.on('stream:start', (event) => {
+     *   console.log(`Streaming started with provider: ${event.provider}`);
+     * });
+     *
+     * emitter.on('stream:end', (event) => {
+     *   console.log(`Streaming completed in ${event.responseTime}ms`);
+     *   if (event.fallback) console.log('Used fallback streaming');
+     * });
+     *
+     * // Listen to tool execution events
+     * emitter.on('tool:start', (event) => {
+     *   console.log(`Tool execution started: ${event.toolName}`);
+     * });
+     *
+     * emitter.on('tool:end', (event) => {
+     *   console.log(`Tool ${event.toolName} ${event.success ? 'succeeded' : 'failed'}`);
+     *   console.log(`Execution time: ${event.responseTime}ms`);
+     * });
+     *
+     * // Listen to tool registration events
+     * emitter.on('tools-register:start', (event) => {
+     *   console.log(`Registering tool: ${event.toolName}`);
+     * });
+     *
+     * emitter.on('tools-register:end', (event) => {
+     *   console.log(`Tool registration ${event.success ? 'succeeded' : 'failed'}: ${event.toolName}`);
+     * });
+     *
+     * // Listen to external MCP server events
+     * emitter.on('externalMCP:serverConnected', (event) => {
+     *   console.log(`External MCP server connected: ${event.serverId}`);
+     *   console.log(`Tools available: ${event.toolCount || 0}`);
+     * });
+     *
+     * emitter.on('externalMCP:serverDisconnected', (event) => {
+     *   console.log(`External MCP server disconnected: ${event.serverId}`);
+     *   console.log(`Reason: ${event.reason || 'Unknown'}`);
+     * });
+     *
+     * emitter.on('externalMCP:toolDiscovered', (event) => {
+     *   console.log(`New tool discovered: ${event.toolName} from ${event.serverId}`);
+     * });
+     *
+     * // Advanced usage with error handling
+     * emitter.on('error', (error) => {
+     *   console.error('NeuroLink error:', error);
+     * });
+     *
+     * // Clean up event listeners when done
+     * function cleanup() {
+     *   emitter.removeAllListeners();
+     * }
+     *
+     * process.on('SIGINT', cleanup);
+     * process.on('SIGTERM', cleanup);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Advanced monitoring with metrics collection
+     * const neurolink = new NeuroLink();
+     * const emitter = neurolink.getEventEmitter();
+     * const metrics = {
+     *   generations: 0,
+     *   totalResponseTime: 0,
+     *   toolExecutions: 0,
+     *   failures: 0
+     * };
+     *
+     * // Collect performance metrics
+     * emitter.on('generation:end', (event) => {
+     *   metrics.generations++;
+     *   metrics.totalResponseTime += event.responseTime;
+     *   metrics.toolExecutions += event.toolsUsed?.length || 0;
+     * });
+     *
+     * emitter.on('tool:end', (event) => {
+     *   if (!event.success) {
+     *     metrics.failures++;
+     *   }
+     * });
+     *
+     * // Log metrics every 10 seconds
+     * setInterval(() => {
+     *   const avgResponseTime = metrics.generations > 0
+     *     ? metrics.totalResponseTime / metrics.generations
+     *     : 0;
+     *
+     *   console.log('NeuroLink Metrics:', {
+     *     totalGenerations: metrics.generations,
+     *     averageResponseTime: `${avgResponseTime.toFixed(2)}ms`,
+     *     totalToolExecutions: metrics.toolExecutions,
+     *     failureRate: `${((metrics.failures / (metrics.toolExecutions || 1)) * 100).toFixed(2)}%`
+     *   });
+     * }, 10000);
+     * ```
+     *
+     * **Available Events:**
+     *
+     * **Generation Events:**
+     * - `generation:start` - Fired when text generation begins
+     *   - `{ provider: string, timestamp: number }`
+     * - `generation:end` - Fired when text generation completes
+     *   - `{ provider: string, responseTime: number, toolsUsed?: string[], timestamp: number }`
+     *
+     * **Streaming Events:**
+     * - `stream:start` - Fired when streaming begins
+     *   - `{ provider: string, timestamp: number }`
+     * - `stream:end` - Fired when streaming completes
+     *   - `{ provider: string, responseTime: number, fallback?: boolean }`
+     *
+     * **Tool Events:**
+     * - `tool:start` - Fired when tool execution begins
+     *   - `{ toolName: string, timestamp: number }`
+     * - `tool:end` - Fired when tool execution completes
+     *   - `{ toolName: string, responseTime: number, success: boolean, timestamp: number }`
+     * - `tools-register:start` - Fired when tool registration begins
+     *   - `{ toolName: string, timestamp: number }`
+     * - `tools-register:end` - Fired when tool registration completes
+     *   - `{ toolName: string, success: boolean, timestamp: number }`
+     *
+     * **External MCP Events:**
+     * - `externalMCP:serverConnected` - Fired when external MCP server connects
+     *   - `{ serverId: string, toolCount?: number, timestamp: number }`
+     * - `externalMCP:serverDisconnected` - Fired when external MCP server disconnects
+     *   - `{ serverId: string, reason?: string, timestamp: number }`
+     * - `externalMCP:serverFailed` - Fired when external MCP server fails
+     *   - `{ serverId: string, error: string, timestamp: number }`
+     * - `externalMCP:toolDiscovered` - Fired when external MCP tool is discovered
+     *   - `{ toolName: string, serverId: string, timestamp: number }`
+     * - `externalMCP:toolRemoved` - Fired when external MCP tool is removed
+     *   - `{ toolName: string, serverId: string, timestamp: number }`
+     * - `externalMCP:serverAdded` - Fired when external MCP server is added
+     *   - `{ serverId: string, config: MCPServerInfo, toolCount: number, timestamp: number }`
+     * - `externalMCP:serverRemoved` - Fired when external MCP server is removed
+     *   - `{ serverId: string, timestamp: number }`
+     *
+     * **Error Events:**
+     * - `error` - Fired when an error occurs
+     *   - `{ error: Error, context?: object }`
+     *
+     * @throws {Error} This method does not throw errors as it returns the internal EventEmitter
+     *
+     * @since 1.0.0
+     * @see {@link https://nodejs.org/api/events.html} Node.js EventEmitter documentation
+     * @see {@link NeuroLink.generate} for events related to text generation
+     * @see {@link NeuroLink.stream} for events related to streaming
+     * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): EventEmitter<[never]>;
     /**