@juspay/neurolink 9.79.3 → 9.80.1

package/dist/types/classifierRouter.d.ts

@@ -0,0 +1,193 @@
+/**
+ * ClassifierRouter types — generic "classify → pick model + tools → run".
+ *
+ * A ClassifierRouter inspects an incoming request, classifies it by difficulty
+ * (and optional required capabilities / suggested tools), then selects a
+ * provider/model from a host-declared "available base" pool — routing harder
+ * tasks to more capable models and easier tasks to cheaper/faster ones — and
+ * optionally narrows the tool set for that request.
+ *
+ * It is entirely opt-in (constructor config, `enabled: false` by default) and
+ * fails open: any classifier or selection error leaves the call unrouted.
+ *
+ * Type names are domain-prefixed `Classifier*` to stay globally unique across
+ * `src/lib/types/` (see CLAUDE.md rule 9).
+ */
+/** Coarse difficulty buckets the classifier maps a request into. */
+export type ClassifierDifficulty = "trivial" | "simple" | "moderate" | "hard" | "expert";
+/** Which classification strategy to run. */
+export type ClassifierStrategyKind = "heuristic" | "llm";
+/**
+ * The classifier's verdict for a single request. Strategy-agnostic: produced
+ * by both the heuristic and the LLM classifier.
+ */
+export type ClassifierDecision = {
+    /** The classified difficulty bucket. */
+    difficulty: ClassifierDifficulty;
+    /** Confidence in the classification (0–1). */
+    confidence: number;
+    /** Capability tags the request needs (e.g. "vision", "tools", "reasoning"). */
+    requiredCapabilities?: string[];
+    /** Tool names the classifier thinks the task needs (allowlist hint). */
+    suggestedTools?: string[];
+    /**
+     * When the LLM classifier picks a model directly, the chosen candidate id
+     * (matches a `ClassifierCandidate.id`). Ignored by the heuristic classifier.
+     */
+    selectedModelId?: string;
+    /** Human-readable explanation, emitted at debug level. */
+    reason?: string;
+};
+/**
+ * Lightweight model descriptor handed to the LLM classifier so it can select a
+ * model directly from the pool by `id` — the generic path for custom models.
+ */
+export type ClassifierCandidate = {
+    id: string;
+    provider: string;
+    model?: string;
+    description?: string;
+    tiers?: ClassifierDifficulty[];
+    capabilities?: string[];
+};
+/**
+ * One candidate (provider, model, region) in the available base pool, with
+ * optional routing metadata. When `cost`/`quality`/`capabilities` are omitted,
+ * the router enriches them from the model registry (by `model` name/alias).
+ */
+export type ClassifierRouterPoolMember = {
+    provider: string;
+    model?: string;
+    region?: string;
+    /**
+     * Stable id the LLM classifier references when selecting a model directly.
+     * Defaults to `${provider}/${model}` (or just `provider`) when omitted.
+     */
+    id?: string;
+    /**
+     * Plain-English description of when to use this model (e.g. "cheap & fast,
+     * for simple Q&A" / "powerful reasoning model for complex analysis"). Drives
+     * LLM-based model selection — the only metadata needed for custom models that
+     * are NOT in the registry (LiteLLM, OpenAI-compatible, self-hosted, …).
+     */
+    description?: string;
+    /** Difficulty tiers this member is eligible for. Omit = eligible for all. */
+    tiers?: ClassifierDifficulty[];
+    /** Relative cost (lower = cheaper). Preferred for easy tiers. */
+    cost?: number;
+    /** Relative quality/capability (higher = more capable). Preferred for hard tiers. */
+    quality?: number;
+    /** Capability tags this member supports (e.g. "vision", "tools"). */
+    capabilities?: string[];
+    /** Tiebreak weight when scores are equal. Default: 1. */
+    weight?: number;
+};
+/** Per-difficulty tool policy applied to the request. */
+export type ClassifierToolDirective = {
+    /** Allowlist of tool names to keep (maps to `options.toolFilter`). */
+    toolFilter?: string[];
+    /** Denylist of tool names to drop (appended to `options.excludeTools`). */
+    excludeTools?: string[];
+};
+/** Provider/model the LLM classifier strategy itself runs on. */
+export type ClassifierModelRef = {
+    provider?: string;
+    model?: string;
+    region?: string;
+    temperature?: number;
+};
+/** Constructor-level configuration for the classifier router. */
+export type ClassifierRouterConfig = {
+    /** Master switch. When false/absent, the router is never built. */
+    enabled: boolean;
+    /**
+     * Classification strategy. Default: "heuristic" (no LLM, zero added latency).
+     * "llm" runs a cheap classifier model (see `classifierModel`).
+     */
+    classifier?: ClassifierStrategyKind;
+    /** Model used by the "llm" strategy. Defaults to provider/model auto. */
+    classifierModel?: ClassifierModelRef;
+    /** The available base pool the router selects a model from. */
+    pool: ClassifierRouterPoolMember[];
+    /**
+     * Explicit difficulty → members map. When a difficulty has entries here they
+     * take precedence over metadata scoring of `pool`.
+     */
+    tierMap?: Partial<Record<ClassifierDifficulty, ClassifierRouterPoolMember[]>>;
+    /** Per-difficulty tool directives applied to the request. */
+    toolDirectives?: Partial<Record<ClassifierDifficulty, ClassifierToolDirective>>;
+    /** Hard timeout (ms) for the LLM classifier call. Default: 8000. */
+    timeoutMs?: number;
+};
+/**
+ * The router's combined decision: a provider/model/region override plus an
+ * optional tool narrowing. Any undefined field means "keep what the caller
+ * already configured". Returning `null` from the router is a valid no-op.
+ */
+export type ClassifierRouterDecision = {
+    provider?: string;
+    model?: string;
+    region?: string;
+    /** Allowlist applied to `options.toolFilter`. */
+    toolFilter?: string[];
+    /** Denylist appended to `options.excludeTools`. */
+    excludeTools?: string[];
+    /** The difficulty this decision was made for (debug/telemetry). */
+    difficulty?: ClassifierDifficulty;
+    /** Remaining ranked candidates, best-first, for downstream failover. */
+    modelFallbacks?: ClassifierRouterPoolMember[];
+    /** Human-readable explanation, emitted at debug level. */
+    reason?: string;
+};
+/** Lightweight request snapshot handed to the router. */
+export type ClassifierRouterInput = {
+    prompt: string;
+    estimatedInputTokens?: number;
+    hasTools?: boolean;
+    requiresVision?: boolean;
+    thinkingLevel?: string;
+    sessionId?: string;
+};
+/** Enriched per-model metadata used while ranking pool members. */
+export type ClassifierModelMeta = {
+    cost?: number;
+    quality?: number;
+    capabilities?: string[];
+};
+/** Minimal options accepted by the injected LLM-classifier `generate` fn. */
+export type ClassifierGenerateOptions = {
+    input: {
+        text: string;
+    };
+    systemPrompt?: string;
+    provider?: string;
+    model?: string;
+    region?: string;
+    temperature?: number;
+    maxTokens?: number;
+    disableTools?: boolean;
+    schema?: unknown;
+    timeout?: number | string;
+    context?: Record<string, unknown>;
+};
+/** Minimal result shape the LLM classifier reads back. */
+export type ClassifierGenerateResult = {
+    content?: string;
+    structuredData?: unknown;
+};
+/** Injected LLM caller — typically a bound `NeuroLink.generate`. */
+export type ClassifierGenerateFn = (options: ClassifierGenerateOptions) => Promise<ClassifierGenerateResult>;
+/** Minimal logger surface the router uses (debug/warn). */
+export type ClassifierLogger = {
+    debug: (message: string, meta?: unknown) => void;
+    warn: (message: string, meta?: unknown) => void;
+};
+/**
+ * Injected dependencies — keep `ClassifierRouter` provider-import-free and
+ * unit-testable (mirrors the `toolRouting` generateFn-injection pattern).
+ */
+export type ClassifierRouterDeps = {
+    /** LLM caller for the "llm" strategy. Omit to disable LLM classification. */
+    generate?: ClassifierGenerateFn;
+    logger?: ClassifierLogger;
+};

package/dist/types/classifierRouter.js

@@ -0,0 +1,16 @@
+/**
+ * ClassifierRouter types — generic "classify → pick model + tools → run".
+ *
+ * A ClassifierRouter inspects an incoming request, classifies it by difficulty
+ * (and optional required capabilities / suggested tools), then selects a
+ * provider/model from a host-declared "available base" pool — routing harder
+ * tasks to more capable models and easier tasks to cheaper/faster ones — and
+ * optionally narrows the tool set for that request.
+ *
+ * It is entirely opt-in (constructor config, `enabled: false` by default) and
+ * fails open: any classifier or selection error leaves the call unrouted.
+ *
+ * Type names are domain-prefixed `Classifier*` to stay globally unique across
+ * `src/lib/types/` (see CLAUDE.md rule 9).
+ */
+export {};

package/dist/types/cli.d.ts

@@ -45,7 +45,7 @@ export type BaseCommandArgs = {
 /**
  * Generate command arguments
  */
-export type GenerateCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
+export type GenerateCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
     /** Input text or prompt */
     input?: string;
     /** AI provider to use */
@@ -110,7 +110,7 @@ export type GenerateCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
 /**
  * Stream command arguments
  */
-export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
+export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
     /** Input text or prompt */
     input?: string;
     /** AI provider to use */
@@ -137,7 +137,7 @@ export type StreamCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
 /**
  * Batch command arguments
  */
-export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & {
+export type BatchCommandArgs = BaseCommandArgs & CliToolRoutingFlags & CliClassifierRouterFlags & {
     /** Input file path */
     file?: string;
     /** AI provider to use */
@@ -1526,3 +1526,27 @@ export type CliToolRoutingFlags = {
      */
     toolRoutingServers?: string;
 };
+/**
+ * CLI flags for the classifier router (`--classifier-*`). Builds a
+ * ClassifierRouterConfig that is injected at SDK construction time.
+ */
+export type CliClassifierRouterFlags = {
+    /** Master enable switch (--classifier-router). */
+    classifierRouter?: boolean;
+    /** Strategy: "heuristic" (default) or "llm" (--classifier-strategy). */
+    classifierStrategy?: string;
+    /** LLM-classifier provider override (--classifier-model-provider). */
+    classifierModelProvider?: string;
+    /** LLM-classifier model override (--classifier-model-name). */
+    classifierModelName?: string;
+    /** LLM-classifier region override (--classifier-model-region). */
+    classifierModelRegion?: string;
+    /**
+     * Path to a JSON file OR inline JSON array of pool members
+     * (--classifier-pool). Each entry: { provider, model?, region?, description?,
+     * tiers?, cost?, quality?, capabilities?, id? }.
+     */
+    classifierPool?: string;
+    /** LLM-classifier hard timeout in ms (--classifier-timeout). */
+    classifierTimeout?: number;
+};

package/dist/types/config.d.ts

@@ -11,6 +11,7 @@ import type { AuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, C
 import type { NeurolinkCredentials } from "./providers.js";
 import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
+import type { ClassifierRouterConfig } from "./classifierRouter.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -104,6 +105,15 @@ export type NeurolinkConstructorConfig = {
      * error proceeds unrouted.
      */
     requestRouter?: RequestRouter;
+    /**
+     * Pre-call classifier router: classifies each request by difficulty and
+     * selects a provider/model from a configured "available base" pool — routing
+     * harder tasks to more capable models and easier tasks to cheaper/faster
+     * ones — and optionally narrows the tool set. Opt-in (`enabled: false` by
+     * default) and fails open. Skipped when a `modelPool` is configured or the
+     * caller pinned both `provider` and `model`. See {@link ClassifierRouterConfig}.
+     */
+    classifierRouter?: ClassifierRouterConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/index.d.ts

@@ -71,3 +71,4 @@ export * from "./replicate.js";
 export * from "./safeFetch.js";
 export * from "./modelPool.js";
 export * from "./requestRouter.js";
+export * from "./classifierRouter.js";

package/dist/types/index.js

@@ -80,3 +80,5 @@ export * from "./safeFetch.js";
 export * from "./modelPool.js";
 // RequestRouter — pluggable pre-call provider/model selection (M9.x+)
 export * from "./requestRouter.js";
+// ClassifierRouter — classify → pick model + tools from a base pool (M9.x+)
+export * from "./classifierRouter.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.79.3",
+  "version": "9.80.1",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, voice (TTS/STT/realtime), and professional CLI. 58+ external MCP servers discoverable, multimodal file processing, RAG pipelines. Build, test, and deploy AI applications with 21+ providers: OpenAI, Anthropic, Google AI Studio, Google Vertex, AWS Bedrock, Azure OpenAI, Mistral, LiteLLM, SageMaker, Hugging Face, Ollama, OpenAI-compatible, OpenRouter, DeepSeek, NVIDIA NIM, LM Studio, llama.cpp, plus voice (OpenAI TTS, ElevenLabs, Deepgram, Azure Speech).",
   "author": {
@@ -132,6 +132,7 @@
     "// CI tier — fast, no live AI calls, safe for every commit": "",
     "test:unit:vitest": "pnpm exec vitest run test/toolRouting.test.ts",
     "test:tool-routing": "pnpm run test:unit:vitest && npx tsx test/continuous-test-suite-tool-routing.ts",
+    "test:classifier-router": "npx tsx test/continuous-test-suite-classifier-router.ts",
     "test:tool-routing-semantic:vitest": "pnpm exec vitest run test/toolRoutingSemantic.test.ts",
     "test:tool-routing-semantic": "pnpm run test:tool-routing-semantic:vitest && npx tsx test/continuous-test-suite-tool-routing-semantic.ts",
     "test:unit": "pnpm run test:envguard && pnpm run test:bugfixes && pnpm run test:mcp:infra && pnpm run test:mcp:bash && pnpm run test:mcp:limits && pnpm run test:mcp:spans && pnpm run test:autoresearch:redis && pnpm run test:unit:vitest && pnpm run test:tool-routing-cli:vitest && pnpm run test:tool-dedup:vitest && pnpm run test:model-pool:vitest && pnpm run test:tool-routing-semantic:vitest && pnpm run test:anthropic-tools-policy && pnpm run test:anthropic-multimodal && pnpm run test:excel-interop",