@juspay/neurolink 10.12.9 → 11.1.0

package/dist/lib/types/providers.d.ts

@@ -96,6 +96,7 @@ export type NeurolinkCredentials = {
     };
     googleAiStudio?: {
         apiKey?: string;
+        baseURL?: string;
     };
     vertex?: {
         projectId?: string;
@@ -200,6 +201,8 @@ export type NeurolinkCredentials = {
     replicate?: {
         apiToken?: string;
         baseUrl?: string;
+        apiKey?: string;
+        baseURL?: string;
     };
     voyage?: {
         apiKey?: string;
@@ -886,6 +889,8 @@ export type GenAIClient = {
 export type GoogleGenAIHttpOptions = {
     /** Custom fetch implementation for proxy support */
     fetch?: typeof fetch;
+    /** Override the API base URL (e.g. a corporate proxy or mock endpoint) */
+    baseUrl?: string;
 };
 /**
  * Google GenAI constructor type
@@ -1531,17 +1536,6 @@ export declare namespace TelemetryTypes {
         recordException(exception: unknown): void;
     };
 }
-/**
- * OpenRouter provider configuration
- */
-export type OpenRouterConfig = {
-    /** OpenRouter API key */
-    apiKey: string;
-    /** HTTP Referer header for attribution on openrouter.ai/activity */
-    referer?: string;
-    /** App name for X-Title header attribution */
-    appName?: string;
-};
 /**
  * OpenRouter model information from /api/v1/models endpoint
  */
@@ -1686,6 +1680,67 @@ export type ProviderRegistration = {
     constructor: ProviderConstructor;
     defaultModel?: string;
     aliases?: string[];
+    descriptor?: ProviderDescriptor;
+};
+/**
+ * Single source of truth for one AI provider's static identity: how it's
+ * addressed (name/aliases), how it's authenticated (credentialsKey/envVars),
+ * what it defaults to (defaultModel), and how the rest of the codebase
+ * should treat it (toolSupport/localRuntime/healthCheck). Every consumer
+ * that used to hand-maintain its own provider table (CLI choices,
+ * CREDENTIAL_KEY_MAP, env-var checks, health-check dispatch, auto-select
+ * priority, PROMPT_ONLY_TOOL_PROVIDERS) derives from PROVIDER_DESCRIPTORS
+ * instead. See src/lib/factories/providerDescriptors.ts for the data.
+ */
+export type ProviderDescriptor = {
+    /** Canonical identity — matches an AIProviderName enum member (never AUTO). */
+    name: AIProviderName;
+    /** Alternate spellings accepted by the CLI and the alias index (kebab-case, shorthand, legacy names). Does not include `name` itself. */
+    aliases: readonly string[];
+    /** Key into NeurolinkCredentials for per-call/per-instance credential overrides. */
+    credentialsKey: keyof NeurolinkCredentials;
+    /** Environment variables this provider reads at runtime. */
+    envVars: {
+        /** Primary identity/secret env var. Absent for providers with no required credential (Ollama, LM Studio, llama.cpp) or that use extraRequired instead of a single key (Vertex). */
+        apiKey?: string;
+        /** Alternate env vars accepted in place of apiKey, checked in order after apiKey. */
+        fallbacks?: readonly string[];
+        baseURL?: string;
+        /** Alternate env vars accepted in place of baseURL. */
+        baseURLFallbacks?: readonly string[];
+        /** Env var that overrides the static defaultModel at runtime. */
+        model?: string;
+        /** Alternate env vars accepted in place of model, checked in order after model. */
+        modelFallbacks?: readonly string[];
+        /** Additional env vars required alongside apiKey (e.g. AWS secret key, Azure endpoint). */
+        extraRequired?: readonly string[];
+        /** Alternate ways to satisfy extraRequired when it isn't a plain env-var list (e.g. Vertex's file-path-OR-individual-fields auth). */
+        extraRequiredFallbacks?: readonly string[];
+        /** True when the provider is usable with zero configuration (local runtime with a documented default URL, or a documented non-secret default like LiteLLM's "sk-anything"). */
+        optional?: boolean;
+    };
+    /**
+     * Static fallback model. The empty string "" is a documented sentinel
+     * meaning "no static default — resolved at runtime via envVars.model or
+     * provider-side auto-discovery" (used by Bedrock, OpenAI-Compatible,
+     * LM Studio, llama.cpp, matching how providerRegistry.ts already passes
+     * `undefined` as their defaultModel argument today).
+     */
+    defaultModel: string;
+    toolSupport: "native" | "prompt-only" | "none" | "model-dependent";
+    /** True only for providers that run entirely on the caller's machine with no cloud account (Ollama, LM Studio, llama.cpp). LiteLLM is a local proxy but commonly points at cloud models, so it is deliberately false. */
+    localRuntime: boolean;
+    /** How ProviderHealthChecker should verify this provider is reachable. */
+    healthCheck: "env-only" | "models-probe" | "live-generate";
+    setupUrl?: string;
+    timeouts?: {
+        generateMs?: number;
+        streamMs?: number;
+    };
+    /** Ascending priority (1 = tried first) in the auto-select fallback chain used by getBestProvider(). Undefined = not part of the auto-select chain. */
+    autoSelectPriority?: number;
+    /** Format-validation regex sourced from providerConfig.ts's API_KEY_FORMATS, when one exists for this provider. */
+    apiKeyFormatPattern?: RegExp;
 };
 /** Minimal NeuroLink-like instance accepted by the image generation service. */
 export type NeuroLinkInstance = {

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

@@ -0,0 +1,30 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { type ProviderErrorRule } from "../types/index.js";
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export declare function classifyProviderError(error: unknown, rules: ProviderErrorRule[], provider: string, modelName?: string): Error;
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export declare const DEFAULT_ERROR_RULES: ProviderErrorRule[];

package/dist/lib/utils/errorClassifier.js

@@ -0,0 +1,94 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { ProviderError, AuthenticationError, RateLimitError, InvalidModelError, NetworkError, } from "../types/index.js";
+import { TimeoutError } from "./timeout.js";
+import { duckTypedStatusCode } from "./providerRetry.js";
+function buildErrorContext(error, provider, modelName) {
+    const record = error && typeof error === "object"
+        ? error
+        : undefined;
+    const message = typeof record?.message === "string"
+        ? record.message
+        : error instanceof Error
+            ? error.message
+            : "Unknown error";
+    return {
+        error,
+        message,
+        statusCode: duckTypedStatusCode(error),
+        errorName: typeof record?.name === "string" ? record.name : undefined,
+        errorCode: typeof record?.code === "string" ? record.code : undefined,
+        provider,
+        modelName,
+    };
+}
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export function classifyProviderError(error, rules, provider, modelName) {
+    if (error instanceof TimeoutError) {
+        return new NetworkError(`Request timed out: ${error.message}`, provider);
+    }
+    const ctx = buildErrorContext(error, provider, modelName);
+    const rule = rules.find((r) => r.match(ctx));
+    if (!rule) {
+        return new ProviderError(`${provider} error: ${ctx.message}`, provider);
+    }
+    const message = typeof rule.message === "function" ? rule.message(ctx) : rule.message;
+    return new rule.errorClass(message, provider);
+}
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export const DEFAULT_ERROR_RULES = [
+    {
+        match: (ctx) => ctx.statusCode === 401 ||
+            /API_KEY_INVALID|Invalid API key|Unauthorized|invalid_api_key/i.test(ctx.message),
+        errorClass: AuthenticationError,
+        message: (ctx) => `Invalid ${ctx.provider} API key. Please check your credentials.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 429 || /rate limit/i.test(ctx.message),
+        errorClass: RateLimitError,
+        message: (ctx) => `${ctx.provider} rate limit exceeded. Please try again later.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 404 ||
+            /model_not_found|model not found/i.test(ctx.message),
+        errorClass: InvalidModelError,
+        message: (ctx) => ctx.modelName
+            ? `${ctx.provider} model '${ctx.modelName}' not found.`
+            : `${ctx.provider} model not found.`,
+    },
+    {
+        match: (ctx) => /ECONNRESET|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|connection/i.test(ctx.message),
+        errorClass: NetworkError,
+        message: (ctx) => `Connection error: ${ctx.message}`,
+    },
+    {
+        match: (ctx) => (ctx.statusCode !== undefined && ctx.statusCode >= 500) ||
+            /\b5\d\d\b|server error/i.test(ctx.message),
+        errorClass: ProviderError,
+        message: (ctx) => `${ctx.provider} server error: ${ctx.message}`,
+    },
+];
+//# sourceMappingURL=errorClassifier.js.map

package/dist/lib/utils/fileDetector.js

@@ -26,6 +26,7 @@ import { fileTypeForExtension, lookupByMimeType, normalizeExtension, } from "../
 import { LANGUAGE_MAP } from "../processors/config/languageMap.js";
 import { getMimeTypeForExtension, TEXT_EXTENSION_MIME_MAP, } from "../processors/config/mimeConstants.js";
 import { CSVProcessor } from "./csvProcessor.js";
+import { withRetry } from "../core/infrastructure/retry.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { detectIsoBmffImageMimeType, hasFtypBoxSignature } from "./isoBmff.js";
 import { logger } from "./logger.js";
@@ -34,11 +35,6 @@ import { withTimeout } from "./errorHandling.js";
 import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
-/**
- * Default retry configuration constants
- */
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_RETRY_DELAY = 1000; // milliseconds
 /**
  * Short-TTL cache of URL → Content-Type (#323). A URL is commonly detected more
  * than once (repeated multimodal prompts reuse the same asset URL); caching the
@@ -202,41 +198,6 @@ function isRetryableNetworkError(error) {
     ];
     return transientKeywords.some((keyword) => errorMessage.includes(keyword));
 }
-/**
- * Execute an operation with automatic retry logic on transient network errors
- *
- * @param operation - Async function to execute
- * @param options - Retry configuration options
- * @returns Promise resolving to the operation result
- * @throws Error if all retry attempts fail or error is non-retryable
- */
-async function withRetry(operation, options = {}) {
-    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const retryDelay = options.retryDelay ?? DEFAULT_RETRY_DELAY;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            return await operation();
-        }
-        catch (error) {
-            const isRetryable = isRetryableNetworkError(error);
-            const isLastAttempt = attempt === maxRetries;
-            if (!isRetryable || isLastAttempt) {
-                throw error;
-            }
-            // Calculate exponential backoff delay
-            const delay = retryDelay * 2 ** attempt;
-            logger.debug("Retrying network operation after transient error", {
-                attempt: attempt + 1,
-                maxRetries,
-                delay,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            await new Promise((resolve) => setTimeout(resolve, delay));
-        }
-    }
-    // TypeScript exhaustiveness check - should never reach here
-    throw new Error("Retry logic failed unexpectedly");
-}
 /**
  * Check if text has JSON markers (starts with { or [ and ends with corresponding closing bracket)
  */
@@ -1542,8 +1503,6 @@ export class FileDetector {
     static async loadFromURL(url, options) {
         const maxSize = options?.maxSize || 200 * 1024 * 1024; // 200MB default (matches Curator memory-safety cap)
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
-        const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
-        const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
         // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
         // body. content-length is advisory (chunked responses omit it), so a
         // missing/invalid header — or a server that refuses HEAD — falls through to
@@ -1641,7 +1600,11 @@ export class FileDetector {
                 }
                 throw redacted;
             }
-        }, { maxRetries, retryDelay });
+        }, {
+            maxRetries: options?.maxRetries ?? 3,
+            baseDelayMs: options?.retryDelay ?? 1000,
+            shouldRetry: isRetryableNetworkError,
+        });
     }
     /**
      * Load file from filesystem path

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

@@ -115,14 +115,6 @@ export declare function createDeepSeekConfig(): ProviderConfigOptions;
  * Creates NVIDIA NIM provider configuration
  */
 export declare function createNvidiaNimConfig(): ProviderConfigOptions;
-/**
- * Creates LM Studio provider configuration (local server)
- */
-export declare function createLmStudioConfig(): ProviderConfigOptions;
-/**
- * Creates llama.cpp provider configuration (local server)
- */
-export declare function createLlamaCppConfig(): ProviderConfigOptions;
 /**
  * Creates xAI Grok provider configuration.
  */

package/dist/lib/utils/providerConfig.js

@@ -411,43 +411,6 @@ export function createNvidiaNimConfig() {
         ],
     };
 }
-/**
- * Creates LM Studio provider configuration (local server)
- */
-export function createLmStudioConfig() {
-    return {
-        providerName: "LM Studio",
-        envVarName: "LM_STUDIO_BASE_URL",
-        setupUrl: "https://lmstudio.ai/",
-        description: "LM Studio server URL",
-        instructions: [
-            "1. Install LM Studio: https://lmstudio.ai/",
-            "2. Open LM Studio and download a model (e.g. Llama 3.2 3B Instruct)",
-            '3. Click "Local Server" → Start Server',
-            "4. Default URL is http://localhost:1234/v1 (override via LM_STUDIO_BASE_URL)",
-        ],
-        // Base URL is optional — defaults to http://localhost:1234/v1 if unset.
-        optional: true,
-    };
-}
-/**
- * Creates llama.cpp provider configuration (local server)
- */
-export function createLlamaCppConfig() {
-    return {
-        providerName: "llama.cpp",
-        envVarName: "LLAMACPP_BASE_URL",
-        setupUrl: "https://github.com/ggerganov/llama.cpp",
-        description: "llama.cpp server URL",
-        instructions: [
-            "1. Build llama.cpp: https://github.com/ggerganov/llama.cpp#build",
-            "2. Run: ./llama-server -m model.gguf --port 8080",
-            "3. Default URL is http://localhost:8080/v1 (override via LLAMACPP_BASE_URL)",
-        ],
-        // Base URL is optional — defaults to http://localhost:8080/v1 if unset.
-        optional: true,
-    };
-}
 /**
  * Creates xAI Grok provider configuration.
  */

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

@@ -36,21 +36,56 @@ export declare class ProviderHealthChecker {
      */
     private static checkModelAvailability;
     /**
-     * Get required environment variables for a provider
-     */
-    private static getRequiredEnvironmentVariables;
+     * Providers whose credential model can't be reduced to "every one of
+     * these exact env vars must be literally set" — the check in
+     * checkEnvironmentConfiguration() below ANDs every entry in the
+     * returned list together, which can't express Vertex's file-OR-
+     * individual-creds-OR-service-account auth, Bedrock's AWS SDK default
+     * provider chain (profile / IAM role, no env vars at all), or
+     * LiteLLM's documented zero-config local proxy. Their real requirement
+     * is validated by checkProviderSpecificConfig()'s dedicated per-provider
+     * checks instead — matches the original hand-written switch's
+     * deliberate `return []` for exactly these three. Naively deriving
+     * [apiKey, ...extraRequired] from the descriptor here (as for the other
+     * 27 providers) would make checkEnvironmentConfiguration() push a false
+     * "missing environment variables" issue — and therefore isHealthy=false
+     * — for legitimate fallback-based Vertex auth, AWS_PROFILE/IAM-role
+     * Bedrock auth, and unauthenticated local LiteLLM proxies. See
+     * hasProviderEnvVars() in providerUtils.ts for the equivalent OR-aware
+     * check used for auto-select gating.
+     */
+    private static readonly ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG;
     /**
-     * Get API key environment variable for a provider
+     * Get required environment variables for a provider
      */
-    private static getApiKeyEnvironmentVariable;
+    static getRequiredEnvironmentVariables(providerName: string): string[];
+    /**
+     * Get API key environment variable for a provider.
+     *
+     * Dead code at its sole call site today (checkApiKeyValidity() early-
+     * returns for VERTEX/OLLAMA/BEDROCK/LITELLM before reaching this), but
+     * now `static` (public) so a future direct caller is plausible — hence
+     * the two intentional diffs from the original hand-written switch are
+     * documented here rather than left silent:
+     *   - vertex: old switch returned "GOOGLE_APPLICATION_CREDENTIALS"
+     *     (one of several valid auth vars); the descriptor's `envVars.apiKey`
+     *     is "GOOGLE_CLOUD_PROJECT_ID" instead — the actual identity var for
+     *     the provider, not one specific credential-supply mechanism.
+     *   - ollama: old switch returned "OLLAMA_BASE_URL"; the descriptor has
+     *     no `envVars.apiKey` for ollama (it's a local, unauthenticated
+     *     runtime), so this now returns "".
+     * Both are kept deliberately (semantically truer identity vars) rather
+     * than reproduced byte-for-byte from the old switch.
+     */
+    static getApiKeyEnvironmentVariable(providerName: string): string;
     /**
      * Validate API key format for a provider
      */
-    private static validateApiKeyFormat;
+    static validateApiKeyFormat(providerName: string, apiKey: string): boolean;
     /**
      * Get health check endpoint for connectivity testing
      */
-    private static getProviderHealthEndpoint;
+    static getProviderHealthEndpoint(providerName: string): string | null;
     /**
      * Provider-specific configuration checks
      */