From 47da8ce28a66e97f398d53169f8ffe3fd7856e09 Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 01:03:57 +0530 Subject: [PATCH 1/6] fix(router): accept and compose per-call hooks in predict_batch and route_batch (#909) --- laya/mcp/remote.py | 12 ++++-- laya/router.py | 25 ++++++++++-- tests/test_hooks.py | 85 +++++++++++++++++++++++++++++++++++++++++ tests/test_hooks_api.py | 29 ++++++++++---- 4 files changed, 137 insertions(+), 14 deletions(-) diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py index 0631e6220..cb6e4bf46 100644 --- a/laya/mcp/remote.py +++ b/laya/mcp/remote.py @@ -193,9 +193,14 @@ def predict_batch( self, requests: Sequence[Dict[str, Any]], batch_size: Optional[int] = None, - hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, + *, + hooks_timeout: Optional[float] = None, + hooks=None, + on_predict_start=None, + on_predict_end=None, + hooks_raise: Optional[bool] = None, ) -> List[Dict[str, Any]]: """One ``/v1/systemone`` call per request, answers in input order. @@ -206,8 +211,9 @@ def predict_batch( keep working. The server applies its own batching inside each call. """ results: List[Dict[str, Any]] = [] - if hooks_timeout is not None: - raise RemoteError("unsupported_remote", "hooks_timeout belongs to the server's hooks") + if any(value is not None for value in (hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout)): + raise RemoteError("unsupported_remote", + "hooks are callables and cannot be sent to laya-serve; install them on the server") for item in requests: if not isinstance(item, dict): raise TypeError("predict_batch requests must be dicts, got %s" % type(item).__name__) diff --git a/laya/router.py b/laya/router.py index 0d907adb2..c70896f8e 100644 --- a/laya/router.py +++ b/laya/router.py @@ -1167,6 +1167,9 @@ def route_batch( self, requests: Sequence[Dict[str, Any]], hooks_timeout: Optional[float] = None, + *, + hooks=None, + hooks_raise: Optional[bool] = None, ) -> List[RouteDecision]: """Route a heterogeneous request batch without loading any checkpoints. @@ -1182,6 +1185,8 @@ def route_batch( ``questions``. hooks_timeout: Override the Router's ``hooks_timeout`` for this call, applied to every request's ``on_route`` dispatch, as on :meth:`route`. + hooks: Per-call hook or sequence of hooks for this call. + hooks_raise: Override the Router's ``hooks_raise`` policy for this call. """ if not isinstance(requests, SequenceABC) or isinstance(requests, (str, bytes)): raise TypeError("requests must be a sequence of request dictionaries") @@ -1210,6 +1215,8 @@ def route_batch( task=request.get("task"), lang=request.get("lang"), lang_guess=request.get("lang_guess"), + hooks=hooks, + hooks_raise=hooks_raise, hooks_timeout=hooks_timeout, ) ) @@ -1220,9 +1227,14 @@ def predict_batch( self, requests: Sequence[Dict[str, Any]], batch_size: Optional[int] = None, - hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, + *, + hooks_timeout: Optional[float] = None, + hooks=None, + on_predict_start=None, + on_predict_end=None, + hooks_raise: Optional[bool] = None, ) -> List[Dict[str, Any]]: """Route and execute a heterogeneous request batch with minimal model churn. @@ -1256,16 +1268,21 @@ def predict_batch( overrides. batch_size: Optional maximum number of states per Agent forward-pass batch. hooks_timeout: Override the Router's ``hooks_timeout`` for this call. + min_confidence: Optional float or per-bucket mapping for confidence gating. sort_by_length: Forwarded to every ``Agent.predict_batch`` call, so each question group pads to a shorter maximum; see ``Agent.predict_batch``. Results retain the input order either way. Silently dropped for an attached agent whose ``predict_batch`` predates the knob (#294). + hooks: Per-call hook or sequence of hooks for this call. + on_predict_start: Plain callable or sequence of callables for start events. + on_predict_end: Plain callable or sequence of callables for end events. + hooks_raise: Override the Router's ``hooks_raise`` policy for this call. Returns: One normal Router prediction result per request, in the same order as the input. """ mc = check_min_confidence(min_confidence) if min_confidence is not None else None - decisions = self.route_batch(requests, hooks_timeout=hooks_timeout) + decisions = self.route_batch(requests, hooks=hooks, hooks_raise=hooks_raise, hooks_timeout=hooks_timeout) if not decisions: return [] @@ -1288,8 +1305,8 @@ def predict_batch( # list alone silently dropped every process-wide default from the batched path while # keeping them on `predict`, so a default audit or metrics hook saw no Router-level event # for a request that arrived through `predict_batch`. - active = compose_hooks(self.hooks) - raise_errors = self.hooks_raise + active = compose_hooks(self.hooks, hooks, on_predict_start, on_predict_end) + raise_errors = self.hooks_raise if hooks_raise is None else bool(hooks_raise) timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout) for model_name, indices in groups.items(): diff --git a/tests/test_hooks.py b/tests/test_hooks.py index f4d32f774..817a738cd 100644 --- a/tests/test_hooks.py +++ b/tests/test_hooks.py @@ -1608,6 +1608,91 @@ def slow_route_router(**kwargs): lambda: Router().route_batch([req("a")], hooks_timeout=0)) +# ------------------------------------------- per-call hooks on Router.predict_batch and route_batch (#909) +per_call_events = [] + + +class PerCallTrace: + def on_predict_start(self, ctx): + per_call_events.append(("start", ctx.states[0])) + + def on_predict_end(self, ctx): + per_call_events.append(("end", ctx.states[0])) + + def on_route(self, ctx): + per_call_events.append(("route", ctx.states[0])) + + +r_batch, en_batch, _ = batch_router() + +# 1. per-call hooks on predict_batch +r_batch.predict_batch([req("call1"), req("call2")], hooks=[PerCallTrace()]) +check("router_batch/per-call hooks execute for all requests", + per_call_events, + [("route", "call1"), ("route", "call2"), + ("start", "call1"), ("start", "call2"), + ("end", "call2"), ("end", "call1")]) + +per_call_events.clear() + +# 2. per-call convenience callables on predict_start and predict_end +seen_starts = [] +seen_ends = [] +r_batch.predict_batch([req("cb1")], + on_predict_start=lambda c: seen_starts.append(c.states[0]), + on_predict_end=lambda c: seen_ends.append(c.states[0])) +check("router_batch/per-call callables execute", (seen_starts, seen_ends), (["cb1"], ["cb1"])) + +# 3. per-call hooks on route_batch +route_trace = [] + + +class RouteTrace: + def on_route(self, ctx): + route_trace.append(ctx.states[0]) + + +r_batch.route_batch([req("rb1"), req("rb2")], hooks=[RouteTrace()]) +check("router_batch/route_batch per-call hooks execute", route_trace, ["rb1", "rb2"]) + +# 4. per-call hooks_raise policy +class FailingStartHook: + def on_predict_start(self, ctx): + raise ValueError("failing hook") + + +check_raises("router_batch/hooks_raise=True propagates exception", + ValueError, + lambda: r_batch.predict_batch([req("fail1")], hooks=[FailingStartHook()], hooks_raise=True)) + +with warnings.catch_warnings(record=True) as _warns: + warnings.simplefilter("always") + res = r_batch.predict_batch([req("warn1")], hooks=[FailingStartHook()], hooks_raise=False) + check("router_batch/hooks_raise=False returns result", len(res), 1) + check_true("router_batch/hooks_raise=False warns", any("failing hook" in str(w.message) for w in _warns)) + +# 5. positional and keyword-only hook controls (#909 review) +r_pos, _, _ = batch_router() + +# route_batch keeps hooks_timeout positional-or-keyword +pos_decisions = r_pos.route_batch([req("pos1")], 1.0) +check("router_batch/route_batch positional hooks_timeout", len(pos_decisions), 1) + +# route_batch takes hooks as keyword-only +kw_decisions = r_pos.route_batch([req("pos1")], 1.0, hooks=[RouteTrace()]) +check("router_batch/route_batch keyword-only hooks", len(kw_decisions), 1) + +# predict_batch keeps hooks_timeout keyword-only +pos_results = r_pos.predict_batch([req("pos2")], 8, hooks_timeout=1.0, hooks=[PerCallTrace()]) +check("router_batch/predict_batch keyword-only controls", len(pos_results), 1) + +# keyword-only enforcement: passing hook controls positionally raises TypeError +check_raises("router_batch/route_batch rejects positional hooks", TypeError, + lambda: r_pos.route_batch([req("pos1")], 1.0, [RouteTrace()])) +check_raises("router_batch/predict_batch rejects positional hooks_timeout past sort_by_length", TypeError, + lambda: r_pos.predict_batch([req("pos2")], 8, None, False, 1.0)) + + # --------------------------------------------------------------- report print("\n%d passed, %d failed" % (len(PASS), len(FAIL))) for f_ in FAIL: diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py index aa5fb0ac8..5c1643cb7 100644 --- a/tests/test_hooks_api.py +++ b/tests/test_hooks_api.py @@ -23,7 +23,7 @@ sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) import laya # noqa: E402 -from laya import Agent, AsyncHook, BaseHook, PredictContext, PredictHook, Router, load # noqa: E402 +from laya import Agent, BaseHook, PredictContext, PredictHook, Router, load # noqa: E402 from laya.hooks import HOOK_EVENTS, Hook # noqa: E402 from laya.onnx_agent import ONNXAgent # noqa: E402 from laya.router import _question_schema # noqa: E402 @@ -135,6 +135,7 @@ def check_param(name, fn, param, default, kind=None): ("Agent.system_one", Agent.system_one), ("Agent.predict_long", Agent.predict_long), ("Router.predict", Router.predict), + ("Router.predict_batch", Router.predict_batch), ("Router.predict_long", Router.predict_long), ("ONNXAgent.system_one", ONNXAgent.system_one)): check_param(label, fn, "hooks", None) @@ -165,8 +166,6 @@ def check_param(name, fn, param, default, kind=None): # Router.predict_batch has no call-level budget: a heterogeneous batch sets it per request, and # the request keys `max_len` / `head_max_len` are read into each request's PredictContext. -check_param("Router.predict_batch", Router.predict_batch, "batch_size", None) -check_param("Router.predict_batch", Router.predict_batch, "hooks_timeout", None) for param in ("max_len", "head_max_len"): check("Router.predict_batch/%s is per-request, not a call argument" % param, param in sig(Router.predict_batch), False) @@ -176,10 +175,26 @@ def check_param(name, fn, param, default, kind=None): check_param("shortlist_choice", laya.shortlist_choice, "return_scores", False, inspect.Parameter.KEYWORD_ONLY) -# route() takes per-call hooks so a hook can pin a checkpoint for one call -check_param("Router.route", Router.route, "hooks", None) -check_param("Router.route", Router.route, "hooks_raise", None) -check_param("Router.route", Router.route, "hooks_timeout", None) +# route() and route_batch() take per-call hooks so a hook can pin a checkpoint for one call +for label, fn in (("Router.route", Router.route), + ("Router.route_batch", Router.route_batch)): + check_param(label, fn, "hooks", None) + check_param(label, fn, "hooks_raise", None) + check_param(label, fn, "hooks_timeout", None) + +# Positional compatibility: hook parameters are keyword-only to protect positional callers +check("Router.route_batch/positional prefix", + [p.name for p in sig(Router.route_batch).values() if p.kind != inspect.Parameter.KEYWORD_ONLY], + ["requests", "hooks_timeout"]) +check("Router.predict_batch/positional prefix", + [p.name for p in sig(Router.predict_batch).values() if p.kind != inspect.Parameter.KEYWORD_ONLY], + ["requests", "batch_size", "min_confidence", "sort_by_length"]) +for param in ("hooks", "hooks_raise"): + check("Router.route_batch/%s is keyword-only" % param, + sig(Router.route_batch)[param].kind, inspect.Parameter.KEYWORD_ONLY) +for param in ("hooks_timeout", "hooks", "on_predict_start", "on_predict_end", "hooks_raise"): + check("Router.predict_batch/%s is keyword-only" % param, + sig(Router.predict_batch)[param].kind, inspect.Parameter.KEYWORD_ONLY) # --------------------------------------------------------------- aliases check_true("Agent.predict is Agent.system_one", Agent.predict is Agent.system_one) From 4506d394b7f078b05b109755ffba9dfc033924b5 Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 01:29:11 +0530 Subject: [PATCH 2/6] fix(serve): declare predict_batch hook refusals, doc types, and health test hygiene (#909) --- laya/router.py | 10 +++++----- tests/test_serve.py | 8 +++++--- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/laya/router.py b/laya/router.py index c70896f8e..b51ea42fb 100644 --- a/laya/router.py +++ b/laya/router.py @@ -1185,7 +1185,7 @@ def route_batch( ``questions``. hooks_timeout: Override the Router's ``hooks_timeout`` for this call, applied to every request's ``on_route`` dispatch, as on :meth:`route`. - hooks: Per-call hook or sequence of hooks for this call. + hooks (HookArg): Per-call hook or sequence of hooks for this call. hooks_raise: Override the Router's ``hooks_raise`` policy for this call. """ if not isinstance(requests, SequenceABC) or isinstance(requests, (str, bytes)): @@ -1267,15 +1267,15 @@ def predict_batch( ``lang_guess`` routing overrides and ``max_len`` / ``head_max_len`` token-budget overrides. batch_size: Optional maximum number of states per Agent forward-pass batch. - hooks_timeout: Override the Router's ``hooks_timeout`` for this call. min_confidence: Optional float or per-bucket mapping for confidence gating. sort_by_length: Forwarded to every ``Agent.predict_batch`` call, so each question group pads to a shorter maximum; see ``Agent.predict_batch``. Results retain the input order either way. Silently dropped for an attached agent whose ``predict_batch`` predates the knob (#294). - hooks: Per-call hook or sequence of hooks for this call. - on_predict_start: Plain callable or sequence of callables for start events. - on_predict_end: Plain callable or sequence of callables for end events. + hooks_timeout: Override the Router's ``hooks_timeout`` for this call. + hooks (HookArg): Per-call hook or sequence of hooks for this call. + on_predict_start (PredictHookArg): Plain callable or sequence of callables for start events. + on_predict_end (PredictHookArg): Plain callable or sequence of callables for end events. hooks_raise: Override the Router's ``hooks_raise`` policy for this call. Returns: diff --git a/tests/test_serve.py b/tests/test_serve.py index 075e370ee..08d2a6ecb 100644 --- a/tests/test_serve.py +++ b/tests/test_serve.py @@ -2419,7 +2419,7 @@ def test_batch_call_controls_are_exactly_predict_batch_kwargs_or_refusal(): from laya.router import Router taken = set(inspect.signature(Router.predict_batch).parameters) - {"self", "requests"} - declared = set(BATCH_BODY_CALL_CONTROLS) | {"hooks_timeout"} + declared = set(BATCH_BODY_CALL_CONTROLS) | set(BODY_REFUSALS) assert taken == declared, "predict_batch() takes %s; serve declares %s" % ( sorted(taken), sorted(declared)) @@ -2682,10 +2682,12 @@ def test_health_liveness_is_open_but_the_detail_needs_the_bearer(monkeypatch): assert leaked not in anonymous.json() -def test_health_without_an_api_key_is_unchanged(): +def test_health_without_an_api_key_is_unchanged(monkeypatch): """A deployment that set no key never asked to be gated, so it gets the whole payload.""" from fastapi.testclient import TestClient + monkeypatch.delenv("LAYA_API_KEY", raising=False) + monkeypatch.delenv("LAYA_IDLE_UNLOAD_SECONDS", raising=False) client = TestClient(create_app(router=FakeRouter())) _, returned = _health_return_keys() assert sorted(client.get("/health").json()) == sorted(returned) @@ -2764,7 +2766,7 @@ def test_http_api_page_documents_exactly_the_health_fields(): "device_is_preference says %r with checkpoint_devices %r" % ( sample["device_is_preference"], sample["checkpoint_devices"])) if sample["checkpoint_devices"]: - assert sample["device"] == next(iter(sample["checkpoint_devices"].values())), ( + assert sample["device"] == sample["checkpoint_devices"][sample["loaded"][0]], ( "device must be the first resident checkpoint's device, as serve.py computes it") # And the shape of a fallback entry, which no page has ever spelled out: read from the dict the From 2420736325d1f0dc2b8632ef97449743c9afbb70 Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 01:53:07 +0530 Subject: [PATCH 3/6] test(hooks): exclude self parameter from positional prefix checks in test_hooks_api (#909) --- tests/test_hooks_api.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py index 5c1643cb7..b90a2e915 100644 --- a/tests/test_hooks_api.py +++ b/tests/test_hooks_api.py @@ -184,10 +184,12 @@ def check_param(name, fn, param, default, kind=None): # Positional compatibility: hook parameters are keyword-only to protect positional callers check("Router.route_batch/positional prefix", - [p.name for p in sig(Router.route_batch).values() if p.kind != inspect.Parameter.KEYWORD_ONLY], + [p.name for p in sig(Router.route_batch).values() + if p.kind != inspect.Parameter.KEYWORD_ONLY and p.name != "self"], ["requests", "hooks_timeout"]) check("Router.predict_batch/positional prefix", - [p.name for p in sig(Router.predict_batch).values() if p.kind != inspect.Parameter.KEYWORD_ONLY], + [p.name for p in sig(Router.predict_batch).values() + if p.kind != inspect.Parameter.KEYWORD_ONLY and p.name != "self"], ["requests", "batch_size", "min_confidence", "sort_by_length"]) for param in ("hooks", "hooks_raise"): check("Router.route_batch/%s is keyword-only" % param, From 5b1c7c8e7201be71cad032f5f8051312ef5c4d4e Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 14:07:50 +0530 Subject: [PATCH 4/6] fix(mcp): separate hooks_timeout error message from callable hooks refusal in RemoteRouter (#909) --- laya/mcp/remote.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py index cb6e4bf46..ec5e1c2df 100644 --- a/laya/mcp/remote.py +++ b/laya/mcp/remote.py @@ -175,7 +175,9 @@ def predict( head_max_len: Optional[int] = None, min_confidence: Optional[float] = None, ) -> Dict[str, Any]: - if any(value is not None for value in (hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout)): + if hooks_timeout is not None: + raise RemoteError("unsupported_remote", "hooks_timeout belongs to the server's hooks") + if any(value is not None for value in (hooks, on_predict_start, on_predict_end, hooks_raise)): raise RemoteError("unsupported_remote", "hooks are callables and cannot be sent to laya-serve; install them on the server") body: Dict[str, Any] = {"state": state, "questions": questions} @@ -211,7 +213,9 @@ def predict_batch( keep working. The server applies its own batching inside each call. """ results: List[Dict[str, Any]] = [] - if any(value is not None for value in (hooks, on_predict_start, on_predict_end, hooks_raise, hooks_timeout)): + if hooks_timeout is not None: + raise RemoteError("unsupported_remote", "hooks_timeout belongs to the server's hooks") + if any(value is not None for value in (hooks, on_predict_start, on_predict_end, hooks_raise)): raise RemoteError("unsupported_remote", "hooks are callables and cannot be sent to laya-serve; install them on the server") for item in requests: From 8feab871c38d73e4a618a3193c683897a3a974bc Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 14:32:35 +0530 Subject: [PATCH 5/6] feat(ts): support per-call hooks in router predictBatch and update docs (#909) --- docs/hooks/api.md | 6 ++- docs/hooks/lifecycle.md | 5 +- laya-ts/README.md | 3 ++ laya-ts/src/index.ts | 2 +- laya-ts/src/router.ts | 23 ++++++++-- laya-ts/tests/router-batch.test.ts | 74 ++++++++++++++++++++++++++++++ 6 files changed, 105 insertions(+), 8 deletions(-) diff --git a/docs/hooks/api.md b/docs/hooks/api.md index c7effc09b..f7284a06d 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 293ca6504..ea7bdc867 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 f8b67aded..b87b626aa 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 517cfeed9..1f62f73b1 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 48e8900b4..567226fd4 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 { - const decisions = this.routeBatch(requests); + const decisions = this.routeBatch(requests, opts); if (decisions.length === 0) return []; const groups = new Map(); @@ -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 { - 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 77c7facaa..22514fe32 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({ From b0be37986b511e65b1b8d9d32d48c3ba7edb7fd5 Mon Sep 17 00:00:00 2001 From: Swatantra Yadav Date: Sun, 4 Oct 2026 19:29:19 +0530 Subject: [PATCH 6/6] fix(router): preserve hooks_timeout positional prefix on predict_batch (#909) --- docs/hooks/api.md | 4 ++-- laya/mcp/remote.py | 2 +- laya/router.py | 4 ++-- tests/test_hooks.py | 14 +++++++++----- tests/test_hooks_api.py | 4 ++-- 5 files changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/hooks/api.md b/docs/hooks/api.md index f7284a06d..0c1bceafc 100644 --- a/docs/hooks/api.md +++ b/docs/hooks/api.md @@ -296,8 +296,8 @@ 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, +router.predict_batch(requests, batch_size=None, hooks_timeout=None, min_confidence=None, + sort_by_length=False, hooks=None, on_predict_start=None, on_predict_end=None, hooks_raise=None) router.system_one(...) # alias of predict diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py index ec5e1c2df..c5f7efc93 100644 --- a/laya/mcp/remote.py +++ b/laya/mcp/remote.py @@ -195,10 +195,10 @@ def predict_batch( self, requests: Sequence[Dict[str, Any]], batch_size: Optional[int] = None, + hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, *, - hooks_timeout: Optional[float] = None, hooks=None, on_predict_start=None, on_predict_end=None, diff --git a/laya/router.py b/laya/router.py index b51ea42fb..1e57b1d2b 100644 --- a/laya/router.py +++ b/laya/router.py @@ -1227,10 +1227,10 @@ def predict_batch( self, requests: Sequence[Dict[str, Any]], batch_size: Optional[int] = None, + hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, *, - hooks_timeout: Optional[float] = None, hooks=None, on_predict_start=None, on_predict_end=None, @@ -1267,12 +1267,12 @@ def predict_batch( ``lang_guess`` routing overrides and ``max_len`` / ``head_max_len`` token-budget overrides. batch_size: Optional maximum number of states per Agent forward-pass batch. + hooks_timeout: Override the Router's ``hooks_timeout`` for this call. min_confidence: Optional float or per-bucket mapping for confidence gating. sort_by_length: Forwarded to every ``Agent.predict_batch`` call, so each question group pads to a shorter maximum; see ``Agent.predict_batch``. Results retain the input order either way. Silently dropped for an attached agent whose ``predict_batch`` predates the knob (#294). - hooks_timeout: Override the Router's ``hooks_timeout`` for this call. hooks (HookArg): Per-call hook or sequence of hooks for this call. on_predict_start (PredictHookArg): Plain callable or sequence of callables for start events. on_predict_end (PredictHookArg): Plain callable or sequence of callables for end events. diff --git a/tests/test_hooks.py b/tests/test_hooks.py index 817a738cd..49edfe244 100644 --- a/tests/test_hooks.py +++ b/tests/test_hooks.py @@ -1682,15 +1682,19 @@ def on_predict_start(self, ctx): kw_decisions = r_pos.route_batch([req("pos1")], 1.0, hooks=[RouteTrace()]) check("router_batch/route_batch keyword-only hooks", len(kw_decisions), 1) -# predict_batch keeps hooks_timeout keyword-only -pos_results = r_pos.predict_batch([req("pos2")], 8, hooks_timeout=1.0, hooks=[PerCallTrace()]) -check("router_batch/predict_batch keyword-only controls", len(pos_results), 1) +# predict_batch preserves hooks_timeout positional prefix from main +pos_results = r_pos.predict_batch([req("pos2")], 8, 1.0, hooks=[PerCallTrace()]) +check("router_batch/predict_batch positional hooks_timeout", len(pos_results), 1) + +# predict_batch takes per-call hooks as keyword-only +kw_results = r_pos.predict_batch([req("pos2")], 8, hooks=[PerCallTrace()]) +check("router_batch/predict_batch keyword-only hooks", len(kw_results), 1) # keyword-only enforcement: passing hook controls positionally raises TypeError check_raises("router_batch/route_batch rejects positional hooks", TypeError, lambda: r_pos.route_batch([req("pos1")], 1.0, [RouteTrace()])) -check_raises("router_batch/predict_batch rejects positional hooks_timeout past sort_by_length", TypeError, - lambda: r_pos.predict_batch([req("pos2")], 8, None, False, 1.0)) +check_raises("router_batch/predict_batch rejects positional hooks", TypeError, + lambda: r_pos.predict_batch([req("pos2")], 8, 1.0, None, False, [PerCallTrace()])) # --------------------------------------------------------------- report diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py index b90a2e915..8d97c165f 100644 --- a/tests/test_hooks_api.py +++ b/tests/test_hooks_api.py @@ -190,11 +190,11 @@ def check_param(name, fn, param, default, kind=None): check("Router.predict_batch/positional prefix", [p.name for p in sig(Router.predict_batch).values() if p.kind != inspect.Parameter.KEYWORD_ONLY and p.name != "self"], - ["requests", "batch_size", "min_confidence", "sort_by_length"]) + ["requests", "batch_size", "hooks_timeout", "min_confidence", "sort_by_length"]) for param in ("hooks", "hooks_raise"): check("Router.route_batch/%s is keyword-only" % param, sig(Router.route_batch)[param].kind, inspect.Parameter.KEYWORD_ONLY) -for param in ("hooks_timeout", "hooks", "on_predict_start", "on_predict_end", "hooks_raise"): +for param in ("hooks", "on_predict_start", "on_predict_end", "hooks_raise"): check("Router.predict_batch/%s is keyword-only" % param, sig(Router.predict_batch)[param].kind, inspect.Parameter.KEYWORD_ONLY)