@juspay/neurolink 3.0.0 → 4.0.0

package/dist/core/constants.js

@@ -0,0 +1,50 @@
+/**
+ * Central configuration constants for NeuroLink
+ * Single source of truth for all default values
+ */
+// Core AI Generation Defaults
+export const DEFAULT_MAX_TOKENS = 10000;
+export const DEFAULT_TEMPERATURE = 0.7;
+export const DEFAULT_TIMEOUT = 30000;
+// Specialized Use Case Defaults
+export const DEFAULT_EVALUATION_MAX_TOKENS = 500; // Keep evaluation fast
+export const DEFAULT_ANALYSIS_MAX_TOKENS = 800; // For analysis tools
+export const DEFAULT_DOCUMENTATION_MAX_TOKENS = 12000; // For documentation generation
+// Provider-specific configurations
+export const PROVIDER_CONFIG = {
+    evaluation: {
+        maxTokens: DEFAULT_EVALUATION_MAX_TOKENS,
+        model: "gemini-2.5-flash",
+        temperature: 0.3, // Lower temperature for consistent evaluation
+    },
+    analysis: {
+        maxTokens: DEFAULT_ANALYSIS_MAX_TOKENS,
+        temperature: 0.5,
+    },
+    documentation: {
+        maxTokens: DEFAULT_DOCUMENTATION_MAX_TOKENS,
+        temperature: 0.4,
+    },
+};
+// CLI Validation Limits
+export const CLI_LIMITS = {
+    maxTokens: {
+        min: 1,
+        max: 50000,
+        default: DEFAULT_MAX_TOKENS,
+    },
+    temperature: {
+        min: 0,
+        max: 2,
+        default: DEFAULT_TEMPERATURE,
+    },
+};
+// Environment Variable Support (for future use)
+export const ENV_DEFAULTS = {
+    maxTokens: process.env.NEUROLINK_DEFAULT_MAX_TOKENS
+        ? parseInt(process.env.NEUROLINK_DEFAULT_MAX_TOKENS, 10)
+        : DEFAULT_MAX_TOKENS,
+    temperature: process.env.NEUROLINK_DEFAULT_TEMPERATURE
+        ? parseFloat(process.env.NEUROLINK_DEFAULT_TEMPERATURE)
+        : DEFAULT_TEMPERATURE,
+};

package/dist/core/defaults.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Default value helper functions for NeuroLink
+ * Centralized logic for applying defaults across the system
+ */
+/**
+ * Apply default values to options object
+ * User-provided values take precedence over defaults
+ */
+export declare function applyDefaults(options: any): any;
+/**
+ * Get default max tokens for a specific provider
+ * Can be extended for provider-specific overrides in the future
+ */
+export declare function getDefaultMaxTokens(provider?: string): number;
+/**
+ * Get default temperature for a specific use case
+ */
+export declare function getDefaultTemperature(useCase?: string): number;

package/dist/core/defaults.js

@@ -0,0 +1,29 @@
+/**
+ * Default value helper functions for NeuroLink
+ * Centralized logic for applying defaults across the system
+ */
+import { DEFAULT_MAX_TOKENS, DEFAULT_TEMPERATURE, ENV_DEFAULTS, } from "./constants.js";
+/**
+ * Apply default values to options object
+ * User-provided values take precedence over defaults
+ */
+export function applyDefaults(options) {
+    return {
+        maxTokens: ENV_DEFAULTS.maxTokens,
+        temperature: ENV_DEFAULTS.temperature,
+        ...options, // User overrides take precedence
+    };
+}
+/**
+ * Get default max tokens for a specific provider
+ * Can be extended for provider-specific overrides in the future
+ */
+export function getDefaultMaxTokens(provider) {
+    return ENV_DEFAULTS.maxTokens;
+}
+/**
+ * Get default temperature for a specific use case
+ */
+export function getDefaultTemperature(useCase) {
+    return ENV_DEFAULTS.temperature;
+}

package/dist/core/evaluation-config.d.ts

@@ -0,0 +1,29 @@
+import type { EvaluationConfig } from "./types.js";
+/**
+ * Parse evaluation configuration from environment variables
+ */
+export declare function parseEvaluationConfig(): EvaluationConfig;
+/**
+ * Get intelligent provider fallback order
+ */
+export declare function getProviderFallbackOrder(config: EvaluationConfig): string[];
+/**
+ * Estimate evaluation cost
+ */
+export declare function estimateEvaluationCost(providerName: string, mode: string, promptLength: number, expectedResponseLength?: number): number;
+/**
+ * Validate evaluation configuration
+ */
+export declare function validateEvaluationConfig(config: EvaluationConfig): string[];
+/**
+ * Get configuration with validation and defaults
+ */
+export declare function getValidatedEvaluationConfig(): EvaluationConfig;
+/**
+ * Check if evaluation is enabled for the current configuration
+ */
+export declare function isEvaluationEnabled(): boolean;
+/**
+ * Get cost-optimized provider based on configuration
+ */
+export declare function getCostOptimizedProvider(config: EvaluationConfig): string | null;

package/dist/core/evaluation-config.js

@@ -0,0 +1,144 @@
+import { getAvailableProviders, sortProvidersByPreference, getProviderConfig, } from "./evaluation-providers.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Parse evaluation configuration from environment variables
+ */
+export function parseEvaluationConfig() {
+    return {
+        provider: process.env.NEUROLINK_EVALUATION_PROVIDER || "google-ai",
+        model: process.env.NEUROLINK_EVALUATION_MODEL || "gemini-2.5-flash",
+        mode: process.env.NEUROLINK_EVALUATION_MODE || "fast",
+        fallbackEnabled: process.env.NEUROLINK_EVALUATION_FALLBACK_ENABLED !== "false",
+        fallbackProviders: (process.env.NEUROLINK_EVALUATION_FALLBACK_PROVIDERS ||
+            "openai,anthropic,vertex,bedrock").split(","),
+        timeout: parseInt(process.env.NEUROLINK_EVALUATION_TIMEOUT || "10000"),
+        maxTokens: parseInt(process.env.NEUROLINK_EVALUATION_MAX_TOKENS || "500"),
+        temperature: parseFloat(process.env.NEUROLINK_EVALUATION_TEMPERATURE || "0.1"),
+        preferCheap: process.env.NEUROLINK_EVALUATION_PREFER_CHEAP !== "false",
+        maxCostPerEval: parseFloat(process.env.NEUROLINK_EVALUATION_MAX_COST_PER_EVAL || "0.01"),
+        retryAttempts: parseInt(process.env.NEUROLINK_EVALUATION_RETRY_ATTEMPTS || "2"),
+    };
+}
+/**
+ * Get intelligent provider fallback order
+ */
+export function getProviderFallbackOrder(config) {
+    const available = getAvailableProviders();
+    const sorted = sortProvidersByPreference(available, config.preferCheap);
+    // Start with user's preferred provider
+    const fallbackOrder = [config.provider];
+    // Add configured fallbacks
+    config.fallbackProviders.forEach((provider) => {
+        if (!fallbackOrder.includes(provider)) {
+            fallbackOrder.push(provider);
+        }
+    });
+    // Add remaining available providers
+    sorted.forEach((providerConfig) => {
+        if (!fallbackOrder.includes(providerConfig.provider)) {
+            fallbackOrder.push(providerConfig.provider);
+        }
+    });
+    logger.debug("[EvaluationConfig] Provider fallback order:", fallbackOrder);
+    return fallbackOrder;
+}
+/**
+ * Estimate evaluation cost
+ */
+export function estimateEvaluationCost(providerName, mode, promptLength, expectedResponseLength = 200) {
+    const config = getProviderConfig(providerName);
+    if (!config || !config.costPerToken) {
+        return 0;
+    }
+    const inputTokens = Math.ceil(promptLength / 4); // Rough token estimation
+    const outputTokens = expectedResponseLength / 4;
+    return (inputTokens * config.costPerToken.input +
+        outputTokens * config.costPerToken.output);
+}
+/**
+ * Validate evaluation configuration
+ */
+export function validateEvaluationConfig(config) {
+    const errors = [];
+    // Validate provider
+    if (!getProviderConfig(config.provider)) {
+        errors.push(`Invalid provider: ${config.provider}`);
+    }
+    // Validate mode
+    if (!["fast", "balanced", "quality"].includes(config.mode)) {
+        errors.push(`Invalid mode: ${config.mode}. Must be 'fast', 'balanced', or 'quality'`);
+    }
+    // Validate timeout
+    if (config.timeout <= 0 || config.timeout > 60000) {
+        errors.push(`Invalid timeout: ${config.timeout}. Must be between 1 and 60000ms`);
+    }
+    // Validate max tokens
+    if (config.maxTokens <= 0 || config.maxTokens > 4000) {
+        errors.push(`Invalid maxTokens: ${config.maxTokens}. Must be between 1 and 4000`);
+    }
+    // Validate temperature
+    if (config.temperature < 0 || config.temperature > 2) {
+        errors.push(`Invalid temperature: ${config.temperature}. Must be between 0 and 2`);
+    }
+    // Validate max cost
+    if (config.maxCostPerEval <= 0) {
+        errors.push(`Invalid maxCostPerEval: ${config.maxCostPerEval}. Must be greater than 0`);
+    }
+    // Validate retry attempts
+    if (config.retryAttempts < 0 || config.retryAttempts > 5) {
+        errors.push(`Invalid retryAttempts: ${config.retryAttempts}. Must be between 0 and 5`);
+    }
+    return errors;
+}
+/**
+ * Get configuration with validation and defaults
+ */
+export function getValidatedEvaluationConfig() {
+    const config = parseEvaluationConfig();
+    const errors = validateEvaluationConfig(config);
+    if (errors.length > 0) {
+        logger.warn("[EvaluationConfig] Configuration validation errors:", errors);
+        // Return default configuration if validation fails
+        return {
+            provider: "google-ai",
+            model: "gemini-2.5-flash",
+            mode: "fast",
+            fallbackEnabled: true,
+            fallbackProviders: ["openai", "anthropic"],
+            timeout: 10000,
+            maxTokens: 500,
+            temperature: 0.1,
+            preferCheap: true,
+            maxCostPerEval: 0.01,
+            retryAttempts: 2,
+        };
+    }
+    return config;
+}
+/**
+ * Check if evaluation is enabled for the current configuration
+ */
+export function isEvaluationEnabled() {
+    // Check if at least one provider is available
+    const available = getAvailableProviders();
+    return available.length > 0;
+}
+/**
+ * Get cost-optimized provider based on configuration
+ */
+export function getCostOptimizedProvider(config) {
+    const available = getAvailableProviders();
+    if (available.length === 0) {
+        return null;
+    }
+    const sorted = sortProvidersByPreference(available, true); // Always prefer cheap for cost optimization
+    // Find the cheapest provider that meets cost requirements
+    for (const providerConfig of sorted) {
+        const estimatedCost = estimateEvaluationCost(providerConfig.provider, config.mode, 1000);
+        if (estimatedCost <= config.maxCostPerEval) {
+            return providerConfig.provider;
+        }
+    }
+    // If no provider meets cost requirements, return the cheapest one
+    return sorted[0].provider;
+}

package/dist/core/evaluation-providers.d.ts

@@ -0,0 +1,30 @@
+import type { ProviderModelConfig } from "./types.js";
+/**
+ * Comprehensive provider configurations for evaluation
+ * All 9 NeuroLink providers with cost and performance data
+ */
+export declare const EVALUATION_PROVIDER_CONFIGS: Record<string, ProviderModelConfig>;
+/**
+ * Get provider configuration by name
+ */
+export declare function getProviderConfig(providerName: string): ProviderModelConfig | null;
+/**
+ * Get all available providers with required API keys present
+ */
+export declare function getAvailableProviders(): ProviderModelConfig[];
+/**
+ * Sort providers by preference (cost, speed, quality)
+ */
+export declare function sortProvidersByPreference(providers: ProviderModelConfig[], preferCheap?: boolean): ProviderModelConfig[];
+/**
+ * Estimate cost for a specific provider and token usage
+ */
+export declare function estimateProviderCost(providerName: string, inputTokens: number, outputTokens: number): number;
+/**
+ * Check if a provider is available (has required API keys)
+ */
+export declare function isProviderAvailable(providerName: string): boolean;
+/**
+ * Get the best available provider based on preference
+ */
+export declare function getBestAvailableProvider(preferCheap?: boolean): ProviderModelConfig | null;

package/dist/core/evaluation-providers.js

@@ -0,0 +1,187 @@
+/**
+ * Comprehensive provider configurations for evaluation
+ * All 9 NeuroLink providers with cost and performance data
+ */
+export const EVALUATION_PROVIDER_CONFIGS = {
+    "google-ai": {
+        provider: "google-ai",
+        models: {
+            fast: "gemini-2.5-flash",
+            balanced: "gemini-2.5-pro",
+            quality: "gemini-2.5-pro",
+        },
+        costPerToken: { input: 0.000075, output: 0.0003 },
+        requiresApiKey: ["GOOGLE_AI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+        performance: { speed: 3, quality: 3, cost: 3 },
+    },
+    openai: {
+        provider: "openai",
+        models: {
+            fast: "gpt-4o-mini",
+            balanced: "gpt-4o",
+            quality: "gpt-4o",
+        },
+        costPerToken: { input: 0.00015, output: 0.0006 },
+        requiresApiKey: ["OPENAI_API_KEY"],
+        performance: { speed: 2, quality: 3, cost: 2 },
+    },
+    anthropic: {
+        provider: "anthropic",
+        models: {
+            fast: "claude-3-haiku-20240307",
+            balanced: "claude-3-sonnet-20240229",
+            quality: "claude-3-opus-20240229",
+        },
+        costPerToken: { input: 0.00025, output: 0.00125 },
+        requiresApiKey: ["ANTHROPIC_API_KEY"],
+        performance: { speed: 2, quality: 3, cost: 2 },
+    },
+    vertex: {
+        provider: "vertex",
+        models: {
+            fast: "gemini-2.5-flash",
+            balanced: "gemini-2.5-pro",
+            quality: "gemini-2.5-pro",
+        },
+        costPerToken: { input: 0.000075, output: 0.0003 },
+        requiresApiKey: [
+            "GOOGLE_VERTEX_PROJECT",
+            "GOOGLE_APPLICATION_CREDENTIALS",
+        ],
+        performance: { speed: 2, quality: 3, cost: 3 },
+    },
+    bedrock: {
+        provider: "bedrock",
+        models: {
+            fast: "anthropic.claude-3-haiku-20240307-v1:0",
+            balanced: "anthropic.claude-3-sonnet-20240229-v1:0",
+            quality: "anthropic.claude-3-opus-20240229-v1:0",
+        },
+        costPerToken: { input: 0.00025, output: 0.00125 },
+        requiresApiKey: ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"],
+        performance: { speed: 2, quality: 3, cost: 2 },
+    },
+    azure: {
+        provider: "azure",
+        models: {
+            fast: "gpt-4o-mini",
+            balanced: "gpt-4o",
+            quality: "gpt-4o",
+        },
+        costPerToken: { input: 0.00015, output: 0.0006 },
+        requiresApiKey: ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"],
+        performance: { speed: 2, quality: 3, cost: 2 },
+    },
+    ollama: {
+        provider: "ollama",
+        models: {
+            fast: "llama3.2:latest",
+            balanced: "llama3.1:8b",
+            quality: "llama3.1:70b",
+        },
+        costPerToken: { input: 0, output: 0 }, // Local model
+        requiresApiKey: [], // No API key needed
+        performance: { speed: 1, quality: 2, cost: 3 },
+    },
+    huggingface: {
+        provider: "huggingface",
+        models: {
+            fast: "microsoft/DialoGPT-medium",
+            balanced: "microsoft/DialoGPT-large",
+            quality: "meta-llama/Llama-2-7b-chat-hf",
+        },
+        costPerToken: { input: 0.0002, output: 0.0006 },
+        requiresApiKey: ["HUGGINGFACE_API_KEY"],
+        performance: { speed: 1, quality: 2, cost: 2 },
+    },
+    mistral: {
+        provider: "mistral",
+        models: {
+            fast: "mistral-small-latest",
+            balanced: "mistral-medium-latest",
+            quality: "mistral-large-latest",
+        },
+        costPerToken: { input: 0.0002, output: 0.0006 },
+        requiresApiKey: ["MISTRAL_API_KEY"],
+        performance: { speed: 2, quality: 2, cost: 2 },
+    },
+};
+/**
+ * Get provider configuration by name
+ */
+export function getProviderConfig(providerName) {
+    return EVALUATION_PROVIDER_CONFIGS[providerName] || null;
+}
+/**
+ * Get all available providers with required API keys present
+ */
+export function getAvailableProviders() {
+    return Object.values(EVALUATION_PROVIDER_CONFIGS).filter((config) => {
+        if (config.requiresApiKey.length === 0) {
+            return true;
+        } // Ollama
+        return config.requiresApiKey.some((key) => process.env[key]);
+    });
+}
+/**
+ * Sort providers by preference (cost, speed, quality)
+ */
+export function sortProvidersByPreference(providers, preferCheap = true) {
+    return providers.sort((a, b) => {
+        if (preferCheap) {
+            // Cost > Speed > Quality for cheap preference
+            if (a.performance.cost !== b.performance.cost) {
+                return b.performance.cost - a.performance.cost;
+            }
+            if (a.performance.speed !== b.performance.speed) {
+                return b.performance.speed - a.performance.speed;
+            }
+            return b.performance.quality - a.performance.quality;
+        }
+        else {
+            // Quality > Speed > Cost for quality preference
+            if (a.performance.quality !== b.performance.quality) {
+                return b.performance.quality - a.performance.quality;
+            }
+            if (a.performance.speed !== b.performance.speed) {
+                return b.performance.speed - a.performance.speed;
+            }
+            return b.performance.cost - a.performance.cost;
+        }
+    });
+}
+/**
+ * Estimate cost for a specific provider and token usage
+ */
+export function estimateProviderCost(providerName, inputTokens, outputTokens) {
+    const config = getProviderConfig(providerName);
+    if (!config || !config.costPerToken) {
+        return 0;
+    }
+    return (inputTokens * config.costPerToken.input +
+        outputTokens * config.costPerToken.output);
+}
+/**
+ * Check if a provider is available (has required API keys)
+ */
+export function isProviderAvailable(providerName) {
+    const config = getProviderConfig(providerName);
+    if (!config) {
+        return false;
+    }
+    if (config.requiresApiKey.length === 0) {
+        return true;
+    } // Ollama
+    return config.requiresApiKey.some((key) => process.env[key]);
+}
+/**
+ * Get the best available provider based on preference
+ */
+export function getBestAvailableProvider(preferCheap = true) {
+    const availableProviders = getAvailableProviders();
+    if (availableProviders.length === 0) {
+        return null;
+    }
+    const sortedProviders = sortProvidersByPreference(availableProviders, preferCheap);
+    return sortedProviders[0];
+}

package/dist/core/evaluation.d.ts

@@ -0,0 +1,117 @@
+/**
+ * NeuroLink Unified Evaluation System
+ *
+ * Combines Universal Evaluation with Lighthouse-Enhanced capabilities
+ * - Domain-aware evaluation with sophisticated context handling
+ * - Multi-provider support with fallback strategies
+ * - Structured output with Zod schema validation
+ * - Tool usage and conversation history analysis
+ * - Enterprise-grade reliability and performance
+ */
+import type { EvaluationData } from "./types.js";
+import { z } from "zod";
+export interface UnifiedEvaluationResult extends EvaluationData {
+    domainAlignment?: number;
+    terminologyAccuracy?: number;
+    toolEffectiveness?: number;
+    contextUtilization?: {
+        conversationUsed: boolean;
+        toolsUsed: boolean;
+        domainKnowledgeUsed: boolean;
+    };
+    evaluationContext?: {
+        domain: string;
+        toolsEvaluated: string[];
+        conversationTurns: number;
+    };
+}
+export interface UnifiedEvaluationContext {
+    userQuery: string;
+    aiResponse: string;
+    context?: Record<string, any>;
+    primaryDomain?: string;
+    assistantRole?: string;
+    toolsUsed?: string[];
+    toolContext?: string;
+    conversationHistory?: Array<{
+        role: "user" | "assistant";
+        content: string;
+        timestamp?: string;
+    }>;
+    sessionId?: string;
+    userId?: string;
+    requestId?: string;
+    mode?: "simple" | "enhanced" | "lighthouse";
+}
+/**
+ * Unified Evaluation Schema (Lighthouse-compatible with extensions)
+ */
+export declare const unifiedEvaluationSchema: z.ZodObject<{
+    relevanceScore: z.ZodNumber;
+    accuracyScore: z.ZodNumber;
+    completenessScore: z.ZodNumber;
+    domainAlignment: z.ZodOptional<z.ZodNumber>;
+    terminologyAccuracy: z.ZodOptional<z.ZodNumber>;
+    toolEffectiveness: z.ZodOptional<z.ZodNumber>;
+    isOffTopic: z.ZodBoolean;
+    reasoning: z.ZodString;
+    suggestedImprovements: z.ZodOptional<z.ZodString>;
+    alertSeverity: z.ZodEnum<["low", "medium", "high", "none"]>;
+}, "strip", z.ZodTypeAny, {
+    relevanceScore: number;
+    accuracyScore: number;
+    completenessScore: number;
+    isOffTopic: boolean;
+    reasoning: string;
+    alertSeverity: "low" | "medium" | "high" | "none";
+    domainAlignment?: number | undefined;
+    terminologyAccuracy?: number | undefined;
+    toolEffectiveness?: number | undefined;
+    suggestedImprovements?: string | undefined;
+}, {
+    relevanceScore: number;
+    accuracyScore: number;
+    completenessScore: number;
+    isOffTopic: boolean;
+    reasoning: string;
+    alertSeverity: "low" | "medium" | "high" | "none";
+    domainAlignment?: number | undefined;
+    terminologyAccuracy?: number | undefined;
+    toolEffectiveness?: number | undefined;
+    suggestedImprovements?: string | undefined;
+}>;
+/**
+ * Main unified evaluation function
+ */
+export declare function performUnifiedEvaluation(context: UnifiedEvaluationContext): Promise<UnifiedEvaluationResult>;
+/**
+ * Enhanced evaluation model selection
+ */
+export declare function getEvaluationModel(): Promise<{
+    provider: any;
+    config: any;
+} | null>;
+/**
+ * Create simple evaluation context (backward compatibility)
+ */
+export declare function createSimpleEvaluationContext(prompt: string, response: string, context?: Record<string, any>): UnifiedEvaluationContext;
+/**
+ * Create enhanced evaluation context
+ */
+export declare function createEnhancedEvaluationContext(userQuery: string, aiResponse: string, options?: {
+    domain?: string;
+    role?: string;
+    toolsUsed?: string[];
+    conversationHistory?: Array<{
+        role: "user" | "assistant";
+        content: string;
+    }>;
+    sessionId?: string;
+    context?: Record<string, any>;
+}): UnifiedEvaluationContext;
+export declare function evaluateResponse(prompt: string, response: string, context?: Record<string, any>, evaluationDomain?: string, toolUsageContext?: string, conversationHistory?: Array<{
+    role: string;
+    content: string;
+    timestamp?: string;
+}>): Promise<UnifiedEvaluationResult>;
+export type EvaluationResult = UnifiedEvaluationResult;