Skip to content

armgit / laya

Public Imported from GitHub
0

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.

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.md
index 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=No
hooks=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 predict
router.load(name) # builds on first use; fires on_load
router.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_load
router.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 any
per-call `hooks`.
diff --git a/docs/hooks/lifecycle.md b/docs/hooks/lifecycle.md
index 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 predict
request 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.md
index 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 loads
const 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 set
diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.ts
index 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.ts
index 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.ts
index 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({