From 40b52a08db39eba1ee3791643f1cbb0bb1584202 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 3 Oct 2026 23:49:39 +0000 Subject: [PATCH 1/2] fix(router): accept per-call hooks in predict_batch Router.predict_batch rejected hooks= even though predict and the docs accept it. Compose per-call hooks after the installed ones, with the same None and empty-list handling, and mirror that on the TypeScript batch path. Co-authored-by: Nithilan Kumaran --- docs/hooks/api.md | 5 +- 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 +++++++++++++++++++++++++++ laya/mcp/remote.py | 8 ++- laya/router.py | 31 ++++++++---- laya/serve.py | 7 +-- tests/test_hooks_api.py | 1 + tests/test_mcp_remote.py | 2 + tests/test_router_batch.py | 81 ++++++++++++++++++++++++++++++ tests/test_serve.py | 13 ++--- 13 files changed, 228 insertions(+), 27 deletions(-) diff --git a/docs/hooks/api.md b/docs/hooks/api.md index c7effc09b..7a3f25b16 100644 --- a/docs/hooks/api.md +++ b/docs/hooks/api.md @@ -296,6 +296,9 @@ 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, hooks_timeout=None, min_confidence=None, + sort_by_length=False, hooks=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 +307,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`, `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({ diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py index 0631e6220..1a5ba6548 100644 --- a/laya/mcp/remote.py +++ b/laya/mcp/remote.py @@ -196,6 +196,7 @@ def predict_batch( hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, + hooks=None, ) -> List[Dict[str, Any]]: """One ``/v1/systemone`` call per request, answers in input order. @@ -203,9 +204,14 @@ def predict_batch( while a Router batch lets each request carry its own questions and controls, so the general form is the per-request call. ``batch_size`` and ``sort_by_length`` shape forward passes and have no meaning here; they are accepted and ignored so callers written against ``Router`` - keep working. The server applies its own batching inside each call. + keep working. The server applies its own batching inside each call. ``hooks`` is accepted + so the signature matches ``Router.predict_batch`` and refused: a hook is a callable and + cannot be sent to ``laya-serve``. """ results: List[Dict[str, Any]] = [] + if hooks is not None: + raise RemoteError("unsupported_remote", + "hooks are callables and cannot be sent to laya-serve; install them on the server") if hooks_timeout is not None: raise RemoteError("unsupported_remote", "hooks_timeout belongs to the server's hooks") for item in requests: diff --git a/laya/router.py b/laya/router.py index 0d907adb2..45864862d 100644 --- a/laya/router.py +++ b/laya/router.py @@ -1167,6 +1167,7 @@ def route_batch( self, requests: Sequence[Dict[str, Any]], hooks_timeout: Optional[float] = None, + hooks=None, ) -> List[RouteDecision]: """Route a heterogeneous request batch without loading any checkpoints. @@ -1182,6 +1183,9 @@ 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 hooks, appended after any installed on the Router and applied to + every request's ``on_route`` dispatch, as on :meth:`route`. ``None`` and ``[]`` + add nothing. """ if not isinstance(requests, SequenceABC) or isinstance(requests, (str, bytes)): raise TypeError("requests must be a sequence of request dictionaries") @@ -1210,6 +1214,7 @@ def route_batch( task=request.get("task"), lang=request.get("lang"), lang_guess=request.get("lang_guess"), + hooks=hooks, hooks_timeout=hooks_timeout, ) ) @@ -1223,6 +1228,7 @@ def predict_batch( hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, + hooks=None, ) -> List[Dict[str, Any]]: """Route and execute a heterogeneous request batch with minimal model churn. @@ -1260,12 +1266,21 @@ def predict_batch( 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 hooks, composed the same way as on :meth:`predict`: installed + hooks first, then this list. ``None`` and ``[]`` add nothing. The list runs + for every request, including ``on_route`` inside :meth:`route_batch`. 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) + # Composed before routing, as `predict` does, so a bad per-call hook raises before any + # checkpoint loads and the same list reaches `on_route` and the predict lifecycle. + # `None` and `[]` normalise to nothing, so they leave the installed hooks alone. + active = compose_hooks(self.hooks, hooks) + raise_errors = self.hooks_raise + timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout) + decisions = self.route_batch(requests, hooks_timeout=hooks_timeout, hooks=hooks) if not decisions: return [] @@ -1283,14 +1298,12 @@ def predict_batch( # `predict` returns as it is. results: List[Any] = [None] * len(requests) answered = 0 - # `compose_hooks`, not `list(self.hooks)`: this is the composition `predict` uses at its - # own dispatch site, and it is what merges in `set_default_hooks`. Reading the instance - # 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 - timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout) + # `active` is the composition `predict` uses at its own dispatch site (`compose_hooks`, + # not `list(self.hooks)`), including per-call `hooks=`. That is what merges in + # `set_default_hooks`. Reading the instance 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`. for model_name, indices in groups.items(): agent = self.load(model_name) diff --git a/laya/serve.py b/laya/serve.py index b259b9981..57cf46ab1 100644 --- a/laya/serve.py +++ b/laya/serve.py @@ -145,9 +145,10 @@ # against ``inspect.signature(Router.predict_batch)`` (call-level) and against the MCP tool's own # item key list (per-request), so a control added to either side has to be placed on one side of # this split -- forwarded, refused, or moved to the item tuple -- before the suite goes green. -# ``hooks_timeout`` is refused on the batch path the same way it is on the single path: it belongs -# to ``predict_batch``'s call-level args but governs how the *deployment's* hooks execute, so a -# caller cannot be allowed to shorten or lengthen that deadline from an HTTP body. +# ``hooks`` and ``hooks_timeout`` are refused on the batch path the same way they are on the single +# path: they belong to ``predict_batch``'s call-level args, but a hook is a callable that runs in +# the server process and ``hooks_timeout`` governs how the *deployment's* hooks execute, so a +# caller cannot send either from an HTTP body. BATCH_BODY_CALL_CONTROLS = ("batch_size", "min_confidence", "sort_by_length") BATCH_BODY_ITEM_CONTROLS = ("max_len", "head_max_len", "task", "lang", "lang_guess") diff --git a/tests/test_hooks_api.py b/tests/test_hooks_api.py index aa5fb0ac8..babb427af 100644 --- a/tests/test_hooks_api.py +++ b/tests/test_hooks_api.py @@ -167,6 +167,7 @@ def check_param(name, fn, param, default, kind=None): # 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) +check_param("Router.predict_batch", Router.predict_batch, "hooks", 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) diff --git a/tests/test_mcp_remote.py b/tests/test_mcp_remote.py index ef412075d..2ba3a8601 100644 --- a/tests/test_mcp_remote.py +++ b/tests/test_mcp_remote.py @@ -253,6 +253,8 @@ def test_remote_batch_refuses_hook_timeouts_and_item_hooks(serve): items = [{"state": "x", "questions": _questions()}] with pytest.raises(RemoteError, match="hooks_timeout"): router.predict_batch(items, hooks_timeout=1) + with pytest.raises(RemoteError, match="callables"): + router.predict_batch(items, hooks=[]) items[0]["hooks"] = [lambda ctx: None] with pytest.raises(RemoteError, match="per-request hooks"): router.predict_batch(items) diff --git a/tests/test_router_batch.py b/tests/test_router_batch.py index 65354349d..98707841b 100644 --- a/tests/test_router_batch.py +++ b/tests/test_router_batch.py @@ -198,6 +198,87 @@ def test_same_checkpoint_different_questions_split_agent_batches(fake_agent): assert calls[1][2] == q2 +def test_predict_batch_accepts_per_call_hooks(): + """`hooks=` matches `predict`: accepted, ordered after `self.hooks`, once per item. + + `None` and `[]` add nothing, so a batch with no per-call hooks behaves as if the + argument was omitted. A per-call hook runs for every request, including `on_route`. + No checkpoint is built: the agent is attached, the same way the router hook tests stub one. + """ + class Stub: + def predict_batch(self, states, questions, batch_size=None, **overrides): + return [ + {"model": "stub", "answers": {"seen": state}, "usage": {}} + for state in states + ] + + order = [] + + class Installed: + def on_route(self, ctx): + order.append(("installed", "route", ctx.states[0])) + + def on_predict_start(self, ctx): + order.append(("installed", "start", ctx.states[0])) + + def on_predict_end(self, ctx): + order.append(("installed", "end", ctx.states[0])) + + class PerCall: + def on_route(self, ctx): + order.append(("percall", "route", ctx.states[0])) + + def on_predict_start(self, ctx): + order.append(("percall", "start", ctx.states[0])) + + def on_predict_end(self, ctx): + order.append(("percall", "end", ctx.states[0])) + + router = Router(hooks=[Installed()]) + router.attach("english", Stub()) + items = [request("one", model="english"), request("two", model="english")] + results = router.predict_batch(items, hooks=[PerCall()]) + assert [r["answers"]["seen"] for r in results] == ["one", "two"] + # route_batch runs before any predict hook; within a checkpoint, ends unwind in reverse. + assert order == [ + ("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", "two"), + ("percall", "end", "two"), + ("installed", "end", "one"), + ("percall", "end", "one"), + ] + + order.clear() + router.predict_batch(items, hooks=None) + none_order = list(order) + order.clear() + router.predict_batch(items, hooks=[]) + empty_order = list(order) + order.clear() + router.predict_batch(items) + assert none_order == empty_order == order + assert none_order == [ + ("installed", "route", "one"), + ("installed", "route", "two"), + ("installed", "start", "one"), + ("installed", "start", "two"), + ("installed", "end", "two"), + ("installed", "end", "one"), + ] + + bare = Router() + bare.attach("english", Stub()) + assert [r["answers"]["seen"] for r in bare.predict_batch(items, hooks=None)] == ["one", "two"] + assert [r["answers"]["seen"] for r in bare.predict_batch(items, hooks=[])] == ["one", "two"] + + def test_predict_batch_honours_hooks_timeout(fake_agent): def slow_hook(ctx): sleep(0.3) diff --git a/tests/test_serve.py b/tests/test_serve.py index 075e370ee..d2b035855 100644 --- a/tests/test_serve.py +++ b/tests/test_serve.py @@ -2410,16 +2410,17 @@ def _batch_client(monkeypatch): def test_batch_call_controls_are_exactly_predict_batch_kwargs_or_refusal(): """A control added to ``Router.predict_batch`` must be placed on one side of the line. - Either serve forwards it (``BATCH_BODY_CALL_CONTROLS``) or it refuses it (``hooks_timeout``, - the one hook-execution arg that ``predict_batch`` takes). Silently ignoring a new kwarg is the - failure mode this pin exists to catch: the same reasoning that made ``/v1/systemone`` refuse - ``hooks_timeout`` in #724 applies to the batch path -- a caller cannot shorten the deadline - on which the operator's own hooks execute. + Either serve forwards it (``BATCH_BODY_CALL_CONTROLS``) or it refuses it (``hooks`` and + ``hooks_timeout``, the hook-execution args that ``predict_batch`` takes). Silently ignoring a + new kwarg is the failure mode this pin exists to catch: the same reasoning that made + ``/v1/systemone`` refuse ``hooks`` and ``hooks_timeout`` applies to the batch path -- a caller + cannot install a callable in the server process or shorten the deadline on which the + operator's own hooks execute. """ 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) | {"hooks_timeout", "hooks"} assert taken == declared, "predict_batch() takes %s; serve declares %s" % ( sorted(taken), sorted(declared)) From de3a1493575a807ae13082dd91350c508470bf5d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 4 Oct 2026 00:02:24 +0000 Subject: [PATCH 2/2] docs(router): annotate predict_batch hooks parameter The strict docs build warns when an Args entry has no type. Give hooks the HookArg annotation predict's composition already uses, on route_batch, predict_batch, and RemoteRouter.predict_batch. Co-authored-by: Nithilan Kumaran --- laya/mcp/remote.py | 3 ++- laya/router.py | 20 ++++++++++---------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/laya/mcp/remote.py b/laya/mcp/remote.py index 1a5ba6548..37027566b 100644 --- a/laya/mcp/remote.py +++ b/laya/mcp/remote.py @@ -29,6 +29,7 @@ import urllib.parse from typing import Any, Dict, List, Optional, Sequence, Union +from ..hooks import HookArg from ..router import Router from ..serve import BODY_CONTROLS, BODY_REFUSALS @@ -196,7 +197,7 @@ def predict_batch( hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, - hooks=None, + hooks: HookArg = None, ) -> List[Dict[str, Any]]: """One ``/v1/systemone`` call per request, answers in input order. diff --git a/laya/router.py b/laya/router.py index 45864862d..67c997e20 100644 --- a/laya/router.py +++ b/laya/router.py @@ -38,8 +38,8 @@ from .confidence import apply_confidence_gate, check_min_confidence from .hooks import ( - HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks, - validate_timeout, + HookArg, HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, + normalise_hooks, validate_timeout, ) from .hooks import _SKIP_DEFAULTS from .lang import analyse @@ -1167,7 +1167,7 @@ def route_batch( self, requests: Sequence[Dict[str, Any]], hooks_timeout: Optional[float] = None, - hooks=None, + hooks: HookArg = None, ) -> List[RouteDecision]: """Route a heterogeneous request batch without loading any checkpoints. @@ -1183,9 +1183,9 @@ 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 hooks, appended after any installed on the Router and applied to - every request's ``on_route`` dispatch, as on :meth:`route`. ``None`` and ``[]`` - add nothing. + hooks (HookArg): Per-call hooks, appended after any installed on the Router and + applied to every request's ``on_route`` dispatch, as on :meth:`route`. ``None`` + and ``[]`` add nothing. """ if not isinstance(requests, SequenceABC) or isinstance(requests, (str, bytes)): raise TypeError("requests must be a sequence of request dictionaries") @@ -1228,7 +1228,7 @@ def predict_batch( hooks_timeout: Optional[float] = None, min_confidence: Optional[float] = None, sort_by_length: bool = False, - hooks=None, + hooks: HookArg = None, ) -> List[Dict[str, Any]]: """Route and execute a heterogeneous request batch with minimal model churn. @@ -1266,9 +1266,9 @@ def predict_batch( 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 hooks, composed the same way as on :meth:`predict`: installed - hooks first, then this list. ``None`` and ``[]`` add nothing. The list runs - for every request, including ``on_route`` inside :meth:`route_batch`. + hooks (HookArg): Per-call hooks, composed the same way as on :meth:`predict`: + installed hooks first, then this list. ``None`` and ``[]`` add nothing. The + list runs for every request, including ``on_route`` inside :meth:`route_batch`. Returns: One normal Router prediction result per request, in the same order as the input.