@juspay/neurolink 7.6.0 → 7.7.0

package/dist/lib/utils/providerUtils.js

@@ -4,6 +4,7 @@
  */
 import { AIProviderFactory } from "../core/factory.js";
 import { logger } from "./logger.js";
+import { ProviderHealthChecker } from "./providerHealth.js";
 /**
  * Get the best available provider based on real-time availability checks
  * Enhanced version consolidated from providerUtils-fixed.ts
@@ -11,12 +12,39 @@ import { logger } from "./logger.js";
  * @returns The best provider name to use
  */
 export async function getBestProvider(requestedProvider) {
-    // 🔧 FIX: Check for explicit default provider in env
+    // Check requested provider FIRST - explicit user choice overrides defaults
+    if (requestedProvider && requestedProvider !== "auto") {
+        // For explicit provider requests, check health first
+        try {
+            const health = await ProviderHealthChecker.checkProviderHealth(requestedProvider, { includeConnectivityTest: false, cacheResults: true });
+            if (health.isHealthy) {
+                logger.debug(`[getBestProvider] Using healthy explicitly requested provider: ${requestedProvider}`);
+                return requestedProvider;
+            }
+            else {
+                logger.warn(`[getBestProvider] Requested provider ${requestedProvider} is unhealthy, finding alternative`, { error: health.error });
+            }
+        }
+        catch (error) {
+            logger.warn(`[getBestProvider] Health check failed for ${requestedProvider}, using anyway`, { error: error instanceof Error ? error.message : String(error) });
+            return requestedProvider; // Return anyway for explicit requests
+        }
+    }
+    // Use health checker to get best available provider
+    const healthyProvider = await ProviderHealthChecker.getBestHealthyProvider();
+    if (healthyProvider) {
+        logger.debug(`[getBestProvider] Selected healthy provider: ${healthyProvider}`);
+        return healthyProvider;
+    }
+    // Fallback to legacy provider checking if health system fails
+    logger.warn("[getBestProvider] Health system failed, falling back to legacy checking");
+    // Check for explicit default provider in env (only when no provider requested)
     if (process.env.DEFAULT_PROVIDER &&
         (await isProviderAvailable(process.env.DEFAULT_PROVIDER))) {
+        logger.debug(`[getBestProvider] Using default provider from env: ${process.env.DEFAULT_PROVIDER}`);
         return process.env.DEFAULT_PROVIDER;
     }
-    // 🔧 FIX: Special case for Ollama - prioritize local when available
+    // Special case for Ollama - prioritize local when available
     if (process.env.OLLAMA_BASE_URL && process.env.OLLAMA_MODEL) {
         try {
             if (await isProviderAvailable("ollama")) {
@@ -28,26 +56,26 @@ export async function getBestProvider(requestedProvider) {
             // Fall through to cloud providers
         }
     }
+    /**
+     * 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.
+     * - 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.
+     * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
+     */
     const providers = [
-        "google-ai",
+        "vertex", // Prioritize Google Cloud AI (Vertex) first
+        "google-ai", // Google AI ecosystem support
+        "openai", // Reliable with broad model support
         "anthropic",
-        "openai",
-        "mistral",
-        "vertex",
+        "bedrock",
         "azure",
+        "mistral",
         "huggingface",
-        "bedrock",
         "ollama", // Keep as fallback
     ];
-    if (requestedProvider && requestedProvider !== "auto") {
-        if (await isProviderAvailable(requestedProvider)) {
-            logger.debug(`[getBestProvider] Using requested provider: ${requestedProvider}`);
-            return requestedProvider;
-        }
-        else {
-            logger.warn(`[getBestProvider] Requested provider '${requestedProvider}' is not available. Falling back to auto-selection.`);
-        }
-    }
     for (const provider of providers) {
         if (await isProviderAvailable(provider)) {
             logger.debug(`[getBestProvider] Selected provider: ${provider}`);
@@ -92,9 +120,236 @@ async function isProviderAvailable(providerName) {
         return false;
     }
 }
+/**
+ * Google Cloud Project ID validation regex
+ * Format requirements:
+ * - Must start with a lowercase letter
+ * - Can contain lowercase letters, numbers, and hyphens
+ * - Must end with a lowercase letter or number
+ * - Total length must be 6-30 characters
+ */
+const GOOGLE_CLOUD_PROJECT_ID_REGEX = /^[a-z][a-z0-9-]{4,28}[a-z0-9]$/;
+/**
+ * Validate environment variable values for a provider
+ * Addresses GitHub Copilot comment about adding environment variable validation
+ * @param provider - Provider name to validate
+ * @returns Validation result with detailed information
+ */
+export function validateProviderEnvVars(provider) {
+    const result = {
+        isValid: true,
+        missingVars: [],
+        invalidVars: [],
+        warnings: [],
+    };
+    switch (provider.toLowerCase()) {
+        case "bedrock":
+        case "amazon":
+        case "aws":
+            validateAwsCredentials(result);
+            break;
+        case "vertex":
+        case "googlevertex":
+        case "google":
+        case "gemini":
+            validateVertexCredentials(result);
+            break;
+        case "openai":
+        case "gpt":
+            validateOpenAICredentials(result);
+            break;
+        case "anthropic":
+        case "claude":
+            validateAnthropicCredentials(result);
+            break;
+        case "azure":
+        case "azureOpenai":
+            validateAzureCredentials(result);
+            break;
+        case "google-ai":
+        case "google-studio":
+            validateGoogleAICredentials(result);
+            break;
+        case "huggingface":
+        case "hugging-face":
+        case "hf":
+            validateHuggingFaceCredentials(result);
+            break;
+        case "mistral":
+        case "mistral-ai":
+        case "mistralai":
+            validateMistralCredentials(result);
+            break;
+        case "ollama":
+        case "local":
+        case "local-ollama":
+            // Ollama doesn't require environment variables
+            break;
+        case "litellm":
+            // LiteLLM validation can be added if needed
+            break;
+        default:
+            result.isValid = false;
+            result.warnings.push(`Unknown provider: ${provider}`);
+    }
+    result.isValid =
+        result.missingVars.length === 0 && result.invalidVars.length === 0;
+    return result;
+}
+/**
+ * Validate AWS credentials with flexible validation
+ * Note: AWS credential formats can vary, so validation is kept reasonably flexible
+ */
+function validateAwsCredentials(result) {
+    const accessKeyId = process.env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = process.env.AWS_SECRET_ACCESS_KEY;
+    const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+    if (!accessKeyId) {
+        result.missingVars.push("AWS_ACCESS_KEY_ID");
+    }
+    else if (!/^[A-Z0-9]{16,}$/.test(accessKeyId)) {
+        // Flexible validation: at least 16 uppercase alphanumeric characters
+        result.invalidVars.push("AWS_ACCESS_KEY_ID (should be uppercase alphanumeric characters, typically 20 chars)");
+    }
+    if (!secretAccessKey) {
+        result.missingVars.push("AWS_SECRET_ACCESS_KEY");
+    }
+    else if (!/^[A-Za-z0-9+/]{30,}$/.test(secretAccessKey)) {
+        // Flexible validation: at least 30 base64 characters (can vary in length)
+        result.invalidVars.push("AWS_SECRET_ACCESS_KEY (should be base64 characters, typically 40+ chars)");
+    }
+    if (!region) {
+        result.warnings.push("AWS_REGION not set, will use default region");
+    }
+}
+/**
+ * Validate Google Vertex credentials
+ */
+function validateVertexCredentials(result) {
+    const projectId = process.env.GOOGLE_CLOUD_PROJECT_ID ||
+        process.env.VERTEX_PROJECT_ID ||
+        process.env.GOOGLE_VERTEX_PROJECT ||
+        process.env.GOOGLE_CLOUD_PROJECT;
+    const hasCredentials = process.env.GOOGLE_APPLICATION_CREDENTIALS ||
+        process.env.GOOGLE_SERVICE_ACCOUNT_KEY ||
+        (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+            process.env.GOOGLE_AUTH_PRIVATE_KEY);
+    if (!projectId) {
+        result.missingVars.push("GOOGLE_CLOUD_PROJECT_ID (or variant)");
+    }
+    else if (!GOOGLE_CLOUD_PROJECT_ID_REGEX.test(projectId)) {
+        result.invalidVars.push("Project ID format invalid (must be 6-30 lowercase letters, digits, hyphens)");
+    }
+    if (!hasCredentials) {
+        result.missingVars.push("Google credentials (GOOGLE_APPLICATION_CREDENTIALS or explicit auth)");
+    }
+    if (process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
+        !isValidEmail(process.env.GOOGLE_AUTH_CLIENT_EMAIL)) {
+        result.invalidVars.push("GOOGLE_AUTH_CLIENT_EMAIL (invalid email format)");
+    }
+}
+/**
+ * Validate OpenAI credentials
+ */
+function validateOpenAICredentials(result) {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("OPENAI_API_KEY");
+    }
+    else if (!/^sk-[A-Za-z0-9]{48,}$/.test(apiKey)) {
+        result.invalidVars.push("OPENAI_API_KEY (should start with 'sk-' followed by 48+ characters)");
+    }
+}
+/**
+ * Validate Anthropic credentials
+ */
+function validateAnthropicCredentials(result) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("ANTHROPIC_API_KEY");
+    }
+    else if (!/^sk-ant-[A-Za-z0-9-_]{95,}$/.test(apiKey)) {
+        result.invalidVars.push("ANTHROPIC_API_KEY (should start with 'sk-ant-' followed by 95+ characters)");
+    }
+}
+/**
+ * Validate Azure credentials
+ */
+function validateAzureCredentials(result) {
+    const apiKey = process.env.AZURE_OPENAI_API_KEY;
+    const endpoint = process.env.AZURE_OPENAI_ENDPOINT;
+    if (!apiKey) {
+        result.missingVars.push("AZURE_OPENAI_API_KEY");
+    }
+    else if (!/^[a-f0-9]{32}$/.test(apiKey)) {
+        result.invalidVars.push("AZURE_OPENAI_API_KEY (should be 32 hexadecimal characters)");
+    }
+    if (!endpoint) {
+        result.missingVars.push("AZURE_OPENAI_ENDPOINT");
+    }
+    else if (!isValidUrl(endpoint)) {
+        result.invalidVars.push("AZURE_OPENAI_ENDPOINT (should be a valid HTTPS URL)");
+    }
+}
+/**
+ * Validate Google AI credentials
+ */
+function validateGoogleAICredentials(result) {
+    const apiKey = process.env.GOOGLE_AI_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("GOOGLE_AI_API_KEY (or GOOGLE_GENERATIVE_AI_API_KEY)");
+    }
+    else if (!/^[A-Za-z0-9_-]{39}$/.test(apiKey)) {
+        result.invalidVars.push("GOOGLE_AI_API_KEY (should be 39 alphanumeric characters with dashes/underscores)");
+    }
+}
+/**
+ * Validate HuggingFace credentials
+ */
+function validateHuggingFaceCredentials(result) {
+    const apiKey = process.env.HUGGINGFACE_API_KEY || process.env.HF_TOKEN;
+    if (!apiKey) {
+        result.missingVars.push("HUGGINGFACE_API_KEY (or HF_TOKEN)");
+    }
+    else if (!/^hf_[A-Za-z0-9]{37}$/.test(apiKey)) {
+        result.invalidVars.push("HUGGINGFACE_API_KEY (should start with 'hf_' followed by 37 characters)");
+    }
+}
+/**
+ * Validate Mistral credentials
+ */
+function validateMistralCredentials(result) {
+    const apiKey = process.env.MISTRAL_API_KEY;
+    if (!apiKey) {
+        result.missingVars.push("MISTRAL_API_KEY");
+    }
+    else if (!/^[A-Za-z0-9]{32,}$/.test(apiKey)) {
+        result.invalidVars.push("MISTRAL_API_KEY (should be 32+ alphanumeric characters)");
+    }
+}
+/**
+ * Helper function to validate email format
+ */
+function isValidEmail(email) {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+}
+/**
+ * Helper function to validate URL format
+ */
+function isValidUrl(url) {
+    try {
+        const parsedUrl = new URL(url);
+        return parsedUrl.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Check if a provider has the minimum required environment variables
  * NOTE: This only checks if variables exist, not if they're valid
+ * For validation, use validateProviderEnvVars instead
  * @param provider - Provider name to check
  * @returns True if the provider has required environment variables
  */

package/dist/lib/utils/timeout.js

@@ -82,7 +82,7 @@ export const DEFAULT_TIMEOUTS = {
         openai: "30s", // OpenAI typically responds quickly
         bedrock: "45s", // AWS can be slower, especially for cold starts
         vertex: "60s", // Google Cloud can be slower
-        anthropic: "30s", // Direct Anthropic API is fast
+        anthropic: "60s", // Increased timeout for Anthropic API stability
         azure: "30s", // Azure OpenAI similar to OpenAI
         "google-ai": "30s", // Google AI Studio is fast
         huggingface: "2m", // Open source models vary significantly

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

@@ -0,0 +1,33 @@
+/**
+ * Provider-specific token limit utilities
+ * Provides safe maxTokens values based on provider and model capabilities
+ */
+import { PROVIDER_MAX_TOKENS } from "../core/constants.js";
+/**
+ * Get the safe maximum tokens for a provider and model
+ */
+export declare function getSafeMaxTokens(provider: keyof typeof PROVIDER_MAX_TOKENS | string, model?: string, requestedMaxTokens?: number): number;
+/**
+ * Validate if maxTokens is safe for a provider/model combination
+ */
+export declare function validateMaxTokens(provider: keyof typeof PROVIDER_MAX_TOKENS | string, model?: string, maxTokens?: number): {
+    isValid: boolean;
+    recommendedMaxTokens: number;
+    warning?: string;
+};
+/**
+ * Get provider-specific token limit recommendations
+ */
+export declare function getTokenLimitRecommendations(provider: string): {
+    conservative: number;
+    balanced: number;
+    maximum: number;
+    models: Record<string, number>;
+};
+/**
+ * Get all provider limits summary
+ */
+export declare function getAllProviderLimits(): Record<string, {
+    default: number;
+    models: Record<string, number>;
+}>;

package/dist/lib/utils/tokenLimits.js

@@ -0,0 +1,118 @@
+/**
+ * Provider-specific token limit utilities
+ * Provides safe maxTokens values based on provider and model capabilities
+ */
+import { PROVIDER_MAX_TOKENS, DEFAULT_MAX_TOKENS } from "../core/constants.js";
+import { logger } from "./logger.js";
+/**
+ * Get the safe maximum tokens for a provider and model
+ */
+export function getSafeMaxTokens(provider, model, requestedMaxTokens) {
+    // Get provider-specific limits
+    const providerLimits = PROVIDER_MAX_TOKENS[provider];
+    if (!providerLimits) {
+        logger.warn(`Unknown provider ${provider}, using default maxTokens limit`);
+        return Math.min(requestedMaxTokens || DEFAULT_MAX_TOKENS, PROVIDER_MAX_TOKENS.default);
+    }
+    // Get model-specific limit or provider default
+    let maxLimit;
+    if (model &&
+        typeof providerLimits === "object" &&
+        providerLimits[model]) {
+        maxLimit = providerLimits[model];
+    }
+    else if (typeof providerLimits === "object" &&
+        providerLimits.default) {
+        maxLimit = providerLimits.default;
+    }
+    else if (typeof providerLimits === "number") {
+        maxLimit = providerLimits;
+    }
+    else {
+        maxLimit = PROVIDER_MAX_TOKENS.default;
+    }
+    // If no specific maxTokens requested, return the provider limit
+    if (!requestedMaxTokens) {
+        return maxLimit;
+    }
+    // If requested maxTokens exceeds the limit, use the limit and warn
+    if (requestedMaxTokens > maxLimit) {
+        logger.warn(`Requested maxTokens ${requestedMaxTokens} exceeds ${provider}/${model} limit of ${maxLimit}. Using ${maxLimit} instead.`);
+        return maxLimit;
+    }
+    // Use the requested value if it's within limits
+    return requestedMaxTokens;
+}
+/**
+ * Validate if maxTokens is safe for a provider/model combination
+ */
+export function validateMaxTokens(provider, model, maxTokens) {
+    const safeMaxTokens = getSafeMaxTokens(provider, model, maxTokens);
+    if (!maxTokens) {
+        return {
+            isValid: true,
+            recommendedMaxTokens: safeMaxTokens,
+        };
+    }
+    const isValid = maxTokens <= safeMaxTokens;
+    return {
+        isValid,
+        recommendedMaxTokens: safeMaxTokens,
+        warning: !isValid
+            ? `maxTokens ${maxTokens} exceeds ${provider}/${model} limit of ${safeMaxTokens}`
+            : undefined,
+    };
+}
+/**
+ * Get provider-specific token limit recommendations
+ */
+export function getTokenLimitRecommendations(provider) {
+    const providerLimits = PROVIDER_MAX_TOKENS[provider];
+    if (!providerLimits || typeof providerLimits === "number") {
+        const limit = typeof providerLimits === "number"
+            ? providerLimits
+            : PROVIDER_MAX_TOKENS.default;
+        return {
+            conservative: Math.floor(limit * 0.5),
+            balanced: Math.floor(limit * 0.75),
+            maximum: limit,
+            models: {},
+        };
+    }
+    const modelLimits = Object.entries(providerLimits)
+        .filter(([key]) => key !== "default")
+        .map(([_, limit]) => limit);
+    const maxLimit = Math.max(...modelLimits, providerLimits.default || 0);
+    const minLimit = Math.min(...modelLimits, providerLimits.default || maxLimit);
+    return {
+        conservative: Math.floor(minLimit * 0.5),
+        balanced: Math.floor(((minLimit + maxLimit) / 2) * 0.75),
+        maximum: maxLimit,
+        models: Object.fromEntries(Object.entries(providerLimits).filter(([key]) => key !== "default")),
+    };
+}
+/**
+ * Get all provider limits summary
+ */
+export function getAllProviderLimits() {
+    const result = {};
+    for (const [provider, limits] of Object.entries(PROVIDER_MAX_TOKENS)) {
+        if (provider === "default") {
+            continue;
+        }
+        if (typeof limits === "number") {
+            result[provider] = {
+                default: limits,
+                models: {},
+            };
+        }
+        else {
+            const { default: defaultLimit, ...models } = limits;
+            result[provider] = {
+                default: defaultLimit || PROVIDER_MAX_TOKENS.default,
+                models: models,
+            };
+        }
+    }
+    return result;
+}

package/dist/mcp/factory.d.ts

@@ -1,7 +1,7 @@
 /**
  * NeuroLink MCP Server Factory
  * Factory-First Architecture: MCP servers create tools for internal orchestration
- * Compatible with Lighthouse MCP patterns for seamless migration
+ * Compatible with MCP patterns for seamless integration
  */
 import { z } from "zod";
 import type { ExecutionContext } from "./contracts/mcpContract.js";
@@ -11,7 +11,7 @@ import type { ExecutionContext } from "./contracts/mcpContract.js";
 export type MCPServerCategory = "aiProviders" | "frameworks" | "development" | "business" | "content" | "data" | "integrations" | "automation" | "analysis" | "custom";
 /**
  * Tool execution context - Rich context passed to every tool execution
- * Following Lighthouse's pattern for rich tool context
+ * Following standard patterns for rich tool context
  * Extends ExecutionContext for compatibility
  */
 export interface NeuroLinkExecutionContext extends ExecutionContext {
@@ -71,7 +71,7 @@ export interface ToolResult {
     };
 }
 /**
- * MCP Tool Interface - Lighthouse compatible with NeuroLink enhancements
+ * MCP Tool Interface - Standard compatible with NeuroLink enhancements
  */
 export interface NeuroLinkMCPTool {
     name: string;
@@ -86,7 +86,7 @@ export interface NeuroLinkMCPTool {
     metadata?: Record<string, unknown>;
 }
 /**
- * MCP Server Interface - Lighthouse compatible
+ * MCP Server Interface - Standard compatible
  */
 export interface NeuroLinkMCPServer {
     id: string;
@@ -118,7 +118,7 @@ export interface MCPServerConfig {
 /**
  * Create MCP Server Factory Function
  *
- * Core factory function for creating Lighthouse-compatible MCP servers.
+ * Core factory function for creating MCP servers.
  * Follows Factory-First architecture where tools are internal implementation.
  *
  * @param config Server configuration with minimal required fields

package/dist/mcp/factory.js

@@ -1,7 +1,7 @@
 /**
  * NeuroLink MCP Server Factory
  * Factory-First Architecture: MCP servers create tools for internal orchestration
- * Compatible with Lighthouse MCP patterns for seamless migration
+ * Compatible with MCP patterns for seamless integration
  */
 import { z } from "zod";
 /**
@@ -34,7 +34,7 @@ const ServerConfigSchema = z.object({
 /**
  * Create MCP Server Factory Function
  *
- * Core factory function for creating Lighthouse-compatible MCP servers.
+ * Core factory function for creating MCP servers.
  * Follows Factory-First architecture where tools are internal implementation.
  *
  * @param config Server configuration with minimal required fields

package/dist/mcp/servers/utilities/utilityServer.d.ts

@@ -1,6 +1,6 @@
 /**
  * NeuroLink Utility Server
- * Provides general utility tools following Lighthouse patterns
+ * Provides general utility tools following standard patterns
  */
 /**
  * Utility Server - General utility tools

package/dist/mcp/servers/utilities/utilityServer.js

@@ -1,6 +1,6 @@
 /**
  * NeuroLink Utility Server
- * Provides general utility tools following Lighthouse patterns
+ * Provides general utility tools following standard patterns
  */
 import { z } from "zod";
 import { createMCPServer } from "../../factory.js";

package/dist/mcp/toolRegistry.js

@@ -19,7 +19,7 @@ export class MCPToolRegistry extends MCPRegistry {
      * Register all direct tools from directAgentTools
      */
     registerDirectTools() {
-        registryLogger.info("Auto-registering direct tools...");
+        registryLogger.debug("Auto-registering direct tools...");
         for (const [toolName, toolDef] of Object.entries(directAgentTools)) {
             const toolId = `direct.${toolName}`;
             const toolInfo = {
@@ -67,7 +67,7 @@ export class MCPToolRegistry extends MCPRegistry {
             });
             registryLogger.debug(`Registered direct tool: ${toolName} as ${toolId}`);
         }
-        registryLogger.info(`Auto-registered ${Object.keys(directAgentTools).length} direct tools`);
+        registryLogger.debug(`Auto-registered ${Object.keys(directAgentTools).length} direct tools`);
     }
     /**
      * Register a server with its tools (updated signature)