@juspay/neurolink 8.32.0 → 8.34.0

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

@@ -89,6 +89,14 @@ export declare class ErrorFactory {
      * Create a memory exhaustion error
      */
     static memoryExhausted(toolName: string, memoryUsageMB: number): NeuroLinkError;
+    /**
+     * Create a missing configuration error (e.g., missing API key)
+     */
+    static missingConfiguration(configName: string, context?: Record<string, unknown>): NeuroLinkError;
+    /**
+     * Create an invalid configuration error (e.g., NaN for numeric values)
+     */
+    static invalidConfiguration(configName: string, reason: string, context?: Record<string, unknown>): NeuroLinkError;
     /**
      * Create an invalid video resolution error
      */

package/dist/lib/utils/errorHandling.js

@@ -180,6 +180,35 @@ export class ErrorFactory {
         });
     }
     // ============================================================================
+    // CONFIGURATION ERRORS
+    // ============================================================================
+    /**
+     * Create a missing configuration error (e.g., missing API key)
+     */
+    static missingConfiguration(configName, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.MISSING_CONFIGURATION,
+            message: `Missing required configuration: ${configName}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
+    /**
+     * Create an invalid configuration error (e.g., NaN for numeric values)
+     */
+    static invalidConfiguration(configName, reason, context) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_CONFIGURATION,
+            message: `Invalid configuration for '${configName}': ${reason}`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: context || {},
+        });
+    }
+    // ============================================================================
     // VIDEO VALIDATION ERRORS
     // ============================================================================
     /**

package/dist/mcp/externalServerManager.js

@@ -14,6 +14,36 @@ import { toolRegistry } from "./toolRegistry.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
 import { isObject, isNonNullObject } from "../utils/typeUtils.js";
+/**
+ * Recursively substitute environment variables in strings
+ * Replaces ${VAR_NAME} with the value from process.env.VAR_NAME
+ * @param value - Value to process (string, object, array, or primitive)
+ * @returns Processed value with environment variables substituted
+ */
+function substituteEnvVariables(value) {
+    if (typeof value === "string") {
+        // Replace ${VAR_NAME} with process.env.VAR_NAME
+        return value.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+            const envValue = process.env[varName.trim()];
+            if (envValue === undefined) {
+                mcpLogger.warn(`[ExternalServerManager] Environment variable ${varName} is not defined, using empty string`);
+                return "";
+            }
+            return envValue;
+        });
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => substituteEnvVariables(item));
+    }
+    if (isNonNullObject(value)) {
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+            result[key] = substituteEnvVariables(val);
+        }
+        return result;
+    }
+    return value;
+}
 /**
  * Type guard to validate if an object can be safely used as Record<string, JsonValue>
  */
@@ -211,7 +241,7 @@ export class ExternalServerManager extends EventEmitter {
                             ? serverConfig.args
                             : [],
                         env: isNonNullObject(serverConfig.env)
-                            ? serverConfig.env
+                            ? substituteEnvVariables(serverConfig.env)
                             : {},
                         timeout: typeof serverConfig.timeout === "number"
                             ? serverConfig.timeout
@@ -233,7 +263,7 @@ export class ExternalServerManager extends EventEmitter {
                             : undefined,
                         // HTTP transport-specific fields
                         headers: isNonNullObject(serverConfig.headers)
-                            ? serverConfig.headers
+                            ? substituteEnvVariables(serverConfig.headers)
                             : undefined,
                         httpOptions: isNonNullObject(serverConfig.httpOptions)
                             ? serverConfig.httpOptions
@@ -342,7 +372,7 @@ export class ExternalServerManager extends EventEmitter {
                             ? serverConfig.args
                             : [],
                         env: isNonNullObject(serverConfig.env)
-                            ? serverConfig.env
+                            ? substituteEnvVariables(serverConfig.env)
                             : {},
                         timeout: typeof serverConfig.timeout === "number"
                             ? serverConfig.timeout
@@ -364,7 +394,7 @@ export class ExternalServerManager extends EventEmitter {
                             : undefined,
                         // HTTP transport-specific fields
                         headers: isNonNullObject(serverConfig.headers)
-                            ? serverConfig.headers
+                            ? substituteEnvVariables(serverConfig.headers)
                             : undefined,
                         httpOptions: isNonNullObject(serverConfig.httpOptions)
                             ? serverConfig.httpOptions
@@ -1108,7 +1138,7 @@ export class ExternalServerManager extends EventEmitter {
         }
         try {
             mcpLogger.debug(`[ExternalServerManager] Discovering tools for server: ${serverId}`);
-            const discoveryResult = await this.toolDiscovery.discoverTools(serverId, instance.client, this.config.defaultTimeout);
+            const discoveryResult = await this.toolDiscovery.discoverTools(serverId, instance.client, instance.config.timeout || this.config.defaultTimeout);
             if (discoveryResult.success) {
                 instance.toolsMap.clear();
                 instance.toolsArray = undefined;
@@ -1164,7 +1194,9 @@ export class ExternalServerManager extends EventEmitter {
                     registrations.push(toolRegistry.registerTool(toolId, toolInfo, {
                         execute: async (params, _context) => {
                             // Execute tool via ExternalServerManager for proper lifecycle management
-                            return await this.executeTool(serverId, toolName, params, { timeout: this.config.defaultTimeout });
+                            return await this.executeTool(serverId, toolName, params, {
+                                timeout: instance.config.timeout || this.config.defaultTimeout,
+                            });
                         },
                     }));
                     mcpLogger.debug(`[ExternalServerManager] Registered tool with main registry: ${toolId}`);
@@ -1277,7 +1309,9 @@ export class ExternalServerManager extends EventEmitter {
             }
             // Execute tool through discovery service (with potentially modified parameters)
             const result = await this.toolDiscovery.executeTool(toolName, serverId, instance.client, finalParameters, {
-                timeout: options?.timeout || this.config.defaultTimeout,
+                timeout: options?.timeout ||
+                    instance.config.timeout ||
+                    this.config.defaultTimeout,
             });
             const duration = Date.now() - startTime;
             // Update metrics

package/dist/neurolink.d.ts

@@ -20,6 +20,78 @@ import { RedisConversationMemoryManager } from "./core/redisConversationMemoryMa
 import type { ExternalMCPServerInstance, ExternalMCPOperationResult, ExternalMCPToolInfo } from "./types/externalMcp.js";
 import type { ObservabilityConfig } from "./types/observability.js";
 import type { NeurolinkConstructorConfig } from "./types/configTypes.js";
+/**
+ * NeuroLink - Universal AI Development Platform
+ *
+ * Main SDK class providing unified access to 13+ AI providers with enterprise features:
+ * - Multi-provider support (OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, etc.)
+ * - MCP (Model Context Protocol) tool integration with 58+ external servers
+ * - Human-in-the-Loop (HITL) security workflows for regulated industries
+ * - Redis-based conversation memory and persistence
+ * - Enterprise middleware system for monitoring and control
+ * - Automatic provider fallback and retry logic
+ * - Streaming with real-time token delivery
+ * - Multimodal support (text, images, PDFs, CSV)
+ *
+ * @category Core
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { NeuroLink } from '@juspay/neurolink';
+ *
+ * const neurolink = new NeuroLink();
+ *
+ * const result = await neurolink.generate({
+ *   input: { text: 'Explain quantum computing' },
+ *   provider: 'vertex',
+ *   model: 'gemini-3-flash'
+ * });
+ *
+ * console.log(result.content);
+ * ```
+ *
+ * @example With HITL security
+ * ```typescript
+ * const neurolink = new NeuroLink({
+ *   hitl: {
+ *     enabled: true,
+ *     requireApproval: ['writeFile', 'executeCode'],
+ *     confidenceThreshold: 0.85
+ *   }
+ * });
+ * ```
+ *
+ * @example With Redis memory
+ * ```typescript
+ * const neurolink = new NeuroLink({
+ *   conversationMemory: {
+ *     enabled: true,
+ *     redis: {
+ *       url: 'redis://localhost:6379'
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example With MCP tools
+ * ```typescript
+ * const neurolink = new NeuroLink();
+ *
+ * // Discover available tools
+ * const tools = await neurolink.getAvailableTools();
+ *
+ * // Use tools in generation
+ * const result = await neurolink.generate({
+ *   input: { text: 'Read the README.md file' },
+ *   tools: ['readFile']
+ * });
+ * ```
+ *
+ * @see {@link GenerateOptions} for generation options
+ * @see {@link StreamOptions} for streaming options
+ * @see {@link NeurolinkConstructorConfig} for configuration options
+ * @since 1.0.0
+ */
 export declare class NeuroLink {
     private mcpInitialized;
     private emitter;
@@ -281,6 +353,106 @@ export declare class NeuroLink {
      * Gracefully shutdown NeuroLink and all MCP connections
      */
     shutdown(): Promise<void>;
+    /**
+     * Generate AI response with comprehensive feature support.
+     *
+     * Primary method for AI generation with support for all NeuroLink features:
+     * - Multi-provider support (13+ providers)
+     * - MCP tool integration
+     * - Structured JSON output with Zod schemas
+     * - Conversation memory (Redis or in-memory)
+     * - HITL security workflows
+     * - Middleware execution
+     * - Multimodal inputs (images, PDFs, CSV)
+     *
+     * @category Generation
+     *
+     * @param optionsOrPrompt - Generation options or simple text prompt
+     * @param optionsOrPrompt.input - Input text and optional files
+     * @param optionsOrPrompt.provider - AI provider name (e.g., 'vertex', 'openai', 'anthropic')
+     * @param optionsOrPrompt.model - Model name to use
+     * @param optionsOrPrompt.tools - MCP tools to enable for this generation
+     * @param optionsOrPrompt.schema - Zod schema for structured output validation
+     * @param optionsOrPrompt.temperature - Sampling temperature (0-2, default: 1.0)
+     * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
+     * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
+     * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @returns Promise resolving to generation result with content and metadata
+     *
+     * @example Basic text generation
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Explain quantum computing' }
+     * });
+     * console.log(result.content);
+     * ```
+     *
+     * @example With specific provider
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Write a poem' },
+     *   provider: 'anthropic',
+     *   model: 'claude-3-opus'
+     * });
+     * ```
+     *
+     * @example With MCP tools
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Read README.md and summarize it' },
+     *   tools: ['readFile']
+     * });
+     * ```
+     *
+     * @example With structured output
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const schema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     *   city: z.string()
+     * });
+     *
+     * const result = await neurolink.generate({
+     *   input: { text: 'Extract person info: John is 30 years old from NYC' },
+     *   schema: schema
+     * });
+     * // result.structuredData is type-safe!
+     * ```
+     *
+     * @example With conversation memory
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'What did we discuss earlier?' },
+     *   context: {
+     *     conversationId: 'conv-123',
+     *     userId: 'user-456'
+     *   }
+     * });
+     * ```
+     *
+     * @example With multimodal input
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: {
+     *     text: 'Describe this image',
+     *     images: ['/path/to/image.jpg']
+     *   },
+     *   provider: 'vertex'
+     * });
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When structured output validation fails
+     * @throws {Error} When HITL approval is denied
+     *
+     * @see {@link GenerateOptions} for all available options
+     * @see {@link GenerateResult} for result structure
+     * @see {@link stream} for streaming generation
+     * @since 1.0.0
+     */
     generate(optionsOrPrompt: GenerateOptions | string): Promise<GenerateResult>;
     /**
      * BACKWARD COMPATIBILITY: Legacy generateText method

package/dist/neurolink.js

@@ -46,6 +46,78 @@ import { ModelRouter } from "./utils/modelRouter.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, } from "./services/server/ai/observability/instrumentation.js";
 import { initializeMem0 } from "./memory/mem0Initializer.js";
+/**
+ * NeuroLink - Universal AI Development Platform
+ *
+ * Main SDK class providing unified access to 13+ AI providers with enterprise features:
+ * - Multi-provider support (OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, etc.)
+ * - MCP (Model Context Protocol) tool integration with 58+ external servers
+ * - Human-in-the-Loop (HITL) security workflows for regulated industries
+ * - Redis-based conversation memory and persistence
+ * - Enterprise middleware system for monitoring and control
+ * - Automatic provider fallback and retry logic
+ * - Streaming with real-time token delivery
+ * - Multimodal support (text, images, PDFs, CSV)
+ *
+ * @category Core
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { NeuroLink } from '@juspay/neurolink';
+ *
+ * const neurolink = new NeuroLink();
+ *
+ * const result = await neurolink.generate({
+ *   input: { text: 'Explain quantum computing' },
+ *   provider: 'vertex',
+ *   model: 'gemini-3-flash'
+ * });
+ *
+ * console.log(result.content);
+ * ```
+ *
+ * @example With HITL security
+ * ```typescript
+ * const neurolink = new NeuroLink({
+ *   hitl: {
+ *     enabled: true,
+ *     requireApproval: ['writeFile', 'executeCode'],
+ *     confidenceThreshold: 0.85
+ *   }
+ * });
+ * ```
+ *
+ * @example With Redis memory
+ * ```typescript
+ * const neurolink = new NeuroLink({
+ *   conversationMemory: {
+ *     enabled: true,
+ *     redis: {
+ *       url: 'redis://localhost:6379'
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example With MCP tools
+ * ```typescript
+ * const neurolink = new NeuroLink();
+ *
+ * // Discover available tools
+ * const tools = await neurolink.getAvailableTools();
+ *
+ * // Use tools in generation
+ * const result = await neurolink.generate({
+ *   input: { text: 'Read the README.md file' },
+ *   tools: ['readFile']
+ * });
+ * ```
+ *
+ * @see {@link GenerateOptions} for generation options
+ * @see {@link StreamOptions} for streaming options
+ * @see {@link NeurolinkConstructorConfig} for configuration options
+ * @since 1.0.0
+ */
 export class NeuroLink {
     mcpInitialized = false;
     emitter = new EventEmitter();
@@ -1191,6 +1263,106 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    /**
+     * Generate AI response with comprehensive feature support.
+     *
+     * Primary method for AI generation with support for all NeuroLink features:
+     * - Multi-provider support (13+ providers)
+     * - MCP tool integration
+     * - Structured JSON output with Zod schemas
+     * - Conversation memory (Redis or in-memory)
+     * - HITL security workflows
+     * - Middleware execution
+     * - Multimodal inputs (images, PDFs, CSV)
+     *
+     * @category Generation
+     *
+     * @param optionsOrPrompt - Generation options or simple text prompt
+     * @param optionsOrPrompt.input - Input text and optional files
+     * @param optionsOrPrompt.provider - AI provider name (e.g., 'vertex', 'openai', 'anthropic')
+     * @param optionsOrPrompt.model - Model name to use
+     * @param optionsOrPrompt.tools - MCP tools to enable for this generation
+     * @param optionsOrPrompt.schema - Zod schema for structured output validation
+     * @param optionsOrPrompt.temperature - Sampling temperature (0-2, default: 1.0)
+     * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
+     * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
+     * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @returns Promise resolving to generation result with content and metadata
+     *
+     * @example Basic text generation
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Explain quantum computing' }
+     * });
+     * console.log(result.content);
+     * ```
+     *
+     * @example With specific provider
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Write a poem' },
+     *   provider: 'anthropic',
+     *   model: 'claude-3-opus'
+     * });
+     * ```
+     *
+     * @example With MCP tools
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'Read README.md and summarize it' },
+     *   tools: ['readFile']
+     * });
+     * ```
+     *
+     * @example With structured output
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const schema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     *   city: z.string()
+     * });
+     *
+     * const result = await neurolink.generate({
+     *   input: { text: 'Extract person info: John is 30 years old from NYC' },
+     *   schema: schema
+     * });
+     * // result.structuredData is type-safe!
+     * ```
+     *
+     * @example With conversation memory
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: 'What did we discuss earlier?' },
+     *   context: {
+     *     conversationId: 'conv-123',
+     *     userId: 'user-456'
+     *   }
+     * });
+     * ```
+     *
+     * @example With multimodal input
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: {
+     *     text: 'Describe this image',
+     *     images: ['/path/to/image.jpg']
+     *   },
+     *   provider: 'vertex'
+     * });
+     * ```
+     *
+     * @throws {Error} When input text is missing or invalid
+     * @throws {Error} When all providers fail to generate content
+     * @throws {Error} When structured output validation fails
+     * @throws {Error} When HITL approval is denied
+     *
+     * @see {@link GenerateOptions} for all available options
+     * @see {@link GenerateResult} for result structure
+     * @see {@link stream} for streaming generation
+     * @since 1.0.0
+     */
     async generate(optionsOrPrompt) {
         const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
         // Convert string prompt to full options