@juspay/neurolink 7.36.0 → 7.37.0

package/dist/utils/modelRouter.js

@@ -0,0 +1,292 @@
+/**
+ * Model Router for NeuroLink Orchestration
+ * Routes tasks to optimal models based on classification and requirements
+ */
+import { logger } from "./logger.js";
+import { BinaryTaskClassifier } from "./taskClassifier.js";
+import { redactForRouting } from "./promptRedaction.js";
+/**
+ * Routing configuration constants
+ */
+const ROUTING_CONFIG = {
+    minRouteConfidence: 0.3,
+    maxRouteConfidence: 0.95,
+    confidenceBoost: 0.1,
+};
+/**
+ * Model configurations for different task types and providers
+ */
+const MODEL_CONFIGS = {
+    fast: {
+        primary: {
+            provider: "vertex",
+            model: "gemini-2.5-flash",
+            capabilities: ["speed", "general", "code", "basic-reasoning"],
+            avgResponseTime: 800, // ms
+            costPerToken: 0.0001,
+            reasoning: "Optimized for speed and efficiency via Vertex AI",
+        },
+        fallback: {
+            provider: "vertex",
+            model: "gemini-2.5-pro",
+            capabilities: ["speed", "general", "basic-reasoning"],
+            avgResponseTime: 1200,
+            costPerToken: 0.0002,
+            reasoning: "Vertex AI Gemini Pro fallback",
+        },
+    },
+    reasoning: {
+        primary: {
+            provider: "vertex",
+            model: "claude-sonnet-4@20250514",
+            capabilities: [
+                "reasoning",
+                "analysis",
+                "complex-logic",
+                "code",
+                "creativity",
+            ],
+            avgResponseTime: 3000, // ms
+            costPerToken: 0.003,
+            reasoning: "Advanced reasoning and analysis via Claude Sonnet 4 on Vertex AI",
+        },
+        fallback: {
+            provider: "vertex",
+            model: "claude-opus-4@20250514",
+            capabilities: [
+                "reasoning",
+                "analysis",
+                "complex-logic",
+                "code",
+                "creativity",
+                "agentic",
+            ],
+            avgResponseTime: 4000,
+            costPerToken: 0.005,
+            reasoning: "Claude Opus 4 fallback on Vertex AI for most complex tasks",
+        },
+    },
+};
+/**
+ * Model Router
+ * Intelligently routes tasks to optimal models based on classification
+ */
+export class ModelRouter {
+    /**
+     * Route a prompt to the optimal model configuration
+     */
+    static route(prompt, options = {}) {
+        const startTime = Date.now();
+        // 1. Classify the task if not overridden
+        let classification;
+        if (options.forceTaskType) {
+            classification = {
+                type: options.forceTaskType,
+                confidence: ROUTING_CONFIG.maxRouteConfidence, // Use maxRouteConfidence instead of 1.0
+                reasoning: "forced task type",
+            };
+        }
+        else {
+            classification = BinaryTaskClassifier.classify(prompt);
+        }
+        // 2. Apply special requirements
+        let taskType = classification.type;
+        const reasons = [classification.reasoning];
+        if (options.requireFast) {
+            taskType = "fast";
+            reasons.push("speed required");
+        }
+        if (options.requireCapability) {
+            // Check if the capability suggests a specific task type
+            const capability = options.requireCapability.toLowerCase();
+            if (["analysis", "reasoning", "complex", "research"].some((c) => capability.includes(c))) {
+                taskType = "reasoning";
+                reasons.push(`capability: ${capability}`);
+            }
+            else if (["speed", "quick", "fast", "simple"].some((c) => capability.includes(c))) {
+                taskType = "fast";
+                reasons.push(`capability: ${capability}`);
+            }
+        }
+        // 3. Select model configuration
+        const config = MODEL_CONFIGS[taskType];
+        const selectedConfig = config.primary;
+        // 4. Calculate confidence based on multiple factors
+        let confidence = classification.confidence;
+        // Adjust confidence based on prompt characteristics
+        if (taskType === "fast" && prompt.length < 30) {
+            confidence = Math.min(ROUTING_CONFIG.maxRouteConfidence, confidence + ROUTING_CONFIG.confidenceBoost);
+            reasons.push("very short prompt");
+        }
+        if (taskType === "reasoning" && prompt.length > 150) {
+            confidence = Math.min(ROUTING_CONFIG.maxRouteConfidence, confidence + ROUTING_CONFIG.confidenceBoost);
+            reasons.push("detailed prompt");
+        }
+        // Ensure final confidence is within configured bounds
+        confidence = Math.max(ROUTING_CONFIG.minRouteConfidence, Math.min(ROUTING_CONFIG.maxRouteConfidence, confidence));
+        // 5. Create route result
+        const route = {
+            provider: selectedConfig.provider,
+            model: selectedConfig.model,
+            reasoning: reasons.join(", "),
+            confidence,
+        };
+        const routingTime = Date.now() - startTime;
+        logger.debug("Model routing decision", {
+            prompt: redactForRouting(prompt),
+            taskType,
+            route: {
+                provider: route.provider,
+                model: route.model,
+                confidence: route.confidence.toFixed(2),
+            },
+            reasoning: route.reasoning,
+            routingTime: `${routingTime}ms`,
+            options: Object.keys(options).length > 0 ? options : undefined,
+        });
+        return route;
+    }
+    /**
+     * Get fallback route if primary route fails
+     */
+    static getFallbackRoute(prompt, primaryRoute, options = {}) {
+        // Determine fallback strategy
+        let fallbackType;
+        if (options.fallbackStrategy) {
+            if (options.fallbackStrategy === "auto") {
+                // Use opposite of primary for fallback
+                const primaryType = this.getTaskTypeFromRoute(primaryRoute);
+                fallbackType = primaryType === "fast" ? "reasoning" : "fast";
+            }
+            else {
+                fallbackType = options.fallbackStrategy;
+            }
+        }
+        else {
+            // Default: use fallback model of same type
+            fallbackType = this.getTaskTypeFromRoute(primaryRoute);
+        }
+        const config = MODEL_CONFIGS[fallbackType];
+        const fallbackConfig = config.fallback;
+        const route = {
+            provider: fallbackConfig.provider,
+            model: fallbackConfig.model,
+            reasoning: `fallback from ${primaryRoute.provider}/${primaryRoute.model}`,
+            confidence: Math.max(ROUTING_CONFIG.minRouteConfidence, Math.min(ROUTING_CONFIG.maxRouteConfidence, primaryRoute.confidence - 0.2)),
+        };
+        logger.debug("Fallback route selected", {
+            originalRoute: `${primaryRoute.provider}/${primaryRoute.model}`,
+            fallbackRoute: `${route.provider}/${route.model}`,
+            fallbackType,
+            strategy: options.fallbackStrategy || "default",
+        });
+        return route;
+    }
+    /**
+     * Determine task type from a model route
+     */
+    static getTaskTypeFromRoute(route) {
+        // Check which config matches this route
+        for (const [taskType, config] of Object.entries(MODEL_CONFIGS)) {
+            if (config.primary.provider === route.provider &&
+                config.primary.model === route.model) {
+                return taskType;
+            }
+            if (config.fallback.provider === route.provider &&
+                config.fallback.model === route.model) {
+                return taskType;
+            }
+        }
+        // Default fallback based on model name patterns
+        if (route.model.includes("flash") || route.model.includes("mini")) {
+            return "fast";
+        }
+        return "reasoning";
+    }
+    /**
+     * Get all available model configurations
+     */
+    static getAvailableModels() {
+        return MODEL_CONFIGS;
+    }
+    /**
+     * Validate model availability for a given route
+     */
+    static async validateRoute(route) {
+        try {
+            // This would typically check provider availability
+            // For now, just validate the configuration exists
+            const configs = Object.values(MODEL_CONFIGS).flatMap((config) => [
+                config.primary,
+                config.fallback,
+            ]);
+            return configs.some((config) => config.provider === route.provider && config.model === route.model);
+        }
+        catch (error) {
+            logger.error("Route validation failed", {
+                route,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return false;
+        }
+    }
+    /**
+     * Get routing statistics for multiple prompts
+     */
+    static getRoutingStats(prompts) {
+        const routes = prompts.map((prompt) => this.route(prompt));
+        // Handle empty prompts array to avoid divide-by-zero
+        if (routes.length === 0) {
+            const stats = {
+                total: 0,
+                fastRoutes: 0,
+                reasoningRoutes: 0,
+                averageConfidence: 0,
+                providerDistribution: {},
+            };
+            logger.debug("Routing statistics", stats);
+            return stats;
+        }
+        const stats = {
+            total: routes.length,
+            fastRoutes: routes.filter((r) => {
+                const taskType = this.getTaskTypeFromRoute(r);
+                return taskType === "fast";
+            }).length,
+            reasoningRoutes: routes.filter((r) => {
+                const taskType = this.getTaskTypeFromRoute(r);
+                return taskType === "reasoning";
+            }).length,
+            averageConfidence: routes.reduce((sum, r) => sum + r.confidence, 0) / routes.length,
+            providerDistribution: routes.reduce((dist, r) => {
+                dist[r.provider] = (dist[r.provider] || 0) + 1;
+                return dist;
+            }, {}),
+        };
+        logger.debug("Routing statistics", stats);
+        return stats;
+    }
+    /**
+     * Estimate cost and performance for a route
+     */
+    static getRouteEstimates(route, estimatedTokens = 500) {
+        // Find the config for this route
+        const allConfigs = Object.values(MODEL_CONFIGS).flatMap((config) => [
+            config.primary,
+            config.fallback,
+        ]);
+        const config = allConfigs.find((c) => c.provider === route.provider && c.model === route.model);
+        if (!config) {
+            return {
+                estimatedCost: 0,
+                estimatedResponseTime: 2000,
+                capabilities: [],
+            };
+        }
+        return {
+            estimatedCost: config.costPerToken * estimatedTokens,
+            estimatedResponseTime: config.avgResponseTime,
+            capabilities: [...config.capabilities],
+        };
+    }
+}

package/dist/utils/promptRedaction.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Prompt redaction utilities for safe logging
+ * Provides consistent prompt masking across NeuroLink components
+ */
+export interface PromptRedactionOptions {
+    /** Maximum length of redacted prompt */
+    maxLength?: number;
+    /** Whether to show word count */
+    showWordCount?: boolean;
+    /** Mask character to use for redaction */
+    maskChar?: string;
+}
+/**
+ * Redact a prompt for safe logging
+ * Truncates to maxLength and optionally shows word count
+ */
+export declare function redactPrompt(prompt: string, options?: PromptRedactionOptions): string;
+/**
+ * Create a short safe mask for highly sensitive contexts
+ */
+export declare function createSafeMask(prompt: string, _maskLength?: number): string;
+/**
+ * Redact for classification context (matches classifier behavior)
+ */
+export declare function redactForClassification(prompt: string): string;
+/**
+ * Redact for routing context (matches router behavior)
+ */
+export declare function redactForRouting(prompt: string): string;

package/dist/utils/promptRedaction.js

@@ -0,0 +1,62 @@
+/**
+ * Prompt redaction utilities for safe logging
+ * Provides consistent prompt masking across NeuroLink components
+ */
+/**
+ * Default redaction options
+ */
+const DEFAULT_REDACTION_OPTIONS = {
+    maxLength: 100,
+    showWordCount: true,
+    maskChar: "*",
+};
+/**
+ * Redact a prompt for safe logging
+ * Truncates to maxLength and optionally shows word count
+ */
+export function redactPrompt(prompt, options = {}) {
+    const opts = { ...DEFAULT_REDACTION_OPTIONS, ...options };
+    if (!prompt || typeof prompt !== 'string') {
+        return '[INVALID_PROMPT]';
+    }
+    const wordCount = prompt.trim().split(/\s+/).length;
+    let redacted = prompt.substring(0, opts.maxLength);
+    // Add ellipsis if truncated
+    if (prompt.length > opts.maxLength) {
+        redacted = redacted.substring(0, opts.maxLength - 3) + "...";
+    }
+    // Optionally append word count
+    if (opts.showWordCount) {
+        redacted += ` [${wordCount} words]`;
+    }
+    return redacted;
+}
+/**
+ * Create a short safe mask for highly sensitive contexts
+ */
+export function createSafeMask(prompt, _maskLength = 20) {
+    if (!prompt || typeof prompt !== 'string') {
+        return '[INVALID_PROMPT]';
+    }
+    const wordCount = prompt.trim().split(/\s+/).length;
+    const charCount = prompt.length;
+    return `[REDACTED: ${charCount} chars, ${wordCount} words]`;
+}
+/**
+ * Redact for classification context (matches classifier behavior)
+ */
+export function redactForClassification(prompt) {
+    return redactPrompt(prompt, {
+        maxLength: 100,
+        showWordCount: false,
+    });
+}
+/**
+ * Redact for routing context (matches router behavior)
+ */
+export function redactForRouting(prompt) {
+    return redactPrompt(prompt, {
+        maxLength: 100,
+        showWordCount: true,
+    });
+}

package/dist/utils/taskClassificationUtils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Task Classification Utility Functions
+ * Helper functions for analyzing prompts and calculating scores
+ */
+import type { ClassificationScores } from "../types/taskClassificationTypes.js";
+/**
+ * Analyze prompt length and apply scoring bonuses
+ */
+export declare function analyzeLengthFactors(prompt: string, reasons: string[]): {
+    fastScore: number;
+    reasoningScore: number;
+};
+/**
+ * Check prompt against fast task patterns
+ */
+export declare function checkFastPatterns(normalizedPrompt: string, reasons: string[]): number;
+/**
+ * Check prompt against reasoning task patterns
+ */
+export declare function checkReasoningPatterns(normalizedPrompt: string, reasons: string[]): number;
+/**
+ * Analyze keyword matches in the prompt
+ */
+export declare function analyzeKeywords(normalizedPrompt: string, reasons: string[]): {
+    fastScore: number;
+    reasoningScore: number;
+};
+/**
+ * Analyze question complexity
+ */
+export declare function analyzeQuestionComplexity(prompt: string, reasons: string[]): number;
+/**
+ * Analyze prompt structure and punctuation
+ */
+export declare function analyzePromptStructure(prompt: string, reasons: string[]): number;
+/**
+ * Analyze domain-specific indicators
+ */
+export declare function analyzeDomainIndicators(normalizedPrompt: string, prompt: string, reasons: string[]): {
+    fastScore: number;
+    reasoningScore: number;
+};
+/**
+ * Calculate final confidence score
+ */
+export declare function calculateConfidence(fastScore: number, reasoningScore: number): number;
+/**
+ * Determine task type based on scores
+ */
+export declare function determineTaskType(fastScore: number, reasoningScore: number): "fast" | "reasoning";
+/**
+ * Comprehensive prompt analysis
+ * Runs all analysis functions and returns combined scores
+ */
+export declare function analyzePrompt(prompt: string): ClassificationScores;

package/dist/utils/taskClassificationUtils.js

@@ -0,0 +1,149 @@
+/**
+ * Task Classification Utility Functions
+ * Helper functions for analyzing prompts and calculating scores
+ */
+import { FAST_PATTERNS, REASONING_PATTERNS, FAST_KEYWORDS, REASONING_KEYWORDS, SCORING_WEIGHTS, CLASSIFICATION_THRESHOLDS, DOMAIN_PATTERNS, } from "../config/taskClassificationConfig.js";
+/**
+ * Analyze prompt length and apply scoring bonuses
+ */
+export function analyzeLengthFactors(prompt, reasons) {
+    let fastScore = 0;
+    let reasoningScore = 0;
+    if (prompt.length < CLASSIFICATION_THRESHOLDS.SHORT_PROMPT_LENGTH) {
+        fastScore += SCORING_WEIGHTS.SHORT_PROMPT_BONUS;
+        reasons.push("short prompt");
+    }
+    else if (prompt.length > CLASSIFICATION_THRESHOLDS.LONG_PROMPT_LENGTH) {
+        reasoningScore += SCORING_WEIGHTS.LONG_PROMPT_BONUS;
+        reasons.push("detailed prompt");
+    }
+    return { fastScore, reasoningScore };
+}
+/**
+ * Check prompt against fast task patterns
+ */
+export function checkFastPatterns(normalizedPrompt, reasons) {
+    for (const pattern of FAST_PATTERNS) {
+        if (pattern.test(normalizedPrompt)) {
+            reasons.push("fast pattern match");
+            return SCORING_WEIGHTS.PATTERN_MATCH_SCORE;
+        }
+    }
+    return 0;
+}
+/**
+ * Check prompt against reasoning task patterns
+ */
+export function checkReasoningPatterns(normalizedPrompt, reasons) {
+    for (const pattern of REASONING_PATTERNS) {
+        if (pattern.test(normalizedPrompt)) {
+            reasons.push("reasoning pattern match");
+            return SCORING_WEIGHTS.PATTERN_MATCH_SCORE;
+        }
+    }
+    return 0;
+}
+/**
+ * Analyze keyword matches in the prompt
+ */
+export function analyzeKeywords(normalizedPrompt, reasons) {
+    const fastKeywordMatches = FAST_KEYWORDS.filter((keyword) => normalizedPrompt.includes(keyword)).length;
+    const reasoningKeywordMatches = REASONING_KEYWORDS.filter((keyword) => normalizedPrompt.includes(keyword)).length;
+    const fastScore = fastKeywordMatches * SCORING_WEIGHTS.KEYWORD_MATCH_SCORE;
+    const reasoningScore = reasoningKeywordMatches * SCORING_WEIGHTS.KEYWORD_MATCH_SCORE;
+    if (fastKeywordMatches > 0) {
+        reasons.push(`${fastKeywordMatches} fast keywords`);
+    }
+    if (reasoningKeywordMatches > 0) {
+        reasons.push(`${reasoningKeywordMatches} reasoning keywords`);
+    }
+    return { fastScore, reasoningScore };
+}
+/**
+ * Analyze question complexity
+ */
+export function analyzeQuestionComplexity(prompt, reasons) {
+    const questionMarks = (prompt.match(/\?/g) || []).length;
+    if (questionMarks > 1) {
+        reasons.push("multiple questions");
+        return SCORING_WEIGHTS.MULTIPLE_QUESTIONS_BONUS;
+    }
+    return 0;
+}
+/**
+ * Analyze prompt structure and punctuation
+ */
+export function analyzePromptStructure(prompt, reasons) {
+    const sentences = prompt.split(/[.!?]+/).filter((s) => s.trim().length > 0);
+    if (sentences.length > 3) {
+        reasons.push("multi-sentence structure");
+        return SCORING_WEIGHTS.MULTI_SENTENCE_BONUS;
+    }
+    return 0;
+}
+/**
+ * Analyze domain-specific indicators
+ */
+export function analyzeDomainIndicators(normalizedPrompt, prompt, reasons) {
+    let fastScore = 0;
+    let reasoningScore = 0;
+    // Check for technical domain
+    if (DOMAIN_PATTERNS.TECHNICAL.test(normalizedPrompt)) {
+        reasoningScore += SCORING_WEIGHTS.TECHNICAL_DOMAIN_BONUS;
+        reasons.push("technical domain");
+    }
+    // Check for simple definition requests
+    if (DOMAIN_PATTERNS.SIMPLE_DEFINITION.test(normalizedPrompt) &&
+        prompt.length < CLASSIFICATION_THRESHOLDS.SIMPLE_DEFINITION_LENGTH) {
+        fastScore += SCORING_WEIGHTS.SIMPLE_DEFINITION_BONUS;
+        reasons.push("simple definition request");
+    }
+    return { fastScore, reasoningScore };
+}
+/**
+ * Calculate final confidence score
+ */
+export function calculateConfidence(fastScore, reasoningScore) {
+    const totalScore = fastScore + reasoningScore;
+    if (totalScore === 0) {
+        return CLASSIFICATION_THRESHOLDS.DEFAULT_CONFIDENCE;
+    }
+    const rawConfidence = Math.max(fastScore, reasoningScore) / totalScore;
+    return Math.max(CLASSIFICATION_THRESHOLDS.MIN_CONFIDENCE, Math.min(CLASSIFICATION_THRESHOLDS.MAX_CONFIDENCE, rawConfidence));
+}
+/**
+ * Determine task type based on scores
+ */
+export function determineTaskType(fastScore, reasoningScore) {
+    return fastScore >= reasoningScore ? "fast" : "reasoning";
+}
+/**
+ * Comprehensive prompt analysis
+ * Runs all analysis functions and returns combined scores
+ */
+export function analyzePrompt(prompt) {
+    const normalizedPrompt = prompt.toLowerCase().trim();
+    const reasons = [];
+    let fastScore = 0;
+    let reasoningScore = 0;
+    // 1. Length analysis
+    const lengthScores = analyzeLengthFactors(prompt, reasons);
+    fastScore += lengthScores.fastScore;
+    reasoningScore += lengthScores.reasoningScore;
+    // 2. Pattern matching
+    fastScore += checkFastPatterns(normalizedPrompt, reasons);
+    reasoningScore += checkReasoningPatterns(normalizedPrompt, reasons);
+    // 3. Keyword analysis
+    const keywordScores = analyzeKeywords(normalizedPrompt, reasons);
+    fastScore += keywordScores.fastScore;
+    reasoningScore += keywordScores.reasoningScore;
+    // 4. Question complexity
+    reasoningScore += analyzeQuestionComplexity(prompt, reasons);
+    // 5. Structure analysis
+    reasoningScore += analyzePromptStructure(prompt, reasons);
+    // 6. Domain analysis
+    const domainScores = analyzeDomainIndicators(normalizedPrompt, prompt, reasons);
+    fastScore += domainScores.fastScore;
+    reasoningScore += domainScores.reasoningScore;
+    return { fastScore, reasoningScore, reasons };
+}

package/dist/utils/taskClassifier.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Binary Task Classifier for NeuroLink Orchestration
+ * Classifies tasks as either 'fast' (quick responses) or 'reasoning' (complex analysis)
+ */
+import type { TaskType, TaskClassification, ClassificationStats, ClassificationValidation } from "../types/taskClassificationTypes.js";
+/**
+ * Binary Task Classifier
+ * Determines if a task requires fast response or deeper reasoning
+ */
+export declare class BinaryTaskClassifier {
+    /**
+     * Classify a prompt as either fast or reasoning task
+     */
+    static classify(prompt: string): TaskClassification;
+    /**
+     * Get classification statistics for multiple prompts
+     */
+    static getClassificationStats(prompts: string[]): ClassificationStats;
+    /**
+     * Validate classification accuracy (for testing/tuning)
+     */
+    static validateClassification(prompt: string, expectedType: TaskType): ClassificationValidation;
+}