@juspay/neurolink 12.18.1 → 12.19.0

package/dist/rag/pipeline/RAGPipeline.js

@@ -32,6 +32,7 @@ import { InMemoryVectorStore } from "../retrieval/vectorQueryTool.js";
 import { InMemoryBM25Index, createHybridSearch, } from "../retrieval/hybridSearch.js";
 import { GraphRAG } from "../graphRag/graphRAG.js";
 import { rerank } from "../reranker/reranker.js";
+import { decideSearchPlan } from "../retrieval/searchDecision.js";
 import { ProviderFactory } from "../../factories/providerFactory.js";
 import { ImageLoader } from "../document/imageLoader.js";
 import { ImageProcessor } from "../../utils/imageProcessor.js";
@@ -250,10 +251,53 @@ export class RAGPipeline {
         try {
             await this.ensureInitialized();
             const startTime = Date.now();
-            const topK = options?.topK || this.config.defaultTopK || 5;
-            const useHybrid = options?.hybrid ?? this.config.enableHybridSearch;
-            const useGraph = options?.graph ?? this.config.enableGraphRAG;
-            const useRerank = options?.rerank ?? this.config.enableReranking;
+            let topK = options?.topK || this.config.defaultTopK || 5;
+            let useHybrid = options?.hybrid ?? this.config.enableHybridSearch;
+            let useGraph = options?.graph ?? this.config.enableGraphRAG;
+            let useRerank = options?.rerank ?? this.config.enableReranking;
+            // Per-query retrieval planning. The four knobs above are otherwise
+            // static config, identical for "what is the refund window?" and "how
+            // does billing relate to entitlements?" — one precise passage versus a
+            // survey across documents. A decision model answers all four for THIS
+            // query in one ~400ms round trip.
+            //
+            // Precedence is strict and one-directional: an explicit QueryOptions
+            // field always wins, and the plan can only select among capabilities
+            // this pipeline was configured with. It never enables one that is not
+            // set up, because `graph: true` on a pipeline with no graph index is a
+            // failure rather than a plan.
+            let plan = null;
+            if (this.config.decide && options?.plan !== false) {
+                try {
+                    plan = await decideSearchPlan(query, this.config.decide, {
+                        defaultTopK: topK,
+                        canHybrid: !!this.config.enableHybridSearch && !!this.hybridSearch,
+                        canGraph: !!this.config.enableGraphRAG,
+                        canRerank: !!this.config.enableReranking && !!this.config.rerankingModel,
+                    });
+                }
+                catch (planError) {
+                    logger.debug("[RAGPipeline] Search planning failed, using config", {
+                        error: planError instanceof Error
+                            ? planError.message
+                            : String(planError),
+                    });
+                }
+            }
+            if (plan) {
+                if (options?.topK === undefined && plan.topK !== undefined) {
+                    topK = plan.topK;
+                }
+                if (options?.hybrid === undefined && plan.hybrid !== undefined) {
+                    useHybrid = plan.hybrid;
+                }
+                if (options?.graph === undefined && plan.graph !== undefined) {
+                    useGraph = plan.graph;
+                }
+                if (options?.rerank === undefined && plan.rerank !== undefined) {
+                    useRerank = plan.rerank;
+                }
+            }
             let results;
             let retrievalMethod = "vector";
             // Generate query embedding
@@ -338,6 +382,7 @@ export class RAGPipeline {
                     retrievalMethod,
                     chunksRetrieved: results.length,
                     reranked,
+                    ...(plan ? { plan } : {}),
                 },
             };
             span.durationMs = Date.now() - spanStartTime;
@@ -347,6 +392,21 @@ export class RAGPipeline {
                 "rag.retrieval_method": retrievalMethod,
                 "rag.results_count": results.length,
                 "rag.reranked": reranked,
+                // The EFFECTIVE knobs, after planning and caller overrides. The span
+                // recorded the configured values at creation; without these a reader
+                // cannot tell a planned query from an unplanned one, which is the
+                // whole question when a fail-open path stops firing.
+                "rag.effective_top_k": topK,
+                "rag.planned": plan !== null,
+                ...(plan
+                    ? {
+                        "rag.plan_model": plan.model,
+                        "rag.plan_latency_ms": plan.latencyMs,
+                        ...(plan.breadthLevel !== undefined
+                            ? { "rag.plan_breadth": plan.breadthLevel }
+                            : {}),
+                    }
+                    : {}),
             };
             getMetricsAggregator().recordSpan(endedSpan);
             return response;
@@ -788,5 +848,6 @@ export function createRAGPipeline(options) {
         enableHybridSearch: options.enableHybrid,
         enableGraphRAG: options.enableGraph,
         multiModal: options.multiModal,
+        decide: options.decide,
     });
 }

package/dist/rag/retrieval/searchDecision.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-search retrieval planning.
+ *
+ * `RAGPipeline.query()` resolves four knobs — `topK`, `hybrid`, `graph`,
+ * `rerank` — and every one of them is config with an optional per-call
+ * override. Nothing inspects the query. The same plan is used for "what is
+ * the refund window?" (one precise passage, an exact phrase worth matching
+ * lexically) and "how does billing relate to entitlements?" (many passages,
+ * relationships between documents).
+ *
+ * One decision request answers all four for the query in hand, in ~400ms.
+ * Every answer is a *suggestion*: an explicit per-call option always wins,
+ * and a capability the pipeline was not configured with can never be turned
+ * on by a model — `graph: true` against a pipeline with no graph index would
+ * be a failure, not a plan.
+ *
+ * @module rag/retrieval/searchDecision
+ */
+import type { DecisionCallerFn, SearchPlanCapabilities, SearchPlanResult } from "../../types/index.js";
+/**
+ * Ask how this particular query should be retrieved.
+ *
+ * Returns `null` when nothing should change — no decision provider, a failed
+ * call, or an answer set that suggests nothing. Every returned field is
+ * optional and means "use this unless the caller said otherwise".
+ */
+export declare function decideSearchPlan(query: string, decide: DecisionCallerFn, capabilities: SearchPlanCapabilities): Promise<SearchPlanResult | null>;

package/dist/rag/retrieval/searchDecision.js

@@ -0,0 +1,124 @@
+/**
+ * Per-search retrieval planning.
+ *
+ * `RAGPipeline.query()` resolves four knobs — `topK`, `hybrid`, `graph`,
+ * `rerank` — and every one of them is config with an optional per-call
+ * override. Nothing inspects the query. The same plan is used for "what is
+ * the refund window?" (one precise passage, an exact phrase worth matching
+ * lexically) and "how does billing relate to entitlements?" (many passages,
+ * relationships between documents).
+ *
+ * One decision request answers all four for the query in hand, in ~400ms.
+ * Every answer is a *suggestion*: an explicit per-call option always wins,
+ * and a capability the pipeline was not configured with can never be turned
+ * on by a model — `graph: true` against a pipeline with no graph index would
+ * be a failure, not a plan.
+ *
+ * @module rag/retrieval/searchDecision
+ */
+import { gateDecisionBoolean, readDecisionScore, } from "../../utils/decisionAnswers.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * How many passages the question needs, narrowest → widest, as multiples of
+ * the configured default. A `score` rather than a number: a decision model
+ * places things on an ordered scale well and reads digits as text badly.
+ */
+const BREADTH_CRITERIA = [
+    "One specific fact, definition or value. A single passage answers it completely.",
+    "A handful of related points — a procedure, a short comparison, one topic explained.",
+    "Several distinct areas that each need their own supporting passage.",
+    "A broad survey that needs evidence from across the whole corpus.",
+];
+/** Multiplier applied to the configured topK, indexed by breadth level. */
+const BREADTH_MULTIPLIER = [0.5, 1, 1.5, 2.5];
+/** Below this the breadth reading is ignored and the configured topK stands. */
+const MIN_BREADTH_CONFIDENCE = 0.5;
+/** Absolute bounds on a suggested topK, whatever the multiplier produces. */
+const MIN_TOP_K = 1;
+const MAX_TOP_K = 50;
+/**
+ * Ask how this particular query should be retrieved.
+ *
+ * Returns `null` when nothing should change — no decision provider, a failed
+ * call, or an answer set that suggests nothing. Every returned field is
+ * optional and means "use this unless the caller said otherwise".
+ */
+export async function decideSearchPlan(query, decide, capabilities) {
+    if (!query.trim()) {
+        return null;
+    }
+    const questions = {
+        breadth: {
+            type: "score",
+            instructions: "How much supporting material does answering this question require from a document collection?",
+            criteria: BREADTH_CRITERIA,
+        },
+    };
+    // Only ask about a capability the pipeline actually has. An answer nobody
+    // can act on costs input tokens and invites the mistake of acting on it.
+    if (capabilities.canHybrid) {
+        questions.hybrid = {
+            type: "boolean",
+            instructions: "This question contains exact terms that must be matched literally — an identifier, error code, file name, version number, API name, or a quoted phrase — rather than only a topic to match by meaning.",
+        };
+    }
+    if (capabilities.canGraph) {
+        questions.graph = {
+            type: "boolean",
+            instructions: "Answering this requires connecting information that lives in separate documents, such as how two things relate, what depends on what, or tracing a chain across sources.",
+        };
+    }
+    if (capabilities.canRerank) {
+        questions.rerank = {
+            type: "boolean",
+            instructions: "This question is specific enough that the ORDER of the retrieved passages matters — a nearly-right passage would produce a wrong answer, so precision is worth an extra ranking pass.",
+        };
+    }
+    const result = await decide({
+        state: { query: query.slice(0, 4000) },
+        // The map is assembled dynamically above; its members are all valid
+        // question shapes, which the cast asserts once here rather than at four
+        // separate construction sites.
+        questions: questions,
+        timeoutMs: capabilities.timeoutMs,
+    });
+    if (!result) {
+        return null;
+    }
+    const plan = {
+        model: result.model,
+        latencyMs: result.latencyMs,
+    };
+    const breadth = readDecisionScore(result.answers, "breadth");
+    if (breadth && breadth.confidence >= MIN_BREADTH_CONFIDENCE) {
+        const level = Math.max(0, Math.min(BREADTH_MULTIPLIER.length - 1, Math.round(breadth.score)));
+        const multiplier = BREADTH_MULTIPLIER[level] ?? 1;
+        plan.topK = Math.max(MIN_TOP_K, Math.min(MAX_TOP_K, Math.round(capabilities.defaultTopK * multiplier)));
+        plan.breadthLevel = level;
+    }
+    if (capabilities.canHybrid) {
+        plan.hybrid = gateDecisionBoolean(result.answers, "hybrid");
+    }
+    if (capabilities.canGraph) {
+        plan.graph = gateDecisionBoolean(result.answers, "graph");
+    }
+    if (capabilities.canRerank) {
+        plan.rerank = gateDecisionBoolean(result.answers, "rerank");
+    }
+    const suggested = plan.topK !== undefined ||
+        plan.hybrid !== undefined ||
+        plan.graph !== undefined ||
+        plan.rerank !== undefined;
+    if (!suggested) {
+        return null;
+    }
+    logger.debug("[RAG] Search plan decided", {
+        model: result.model,
+        latencyMs: result.latencyMs,
+        topK: plan.topK,
+        hybrid: plan.hybrid,
+        graph: plan.graph,
+        rerank: plan.rerank,
+    });
+    return plan;
+}

package/dist/routing/classifierRouter.d.ts

@@ -11,18 +11,52 @@
  * 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";
+import type { ClassifierRouterConfig, ClassifierRouterDecision, ClassifierRouterDeps, ClassifierRouterInput, ClassifierRouterPoolMember } from "../types/index.js";
 export declare class ClassifierRouter {
     private readonly config;
     private readonly deps;
     private readonly metaCache;
+    /**
+     * The effective pool: what the host declared, plus catalogue-derived members
+     * when `catalog.enabled`. Mutable so a long-lived host can widen or narrow
+     * it without rebuilding the router — the constructor-frozen pool was the one
+     * thing preventing a runtime model catalogue.
+     */
+    private pool;
+    /** Registry index for candidate enrichment; built once, on first use. */
+    private registryIndex?;
     constructor(config: ClassifierRouterConfig, deps?: ClassifierRouterDeps);
+    /**
+     * Merge the declared pool with the catalogue. Declared members win on a
+     * duplicate `provider/model`, because a host that spelled a member out has
+     * said something about it (a region, a description, an explicit tier) that
+     * the registry does not know.
+     */
+    private static composePool;
+    /**
+     * Replace the routable pool at runtime. Returns the new size.
+     *
+     * Clears the metadata cache, since a member's declared cost/quality is
+     * cached per `provider::model` and a replacement pool may declare different
+     * values for the same pair.
+     */
+    setPool(members: ClassifierRouterPoolMember[]): number;
+    /** The pool currently routed over, declared plus catalogue. */
+    getPool(): ClassifierRouterPoolMember[];
+    /** Rebuild the catalogue half of the pool (e.g. after credentials change). */
+    refreshCatalog(): number;
     /**
      * 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. */
+    /**
+     * Resolve "auto" (the default) to a concrete strategy. Jev is preferred the
+     * moment a TypeSafe key is present; without one the behaviour is exactly
+     * what it was before Jev existed.
+     */
+    private resolveStrategy;
+    /** Run the chosen strategy; every one falls back to heuristic on failure. */
     private classify;
     /**
      * Build LLM-facing model descriptors + an id→member map so the classifier can
@@ -35,12 +69,50 @@ export declare class ClassifierRouter {
      * metadata scoring.
      */
     private selectModels;
+    /**
+     * Whether a directly-picked model clears the bar that applies to it.
+     *
+     * The bars are asymmetric because the two mistakes do not cost the same, and
+     * which one a pick risks depends on what the difficulty tier would otherwise
+     * have chosen. Picking something COSTLIER than the tier's own choice risks
+     * spending more than necessary, so it clears the low upgrade bar. Picking
+     * something CHEAPER risks handing the task to a model that cannot do it, so
+     * it must clear the high downgrade bar. Agreeing with the tier needs no bar
+     * at all.
+     *
+     * A strategy that reports no confidence for its pick — the LLM classifier —
+     * is honoured exactly as before. Its self-reported numbers are not
+     * calibrated, so a bar over them would be arithmetic on noise, and imposing
+     * one would silently change the behaviour of a shipped, unrelated strategy.
+     */
+    private pickClearsBar;
+    /** The difficulty-based ranking, independent of any direct pick. */
+    private rankForDifficulty;
+    /**
+     * Whether a member's context window can hold the estimated request. Unknown
+     * windows pass — the registry does not know every model, and starving the
+     * pool on missing metadata is worse than an occasional retry.
+     */
+    private fitsRequest;
+    /** Drop members too small for the request, unless that empties the pool. */
+    private withRoomFor;
     /** 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;
+    /**
+     * Turn the classifier's context reading into a compaction threshold.
+     *
+     * Returns undefined — meaning "leave the 0.8 default alone" — whenever the
+     * feature is off, no scope was read, or the scope is the widest one. The
+     * mapping can only ever LOWER the threshold, which is enforced in
+     * `contextScopeToThreshold` rather than here, because the consequence of
+     * getting it wrong in the other direction is not recoverable: a
+     * `context_window` error puts the model into ModelPool's 10-year cooldown.
+     */
+    private selectContextBudget;
     /** Tool narrowing: per-difficulty directive, then classifier hints. */
     private selectTools;
     /**