@juspay/neurolink 9.41.0 → 9.42.0

package/dist/lib/utils/providerHealth.js

@@ -228,7 +228,8 @@ export class ProviderHealthChecker {
         }
         // Providers that don't use API keys directly
         if (providerName === AIProviderName.OLLAMA ||
-            providerName === AIProviderName.BEDROCK) {
+            providerName === AIProviderName.BEDROCK ||
+            providerName === AIProviderName.LITELLM) {
             healthStatus.hasApiKey = true;
             return;
         }
@@ -368,6 +369,8 @@ export class ProviderHealthChecker {
                 return [];
             case AIProviderName.AZURE:
                 return ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"];
+            case AIProviderName.LITELLM:
+                return [];
             case AIProviderName.OLLAMA:
                 return []; // Ollama typically doesn't require API keys
             default:
@@ -391,8 +394,10 @@ export class ProviderHealthChecker {
                 return "AWS_ACCESS_KEY_ID";
             case AIProviderName.AZURE:
                 return "AZURE_OPENAI_API_KEY";
+            case AIProviderName.LITELLM:
+                return "LITELLM_API_KEY";
             case AIProviderName.OLLAMA:
-                return "OLLAMA_API_BASE";
+                return "OLLAMA_BASE_URL";
             default:
                 return "";
         }
@@ -416,6 +421,8 @@ export class ProviderHealthChecker {
                 return apiKey.length >= API_KEY_LENGTHS.AWS_ACCESS_KEY; // AWS access key length
             case AIProviderName.AZURE:
                 return apiKey.length >= API_KEY_LENGTHS.AZURE_MIN; // Azure OpenAI API key length
+            case AIProviderName.LITELLM:
+                return apiKey.length > 0;
             case AIProviderName.OLLAMA:
                 return true; // Ollama usually doesn't require specific format
             default:
@@ -437,8 +444,10 @@ export class ProviderHealthChecker {
                 return null; // Complex authentication required
             case AIProviderName.BEDROCK:
                 return null; // AWS endpoints vary by region
+            case AIProviderName.LITELLM:
+                return this.getLiteLLMModelsUrl();
             case AIProviderName.OLLAMA:
-                return "http://localhost:11434/api/version";
+                return this.getOllamaTagsUrl();
             default:
                 return null;
         }
@@ -457,6 +466,9 @@ export class ProviderHealthChecker {
             case AIProviderName.AZURE:
                 await this.checkAzureConfig(healthStatus);
                 break;
+            case AIProviderName.LITELLM:
+                await this.checkLiteLLMConfig(healthStatus);
+                break;
             case AIProviderName.OLLAMA:
                 await this.checkOllamaConfig(healthStatus);
                 break;
@@ -648,15 +660,177 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push("Set one of: AZURE_OPENAI_MODEL, AZURE_OPENAI_DEPLOYMENT, or AZURE_OPENAI_DEPLOYMENT_ID");
         }
     }
+    static getLiteLLMBaseUrl() {
+        return process.env.LITELLM_BASE_URL || "http://localhost:4000";
+    }
+    static getLiteLLMModelsUrl() {
+        return new URL("/v1/models", this.getLiteLLMBaseUrl()).toString();
+    }
+    static getConfiguredLiteLLMModel() {
+        return process.env.LITELLM_MODEL || "openai/gpt-4o-mini";
+    }
+    static getOllamaBaseUrl() {
+        return (process.env.OLLAMA_BASE_URL ||
+            process.env.OLLAMA_API_BASE ||
+            "http://localhost:11434");
+    }
+    static getOllamaTagsUrl() {
+        return new URL("/api/tags", this.getOllamaBaseUrl()).toString();
+    }
+    static getConfiguredOllamaModel() {
+        return process.env.OLLAMA_MODEL || "llama3.1:8b";
+    }
+    static async fetchJsonWithTimeout(url, options = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.DEFAULT_TIMEOUT);
+        try {
+            const proxyFetch = createProxyFetch();
+            const response = await proxyFetch(url, {
+                method: "GET",
+                headers: options.headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            return await response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    static normalizeModelList(models) {
+        return models
+            .map((entry) => {
+            if (typeof entry === "string") {
+                return entry;
+            }
+            if (entry &&
+                typeof entry === "object" &&
+                "id" in entry &&
+                typeof entry.id === "string") {
+                return entry.id;
+            }
+            if (entry &&
+                typeof entry === "object" &&
+                "name" in entry &&
+                typeof entry.name === "string") {
+                return entry.name;
+            }
+            return null;
+        })
+            .filter((model) => typeof model === "string");
+    }
+    static hasRequestedModel(availableModels, requestedModel) {
+        return availableModels.some((model) => model === requestedModel ||
+            model.startsWith(`${requestedModel}:`) ||
+            requestedModel.startsWith(`${model}:`));
+    }
+    static async getOllamaAvailableModels(timeout = 2000) {
+        const payload = (await this.fetchJsonWithTimeout(this.getOllamaTagsUrl(), {
+            timeout,
+        }));
+        return this.normalizeModelList(payload.models ?? []);
+    }
+    static async getLiteLLMAvailableModels(timeout = 2000) {
+        const payload = (await this.fetchJsonWithTimeout(this.getLiteLLMModelsUrl(), {
+            timeout,
+            headers: {
+                Authorization: `Bearer ${process.env.LITELLM_API_KEY || "sk-anything"}`,
+                "Content-Type": "application/json",
+            },
+        }));
+        return this.normalizeModelList(payload.data ?? []);
+    }
+    static async checkOllamaAvailability(options) {
+        try {
+            const models = await this.getOllamaAvailableModels(options.timeout);
+            if (!this.hasRequestedModel(models, options.model)) {
+                return {
+                    available: false,
+                    reason: `Configured Ollama model '${options.model}' is not installed`,
+                    models,
+                };
+            }
+            return { available: true, models };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+                models: [],
+            };
+        }
+    }
+    static async checkLiteLLMAvailability(options) {
+        try {
+            const models = await this.getLiteLLMAvailableModels(options.timeout);
+            if (models.length === 0) {
+                return {
+                    available: false,
+                    reason: "LiteLLM returned an empty model list",
+                    models,
+                };
+            }
+            if (!this.hasRequestedModel(models, options.model)) {
+                return {
+                    available: false,
+                    reason: `Configured LiteLLM model '${options.model}' is not exposed by the proxy`,
+                    models,
+                };
+            }
+            return { available: true, models };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+                models: [],
+            };
+        }
+    }
+    static async checkLiteLLMConfig(healthStatus) {
+        const liteLLMBase = this.getLiteLLMBaseUrl();
+        if (!liteLLMBase.startsWith("http")) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push("Invalid LITELLM_BASE_URL format");
+            healthStatus.recommendations.push("Set LITELLM_BASE_URL to a valid URL (e.g., http://localhost:4000)");
+            return;
+        }
+        const availability = await this.checkLiteLLMAvailability({
+            model: this.getConfiguredLiteLLMModel(),
+            timeout: 2000,
+        });
+        if (!availability.available) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push(`LiteLLM runtime check failed: ${availability.reason ?? "unknown error"}`);
+            healthStatus.recommendations.push("Start the LiteLLM proxy and ensure the configured model is available from /v1/models");
+            return;
+        }
+        healthStatus.isConfigured = true;
+    }
     /**
      * Check Ollama configuration
      */
     static async checkOllamaConfig(healthStatus) {
-        const ollamaBase = process.env.OLLAMA_API_BASE || "http://localhost:11434";
+        const ollamaBase = this.getOllamaBaseUrl();
         if (!ollamaBase.startsWith("http")) {
-            healthStatus.configurationIssues.push("Invalid OLLAMA_API_BASE format");
-            healthStatus.recommendations.push("Set OLLAMA_API_BASE to a valid URL (e.g., http://localhost:11434)");
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
+            healthStatus.recommendations.push("Set OLLAMA_BASE_URL to a valid URL (e.g., http://localhost:11434). OLLAMA_API_BASE remains supported as a legacy alias.");
+            return;
         }
+        const availability = await this.checkOllamaAvailability({
+            model: this.getConfiguredOllamaModel(),
+            timeout: 2000,
+        });
+        if (!availability.available) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push(`Ollama runtime check failed: ${availability.reason ?? "unknown error"}`);
+            healthStatus.recommendations.push("Start Ollama and install the configured model before using Ollama as a fallback provider");
+            return;
+        }
+        healthStatus.isConfigured = true;
     }
     /**
      * Get common models for a provider
@@ -703,8 +877,21 @@ export class ProviderHealthChecker {
                 return [BedrockModels.CLAUDE_3_SONNET, BedrockModels.CLAUDE_3_HAIKU];
             case AIProviderName.AZURE:
                 return [OpenAIModels.GPT_4O, OpenAIModels.GPT_4O_MINI, "gpt-35-turbo"];
-            case AIProviderName.OLLAMA:
-                return ["llama3.2:latest", "llama3.1:latest", "mistral:latest"];
+            case AIProviderName.LITELLM:
+                return [
+                    "openai/gpt-4o-mini",
+                    "anthropic/claude-3-haiku",
+                    "google/gemini-2.5-flash",
+                ];
+            case AIProviderName.OLLAMA: {
+                const envModel = process.env.OLLAMA_MODEL;
+                const defaults = [
+                    "llama3.2:latest",
+                    "llama3.1:latest",
+                    "mistral:latest",
+                ];
+                return envModel ? [envModel, ...defaults] : defaults;
+            }
             default:
                 return [];
         }
@@ -1139,18 +1326,61 @@ export class ProviderHealthChecker {
             this.consecutiveFailures.clear();
         }
     }
+    static async checkFallbackProviderAvailability(providerName, model) {
+        const provider = providerName;
+        if (provider === AIProviderName.OLLAMA) {
+            const availability = await this.checkOllamaAvailability({
+                model,
+                timeout: 2000,
+            });
+            return {
+                available: availability.available,
+                reason: availability.reason,
+            };
+        }
+        if (provider === AIProviderName.LITELLM) {
+            const availability = await this.checkLiteLLMAvailability({
+                model,
+                timeout: 2000,
+            });
+            return {
+                available: availability.available,
+                reason: availability.reason,
+            };
+        }
+        try {
+            const health = await this.checkProviderHealth(provider, {
+                includeConnectivityTest: false,
+                cacheResults: true,
+                maxCacheAge: 15_000,
+                timeout: 2000,
+            });
+            return {
+                available: health.isHealthy,
+                reason: health.error || health.configurationIssues[0] || health.warning,
+            };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
     /**
      * Get the best healthy provider from a list of options (NON-BLOCKING)
      * Prioritizes healthy providers over configured but unhealthy ones
      * Uses fast, cached health checks to avoid blocking initialization
      */
     static async getBestHealthyProvider(preferredProviders = [
+        "litellm",
+        "ollama",
         "openai",
         "anthropic",
         "vertex",
+        "google-ai",
         "bedrock",
         "azure",
-        "google-ai",
     ]) {
         const healthStatuses = await this.checkAllProvidersHealth({
             includeConnectivityTest: false, // Quick config check only
@@ -1191,6 +1421,7 @@ export class ProviderHealthChecker {
             AIProviderName.OPENAI,
             AIProviderName.BEDROCK,
             AIProviderName.AZURE,
+            AIProviderName.LITELLM,
             AIProviderName.OLLAMA,
         ];
         const healthChecks = providers.map((provider) => this.checkProviderHealth(provider, options));

package/dist/lib/utils/providerUtils.js

@@ -63,15 +63,18 @@ export async function getBestProvider(requestedProvider) {
     }
     /**
      * Provider priority order rationale:
-     * - Vertex (Google Cloud AI) is prioritized first for its enterprise-grade reliability and advanced model capabilities.
-     * - Google AI follows as second priority for comprehensive Google AI ecosystem support.
+     * - LiteLLM and Ollama are prioritized first for local/self-hosted deployments,
+     *   avoiding cloud quota/rate-limit issues during fallback scenarios.
+     * - Vertex (Google Cloud AI) follows for enterprise-grade reliability.
+     * - Google AI follows as second cloud priority for comprehensive Google AI ecosystem support.
      * - OpenAI maintains high priority due to its consistent reliability and broad model support.
-     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance in our use cases.
-     * - Ollama is kept as a fallback for local deployments when available.
+     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance.
      * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
      */
     const providers = [
-        "vertex", // Prioritize Google Cloud AI (Vertex) first
+        "litellm", // Prioritize self-hosted/proxy (no rate limits)
+        "ollama", // Local models (no rate limits)
+        "vertex", // Google Cloud AI (enterprise)
         "google-ai", // Google AI ecosystem support
         "openai", // Reliable with broad model support
         "anthropic",
@@ -79,7 +82,6 @@ export async function getBestProvider(requestedProvider) {
         "azure",
         "mistral",
         "huggingface",
-        "ollama", // Keep as fallback
     ];
     for (const provider of providers) {
         if (await isProviderAvailable(provider)) {
@@ -107,8 +109,11 @@ async function isProviderAvailable(providerName) {
             });
             if (response.ok) {
                 const { models } = await response.json();
-                const defaultOllamaModel = "llama3.2:latest";
-                return models.some((m) => m.name === defaultOllamaModel);
+                const defaultOllamaModel = process.env.OLLAMA_MODEL || "llama3.1:8b";
+                // Check for exact match first, then prefix match (e.g. "gemma3:27b" matches "gemma3:27b-fp16")
+                return models.some((m) => m.name === defaultOllamaModel ||
+                    (typeof m.name === "string" &&
+                        m.name.startsWith(defaultOllamaModel.split(":")[0] + ":")));
             }
             return false;
         }
@@ -414,6 +419,7 @@ export function getAvailableProviders() {
         "anthropic",
         "azure",
         "google-ai",
+        "litellm",
         "huggingface",
         "ollama",
         "mistral",

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

@@ -0,0 +1,4 @@
+import type { Tool, ToolChoice } from "ai";
+export declare function resolveToolChoice(options: {
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+}, tools: Record<string, Tool> | undefined, shouldUseTools: boolean): ToolChoice<Record<string, Tool>> | "none";

package/dist/lib/utils/toolChoice.js

@@ -0,0 +1,7 @@
+export function resolveToolChoice(options, tools, shouldUseTools) {
+    if (!shouldUseTools || !tools || Object.keys(tools).length === 0) {
+        return "none";
+    }
+    return options.toolChoice ?? "auto";
+}
+//# sourceMappingURL=toolChoice.js.map

package/dist/neurolink.d.ts

@@ -13,8 +13,9 @@ import type { MCPToolAnnotations } from "./mcp/toolAnnotations.js";
 import { MCPToolRegistry } from "./mcp/toolRegistry.js";
 import type { MetricsSummary, TraceView } from "./observability/metricsAggregator.js";
 import type { SpanData } from "./observability/types/spanTypes.js";
-import type { JsonObject, NeuroLinkEvents, TypedEventEmitter } from "./types/common.js";
+import { TaskManager } from "./tasks/taskManager.js";
 import type { AuthenticatedContext, MastraAuthProvider } from "./types/authTypes.js";
+import type { JsonObject, NeuroLinkEvents, TypedEventEmitter } from "./types/common.js";
 import type { MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig } from "./types/configTypes.js";
 import type { ChatMessage } from "./types/conversation.js";
 import type { ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo } from "./types/externalMcp.js";
@@ -25,7 +26,6 @@ import type { ObservabilityConfig } from "./types/observability.js";
 import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions } from "./types/tools.js";
 import type { BatchOperationResult } from "./types/typeAliases.js";
-import { TaskManager } from "./tasks/taskManager.js";
 export declare class NeuroLink {
     private mcpInitialized;
     private mcpSkipped;
@@ -1909,6 +1909,7 @@ export declare class NeuroLink {
      * @param config - Auth provider or configuration to create one
      */
     setAuthProvider(config: NeuroLinkAuthConfig): Promise<void>;
+    private initializeAuthProviderFromConfig;
     /**
      * Get the currently configured authentication provider
      */