@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/utils/providerRetry.js

@@ -0,0 +1,112 @@
+/**
+ * Provider-level retry utility for AI SDK calls (NL11)
+ *
+ * The Vercel AI SDK's `generateText()` and `streamText()` have built-in retry
+ * logic (`_retryWithExponentialBackoff()` with default `maxRetries: 2`) that
+ * retries on HTTP 429/500/503. These retries are completely invisible to OTel
+ * because they happen inside the AI SDK.
+ *
+ * This module provides an instrumented retry wrapper that:
+ * 1. Disables the AI SDK's internal retries (via `maxRetries: 0`)
+ * 2. Implements our own retry loop with full OTel span events
+ * 3. Records retry attempts, delays, status codes, and total attempt count
+ *
+ * @module utils/providerRetry
+ */
+import { APICallError } from "@ai-sdk/provider";
+import { logger } from "./logger.js";
+/** Maximum number of retry attempts after the initial call (total = 1 + MAX_PROVIDER_RETRIES). */
+export const MAX_PROVIDER_RETRIES = 2;
+/** Base delay in ms for exponential backoff between retries. */
+export const BASE_RETRY_DELAY_MS = 1000;
+/**
+ * Check whether an error thrown by the AI SDK is retryable.
+ *
+ * Uses `APICallError.isInstance()` for proper type-safe detection (the class
+ * uses a branded symbol marker, so `instanceof` doesn't work across package
+ * boundaries). Falls back to duck-typing for non-APICallError cases.
+ */
+export function isRetryableProviderError(error) {
+    // Preferred path: use the AI SDK's own branded type check + isRetryable flag
+    if (APICallError.isInstance(error)) {
+        return error.isRetryable;
+    }
+    // Fallback: duck-type for status codes on errors that aren't APICallError
+    if (error && typeof error === "object" && "statusCode" in error) {
+        const statusCode = error.statusCode;
+        return statusCode === 429 || statusCode >= 500;
+    }
+    return false;
+}
+/**
+ * Extract the HTTP status code from an AI SDK error, if available.
+ */
+export function getErrorStatusCode(error) {
+    if (APICallError.isInstance(error)) {
+        return error.statusCode;
+    }
+    if (error && typeof error === "object" && "statusCode" in error) {
+        return error.statusCode;
+    }
+    return undefined;
+}
+/**
+ * Execute a provider call with instrumented retry logic.
+ *
+ * @param operation  - The async operation to execute (should already use `maxRetries: 0`)
+ * @param span       - The OTel span to annotate with retry events and attributes
+ * @param label      - A human-readable label for log messages (e.g. "generateText", "streamText")
+ * @returns The result of the operation
+ */
+export async function withProviderRetry(operation, span, label) {
+    for (let attempt = 0; attempt <= MAX_PROVIDER_RETRIES; attempt++) {
+        try {
+            const result = await operation();
+            // Record how many attempts it took on the span
+            span.setAttribute("gen_ai.provider.total_attempts", attempt + 1);
+            if (attempt > 0) {
+                logger.info(`[providerRetry] ${label} succeeded after ${attempt + 1} attempts`);
+            }
+            return result;
+        }
+        catch (error) {
+            const retryable = isRetryableProviderError(error);
+            const statusCode = getErrorStatusCode(error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (!retryable || attempt === MAX_PROVIDER_RETRIES) {
+                // Record failure details before re-throwing
+                span.setAttribute("gen_ai.provider.total_attempts", attempt + 1);
+                if (attempt > 0) {
+                    span.setAttribute("gen_ai.provider.retries_exhausted", true);
+                }
+                logger.warn(`[providerRetry] ${label} failed (non-retryable or retries exhausted)`, {
+                    attempt: attempt + 1,
+                    retryable,
+                    statusCode,
+                    error: errorMessage,
+                });
+                throw error;
+            }
+            // Calculate exponential backoff delay
+            const delay = BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+            // Record retry event on the OTel span
+            span.addEvent("gen_ai.provider.retry", {
+                "retry.attempt": attempt + 1,
+                "retry.delay_ms": delay,
+                ...(statusCode !== undefined && { "retry.status_code": statusCode }),
+                "retry.error": errorMessage.slice(0, 256),
+            });
+            logger.warn(`[providerRetry] ${label} retrying after ${statusCode || "unknown"} error`, {
+                attempt: attempt + 1,
+                maxRetries: MAX_PROVIDER_RETRIES,
+                delayMs: delay,
+                statusCode,
+                error: errorMessage,
+            });
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    // This should never be reached due to the throw inside the loop,
+    // but TypeScript requires it for exhaustiveness.
+    throw new Error(`[providerRetry] ${label} exhausted all retries`);
+}

package/dist/client/utils/providerUtils.js

@@ -0,0 +1,434 @@
+/**
+ * Utility functions for AI provider management
+ * Consolidated from providerUtils-fixed.ts
+ */
+import { AIProviderFactory } from "../core/factory.js";
+import { logger } from "./logger.js";
+import { ProviderHealthChecker } from "./providerHealth.js";
+import { API_KEY_FORMATS, API_KEY_LENGTHS, PROJECT_ID_FORMAT, } from "./providerConfig.js";
+/**
+ * Get the best available provider based on real-time availability checks
+ * Enhanced version consolidated from providerUtils-fixed.ts
+ * @param requestedProvider - Optional preferred provider name
+ * @returns The best provider name to use
+ */
+export async function getBestProvider(requestedProvider) {
+    // Check requested provider FIRST - explicit user choice overrides defaults
+    if (requestedProvider && requestedProvider !== "auto") {
+        // For explicit provider requests, ALWAYS honor the request
+        // Never override explicit provider selection with health-based fallbacks
+        logger.debug(`[getBestProvider] Using explicitly requested provider: ${requestedProvider}`);
+        // Optional health check for logging purposes only
+        try {
+            const health = await ProviderHealthChecker.checkProviderHealth(requestedProvider, { includeConnectivityTest: false, cacheResults: true });
+            if (health.isHealthy) {
+                logger.debug(`[getBestProvider] Explicitly requested provider ${requestedProvider} is healthy`);
+            }
+            else {
+                logger.warn(`[getBestProvider] Explicitly requested provider ${requestedProvider} may have issues, but using anyway`, { error: health.error });
+            }
+        }
+        catch (error) {
+            logger.warn(`[getBestProvider] Health check failed for explicitly requested provider ${requestedProvider}, using anyway`, { error: error instanceof Error ? error.message : String(error) });
+        }
+        // ALWAYS return the explicitly requested provider
+        return requestedProvider;
+    }
+    // Use health checker to get best available provider
+    const healthyProvider = await ProviderHealthChecker.getBestHealthyProvider();
+    if (healthyProvider) {
+        logger.debug(`[getBestProvider] Selected healthy provider: ${healthyProvider}`);
+        return healthyProvider;
+    }
+    // Fallback to legacy provider checking if health system fails
+    logger.warn("[getBestProvider] Health system failed, falling back to legacy checking");
+    // Check for explicit default provider in env (only when no provider requested)
+    if (process.env.DEFAULT_PROVIDER &&
+        (await isProviderAvailable(process.env.DEFAULT_PROVIDER))) {
+        logger.debug(`[getBestProvider] Using default provider from env: ${process.env.DEFAULT_PROVIDER}`);
+        return process.env.DEFAULT_PROVIDER;
+    }
+    // Special case for Ollama - prioritize local when available
+    if (process.env.OLLAMA_BASE_URL && process.env.OLLAMA_MODEL) {
+        try {
+            if (await isProviderAvailable("ollama")) {
+                logger.debug(`[getBestProvider] Prioritizing working local Ollama`);
+                return "ollama"; // Prioritize working local AI
+            }
+        }
+        catch {
+            // Fall through to cloud providers
+        }
+    }
+    /**
+     * Provider priority order rationale:
+     * - Vertex (Google Cloud AI) is prioritized first for its enterprise-grade reliability and advanced model capabilities.
+     * - Google AI follows as second priority for comprehensive Google AI ecosystem support.
+     * - OpenAI maintains high priority due to its consistent reliability and broad model support.
+     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance in our use cases.
+     * - Ollama is kept as a fallback for local deployments when available.
+     * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
+     */
+    const providers = [
+        "vertex", // Prioritize Google Cloud AI (Vertex) first
+        "google-ai", // Google AI ecosystem support
+        "openai", // Reliable with broad model support
+        "anthropic",
+        "bedrock",
+        "azure",
+        "mistral",
+        "huggingface",
+        "ollama", // Keep as fallback
+    ];
+    for (const provider of providers) {
+        if (await isProviderAvailable(provider)) {
+            logger.debug(`[getBestProvider] Selected provider: ${provider}`);
+            return provider;
+        }
+    }
+    throw new Error("No available AI providers. Please check your configurations.");
+}
+/**
+ * Check if a provider is truly available by performing a quick authentication test.
+ * Enhanced function consolidated from providerUtils-fixed.ts
+ * @param providerName - The name of the provider to check.
+ * @returns True if the provider is available and authenticated.
+ */
+async function isProviderAvailable(providerName) {
+    if (!hasProviderEnvVars(providerName) && providerName !== "ollama") {
+        return false;
+    }
+    if (providerName === "ollama") {
+        try {
+            const response = await fetch("http://localhost:11434/api/tags", {
+                method: "GET",
+                signal: AbortSignal.timeout(2000),
+            });
+            if (response.ok) {
+                const { models } = await response.json();
+                const defaultOllamaModel = "llama3.2:latest";
+                return models.some((m) => m.name === defaultOllamaModel);
+            }
+            return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        const provider = await AIProviderFactory.createProvider(providerName);
+        await provider.generate({ prompt: "test", maxTokens: 1 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate environment variable values for a provider
+ * Addresses GitHub Copilot comment about adding environment variable validation
+ * @param provider - Provider name to validate
+ * @returns Validation result with detailed information
+ */
+export function validateProviderEnvVars(provider) {
+    const result = {
+        isValid: true,
+        missingVars: [],
+        invalidVars: [],
+        warnings: [],
+    };
+    switch (provider.toLowerCase()) {
+        case "bedrock":
+        case "amazon":
+        case "aws":
+            validateAwsCredentials(result);
+            break;
+        case "vertex":
+        case "googlevertex":
+        case "google":
+        case "gemini":
+            validateVertexCredentials(result);
+            break;
+        case "openai":
+        case "gpt":
+            validateOpenAICredentials(result);
+            break;
+        case "anthropic":
+        case "claude":
+            validateAnthropicCredentials(result);
+            break;
+        case "azure":
+        case "azureopenai":
+            validateAzureCredentials(result);
+            break;
+        case "google-ai":
+        case "google-studio":
+            validateGoogleAICredentials(result);
+            break;
+        case "huggingface":
+        case "hugging-face":
+        case "hf":
+            validateHuggingFaceCredentials(result);
+            break;
+        case "mistral":
+        case "mistral-ai":
+        case "mistralai":
+            validateMistralCredentials(result);
+            break;
+        case "ollama":
+        case "local":
+        case "local-ollama":
+            // Ollama doesn't require environment variables
+            break;
+        case "litellm":
+            // LiteLLM validation can be added if needed
+            break;
+        default:
+            result.isValid = false;
+            result.warnings.push(`Unknown provider: ${provider}`);
+    }
+    result.isValid =
+        result.missingVars.length === 0 && result.invalidVars.length === 0;
+    return result;
+}
+/**
+ * Validate AWS credentials with flexible validation
+ * Note: AWS credential formats can vary, so validation is kept reasonably flexible
+ */
+function validateAwsCredentials(result) {
+    const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+    const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+    if (!accessKeyId) {
+        result.missingVars.push("AWS_ACCESS_KEY_ID");
+    }
+    else if (!/^[A-Z0-9]{16,}$/.test(accessKeyId)) {
+        // Flexible validation: at least 16 uppercase alphanumeric characters
+        result.invalidVars.push("AWS_ACCESS_KEY_ID (should be uppercase alphanumeric characters, typically 20 chars)");
+    }
+    if (!secretAccessKey) {
+        result.missingVars.push("AWS_SECRET_ACCESS_KEY");
+    }
+    else if (!/^[A-Za-z0-9+/]{30,}$/.test(secretAccessKey)) {
+        // Flexible validation: at least 30 base64 characters (can vary in length)
+        result.invalidVars.push("AWS_SECRET_ACCESS_KEY (should be base64 characters, typically 40+ chars)");
+    }
+    if (!region) {
+        result.warnings.push("AWS_REGION not set, will use default region");
+    }
+}
+/**
+ * Validate Google Vertex credentials
+ */
+function validateVertexCredentials(result) {
+    const projectId = process.env.GOOGLE_CLOUD_PROJECT_ID ||
+        process.env.VERTEX_PROJECT_ID ||
+        process.env.GOOGLE_VERTEX_PROJECT ||
+        process.env.GOOGLE_CLOUD_PROJECT;
+    const hasCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+        process.env.GOOGLE_SERVICE_ACCOUNT_KEY ||
+        (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+            process.env.GOOGLE_AUTH_PRIVATE_KEY);
+    if (!projectId) {
+        result.missingVars.push("GOOGLE_CLOUD_PROJECT_ID (or variant)");
+    }
+    else if (!PROJECT_ID_FORMAT.PATTERN.test(projectId)) {
+        result.invalidVars.push("Project ID format invalid (must be 6-30 lowercase letters, digits, hyphens)");
+    }
+    if (!hasCredentials) {
+        result.missingVars.push("Google credentials (GOOGLE_APPLICATION_CREDENTIALS or explicit auth)");
+    }
+    if (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+        !isValidEmail(process.env.GOOGLE_AUTH_CLIENT_EMAIL)) {
+        result.invalidVars.push("GOOGLE_AUTH_CLIENT_EMAIL (invalid email format)");
+    }
+}
+/**
+ * Validate OpenAI credentials
+ */
+function validateOpenAICredentials(result) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("OPENAI_API_KEY");
+    }
+    else if (!API_KEY_FORMATS.openai.test(apiKey)) {
+        result.invalidVars.push(`OPENAI_API_KEY (should start with 'sk-' followed by ${API_KEY_LENGTHS.OPENAI_MIN}+ characters)`);
+    }
+}
+/**
+ * Validate Anthropic credentials
+ */
+function validateAnthropicCredentials(result) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("ANTHROPIC_API_KEY");
+    }
+    else if (!API_KEY_FORMATS.anthropic.test(apiKey)) {
+        result.invalidVars.push(`ANTHROPIC_API_KEY (should start with 'sk-ant-' followed by ${API_KEY_LENGTHS.ANTHROPIC_MIN}+ characters)`);
+    }
+}
+/**
+ * Validate Azure credentials
+ */
+function validateAzureCredentials(result) {
+    const apiKey = process.env.AZURE_OPENAI_API_KEY;
+    const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
+    if (!apiKey) {
+        result.missingVars.push("AZURE_OPENAI_API_KEY");
+    }
+    else if (!API_KEY_FORMATS.azure.test(apiKey)) {
+        result.invalidVars.push(`AZURE_OPENAI_API_KEY (should be at least ${API_KEY_LENGTHS.AZURE_MIN} alphanumeric characters)`);
+    }
+    if (!endpoint) {
+        result.missingVars.push("AZURE_OPENAI_ENDPOINT");
+    }
+    else if (!isValidUrl(endpoint)) {
+        result.invalidVars.push("AZURE_OPENAI_ENDPOINT (should be a valid HTTPS URL)");
+    }
+}
+/**
+ * Validate Google AI credentials
+ */
+function validateGoogleAICredentials(result) {
+    const apiKey = process.env.GOOGLE_AI_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("GOOGLE_AI_API_KEY (or GOOGLE_GENERATIVE_AI_API_KEY)");
+    }
+    else if (!API_KEY_FORMATS["google-ai"].test(apiKey)) {
+        result.invalidVars.push(`GOOGLE_AI_API_KEY (should be ${API_KEY_LENGTHS.GOOGLE_AI_EXACT} alphanumeric characters with dashes/underscores)`);
+    }
+}
+/**
+ * Validate HuggingFace credentials
+ */
+function validateHuggingFaceCredentials(result) {
+    const apiKey = process.env.HUGGINGFACE_API_KEY || process.env.HF_TOKEN;
+    if (!apiKey) {
+        result.missingVars.push("HUGGINGFACE_API_KEY (or HF_TOKEN)");
+    }
+    else if (!API_KEY_FORMATS.huggingface.test(apiKey)) {
+        result.invalidVars.push(`HUGGINGFACE_API_KEY (should start with 'hf_' followed by ${API_KEY_LENGTHS.HUGGINGFACE_EXACT} characters)`);
+    }
+}
+/**
+ * Validate Mistral credentials
+ */
+function validateMistralCredentials(result) {
+    const apiKey = process.env.MISTRAL_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("MISTRAL_API_KEY");
+    }
+    else if (!API_KEY_FORMATS.mistral.test(apiKey)) {
+        result.invalidVars.push(`MISTRAL_API_KEY (should be ${API_KEY_LENGTHS.MISTRAL_EXACT} alphanumeric characters)`);
+    }
+}
+/**
+ * Helper function to validate email format
+ */
+function isValidEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+}
+/**
+ * Helper function to validate URL format
+ */
+function isValidUrl(url) {
+    try {
+        const parsedUrl = new URL(url);
+        return parsedUrl.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a provider has the minimum required environment variables
+ * NOTE: This only checks if variables exist, not if they're valid
+ * For validation, use validateProviderEnvVars instead
+ * @param provider - Provider name to check
+ * @returns True if the provider has required environment variables
+ */
+export function hasProviderEnvVars(provider) {
+    switch (provider.toLowerCase()) {
+        case "bedrock":
+        case "amazon":
+        case "aws":
+            return !!(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY);
+        case "vertex":
+        case "googlevertex":
+        case "google":
+        case "gemini":
+            return !!((process.env.GOOGLE_CLOUD_PROJECT_ID ||
+                process.env.VERTEX_PROJECT_ID ||
+                process.env.GOOGLE_VERTEX_PROJECT ||
+                process.env.GOOGLE_CLOUD_PROJECT) &&
+                (process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+                    process.env.GOOGLE_SERVICE_ACCOUNT_KEY ||
+                    (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+                        process.env.GOOGLE_AUTH_PRIVATE_KEY)));
+        case "openai":
+        case "gpt":
+            return !!process.env.OPENAI_API_KEY;
+        case "anthropic":
+        case "claude":
+            return !!process.env.ANTHROPIC_API_KEY;
+        case "azure":
+        case "azureopenai":
+            return !!process.env.AZURE_OPENAI_API_KEY;
+        case "google-ai":
+        case "google-studio":
+            return !!(process.env.GOOGLE_AI_API_KEY ||
+                process.env.GOOGLE_GENERATIVE_AI_API_KEY);
+        case "huggingface":
+        case "hugging-face":
+        case "hf":
+            return !!(process.env.HUGGINGFACE_API_KEY || process.env.HF_TOKEN);
+        case "ollama":
+        case "local":
+        case "local-ollama":
+            // For Ollama, we check if the service is potentially available
+            // This is a basic check - actual connectivity will be verified during usage
+            return true; // Ollama doesn't require environment variables, just local service
+        case "mistral":
+        case "mistral-ai":
+        case "mistralai":
+            return !!process.env.MISTRAL_API_KEY;
+        case "litellm":
+            // LiteLLM requires a proxy server, which can be checked for availability
+            // Default base URL is assumed, or can be configured via environment
+            return true; // LiteLLM proxy availability will be checked during usage
+        default:
+            return false;
+    }
+}
+/**
+ * Get available provider names
+ * @returns Array of available provider names
+ */
+export function getAvailableProviders() {
+    return [
+        "bedrock",
+        "vertex",
+        "openai",
+        "anthropic",
+        "azure",
+        "google-ai",
+        "huggingface",
+        "ollama",
+        "mistral",
+    ];
+}
+/**
+ * Validate provider name
+ * @param provider - Provider name to validate
+ * @returns True if provider name is valid
+ */
+export function isValidProvider(provider) {
+    return getAvailableProviders().includes(provider.toLowerCase());
+}
+/**
+ * Type guard for provider error
+ */
+export function isProviderError(error) {
+    return error instanceof Error && "provider" in error;
+}