@juspay/neurolink 7.7.0 → 7.8.0

package/dist/providers/sagemaker/errors.js

@@ -0,0 +1,216 @@
+/**
+ * Error handling system for Amazon SageMaker Provider
+ *
+ * This module provides comprehensive error handling, categorization,
+ * and user-friendly error messages for SageMaker operations.
+ */
+import { ERROR_MESSAGE_TEMPLATES, ERROR_MESSAGE_PREFIXES, RETRY_DELAYS, RETRYABLE_ERROR_CONDITIONS, AWS_ERROR_MAPPINGS, ERROR_KEYWORDS, } from "./error-constants.js";
+/**
+ * Custom error class for SageMaker-specific errors
+ */
+export class SageMakerError extends Error {
+    code;
+    statusCode;
+    cause;
+    endpoint;
+    requestId;
+    retryable;
+    constructor(message, code = "UNKNOWN_ERROR", statusCode, cause, endpoint, requestId, retryable = false) {
+        super(message);
+        this.name = "SageMakerError";
+        this.code = code;
+        this.statusCode = statusCode;
+        this.cause = cause;
+        this.endpoint = endpoint;
+        this.requestId = requestId;
+        this.retryable = retryable;
+        // Capture stack trace if available
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SageMakerError);
+        }
+    }
+    /**
+     * Convert error to JSON for logging/serialization
+     */
+    toJSON() {
+        return {
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            cause: this.cause,
+            endpoint: this.endpoint,
+            requestId: this.requestId,
+            retryable: this.retryable,
+            stack: this.stack,
+        };
+    }
+    /**
+     * Get user-friendly error message with troubleshooting guidance
+     */
+    getUserFriendlyMessage() {
+        return getSageMakerErrorGuidance(this.code, this.message, this.endpoint);
+    }
+    /**
+     * Check if this error type is retryable
+     */
+    isRetryable() {
+        return this.retryable;
+    }
+    /**
+     * Get recommended retry delay in milliseconds
+     */
+    getRetryDelay() {
+        return (RETRY_DELAYS[this.code] ||
+            RETRY_DELAYS.DEFAULT);
+    }
+}
+/**
+ * Main error handler for SageMaker operations
+ *
+ * @param error - Original error from AWS SDK or other operations
+ * @param endpoint - Endpoint name where error occurred (optional)
+ * @returns Categorized SageMakerError with user guidance
+ */
+export function handleSageMakerError(error, endpoint) {
+    // Handle cases where error is already a SageMakerError
+    if (error instanceof SageMakerError) {
+        return error;
+    }
+    // Handle standard Error objects
+    if (error instanceof Error) {
+        const errorName = error.name;
+        const errorMessage = error.message.toLowerCase();
+        // AWS SDK specific errors using centralized constants
+        if (errorName === "ValidationException" ||
+            ERROR_KEYWORDS.VALIDATION.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.VALIDATION}: ${error.message}`, "VALIDATION_ERROR", 400, error, endpoint, extractRequestId(error), false);
+        }
+        if (errorName === "ModelError" ||
+            ERROR_KEYWORDS.MODEL.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.MODEL}: ${error.message}`, "MODEL_ERROR", 500, error, endpoint, extractRequestId(error), false);
+        }
+        if (errorName === "InternalFailure" ||
+            ERROR_KEYWORDS.INTERNAL.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.INTERNAL}: ${error.message}`, "INTERNAL_ERROR", 500, error, endpoint, extractRequestId(error), true);
+        }
+        if (errorName === "ServiceUnavailable" ||
+            ERROR_KEYWORDS.SERVICE_UNAVAILABLE.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.SERVICE_UNAVAILABLE}: ${error.message}`, "SERVICE_UNAVAILABLE", 503, error, endpoint, extractRequestId(error), true);
+        }
+        if (errorName === "ThrottlingException" ||
+            ERROR_KEYWORDS.THROTTLING.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.THROTTLING}: ${error.message}`, "THROTTLING_ERROR", 429, error, endpoint, extractRequestId(error), true);
+        }
+        if (errorName === "CredentialsError" ||
+            ERROR_KEYWORDS.CREDENTIALS.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.CREDENTIALS}: ${error.message}`, "CREDENTIALS_ERROR", 401, error, endpoint, undefined, false);
+        }
+        if (errorName === "NetworkingError" ||
+            ERROR_KEYWORDS.NETWORK.some((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.NETWORK}: ${error.message}`, "NETWORK_ERROR", 0, error, endpoint, undefined, true);
+        }
+        if (ERROR_KEYWORDS.ENDPOINT_NOT_FOUND.every((keyword) => errorMessage.includes(keyword))) {
+            return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.ENDPOINT_NOT_FOUND}: ${error.message}`, "ENDPOINT_NOT_FOUND", 404, error, endpoint, extractRequestId(error), false);
+        }
+        // Generic error handling
+        return new SageMakerError(error.message, "UNKNOWN_ERROR", 500, error, endpoint, extractRequestId(error), false);
+    }
+    // Handle non-Error objects
+    const errorMessage = typeof error === "string" ? error : "Unknown error occurred";
+    return new SageMakerError(errorMessage, "UNKNOWN_ERROR", 500, undefined, endpoint, undefined, false);
+}
+/**
+ * Extract request ID from AWS SDK error for debugging
+ *
+ * @param error - Error object that might contain request ID
+ * @returns Request ID if found, undefined otherwise
+ */
+function extractRequestId(error) {
+    const errorAny = error;
+    return (errorAny.requestId ||
+        errorAny.RequestId ||
+        errorAny.$metadata?.requestId ||
+        undefined);
+}
+/**
+ * Get user-friendly error guidance based on error code
+ *
+ * @param code - SageMaker error code
+ * @param originalMessage - Original error message
+ * @param endpoint - Endpoint name (optional)
+ * @returns User-friendly error message with troubleshooting steps
+ */
+function getSageMakerErrorGuidance(code, originalMessage, endpoint) {
+    const endpointContext = endpoint ? ` (endpoint: ${endpoint})` : "";
+    // Get template for the error code, falling back to default
+    const template = ERROR_MESSAGE_TEMPLATES[code] || ERROR_MESSAGE_TEMPLATES.DEFAULT;
+    // Replace placeholders in the template
+    return template
+        .replace("{endpointContext}", endpointContext)
+        .replace("{originalMessage}", originalMessage);
+}
+/**
+ * Create a validation error for configuration issues
+ *
+ * @param message - Validation error message
+ * @param field - Configuration field that failed validation
+ * @returns SageMakerError with validation details
+ */
+export function createValidationError(message, field) {
+    const fullMessage = field
+        ? `${ERROR_MESSAGE_PREFIXES.VALIDATION_FIELD} '${field}': ${message}`
+        : message;
+    return new SageMakerError(fullMessage, "VALIDATION_ERROR", 400);
+}
+/**
+ * Create a credentials error with setup guidance
+ *
+ * @param message - Credentials error message
+ * @returns SageMakerError with credentials guidance
+ */
+export function createCredentialsError(message) {
+    return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.CREDENTIALS_SETUP}: ${message}`, "CREDENTIALS_ERROR", 401, undefined, undefined, undefined, false);
+}
+/**
+ * Create a network error with connectivity guidance
+ *
+ * @param message - Network error message
+ * @param endpoint - Endpoint that failed to connect
+ * @returns SageMakerError with network guidance
+ */
+export function createNetworkError(message, endpoint) {
+    return new SageMakerError(`${ERROR_MESSAGE_PREFIXES.NETWORK_CONNECTION}: ${message}`, "NETWORK_ERROR", 0, undefined, endpoint, undefined, true);
+}
+/**
+ * Check if an error is retryable based on its characteristics
+ *
+ * @param error - Error to check
+ * @returns True if the error suggests a retry might succeed
+ */
+export function isRetryableError(error) {
+    if (error instanceof SageMakerError) {
+        return error.isRetryable();
+    }
+    if (error instanceof Error) {
+        const errorMessage = error.message.toLowerCase();
+        const errorName = error.name;
+        // Check against retryable error names and message keywords
+        return (RETRYABLE_ERROR_CONDITIONS.ERROR_NAMES.includes(errorName) ||
+            RETRYABLE_ERROR_CONDITIONS.ERROR_MESSAGE_KEYWORDS.some((keyword) => errorMessage.includes(keyword)));
+    }
+    return false;
+}
+/**
+ * Get recommended retry delay for an error
+ *
+ * @param error - Error to get retry delay for
+ * @param attempt - Current retry attempt number (for exponential backoff)
+ * @returns Recommended delay in milliseconds
+ */
+export function getRetryDelay(error, attempt = 1) {
+    if (error instanceof SageMakerError) {
+        return error.getRetryDelay() * Math.pow(2, attempt - 1);
+    }
+    // Default exponential backoff
+    return 1000 * Math.pow(2, attempt - 1);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Amazon SageMaker Provider - Main Export Module (Simplified)
+ *
+ * This module provides the main exports for SageMaker integration (Phase 1).
+ * Full implementation will be completed in subsequent phases.
+ */
+import { AmazonSageMakerProvider } from "../amazonSagemaker.js";
+export { AmazonSageMakerProvider } from "../amazonSagemaker.js";
+export { SageMakerRuntimeClient, createSageMakerRuntimeClient, testSageMakerConnectivity, } from "./client.js";
+export { getSageMakerConfig, getSageMakerModelConfig, getDefaultSageMakerEndpoint, getSageMakerModel, validateAWSCredentials, getConfigurationSummary, clearConfigurationCache, loadConfigurationFromFile, checkSageMakerConfiguration, } from "./config.js";
+export { SageMakerError, handleSageMakerError, createValidationError, createCredentialsError, createNetworkError, isRetryableError, getRetryDelay, } from "./errors.js";
+export type { SageMakerConfig, SageMakerModelConfig, SageMakerEndpointInfo, SageMakerUsage, InvokeEndpointParams, InvokeEndpointResponse, SageMakerStreamChunk, SageMakerToolCall, SageMakerToolResult, SageMakerGenerationOptions, SageMakerGenerationResponse, SageMakerErrorCode, SageMakerErrorInfo, BatchInferenceConfig, ModelDeploymentConfig, EndpointMetrics, CostEstimate, } from "./types.js";
+/**
+ * Factory function to create a SageMaker Provider
+ *
+ * @param modelName - Optional model name
+ * @param endpointName - Optional endpoint name
+ * @returns AmazonSageMakerProvider instance
+ */
+export declare function createSageMakerProvider(modelName?: string, endpointName?: string): AmazonSageMakerProvider;
+/**
+ * Utility function to validate SageMaker setup (Simplified)
+ *
+ * @returns Setup validation result
+ */
+export declare function validateSageMakerSetup(): Promise<{
+    valid: boolean;
+    issues: string[];
+    recommendations: string[];
+    configSummary: Record<string, unknown>;
+}>;
+/**
+ * Default export for convenience
+ */
+export { AmazonSageMakerProvider as default };

package/dist/providers/sagemaker/index.js

@@ -0,0 +1,67 @@
+/**
+ * Amazon SageMaker Provider - Main Export Module (Simplified)
+ *
+ * This module provides the main exports for SageMaker integration (Phase 1).
+ * Full implementation will be completed in subsequent phases.
+ */
+// Import for internal use
+import { AmazonSageMakerProvider } from "../amazonSagemaker.js";
+import { checkSageMakerConfiguration } from "./config.js";
+// Core provider exports
+export { AmazonSageMakerProvider } from "../amazonSagemaker.js";
+export { SageMakerRuntimeClient, createSageMakerRuntimeClient, testSageMakerConnectivity, } from "./client.js";
+// Configuration exports
+export { getSageMakerConfig, getSageMakerModelConfig, getDefaultSageMakerEndpoint, getSageMakerModel, validateAWSCredentials, getConfigurationSummary, clearConfigurationCache, loadConfigurationFromFile, checkSageMakerConfiguration, } from "./config.js";
+// Error handling exports
+export { SageMakerError, handleSageMakerError, createValidationError, createCredentialsError, createNetworkError, isRetryableError, getRetryDelay, } from "./errors.js";
+/**
+ * Factory function to create a SageMaker Provider
+ *
+ * @param modelName - Optional model name
+ * @param endpointName - Optional endpoint name
+ * @returns AmazonSageMakerProvider instance
+ */
+export function createSageMakerProvider(modelName, endpointName) {
+    return new AmazonSageMakerProvider(modelName, endpointName);
+}
+/**
+ * Utility function to validate SageMaker setup (Simplified)
+ *
+ * @returns Setup validation result
+ */
+export async function validateSageMakerSetup() {
+    const issues = [];
+    const recommendations = [];
+    try {
+        // Check configuration
+        const configCheck = checkSageMakerConfiguration();
+        if (!configCheck.configured) {
+            issues.push(...configCheck.issues);
+        }
+        // Add general recommendations
+        if (issues.length === 0) {
+            recommendations.push("SageMaker basic configuration appears valid");
+            recommendations.push("Full functionality will be available in Phase 2");
+        }
+        return {
+            valid: issues.length === 0,
+            issues,
+            recommendations,
+            configSummary: configCheck.summary,
+        };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            issues: [
+                `Setup validation failed: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+            recommendations: ["Check your SageMaker configuration and try again"],
+            configSummary: {},
+        };
+    }
+}
+/**
+ * Default export for convenience
+ */
+export { AmazonSageMakerProvider as default };

package/dist/providers/sagemaker/language-model.d.ts

@@ -0,0 +1,182 @@
+/**
+ * SageMaker Language Model Implementation
+ *
+ * This module implements the LanguageModelV1 interface for Amazon SageMaker
+ * integration with the Vercel AI SDK.
+ */
+import type { LanguageModelV1, LanguageModelV1CallOptions, LanguageModelV1StreamPart } from "ai";
+import type { SageMakerConfig, SageMakerModelConfig } from "./types.js";
+/**
+ * SageMaker Language Model implementing LanguageModelV1 interface
+ */
+export declare class SageMakerLanguageModel implements LanguageModelV1 {
+    readonly specificationVersion = "v1";
+    readonly provider = "sagemaker";
+    readonly modelId: string;
+    readonly supportsStreaming = true;
+    readonly defaultObjectGenerationMode: "json";
+    private client;
+    private config;
+    private modelConfig;
+    constructor(modelId: string, config: SageMakerConfig, modelConfig: SageMakerModelConfig);
+    /**
+     * Generate text synchronously using SageMaker endpoint
+     */
+    doGenerate(options: LanguageModelV1CallOptions): Promise<{
+        text?: string;
+        reasoning?: string | Array<{
+            type: "text";
+            text: string;
+            signature?: string;
+        } | {
+            type: "redacted";
+            data: string;
+        }>;
+        files?: Array<{
+            data: string | Uint8Array;
+            mimeType: string;
+        }>;
+        logprobs?: Array<{
+            token: string;
+            logprob: number;
+            topLogprobs: Array<{
+                token: string;
+                logprob: number;
+            }>;
+        }>;
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens?: number;
+        };
+        finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "unknown";
+        warnings?: Array<{
+            type: "other";
+            message: string;
+        }>;
+        rawCall: {
+            rawPrompt: unknown;
+            rawSettings: Record<string, unknown>;
+        };
+        rawResponse?: {
+            headers?: Record<string, string>;
+        };
+        request?: {
+            body?: string;
+        };
+    }>;
+    /**
+     * Generate text with streaming using SageMaker endpoint
+     */
+    doStream(options: LanguageModelV1CallOptions): Promise<{
+        stream: ReadableStream<LanguageModelV1StreamPart>;
+        rawCall: {
+            rawPrompt: unknown;
+            rawSettings: Record<string, unknown>;
+        };
+        rawResponse?: {
+            headers?: Record<string, string>;
+        };
+        request?: {
+            body?: string;
+        };
+        warnings?: Array<{
+            type: "other";
+            message: string;
+        }>;
+    }>;
+    /**
+     * Convert AI SDK options to SageMaker request format
+     */
+    private convertToSageMakerRequest;
+    /**
+     * Convert Vercel AI SDK tools to SageMaker format
+     */
+    private convertToolsToSageMakerFormat;
+    /**
+     * Convert Vercel AI SDK tool choice to SageMaker format
+     */
+    private convertToolChoiceToSageMakerFormat;
+    /**
+     * Convert Vercel AI SDK response format to SageMaker format (Phase 4)
+     */
+    private convertResponseFormatToSageMakerFormat;
+    /**
+     * Extract text content from AI SDK prompt format
+     */
+    private extractPromptText;
+    /**
+     * Extract generated text from SageMaker response
+     */
+    private extractTextFromResponse;
+    /**
+     * Extract tool calls from SageMaker response (Phase 4)
+     */
+    private extractToolCallsFromResponse;
+    /**
+     * Map SageMaker finish reason to standardized format
+     */
+    private mapSageMakerFinishReason;
+    /**
+     * Get model configuration summary for debugging
+     */
+    getModelInfo(): {
+        modelId: string;
+        provider: string;
+        specificationVersion: string;
+        endpointName: string;
+        modelType: "huggingface" | "mistral" | "custom" | "claude" | "llama" | "jumpstart" | undefined;
+        region: string;
+    };
+    /**
+     * Test basic connectivity to the SageMaker endpoint
+     */
+    testConnectivity(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Batch inference support (Phase 4)
+     * Process multiple prompts in a single request for efficiency
+     */
+    doBatchGenerate(prompts: string[], options?: {
+        maxTokens?: number;
+        temperature?: number;
+        topP?: number;
+    }): Promise<Array<{
+        text: string;
+        usage: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "error" | "unknown";
+    }>>;
+    /**
+     * Process prompts in parallel with advanced concurrency control and error handling
+     */
+    private processPromptsInParallel;
+    /**
+     * Enhanced model information with batch capabilities
+     */
+    getModelCapabilities(): {
+        capabilities: {
+            streaming: boolean;
+            toolCalling: boolean;
+            structuredOutput: boolean;
+            batchInference: boolean;
+            supportedResponseFormats: string[];
+            supportedToolTypes: string[];
+            maxBatchSize: number;
+            adaptiveConcurrency: boolean;
+            errorRecovery: boolean;
+        };
+        modelId: string;
+        provider: string;
+        specificationVersion: string;
+        endpointName: string;
+        modelType: "huggingface" | "mistral" | "custom" | "claude" | "llama" | "jumpstart" | undefined;
+        region: string;
+    };
+}
+export default SageMakerLanguageModel;