@juspay/neurolink 7.7.0 → 7.8.0

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/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;

package/dist/providers/sagemaker/adaptive-semaphore.js

@@ -0,0 +1,212 @@
+/**
+ * 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.
+ */
+import { logger } from "../../utils/logger.js";
+/**
+ * Adaptive semaphore that automatically adjusts concurrency based on performance metrics
+ */
+export class AdaptiveSemaphore {
+    count;
+    waiters = [];
+    currentConcurrency;
+    activeRequests = 0;
+    completedCount = 0;
+    errorCount = 0;
+    responseTimes = [];
+    maxConcurrency;
+    minConcurrency;
+    constructor(config) {
+        this.currentConcurrency = config.initialConcurrency;
+        this.count = config.initialConcurrency;
+        this.maxConcurrency = config.maxConcurrency;
+        this.minConcurrency = config.minConcurrency;
+        logger.debug("AdaptiveSemaphore initialized", {
+            initialConcurrency: config.initialConcurrency,
+            maxConcurrency: config.maxConcurrency,
+            minConcurrency: config.minConcurrency,
+        });
+    }
+    /**
+     * Acquire a semaphore permit, waiting if necessary
+     */
+    async acquire() {
+        return new Promise((resolve) => {
+            if (this.count > 0) {
+                this.count--;
+                this.activeRequests++;
+                resolve();
+            }
+            else {
+                this.waiters.push(() => {
+                    this.count--;
+                    this.activeRequests++;
+                    resolve();
+                });
+            }
+        });
+    }
+    /**
+     * Release a semaphore permit and wake up waiting requests
+     */
+    release() {
+        this.activeRequests--;
+        if (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter();
+        }
+        else {
+            this.count++;
+        }
+    }
+    /**
+     * Record successful completion with response time for adaptive adjustment
+     */
+    recordSuccess(responseTimeMs) {
+        this.completedCount++;
+        this.responseTimes.push(responseTimeMs);
+        // Keep only recent response times for calculation (last 10 responses)
+        if (this.responseTimes.length > 10) {
+            this.responseTimes.shift();
+        }
+        this.adjustConcurrencyBasedOnPerformance(responseTimeMs, false);
+    }
+    /**
+     * Record error for adaptive adjustment
+     */
+    recordError(responseTimeMs) {
+        this.errorCount++;
+        if (responseTimeMs) {
+            this.responseTimes.push(responseTimeMs);
+            if (this.responseTimes.length > 10) {
+                this.responseTimes.shift();
+            }
+        }
+        this.adjustConcurrencyBasedOnPerformance(responseTimeMs || 0, true);
+    }
+    /**
+     * Manually adjust concurrency level
+     */
+    adjustConcurrency(newLimit) {
+        const clampedLimit = Math.max(this.minConcurrency, Math.min(this.maxConcurrency, newLimit));
+        const diff = clampedLimit - (this.currentConcurrency - this.count);
+        this.count += diff;
+        this.currentConcurrency = clampedLimit;
+        logger.debug("Concurrency adjusted", {
+            newConcurrency: clampedLimit,
+            previousConcurrency: this.currentConcurrency - diff,
+            availableCount: this.count,
+            activeRequests: this.activeRequests,
+        });
+        // Wake up waiting requests if we increased concurrency
+        while (this.count > 0 && this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            this.count--;
+            this.activeRequests++;
+            waiter();
+        }
+    }
+    /**
+     * Get current performance metrics
+     */
+    getMetrics() {
+        const averageResponseTime = this.responseTimes.length > 0
+            ? this.responseTimes.reduce((sum, time) => sum + time, 0) /
+                this.responseTimes.length
+            : 0;
+        return {
+            activeRequests: this.activeRequests,
+            currentConcurrency: this.currentConcurrency,
+            completedCount: this.completedCount,
+            errorCount: this.errorCount,
+            averageResponseTime,
+            waitingCount: this.waiters.length,
+        };
+    }
+    /**
+     * Reset metrics for new batch or session
+     */
+    resetMetrics() {
+        this.completedCount = 0;
+        this.errorCount = 0;
+        this.responseTimes = [];
+    }
+    /**
+     * Automatically adjust concurrency based on performance indicators
+     */
+    adjustConcurrencyBasedOnPerformance(responseTimeMs, isError) {
+        const metrics = this.getMetrics();
+        if (isError) {
+            // On error, reduce concurrency to be more conservative
+            if (this.currentConcurrency > this.minConcurrency) {
+                this.adjustConcurrency(Math.max(this.minConcurrency, this.currentConcurrency - 1));
+                logger.warn("Reduced concurrency due to error", {
+                    newConcurrency: this.currentConcurrency,
+                    errorCount: this.errorCount,
+                });
+            }
+            return;
+        }
+        // Only adjust after we have some data to work with
+        if (this.completedCount < 3) {
+            return;
+        }
+        const fastResponseThreshold = 2000; // 2 seconds
+        const slowResponseThreshold = 5000; // 5 seconds
+        if (responseTimeMs < fastResponseThreshold &&
+            metrics.averageResponseTime < fastResponseThreshold &&
+            this.currentConcurrency < this.maxConcurrency) {
+            // Fast responses and no bottleneck - increase concurrency
+            this.adjustConcurrency(Math.min(this.maxConcurrency, this.currentConcurrency + 1));
+            logger.debug("Increased concurrency due to fast responses", {
+                newConcurrency: this.currentConcurrency,
+                averageResponseTime: metrics.averageResponseTime,
+            });
+        }
+        else if (responseTimeMs > slowResponseThreshold &&
+            this.currentConcurrency > this.minConcurrency) {
+            // Slow responses - decrease concurrency
+            this.adjustConcurrency(Math.max(this.minConcurrency, this.currentConcurrency - 1));
+            logger.debug("Decreased concurrency due to slow responses", {
+                newConcurrency: this.currentConcurrency,
+                responseTime: responseTimeMs,
+            });
+        }
+    }
+    /**
+     * Check if semaphore is idle (no active or waiting requests)
+     */
+    isIdle() {
+        return this.activeRequests === 0 && this.waiters.length === 0;
+    }
+    /**
+     * Get current concurrency limit
+     */
+    getCurrentConcurrency() {
+        return this.currentConcurrency;
+    }
+    /**
+     * Get number of active requests
+     */
+    getActiveRequestCount() {
+        return this.activeRequests;
+    }
+    /**
+     * Get number of waiting requests
+     */
+    getWaitingRequestCount() {
+        return this.waiters.length;
+    }
+}
+/**
+ * Factory function to create an adaptive semaphore with default configuration
+ */
+export function createAdaptiveSemaphore(initialConcurrency, maxConcurrency = 10, minConcurrency = 1) {
+    return new AdaptiveSemaphore({
+        initialConcurrency,
+        maxConcurrency,
+        minConcurrency,
+    });
+}

package/dist/providers/sagemaker/client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * AWS SageMaker Runtime Client Wrapper
+ *
+ * This module provides a wrapper around the AWS SDK SageMaker Runtime client
+ * with enhanced error handling, retry logic, and NeuroLink-specific features.
+ */
+import type { SageMakerConfig, InvokeEndpointParams, InvokeEndpointResponse } from "./types.js";
+/**
+ * Enhanced SageMaker Runtime client with retry logic and error handling
+ */
+export declare class SageMakerRuntimeClient {
+    private client;
+    private config;
+    private isDisposed;
+    constructor(config: SageMakerConfig);
+    /**
+     * Invoke a SageMaker endpoint for synchronous inference
+     *
+     * @param params - Endpoint invocation parameters
+     * @returns Promise resolving to the inference response
+     * @throws {SageMakerError} When the request fails
+     */
+    invokeEndpoint(params: InvokeEndpointParams): Promise<InvokeEndpointResponse>;
+    /**
+     * Invoke a SageMaker endpoint with streaming response
+     *
+     * @param params - Endpoint invocation parameters for streaming
+     * @returns Promise resolving to async iterable of response chunks
+     * @throws {SageMakerError} When the request fails
+     */
+    invokeEndpointWithStreaming(params: InvokeEndpointParams): Promise<{
+        Body: AsyncIterable<Uint8Array>;
+        ContentType?: string;
+        InvokedProductionVariant?: string;
+    }>;
+    /**
+     * Execute a request with automatic retry logic
+     *
+     * @param operation - Function that executes the AWS SDK command
+     * @param endpointName - Endpoint name for error context
+     * @param attempt - Current attempt number (for recursive retries)
+     * @returns Promise resolving to the operation result
+     */
+    private executeWithRetry;
+    /**
+     * Validate endpoint connectivity and permissions
+     *
+     * @param endpointName - Name of the endpoint to validate
+     * @returns Promise resolving to validation result
+     */
+    validateEndpoint(endpointName: string): Promise<{
+        isValid: boolean;
+        status?: string;
+        error?: string;
+    }>;
+    /**
+     * Get client configuration summary for debugging
+     *
+     * @returns Configuration summary (with sensitive data masked)
+     */
+    getConfigSummary(): Record<string, unknown>;
+    /**
+     * Check if the client is properly configured
+     *
+     * @returns True if client appears to be properly configured
+     */
+    isConfigured(): boolean;
+    /**
+     * Convert AWS SDK async iterable stream with payload structure
+     */
+    private convertAsyncIterableStream;
+    /**
+     * Convert Node.js readable stream with reader interface
+     */
+    private convertReadableStream;
+    /**
+     * Convert non-stream data to single Uint8Array chunk as fallback
+     */
+    private convertFallbackData;
+    /**
+     * Convert AWS response stream to async iterable of Uint8Array chunks
+     * Refactored into smaller focused methods for different stream types
+     */
+    private convertAWSStreamToIterable;
+    /**
+     * Check if the client has been disposed
+     */
+    get disposed(): boolean;
+    /**
+     * Dispose of the client and clean up resources using explicit disposed state pattern
+     *
+     * AWS SDK v3 Automatic Resource Management:
+     * ========================================
+     *
+     * The AWS SDK v3 uses automatic resource cleanup and doesn't require explicit disposal
+     * of client instances in most cases. Here's how it works:
+     *
+     * 1. **HTTP Connection Pools**: AWS SDK v3 uses Node.js's built-in HTTP agent with
+     *    connection pooling. These connections are automatically managed and will be
+     *    closed when the Node.js process exits or becomes idle.
+     *
+     * 2. **Memory Management**: SDK clients don't hold significant resources that require
+     *    manual cleanup. The JavaScript garbage collector handles memory deallocation
+     *    when client references are removed.
+     *
+     * 3. **Background Timers**: Any internal timers (for retries, timeouts) are automatically
+     *    cleared when operations complete or the client goes out of scope.
+     *
+     * 4. **Keep-Alive Connections**: HTTP keep-alive connections are managed by the
+     *    underlying HTTP agent and will timeout automatically based on the configured
+     *    keep-alive timeout (typically 15 seconds).
+     *
+     * Why We Still Implement dispose():
+     * =================================
+     *
+     * 1. **Explicit State Management**: Provides clear lifecycle control and prevents
+     *    accidental usage of disposed clients.
+     *
+     * 2. **Resource Tracking**: Allows our application to track when clients are no
+     *    longer needed, which is useful for debugging and monitoring.
+     *
+     * 3. **Defensive Programming**: Ensures we don't rely on automatic cleanup in
+     *    environments where it might not work as expected.
+     *
+     * 4. **Future Compatibility**: If future SDK versions require explicit cleanup,
+     *    we already have the infrastructure in place.
+     *
+     * For more information, see:
+     * - https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/
+     * - https://aws.amazon.com/blogs/developer/node-js-configuring-maxsockets-in-sdk-for-javascript/
+     */
+    dispose(): void;
+    /**
+     * Ensure client is not disposed before operations
+     */
+    private ensureNotDisposed;
+}
+/**
+ * Factory function to create a SageMaker Runtime client
+ *
+ * @param config - SageMaker configuration
+ * @returns Configured SageMakerRuntimeClient instance
+ */
+export declare function createSageMakerRuntimeClient(config: SageMakerConfig): SageMakerRuntimeClient;
+/**
+ * Utility function to test SageMaker connectivity
+ *
+ * @param config - SageMaker configuration
+ * @param endpointName - Endpoint to test
+ * @returns Promise resolving to connectivity test result
+ */
+export declare function testSageMakerConnectivity(config: SageMakerConfig, endpointName: string): Promise<{
+    connected: boolean;
+    latency?: number;
+    error?: string;
+}>;