@juspay/neurolink 7.36.0 → 7.37.0

package/dist/lib/neurolink.js

@@ -35,6 +35,9 @@ import { getConversationMessages, storeConversationTurn, } from "./utils/convers
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
 // Import direct tools server for automatic registration
 import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
+// Import orchestration components
+import { ModelRouter } from "./utils/modelRouter.js";
+import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
 // Core types imported from "./types/index.js"
 export class NeuroLink {
@@ -75,6 +78,8 @@ export class NeuroLink {
     conversationMemory;
     conversationMemoryNeedsInit = false;
     conversationMemoryConfig;
+    // Add orchestration property
+    enableOrchestration;
     /**
      * Creates a new NeuroLink instance for AI text generation with MCP tool integration.
      *
@@ -83,6 +88,7 @@ export class NeuroLink {
      * @param config.conversationMemory.enabled - Whether to enable conversation memory (default: false)
      * @param config.conversationMemory.maxSessions - Maximum number of concurrent sessions (default: 100)
      * @param config.conversationMemory.maxTurnsPerSession - Maximum conversation turns per session (default: 50)
+     * @param config.enableOrchestration - Whether to enable smart model orchestration (default: false)
      *
      * @example
      * ```typescript
@@ -97,6 +103,11 @@ export class NeuroLink {
      *     maxTurnsPerSession: 20
      *   }
      * });
+     *
+     * // With orchestration enabled
+     * const neurolink = new NeuroLink({
+     *   enableOrchestration: true
+     * });
      * ```
      *
      * @throws {Error} When provider registry setup fails
@@ -112,6 +123,8 @@ export class NeuroLink {
         const constructorStartTime = Date.now();
         const constructorHrTimeStart = process.hrtime.bigint();
         const constructorId = `neurolink-constructor-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+        // Initialize orchestration setting
+        this.enableOrchestration = config?.enableOrchestration ?? false;
         this.logConstructorStart(constructorId, constructorStartTime, constructorHrTimeStart, config);
         this.initializeProviderRegistry(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeConversationMemory(config, constructorId, constructorStartTime, constructorHrTimeStart);
@@ -758,6 +771,206 @@ export class NeuroLink {
             mcpLogger.debug("💡 Memory cleanup suggestion: MCP initialization used significant memory. Consider calling MemoryManager.forceGC() after heavy operations.");
         }
     }
+    /**
+     * Apply orchestration to determine optimal provider and model
+     * @param options - Original GenerateOptions
+     * @returns Modified options with orchestrated provider marked in context, or empty object if validation fails
+     */
+    async applyOrchestration(options) {
+        const startTime = Date.now();
+        try {
+            // Ensure input.text exists before proceeding
+            if (!options.input?.text || typeof options.input.text !== "string") {
+                logger.debug("Orchestration skipped - no valid input text", {
+                    hasInput: !!options.input,
+                    hasText: !!options.input?.text,
+                    textType: typeof options.input?.text,
+                });
+                return {}; // Return empty object to preserve existing fallback behavior
+            }
+            // Compute classification once to avoid duplicate calls
+            const classification = BinaryTaskClassifier.classify(options.input.text);
+            // Use the model router to get the optimal route
+            const route = ModelRouter.route(options.input.text);
+            // Validate that the routed provider is available and configured
+            const isProviderAvailable = await this.hasProviderEnvVars(route.provider);
+            if (!isProviderAvailable && route.provider !== "ollama") {
+                logger.debug("Orchestration provider validation failed", {
+                    taskType: classification.type,
+                    routedProvider: route.provider,
+                    routedModel: route.model,
+                    reason: "Provider not configured or missing environment variables",
+                    orchestrationTime: `${Date.now() - startTime}ms`,
+                });
+                return {}; // Return empty object to preserve existing fallback behavior
+            }
+            // For Ollama, check if service is running and model is available
+            if (route.provider === "ollama") {
+                try {
+                    const response = await fetch("http://localhost:11434/api/tags", {
+                        method: "GET",
+                        signal: AbortSignal.timeout(2000),
+                    });
+                    if (!response.ok) {
+                        logger.debug("Orchestration provider validation failed", {
+                            taskType: classification.type,
+                            routedProvider: route.provider,
+                            routedModel: route.model,
+                            reason: "Ollama service not responding",
+                            orchestrationTime: `${Date.now() - startTime}ms`,
+                        });
+                        return {}; // Return empty object to preserve existing fallback behavior
+                    }
+                    const { models } = await response.json();
+                    const modelIsAvailable = models.some((m) => m.name === (route.model || "llama3.2:latest"));
+                    if (!modelIsAvailable) {
+                        logger.debug("Orchestration provider validation failed", {
+                            taskType: classification.type,
+                            routedProvider: route.provider,
+                            routedModel: route.model,
+                            reason: `Ollama model '${route.model || "llama3.2:latest"}' not found`,
+                            orchestrationTime: `${Date.now() - startTime}ms`,
+                        });
+                        return {}; // Return empty object to preserve existing fallback behavior
+                    }
+                }
+                catch (error) {
+                    logger.debug("Orchestration provider validation failed", {
+                        taskType: classification.type,
+                        routedProvider: route.provider,
+                        routedModel: route.model,
+                        reason: error instanceof Error ? error.message : "Ollama service check failed",
+                        orchestrationTime: `${Date.now() - startTime}ms`,
+                    });
+                    return {}; // Return empty object to preserve existing fallback behavior
+                }
+            }
+            logger.debug("Orchestration route determined", {
+                taskType: classification.type,
+                selectedProvider: route.provider,
+                selectedModel: route.model,
+                confidence: route.confidence,
+                reasoning: route.reasoning,
+                orchestrationTime: `${Date.now() - startTime}ms`,
+            });
+            // Mark preferred provider in context instead of directly setting provider
+            // This preserves global fallback behavior while indicating orchestration preference
+            return {
+                model: route.model,
+                context: {
+                    ...(options.context || {}),
+                    __orchestratedPreferredProvider: route.provider,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("Orchestration failed", {
+                error: error instanceof Error ? error.message : String(error),
+                orchestrationTime: `${Date.now() - startTime}ms`,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Apply orchestration to determine optimal provider and model for streaming
+     * @param options - Original StreamOptions
+     * @returns Modified options with orchestrated provider marked in context, or empty object if validation fails
+     */
+    async applyStreamOrchestration(options) {
+        const startTime = Date.now();
+        try {
+            // Ensure input.text exists before proceeding
+            if (!options.input?.text || typeof options.input.text !== "string") {
+                logger.debug("Stream orchestration skipped - no valid input text", {
+                    hasInput: !!options.input,
+                    hasText: !!options.input?.text,
+                    textType: typeof options.input?.text,
+                });
+                return {}; // Return empty object to preserve existing fallback behavior
+            }
+            // Compute classification once to avoid duplicate calls
+            const classification = BinaryTaskClassifier.classify(options.input.text);
+            // Use the model router to get the optimal route
+            const route = ModelRouter.route(options.input.text);
+            // Validate that the routed provider is available and configured
+            const isProviderAvailable = await this.hasProviderEnvVars(route.provider);
+            if (!isProviderAvailable && route.provider !== "ollama") {
+                logger.debug("Stream orchestration provider validation failed", {
+                    taskType: classification.type,
+                    routedProvider: route.provider,
+                    routedModel: route.model,
+                    reason: "Provider not configured or missing environment variables",
+                    orchestrationTime: `${Date.now() - startTime}ms`,
+                });
+                return {}; // Return empty object to preserve existing fallback behavior
+            }
+            // For Ollama, check if service is running and model is available
+            if (route.provider === "ollama") {
+                try {
+                    const response = await fetch("http://localhost:11434/api/tags", {
+                        method: "GET",
+                        signal: AbortSignal.timeout(2000),
+                    });
+                    if (!response.ok) {
+                        logger.debug("Stream orchestration provider validation failed", {
+                            taskType: classification.type,
+                            routedProvider: route.provider,
+                            routedModel: route.model,
+                            reason: "Ollama service not responding",
+                            orchestrationTime: `${Date.now() - startTime}ms`,
+                        });
+                        return {}; // Return empty object to preserve existing fallback behavior
+                    }
+                    const { models } = await response.json();
+                    const modelIsAvailable = models.some((m) => m.name === (route.model || "llama3.2:latest"));
+                    if (!modelIsAvailable) {
+                        logger.debug("Stream orchestration provider validation failed", {
+                            taskType: classification.type,
+                            routedProvider: route.provider,
+                            routedModel: route.model,
+                            reason: `Ollama model '${route.model || "llama3.2:latest"}' not found`,
+                            orchestrationTime: `${Date.now() - startTime}ms`,
+                        });
+                        return {}; // Return empty object to preserve existing fallback behavior
+                    }
+                }
+                catch (error) {
+                    logger.debug("Stream orchestration provider validation failed", {
+                        taskType: classification.type,
+                        routedProvider: route.provider,
+                        routedModel: route.model,
+                        reason: error instanceof Error ? error.message : "Ollama service check failed",
+                        orchestrationTime: `${Date.now() - startTime}ms`,
+                    });
+                    return {}; // Return empty object to preserve existing fallback behavior
+                }
+            }
+            logger.debug("Stream orchestration route determined", {
+                taskType: classification.type,
+                selectedProvider: route.provider,
+                selectedModel: route.model,
+                confidence: route.confidence,
+                reasoning: route.reasoning,
+                orchestrationTime: `${Date.now() - startTime}ms`,
+            });
+            // Mark preferred provider in context instead of directly setting provider
+            // This preserves global fallback behavior while indicating orchestration preference
+            return {
+                model: route.model,
+                context: {
+                    ...(options.context || {}),
+                    __orchestratedPreferredProvider: route.provider,
+                },
+            };
+        }
+        catch (error) {
+            logger.error("Stream orchestration failed", {
+                error: error instanceof Error ? error.message : String(error),
+                orchestrationTime: `${Date.now() - startTime}ms`,
+            });
+            throw error;
+        }
+    }
     /**
      * MAIN ENTRY POINT: Enhanced generate method with new function signature
      * Replaces both generateText and legacy methods
@@ -833,6 +1046,27 @@ export class NeuroLink {
             throw new Error("Input text is required and must be a non-empty string");
         }
         const startTime = Date.now();
+        // Apply orchestration if enabled and no specific provider/model requested
+        if (this.enableOrchestration && !options.provider && !options.model) {
+            try {
+                const orchestratedOptions = await this.applyOrchestration(options);
+                logger.debug("Orchestration applied", {
+                    originalProvider: options.provider || "auto",
+                    orchestratedProvider: orchestratedOptions.provider,
+                    orchestratedModel: orchestratedOptions.model,
+                    prompt: options.input.text.substring(0, 100),
+                });
+                // Use orchestrated options
+                Object.assign(options, orchestratedOptions);
+            }
+            catch (error) {
+                logger.warn("Orchestration failed, continuing with original options", {
+                    error: error instanceof Error ? error.message : String(error),
+                    originalProvider: options.provider || "auto",
+                });
+                // Continue with original options if orchestration fails
+            }
+        }
         // Emit generation start event (NeuroLink format - keep existing)
         this.emitter.emit("generation:start", {
             provider: options.provider || "auto",
@@ -1429,14 +1663,21 @@ export class NeuroLink {
             "ollama",
         ];
         const requestedProvider = options.provider === "auto" ? undefined : options.provider;
-        // If specific provider requested, only use that provider (no fallback)
-        const tryProviders = requestedProvider
-            ? [requestedProvider]
-            : providerPriority;
+        // Check for orchestrated preferred provider in context
+        const preferredOrchestrated = options.context && typeof options.context === 'object' && '__orchestratedPreferredProvider' in options.context
+            ? options.context.__orchestratedPreferredProvider
+            : undefined;
+        // Build provider list with orchestrated preference first, then fallback to full list
+        const tryProviders = preferredOrchestrated
+            ? [preferredOrchestrated, ...providerPriority.filter((p) => p !== preferredOrchestrated)]
+            : requestedProvider
+                ? [requestedProvider]
+                : providerPriority;
         logger.debug(`[${functionTag}] Starting direct generation`, {
             requestedProvider: requestedProvider || "auto",
+            preferredOrchestrated: preferredOrchestrated || "none",
             tryProviders,
-            allowFallback: !requestedProvider,
+            allowFallback: !requestedProvider || !!preferredOrchestrated,
         });
         let lastError = null;
         // Try each provider in order
@@ -1651,6 +1892,28 @@ export class NeuroLink {
             await this.initializeConversationMemoryForGeneration(streamId, startTime, hrTimeStart);
             // Initialize MCP
             await this.initializeMCP();
+            const _originalPrompt = options.input.text;
+            // Apply orchestration if enabled and no specific provider/model requested
+            if (this.enableOrchestration && !options.provider && !options.model) {
+                try {
+                    const orchestratedOptions = await this.applyStreamOrchestration(options);
+                    logger.debug("Stream orchestration applied", {
+                        originalProvider: options.provider || "auto",
+                        orchestratedProvider: orchestratedOptions.provider,
+                        orchestratedModel: orchestratedOptions.model,
+                        prompt: options.input.text?.substring(0, 100),
+                    });
+                    // Use orchestrated options
+                    Object.assign(options, orchestratedOptions);
+                }
+                catch (error) {
+                    logger.warn("Stream orchestration failed, continuing with original options", {
+                        error: error instanceof Error ? error.message : String(error),
+                        originalProvider: options.provider || "auto",
+                    });
+                    // Continue with original options if orchestration fails
+                }
+            }
             factoryResult = processStreamingFactoryOptions(options);
             enhancedOptions = createCleanStreamOptions(options);
             if (options.input?.text) {

package/dist/lib/types/index.d.ts

@@ -5,10 +5,12 @@ export * from "./common.js";
 export * from "./tools.js";
 export * from "./providers.js";
 export * from "./cli.js";
+export * from "./taskClassificationTypes.js";
 export type { Unknown, UnknownRecord, UnknownArray, JsonValue, JsonObject, JsonArray, ErrorInfo, Result, FunctionParameters, } from "./common.js";
 export type { ToolArgs, ToolContext, ToolResult, ToolDefinition, SimpleTool, AvailableTool, ToolExecution, } from "./tools.js";
 export type { AISDKModel, ProviderError, ProviderConfig } from "./providers.js";
 export type { BaseCommandArgs, GenerateCommandArgs, MCPCommandArgs, ModelsCommandArgs, CommandResult, GenerateResult, StreamChunk, } from "./cli.js";
+export type { TaskType, TaskClassification, ClassificationScores, ClassificationStats, ClassificationValidation, } from "./taskClassificationTypes.js";
 export type { MCPTransportType, MCPServerConnectionStatus, MCPServerCategory, MCPServerStatus, MCPDiscoveredServer, MCPConnectedServer, MCPToolInfo, MCPExecutableTool, MCPServerMetadata, MCPToolMetadata, MCPServerRegistryEntry, } from "./mcpTypes.js";
 export type { ExternalMCPServerInstance, ExternalMCPServerStatus, ExternalMCPToolInfo, ExternalMCPServerHealth, ExternalMCPConfigValidation, ExternalMCPOperationResult, ExternalMCPToolContext, ExternalMCPToolResult, ExternalMCPServerEvents, ExternalMCPManagerConfig, } from "./externalMcp.js";
 export type { ModelCapability, ModelUseCase, ModelFilter, ModelResolutionContext, ModelStats, ModelPricing, } from "./providers.js";

package/dist/lib/types/index.js

@@ -9,6 +9,8 @@ export * from "./tools.js";
 export * from "./providers.js";
 // CLI types
 export * from "./cli.js";
+// Task classification types
+export * from "./taskClassificationTypes.js";
 // Generate types - NEW
 export * from "./generateTypes.js";
 // Analytics types - NEW

package/dist/lib/types/taskClassificationTypes.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Task Classification Types
+ * Type definitions for the task classification system
+ */
+/**
+ * Supported task types for classification
+ */
+export type TaskType = "fast" | "reasoning";
+/**
+ * Result of task classification analysis
+ */
+export interface TaskClassification {
+    /** The classified task type */
+    type: TaskType;
+    /** Confidence score (0-1) in the classification */
+    confidence: number;
+    /** Human-readable explanation of the classification decision */
+    reasoning: string;
+}
+/**
+ * Internal scoring data used during classification analysis
+ */
+export interface ClassificationScores {
+    /** Score indicating likelihood of fast task */
+    fastScore: number;
+    /** Score indicating likelihood of reasoning task */
+    reasoningScore: number;
+    /** Array of reasons contributing to the scores */
+    reasons: string[];
+}
+/**
+ * Statistics for batch classification analysis
+ */
+export interface ClassificationStats {
+    /** Total number of prompts analyzed */
+    total: number;
+    /** Number of prompts classified as fast */
+    fast: number;
+    /** Number of prompts classified as reasoning */
+    reasoning: number;
+    /** Average confidence across all classifications */
+    averageConfidence: number;
+}
+/**
+ * Validation result for testing classification accuracy
+ */
+export interface ClassificationValidation {
+    /** Whether the classification matched the expected result */
+    correct: boolean;
+    /** The actual classification result */
+    classification: TaskClassification;
+}

package/dist/lib/types/taskClassificationTypes.js

@@ -0,0 +1,5 @@
+/**
+ * Task Classification Types
+ * Type definitions for the task classification system
+ */
+export {};

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

@@ -0,0 +1,107 @@
+/**
+ * Model Router for NeuroLink Orchestration
+ * Routes tasks to optimal models based on classification and requirements
+ */
+import type { TaskType } from "../types/taskClassificationTypes.js";
+export interface ModelRoute {
+    provider: string;
+    model: string;
+    reasoning: string;
+    confidence: number;
+}
+export interface ModelRoutingOptions {
+    /** Override the task classification */
+    forceTaskType?: TaskType;
+    /** Require specific performance characteristics */
+    requireFast?: boolean;
+    /** Require specific capability (reasoning, creativity, etc.) */
+    requireCapability?: string;
+    /** Fallback strategy if primary choice fails */
+    fallbackStrategy?: "fast" | "reasoning" | "auto";
+}
+/**
+ * Model configurations for different task types and providers
+ */
+declare const MODEL_CONFIGS: {
+    readonly fast: {
+        readonly primary: {
+            readonly provider: "vertex";
+            readonly model: "gemini-2.5-flash";
+            readonly capabilities: readonly ["speed", "general", "code", "basic-reasoning"];
+            readonly avgResponseTime: 800;
+            readonly costPerToken: 0.0001;
+            readonly reasoning: "Optimized for speed and efficiency via Vertex AI";
+        };
+        readonly fallback: {
+            readonly provider: "vertex";
+            readonly model: "gemini-2.5-pro";
+            readonly capabilities: readonly ["speed", "general", "basic-reasoning"];
+            readonly avgResponseTime: 1200;
+            readonly costPerToken: 0.0002;
+            readonly reasoning: "Vertex AI Gemini Pro fallback";
+        };
+    };
+    readonly reasoning: {
+        readonly primary: {
+            readonly provider: "vertex";
+            readonly model: "claude-sonnet-4@20250514";
+            readonly capabilities: readonly ["reasoning", "analysis", "complex-logic", "code", "creativity"];
+            readonly avgResponseTime: 3000;
+            readonly costPerToken: 0.003;
+            readonly reasoning: "Advanced reasoning and analysis via Claude Sonnet 4 on Vertex AI";
+        };
+        readonly fallback: {
+            readonly provider: "vertex";
+            readonly model: "claude-opus-4@20250514";
+            readonly capabilities: readonly ["reasoning", "analysis", "complex-logic", "code", "creativity", "agentic"];
+            readonly avgResponseTime: 4000;
+            readonly costPerToken: 0.005;
+            readonly reasoning: "Claude Opus 4 fallback on Vertex AI for most complex tasks";
+        };
+    };
+};
+/**
+ * Model Router
+ * Intelligently routes tasks to optimal models based on classification
+ */
+export declare class ModelRouter {
+    /**
+     * Route a prompt to the optimal model configuration
+     */
+    static route(prompt: string, options?: ModelRoutingOptions): ModelRoute;
+    /**
+     * Get fallback route if primary route fails
+     */
+    static getFallbackRoute(prompt: string, primaryRoute: ModelRoute, options?: ModelRoutingOptions): ModelRoute;
+    /**
+     * Determine task type from a model route
+     */
+    private static getTaskTypeFromRoute;
+    /**
+     * Get all available model configurations
+     */
+    static getAvailableModels(): typeof MODEL_CONFIGS;
+    /**
+     * Validate model availability for a given route
+     */
+    static validateRoute(route: ModelRoute): Promise<boolean>;
+    /**
+     * Get routing statistics for multiple prompts
+     */
+    static getRoutingStats(prompts: string[]): {
+        total: number;
+        fastRoutes: number;
+        reasoningRoutes: number;
+        averageConfidence: number;
+        providerDistribution: Record<string, number>;
+    };
+    /**
+     * Estimate cost and performance for a route
+     */
+    static getRouteEstimates(route: ModelRoute, estimatedTokens?: number): {
+        estimatedCost: number;
+        estimatedResponseTime: number;
+        capabilities: string[];
+    };
+}
+export {};