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.

docs(hooks): scope plain callables to on_predict_start=/on_predict_end=

Aashishdec2fd90bffa
diff --git a/docs/hooks/index.md b/docs/hooks/index.md
index 2c96282c..f4b23393 100644
--- a/docs/hooks/index.md
+++ b/docs/hooks/index.md
@@ -73,8 +73,11 @@ hooks.set_default_hooks(hooks=[Tracer()])
There are three ideas.
1. **A hook is a callable or an object.** A plain function is convenient for one event; an
- object is convenient for several. Both are passed to `hooks=` / `on_predict_start=` /
- `on_predict_end=`.
+ object is convenient for several. Only the object form goes to `hooks=` -- a plain callable
+ there is refused at construction, because `hooks=` reads for lifecycle methods (`on_route`,
+ `on_load`, `on_evict`, `on_predict_start`, `on_predict_end`) and a bare function has none of
+ them. Pass a plain callable as `on_predict_start=` or `on_predict_end=`; those are the
+ single-event parameters, so a callable is exactly what they take.
2. **Every hook of one call shares one mutable `PredictContext`.** It carries the states,
questions, results, routing decision, model name, usage, timing and any error. A call can carry
diff --git a/laya/hooks.py b/laya/hooks.py
index 224eea20..b680808c 100644
--- a/laya/hooks.py
+++ b/laya/hooks.py
@@ -1,8 +1,10 @@
"""Opt-in prediction hooks: observe or shape every decision without forking.
-A hook is either a plain callable or an object implementing any subset of the lifecycle
-methods on `Hook`. Hooks are configured on `Agent` / `Router` and can be overridden per call.
-Everything here is pure Python: importing `laya` must not start pulling torch.
+A hook on `hooks=` is an object implementing any subset of the lifecycle methods on `Hook`;
+a plain callable is only accepted on the single-event `on_predict_start=` / `on_predict_end=`
+parameters, because `hooks=` reads for method names and a bare function has none. Hooks are
+configured on `Agent` / `Router` and can be overridden per call. Everything here is pure
+Python: importing `laya` must not start pulling torch.
"""
from __future__ import annotations
diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 49edfe24..813622f0 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -1697,6 +1697,40 @@ check_raises("router_batch/predict_batch rejects positional hooks", TypeError,
lambda: r_pos.predict_batch([req("pos2")], 8, 1.0, None, False, [PerCallTrace()]))
+# --------------------------------------------------------------- docs prose for plain callables
+# `docs/hooks/index.md` and the `laya/hooks.py` module docstring used to say a plain callable
+# goes to `hooks=` alongside `on_predict_start=` / `on_predict_end=`. `_coerce_hooks` has always
+# refused that -- the check at laya/hooks.py:177-182 raises TypeError before the callable is
+# installed, because `hooks=` reads for lifecycle method names. `docs/hooks/api.md`,
+# `docs/hooks/patterns.md`, and `docs/hooks/errors.md` all said the opposite; only the primer
+# and the module docstring drifted. The gate drives the real behaviour and bans the pre-fix
+# wording in both places, so the page cannot regress to the sentence that made callers type
+# `laya.load(..., hooks=[lambda ctx: None])` and hit a TypeError at construction.
+from pathlib import Path as _P # noqa: E402
+
+_hook_index = _P(__file__).resolve().parents[1] / "docs" / "hooks" / "index.md"
+_hooks_mod = _P(__file__).resolve().parents[1] / "laya" / "hooks.py"
+_index_text = _hook_index.read_text(encoding="utf-8")
+_hooks_text = _hooks_mod.read_text(encoding="utf-8")
+
+check_true("docs_hooks/index.md drops the 'hooks=/on_predict_start=/on_predict_end=' equal-share claim",
+ "Both are passed to `hooks=` / `on_predict_start=` /" not in _index_text)
+check_true("docs_hooks/index.md scopes plain callable to on_predict_start=/on_predict_end=",
+ "Pass a plain callable as `on_predict_start=` or `on_predict_end=`" in _index_text)
+check_true("laya/hooks.py docstring drops 'a hook is either a plain callable'",
+ "A hook is either a plain callable" not in _hooks_text)
+check_true("laya/hooks.py docstring names the single-event parameters as the plain-callable path",
+ "plain callable is only accepted on the single-event" in _hooks_text)
+
+# Live driver: `normalise_hooks` on the two paths.
+check_raises("hooks= rejects a plain callable at construction",
+ TypeError, lambda: normalise_hooks(hooks=[lambda ctx: None]))
+_plain_ok = normalise_hooks(on_predict_start=lambda ctx: None)
+check_true("on_predict_start= accepts a plain callable",
+ len(_plain_ok) == 1 and hasattr(_plain_ok[0], "on_predict_start"),
+ "got %r" % (_plain_ok,))
+
+
# --------------------------------------------------------------- report
print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
for f_ in FAIL: