Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
feat(ts): support per-call hooks in router predictBatch and update docs (#909)
Swatantra Yadav8feab871c38d
diff --git a/docs/hooks/api.md b/docs/hooks/api.mdindex c7effc09..f7284a06 100644--- a/docs/hooks/api.md+++ b/docs/hooks/api.md@@ -296,6 +296,10 @@ router.predict(state, questions, model=None, task=None, lang=None, lang_guess=Nohooks=None, on_predict_start=None, on_predict_end=None, hooks_raise=None,hooks_timeout=None, max_len=None, head_max_len=None)+router.predict_batch(requests, batch_size=None, min_confidence=None, sort_by_length=False,+ hooks_timeout=None, hooks=None, on_predict_start=None, on_predict_end=None,+ hooks_raise=None)+router.system_one(...) # alias of predictrouter.load(name) # builds on first use; fires on_loadrouter.preload(names=None) # builds several; fires on_load per build@@ -304,7 +308,7 @@ router.attach(name, agent) # registers an existing agent; does not fire on_loadrouter.loaded # list of resident checkpoint names```-- Per-call `hooks=` on `route` and `predict` apply to the whole call, including `on_route`.+- Per-call `hooks=` on `route`, `route_batch`, `predict` and `predict_batch` apply to the whole call, including `on_route`. On `predict_batch` the list is composed the same way as on `predict` (installed hooks first, then the per-call list; `None` and `[]` add nothing) and runs once per request.- `route()` is public: calling it dispatches `on_route` with the installed hooks plus anyper-call `hooks`.diff --git a/docs/hooks/lifecycle.md b/docs/hooks/lifecycle.mdindex 293ca650..ea7bdc86 100644--- a/docs/hooks/lifecycle.md+++ b/docs/hooks/lifecycle.md@@ -116,9 +116,10 @@ Each result is what `predict` returns for that request, so Router-level predictrequest here too: every request gets its own `PredictContext`, `run_id` and `elapsed_ms`.```-Router.predict_batch(requests, batch_size=...)+Router.predict_batch(requests, batch_size=..., hooks=...)│- ├─ route_batch(requests) ──► on_route, once per request (no checkpoint loaded yet)+ ├─ active = installed hooks + per-call hooks (installed first; None and [] add nothing)+ ├─ route_batch(requests, hooks=per-call) ──► on_route, once per request (no checkpoint loaded yet)│└─ for each checkpoint, in order of first appearance:│diff --git a/laya-ts/README.md b/laya-ts/README.mdindex f8b67ade..b87b626a 100644--- a/laya-ts/README.md+++ b/laya-ts/README.md@@ -146,6 +146,9 @@ const results = await agent.predictBatch(states, questions, { batchSize: 32 });// in as few forward passes as possible. Results keep input order and carry `routing`.const decisions = router.routeBatch(requests); // validate + route, nothing loadsconst routed = await router.predictBatch(requests, 32); // == router.predictMany(...)+// Per-call hooks are composed like predict: installed hooks first, then this list.+// null and [] add nothing. The list runs once per request, including onRoute.+const traced = await router.predictBatch(requests, null, { hooks: [tracer] });// requests routed to the same checkpoint still split into separate batches when their// question schemas differ (order-sensitively), when per-request start hooks setdiff --git a/laya-ts/src/index.ts b/laya-ts/src/index.tsindex 517cfeed..1f62f73b 100644--- a/laya-ts/src/index.ts+++ b/laya-ts/src/index.ts@@ -16,7 +16,7 @@ export type {export { createNodeProvider, createWebProvider, feed, feedHead, loadNodeBundle, loadWebBundle, PINNED_REVISIONS, resolveRevision } from "./providers.js";export type { Batch, SessionProvider, ProviderOptions, NodeBundle, WebBundle } from "./providers.js";export { Router, normaliseName, DEFAULT_MODELS, digestsFromEnv, _digestsFromEnv } from "./router.js";-export type { RoutedResult, RouteDecision, ModelName, ModelSpec, BatchRequest, RouterOptions, RouteOptions } from "./router.js";+export type { RoutedResult, RouteDecision, ModelName, ModelSpec, BatchRequest, PredictBatchOptions, RouterOptions, RouteOptions } from "./router.js";export { shortlistChoice, predictShortlist, embedFnFromAgent, DEFAULT_SHORTLIST_K } from "./shortlist.js";export type { EmbedFn, ShortlistMeta } from "./shortlist.js";export { analyse, isEnglish, guessLatinLanguage, detectScript } from "./lang.js";diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.tsindex 48e8900b..567226fd 100644--- a/laya-ts/src/router.ts+++ b/laya-ts/src/router.ts@@ -154,6 +154,15 @@ export interface RouteOptions {hooksRaise?: boolean;}+/**+ * Per-call options for `Router.predictBatch` / `predictMany` / `routeBatch`.+ * `hooks` is composed the same way as on `predict`: installed hooks first, then this list.+ * `null`, `undefined` and `[]` add nothing.+ */+export interface PredictBatchOptions {+ hooks?: HookArg;+}+/** One item of a Router.predictBatch/routeBatch batch: state, questions, route overrides. */export interface BatchRequest {state: unknown;@@ -682,7 +691,7 @@ export class Router extends HookRegistry {* validated before anything loads, so a malformed batch fails fast. Entries keep input* order; routing is deterministic, so repeated batches route identically.*/- routeBatch(requests: BatchRequest[]): RouteDecision[] {+ routeBatch(requests: BatchRequest[], opts: PredictBatchOptions = {}): RouteDecision[] {if (!Array.isArray(requests)) {throw new TypeError("requests must be an array of request objects");}@@ -711,6 +720,7 @@ export class Router extends HookRegistry {task: request.task ?? null,lang: request.lang ?? null,langGuess: request.langGuess ?? request.lang_guess ?? null,+ hooks: opts.hooks,}),);}@@ -731,12 +741,16 @@ export class Router extends HookRegistry {* Router-level predict hooks run per request: each request gets its own PredictContext* carrying `decision`; `onPredictStart` may rewrite a request or `ctx.skip()` it, and* `onPredictEnd` runs once per started request even when the batch fails.+ * `opts.hooks` are per-call hooks, appended after any installed on the Router, the same+ * composition `predict` uses. `null` and `[]` add nothing. They apply to `onRoute` as well+ * as to each request's predict lifecycle.*/async predictBatch(requests: BatchRequest[],batchSize: number | null = null,+ opts: PredictBatchOptions = {},): Promise<RoutedResult[]> {- const decisions = this.routeBatch(requests);+ const decisions = this.routeBatch(requests, opts);if (decisions.length === 0) return [];const groups = new Map<string, number[]>();@@ -748,7 +762,7 @@ export class Router extends HookRegistry {}const results: (RoutedResult | null)[] = new Array(requests.length).fill(null);- const active = composeHooks(this.hooks);+ const active = composeHooks(this.hooks, opts.hooks);const raiseErrors = this.hooksRaise;for (const [modelName, indices] of groups) {@@ -924,8 +938,9 @@ export class Router extends HookRegistry {async predictMany(requests: BatchRequest[],batchSize: number | null = null,+ opts: PredictBatchOptions = {},): Promise<RoutedResult[]> {- return this.predictBatch(requests, batchSize);+ return this.predictBatch(requests, batchSize, opts);}/**diff --git a/laya-ts/tests/router-batch.test.ts b/laya-ts/tests/router-batch.test.tsindex 77c7faca..22514fe3 100644--- a/laya-ts/tests/router-batch.test.ts+++ b/laya-ts/tests/router-batch.test.ts@@ -174,6 +174,80 @@ describe("Router.routeBatch / predictBatch", () => {]);});+ it("accepts per-call hooks in predict order, and treats null and [] as no-ops", async () => {+ const order: string[] = [];+ const installed = {+ onRoute(ctx: { states: unknown[] }) {+ order.push(`installed:route:${ctx.states[0]}`);+ },+ onPredictStart(ctx: { states: unknown[] }) {+ order.push(`installed:start:${ctx.states[0]}`);+ },+ onPredictEnd(ctx: { states: unknown[] }) {+ order.push(`installed:end:${ctx.states[0]}`);+ },+ };+ const perCall = {+ onRoute(ctx: { states: unknown[] }) {+ order.push(`percall:route:${ctx.states[0]}`);+ },+ onPredictStart(ctx: { states: unknown[] }) {+ order.push(`percall:start:${ctx.states[0]}`);+ },+ onPredictEnd(ctx: { states: unknown[] }) {+ order.push(`percall:end:${ctx.states[0]}`);+ },+ };+ const { router } = makeRouter({ hooks: [installed] });+ const items = [req("one", { model: "english" }), req("two", { model: "english" })];+ const results = await router.predictBatch(items, null, { hooks: [perCall] });+ expect(results.map((r) => r.answers.seen)).toEqual(["one", "two"]);+ // routeBatch runs before any predict hook. End hooks follow start order on this runtime.+ expect(order).toEqual([+ "installed:route:one",+ "percall:route:one",+ "installed:route:two",+ "percall:route:two",+ "installed:start:one",+ "percall:start:one",+ "installed:start:two",+ "percall:start:two",+ "installed:end:one",+ "percall:end:one",+ "installed:end:two",+ "percall:end:two",+ ]);++ order.length = 0;+ await router.predictBatch(items, null, { hooks: null });+ const noneOrder = [...order];+ order.length = 0;+ await router.predictBatch(items, null, { hooks: [] });+ const emptyOrder = [...order];+ order.length = 0;+ await router.predictBatch(items);+ expect(noneOrder).toEqual(emptyOrder);+ expect(emptyOrder).toEqual(order);+ expect(noneOrder).toEqual([+ "installed:route:one",+ "installed:route:two",+ "installed:start:one",+ "installed:start:two",+ "installed:end:one",+ "installed:end:two",+ ]);++ const { router: bare } = makeRouter();+ expect((await bare.predictBatch(items, null, { hooks: null })).map((r) => r.answers.seen)).toEqual([+ "one",+ "two",+ ]);+ expect((await bare.predictBatch(items, null, { hooks: [] })).map((r) => r.answers.seen)).toEqual([+ "one",+ "two",+ ]);+ });+it("runs router hooks per request and short-circuits skipped requests", async () => {const events: string[] = [];const { router, calls } = makeRouter({