Files
laya/tests/test_hooks_api.py
Emiliano G.O.andGitHub 27b6576abd feat(hooks): BaseHook and process-wide default hooks (#276)
- BaseHook: a no-op base class for subclassing, exported at the top level next
  to the Hook protocol.
- laya.hooks gains a process-wide registry: default_hooks, set_default_hooks,
  add_default_hook, clear_default_hooks, and compose_hooks. Defaults run before
  installed and per-call hooks, and cover the Router lifecycle events too.
- Tests and docs updated (api, index, patterns, examples).
2026-09-24 08:26:54 +05:30

159 lines
6.8 KiB
Python

"""API-stability guard for prediction hooks.
These tests pin the public hook surface (parameter names, kinds, defaults, context fields,
lifecycle events, exports) so a change that would break callers fails here first. If a change
is intentional, update this file in the same commit.
Run: python tests/test_hooks_api.py
"""
import dataclasses
import inspect
import os
import sys
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
import laya # 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
PASS, FAIL = [], []
def check(name, got, want):
if got == want:
PASS.append(name)
else:
FAIL.append("%s: got %r, want %r" % (name, got, want))
def check_true(name, cond, detail=""):
if cond:
PASS.append(name)
else:
FAIL.append("%s%s" % (name, ": " + detail if detail else ""))
def sig(fn):
return inspect.signature(fn).parameters
def check_param(name, fn, param, default, kind=None):
params = sig(fn)
if param not in params:
FAIL.append("%s/%s: missing parameter" % (name, param))
return
p = params[param]
check("%s/%s default" % (name, param), p.default, default)
if kind is not None:
check("%s/%s kind" % (name, param), p.kind, kind)
HOOK_KEYS = {
"hooks": None,
"on_predict_start": None,
"on_predict_end": None,
"hooks_raise": True,
"hooks_concurrent": True,
}
# --------------------------------------------------------------- constructors
for label, fn in (("Agent.__init__", Agent.__init__), ("load", load),
("Router.__init__", Router.__init__), ("ONNXAgent.__init__", ONNXAgent.__init__)):
for param, default in HOOK_KEYS.items():
check_param(label, fn, param, default)
# Router keeps lang_guess too
check_param("Router.__init__", Router.__init__, "lang_guess", None)
# --------------------------------------------------------------- predict surfaces
for label, fn in (("Agent.predict_batch", Agent.predict_batch),
("Agent.system_one", Agent.system_one),
("Router.predict", Router.predict),
("ONNXAgent.system_one", ONNXAgent.system_one)):
check_param(label, fn, "hooks", None)
check_param(label, fn, "on_predict_start", None)
check_param(label, fn, "on_predict_end", None)
check_param(label, fn, "hooks_raise", None)
check_param("Agent.predict_batch", Agent.predict_batch, "batch_size", None)
# per-call token-budget overrides
for label, fn in (("Agent.predict_batch", Agent.predict_batch),
("Agent.system_one", Agent.system_one),
("Router.predict", Router.predict),
("ONNXAgent.system_one", ONNXAgent.system_one)):
check_param(label, fn, "max_len", None)
check_param(label, fn, "head_max_len", None)
# 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)
# --------------------------------------------------------------- aliases
check_true("Agent.predict is Agent.system_one", Agent.predict is Agent.system_one)
check_true("Router.system_one is Router.predict", Router.system_one is Router.predict)
check_true("ONNXAgent.predict is ONNXAgent.system_one", ONNXAgent.predict is ONNXAgent.system_one)
# --------------------------------------------------------------- context
FIELDS = ["states", "questions", "run_id", "results", "decision", "model", "agent", "router",
"max_len", "head_max_len", "usage", "started_at", "elapsed_ms", "error"]
check("PredictContext fields", [f.name for f in dataclasses.fields(PredictContext)], FIELDS)
check("PredictContext/states required", PredictContext.__dataclass_fields__["states"].default,
dataclasses.MISSING)
check("PredictContext/questions required", PredictContext.__dataclass_fields__["questions"].default,
dataclasses.MISSING)
for optional in ("results", "decision", "model", "agent", "router", "usage", "elapsed_ms", "error"):
check("PredictContext/%s default None" % optional,
PredictContext.__dataclass_fields__[optional].default, None)
check_true("PredictContext/skip exists", callable(getattr(PredictContext, "skip", None)))
check_true("PredictContext/run_id has a factory",
PredictContext.__dataclass_fields__["run_id"].default_factory is not dataclasses.MISSING)
# --------------------------------------------------------------- hook protocol
check("Hook lifecycle events", set(HOOK_EVENTS),
{"on_predict_start", "on_predict_end", "on_route", "on_load", "on_evict", "on_error"})
for event in HOOK_EVENTS:
check_true("Hook/%s declared" % event, hasattr(Hook, event))
check_true("PredictHook is callable-typed", callable(PredictHook))
# --------------------------------------------------------------- exports
for name in ("PredictContext", "PredictHook", "Hook", "BaseHook"):
check_true("__all__/%s" % name, name in laya.__all__)
check_true("laya.%s exists" % name, hasattr(laya, name))
# BaseHook is the concrete no-op base class; all six events exist and are callable.
for event in HOOK_EVENTS:
check_true("BaseHook/%s callable" % event, callable(getattr(BaseHook, event, None)))
# process-wide default registry lives in laya.hooks (not the top level)
for helper in ("default_hooks", "set_default_hooks", "add_default_hook", "clear_default_hooks",
"compose_hooks"):
check_true("laya.hooks/%s exists" % helper, callable(getattr(__import__("laya.hooks", fromlist=[helper]), helper, None)))
check_true("defaults/not exported at top level", not hasattr(laya, "set_default_hooks"))
# --------------------------------------------------------------- class defaults
for label, cls in (("Agent", Agent), ("Router", Router), ("ONNXAgent", ONNXAgent)):
check("%s/hooks default" % label, cls.hooks, ())
check("%s/hooks_raise default" % label, cls.hooks_raise, True)
check("%s/hooks_concurrent default" % label, cls.hooks_concurrent, True)
check("%s/_hooks_lock default" % label, cls._hooks_lock, None)
# Agent and ONNXAgent carry the checkpoint id for ctx.model; Router has no single model.
for label, cls in (("Agent", Agent), ("ONNXAgent", ONNXAgent)):
check("%s/model_id default" % label, cls.model_id, None)
# runtime registration surface
for label, cls in (("Agent", Agent), ("Router", Router), ("ONNXAgent", ONNXAgent)):
for method in ("add_hook", "remove_hook", "hooks_installed"):
check_true("%s/%s exists" % (label, method), callable(getattr(cls, method, None)))
print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
for f in FAIL:
print(" FAIL", f)
if not FAIL:
print("all hook API tests passed")
sys.exit(1 if FAIL else 0)