@juspay/neurolink 7.7.1 → 7.9.0

package/dist/neurolink.js

@@ -26,15 +26,32 @@ import { validateTool, createMCPServerFromTools, } from "./sdk/toolRegistration.
 import { processFactoryOptions, enhanceTextGenerationOptions, validateFactoryConfig, processStreamingFactoryOptions, createCleanStreamOptions, } from "./utils/factoryProcessing.js";
 // Enhanced error handling imports
 import { ErrorFactory, NeuroLinkError, withTimeout, withRetry, isRetriableError, logStructuredError, CircuitBreaker, } from "./utils/errorHandling.js";
+import { EventEmitter } from "events";
 // Core types imported from core/types.js
 export class NeuroLink {
     mcpInitialized = false;
+    emitter = new EventEmitter();
     // Tool registration support
     customTools = new Map();
     inMemoryServers = new Map();
     // Enhanced error handling support
     toolCircuitBreakers = new Map();
     toolExecutionMetrics = new Map();
+    /**
+     * Helper method to emit tool end event in a consistent way
+     * Used by executeTool in both success and error paths
+     * @param toolName - Name of the tool
+     * @param startTime - Timestamp when tool execution started
+     * @param success - Whether the tool execution was successful
+     */
+    emitToolEndEvent(toolName, startTime, success) {
+        this.emitter.emit("tool:end", {
+            toolName,
+            responseTime: Date.now() - startTime,
+            success,
+            timestamp: Date.now(),
+        });
+    }
     constructor() {
         // SDK always disables manual MCP config for security
         ProviderRegistry.setOptions({
@@ -91,7 +108,6 @@ export class NeuroLink {
      * Replaces both generateText and legacy methods
      */
     async generate(optionsOrPrompt) {
-        const startTime = Date.now();
         // Convert string prompt to full options
         const options = typeof optionsOrPrompt === "string"
             ? { input: { text: optionsOrPrompt } }
@@ -100,6 +116,12 @@ export class NeuroLink {
         if (!options.input?.text || typeof options.input.text !== "string") {
             throw new Error("Input text is required and must be a non-empty string");
         }
+        const startTime = Date.now();
+        // Emit generation start event
+        this.emitter.emit("generation:start", {
+            provider: options.provider || "auto",
+            timestamp: startTime,
+        });
         // Process factory configuration
         const factoryResult = processFactoryOptions(options);
         // Validate factory configuration if present
@@ -142,6 +164,13 @@ export class NeuroLink {
         }
         // Use redesigned generation logic
         const textResult = await this.generateTextInternal(textOptions);
+        // Emit generation completion event
+        this.emitter.emit("generation:end", {
+            provider: textResult.provider,
+            responseTime: Date.now() - startTime,
+            toolsUsed: textResult.toolsUsed,
+            timestamp: Date.now(),
+        });
         // Convert back to GenerateResult
         const generateResult = {
             content: textResult.content,
@@ -509,6 +538,11 @@ export class NeuroLink {
             options.input.text.trim() === "") {
             throw new Error("Stream options must include input.text as a non-empty string");
         }
+        // Emit stream start event
+        this.emitter.emit("stream:start", {
+            provider: options.provider || "auto",
+            timestamp: startTime,
+        });
         // Process factory configuration for streaming
         const factoryResult = processFactoryOptions(options);
         const streamingResult = processStreamingFactoryOptions(options);
@@ -576,6 +610,11 @@ export class NeuroLink {
                 responseTime,
                 provider: providerName,
             });
+            // Emit stream completion event
+            this.emitter.emit("stream:end", {
+                provider: providerName,
+                responseTime,
+            });
             // Convert to StreamResult format - Include analytics and evaluation from provider
             return {
                 stream,
@@ -615,6 +654,12 @@ export class NeuroLink {
             const cleanOptions = createCleanStreamOptions(enhancedOptions);
             const streamResult = await provider.stream(cleanOptions);
             const responseTime = Date.now() - startTime;
+            // Emit stream completion event for fallback
+            this.emitter.emit("stream:end", {
+                provider: providerName,
+                responseTime,
+                fallback: true,
+            });
             return {
                 stream: streamResult.stream,
                 provider: providerName,
@@ -643,6 +688,13 @@ export class NeuroLink {
             };
         }
     }
+    /**
+     * Get the EventEmitter to listen to NeuroLink events
+     * @returns EventEmitter instance
+     */
+    getEventEmitter() {
+        return this.emitter;
+    }
     // ========================================
     // Tool Registration API
     // ========================================
@@ -652,6 +704,11 @@ export class NeuroLink {
      * @param tool - Tool configuration
      */
     registerTool(name, tool) {
+        // Emit tool registration start event
+        this.emitter.emit("tools-register:start", {
+            toolName: name,
+            timestamp: Date.now(),
+        });
         try {
             // Validate tool configuration
             validateTool(name, tool);
@@ -666,6 +723,12 @@ export class NeuroLink {
             // Store as in-memory server
             this.inMemoryServers.set(serverId, mcpServer);
             logger.info(`Registered custom tool: ${name}`);
+            // Emit tool registration success event
+            this.emitter.emit("tools-register:end", {
+                toolName: name,
+                success: true,
+                timestamp: Date.now(),
+            });
         }
         catch (error) {
             logger.error(`Failed to register tool ${name}:`, error);
@@ -758,6 +821,11 @@ export class NeuroLink {
     async executeTool(toolName, params = {}, options) {
         const functionTag = "NeuroLink.executeTool";
         const executionStartTime = Date.now();
+        // Emit tool start event
+        this.emitter.emit("tool:start", {
+            toolName,
+            timestamp: executionStartTime,
+        });
         // Set default options
         const finalOptions = {
             timeout: options?.timeout || 30000, // 30 second default timeout
@@ -832,6 +900,8 @@ export class NeuroLink {
                 memoryDelta,
                 circuitBreakerState: circuitBreaker.getState(),
             });
+            // Emit tool end event using the helper method
+            this.emitToolEndEvent(toolName, executionStartTime, true);
             return result;
         }
         catch (error) {
@@ -867,6 +937,8 @@ export class NeuroLink {
             else {
                 structuredError = ErrorFactory.toolExecutionFailed(toolName, new Error(String(error)));
             }
+            // Emit tool end event using the helper method
+            this.emitToolEndEvent(toolName, executionStartTime, false);
             // Add execution context to structured error
             structuredError = new NeuroLinkError({
                 ...structuredError,

package/dist/providers/amazonSagemaker.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Amazon SageMaker Provider Implementation (Simplified)
+ *
+ * This module provides a simplified SageMaker provider that extends BaseProvider
+ * and integrates with the NeuroLink ecosystem using existing patterns.
+ */
+import type { ZodType, ZodTypeDef } from "zod";
+import type { Schema, LanguageModelV1 } from "ai";
+import type { AIProviderName } from "../core/types.js";
+import type { StreamOptions, StreamResult } from "../types/streamTypes.js";
+import { BaseProvider } from "../core/baseProvider.js";
+/**
+ * Amazon SageMaker Provider extending BaseProvider
+ */
+export declare class AmazonSageMakerProvider extends BaseProvider {
+    private sagemakerModel;
+    private sagemakerConfig;
+    private modelConfig;
+    constructor(modelName?: string, endpointName?: string);
+    protected getProviderName(): AIProviderName;
+    protected getDefaultModel(): string;
+    protected getAISDKModel(): LanguageModelV1;
+    protected executeStream(options: StreamOptions, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<StreamResult>;
+    protected handleProviderError(error: unknown): Error;
+    /**
+     * Get SageMaker-specific provider information
+     */
+    getSageMakerInfo(): {
+        endpointName: string;
+        modelType: string;
+        region: string;
+        configured: boolean;
+    };
+    /**
+     * Test basic configuration
+     */
+    testConnection(): Promise<{
+        connected: boolean;
+        error?: string;
+    }>;
+    /**
+     * Public method to get the AI SDK model for CLI and external usage
+     */
+    getModel(): Promise<LanguageModelV1>;
+    /**
+     * Test connectivity to the SageMaker endpoint
+     */
+    testConnectivity(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get model capabilities and information
+     */
+    getModelCapabilities(): {
+        capabilities: {
+            streaming: boolean;
+            toolCalling: boolean;
+            structuredOutput: boolean;
+            batchInference: boolean;
+            supportedResponseFormats: string[];
+            supportedToolTypes: string[];
+            maxBatchSize: number;
+        };
+    };
+}
+export default AmazonSageMakerProvider;

package/dist/providers/amazonSagemaker.js

@@ -0,0 +1,149 @@
+/**
+ * Amazon SageMaker Provider Implementation (Simplified)
+ *
+ * This module provides a simplified SageMaker provider that extends BaseProvider
+ * and integrates with the NeuroLink ecosystem using existing patterns.
+ */
+import { BaseProvider } from "../core/baseProvider.js";
+import { logger } from "../utils/logger.js";
+// SageMaker-specific imports
+import { getSageMakerConfig, getSageMakerModelConfig, getDefaultSageMakerEndpoint, getSageMakerModel, } from "./sagemaker/config.js";
+import { handleSageMakerError, SageMakerError } from "./sagemaker/errors.js";
+import { SageMakerLanguageModel } from "./sagemaker/language-model.js";
+/**
+ * Amazon SageMaker Provider extending BaseProvider
+ */
+export class AmazonSageMakerProvider extends BaseProvider {
+    sagemakerModel;
+    sagemakerConfig;
+    modelConfig;
+    constructor(modelName, endpointName) {
+        super(modelName, "sagemaker");
+        try {
+            // Load and validate configuration
+            this.sagemakerConfig = getSageMakerConfig();
+            this.modelConfig = getSageMakerModelConfig(endpointName || getDefaultSageMakerEndpoint());
+            // Create the proper LanguageModel (v2) implementation
+            this.sagemakerModel = new SageMakerLanguageModel(this.modelName, this.sagemakerConfig, this.modelConfig);
+            logger.debug("Amazon SageMaker Provider initialized", {
+                modelName: this.modelName,
+                endpointName: this.modelConfig.endpointName,
+                region: this.sagemakerConfig.region,
+                provider: this.providerName,
+            });
+        }
+        catch (error) {
+            logger.error("Failed to initialize SageMaker provider", {
+                error: error instanceof Error ? error.message : String(error),
+                modelName,
+                endpointName,
+            });
+            throw handleSageMakerError(error);
+        }
+    }
+    getProviderName() {
+        return "sagemaker";
+    }
+    getDefaultModel() {
+        return getSageMakerModel();
+    }
+    getAISDKModel() {
+        return this.sagemakerModel;
+    }
+    async executeStream(options, analysisSchema) {
+        try {
+            // For now, throw an error indicating this is not yet implemented
+            throw new SageMakerError("SageMaker streaming not yet fully implemented. Coming in next phase.", "MODEL_ERROR", 501, undefined, this.modelConfig.endpointName);
+        }
+        catch (error) {
+            throw this.handleProviderError(error);
+        }
+    }
+    handleProviderError(error) {
+        if (error instanceof SageMakerError) {
+            return error;
+        }
+        if (error instanceof Error && error.name === "TimeoutError") {
+            return new SageMakerError(`SageMaker request timed out. Consider increasing timeout.`, "NETWORK_ERROR", 408, error, this.modelConfig.endpointName);
+        }
+        return handleSageMakerError(error, this.modelConfig.endpointName);
+    }
+    /**
+     * Get SageMaker-specific provider information
+     */
+    getSageMakerInfo() {
+        return {
+            endpointName: this.modelConfig.endpointName,
+            modelType: this.modelConfig.modelType || "custom",
+            region: this.sagemakerConfig.region,
+            configured: !!(this.sagemakerConfig.accessKeyId && this.sagemakerConfig.secretAccessKey),
+        };
+    }
+    /**
+     * Test basic configuration
+     */
+    async testConnection() {
+        try {
+            // Basic validation test
+            if (!this.sagemakerConfig.accessKeyId ||
+                !this.sagemakerConfig.secretAccessKey) {
+                return {
+                    connected: false,
+                    error: "AWS credentials not configured",
+                };
+            }
+            if (!this.modelConfig.endpointName ||
+                this.modelConfig.endpointName === "default-endpoint") {
+                return {
+                    connected: false,
+                    error: "SageMaker endpoint not configured",
+                };
+            }
+            // For now, just return that configuration looks valid
+            return {
+                connected: true,
+            };
+        }
+        catch (error) {
+            return {
+                connected: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    /**
+     * Public method to get the AI SDK model for CLI and external usage
+     */
+    async getModel() {
+        return this.getAISDKModel();
+    }
+    /**
+     * Test connectivity to the SageMaker endpoint
+     */
+    async testConnectivity() {
+        const model = this.sagemakerModel;
+        return model.testConnectivity
+            ? await model.testConnectivity()
+            : { success: false, error: "Test method not available" };
+    }
+    /**
+     * Get model capabilities and information
+     */
+    getModelCapabilities() {
+        const model = this.sagemakerModel;
+        return model.getModelCapabilities
+            ? model.getModelCapabilities()
+            : {
+                capabilities: {
+                    streaming: true,
+                    toolCalling: true,
+                    structuredOutput: true,
+                    batchInference: true,
+                    supportedResponseFormats: ["text", "json_object"],
+                    supportedToolTypes: ["function"],
+                    maxBatchSize: 10,
+                },
+            };
+    }
+}
+export default AmazonSageMakerProvider;

package/dist/providers/googleVertex.d.ts

@@ -108,6 +108,10 @@ export declare class GoogleVertexProvider extends BaseProvider {
             maxTokens: number;
         };
     };
+    /**
+     * Get model suggestions when a model is not found
+     */
+    private getModelSuggestions;
 }
 export default GoogleVertexProvider;
 export { GoogleVertexProvider as GoogleVertexAI };

package/dist/providers/googleVertex.js

@@ -40,9 +40,9 @@ const getVertexLocation = () => {
         "us-central1");
 };
 const getDefaultVertexModel = () => {
-    // Use gemini-1.5-pro as default - stable and widely supported model
+    // Use gemini-2.5-flash as default - latest and best price-performance model
     // Override with VERTEX_MODEL environment variable if needed
-    return process.env.VERTEX_MODEL || "gemini-1.5-pro";
+    return process.env.VERTEX_MODEL || "gemini-2.5-flash";
 };
 const hasGoogleCredentials = () => {
     return !!(process.env.GOOGLE_APPLICATION_CREDENTIALS ||
@@ -276,7 +276,8 @@ export class GoogleVertexProvider extends BaseProvider {
             return new Error(`❌ Google Vertex AI Permission Denied\n\nYour Google Cloud credentials don't have permission to access Vertex AI.\n\nRequired Steps:\n1. Ensure your service account has Vertex AI User role\n2. Check if Vertex AI API is enabled in your project\n3. Verify your project ID is correct\n4. Confirm your location/region has Vertex AI available`);
         }
         if (message.includes("NOT_FOUND")) {
-            return new Error(`❌ Google Vertex AI Model Not Found\n\n${message}\n\nCheck:\n1. Model name is correct (e.g., 'gemini-1.5-pro')\n2. Model is available in your region (${this.location})\n3. Your project has access to the model\n4. Model supports your request parameters`);
+            const modelSuggestions = this.getModelSuggestions(this.modelName);
+            return new Error(`❌ Google Vertex AI Model Not Found\n\n${message}\n\nModel '${this.modelName}' is not available.\n\nSuggested alternatives:\n${modelSuggestions}\n\nTroubleshooting:\n1. Check model name spelling and format\n2. Verify model is available in your region (${this.location})\n3. Ensure your project has access to the model\n4. For Claude models, enable Anthropic integration in Google Cloud Console`);
         }
         if (message.includes("QUOTA_EXCEEDED")) {
             return new Error(`❌ Google Vertex AI Quota Exceeded\n\n${message}\n\nSolutions:\n1. Check your Vertex AI quotas in Google Cloud Console\n2. Request quota increase if needed\n3. Try a different model or reduce request frequency\n4. Consider using a different region`);
@@ -520,6 +521,46 @@ export class GoogleVertexProvider extends BaseProvider {
             },
         };
     }
+    /**
+     * Get model suggestions when a model is not found
+     */
+    getModelSuggestions(requestedModel) {
+        const availableModels = {
+            google: [
+                "gemini-2.5-pro",
+                "gemini-2.5-flash",
+                "gemini-2.5-flash-lite",
+                "gemini-2.0-flash-001",
+                "gemini-1.5-pro",
+                "gemini-1.5-flash"
+            ],
+            claude: [
+                "claude-sonnet-4@20250514",
+                "claude-opus-4@20250514",
+                "claude-3-5-sonnet-20241022",
+                "claude-3-5-haiku-20241022",
+                "claude-3-sonnet-20240229",
+                "claude-3-haiku-20240307",
+                "claude-3-opus-20240229",
+            ],
+        };
+        let suggestions = "\n🤖 Google Models (always available):\n";
+        availableModels.google.forEach((model) => {
+            suggestions += `  • ${model}\n`;
+        });
+        suggestions += "\n🧠 Claude Models (requires Anthropic integration):\n";
+        availableModels.claude.forEach((model) => {
+            suggestions += `  • ${model}\n`;
+        });
+        // If the requested model looks like a Claude model, provide specific guidance
+        if (requestedModel && requestedModel.toLowerCase().includes("claude")) {
+            suggestions += `\n💡 Tip: "${requestedModel}" appears to be a Claude model.\n`;
+            suggestions +=
+                "Ensure Anthropic integration is enabled in your Google Cloud project.\n";
+            suggestions += "Try using an available Claude model from the list above.";
+        }
+        return suggestions;
+    }
 }
 export default GoogleVertexProvider;
 // Re-export for compatibility

package/dist/providers/index.d.ts

@@ -4,6 +4,7 @@
  */
 export { GoogleVertexProvider as GoogleVertexAI } from "./googleVertex.js";
 export { AmazonBedrockProvider as AmazonBedrock } from "./amazonBedrock.js";
+export { AmazonSageMakerProvider as AmazonSageMaker } from "./amazonSagemaker.js";
 export { OpenAIProvider as OpenAI } from "./openAI.js";
 export { OpenAICompatibleProvider as OpenAICompatible } from "./openaiCompatible.js";
 export { AnthropicProvider as AnthropicProvider } from "./anthropic.js";
@@ -12,6 +13,7 @@ export { GoogleAIStudioProvider as GoogleAIStudio } from "./googleAiStudio.js";
 export { HuggingFaceProvider as HuggingFace } from "./huggingFace.js";
 export { OllamaProvider as Ollama } from "./ollama.js";
 export { MistralProvider as MistralAI } from "./mistral.js";
+export { LiteLLMProvider as LiteLLM } from "./litellm.js";
 export type { AIProvider } from "../core/types.js";
 /**
  * Provider registry for dynamic provider instantiation
@@ -19,6 +21,7 @@ export type { AIProvider } from "../core/types.js";
 export declare const PROVIDERS: {
     readonly vertex: "GoogleVertexAI";
     readonly bedrock: "AmazonBedrock";
+    readonly sagemaker: "AmazonSageMaker";
     readonly openai: "OpenAI";
     readonly "openai-compatible": "OpenAICompatible";
     readonly anthropic: "AnthropicProvider";
@@ -27,6 +30,7 @@ export declare const PROVIDERS: {
     readonly huggingface: "HuggingFace";
     readonly ollama: "Ollama";
     readonly mistral: "MistralAI";
+    readonly litellm: "LiteLLM";
 };
 /**
  * Type for valid provider names

package/dist/providers/index.js

@@ -4,6 +4,7 @@
  */
 export { GoogleVertexProvider as GoogleVertexAI } from "./googleVertex.js";
 export { AmazonBedrockProvider as AmazonBedrock } from "./amazonBedrock.js";
+export { AmazonSageMakerProvider as AmazonSageMaker } from "./amazonSagemaker.js";
 export { OpenAIProvider as OpenAI } from "./openAI.js";
 export { OpenAICompatibleProvider as OpenAICompatible } from "./openaiCompatible.js";
 export { AnthropicProvider as AnthropicProvider } from "./anthropic.js";
@@ -12,12 +13,14 @@ export { GoogleAIStudioProvider as GoogleAIStudio } from "./googleAiStudio.js";
 export { HuggingFaceProvider as HuggingFace } from "./huggingFace.js";
 export { OllamaProvider as Ollama } from "./ollama.js";
 export { MistralProvider as MistralAI } from "./mistral.js";
+export { LiteLLMProvider as LiteLLM } from "./litellm.js";
 /**
  * Provider registry for dynamic provider instantiation
  */
 export const PROVIDERS = {
     vertex: "GoogleVertexAI",
     bedrock: "AmazonBedrock",
+    sagemaker: "AmazonSageMaker",
     openai: "OpenAI",
     "openai-compatible": "OpenAICompatible",
     anthropic: "AnthropicProvider",
@@ -26,6 +29,7 @@ export const PROVIDERS = {
     huggingface: "HuggingFace",
     ollama: "Ollama",
     mistral: "MistralAI",
+    litellm: "LiteLLM",
 };
 /**
  * List of all available provider names

package/dist/providers/sagemaker/adaptive-semaphore.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Adaptive Semaphore Utility
+ *
+ * Provides a sophisticated semaphore implementation with dynamic concurrency adjustment
+ * for optimal resource utilization and performance tuning based on response times and error rates.
+ */
+export interface AdaptiveSemaphoreConfig {
+    initialConcurrency: number;
+    maxConcurrency: number;
+    minConcurrency: number;
+}
+export interface AdaptiveSemaphoreMetrics {
+    activeRequests: number;
+    currentConcurrency: number;
+    completedCount: number;
+    errorCount: number;
+    averageResponseTime: number;
+    waitingCount: number;
+}
+/**
+ * Adaptive semaphore that automatically adjusts concurrency based on performance metrics
+ */
+export declare class AdaptiveSemaphore {
+    private count;
+    private waiters;
+    private currentConcurrency;
+    private activeRequests;
+    private completedCount;
+    private errorCount;
+    private responseTimes;
+    private readonly maxConcurrency;
+    private readonly minConcurrency;
+    constructor(config: AdaptiveSemaphoreConfig);
+    /**
+     * Acquire a semaphore permit, waiting if necessary
+     */
+    acquire(): Promise<void>;
+    /**
+     * Release a semaphore permit and wake up waiting requests
+     */
+    release(): void;
+    /**
+     * Record successful completion with response time for adaptive adjustment
+     */
+    recordSuccess(responseTimeMs: number): void;
+    /**
+     * Record error for adaptive adjustment
+     */
+    recordError(responseTimeMs?: number): void;
+    /**
+     * Manually adjust concurrency level
+     */
+    adjustConcurrency(newLimit: number): void;
+    /**
+     * Get current performance metrics
+     */
+    getMetrics(): AdaptiveSemaphoreMetrics;
+    /**
+     * Reset metrics for new batch or session
+     */
+    resetMetrics(): void;
+    /**
+     * Automatically adjust concurrency based on performance indicators
+     */
+    private adjustConcurrencyBasedOnPerformance;
+    /**
+     * Check if semaphore is idle (no active or waiting requests)
+     */
+    isIdle(): boolean;
+    /**
+     * Get current concurrency limit
+     */
+    getCurrentConcurrency(): number;
+    /**
+     * Get number of active requests
+     */
+    getActiveRequestCount(): number;
+    /**
+     * Get number of waiting requests
+     */
+    getWaitingRequestCount(): number;
+}
+/**
+ * Factory function to create an adaptive semaphore with default configuration
+ */
+export declare function createAdaptiveSemaphore(initialConcurrency: number, maxConcurrency?: number, minConcurrency?: number): AdaptiveSemaphore;