Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/hooks/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 5 additions & 3 deletions laya/hooks.py
Original file line number Diff line number Diff line change
@@ -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

Expand Down
34 changes: 34 additions & 0 deletions tests/test_hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -1697,6 +1697,40 @@ def on_predict_start(self, ctx):
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:
Expand Down
Loading