@juspay/neurolink 10.12.9 → 11.1.0

package/dist/factories/providerFactory.js

@@ -1,6 +1,26 @@
 import { logger } from "../utils/logger.js";
+import { PROVIDER_DESCRIPTORS, PROVIDER_DESCRIPTORS_BY_NAME, PROVIDER_ALIAS_INDEX, } from "./providerDescriptors.js";
 // Pure factory pattern with no hardcoded imports
 // All providers loaded dynamically via registry to avoid circular dependencies
+/**
+ * Resolve a registered provider name (or alias) to its NeurolinkCredentials
+ * key. Backed by ProviderFactory.getDescriptor() — PROVIDER_DESCRIPTORS is
+ * the single source of truth for provider identity — instead of a
+ * hand-maintained map, so this can no longer drift out of sync with the
+ * descriptors, and it correctly resolves aliases (e.g. "hf") through
+ * PROVIDER_ALIAS_INDEX, not just canonical names. Falls back to the
+ * lowercased input when no descriptor is found, matching the retired
+ * map's behavior for unknown provider names.
+ *
+ * Referencing ProviderFactory here (defined further down this file) is
+ * safe: this function's body only runs when called, by which point the
+ * module has finished evaluating and ProviderFactory is fully defined —
+ * there is no temporal-dead-zone hazard from the declaration order.
+ */
+export function resolveCredentialKey(providerName) {
+    const normalized = providerName.toLowerCase();
+    return (ProviderFactory.getDescriptor(normalized)?.credentialsKey ?? normalized);
+}
 /**
  * True Factory Pattern implementation for AI Providers
  * Uses registration-based approach to eliminate switch statements
@@ -13,11 +33,12 @@ export class ProviderFactory {
      * Register a provider with the factory
      */
     static registerProvider(name, constructor, defaultModel, // Optional - provider can read from env
-    aliases = []) {
+    aliases = [], descriptor) {
         const registration = {
             constructor,
             defaultModel,
             aliases,
+            descriptor,
         };
         // Register main name
         ProviderFactory.providers.set(name.toLowerCase(), registration);
@@ -58,21 +79,7 @@ export class ProviderFactory {
             // Fallback to registry default if no env var
             model = model || registration.defaultModel;
         }
-        // Map registered provider names to NeurolinkCredentials keys.
-        // Most names match (openai, anthropic, vertex, bedrock, etc.)
-        // but every kebab-case provider whose canonical credentials key is
-        // camelCase MUST be mapped here — otherwise per-call credential
-        // overrides silently get dropped (the factory looks up
-        // credentials["lm-studio"] which is undefined while the user wrote
-        // credentials.lmStudio).
-        const credentialKeyMap = {
-            "google-ai": "googleAiStudio",
-            "openai-compatible": "openaiCompatible",
-            huggingface: "huggingFace",
-            "lm-studio": "lmStudio",
-            "nvidia-nim": "nvidiaNim",
-        };
-        const credKey = credentialKeyMap[normalizedName] ?? normalizedName;
+        const credKey = resolveCredentialKey(normalizedName);
         // Extract provider-scoped credential slice (e.g. credentials.openai for OpenAI)
         const scopedCredentials = credentials
             ? credentials[credKey]
@@ -81,30 +88,8 @@ export class ProviderFactory {
             if (typeof registration.constructor !== "function") {
                 throw new Error(`Invalid constructor for provider ${providerName}: not a function`);
             }
-            let result;
-            try {
-                const factoryResult = registration.constructor(model, resolvedProviderName, sdk, region, scopedCredentials);
-                // Handle both sync and async results
-                result =
-                    factoryResult instanceof Promise
-                        ? await factoryResult
-                        : factoryResult;
-            }
-            catch (factoryError) {
-                if (registration.constructor.prototype &&
-                    registration.constructor.prototype.constructor ===
-                        registration.constructor) {
-                    try {
-                        result = new registration.constructor(model, resolvedProviderName, sdk, region, scopedCredentials);
-                    }
-                    catch (constructorError) {
-                        throw new Error(`Both factory function and constructor failed. Factory error: ${factoryError}. Constructor error: ${constructorError}`, { cause: constructorError });
-                    }
-                }
-                else {
-                    throw factoryError;
-                }
-            }
+            const factoryResult = registration.constructor(model, resolvedProviderName, sdk, region, scopedCredentials);
+            const result = factoryResult instanceof Promise ? await factoryResult : factoryResult;
             return result;
         }
         catch (error) {
@@ -130,16 +115,42 @@ export class ProviderFactory {
     static getProviderInfo(providerName) {
         return ProviderFactory.providers.get(providerName.toLowerCase());
     }
+    /**
+     * Look up a provider's static descriptor. Checks the built-in
+     * PROVIDER_DESCRIPTORS first (works even before registerAllProviders()
+     * has run, and resolves aliases via PROVIDER_ALIAS_INDEX), then falls
+     * back to whatever descriptor a live custom registration attached via
+     * registerProvider()'s 5th parameter.
+     */
+    static getDescriptor(name) {
+        const normalized = name.toLowerCase();
+        const canonical = PROVIDER_ALIAS_INDEX.get(normalized);
+        if (canonical) {
+            const builtIn = PROVIDER_DESCRIPTORS_BY_NAME.get(canonical);
+            if (builtIn) {
+                return builtIn;
+            }
+        }
+        return ProviderFactory.providers.get(normalized)?.descriptor;
+    }
+    /** All built-in provider descriptors (does not include custom-registered providers that lack a descriptor). */
+    static getAllDescriptors() {
+        return PROVIDER_DESCRIPTORS;
+    }
     /**
      * Normalize provider names using aliases (PHASE 1: Factory Pattern)
      */
     static normalizeProviderName(providerName) {
         const normalized = providerName.toLowerCase();
-        // Check direct registration
         if (ProviderFactory.providers.has(normalized)) {
             return normalized;
         }
-        // Check aliases from all registrations
+        const canonical = PROVIDER_ALIAS_INDEX.get(normalized);
+        if (canonical && ProviderFactory.providers.has(canonical)) {
+            return canonical;
+        }
+        // Fallback for providers registered without a built-in descriptor
+        // (e.g. TTS/STT/media handlers registered outside PROVIDER_DESCRIPTORS).
         for (const [name, registration] of ProviderFactory.providers.entries()) {
             if (registration.aliases?.includes(normalized)) {
                 return name;

package/dist/factories/providerRegistry.js

@@ -1,6 +1,7 @@
 import { ProviderFactory } from "./providerFactory.js";
 import { logger } from "../utils/logger.js";
 import { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, MistralModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, XaiModels, GroqModels, CohereModels, TogetherAIModels, FireworksModels, PerplexityModels, CloudflareModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
+import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -67,26 +68,26 @@ export class ProviderRegistry {
                 const googleAiCreds = credentials;
                 const { GoogleAIStudioProvider } = await import("../providers/googleAiStudio/index.js");
                 return new GoogleAIStudioProvider(modelName, sdk, googleAiCreds);
-            }, GoogleAIModels.GEMINI_2_5_FLASH, ["googleAiStudio", "google", "gemini", "google-ai", "google-ai-studio"]);
+            }, GoogleAIModels.GEMINI_2_5_FLASH, ["googleAiStudio", "google", "gemini", "google-ai", "google-ai-studio"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.GOOGLE_AI));
             // Register OpenAI provider
             ProviderFactory.registerProvider(AIProviderName.OPENAI, async (modelName, _providerName, sdk, _region, credentials) => {
                 const openaiCreds = credentials;
                 const { OpenAIProvider } = await import("../providers/openAI/index.js");
                 return new OpenAIProvider(modelName, sdk, undefined, openaiCreds);
-            }, OpenAIModels.GPT_4O_MINI, ["gpt", "chatgpt"]);
+            }, OpenAIModels.GPT_4O_MINI, ["gpt", "chatgpt"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.OPENAI));
             // Register Anthropic provider
             ProviderFactory.registerProvider(AIProviderName.ANTHROPIC, async (modelName, _providerName, sdk, _region, credentials) => {
                 const anthropicCreds = credentials;
                 const { AnthropicProvider } = await import("../providers/anthropic/index.js");
                 return new AnthropicProvider(modelName, sdk, undefined, anthropicCreds);
-            }, AnthropicModels.CLAUDE_SONNET_4_6, ["claude", "anthropic"]);
+            }, AnthropicModels.CLAUDE_SONNET_4_6, ["claude", "anthropic"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.ANTHROPIC));
             // Register Amazon Bedrock provider
             ProviderFactory.registerProvider(AIProviderName.BEDROCK, async (modelName, _providerName, sdk, region, credentials) => {
                 const bedrockCreds = credentials;
                 const { AmazonBedrockProvider } = await import("../providers/amazonBedrock/index.js");
                 return new AmazonBedrockProvider(modelName, sdk, region, bedrockCreds);
             }, undefined, // Let provider read BEDROCK_MODEL from .env
-            ["bedrock", "aws"]);
+            ["bedrock", "aws"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.BEDROCK));
             // Register Azure OpenAI provider
             ProviderFactory.registerProvider(AIProviderName.AZURE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const azureCreds = credentials;
@@ -96,45 +97,45 @@ export class ProviderRegistry {
                 process.env.AZURE_OPENAI_MODEL ||
                 process.env.AZURE_OPENAI_DEPLOYMENT ||
                 process.env.AZURE_OPENAI_DEPLOYMENT_ID ||
-                "gpt-4o-mini", ["azure", "azureOpenai"]);
+                "gpt-4o-mini", ["azure", "azureOpenai"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.AZURE));
             // Register Google Vertex AI provider
             ProviderFactory.registerProvider(AIProviderName.VERTEX, async (modelName, providerName, sdk, region, credentials) => {
                 const vertexCreds = credentials;
                 const { GoogleVertexProvider } = await import("../providers/googleVertex/index.js");
                 return new GoogleVertexProvider(modelName, providerName, sdk, region, vertexCreds);
-            }, VertexModels.CLAUDE_4_6_SONNET, ["vertex", "googleVertex"]);
+            }, VertexModels.CLAUDE_4_6_SONNET, ["vertex", "googleVertex"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.VERTEX));
             // Register Hugging Face provider (Unified Router implementation)
-            ProviderFactory.registerProvider(AIProviderName.HUGGINGFACE, async (modelName, _providerName, _sdk, _region, credentials) => {
+            ProviderFactory.registerProvider(AIProviderName.HUGGINGFACE, async (modelName, _providerName, sdk, region, credentials) => {
                 const hfCreds = credentials;
                 const { HuggingFaceProvider } = await import("../providers/huggingFace/index.js");
-                return new HuggingFaceProvider(modelName, undefined, hfCreds);
+                return new HuggingFaceProvider(modelName, sdk, region, hfCreds);
             }, process.env.HUGGINGFACE_MODEL ||
-                HuggingFaceModels.QWEN_2_5_72B_INSTRUCT, ["huggingface", "hf"]);
+                HuggingFaceModels.QWEN_2_5_72B_INSTRUCT, ["huggingface", "hf"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.HUGGINGFACE));
             // Register Mistral AI provider
             ProviderFactory.registerProvider(AIProviderName.MISTRAL, async (modelName, _providerName, sdk, _region, credentials) => {
                 const mistralCreds = credentials;
                 const { MistralProvider } = await import("../providers/mistral.js");
                 return new MistralProvider(modelName, sdk, undefined, mistralCreds);
-            }, MistralModels.MISTRAL_LARGE_LATEST, ["mistral"]);
+            }, MistralModels.MISTRAL_LARGE_LATEST, ["mistral"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.MISTRAL));
             // Register Ollama provider
             ProviderFactory.registerProvider(AIProviderName.OLLAMA, async (modelName, _providerName, sdk, _region, credentials) => {
                 const ollamaCreds = credentials;
                 const { OllamaProvider } = await import("../providers/ollama/index.js");
                 return new OllamaProvider(modelName, sdk, undefined, ollamaCreds);
-            }, process.env.OLLAMA_MODEL || OllamaModels.LLAMA3_2_LATEST, ["ollama", "local"]);
+            }, process.env.OLLAMA_MODEL || OllamaModels.LLAMA3_2_LATEST, ["ollama", "local"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.OLLAMA));
             // Register LiteLLM provider
             ProviderFactory.registerProvider(AIProviderName.LITELLM, async (modelName, _providerName, sdk, _region, credentials) => {
                 const litellmCreds = credentials;
                 const { LiteLLMProvider } = await import("../providers/litellm/index.js");
                 return new LiteLLMProvider(modelName, sdk, undefined, litellmCreds);
-            }, process.env.LITELLM_MODEL || LiteLLMModels.OPENAI_GPT_4O_MINI, ["litellm"]);
+            }, process.env.LITELLM_MODEL || LiteLLMModels.OPENAI_GPT_4O_MINI, ["litellm"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.LITELLM));
             // Register OpenAI Compatible provider
             ProviderFactory.registerProvider(AIProviderName.OPENAI_COMPATIBLE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const openaiCompatCreds = credentials;
                 const { OpenAICompatibleProvider } = await import("../providers/openaiCompatible/index.js");
                 return new OpenAICompatibleProvider(modelName, sdk, undefined, openaiCompatCreds);
             }, process.env.OPENAI_COMPATIBLE_MODEL || undefined, // Enable auto-discovery when no model specified
-            ["openai-compatible", "vllm", "compatible"]);
+            ["openai-compatible", "vllm", "compatible"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.OPENAI_COMPATIBLE));
             // Register OpenRouter provider (300+ models from 60+ providers)
             ProviderFactory.registerProvider(AIProviderName.OPENROUTER, async (modelName, _providerName, sdk, _region, credentials) => {
                 const openrouterCreds = credentials;
@@ -146,117 +147,117 @@ export class ProviderRegistry {
             // for the rationale. Keep the three defaults aligned at the new
             // model (claude-sonnet-4.5) so the registry doesn't override the
             // provider's getDefault.
-            process.env.OPENROUTER_MODEL || OpenRouterModels.CLAUDE_SONNET_4_5, ["openrouter", "or"]);
+            process.env.OPENROUTER_MODEL || OpenRouterModels.CLAUDE_SONNET_4_5, ["openrouter", "or"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.OPENROUTER));
             // Register Amazon SageMaker provider
             ProviderFactory.registerProvider(AIProviderName.SAGEMAKER, async (modelName, _providerName, _sdk, region, credentials) => {
                 const sagemakerCreds = credentials;
                 const { AmazonSageMakerProvider } = await import("../providers/amazonSagemaker.js");
                 return new AmazonSageMakerProvider(modelName, undefined, region, undefined, sagemakerCreds);
-            }, process.env.SAGEMAKER_MODEL || "sagemaker-model", ["sagemaker", "aws-sagemaker"]);
+            }, process.env.SAGEMAKER_MODEL || "sagemaker-model", ["sagemaker", "aws-sagemaker"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.SAGEMAKER));
             // Register DeepSeek provider
             ProviderFactory.registerProvider(AIProviderName.DEEPSEEK, async (modelName, _providerName, sdk, _region, credentials) => {
                 const deepseekCreds = credentials;
                 const { DeepSeekProvider } = await import("../providers/deepseek.js");
                 return new DeepSeekProvider(modelName, sdk, undefined, deepseekCreds);
-            }, process.env.DEEPSEEK_MODEL || DeepSeekModels.DEEPSEEK_CHAT, ["deepseek", "ds"]);
+            }, process.env.DEEPSEEK_MODEL || DeepSeekModels.DEEPSEEK_CHAT, ["deepseek", "ds"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.DEEPSEEK));
             // Register NVIDIA NIM provider
             ProviderFactory.registerProvider(AIProviderName.NVIDIA_NIM, async (modelName, _providerName, sdk, _region, credentials) => {
                 const nimCreds = credentials;
                 const { NvidiaNimProvider } = await import("../providers/nvidiaNim/index.js");
                 return new NvidiaNimProvider(modelName, sdk, undefined, nimCreds);
-            }, process.env.NVIDIA_NIM_MODEL || NvidiaNimModels.LLAMA_3_3_70B_INSTRUCT, ["nvidia", "nim", "nvidia-nim"]);
+            }, process.env.NVIDIA_NIM_MODEL || NvidiaNimModels.LLAMA_3_3_70B_INSTRUCT, ["nvidia", "nim", "nvidia-nim"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.NVIDIA_NIM));
             // Register LM Studio provider (local)
             ProviderFactory.registerProvider(AIProviderName.LM_STUDIO, async (modelName, _providerName, sdk, _region, credentials) => {
                 const lmStudioCreds = credentials;
                 const { LMStudioProvider } = await import("../providers/lmStudio.js");
                 return new LMStudioProvider(modelName, sdk, undefined, lmStudioCreds);
-            }, process.env.LM_STUDIO_MODEL || undefined, ["lmstudio", "lm-studio", "lms"]);
+            }, process.env.LM_STUDIO_MODEL || undefined, ["lmstudio", "lm-studio", "lms"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.LM_STUDIO));
             // Register llama.cpp provider (local)
             ProviderFactory.registerProvider(AIProviderName.LLAMACPP, async (modelName, _providerName, sdk, _region, credentials) => {
                 const llamaCppCreds = credentials;
                 const { LlamaCppProvider } = await import("../providers/llamaCpp.js");
                 return new LlamaCppProvider(modelName, sdk, undefined, llamaCppCreds);
-            }, process.env.LLAMACPP_MODEL || undefined, ["llamacpp", "llama.cpp", "llama-cpp"]);
+            }, process.env.LLAMACPP_MODEL || undefined, ["llamacpp", "llama.cpp", "llama-cpp"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.LLAMACPP));
             // Register xAI Grok provider
             ProviderFactory.registerProvider(AIProviderName.XAI, async (modelName, _providerName, sdk, _region, credentials) => {
                 const xaiCreds = credentials;
                 const { XaiProvider } = await import("../providers/xai.js");
                 return new XaiProvider(modelName, sdk, undefined, xaiCreds);
-            }, process.env.XAI_MODEL || XaiModels.GROK_3, ["xai", "grok"]);
+            }, process.env.XAI_MODEL || XaiModels.GROK_3, ["xai", "grok"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.XAI));
             // Register Groq provider
             ProviderFactory.registerProvider(AIProviderName.GROQ, async (modelName, _providerName, sdk, _region, credentials) => {
                 const groqCreds = credentials;
                 const { GroqProvider } = await import("../providers/groq.js");
                 return new GroqProvider(modelName, sdk, undefined, groqCreds);
-            }, process.env.GROQ_MODEL || GroqModels.LLAMA_3_3_70B_VERSATILE, ["groq"]);
+            }, process.env.GROQ_MODEL || GroqModels.LLAMA_3_3_70B_VERSATILE, ["groq"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.GROQ));
             // Register Cohere provider
             ProviderFactory.registerProvider(AIProviderName.COHERE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const cohereCreds = credentials;
                 const { CohereProvider } = await import("../providers/cohere.js");
                 return new CohereProvider(modelName, sdk, undefined, cohereCreds);
-            }, process.env.COHERE_MODEL || CohereModels.COMMAND_R_PLUS, ["cohere"]);
+            }, process.env.COHERE_MODEL || CohereModels.COMMAND_R_PLUS, ["cohere"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.COHERE));
             // Register Together AI provider
             ProviderFactory.registerProvider(AIProviderName.TOGETHER_AI, async (modelName, _providerName, sdk, _region, credentials) => {
                 const togetherCreds = credentials;
                 const { TogetherAIProvider } = await import("../providers/togetherAi.js");
                 return new TogetherAIProvider(modelName, sdk, undefined, togetherCreds);
             }, process.env.TOGETHER_MODEL ||
-                TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO, ["together-ai", "together"]);
+                TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO, ["together-ai", "together"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.TOGETHER_AI));
             // Register Fireworks AI provider
             ProviderFactory.registerProvider(AIProviderName.FIREWORKS, async (modelName, _providerName, sdk, _region, credentials) => {
                 const fireworksCreds = credentials;
                 const { FireworksProvider } = await import("../providers/fireworks.js");
                 return new FireworksProvider(modelName, sdk, undefined, fireworksCreds);
-            }, process.env.FIREWORKS_MODEL || FireworksModels.DEEPSEEK_V4_PRO, ["fireworks"]);
+            }, process.env.FIREWORKS_MODEL || FireworksModels.DEEPSEEK_V4_PRO, ["fireworks"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.FIREWORKS));
             // Register Perplexity provider
             ProviderFactory.registerProvider(AIProviderName.PERPLEXITY, async (modelName, _providerName, sdk, _region, credentials) => {
                 const perplexityCreds = credentials;
                 const { PerplexityProvider } = await import("../providers/perplexity.js");
                 return new PerplexityProvider(modelName, sdk, undefined, perplexityCreds);
-            }, process.env.PERPLEXITY_MODEL || PerplexityModels.SONAR, ["perplexity", "pplx"]);
+            }, process.env.PERPLEXITY_MODEL || PerplexityModels.SONAR, ["perplexity", "pplx"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.PERPLEXITY));
             // Register Cloudflare Workers AI provider
             ProviderFactory.registerProvider(AIProviderName.CLOUDFLARE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const cloudflareCreds = credentials;
                 const { CloudflareProvider } = await import("../providers/cloudflare.js");
                 return new CloudflareProvider(modelName, sdk, undefined, cloudflareCreds);
-            }, process.env.CLOUDFLARE_MODEL || CloudflareModels.LLAMA_3_3_70B_FAST, ["cloudflare", "workers-ai", "cf-ai"]);
+            }, process.env.CLOUDFLARE_MODEL || CloudflareModels.LLAMA_3_3_70B_FAST, ["cloudflare", "workers-ai", "cf-ai"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.CLOUDFLARE));
             // Register Voyage AI embeddings provider
             ProviderFactory.registerProvider(AIProviderName.VOYAGE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const voyageCreds = credentials;
                 const { VoyageProvider } = await import("../providers/voyage.js");
                 return new VoyageProvider(modelName, sdk, undefined, voyageCreds);
-            }, process.env.VOYAGE_MODEL || VoyageModels.VOYAGE_3_5, ["voyage", "voyage-ai"]);
+            }, process.env.VOYAGE_MODEL || VoyageModels.VOYAGE_3_5, ["voyage", "voyage-ai"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.VOYAGE));
             // Register Jina AI embeddings + reranking provider
             ProviderFactory.registerProvider(AIProviderName.JINA, async (modelName, _providerName, sdk, _region, credentials) => {
                 const jinaCreds = credentials;
                 const { JinaProvider } = await import("../providers/jina.js");
                 return new JinaProvider(modelName, sdk, undefined, jinaCreds);
-            }, process.env.JINA_MODEL || JinaModels.JINA_EMBEDDINGS_V3, ["jina", "jina-ai"]);
+            }, process.env.JINA_MODEL || JinaModels.JINA_EMBEDDINGS_V3, ["jina", "jina-ai"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.JINA));
             // Register Stability AI image-gen provider
             ProviderFactory.registerProvider(AIProviderName.STABILITY, async (modelName, _providerName, sdk, _region, credentials) => {
                 const stabilityCreds = credentials;
                 const { StabilityProvider } = await import("../providers/stability.js");
                 return new StabilityProvider(modelName, sdk, undefined, stabilityCreds);
-            }, process.env.STABILITY_MODEL || StabilityModels.STABLE_IMAGE_ULTRA, ["stability", "stability-ai", "sd"]);
+            }, process.env.STABILITY_MODEL || StabilityModels.STABLE_IMAGE_ULTRA, ["stability", "stability-ai", "sd"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.STABILITY));
             // Register Ideogram image-gen provider
             ProviderFactory.registerProvider(AIProviderName.IDEOGRAM, async (modelName, _providerName, sdk, _region, credentials) => {
                 const ideogramCreds = credentials;
                 const { IdeogramProvider } = await import("../providers/ideogram.js");
                 return new IdeogramProvider(modelName, sdk, undefined, ideogramCreds);
-            }, process.env.IDEOGRAM_MODEL || IdeogramModels.IDEOGRAM_V3, ["ideogram"]);
+            }, process.env.IDEOGRAM_MODEL || IdeogramModels.IDEOGRAM_V3, ["ideogram"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.IDEOGRAM));
             // Register Replicate LLM provider (multi-modal — also serves video /
             // avatar / music handlers via dedicated processors registered below)
             ProviderFactory.registerProvider(AIProviderName.REPLICATE, async (modelName, _providerName, sdk, _region, credentials) => {
                 const replicateCreds = credentials;
                 const { ReplicateProvider } = await import("../providers/replicate.js");
                 return new ReplicateProvider(modelName, sdk, undefined, replicateCreds);
-            }, process.env.REPLICATE_MODEL || ReplicateModels.LLAMA_3_70B_INSTRUCT, ["replicate"]);
+            }, process.env.REPLICATE_MODEL || ReplicateModels.LLAMA_3_70B_INSTRUCT, ["replicate"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.REPLICATE));
             // Register Recraft image-gen provider
             ProviderFactory.registerProvider(AIProviderName.RECRAFT, async (modelName, _providerName, sdk, _region, credentials) => {
                 const recraftCreds = credentials;
                 const { RecraftProvider } = await import("../providers/recraft.js");
                 return new RecraftProvider(modelName, sdk, undefined, recraftCreds);
-            }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"]);
+            }, process.env.RECRAFT_MODEL || RecraftModels.RECRAFT_V3, ["recraft"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.RECRAFT));
             logger.debug("All AI providers registered successfully");
             // ===== TTS HANDLER REGISTRATION =====
             try {

package/dist/index.d.ts

@@ -33,6 +33,8 @@
  */
 import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
+export { ProviderFactory } from "./factories/providerFactory.js";
+export { PROVIDER_DESCRIPTORS, PROVIDER_DESCRIPTORS_BY_NAME, PROVIDER_ALIAS_INDEX, } from "./factories/providerDescriptors.js";
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, withRetry, TypedEventEmitter, } from "./core/infrastructure/index.js";
 export { NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
@@ -396,7 +398,14 @@ export { classifyProviderError, ModelPool, createDefaultRequestRouter, Classifie
  * await server.start();
  * ```
  */
-export { AgentExecuteRequestSchema, AlreadyRunningError, AuthenticationError, AuthorizationError, BaseServerAdapter, ConfigurationError, createAgentRoutes, createAgentWebSocketHandler, createAllRoutes, createAuthMiddleware, createCacheInvalidator, createCacheMiddleware, createCompressionMiddleware, createDataStreamResponse, createDataStreamWriter, createErrorHandlingMiddleware, createErrorResponse, createFieldValidator, createHealthRoutes, createLoggingMiddleware, createMCPRoutes, createMemoryRoutes, createNDJSONHeaders, createOpenAPIGenerator, createRateLimitMiddleware, createRequestIdMiddleware, createRequestValidationMiddleware, createRoleMiddleware, createSecurityHeadersMiddleware, createServer, createSlidingWindowRateLimitMiddleware, createSSEHeaders, createTimingMiddleware, createToolRoutes, ErrorCategory, ErrorRecoveryStrategies, ErrorSeverity, ExpressServerAdapter, FastifyServerAdapter, generateOpenAPIFromConfig, generateOpenAPISpec, HandlerError, HonoServerAdapter, InMemoryCacheStore, InMemoryRateLimitStore, InvalidAuthenticationError, KoaServerAdapter, MissingDependencyError, NotRunningError, pipeAsyncIterableToDataStream, RateLimitError, RouteConflictError, RouteNotFoundError, registerAllRoutes, ServerAdapterError, ServerAdapterErrorCode, ServerAdapterFactory, ServerNameParamSchema, ServerRateLimitError, ServerStartError, ServerStopError, ServerValidationError, SessionIdParamSchema, StreamAbortedError, StreamingError, TimeoutError, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, ValidationError, validateParams, validateQuery, validateRequest, WebSocketConnectionError, WebSocketConnectionManager, WebSocketError, WebSocketMessageRouter, wrapError, } from "./server/index.js";
+export { AgentExecuteRequestSchema, AlreadyRunningError, BaseServerAdapter, ConfigurationError, createAgentRoutes, createAgentWebSocketHandler, createAllRoutes, createAuthMiddleware, createCacheInvalidator, createCacheMiddleware, createCompressionMiddleware, createDataStreamResponse, createDataStreamWriter, createErrorHandlingMiddleware, createErrorResponse, createFieldValidator, createHealthRoutes, createLoggingMiddleware, createMCPRoutes, createMemoryRoutes, createNDJSONHeaders, createOpenAPIGenerator, createRateLimitMiddleware, createRequestIdMiddleware, createRequestValidationMiddleware, createRoleMiddleware, createSecurityHeadersMiddleware, createServer, createSlidingWindowRateLimitMiddleware, createSSEHeaders, createTimingMiddleware, createToolRoutes, ErrorCategory, ErrorRecoveryStrategies, ErrorSeverity, ExpressServerAdapter, FastifyServerAdapter, generateOpenAPIFromConfig, generateOpenAPISpec, HandlerError, HonoServerAdapter, InMemoryCacheStore, InMemoryRateLimitStore, InvalidAuthenticationError, KoaServerAdapter, MissingDependencyError, NotRunningError, pipeAsyncIterableToDataStream, RouteConflictError, RouteNotFoundError, registerAllRoutes, ServerAdapterError, ServerAdapterErrorCode, ServerAdapterFactory, ServerAuthenticationError, ServerAuthorizationError, ServerNameParamSchema, ServerRateLimitError, ServerStartError, ServerStopError, ServerTimeoutError, ServerValidationError, SessionIdParamSchema, StreamAbortedError, StreamingError, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, ValidationError, validateParams, validateQuery, validateRequest, WebSocketConnectionError, WebSocketConnectionManager, WebSocketError, WebSocketMessageRouter, wrapError, } from "./server/index.js";
+/**
+ * @deprecated Use `ServerTimeoutError` instead — renamed to end the naming
+ * collision with the canonical `utils/timeout.ts` `TimeoutError`. Kept as an
+ * alias so existing callers importing `TimeoutError` from `@juspay/neurolink`
+ * are not broken.
+ */
+export { ServerTimeoutError as TimeoutError } from "./server/index.js";
 /**
  * RAG (Retrieval-Augmented Generation) Document Processing
  *

package/dist/index.js

@@ -34,6 +34,9 @@
 // Core exports
 import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
+// Provider descriptor exports (single source of truth for provider identity)
+export { ProviderFactory } from "./factories/providerFactory.js";
+export { PROVIDER_DESCRIPTORS, PROVIDER_DESCRIPTORS_BY_NAME, PROVIDER_ALIAS_INDEX, } from "./factories/providerDescriptors.js";
 // Config Manager export
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 // Core Infrastructure exports (factory + registry patterns)
@@ -613,7 +616,7 @@ export { classifyProviderError, ModelPool, createDefaultRequestRouter, Classifie
  */
 export { 
 // Validation
-AgentExecuteRequestSchema, AlreadyRunningError, AuthenticationError, AuthorizationError, 
+AgentExecuteRequestSchema, AlreadyRunningError, 
 // Framework Adapters
 BaseServerAdapter, ConfigurationError, 
 // Routes
@@ -627,11 +630,18 @@ createServer, createSlidingWindowRateLimitMiddleware, createSSEHeaders, createTi
 // Error Constants
 ErrorCategory, ErrorRecoveryStrategies, ErrorSeverity, ExpressServerAdapter, FastifyServerAdapter, generateOpenAPIFromConfig, generateOpenAPISpec, HandlerError, HonoServerAdapter, InMemoryCacheStore, InMemoryRateLimitStore, InvalidAuthenticationError, KoaServerAdapter, MissingDependencyError, NotRunningError, 
 // OpenAPI
-pipeAsyncIterableToDataStream, RateLimitError, RouteConflictError, RouteNotFoundError, registerAllRoutes, 
+pipeAsyncIterableToDataStream, RouteConflictError, RouteNotFoundError, registerAllRoutes, 
 // Errors
-ServerAdapterError, ServerAdapterErrorCode, ServerAdapterFactory, ServerNameParamSchema, ServerRateLimitError, ServerStartError, ServerStopError, ServerValidationError, SessionIdParamSchema, StreamAbortedError, StreamingError, TimeoutError, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, ValidationError, validateParams, validateQuery, validateRequest, WebSocketConnectionError, 
+ServerAdapterError, ServerAdapterErrorCode, ServerAdapterFactory, ServerAuthenticationError, ServerAuthorizationError, ServerNameParamSchema, ServerRateLimitError, ServerStartError, ServerStopError, ServerTimeoutError, ServerValidationError, SessionIdParamSchema, StreamAbortedError, StreamingError, ToolArgumentsSchema, ToolExecuteRequestSchema, ToolNameParamSchema, ToolSearchQuerySchema, ValidationError, validateParams, validateQuery, validateRequest, WebSocketConnectionError, 
 // WebSocket
 WebSocketConnectionManager, WebSocketError, WebSocketMessageRouter, wrapError, } from "./server/index.js";
+/**
+ * @deprecated Use `ServerTimeoutError` instead — renamed to end the naming
+ * collision with the canonical `utils/timeout.ts` `TimeoutError`. Kept as an
+ * alias so existing callers importing `TimeoutError` from `@juspay/neurolink`
+ * are not broken.
+ */
+export { ServerTimeoutError as TimeoutError } from "./server/index.js";
 // ============================================================================
 // RAG DOCUMENT PROCESSING - Retrieval-Augmented Generation
 // ============================================================================

package/dist/lib/core/baseProvider.js

@@ -1,6 +1,6 @@
 import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
 import { directAgentTools } from "../agent/directTools.js";
-import { IMAGE_GENERATION_MODELS } from "../core/constants.js";
+import { isImageGenerationModel } from "../core/constants.js";
 import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
@@ -195,7 +195,7 @@ export class BaseProvider {
         // Skip this path when the caller explicitly requests non-image output (e.g.
         // JSON analysis) so dual-mode models like gemini-3.1-flash-image-preview
         // can still perform text/structured generation.
-        const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
+        const isImageModel = isImageGenerationModel(this.modelName);
         const requestsNonImageOutput = options.output?.format === "json" ||
             options.output?.format === "structured" ||
             options.output?.format === "text";
@@ -966,7 +966,7 @@ export class BaseProvider {
             if (options.output?.mode === "video") {
                 return await this.handleVideoGeneration(options, startTime);
             }
-            const isImageModel = IMAGE_GENERATION_MODELS.some((m) => this.modelName.includes(m));
+            const isImageModel = isImageGenerationModel(this.modelName);
             const requestsNonImageOutput = options.output?.format === "json" ||
                 options.output?.format === "structured" ||
                 options.output?.format === "text";

package/dist/lib/core/dynamicModels.d.ts

@@ -1,4 +1,4 @@
-import type { DynamicModelConfig as ModelConfig } from "../types/index.js";
+import { type DynamicModelConfig as ModelConfig } from "../types/index.js";
 /**
  * Dynamic Model Provider
  * Loads and manages model configurations from external sources

package/dist/lib/core/dynamicModels.js

@@ -1,28 +1,6 @@
-import { z } from "zod";
 import { isAbortError } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
-/**
- * Model configuration schema for validation
- */
-const ModelConfigSchema = z.object({
-    id: z.string(),
-    displayName: z.string(),
-    capabilities: z.array(z.string()),
-    deprecated: z.boolean(),
-    pricing: z.object({
-        input: z.number(),
-        output: z.number(),
-    }),
-    contextWindow: z.number(),
-    releaseDate: z.string(),
-});
-const ModelRegistrySchema = z.object({
-    version: z.string(),
-    lastUpdated: z.string(),
-    models: z.record(z.string(), z.record(z.string(), ModelConfigSchema)),
-    aliases: z.record(z.string(), z.string()).optional(),
-    defaults: z.record(z.string(), z.string()).optional(),
-});
+import { ModelRegistrySchema, } from "../types/index.js";
 /**
  * Dynamic Model Provider
  * Loads and manages model configurations from external sources

package/dist/lib/core/modelConfiguration.d.ts

@@ -4,7 +4,7 @@
  * Replaces hardcoded model-specific logic with configurable, runtime-updateable configurations.
  * This addresses GitHub Copilot review comment about making model-specific logic configuration-based.
  */
-import type { ModelTier, ProviderConfiguration, ConfigSource } from "../types/index.js";
+import type { ModelTier, ProviderConfiguration } from "../types/index.js";
 /**
  * Model name constants - extracted from hardcoded values for better maintainability
  * These constants can be overridden by environment variables
@@ -153,53 +153,6 @@ export declare class ModelConfigurationManager {
      * Get all provider configurations
      */
     getAllConfigurations(): Map<string, ProviderConfiguration>;
-    /**
-     * Update provider configuration (runtime updates)
-     */
-    updateProviderConfiguration(provider: string, config: ProviderConfiguration): void;
-    /**
-     * Parse YAML content with basic support
-     * For full YAML support, would need a proper YAML library
-     */
-    private parseYAMLContent;
-    /**
-     * Convert simple YAML to JSON object
-     * Handles basic key-value pairs only
-     */
-    private convertSimpleYAMLToJSON;
-    /**
-     * Process a single YAML line
-     * Returns key-value pair if valid, null otherwise
-     */
-    private processYAMLLine;
-    /**
-     * Convert YAML value to appropriate JavaScript type
-     */
-    private convertYAMLValue;
-    /**
-     * Load configurations from external source
-     */
-    loadConfigurationsFromFile(configPath: string): void;
-    /**
-     * Validate provider configuration structure
-     */
-    private isValidProviderConfiguration;
-    /**
-     * Apply model name overrides from configuration file
-     */
-    private applyModelNameOverrides;
-    /**
-     * Apply global default configurations
-     */
-    private applyGlobalDefaults;
-    /**
-     * Get configuration metadata
-     */
-    getConfigurationMeta(): {
-        source: ConfigSource;
-        lastUpdated: number;
-        providerCount: number;
-    };
     /**
      * Get model for specific tier and provider
      */
@@ -224,25 +177,3 @@ export declare class ModelConfigurationManager {
  * Global instance accessor
  */
 export declare const modelConfig: ModelConfigurationManager;
-/**
- * Convenience functions for common operations
- */
-/**
- * Get provider configuration (backwards compatible)
- */
-export declare function getProviderConfiguration(provider: string): ProviderConfiguration | null;
-/**
- * Get model for tier (backwards compatible)
- */
-export declare function getModelForTier(provider: string, tier: ModelTier): string | null;
-/**
- * Get cost information (backwards compatible)
- */
-export declare function getCostInfo(provider: string, model?: string): {
-    input: number;
-    output: number;
-} | null;
-/**
- * Check provider availability (backwards compatible)
- */
-export declare function isProviderAvailable(provider: string): boolean;