@juspay/neurolink 11.2.2 → 11.2.4

package/dist/core/handlerRegistry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}

package/dist/core/handlerRegistry.js

@@ -0,0 +1,61 @@
+import { logger } from "../utils/logger.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export class HandlerRegistry {
+    scopeName;
+    handlers = new Map();
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName) {
+        this.scopeName = scopeName;
+    }
+    register(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            // Every caller today passes a literal provider slug, but this class is
+            // generic over an arbitrary string — sanitize before logging it so a
+            // future caller building the key from untrusted input can't leak a
+            // bearer token/API key through this warning.
+            logger.warn(`[${this.scopeName}] Overwriting existing handler for provider: ${sanitizeForLog(key)}`);
+        }
+        this.handlers.set(key, handler);
+    }
+    supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    get(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    clear() {
+        this.handlers.clear();
+        logger.debug(`[${this.scopeName}] Cleared all handlers`);
+    }
+}

package/dist/factories/providerRegistry.js

@@ -1,7 +1,8 @@
 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 { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
+import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -111,12 +112,18 @@ export class ProviderRegistry {
                 return new HuggingFaceProvider(modelName, sdk, region, hfCreds);
             }, process.env.HUGGINGFACE_MODEL ||
                 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"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.MISTRAL));
+            // Register the config-driven OpenAI-compatible catalog providers
+            // (groq, xai, together-ai, fireworks, perplexity, mistral, cloudflare).
+            // To add a new zero-quirk OpenAI-compatible provider, add one entry to
+            // OPENAI_COMPAT_CATALOG (openaiCompatCatalog.ts) — not a new block here.
+            for (const entry of OPENAI_COMPAT_CATALOG) {
+                ProviderFactory.registerProvider(entry.providerName, async (modelName, _providerName, sdk, _region, credentials) => {
+                    const { ConfiguredOpenAICompatProvider } = await import("../providers/configuredOpenAICompat.js");
+                    return new ConfiguredOpenAICompatProvider(entry, modelName, sdk, credentials);
+                }, entry.registryDefaultModelChecksEnvVar
+                    ? process.env[entry.modelEnvVar] || entry.registryDefaultModel
+                    : entry.registryDefaultModel, entry.aliases, PROVIDER_DESCRIPTORS_BY_NAME.get(entry.providerName));
+            }
             // Register Ollama provider
             ProviderFactory.registerProvider(AIProviderName.OLLAMA, async (modelName, _providerName, sdk, _region, credentials) => {
                 const ollamaCreds = credentials;
@@ -178,49 +185,12 @@ export class ProviderRegistry {
                 const { LlamaCppProvider } = await import("../providers/llamaCpp.js");
                 return new LlamaCppProvider(modelName, sdk, undefined, llamaCppCreds);
             }, 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"], 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"], 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"], 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"], 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"], 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"], 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"], 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;

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

@@ -0,0 +1,29 @@
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export declare class HandlerRegistry<THandler> {
+    private readonly scopeName;
+    private readonly handlers;
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName: string);
+    register(providerName: string, handler: THandler): void;
+    supports(providerName: string): boolean;
+    get(providerName: string): THandler | undefined;
+    list(): string[];
+    clear(): void;
+}

package/dist/lib/core/handlerRegistry.js

@@ -0,0 +1,62 @@
+import { logger } from "../utils/logger.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
+/**
+ * Generic provider-name → handler registry shared by every media-generation
+ * ecosystem (TTS, STT, Realtime, Video, Music, Avatar). Each ecosystem's own
+ * processor class composes one instance of this class instead of hand-rolling
+ * its own `Map<string, THandler>` plus register/supports/get/list methods.
+ *
+ * Centralizes only the behavior that was byte-identical across all six
+ * hand-rolled registries: input validation, name normalization (lowercase),
+ * the overwrite-warning log line, and the four lookup/list/clear operations.
+ * Registration-outcome debug logging (whose exact phrasing differs per
+ * ecosystem — e.g. "Registered TTS handler..." vs "Registered video
+ * handler...") and any ecosystem-specific extra logging (e.g. TTS/STT's
+ * `supports()` diagnostics) stay in the owning processor's own wrapper
+ * methods; this class does not attempt to unify those.
+ */
+export class HandlerRegistry {
+    scopeName;
+    handlers = new Map();
+    /**
+     * @param scopeName Log-line prefix, e.g. "TTSProcessor" — matches the
+     *   `[ClassName]` prefix each processor already uses in its own logs.
+     */
+    constructor(scopeName) {
+        this.scopeName = scopeName;
+    }
+    register(providerName, handler) {
+        if (!providerName) {
+            throw new Error("Provider name is required");
+        }
+        if (!handler) {
+            throw new Error("Handler is required");
+        }
+        const key = providerName.toLowerCase();
+        if (this.handlers.has(key)) {
+            // Every caller today passes a literal provider slug, but this class is
+            // generic over an arbitrary string — sanitize before logging it so a
+            // future caller building the key from untrusted input can't leak a
+            // bearer token/API key through this warning.
+            logger.warn(`[${this.scopeName}] Overwriting existing handler for provider: ${sanitizeForLog(key)}`);
+        }
+        this.handlers.set(key, handler);
+    }
+    supports(providerName) {
+        if (!providerName) {
+            return false;
+        }
+        return this.handlers.has(providerName.toLowerCase());
+    }
+    get(providerName) {
+        return this.handlers.get(providerName.toLowerCase());
+    }
+    list() {
+        return Array.from(this.handlers.keys());
+    }
+    clear() {
+        this.handlers.clear();
+        logger.debug(`[${this.scopeName}] Cleared all handlers`);
+    }
+}
+//# sourceMappingURL=handlerRegistry.js.map

package/dist/lib/factories/providerRegistry.js

@@ -1,7 +1,8 @@
 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 { AIProviderName, GoogleAIModels, OpenAIModels, AnthropicModels, VertexModels, OllamaModels, LiteLLMModels, HuggingFaceModels, DeepSeekModels, NvidiaNimModels, OpenRouterModels, CohereModels, VoyageModels, JinaModels, StabilityModels, IdeogramModels, RecraftModels, ReplicateModels, } from "../constants/enums.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "./providerDescriptors.js";
+import { OPENAI_COMPAT_CATALOG } from "../providers/openaiCompatCatalog.js";
 /**
  * Provider Registry - registers all providers with the factory
  * This is where we migrate providers one by one to the new pattern
@@ -111,12 +112,18 @@ export class ProviderRegistry {
                 return new HuggingFaceProvider(modelName, sdk, region, hfCreds);
             }, process.env.HUGGINGFACE_MODEL ||
                 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"], PROVIDER_DESCRIPTORS_BY_NAME.get(AIProviderName.MISTRAL));
+            // Register the config-driven OpenAI-compatible catalog providers
+            // (groq, xai, together-ai, fireworks, perplexity, mistral, cloudflare).
+            // To add a new zero-quirk OpenAI-compatible provider, add one entry to
+            // OPENAI_COMPAT_CATALOG (openaiCompatCatalog.ts) — not a new block here.
+            for (const entry of OPENAI_COMPAT_CATALOG) {
+                ProviderFactory.registerProvider(entry.providerName, async (modelName, _providerName, sdk, _region, credentials) => {
+                    const { ConfiguredOpenAICompatProvider } = await import("../providers/configuredOpenAICompat.js");
+                    return new ConfiguredOpenAICompatProvider(entry, modelName, sdk, credentials);
+                }, entry.registryDefaultModelChecksEnvVar
+                    ? process.env[entry.modelEnvVar] || entry.registryDefaultModel
+                    : entry.registryDefaultModel, entry.aliases, PROVIDER_DESCRIPTORS_BY_NAME.get(entry.providerName));
+            }
             // Register Ollama provider
             ProviderFactory.registerProvider(AIProviderName.OLLAMA, async (modelName, _providerName, sdk, _region, credentials) => {
                 const ollamaCreds = credentials;
@@ -178,49 +185,12 @@ export class ProviderRegistry {
                 const { LlamaCppProvider } = await import("../providers/llamaCpp.js");
                 return new LlamaCppProvider(modelName, sdk, undefined, llamaCppCreds);
             }, 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"], 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"], 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"], 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"], 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"], 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"], 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"], 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;

package/dist/lib/providers/configuredOpenAICompat.js

@@ -2,6 +2,7 @@ import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
 import { getProviderModel, resolveOpenAICompatConfig, } from "../utils/providerConfig.js";
 import { classifyProviderError } from "../utils/errorClassifier.js";
+import { TimeoutError } from "../utils/timeout.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
 /**
  * Generic OpenAI-compatible provider driven entirely by an
@@ -51,9 +52,15 @@ export class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvide
         return this.entry.fallbackModels;
     }
     formatProviderError(error) {
-        // classifyProviderError handles TimeoutError internally (always maps
-        // to NetworkError, ahead of any rule table) — no local pre-check
-        // needed or wanted here; see this task's design note.
+        // classifyProviderError hard-codes TimeoutError -> NetworkError ahead
+        // of any rule table and does not allow a per-provider override. An
+        // entry can opt out of that default via timeoutErrorClass (currently
+        // only Groq, reproducing its pre-migration subclass's own TimeoutError
+        // interception) — checked here, before ever reaching the shared
+        // classifier, so every other entry still gets its unmodified default.
+        if (error instanceof TimeoutError && this.entry.timeoutErrorClass) {
+            return new this.entry.timeoutErrorClass(`${this.entry.configOptions.providerName} request timed out: ${error.message}`, this.entry.providerName);
+        }
         return classifyProviderError(error, this.entry.errorRules, this.entry.providerName, this.modelName);
     }
 }

package/dist/lib/providers/openaiCompatCatalog.js

@@ -49,17 +49,15 @@ export const OPENAI_COMPAT_CATALOG = [
             GroqModels.LLAMA_3_2_90B_VISION_PREVIEW,
             GroqModels.LLAMA_3_2_11B_VISION_PREVIEW,
         ],
-        // KNOWN GAP (not reproducible by this data-only array — flagged for PR C,
-        // see plan-05/task-A-report.md): live GroqProvider.formatProviderError()
-        // intercepts TimeoutError and returns a plain ProviderError BEFORE ever
-        // calling classifyProviderError, overriding that function's own
-        // (non-overridable) rule that TimeoutError always maps to NetworkError.
-        // ConfiguredOpenAICompatProvider.formatProviderError() has no such
-        // pre-check hook, so migrating Groq onto it as-is would silently
-        // reclassify Groq timeouts as NetworkError. This entry's errorRules
-        // still mirrors Groq's live rule array faithfully for every other error
-        // shape; the TimeoutError special case is a structural gap in
-        // ConfiguredOpenAICompatProvider, not a data error here.
+        // Groq's pre-migration subclass intercepted TimeoutError itself and
+        // returned a plain ProviderError, ahead of classifyProviderError's own
+        // non-overridable TimeoutError -> NetworkError default. Expressed here
+        // as data — see OpenAICompatCatalogEntry.timeoutErrorClass and
+        // ConfiguredOpenAICompatProvider.formatProviderError, which consults
+        // this field before ever delegating to the shared classifier. No other
+        // entry in this catalog sets it, so every other provider still gets
+        // the classifier's unmodified default.
+        timeoutErrorClass: ProviderError,
         errorRules: [
             {
                 match: (ctx) => ctx.statusCode === 401 ||

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

@@ -8,7 +8,7 @@ import type { ValidationSchema } from "./aliases.js";
 import type { EnhancedGenerateResult, GenerateResult, TextGenerationOptions } from "./generate.js";
 import type { MultimodalAudioEntry } from "./file.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
-import type { ProviderErrorRule } from "./errors.js";
+import type { ProviderError, ProviderErrorRule } from "./errors.js";
 import type { ExternalMCPToolInfo } from "./externalMcp.js";
 import type { ClaudeSubscriptionTier, AnthropicAuthMethod, AnthropicAuthConfig, SubscriptionInfo, OAuthToken } from "./subscription.js";
 import type { Tool } from "./tools.js";
@@ -671,6 +671,20 @@ export type OpenAICompatCatalogEntry = {
      * Task 4, so nothing actually mutates it at runtime.
      */
     errorRules: ProviderErrorRule[];
+    /**
+     * Optional override for the Error subclass a TimeoutError should produce
+     * for this entry. classifyProviderError() hard-codes
+     * TimeoutError -> NetworkError unconditionally, ahead of any rule table,
+     * and does not make that mapping overridable per-provider (see
+     * errorClassifier.ts). Groq's pre-migration subclass predates that
+     * shared classifier and intercepted TimeoutError itself, returning a
+     * plain ProviderError instead — this field lets
+     * ConfiguredOpenAICompatProvider reproduce that one documented
+     * divergence as data (see its formatProviderError), rather than adding a
+     * class-level hook back in. Omit for every entry whose timeout should use
+     * the classifier's default (six of the seven catalog entries).
+     */
+    timeoutErrorClass?: new (message: string, provider?: string) => ProviderError;
 };
 /** The subset of OpenAICompatCatalogEntry that resolveOpenAICompatConfig()
  *  needs — lets call sites pass a minimal object without the full catalog

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

@@ -43,7 +43,7 @@ export declare class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export declare class AvatarProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register an avatar handler for a specific provider.
      */
@@ -63,6 +63,10 @@ export declare class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): AvatarHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate an avatar video via the registered handler.

package/dist/lib/utils/avatarProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Avatar-specific error codes.
  */
@@ -47,38 +48,26 @@ export class AvatarError extends NeuroLinkError {
  * Static processor managing the avatar handler registry.
  */
 export class AvatarProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("AvatarProcessor");
     /**
      * Register an avatar handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[AvatarProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[AvatarProcessor] Registered avatar handler: ${key}`);
     }
     /**
      * Check if a provider has a registered avatar handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered avatar handler by provider name.
@@ -87,7 +76,13 @@ export class AvatarProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {

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

@@ -42,7 +42,7 @@ export declare class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export declare class MusicProcessor {
-    private static readonly handlers;
+    private static readonly registry;
     /**
      * Register a music handler for a specific provider.
      */
@@ -62,6 +62,10 @@ export declare class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName: string): MusicHandler | undefined;
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers(): void;
     private static buildSpanAttributes;
     /**
      * Generate a music track via the registered handler.

package/dist/lib/utils/musicProcessor.js

@@ -13,6 +13,7 @@ import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { SpanSerializer, SpanStatus, SpanType, getMetricsAggregator, } from "../observability/index.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { logger } from "./logger.js";
+import { HandlerRegistry } from "../core/handlerRegistry.js";
 /**
  * Music-specific error codes.
  */
@@ -46,38 +47,26 @@ export class MusicError extends NeuroLinkError {
  * Static processor managing the music handler registry.
  */
 export class MusicProcessor {
-    static handlers = new Map();
+    static registry = new HandlerRegistry("MusicProcessor");
     /**
      * Register a music handler for a specific provider.
      */
     static registerHandler(providerName, handler) {
-        if (!providerName) {
-            throw new Error("Provider name is required");
-        }
-        if (!handler) {
-            throw new Error("Handler is required");
-        }
-        const key = providerName.toLowerCase();
-        if (this.handlers.has(key)) {
-            logger.warn(`[MusicProcessor] Overwriting existing handler for provider: ${key}`);
-        }
-        this.handlers.set(key, handler);
+        const key = providerName ? providerName.toLowerCase() : providerName;
+        this.registry.register(providerName, handler);
         logger.debug(`[MusicProcessor] Registered music handler: ${key}`);
     }
     /**
      * Check if a provider has a registered music handler.
      */
     static supports(providerName) {
-        if (!providerName) {
-            return false;
-        }
-        return this.handlers.has(providerName.toLowerCase());
+        return this.registry.supports(providerName);
     }
     /**
      * List the names of all registered providers.
      */
     static listProviders() {
-        return Array.from(this.handlers.keys());
+        return this.registry.list();
     }
     /**
      * Get a registered music handler by provider name.
@@ -86,7 +75,13 @@ export class MusicProcessor {
      * already-registered primary handler when backfilling its aliases.
      */
     static getHandler(providerName) {
-        return this.handlers.get(providerName.toLowerCase());
+        return this.registry.get(providerName);
+    }
+    /**
+     * Clear all registered handlers (for testing).
+     */
+    static clearHandlers() {
+        this.registry.clear();
     }
     static buildSpanAttributes(provider, options) {
         return {