@juspay/neurolink 9.79.2 → 9.80.0

package/dist/routing/classifierRouter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ClassifierRouter — the single "classify → pick model + tools → run" engine.
+ *
+ * Given a request snapshot it (1) classifies difficulty (heuristic or a cheap
+ * LLM), (2) selects the best provider/model from the host-declared base pool —
+ * cheaper/faster for easy tiers, more capable for hard tiers — enriching pool
+ * members with real cost/quality metadata from the model registry, and
+ * (3) narrows the tool set via per-difficulty directives or classifier hints.
+ *
+ * Pure of provider imports (mirrors ModelPool): the LLM caller is injected.
+ * The only data dependency is the read-only `ModelResolver` registry lookup,
+ * used purely for metadata enrichment and never for provider construction.
+ */
+import type { ClassifierRouterConfig, ClassifierRouterDecision, ClassifierRouterDeps, ClassifierRouterInput } from "../types/index.js";
+export declare class ClassifierRouter {
+    private readonly config;
+    private readonly deps;
+    private readonly metaCache;
+    constructor(config: ClassifierRouterConfig, deps?: ClassifierRouterDeps);
+    /**
+     * Classify the request and produce a combined model + tool decision, or
+     * `null` when nothing should change. Never throws (fails open).
+     */
+    route(input: ClassifierRouterInput): Promise<ClassifierRouterDecision | null>;
+    /** Run the configured strategy; LLM falls back to heuristic on failure. */
+    private classify;
+    /**
+     * Build LLM-facing model descriptors + an id→member map so the classifier can
+     * pick a model directly. Works for ANY pool, registry-backed or not.
+     */
+    private buildCandidates;
+    /**
+     * Resolve the ranked model list for a decision. Prefers the LLM's direct pick
+     * (`selectedModelId`); otherwise falls back to difficulty-based tierMap /
+     * metadata scoring.
+     */
+    private selectModels;
+    /** Candidate members for a difficulty: explicit tierMap or eligible pool. */
+    private candidatesFor;
+    /** Drop members that cannot satisfy the required capabilities (lenient). */
+    private filterByCapabilities;
+    /** Rank candidates best-first for the difficulty's strategy. */
+    private rank;
+    /** Tool narrowing: per-difficulty directive, then classifier hints. */
+    private selectTools;
+    /**
+     * Resolve cost/quality/capabilities for a member. Declared values win;
+     * gaps are filled from the model registry (by model name/alias) when known.
+     * Results are cached per (provider/model) for the router's lifetime.
+     */
+    private metaFor;
+}

package/dist/routing/classifierRouter.js

@@ -0,0 +1,268 @@
+/**
+ * ClassifierRouter — the single "classify → pick model + tools → run" engine.
+ *
+ * Given a request snapshot it (1) classifies difficulty (heuristic or a cheap
+ * LLM), (2) selects the best provider/model from the host-declared base pool —
+ * cheaper/faster for easy tiers, more capable for hard tiers — enriching pool
+ * members with real cost/quality metadata from the model registry, and
+ * (3) narrows the tool set via per-difficulty directives or classifier hints.
+ *
+ * Pure of provider imports (mirrors ModelPool): the LLM caller is injected.
+ * The only data dependency is the read-only `ModelResolver` registry lookup,
+ * used purely for metadata enrichment and never for provider construction.
+ */
+import { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";
+import { ModelResolver } from "../models/modelResolver.js";
+/** Maps a registry quality enum to a comparable numeric score. */
+const QUALITY_SCORE = { high: 3, medium: 2, low: 1 };
+/** How each difficulty ranks candidate members. */
+const DIFFICULTY_RANK_MODE = {
+    trivial: "cost-asc",
+    simple: "cost-asc",
+    moderate: "balanced",
+    hard: "quality-desc",
+    expert: "quality-desc",
+};
+/** Neutral default for an unknown numeric metric (keeps ordering stable). */
+const NEUTRAL = 0.5;
+/**
+ * Cap on the per-(provider,model) metadata cache so it can't grow unbounded in
+ * long-lived processes with large or dynamic pools. FIFO eviction.
+ */
+const MAX_META_CACHE_ENTRIES = 1000;
+export class ClassifierRouter {
+    config;
+    deps;
+    metaCache = new Map();
+    constructor(config, deps = {}) {
+        this.config = config;
+        this.deps = deps;
+    }
+    /**
+     * Classify the request and produce a combined model + tool decision, or
+     * `null` when nothing should change. Never throws (fails open).
+     */
+    async route(input) {
+        try {
+            // For the LLM strategy, hand the pool to the classifier so it can select
+            // a model directly — the generic path for custom/registry-less models.
+            const useLlm = this.config.classifier === "llm" && !!this.deps.generate;
+            const built = useLlm ? this.buildCandidates() : undefined;
+            const decision = await this.classify(input, built?.descriptors);
+            const ranked = this.selectModels(decision, built?.byId);
+            const primary = ranked[0];
+            const { toolFilter, excludeTools } = this.selectTools(decision);
+            if (!primary && !toolFilter && !excludeTools) {
+                return null;
+            }
+            return {
+                provider: primary?.provider,
+                model: primary?.model,
+                region: primary?.region,
+                difficulty: decision.difficulty,
+                modelFallbacks: ranked.slice(1),
+                toolFilter,
+                excludeTools,
+                reason: decision.reason,
+            };
+        }
+        catch (err) {
+            this.deps.logger?.warn?.("[ClassifierRouter] route failed — no-op", {
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        }
+    }
+    /** Run the configured strategy; LLM falls back to heuristic on failure. */
+    async classify(input, candidates) {
+        if (this.config.classifier === "llm" && this.deps.generate) {
+            try {
+                return await classifyLlm(input, this.deps.generate, this.config.classifierModel, this.config.timeoutMs, candidates);
+            }
+            catch (err) {
+                this.deps.logger?.warn?.("[ClassifierRouter] LLM classify failed — using heuristic", { error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        return classifyHeuristic(input);
+    }
+    /**
+     * Build LLM-facing model descriptors + an id→member map so the classifier can
+     * pick a model directly. Works for ANY pool, registry-backed or not.
+     */
+    buildCandidates() {
+        const pool = this.config.pool ?? [];
+        const byId = new Map();
+        const used = new Set();
+        const descriptors = [];
+        pool.forEach((m, i) => {
+            let id = m.id ?? (m.model ? `${m.provider}/${m.model}` : m.provider);
+            if (used.has(id)) {
+                id = `${id}#${i}`;
+            }
+            used.add(id);
+            byId.set(id, m);
+            descriptors.push({
+                id,
+                provider: m.provider,
+                model: m.model,
+                description: m.description,
+                tiers: m.tiers,
+                capabilities: this.metaFor(m).capabilities,
+            });
+        });
+        return { descriptors, byId };
+    }
+    /**
+     * Resolve the ranked model list for a decision. Prefers the LLM's direct pick
+     * (`selectedModelId`); otherwise falls back to difficulty-based tierMap /
+     * metadata scoring.
+     */
+    selectModels(decision, byId) {
+        if (decision.selectedModelId && byId) {
+            const picked = byId.get(decision.selectedModelId);
+            if (picked) {
+                const rest = (this.config.pool ?? []).filter((m) => m !== picked);
+                const rankedRest = this.rank(this.filterByCapabilities(rest, decision.requiredCapabilities), decision.difficulty);
+                return [picked, ...rankedRest];
+            }
+        }
+        const eligible = this.candidatesFor(decision);
+        const capable = this.filterByCapabilities(eligible, decision.requiredCapabilities);
+        return this.rank(capable, decision.difficulty);
+    }
+    /** Candidate members for a difficulty: explicit tierMap or eligible pool. */
+    candidatesFor(decision) {
+        const tierMembers = this.config.tierMap?.[decision.difficulty];
+        if (tierMembers && tierMembers.length > 0) {
+            return tierMembers;
+        }
+        const pool = this.config.pool ?? [];
+        const eligible = pool.filter((m) => !m.tiers || m.tiers.includes(decision.difficulty));
+        return eligible.length > 0 ? eligible : pool;
+    }
+    /** Drop members that cannot satisfy the required capabilities (lenient). */
+    filterByCapabilities(members, required) {
+        if (!required || required.length === 0) {
+            return members;
+        }
+        const kept = members.filter((m) => {
+            const caps = this.metaFor(m).capabilities;
+            // Unknown capabilities → keep (don't starve the pool on missing metadata).
+            if (!caps || caps.length === 0) {
+                return true;
+            }
+            return required.every((c) => caps.includes(c));
+        });
+        return kept.length > 0 ? kept : members;
+    }
+    /** Rank candidates best-first for the difficulty's strategy. */
+    rank(members, difficulty) {
+        const mode = DIFFICULTY_RANK_MODE[difficulty];
+        const originalIndex = new Map(members.map((m, i) => [m, i]));
+        const num = (v) => (typeof v === "number" ? v : NEUTRAL);
+        return [...members].sort((a, b) => {
+            const ma = this.metaFor(a);
+            const mb = this.metaFor(b);
+            let delta;
+            if (mode === "cost-asc") {
+                delta = num(ma.cost) - num(mb.cost);
+            }
+            else if (mode === "quality-desc") {
+                delta = num(mb.quality) - num(ma.quality);
+            }
+            else {
+                // balanced: maximize quality-minus-cost
+                delta =
+                    num(mb.quality) - num(mb.cost) - (num(ma.quality) - num(ma.cost));
+            }
+            if (delta !== 0) {
+                return delta;
+            }
+            const weightDelta = (b.weight ?? 1) - (a.weight ?? 1);
+            if (weightDelta !== 0) {
+                return weightDelta;
+            }
+            // Stable: preserve declared pool order on a tie.
+            return (originalIndex.get(a) ?? 0) - (originalIndex.get(b) ?? 0);
+        });
+    }
+    /** Tool narrowing: per-difficulty directive, then classifier hints. */
+    selectTools(decision) {
+        const directive = this.config.toolDirectives?.[decision.difficulty];
+        let toolFilter = directive?.toolFilter
+            ? [...directive.toolFilter]
+            : undefined;
+        const excludeTools = directive?.excludeTools
+            ? [...directive.excludeTools]
+            : undefined;
+        // When no explicit allowlist is configured, honor the classifier's hint.
+        if ((!toolFilter || toolFilter.length === 0) &&
+            decision.suggestedTools &&
+            decision.suggestedTools.length > 0) {
+            toolFilter = [...decision.suggestedTools];
+        }
+        return { toolFilter, excludeTools };
+    }
+    /**
+     * Resolve cost/quality/capabilities for a member. Declared values win;
+     * gaps are filled from the model registry (by model name/alias) when known.
+     * Results are cached per (provider/model) for the router's lifetime.
+     */
+    metaFor(member) {
+        const key = `${member.provider}::${member.model ?? ""}`;
+        const cached = this.metaCache.get(key);
+        if (cached) {
+            return cached;
+        }
+        let cost = member.cost;
+        let quality = member.quality;
+        let capabilities = member.capabilities
+            ? [...member.capabilities]
+            : undefined;
+        const needsEnrichment = cost === undefined || quality === undefined || capabilities === undefined;
+        if (needsEnrichment && member.model) {
+            try {
+                const info = ModelResolver.resolveModel(member.model);
+                if (info) {
+                    if (cost === undefined) {
+                        cost = info.pricing.inputCostPer1K + info.pricing.outputCostPer1K;
+                    }
+                    if (quality === undefined) {
+                        quality = QUALITY_SCORE[info.performance.quality] ?? NEUTRAL;
+                    }
+                    if (capabilities === undefined) {
+                        const caps = [];
+                        if (info.capabilities.vision) {
+                            caps.push("vision");
+                        }
+                        if (info.capabilities.functionCalling) {
+                            caps.push("tools");
+                        }
+                        if (info.capabilities.reasoning) {
+                            caps.push("reasoning");
+                        }
+                        if (info.capabilities.codeGeneration) {
+                            caps.push("code");
+                        }
+                        if (info.capabilities.multimodal) {
+                            caps.push("multimodal");
+                        }
+                        capabilities = caps;
+                    }
+                }
+            }
+            catch {
+                // Enrichment is best-effort; ignore registry lookup failures.
+            }
+        }
+        const meta = { cost, quality, capabilities };
+        if (this.metaCache.size >= MAX_META_CACHE_ENTRIES) {
+            const oldest = this.metaCache.keys().next().value;
+            if (oldest !== undefined) {
+                this.metaCache.delete(oldest);
+            }
+        }
+        this.metaCache.set(key, meta);
+        return meta;
+    }
+}

package/dist/routing/classifierStrategies.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Classification strategies for the ClassifierRouter.
+ *
+ * - `classifyHeuristic` — zero-cost, no LLM. Generalizes the existing binary
+ *   task classifier scorer (fast vs reasoning) into five difficulty tiers.
+ * - `classifyLlm` — runs a cheap "classifier model" via an injected generate
+ *   function, asking for a schema-constrained difficulty verdict. Falls back to
+ *   the heuristic on any failure.
+ */
+import type { ClassifierCandidate, ClassifierDecision, ClassifierDifficulty, ClassifierGenerateFn, ClassifierModelRef, ClassifierRouterInput } from "../types/index.js";
+/** Difficulty tiers, ordered easiest → hardest. */
+export declare const CLASSIFIER_DIFFICULTIES: ClassifierDifficulty[];
+/**
+ * Heuristic classifier — maps the binary fast/reasoning scores plus prompt
+ * length into one of five difficulty tiers. Deterministic and dependency-free.
+ */
+export declare function classifyHeuristic(input: ClassifierRouterInput): ClassifierDecision;
+/**
+ * LLM classifier — asks a cheap model for a schema-constrained verdict.
+ * Falls back to the heuristic if the model is unavailable, times out, or
+ * returns output that does not match the schema.
+ */
+export declare function classifyLlm(input: ClassifierRouterInput, generate: ClassifierGenerateFn, classifierModel?: ClassifierModelRef, timeoutMs?: number, candidates?: ClassifierCandidate[]): Promise<ClassifierDecision>;

package/dist/routing/classifierStrategies.js

@@ -0,0 +1,155 @@
+/**
+ * Classification strategies for the ClassifierRouter.
+ *
+ * - `classifyHeuristic` — zero-cost, no LLM. Generalizes the existing binary
+ *   task classifier scorer (fast vs reasoning) into five difficulty tiers.
+ * - `classifyLlm` — runs a cheap "classifier model" via an injected generate
+ *   function, asking for a schema-constrained difficulty verdict. Falls back to
+ *   the heuristic on any failure.
+ */
+import { z } from "zod";
+import { analyzePrompt, calculateConfidence, } from "../utils/taskClassificationUtils.js";
+import { withTimeout } from "../utils/async/index.js";
+/** Difficulty tiers, ordered easiest → hardest. */
+export const CLASSIFIER_DIFFICULTIES = [
+    "trivial",
+    "simple",
+    "moderate",
+    "hard",
+    "expert",
+];
+/**
+ * Add capability tags implied by the request shape (vision/tools) to a set the
+ * classifier already produced.
+ */
+function withRequestCapabilities(input, base) {
+    const caps = new Set(base ?? []);
+    if (input.requiresVision) {
+        caps.add("vision");
+    }
+    if (input.hasTools) {
+        caps.add("tools");
+    }
+    return caps.size > 0 ? Array.from(caps) : undefined;
+}
+/**
+ * Heuristic classifier — maps the binary fast/reasoning scores plus prompt
+ * length into one of five difficulty tiers. Deterministic and dependency-free.
+ */
+export function classifyHeuristic(input) {
+    const prompt = input.prompt ?? "";
+    const { fastScore, reasoningScore, reasons } = analyzePrompt(prompt);
+    const net = reasoningScore - fastScore;
+    const len = prompt.trim().length;
+    let difficulty;
+    if (fastScore === 0 && reasoningScore === 0) {
+        // No signal — fall back to length as a weak proxy.
+        difficulty = len < 80 ? "simple" : len < 400 ? "moderate" : "hard";
+    }
+    else if (net <= -2) {
+        difficulty = "trivial";
+    }
+    else if (net <= 0) {
+        difficulty = "simple";
+    }
+    else if (net <= 3) {
+        difficulty = "moderate";
+    }
+    else if (net <= 7) {
+        difficulty = "hard";
+    }
+    else {
+        difficulty = "expert";
+    }
+    return {
+        difficulty,
+        confidence: calculateConfidence(fastScore, reasoningScore),
+        requiredCapabilities: withRequestCapabilities(input),
+        reason: `heuristic: net=${net}, len=${len}${reasons.length ? ` (${reasons.slice(0, 3).join("; ")})` : ""}`,
+    };
+}
+/** Schema the LLM classifier is forced to answer with. */
+const classifierOutputSchema = z.object({
+    difficulty: z.enum(["trivial", "simple", "moderate", "hard", "expert"]),
+    confidence: z.number().min(0).max(1).optional(),
+    requiredCapabilities: z.array(z.string()).optional(),
+    suggestedTools: z.array(z.string()).optional(),
+    selectedModelId: z.string().optional(),
+    reason: z.string().optional(),
+});
+const CLASSIFIER_SYSTEM_PROMPT = [
+    "You are a routing classifier inside an AI gateway.",
+    "Classify the user's task by difficulty into EXACTLY one of:",
+    "trivial, simple, moderate, hard, expert.",
+    "Judge by reasoning depth, number of steps, domain expertise required, and ambiguity.",
+    "Greetings/lookups/one-liners are trivial/simple; multi-step analysis, design,",
+    "or expert-domain work is hard/expert.",
+    'Also list required model capabilities (e.g. "vision", "tools", "reasoning")',
+    "and, only if obvious, the names of tools the task needs.",
+    "If a list of available models is provided, also set selectedModelId to the",
+    "single best model id for this task.",
+    "Respond ONLY via the structured schema.",
+].join(" ");
+/**
+ * LLM classifier — asks a cheap model for a schema-constrained verdict.
+ * Falls back to the heuristic if the model is unavailable, times out, or
+ * returns output that does not match the schema.
+ */
+export async function classifyLlm(input, generate, classifierModel, timeoutMs, candidates) {
+    const lines = [
+        "Task to classify:",
+        '"""',
+        (input.prompt ?? "").slice(0, 4000),
+        '"""',
+        `hasTools=${!!input.hasTools} requiresVision=${!!input.requiresVision}`,
+    ];
+    if (candidates && candidates.length > 0) {
+        lines.push("", "Available models — pick the single best `id` for THIS task:");
+        for (const c of candidates) {
+            const bits = [c.provider + (c.model ? `/${c.model}` : "")];
+            if (c.description) {
+                bits.push(c.description);
+            }
+            if (c.tiers && c.tiers.length > 0) {
+                bits.push(`tiers: ${c.tiers.join("/")}`);
+            }
+            if (c.capabilities && c.capabilities.length > 0) {
+                bits.push(`caps: ${c.capabilities.join(",")}`);
+            }
+            lines.push(`- id="${c.id}": ${bits.join(" — ")}`);
+        }
+        lines.push("", "Set selectedModelId to the chosen id (omit if unsure).");
+    }
+    // `timeout` lets the provider abort its own request; withTimeout adds a hard
+    // wall-clock ceiling so a stalled classifier call can never block the turn.
+    // A TimeoutError propagates to ClassifierRouter.classify(), which falls back
+    // to the heuristic (fail-open).
+    const hardTimeoutMs = timeoutMs ?? 8000;
+    const result = await withTimeout(generate({
+        input: { text: lines.join("\n") },
+        systemPrompt: CLASSIFIER_SYSTEM_PROMPT,
+        provider: classifierModel?.provider,
+        model: classifierModel?.model,
+        region: classifierModel?.region,
+        temperature: classifierModel?.temperature ?? 0,
+        disableTools: true,
+        schema: classifierOutputSchema,
+        timeout: hardTimeoutMs,
+        // Marker consumed by NeuroLink.applyClassifierRouting to prevent the
+        // classifier's own generate() call from recursively re-routing.
+        context: { __classifierRouted: true },
+    }), hardTimeoutMs, `Classifier LLM call exceeded ${hardTimeoutMs}ms`);
+    const parsed = classifierOutputSchema.safeParse(result?.structuredData);
+    if (!parsed.success) {
+        return classifyHeuristic(input);
+    }
+    const d = parsed.data;
+    return {
+        difficulty: d.difficulty,
+        confidence: d.confidence ?? 0.7,
+        requiredCapabilities: withRequestCapabilities(input, d.requiredCapabilities),
+        suggestedTools: d.suggestedTools,
+        selectedModelId: d.selectedModelId,
+        reason: d.reason ?? "llm classifier",
+    };
+}

package/dist/routing/index.d.ts

@@ -5,3 +5,5 @@
  */
 export { classifyProviderError, ModelPool } from "./modelPool.js";
 export { createDefaultRequestRouter } from "./requestRouter.js";
+export { ClassifierRouter } from "./classifierRouter.js";
+export { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";

package/dist/routing/index.js

@@ -5,3 +5,5 @@
  */
 export { classifyProviderError, ModelPool } from "./modelPool.js";
 export { createDefaultRequestRouter } from "./requestRouter.js";
+export { ClassifierRouter } from "./classifierRouter.js";
+export { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";

package/dist/session/globalSessionState.d.ts

@@ -1,10 +1,12 @@
 import { NeuroLink } from "../neurolink.js";
-import type { ConversationMemoryConfig, LoopSessionState, SessionVariableValue, ToolRoutingConfig } from "../types/index.js";
+import type { ClassifierRouterConfig, ConversationMemoryConfig, LoopSessionState, SessionVariableValue, ToolRoutingConfig } from "../types/index.js";
 export declare class GlobalSessionManager {
     private static instance;
     private loopSession;
     /** Optional tool-routing config set by CLI handlers before SDK construction. */
     private _toolRoutingConfig;
+    /** Optional classifier-router config set by CLI handlers before SDK construction. */
+    private _classifierRouterConfig;
     static getInstance(): GlobalSessionManager;
     setLoopSession(config?: ConversationMemoryConfig): string;
     /**
@@ -42,6 +44,13 @@ export declare class GlobalSessionManager {
      * already exists).
      */
     setToolRoutingConfig(config: ToolRoutingConfig): void;
+    /**
+     * Store a classifier-router config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setClassifierRouterConfig(config: ClassifierRouterConfig): void;
     getOrCreateNeuroLink(): NeuroLink;
     getCurrentSessionId(): string | undefined;
     setSessionVariable(key: string, value: SessionVariableValue): void;

package/dist/session/globalSessionState.js

@@ -33,6 +33,8 @@ export class GlobalSessionManager {
     loopSession = null;
     /** Optional tool-routing config set by CLI handlers before SDK construction. */
     _toolRoutingConfig = undefined;
+    /** Optional classifier-router config set by CLI handlers before SDK construction. */
+    _classifierRouterConfig = undefined;
     static getInstance() {
         if (!GlobalSessionManager.instance) {
             GlobalSessionManager.instance = new GlobalSessionManager();
@@ -141,6 +143,18 @@ export class GlobalSessionManager {
         }
         this._toolRoutingConfig = config;
     }
+    /**
+     * Store a classifier-router config to be injected at SDK construction time.
+     * Call this BEFORE `getOrCreateNeuroLink()` inside a command handler.
+     * When a loop session is already active the config is ignored (the instance
+     * already exists).
+     */
+    setClassifierRouterConfig(config) {
+        if (this.hasActiveSession()) {
+            return;
+        }
+        this._classifierRouterConfig = config;
+    }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
         if (session) {
@@ -160,6 +174,10 @@ export class GlobalSessionManager {
             options.toolRouting = this._toolRoutingConfig;
             this._toolRoutingConfig = undefined;
         }
+        if (this._classifierRouterConfig) {
+            options.classifierRouter = this._classifierRouterConfig;
+            this._classifierRouterConfig = undefined;
+        }
         return new NeuroLink(Object.keys(options).length ? options : undefined);
     }
     getCurrentSessionId() {