@juspay/neurolink
Version:
Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applicatio
1,073 lines • 66.5 kB
JavaScript
/**
* Provider Health Checking System
* Prevents 500 errors by validating provider availability and configuration
*/
import { logger } from "./logger.js";
import { AIProviderName, OpenAIModels, GoogleAIModels, AnthropicModels, BedrockModels, } from "../constants/enums.js";
import { API_KEY_LENGTHS, PROJECT_ID_FORMAT } from "./providerConfig.js";
import { basename } from "path";
import { createProxyFetch } from "../proxy/proxyFetch.js";
export class ProviderHealthChecker {
static healthCache = new Map();
static DEFAULT_TIMEOUT = 5000; // 5 seconds
static DEFAULT_CACHE_AGE = 300000; // 5 minutes
static CONSECUTIVE_FAILURE_THRESHOLD = ProviderHealthChecker.getValidatedFailureThreshold();
static consecutiveFailures = new Map();
/**
* Validate and return a safe failure threshold value
*/
static getValidatedFailureThreshold() {
const envValue = process.env.PROVIDER_FAILURE_THRESHOLD;
if (!envValue) {
return 3; // default
}
const parsed = Number(envValue);
if (isNaN(parsed) || parsed <= 0 || parsed > 10) {
logger.warn(`Invalid PROVIDER_FAILURE_THRESHOLD: ${envValue} (must be between 1 and 10), using default: 3`);
return 3;
}
return parsed;
}
/**
* Comprehensive health check for a provider
*/
static async checkProviderHealth(providerName, options = {}) {
const { timeout = this.DEFAULT_TIMEOUT, includeConnectivityTest = false, includeModelValidation = false, cacheResults = true, maxCacheAge = this.DEFAULT_CACHE_AGE, } = options;
// Check cache first
if (cacheResults) {
const cached = this.getCachedHealth(providerName, maxCacheAge);
if (cached) {
logger.debug(`Using cached health status for ${providerName}`);
return cached;
}
}
// Check if provider has consecutive failures (blacklisting)
const failureCount = this.consecutiveFailures.get(providerName) || 0;
if (failureCount >= this.CONSECUTIVE_FAILURE_THRESHOLD) {
const healthStatus = {
provider: providerName,
isHealthy: false,
isConfigured: false,
hasApiKey: false,
lastChecked: new Date(),
error: `Provider blacklisted after ${failureCount} consecutive failures`,
warning: "Provider will be retried after cache TTL expires",
configurationIssues: [
`Blacklisted due to ${failureCount} consecutive failures`,
],
recommendations: ["Check provider status and configuration"],
};
logger.warn(`Provider ${providerName} blacklisted due to consecutive failures`, { failureCount });
return healthStatus;
}
const startTime = Date.now();
const healthStatus = {
provider: providerName,
isHealthy: false,
isConfigured: false,
hasApiKey: false,
lastChecked: new Date(),
configurationIssues: [],
recommendations: [],
};
try {
// 1. Check environment configuration
await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout);
// 2. Check API key validity (basic format validation)
await this.checkApiKeyValidity(providerName, healthStatus);
// 3. Optional: Connectivity test
if (includeConnectivityTest) {
await this.checkConnectivity(providerName, healthStatus, timeout);
}
// 4. Optional: Model validation
if (includeModelValidation) {
await this.checkModelAvailability(providerName, healthStatus);
}
// 5. Determine overall health
healthStatus.isHealthy =
healthStatus.isConfigured &&
healthStatus.hasApiKey &&
healthStatus.configurationIssues.length === 0;
healthStatus.responseTime = Date.now() - startTime;
// Cache results
if (cacheResults) {
this.healthCache.set(providerName, {
status: healthStatus,
timestamp: Date.now(),
});
}
// Reset failure count on success
if (healthStatus.isHealthy) {
this.consecutiveFailures.delete(providerName);
}
else {
// Track consecutive failures
const currentFailures = this.consecutiveFailures.get(providerName) || 0;
this.consecutiveFailures.set(providerName, currentFailures + 1);
}
logger.debug(`Health check completed for ${providerName}`, {
isHealthy: healthStatus.isHealthy,
responseTime: healthStatus.responseTime,
issues: healthStatus.configurationIssues.length,
});
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
healthStatus.error = errorMessage;
healthStatus.configurationIssues.push(`Health check failed: ${errorMessage}`);
healthStatus.responseTime = Date.now() - startTime;
// Track consecutive failures
const currentFailures = this.consecutiveFailures.get(providerName) || 0;
this.consecutiveFailures.set(providerName, currentFailures + 1);
logger.warn(`Health check failed for ${providerName}`, {
error: errorMessage,
consecutiveFailures: currentFailures + 1,
});
}
return healthStatus;
}
/**
* Check environment configuration for a provider
*/
static async checkEnvironmentConfiguration(providerName, healthStatus, timeout) {
const requiredEnvVars = this.getRequiredEnvironmentVariables(providerName);
logger.debug(`[ProviderHealthChecker] Checking environment configuration for ${providerName}`, {
requiredEnvVars,
presentEnvVars: requiredEnvVars.map((envVar) => ({
name: envVar,
present: !!process.env[envVar],
hasValue: !!(process.env[envVar] && process.env[envVar].trim() !== ""),
})),
});
let allConfigured = true;
const missingVars = [];
for (const envVar of requiredEnvVars) {
const value = process.env[envVar];
if (!value || value.trim() === "") {
allConfigured = false;
missingVars.push(envVar);
}
}
healthStatus.isConfigured = allConfigured;
logger.debug(`[ProviderHealthChecker] Environment configuration result for ${providerName}`, {
isConfigured: allConfigured,
missingVars,
totalRequired: requiredEnvVars.length,
totalMissing: missingVars.length,
});
if (!allConfigured) {
healthStatus.configurationIssues.push(`Missing required environment variables: ${missingVars.join(", ")}`);
healthStatus.recommendations.push(`Set the following environment variables: ${missingVars.join(", ")}`);
}
// Provider-specific configuration checks
await this.checkProviderSpecificConfig(providerName, healthStatus, timeout);
}
/**
* Check API key validity (format validation)
*/
static async checkApiKeyValidity(providerName, healthStatus) {
// 🎯 SPECIAL HANDLING FOR VERTEX AI: Check both auth methods
if (providerName === AIProviderName.VERTEX) {
logger.debug("Vertex AI authentication check starting", {
providerName,
});
// Method 1: Check GOOGLE_APPLICATION_CREDENTIALS (file-based)
const credentialsFile = process.env.GOOGLE_APPLICATION_CREDENTIALS;
let fileBasedAuthValid = false;
if (credentialsFile) {
logger.debug("Checking GOOGLE_APPLICATION_CREDENTIALS file");
try {
const { promises: fs } = await import("fs");
try {
await fs.access(credentialsFile);
fileBasedAuthValid = true;
}
catch {
fileBasedAuthValid = false;
}
logger.debug("File auth check result", {
fileExists: fileBasedAuthValid,
});
}
catch (error) {
logger.debug("File auth check error", {
error: String(error),
});
fileBasedAuthValid = false;
}
}
// Method 2: Check individual environment variables
const hasIndividualAuth = !!(process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
process.env.GOOGLE_AUTH_PRIVATE_KEY);
logger.debug("Individual auth check", {
hasClientEmail: !!process.env.GOOGLE_AUTH_CLIENT_EMAIL,
hasPrivateKey: !!process.env.GOOGLE_AUTH_PRIVATE_KEY,
hasIndividualAuth,
});
// Vertex is valid if EITHER auth method works
const hasValidAuth = fileBasedAuthValid || hasIndividualAuth;
logger.debug("Vertex auth final result", {
fileBasedAuthValid,
hasIndividualAuth,
hasValidAuth,
});
if (hasValidAuth) {
healthStatus.hasApiKey = true;
logger.debug("Vertex auth SUCCESS", {
authMethod: fileBasedAuthValid ? "file-based" : "individual-env-vars",
});
}
else {
healthStatus.hasApiKey = false;
healthStatus.configurationIssues.push(`Vertex AI authentication not found: neither GOOGLE_APPLICATION_CREDENTIALS file nor individual credentials (GOOGLE_AUTH_CLIENT_EMAIL + GOOGLE_AUTH_PRIVATE_KEY) are properly configured`);
logger.debug("Vertex auth FAILED", {
reason: "No valid auth method found",
});
}
return;
}
// Providers that don't use API keys directly
if (providerName === AIProviderName.OLLAMA ||
providerName === AIProviderName.BEDROCK ||
providerName === AIProviderName.LITELLM) {
healthStatus.hasApiKey = true;
return;
}
// 🔧 STANDARD HANDLING FOR OTHER PROVIDERS
const apiKeyVar = this.getApiKeyEnvironmentVariable(providerName);
const apiKey = process.env[apiKeyVar];
if (!apiKey) {
healthStatus.hasApiKey = false;
healthStatus.configurationIssues.push(`API key not found in ${apiKeyVar}`);
return;
}
// Basic format validation
const isValidFormat = this.validateApiKeyFormat(providerName, apiKey);
if (!isValidFormat) {
healthStatus.hasApiKey = false;
healthStatus.configurationIssues.push(`API key format appears invalid for ${providerName}`);
healthStatus.recommendations.push(`Verify the API key format for ${providerName}`);
}
else {
healthStatus.hasApiKey = true;
}
}
/**
* Check connectivity to provider endpoints
*/
static async checkConnectivity(providerName, healthStatus, timeout) {
const endpoint = this.getProviderHealthEndpoint(providerName);
if (!endpoint) {
healthStatus.warning = "No connectivity test available for this provider";
return;
}
const headers = {
"User-Agent": "NeuroLink-HealthCheck/1.0",
...this.getConnectivityHeaders(providerName),
};
try {
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), timeout);
try {
const proxyFetch = createProxyFetch();
let response = await proxyFetch(endpoint, {
method: "HEAD",
signal: controller.signal,
headers,
});
// Fallback to GET if HEAD returns 405 (Method Not Allowed) for restrictive gateways
if (response.status === 405) {
response = await proxyFetch(endpoint, {
method: "GET",
signal: controller.signal,
headers,
});
}
if (!response.ok) {
healthStatus.configurationIssues.push(`Connectivity test failed: HTTP ${response.status}`);
}
}
finally {
clearTimeout(timeoutId);
}
}
catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
// Provide specific error messages for common network issues
if (errorMessage.includes("abort")) {
healthStatus.configurationIssues.push(`Connectivity test timed out after ${timeout}ms`);
}
else if (errorMessage.includes("ENOTFOUND") ||
errorMessage.includes("getaddrinfo")) {
healthStatus.configurationIssues.push(`DNS resolution failed: Cannot resolve hostname for ${providerName}`);
}
else if (errorMessage.includes("ECONNREFUSED")) {
healthStatus.configurationIssues.push(`Connection refused: ${providerName} service is not accepting connections`);
}
else if (errorMessage.includes("ETIMEDOUT")) {
healthStatus.configurationIssues.push(`Connection timeout: ${providerName} service did not respond`);
}
else if (errorMessage.includes("certificate") ||
errorMessage.includes("SSL") ||
errorMessage.includes("TLS")) {
healthStatus.configurationIssues.push(`SSL/TLS certificate error: ${providerName} has certificate issues`);
}
else if (errorMessage.includes("ECONNRESET")) {
healthStatus.configurationIssues.push(`Connection reset: ${providerName} terminated the connection`);
}
else if (errorMessage.includes("network") ||
errorMessage.includes("offline")) {
healthStatus.configurationIssues.push(`Network error: Check internet connectivity and firewall settings`);
}
else {
healthStatus.configurationIssues.push(`Connectivity test failed: ${errorMessage}`);
}
}
}
static getConnectivityHeaders(providerName) {
if (providerName === AIProviderName.LITELLM) {
return {
Authorization: `Bearer ${process.env.LITELLM_API_KEY || "sk-anything"}`,
};
}
return {};
}
/**
* Check model availability (if possible without making API calls)
*/
static async checkModelAvailability(providerName, healthStatus) {
// Basic model name validation and recommendations
const commonModels = this.getCommonModelsForProvider(providerName);
if (commonModels.length > 0) {
if (providerName === AIProviderName.VERTEX) {
// Provide detailed information about dual provider architecture
healthStatus.recommendations.push(`Available models for ${providerName} (using dual provider architecture):\n` +
` Google Models (via vertex provider):\n` +
` • gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite\n` +
` • gemini-2.0-flash-001, gemini-1.5-pro, gemini-1.5-flash\n` +
` Anthropic Models (via vertexAnthropic provider):\n` +
` • claude-sonnet-4@20250514, claude-opus-4@20250514\n` +
` • claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022\n` +
` • claude-3-sonnet-20240229, claude-3-haiku-20240307, claude-3-opus-20240229\n` +
` Implementation: Uses native SDKs (@google/genai for Gemini, @anthropic-ai/vertex-sdk for Claude)\n` +
` Authentication: Requires Google Cloud project with Vertex AI API enabled\n` +
` Note: Anthropic models require Anthropic integration in your Google Cloud project`);
}
else {
healthStatus.recommendations.push(`Common models for ${providerName}: ${commonModels.slice(0, 3).join(", ")}`);
}
}
}
/**
* Get required environment variables for a provider
*/
static getRequiredEnvironmentVariables(providerName) {
switch (providerName) {
case AIProviderName.ANTHROPIC:
return ["ANTHROPIC_API_KEY"];
case AIProviderName.OPENAI:
return ["OPENAI_API_KEY"];
case AIProviderName.VERTEX:
// Vertex AI requires authentication, but not via a single environment variable.
// Authentication can be provided via a credential file or individual credentials + project.
// The required authentication is checked in checkProviderSpecificConfig instead of here.
// Returning an empty array here does NOT mean authentication is not required.
return [];
case AIProviderName.GOOGLE_AI:
return ["GOOGLE_AI_API_KEY"];
case AIProviderName.BEDROCK:
// Bedrock credentials are resolved via AWS SDK default provider chain.
// Region/auth validated in provider-specific checks.
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:
return [];
}
}
/**
* Get API key environment variable for a provider
*/
static getApiKeyEnvironmentVariable(providerName) {
switch (providerName) {
case AIProviderName.ANTHROPIC:
return "ANTHROPIC_API_KEY";
case AIProviderName.OPENAI:
return "OPENAI_API_KEY";
case AIProviderName.VERTEX:
return "GOOGLE_APPLICATION_CREDENTIALS";
case AIProviderName.GOOGLE_AI:
return "GOOGLE_AI_API_KEY";
case AIProviderName.BEDROCK:
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_BASE_URL";
default:
return "";
}
}
/**
* Validate API key format for a provider
*/
static validateApiKeyFormat(providerName, apiKey) {
switch (providerName) {
case AIProviderName.ANTHROPIC:
return (apiKey.startsWith("sk-ant-") &&
apiKey.length >= API_KEY_LENGTHS.ANTHROPIC_MIN);
case AIProviderName.OPENAI:
return (apiKey.startsWith("sk-") &&
apiKey.length >= API_KEY_LENGTHS.OPENAI_MIN);
case AIProviderName.GOOGLE_AI:
return apiKey.length >= API_KEY_LENGTHS.GOOGLE_AI_EXACT; // Basic length check
case AIProviderName.VERTEX:
return apiKey.endsWith(".json") || apiKey.includes("type"); // JSON key format
case AIProviderName.BEDROCK:
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:
return true; // Default to true for unknown providers
}
}
/**
* Get health check endpoint for connectivity testing
*/
static getProviderHealthEndpoint(providerName) {
switch (providerName) {
case AIProviderName.ANTHROPIC:
return null; // Anthropic doesn't have a public health endpoint
case AIProviderName.OPENAI:
return "https://api.openai.com/v1/models";
case AIProviderName.GOOGLE_AI:
return null; // No public health endpoint
case AIProviderName.VERTEX:
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 this.getOllamaTagsUrl();
default:
return null;
}
}
/**
* Provider-specific configuration checks
*/
static async checkProviderSpecificConfig(providerName, healthStatus, timeout) {
switch (providerName) {
case AIProviderName.VERTEX:
await this.checkVertexAIConfig(healthStatus);
break;
case AIProviderName.BEDROCK:
await this.checkBedrockConfig(healthStatus);
break;
case AIProviderName.AZURE:
await this.checkAzureConfig(healthStatus);
break;
case AIProviderName.LITELLM:
await this.checkLiteLLMConfig(healthStatus, timeout);
break;
case AIProviderName.OLLAMA:
await this.checkOllamaConfig(healthStatus, timeout);
break;
}
}
/**
* Check Vertex AI configuration
*/
static async checkVertexAIConfig(healthStatus) {
logger.debug("Starting Vertex AI health check");
const projectId = this.getVertexProjectId();
if (!projectId) {
healthStatus.configurationIssues.push("Google Cloud project ID not set");
healthStatus.recommendations.push("Set one of: GOOGLE_VERTEX_PROJECT, GOOGLE_CLOUD_PROJECT_ID, GOOGLE_PROJECT_ID, or GOOGLE_CLOUD_PROJECT");
}
const hasValidAuth = await this.checkVertexAuthentication(healthStatus);
if (projectId && hasValidAuth) {
healthStatus.isConfigured = true;
logger.debug("Vertex AI health check PASSED");
}
else {
logger.debug("Vertex AI health check FAILED");
}
}
/**
* Get Vertex AI project ID from environment variables
*/
static getVertexProjectId() {
return (process.env.GOOGLE_PROJECT_ID ||
process.env.GOOGLE_CLOUD_PROJECT_ID ||
process.env.GOOGLE_VERTEX_PROJECT ||
process.env.GOOGLE_CLOUD_PROJECT ||
process.env.VERTEX_PROJECT_ID);
}
/**
* Check Vertex AI authentication
*/
static async checkVertexAuthentication(healthStatus) {
let hasValidAuth = false;
if (process.env.GOOGLE_APPLICATION_CREDENTIALS) {
hasValidAuth = await this.checkGoogleApplicationCredentials(healthStatus);
}
if (!hasValidAuth) {
hasValidAuth = this.checkIndividualGoogleCredentials(healthStatus);
}
if (!hasValidAuth) {
healthStatus.configurationIssues.push("Google Cloud authentication not configured or credentials file missing");
healthStatus.recommendations.push("Set either GOOGLE_APPLICATION_CREDENTIALS (valid file path), GOOGLE_SERVICE_ACCOUNT_KEY (base64), or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
}
return hasValidAuth;
}
/**
* Check Google Application Credentials file
*/
static async checkGoogleApplicationCredentials(healthStatus) {
const credentialsPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
if (!credentialsPath) {
healthStatus.warning =
"GOOGLE_APPLICATION_CREDENTIALS environment variable not set";
return false;
}
try {
const { promises: fs } = await import("fs");
await fs.access(credentialsPath);
const fileName = basename(credentialsPath);
const jsonFilePattern = /\.json(\.\w+)?$/;
if (!jsonFilePattern.test(fileName)) {
healthStatus.warning =
"GOOGLE_APPLICATION_CREDENTIALS should point to a JSON file";
}
healthStatus.hasApiKey = true;
return true;
}
catch {
healthStatus.warning = `GOOGLE_APPLICATION_CREDENTIALS file does not exist: ${credentialsPath}`;
return false;
}
}
/**
* Check individual Google credentials
*/
static checkIndividualGoogleCredentials(healthStatus) {
const hasServiceAccountKey = !!process.env.GOOGLE_SERVICE_ACCOUNT_KEY;
const hasIndividualCredentials = !!(process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
process.env.GOOGLE_AUTH_PRIVATE_KEY);
if (hasServiceAccountKey || hasIndividualCredentials) {
healthStatus.hasApiKey = true;
return true;
}
return false;
}
/**
* Check AWS Bedrock configuration
*/
static async checkBedrockConfig(healthStatus) {
logger.debug("Starting AWS Bedrock comprehensive health check");
this.checkAWSRegion(healthStatus);
this.checkAWSCredentials(healthStatus);
this.checkBedrockModels(healthStatus);
this.checkBedrockEndpoint(healthStatus);
if (healthStatus.configurationIssues.length === 0) {
healthStatus.hasApiKey = true;
logger.debug("AWS Bedrock configuration appears valid");
}
}
/**
* Check AWS region configuration
*/
static checkAWSRegion(healthStatus) {
const awsRegion = process.env.AWS_REGION;
const validBedrockRegions = [
"us-east-1",
"us-west-2",
"ap-southeast-1",
"ap-northeast-1",
"eu-central-1",
"eu-west-1",
"ap-south-1",
];
if (!awsRegion) {
healthStatus.configurationIssues.push("AWS_REGION not set");
healthStatus.recommendations.push(`Set AWS_REGION to a Bedrock-supported region: ${validBedrockRegions.join(", ")}`);
}
else if (!validBedrockRegions.includes(awsRegion)) {
healthStatus.configurationIssues.push(`AWS_REGION '${awsRegion}' may not support all Bedrock models`);
healthStatus.recommendations.push(`Consider using a primary Bedrock region: ${validBedrockRegions.slice(0, 3).join(", ")}`);
}
}
/**
* Check AWS credentials
*/
static checkAWSCredentials(healthStatus) {
const awsAccessKeyId = process.env.AWS_ACCESS_KEY_ID;
const awsSecretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
const awsProfile = process.env.AWS_PROFILE;
if (!awsAccessKeyId && !awsProfile) {
healthStatus.configurationIssues.push("No AWS credentials found");
healthStatus.recommendations.push("Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, or configure AWS_PROFILE");
}
else if (awsAccessKeyId && !awsSecretAccessKey) {
healthStatus.configurationIssues.push("AWS_ACCESS_KEY_ID set but AWS_SECRET_ACCESS_KEY missing");
healthStatus.recommendations.push("Set AWS_SECRET_ACCESS_KEY to match your AWS_ACCESS_KEY_ID");
}
}
/**
* Check Bedrock models
*/
static checkBedrockModels(healthStatus) {
const bedrockModel = process.env.BEDROCK_MODEL || process.env.BEDROCK_MODEL_ID;
const supportedModels = [
BedrockModels.CLAUDE_3_SONNET,
BedrockModels.CLAUDE_3_HAIKU,
BedrockModels.CLAUDE_3_5_SONNET,
"anthropic.claude-v2:1",
"amazon.titan-text-express-v1",
];
if (!bedrockModel) {
healthStatus.recommendations.push(`Set BEDROCK_MODEL or BEDROCK_MODEL_ID for faster startup (e.g., ${BedrockModels.CLAUDE_3_SONNET})`);
}
else if (!supportedModels.includes(bedrockModel)) {
healthStatus.recommendations.push(`Consider using a popular Bedrock model: ${supportedModels.slice(0, 3).join(", ")}`);
}
}
/**
* Check Bedrock endpoint
*/
static checkBedrockEndpoint(healthStatus) {
const bedrockEndpoint = process.env.BEDROCK_ENDPOINT_URL;
if (bedrockEndpoint && !bedrockEndpoint.startsWith("https://")) {
healthStatus.configurationIssues.push("BEDROCK_ENDPOINT_URL should use HTTPS");
healthStatus.recommendations.push("Update BEDROCK_ENDPOINT_URL to use HTTPS protocol");
}
}
/**
* Check Azure OpenAI configuration
*/
static async checkAzureConfig(healthStatus) {
const azureEndpoint = process.env.AZURE_OPENAI_ENDPOINT;
if (azureEndpoint && !azureEndpoint.startsWith("https://")) {
healthStatus.configurationIssues.push("Invalid AZURE_OPENAI_ENDPOINT format");
healthStatus.recommendations.push("Set AZURE_OPENAI_ENDPOINT to a valid URL (e.g., https://your-resource.openai.azure.com/)");
}
// Check for deployment name using the SAME logic as the Azure provider
const deploymentName = process.env.AZURE_OPENAI_MODEL ||
process.env.AZURE_OPENAI_DEPLOYMENT ||
process.env.AZURE_OPENAI_DEPLOYMENT_ID;
if (!deploymentName) {
healthStatus.configurationIssues.push("No Azure deployment specified");
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) {
const normalizedRequestedModel = requestedModel.trim();
const requiresExactMatch = /@/.test(normalizedRequestedModel);
return availableModels.some((model) => model === normalizedRequestedModel ||
(!requiresExactMatch &&
(model.startsWith(`${normalizedRequestedModel}:`) ||
model.startsWith(`${normalizedRequestedModel}@`))));
}
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, timeout = this.DEFAULT_TIMEOUT) {
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,
});
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, timeout = this.DEFAULT_TIMEOUT) {
const ollamaBase = this.getOllamaBaseUrl();
if (!ollamaBase.startsWith("http")) {
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,
});
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
*/
static getCommonModelsForProvider(providerName) {
switch (providerName) {
case AIProviderName.ANTHROPIC:
return [
AnthropicModels.CLAUDE_3_5_SONNET,
AnthropicModels.CLAUDE_3_HAIKU,
AnthropicModels.CLAUDE_3_OPUS,
];
case AIProviderName.OPENAI:
return [
OpenAIModels.GPT_4O,
OpenAIModels.GPT_4O_MINI,
OpenAIModels.GPT_3_5_TURBO,
];
case AIProviderName.GOOGLE_AI:
return [
GoogleAIModels.GEMINI_1_5_PRO,
GoogleAIModels.GEMINI_1_5_FLASH,
GoogleAIModels.GEMINI_2_5_PRO,
];
case AIProviderName.VERTEX:
return [
// Google models (via vertex provider)
GoogleAIModels.GEMINI_2_5_PRO,
GoogleAIModels.GEMINI_2_5_FLASH,
GoogleAIModels.GEMINI_2_5_FLASH_LITE,
GoogleAIModels.GEMINI_2_0_FLASH_001,
GoogleAIModels.GEMINI_1_5_PRO,
GoogleAIModels.GEMINI_1_5_FLASH,
// Anthropic models (via vertexAnthropic provider)
"claude-sonnet-4@20250514",
"claude-opus-4@20250514",
AnthropicModels.CLAUDE_3_5_SONNET,
AnthropicModels.CLAUDE_3_5_HAIKU,
AnthropicModels.CLAUDE_3_SONNET,
AnthropicModels.CLAUDE_3_HAIKU,
AnthropicModels.CLAUDE_3_OPUS,
];
case AIProviderName.BEDROCK:
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.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 [];
}
}
/**
* Get cached health status if still valid
*/
static getCachedHealth(providerName, maxAge) {
const cached = this.healthCache.get(providerName);
if (!cached) {
return null;
}
const age = Date.now() - cached.timestamp;
if (age > maxAge) {
this.healthCache.delete(providerName);
return null;
}
return cached.status;
}
/**
* Check if Vertex AI supports Anthropic models (dual provider architecture)
*/
static async checkVertexAnthropicSupport() {
const result = {
isSupported: false,
hasCreateVertexAnthropic: false,
hasCorrectTypes: false,
hasValidProject: false,
hasRegionalSupport: false,
hasNetworkAccess: false,
hasAnthropicModels: false,
authentication: {
isValid: false,
method: "none",
issues: [],
},
projectConfiguration: {
isValid: false,
projectId: undefined,
region: undefined,
issues: [],
},
modelSupport: {
availableModels: [],
recommendedModels: [
"claude-sonnet-4@20250514",
"claude-opus-4@20250514",
"claude-3-5-sonnet-20241022",
"claude-3-5-haiku-20241022",
"claude-3-sonnet-20240229",
"claude-3-haiku-20240307",
],
deprecatedModels: [
"claude-3-opus-20240229", // Still available but newer versions preferred
],
},
recommendations: [],
troubleshooting: [],
};
logger.debug("Starting comprehensive Vertex Anthropic support verification");
try {
// 1. Check SDK module availability
logger.debug("Checking @anthropic-ai/vertex-sdk module availability");
const anthropicModule = await import("@anthropic-ai/vertex-sdk");
result.hasCreateVertexAnthropic =
typeof anthropicModule.AnthropicVertex === "function";
result.hasCorrectTypes = true; // Types are bundled with the class
if (!result.hasCreateVertexAnthropic) {
result.troubleshooting.push("📦 Install @anthropic-ai/vertex-sdk for Claude on Vertex AI support", "🔄 Run: npm install @anthropic-ai/vertex-sdk", "📖 See: https://docs.anthropic.com/en/api/claude-on-vertex-ai");
return result;
}
logger.debug("SDK module verified successfully");
// 2. Comprehensive Authentication Validation
logger.debug("Starting authentication validation");
result.authentication = await this.validateVertexAuthentication();
if (!result.authentication.isValid) {
result.troubleshooting.push("🔐 Fix authentication configuration:", " Option 1: Set GOOGLE_APPLICATION_CREDENTIALS to valid service account file", " Option 2: Set individual env vars: GOOGLE_AUTH_CLIENT_EMAIL, GOOGLE_AUTH_PRIVATE_KEY", "📖 See: https://cloud.google.com/docs/authentication/provide-credentials-adc");
}
// 3. Project Configuration Validation
logger.debug("Starting project configuration validation");
result.projectConfiguration =
await this.validateVertexProjectConfiguration();
result.hasValidProject = result.projectConfiguration.isValid;
if (!result.hasValidProject) {
result.troubleshooting.push("🏗️ Fix project configuration:", " Set GOOGLE_VERTEX_PROJECT or GOOGLE_CLOUD_PROJECT environment variable", " Ensure project exists and has Vertex AI API enabled", "📖 See: https://console.cloud.google.com/apis/library/aiplatform.googleapis.com");
}
// 4. Regional Support Validation
logger.debug("Starting regional support validation");
result.hasRegionalSupport = await this.checkVertexRegionalSupport(result.projectConfiguration.region);
if (!result.hasRegionalSupport) {
result.troubleshooting.push("🌍 Regional support issues:", " Anthropic models may not be available in your region", " Try regions: us-central1, us-east4, europe-west1, asia-southeast1", " Set GOOGLE_CLOUD_LOCATION environment variable");
}
// 5. Network Connectivity Check (non-blocking)
logger.debug("Starting network connectivity check");
result.hasNetworkAccess = await this.checkVertexNetworkConnectivity(result.projectConfiguration.region || "us-central1");
if (!result.hasNetworkAccess) {
result.troubleshooting.push("🌐 Network connectivity issues:", " Check proxy configuration if behind corporate firewall", " Verify DNS resolution for *.googleapis.com", " Ensure firewall allows HTTPS to Google Cloud endpoints");
}
// 6. Anthropic Model Integration Check
logger.debug("Starting Anthropic model integration check");
result.hasAnthropicModels = await this.checkAnthropicModelIntegration(result.projectConfiguration.projectId, result.projectConfiguration.region);
if (!result.hasAnthropicModels) {
result.troubleshooting.push("🤖 Anthropic model integration issues:", " Enable Anthropic integration in Google Cloud Console", " Navigate to: Vertex AI > Model Garden > Anthropic", " Accept terms and enable Claude model access", "📖 See: https://console.cloud.google.com/vertex-ai/publishers/anthropic");
}
// Calculate overall support status
result.isSupported =
result.hasCreateVertexAnthropic &&
result.authentication.isValid &&
result.hasValidProject &&
result.hasRegionalSupport;
// Note: Network and model integration are nice-to-have but not blocking
// Generate comprehensive recommendations
if (result.isSupported) {
result.recommendations.push("✅ Vertex Anthropic support is fully configured", "✅ Claude models are available via vertexAnthropic provider", `✅ Authentication: ${result.authentication.method}`, `✅ Project: ${result.projectConfiguration.projectId}`, `✅ Region: ${result.projectConfiguration.region}`);
if (result.hasNetworkAccess) {
result.recommendations.push("✅ Network connectivity verified");
}
else {
result.recommendations.push("⚠️ Network connectivity not verified (may still work)");
}
if (result.hasAnthropicModels) {
result.recommendations.push("✅ Anthropic model integration verified");
}
else {
result.recommendations.push("⚠️ Anthropic model integration not verified");
}
result.recommendations.push("", "🎯 Recommended Claude models:", ...result.modelSupport.recommendedModels.map((model) => ` • ${model}`), "", "📚 Usage example:", ' const vertex = new GoogleVertexProvider("claude-3-5-sonnet-20241022")', ' const result = await vertex.generate("Hello, Claude!")');
logger.info("Vertex Anthropic support verification: FULLY_SUPPORTED");
}
else {
const missingComponents = [];
if (!result.hasCreateVertexAnthropic) {
missingComponents.push("SDK module");
}
if (!result.authentication.isValid) {
missingComponents.push("authentication");
}
if (!result.hasValidProject) {
missingComponents.push("project configuration");
}
if (!result.hasRegionalSupport) {
missingComponents.push("regional support");
}
result.recommendations.push(`⚠️ Vertex Anthropic support partially available`, `❌ Missing: ${missingComponents.join(", ")}`, "", "🔧 Quick fixes needed:");
result.recommendations.push(...result.troubleshooting);
logger.warn("Vertex Anthropic support verification: PARTIALLY_SUPPORTED", {
missingComponents,
hasBasicSupport: result.hasCreateVertexAnthropic,
authenticationValid: result.authentication.isValid,
projectValid: result.hasValidProject,
});
}
}
catch (error) {
logger.error("Vertex Anthropic support check failed", {
error: error instanceof Error ? error.message : String(error),
stack: error instanceof Error ? error.stack : undefined,
});
result.recommendations.push("❌ Comprehensive Anthropic support check failed", `🐛 Error: ${error instanceof Error ? error.message : String(error)}`, "", "🔧 Troubleshooting steps:", "1. Verify @google-cloud/vertexai and @anthropic-ai/vertex-sdk are properly installed", "2. Verify Google Cloud authentication setup", "3. Check project ID and region configuration", "4. Enable Vertex AI API in Google Cloud Console", "5. Enable Anthropic integration in Vertex AI Model Garden");
}
return result;
}
/**
* Validate Vert