@juspay/neurolink 9.79.3 → 9.80.1

package/dist/cli/factories/commandFactory.js

@@ -11,6 +11,7 @@ import { normalizeEvaluationData } from "../../lib/utils/evaluationUtils.js";
 import { logger } from "../../lib/utils/logger.js";
 import { createThinkingConfigFromRecord } from "../../lib/utils/thinkingConfig.js";
 import { buildToolRoutingConfigFromCli } from "../utils/toolRoutingFlags.js";
+import { buildClassifierRouterConfigFromCli } from "../utils/classifierRouterFlags.js";
 import { configManager } from "../commands/config.js";
 import { MCPCommandFactory } from "../commands/mcp.js";
 import { ModelsCommandFactory } from "../commands/models.js";
@@ -577,6 +578,43 @@ export class CLICommandFactory {
             description: "Path to a JSON file OR inline JSON array of {id, description} server descriptors for the routable catalog.",
             alias: "tool-routing-servers",
         },
+        // Classifier-router options
+        classifierRouter: {
+            type: "boolean",
+            description: "Enable the classifier router: classify each request and pick a model (and tools) from --classifier-pool.",
+            alias: "classifier-router",
+        },
+        classifierStrategy: {
+            type: "string",
+            description: "Classifier strategy: 'heuristic' (default, no LLM) or 'llm' (a cheap model picks per prompt).",
+            choices: ["heuristic", "llm"],
+            alias: "classifier-strategy",
+        },
+        classifierModelProvider: {
+            type: "string",
+            description: "Provider for the LLM classifier model (strategy=llm).",
+            alias: "classifier-model-provider",
+        },
+        classifierModelName: {
+            type: "string",
+            description: "Model name for the LLM classifier model (strategy=llm).",
+            alias: "classifier-model-name",
+        },
+        classifierModelRegion: {
+            type: "string",
+            description: "Region for the LLM classifier model (strategy=llm).",
+            alias: "classifier-model-region",
+        },
+        classifierPool: {
+            type: "string",
+            description: "Path to a JSON file OR inline JSON array of pool members: { provider, model?, region?, description?, tiers?, cost?, quality?, id? }.",
+            alias: "classifier-pool",
+        },
+        classifierTimeout: {
+            type: "number",
+            description: "LLM classifier hard timeout in milliseconds.",
+            alias: "classifier-timeout",
+        },
         region: {
             type: "string",
             description: "Vertex AI region (e.g., us-central1, europe-west1, asia-northeast1)",
@@ -868,6 +906,14 @@ export class CLICommandFactory {
             toolRoutingRouterRegion: argv.toolRoutingRouterRegion,
             toolRoutingAlwaysInclude: argv.toolRoutingAlwaysInclude,
             toolRoutingServers: argv.toolRoutingServers,
+            // Classifier-router flags — constructor-level config (see note above).
+            classifierRouter: argv.classifierRouter,
+            classifierStrategy: argv.classifierStrategy,
+            classifierModelProvider: argv.classifierModelProvider,
+            classifierModelName: argv.classifierModelName,
+            classifierModelRegion: argv.classifierModelRegion,
+            classifierPool: argv.classifierPool,
+            classifierTimeout: argv.classifierTimeout,
         };
     }
     /**
@@ -2269,6 +2315,11 @@ export class CLICommandFactory {
             if (toolRoutingConfig) {
                 globalSession.setToolRoutingConfig(toolRoutingConfig);
             }
+            // Inject classifier-router config into the SDK instance before constructing it.
+            const classifierRouterConfig = buildClassifierRouterConfigFromCli(options);
+            if (classifierRouterConfig) {
+                globalSession.setClassifierRouterConfig(classifierRouterConfig);
+            }
             // Initialize SDK and session
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
@@ -2504,6 +2555,11 @@ export class CLICommandFactory {
         if (toolRoutingConfig) {
             globalSession.setToolRoutingConfig(toolRoutingConfig);
         }
+        // Inject classifier-router config into the SDK instance before constructing it.
+        const classifierRouterConfig = buildClassifierRouterConfigFromCli(options);
+        if (classifierRouterConfig) {
+            globalSession.setClassifierRouterConfig(classifierRouterConfig);
+        }
         const sdk = globalSession.getOrCreateNeuroLink();
         const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
         const enhancedOptions = { ...options, ...sessionVariables };
@@ -2985,6 +3041,11 @@ export class CLICommandFactory {
             if (toolRoutingConfig) {
                 globalSession.setToolRoutingConfig(toolRoutingConfig);
             }
+            // Inject classifier-router config into the SDK instance before constructing it.
+            const classifierRouterConfig = buildClassifierRouterConfigFromCli(options);
+            if (classifierRouterConfig) {
+                globalSession.setClassifierRouterConfig(classifierRouterConfig);
+            }
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };

package/dist/cli/utils/classifierRouterFlags.d.ts

@@ -0,0 +1,19 @@
+/**
+ * CLI helper: parse --classifier-* flags into a ClassifierRouterConfig.
+ *
+ * Side-effect-free so it can be unit-tested without a running NeuroLink
+ * instance. Mirrors the `--tool-routing-*` flag parser.
+ */
+import type { CliClassifierRouterFlags, ClassifierRouterConfig } from "../../lib/types/index.js";
+/**
+ * Build a {@link ClassifierRouterConfig} from the parsed CLI flags.
+ *
+ * Returns `undefined` when `--classifier-router` is absent or false, so callers
+ * can skip the setter entirely with a simple truthiness check.
+ *
+ * `--classifier-pool` is parsed permissively:
+ * - If the value is an existing file path, the file is read and JSON-parsed.
+ * - Otherwise the value is treated as an inline JSON string.
+ * - On any parse error a warning is logged and the pool is left empty.
+ */
+export declare function buildClassifierRouterConfigFromCli(flags: CliClassifierRouterFlags & Record<string, unknown>): ClassifierRouterConfig | undefined;

package/dist/cli/utils/classifierRouterFlags.js

@@ -0,0 +1,111 @@
+/**
+ * CLI helper: parse --classifier-* flags into a ClassifierRouterConfig.
+ *
+ * Side-effect-free so it can be unit-tested without a running NeuroLink
+ * instance. Mirrors the `--tool-routing-*` flag parser.
+ */
+import fs from "node:fs";
+import { logger } from "../../lib/utils/logger.js";
+// Trust model: --classifier-pool is a local, user-supplied CLI flag. The
+// invoking user already holds the process's OS permissions, so absolute and
+// home-dir config paths are fully supported — there is no cross-trust boundary
+// to enforce (a local CLI reading a path its own operator passed is not a
+// path-traversal vector). The caps below are a robustness guard against
+// accidentally pointing at a huge file (e.g. a log or binary), not a security
+// boundary.
+const MAX_POOL_INPUT_BYTES = 1_000_000; // 1 MB
+const MAX_POOL_ENTRIES = 1_000;
+/**
+ * Build a {@link ClassifierRouterConfig} from the parsed CLI flags.
+ *
+ * Returns `undefined` when `--classifier-router` is absent or false, so callers
+ * can skip the setter entirely with a simple truthiness check.
+ *
+ * `--classifier-pool` is parsed permissively:
+ * - If the value is an existing file path, the file is read and JSON-parsed.
+ * - Otherwise the value is treated as an inline JSON string.
+ * - On any parse error a warning is logged and the pool is left empty.
+ */
+export function buildClassifierRouterConfigFromCli(flags) {
+    if (!flags.classifierRouter) {
+        return undefined;
+    }
+    const strategy = flags.classifierStrategy === "llm" ? "llm" : "heuristic";
+    const pool = typeof flags.classifierPool === "string" &&
+        flags.classifierPool.trim() !== ""
+        ? parsePoolFlag(flags.classifierPool)
+        : [];
+    if (pool.length === 0) {
+        logger.warn("[classifier-router] --classifier-router is enabled but --classifier-pool is empty/missing; model routing is a no-op until a pool is provided.");
+    }
+    const config = {
+        enabled: true,
+        classifier: strategy,
+        pool,
+    };
+    if (flags.classifierTimeout !== undefined) {
+        const t = flags.classifierTimeout;
+        if (Number.isFinite(t) && t > 0) {
+            config.timeoutMs = t;
+        }
+        else {
+            logger.warn(`[classifier-router] --classifier-timeout value ${String(t)} is not a positive finite number; ignoring (SDK default applies).`);
+        }
+    }
+    const hasProvider = typeof flags.classifierModelProvider === "string";
+    const hasModel = typeof flags.classifierModelName === "string";
+    const hasRegion = typeof flags.classifierModelRegion === "string";
+    if (hasProvider || hasModel || hasRegion) {
+        config.classifierModel = {
+            ...(hasProvider && {
+                provider: flags.classifierModelProvider,
+            }),
+            ...(hasModel && { model: flags.classifierModelName }),
+            ...(hasRegion && { region: flags.classifierModelRegion }),
+        };
+    }
+    return config;
+}
+/**
+ * Parse the `--classifier-pool` value (file path first, then inline JSON).
+ * Logs a warning and returns `[]` on any error (fail open).
+ */
+function parsePoolFlag(value) {
+    try {
+        const resolved = fs.existsSync(value) ? value : null;
+        if (resolved !== null) {
+            const { size } = fs.statSync(resolved);
+            if (size > MAX_POOL_INPUT_BYTES) {
+                logger.warn(`[classifier-router] --classifier-pool file exceeds ${MAX_POOL_INPUT_BYTES} bytes (got ${size}); ignoring.`);
+                return [];
+            }
+        }
+        else if (Buffer.byteLength(value, "utf8") > MAX_POOL_INPUT_BYTES) {
+            logger.warn(`[classifier-router] --classifier-pool inline JSON exceeds ${MAX_POOL_INPUT_BYTES} bytes; ignoring.`);
+            return [];
+        }
+        const jsonText = resolved ? fs.readFileSync(resolved, "utf8") : value;
+        const parsed = JSON.parse(jsonText);
+        if (!Array.isArray(parsed)) {
+            logger.warn("[classifier-router] --classifier-pool must be a JSON array; ignoring.");
+            return [];
+        }
+        // Validate loosely — every member must at least name a provider.
+        const valid = parsed.filter((entry) => typeof entry === "object" &&
+            entry !== null &&
+            typeof entry.provider === "string");
+        if (valid.length !== parsed.length) {
+            logger.warn(`[classifier-router] ${parsed.length - valid.length} pool member(s) skipped — each must have a string "provider" field.`);
+        }
+        if (valid.length > MAX_POOL_ENTRIES) {
+            logger.warn(`[classifier-router] --classifier-pool has ${valid.length} entries; truncating to ${MAX_POOL_ENTRIES}.`);
+            return valid.slice(0, MAX_POOL_ENTRIES);
+        }
+        return valid;
+    }
+    catch (err) {
+        logger.warn(`[classifier-router] Failed to parse --classifier-pool: ${err.message}. Using empty pool (fail open).`);
+        return [];
+    }
+}
+//# sourceMappingURL=classifierRouterFlags.js.map

package/dist/index.d.ts

@@ -367,7 +367,7 @@ export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLO
  * });
  * ```
  */
-export { classifyProviderError, ModelPool, createDefaultRequestRouter, } from "./routing/index.js";
+export { classifyProviderError, ModelPool, createDefaultRequestRouter, ClassifierRouter, classifyHeuristic, } from "./routing/index.js";
 /**
  * Server Adapters for exposing NeuroLink as HTTP APIs
  *

package/dist/index.js

@@ -574,7 +574,7 @@ export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLO
  * });
  * ```
  */
-export { classifyProviderError, ModelPool, createDefaultRequestRouter, } from "./routing/index.js";
+export { classifyProviderError, ModelPool, createDefaultRequestRouter, ClassifierRouter, classifyHeuristic, } from "./routing/index.js";
 // ============================================================================
 // SERVER ADAPTERS - HTTP API Framework Integration
 // ============================================================================

package/dist/lib/index.d.ts

@@ -367,7 +367,7 @@ export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLO
  * });
  * ```
  */
-export { classifyProviderError, ModelPool, createDefaultRequestRouter, } from "./routing/index.js";
+export { classifyProviderError, ModelPool, createDefaultRequestRouter, ClassifierRouter, classifyHeuristic, } from "./routing/index.js";
 /**
  * Server Adapters for exposing NeuroLink as HTTP APIs
  *

package/dist/lib/index.js

@@ -574,7 +574,7 @@ export { createMultiJudgeWorkflow, MULTI_JUDGE_3_WORKFLOW, MULTI_JUDGE_5_WORKFLO
  * });
  * ```
  */
-export { classifyProviderError, ModelPool, createDefaultRequestRouter, } from "./routing/index.js";
+export { classifyProviderError, ModelPool, createDefaultRequestRouter, ClassifierRouter, classifyHeuristic, } from "./routing/index.js";
 // ============================================================================
 // SERVER ADAPTERS - HTTP API Framework Integration
 // ============================================================================

package/dist/lib/neurolink.d.ts

@@ -112,6 +112,7 @@ export declare class NeuroLink {
     private readonly fallbackConfig;
     private readonly modelPool;
     private readonly requestRouter;
+    private readonly classifierRouter;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -634,6 +635,19 @@ export declare class NeuroLink {
      * @param thinkingLevel — optional thinking level string from the call options.
      */
     private applyRequestRouter;
+    /**
+     * Applies the host-configured `classifierRouter` to `options` in place.
+     *
+     * Classifies the request by difficulty and selects a provider/model from the
+     * configured base pool (cheaper/faster for easy tasks, more capable for hard
+     * ones), and optionally narrows the tool set via `toolFilter`/`excludeTools`.
+     *
+     * Skipped when: no router is configured; the inbound call is the classifier's
+     * own generate() (marked `__classifierRouted`); the caller pinned BOTH
+     * provider and model; or a ModelPool is configured (the pool owns selection).
+     * Fails open — any error leaves options unchanged.
+     */
+    private applyClassifierRouting;
     private prepareGenerateAugmentations;
     private buildGenerateTextOptions;
     private finalizeGenerateRequestResult;

package/dist/lib/neurolink.js

@@ -87,6 +87,7 @@ import { isNonNullObject } from "./utils/typeUtils.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
 import { ModelPool, classifyProviderError } from "./routing/index.js";
+import { ClassifierRouter } from "./routing/classifierRouter.js";
 import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, } from "./utils/providerErrorClassification.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
@@ -388,6 +389,9 @@ export class NeuroLink {
     // RequestRouter: pluggable pre-call provider/model selector.
     // Stored directly from config.requestRouter; null when not configured.
     requestRouter;
+    // ClassifierRouter: opt-in "classify → pick model + tools" pre-call router.
+    // Built from config.classifierRouter; null when not configured.
+    classifierRouter;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -796,6 +800,17 @@ export class NeuroLink {
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
         this.requestRouter = config?.requestRouter ?? null;
+        // ClassifierRouter: opt-in. The LLM strategy reuses this instance's
+        // generate() (marked so it never recursively re-routes). Fails open.
+        this.classifierRouter = config?.classifierRouter?.enabled
+            ? new ClassifierRouter(config.classifierRouter, {
+                generate: (genOptions) => this.generate(genOptions),
+                logger: {
+                    debug: (message, meta) => logger.debug(message, meta),
+                    warn: (message, meta) => logger.warn(message, meta),
+                },
+            })
+            : null;
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -3105,6 +3120,13 @@ Current user's request: ${currentInput}`;
     }
     async runStandardGenerateRequest(options, originalPrompt, generateSpan) {
         const startTime = Date.now();
+        // Pre-call classifier router: opt-in. Classifies the request and selects a
+        // provider/model from the configured base pool (and optionally narrows the
+        // tool set) BEFORE orchestration/requestRouter, so it takes precedence.
+        // Fails open.
+        await this.applyClassifierRouting(options, options.input?.text ?? originalPrompt ?? "", !options.disableTools &&
+            (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options.thinkingConfig?.thinkingLevel);
         await this.maybeApplyGenerateOrchestration(options);
         // Pre-call request router: opt-in, only when the caller did not set both
         // provider+model. Fails open (any router error leaves options unchanged).
@@ -3241,6 +3263,12 @@ Current user's request: ${currentInput}`;
         if (!this.requestRouter) {
             return;
         }
+        // Stand down if the classifier router already selected a provider/model on
+        // this turn — one explicit precedence order: classifierRouter wins.
+        if (options.context
+            ?.__classifierRouted) {
+            return;
+        }
         // Skip if the caller explicitly set both provider AND model — they know
         // what they want; the router should not override an intentional choice.
         if (options.provider && options.model) {
@@ -3307,6 +3335,103 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Applies the host-configured `classifierRouter` to `options` in place.
+     *
+     * Classifies the request by difficulty and selects a provider/model from the
+     * configured base pool (cheaper/faster for easy tasks, more capable for hard
+     * ones), and optionally narrows the tool set via `toolFilter`/`excludeTools`.
+     *
+     * Skipped when: no router is configured; the inbound call is the classifier's
+     * own generate() (marked `__classifierRouted`); the caller pinned BOTH
+     * provider and model; or a ModelPool is configured (the pool owns selection).
+     * Fails open — any error leaves options unchanged.
+     */
+    async applyClassifierRouting(options, promptText, hasTools, requiresVision, thinkingLevel) {
+        if (!this.classifierRouter) {
+            return;
+        }
+        const opt = options;
+        // Prevent recursion: the LLM classifier itself calls generate() with this
+        // marker set. Also respect any explicit prior routing decision.
+        if (opt.context?.__classifierRouted) {
+            return;
+        }
+        // Honor an intentional caller choice of BOTH provider and model.
+        if (options.provider && options.model) {
+            return;
+        }
+        // A ModelPool overrides provider/model per member unconditionally; let it
+        // own selection (mirrors applyRequestRouter precedence).
+        if (this.modelPool) {
+            logger.debug("[NeuroLink] applyClassifierRouting: skipped — modelPool takes precedence");
+            return;
+        }
+        const sessionId = typeof opt.context?.sessionId === "string"
+            ? opt.context.sessionId
+            : undefined;
+        try {
+            const decision = await this.classifierRouter.route({
+                prompt: promptText,
+                estimatedInputTokens: Math.ceil((promptText?.length ?? 0) / 4),
+                hasTools,
+                requiresVision,
+                thinkingLevel,
+                sessionId,
+            });
+            if (!decision) {
+                return;
+            }
+            // Apply provider/model/region as a coherent set (same discipline as
+            // applyRequestRouter): only fill fields the caller did not pin.
+            if (decision.provider && !options.provider) {
+                options.provider = decision.provider;
+                if (decision.model && !options.model) {
+                    options.model = decision.model;
+                }
+                if (decision.region && !options.region) {
+                    options.region = decision.region;
+                }
+            }
+            else if (!decision.provider && decision.model && !options.model) {
+                options.model = decision.model;
+            }
+            // Narrow tools unless the caller disabled tools entirely.
+            if (!opt.disableTools) {
+                if (decision.excludeTools && decision.excludeTools.length > 0) {
+                    opt.excludeTools = Array.from(new Set([...(opt.excludeTools ?? []), ...decision.excludeTools]));
+                }
+                if (decision.toolFilter && decision.toolFilter.length > 0) {
+                    const allow = decision.toolFilter;
+                    opt.toolFilter =
+                        opt.toolFilter && opt.toolFilter.length > 0
+                            ? opt.toolFilter.filter((t) => allow.includes(t))
+                            : [...allow];
+                }
+            }
+            // Mark routed so orchestration/requestRouter stand down this turn.
+            if (decision.provider || decision.model) {
+                const ctx = opt.context ?? {};
+                ctx.__classifierRouted = true;
+                opt.context = ctx;
+            }
+            if (decision.reason) {
+                logger.debug("[NeuroLink] classifierRouter decision", {
+                    reason: decision.reason,
+                    difficulty: decision.difficulty,
+                    provider: options.provider,
+                    model: options.model,
+                });
+            }
+        }
+        catch (classifierErr) {
+            logger.warn("[NeuroLink] classifierRouter threw — proceeding unrouted", {
+                error: classifierErr instanceof Error
+                    ? classifierErr.message
+                    : String(classifierErr),
+            });
+        }
+    }
     async prepareGenerateAugmentations(options) {
         if (options.rag?.files?.length) {
             try {
@@ -5829,6 +5954,12 @@ Current user's request: ${currentInput}`;
             // classify correctly. After the workflow short-circuit, so workflow
             // streams skip it.
             await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, () => this.applyToolRoutingExclusions(options, originalPrompt)));
+            // Pre-call classifier router for stream: opt-in, fails open. Runs before
+            // the request router so it takes precedence.
+            await this.applyClassifierRouting(options, originalPrompt, !options.disableTools &&
+                (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                    this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options
+                .thinking?.thinkingLevel);
             // Pre-call request router for stream: opt-in, fails open.
             await this.applyRequestRouter(options, originalPrompt, !options.disableTools &&
                 (!!(options.tools && Object.keys(options.tools).length > 0) ||

package/dist/lib/providers/googleVertex.d.ts

@@ -1,8 +1,10 @@
 import type { ZodType } from "zod";
 import { AIProviderName } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
-import type { EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult } from "../types/index.js";
+import type { EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult, VertexAnthropicMessage, ChatMessage, MinimalChatMessage } from "../types/index.js";
 import type { Schema, LanguageModel } from "../types/index.js";
+export declare function buildAnthropicHistoryMessages(conversationMessages: Array<ChatMessage | MinimalChatMessage>): VertexAnthropicMessage[];
+export declare function appendUserMessage(messages: VertexAnthropicMessage[], content: VertexAnthropicMessage["content"]): void;
 /**
  * Recursively strip JSON-schema fields that Vertex Gemini's function-call AND
  * `responseSchema` (structured output) validators reject with 400