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.

83.2 KB
Raw Blame
"""Prediction hooks: observe or shape a decision without a model or a download.

The Agent path uses the same weight-free fake as `test_batch.py` (the real `predict_batch`
with `_encode_state` / `_forward` / `_decode_answers` stubbed). The Router path patches
`laya.agent.Agent` so a model build never touches the Hub.

Run: python tests/test_hooks.py
"""
import contextvars
import inspect
import os
import sys
import threading
import time
import warnings

import numpy as np

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import laya.agent as _agent_mod  # noqa: E402
from laya.agent import Agent  # noqa: E402
from laya.hooks import OptionStabilityHook, normalise_hooks  # noqa: E402
from laya.router import RouteDecision, Router  # 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 check_raises(name, exc, fn):
    try:
        fn()
    except exc:
        PASS.append(name)
        return
    except BaseException as other:  # noqa: BLE001
        FAIL.append("%s: raised %r, want %r" % (name, other, exc))
        return
    FAIL.append("%s: did not raise %r" % (name, exc))


NQ = 2
QUESTIONS = {"a": {"type": "noul", "instructions": "?"}, "b": {"type": "noul", "instructions": "?"}}


# `_encode_state` items carry the state truncation counts that `predict_batch` reports in `usage` (#174)
NO_STATE_STATS = {"state_tokens": 0, "state_tokens_used": 0, "state_tokens_dropped": 0, "truncated": False}


def make_fake():
    """A real `predict_batch` with the three composed helpers stubbed out."""
    fake = Agent.__new__(Agent)
    fake.tok = type("Tok", (), {"pad_token_id": 0})()
    fake._to_internal = staticmethod(Agent._to_internal).__func__
    fake._encode_states = []
    fake._forward_calls = []

    def _encode_state(state, ids, internal):
        fake._encode_states.append(state)
        return [{"ids": [1, 2, 3], "markers": [0, 1], "qtype": 2, "state_stats": NO_STATE_STATS} for _ in ids]

    def _forward(b):
        n = b["input_ids"].shape[0]
        fake._forward_calls.append(n)
        return np.zeros((n, 2), dtype=np.float32), np.full((n, 2), 0.5, dtype=np.float32)

    def _decode_answers(logits, act, items, ids, internal, offset):
        return {"_offset": offset}

    fake._encode_state = _encode_state
    fake._forward = _forward
    fake._decode_answers = _decode_answers
    return fake


class FakeAgent:
    def system_one(self, state, questions):
        return {"model": "fake", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}


# --------------------------------------------------------------- order and context
events = []
results_at_start = []
results_at_end = []
run_id_start = []
run_id_end = []


def start(ctx):
    events.append(("start", ctx))
    results_at_start.append(ctx.results)
    run_id_start.append(ctx.run_id)


def end(ctx):
    events.append(("end", ctx))
    results_at_end.append(ctx.results)
    run_id_end.append(ctx.run_id)


f = make_fake()
res = f.predict_batch(["s0", "s1"], QUESTIONS, on_predict_start=start, on_predict_end=end)
check("order/start then end", [e[0] for e in events], ["start", "end"])
check("order/once each", len(events), 2)
check("context/start sees states", events[0][1].states, ["s0", "s1"])
check("context/start sees questions", events[0][1].questions, QUESTIONS)
check("context/start has no results", results_at_start, [None])
check_true("context/end results is the returned object", results_at_end[0] is res)
check("context/end result count", len(results_at_end[0]), 2)
check_true("context/elapsed_ms set", events[1][1].elapsed_ms is not None)
check("context/usage aggregated", events[1][1].usage, {"input_tokens": 12, "output_tokens": 0})
check_true("context/agent set", events[1][1].agent is f)
check_true("context/run_id is a non-empty string",
           isinstance(run_id_start[0], str) and bool(run_id_start[0]))
check("context/run_id is shared by start and end", run_id_end[0], run_id_start[0])

_rids = []
_f2 = make_fake()
_f2.predict_batch(["s0"], QUESTIONS, on_predict_end=lambda c: _rids.append(c.run_id))
_f2.predict_batch(["s0"], QUESTIONS, on_predict_end=lambda c: _rids.append(c.run_id))
check("context/run_id differs per call", len(set(_rids)), 2)


# --------------------------------------------------------------- mutation
def rewrite(ctx):
    ctx.states = ["rewritten"]
    ctx.questions = {"a": {"type": "noul", "instructions": "?"}}


f = make_fake()
f.predict_batch(["orig"], QUESTIONS, on_predict_start=rewrite)
check("mutation/start rewrite is what gets encoded", f._encode_states, ["rewritten"])


def replace_results(ctx):
    ctx.results = [{"model": "replaced"}]


f = make_fake()
res = f.predict_batch(["s0"], QUESTIONS, on_predict_end=replace_results)
check("mutation/end rewrite is returned", res, [{"model": "replaced"}])


# --------------------------------------------------------------- caching short-circuit
end_calls = {"n": 0}


def cache_hit(ctx):
    ctx.skip([{"model": "cached"}])


def count_end(ctx):
    end_calls["n"] += 1


f = make_fake()
res = f.predict_batch(["s0"], QUESTIONS, on_predict_start=cache_hit, on_predict_end=count_end)
check("skip/returns cached results", res, [{"model": "cached"}])
check("skip/no forward pass", f._forward_calls, [])
check("skip/end still runs", end_calls["n"], 1)


# --------------------------------------------------------------- installed vs per-call
order = []
f = make_fake()
f.hooks = normalise_hooks(on_predict_start=lambda ctx: order.append("installed"))
f.predict_batch(["s0"], QUESTIONS, on_predict_start=lambda ctx: order.append("percall"))
check("installed/per-call additive and ordered", order, ["installed", "percall"])

seq = []
f = make_fake()
f.predict_batch(["s0"], QUESTIONS,
                on_predict_start=[lambda c: seq.append(1), lambda c: seq.append(2)])
check("sequence/runs in order", seq, [1, 2])


# --------------------------------------------------------------- system_one inherits
seen = []
f = make_fake()
f.hooks = normalise_hooks(on_predict_start=lambda ctx: seen.append(ctx.states))
out = f.system_one("state", QUESTIONS)
check("system_one/hook fired", seen, [["state"]])
check_true("system_one/returns a dict", isinstance(out, dict))


# --------------------------------------------------------------- error policy
def boom(ctx):
    raise ValueError("hook boom")


f = make_fake()
check_raises("hooks_raise=True/propagates", ValueError,
             lambda: f.predict_batch(["s0"], QUESTIONS, on_predict_start=boom))

f = make_fake()
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    res = f.predict_batch(["s0"], QUESTIONS, on_predict_start=boom, hooks_raise=False)
check("hooks_raise=False/continues", len(res), 1)
check_true("hooks_raise=False/warns",
           any(issubclass(w.category, RuntimeWarning) for w in caught))

# ... but it arrives once per distinct message, not once per failure. The emit site is a plain
# `warnings.warn` inside `laya/hooks.py::dispatch` (`:543-547`) whose text names the hook, the event and
# the exception, so a hook that fails the same way repeats the same string, and Python's default
# `RuntimeWarning` filter dedups by (message, category, caller line) for the rest of the process.
# Every other `catch_warnings(record=True)` block in this suite (five of them) sets
# `simplefilter("always")`, which is why the suite never contradicted the page.
f = make_fake()
with warnings.catch_warnings(record=True) as dedup:
    warnings.simplefilter("default")
    for _ in range(3):
        f.predict_batch(["s0"], QUESTIONS, on_predict_start=boom, hooks_raise=False)
check("warnings/identical repeats dedup to one line under the default filter", len(dedup), 1)
check("warnings/and that line is the hook failure",
      [str(w.message) for w in dedup], ["laya: hook _StartAdapter.on_predict_start failed: hook boom"])

# The other half of the same claim: dedup keys on the message text, so a hook whose error varies with
# the call -- a retry counter, a request id -- is not deduped at all. That is the arm that stays noisy.
class Drifting:
    def __init__(self):
        self.n = 0

    def on_predict_start(self, ctx):
        self.n += 1
        raise ValueError("hook attempt %d" % self.n)


f = make_fake()
drifting = Drifting()
with warnings.catch_warnings(record=True) as varies:
    warnings.simplefilter("default")
    for _ in range(3):
        f.predict_batch(["s0"], QUESTIONS, hooks=[drifting], hooks_raise=False)
check("warnings/a varying message prints once per distinct text", len(varies), 3)
check("warnings/all three name the same hook and event",
      sorted({str(w.message).rsplit(": hook ", 1)[0] for w in varies}),
      ["laya: hook Drifting.on_predict_start failed"])
check("warnings/and the three texts are the three attempts",
      sorted(str(w.message).rsplit(": ", 1)[1] for w in varies),
      ["hook attempt 1", "hook attempt 2", "hook attempt 3"])

# What makes two *distinct* texts is the hook type and the event named in the message: two classes
# failing in one call are two lines, one hook failing on both events is two lines, but two instances
# of the same class failing the same way collapse into one -- they produce the same string.
class WarnPairA:
    def on_predict_start(self, ctx):
        raise ValueError("hook boom")


class WarnPairB:
    def on_predict_start(self, ctx):
        raise ValueError("hook boom")


f = make_fake()
with warnings.catch_warnings(record=True) as same_type:
    warnings.simplefilter("default")
    f.predict_batch(["s0"], QUESTIONS, hooks=[WarnPairA(), WarnPairA()], hooks_raise=False)
check("warnings/two instances of one class share one line", len(same_type), 1)

f = make_fake()
with warnings.catch_warnings(record=True) as other_type:
    warnings.simplefilter("default")
    f.predict_batch(["s0"], QUESTIONS, hooks=[WarnPairA(), WarnPairB()], hooks_raise=False)
check("warnings/two classes failing alike are two lines", len(other_type), 2)


class WarnBothEvents:
    def on_predict_start(self, ctx):
        raise ValueError("hook boom")

    def on_predict_end(self, ctx):
        raise ValueError("hook boom")


f = make_fake()
with warnings.catch_warnings(record=True) as both_events:
    warnings.simplefilter("default")
    f.predict_batch(["s0"], QUESTIONS, hooks=[WarnBothEvents()], hooks_raise=False)
check("warnings/one hook failing on both events is two lines",
      [str(w.message).rsplit(": hook ", 1)[0] for w in both_events],
      ["laya: hook WarnBothEvents.on_predict_start failed",
       "laya: hook WarnBothEvents.on_predict_end failed"])

# And the call site is the other half of the key: the same hook failing from two different dispatch
# lines -- an Agent call and a Router call -- has byte-identical text and still prints twice.
class WarnTwoSites:
    def on_predict_start(self, ctx):
        raise ValueError("same text")


class WarnRouteFake:
    """The smallest thing a Router will attach: a `predict_batch` that answers."""

    def predict_batch(self, states, questions, batch_size=None, **overrides):
        return [{"model": "fake", "answers": {"seen": s},
                 "usage": {"input_tokens": len(s), "output_tokens": 0}} for s in states]

    def system_one(self, state, questions, **overrides):
        return self.predict_batch([state], questions, **overrides)[0]


two_sites = WarnTwoSites()
f = make_fake()
with warnings.catch_warnings(record=True) as sites:
    warnings.simplefilter("default")
    f.predict_batch(["s0"], QUESTIONS, hooks=[two_sites], hooks_raise=False)
    rr = Router()
    rr.attach("english", WarnRouteFake())
    rr.predict_batch([{"state": "a", "questions": QUESTIONS, "model": "english"}],
                     hooks=[two_sites], hooks_raise=False)
check("warnings/the same text from two call sites prints twice", len(sites), 2)
check("warnings/and the identical texts come from different sites",
      len({(os.path.basename(w.filename), w.lineno) for w in sites}), 2)


class ErrHook:
    def __init__(self):
        self.errors = []

    def on_error(self, ctx):
        self.errors.append(ctx.error)


fail_seen = {}


def end_on_fail(ctx):
    fail_seen["error"] = ctx.error


def bad_forward(b):
    raise RuntimeError("infer boom")


rec = ErrHook()
f = make_fake()
f._forward = bad_forward
raised = None
try:
    f.predict_batch(["s0"], QUESTIONS, hooks=[rec], on_predict_end=end_on_fail)
except RuntimeError as exc:
    raised = exc
check_true("on_error/propagates original", isinstance(raised, RuntimeError))
check("on_error/fired once", len(rec.errors), 1)
check("on_error/saw the error", str(rec.errors[0]), "infer boom")
check("on_error/end still ran", str(fail_seen.get("error")), "infer boom")


class BadErrHook:
    def on_error(self, ctx):
        raise ValueError("hook error")


f = make_fake()
f._forward = bad_forward
raised = None
try:
    f.predict_batch(["s0"], QUESTIONS, hooks=[BadErrHook()])
except BaseException as exc:  # noqa: BLE001
    raised = exc
check_true("on_error/failing hook does not mask the original", isinstance(raised, RuntimeError))
check_true("on_error/failing hook is chained",
           isinstance(getattr(raised, "__context__", None), ValueError))


# a start hook that raises must still run on_error and the end hooks
class StartErrRec:
    def __init__(self):
        self.errors = []

    def on_error(self, ctx):
        self.errors.append(ctx.error)


start_fail_seen = []


def raising_start(ctx):
    raise ValueError("start boom")


def end_after_start_fail(ctx):
    start_fail_seen.append(ctx.error)


rec2 = StartErrRec()
f = make_fake()
raised = None
try:
    f.predict_batch(["s0"], QUESTIONS, hooks=[rec2],
                    on_predict_start=raising_start, on_predict_end=end_after_start_fail)
except ValueError as exc:
    raised = exc
check_true("start failure/propagates", isinstance(raised, ValueError))
check("start failure/on_error fired", len(rec2.errors), 1)
check("start failure/end fired with the error", len(start_fail_seen), 1)
check("start failure/end saw the error", str(start_fail_seen[0]), "start boom")


# ctx.model carries the agent's model id
f = make_fake()
f.model_id = "convaiinnovations/laya"
models = []
f.predict_batch(["s0"], QUESTIONS, on_predict_end=lambda c: models.append(c.model))
check("context/model is the agent model_id", models, ["convaiinnovations/laya"])


# --------------------------------------------------------------- empty inputs
empty = []
f = make_fake()
res = f.predict_batch([], QUESTIONS,
                      on_predict_start=lambda c: empty.append(("s", c.results)),
                      on_predict_end=lambda c: empty.append(("e", c.results)))
check("empty states/returns []", res, [])
check("empty states/start results None", empty[0][1], None)
check("empty states/end results []", empty[1][1], [])

empty = []
f = make_fake()
f.predict_batch(["s0"], {}, on_predict_end=lambda c: empty.append(c.results))
check("empty questions/end sees empty results",
      empty[0],
      [{"model": "laya-rl-agent", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}])


# --------------------------------------------------------------- input guards and rescue
f = make_fake()
check_raises("guard/bare string raises", TypeError, lambda: f.predict_batch("nope", QUESTIONS))
f = make_fake()
check_raises("guard/bare dict raises", TypeError, lambda: f.predict_batch({"body": "x"}, QUESTIONS))


def normalise_state(ctx):
    ctx.states = [ctx.states]


f = make_fake()
f.predict_batch("nope", QUESTIONS, on_predict_start=normalise_state)
check("guard/a hook can normalise a bare string", f._encode_states, ["nope"])


# --------------------------------------------------------------- hand-built instance
f = make_fake()
res = f.predict_batch(["s0", "s1", "s2"], QUESTIONS)
check("defaults/unset hooks are a no-op", len(res), 3)
check("defaults/offsets unchanged", [r["answers"]["_offset"] for r in res], [0, NQ, 2 * NQ])


# --------------------------------------------------------------- dynamic registration
class Tag:
    def __init__(self, log, tag):
        self.log = log
        self.tag = tag

    def on_predict_end(self, ctx):
        self.log.append(self.tag)


log = []
f = make_fake()
f.add_hook(Tag(log, "a"))
f.predict_batch(["s0"], QUESTIONS)
check("add_hook/fires", log, ["a"])
check("remove_hook/returns True", f.remove_hook(f.hooks[-1]), True)
log.clear()
f.predict_batch(["s0"], QUESTIONS)
check("remove_hook/no longer fires", log, [])
check("remove_hook/unknown returns False", f.remove_hook(object()), False)

log = []
f = make_fake()
check_true("add_hook/returns self", f.add_hook([Tag(log, "x"), Tag(log, "y")]) is f)
f.predict_batch(["s0"], QUESTIONS)
check("add_hook/sequence order", log, ["x", "y"])

log = []
f = make_fake()
f.add_hook(Tag(log, "installed"))
with f.hooks_installed(Tag(log, "temp")):
    f.predict_batch(["s0"], QUESTIONS)
f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/only during the block", log, ["installed", "temp", "installed"])

# ...and the block restores the PREVIOUS list, which is what the docs promise. Installing a hook
# that is already installed is legal (`add_hook` appends), so the block has to take its own copy
# back off and leave the caller's in place. Removing by identity instead took both, so a hook an
# application had installed once was silently uninstalled by any block that happened to name it.
log = []
f = make_fake()
already = Tag(log, "already")
f.add_hook(already)
check("hooks_installed/pre-installed hook is present", len(f.hooks), 1)
with f.hooks_installed(already):
    check("hooks_installed/the block adds a second copy", len(f.hooks), 2)
    f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/restores the previous list", len(f.hooks), 1)
log.clear()
f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/the pre-installed hook still fires after the block", log, ["already"])

# The block removes ONE occurrence per hook it added -- the most recent match by identity -- and
# touches nothing else. Two cases pin that, because the obvious alternatives get them wrong: a
# snapshot restore reinstates a list from before the inner block and so drops a hook the inner
# block legitimately installed; and removing by identity takes the caller's own copy too.
log = []
f = make_fake()
outer, inner = Tag(log, "outer"), Tag(log, "inner")
with f.hooks_installed(outer):
    check("hooks_installed/overlapping blocks: outer installed", len(f.hooks), 1)
    with f.hooks_installed(inner):
        check("hooks_installed/overlapping blocks: both installed", len(f.hooks), 2)
    check("hooks_installed/overlapping blocks: inner exit leaves the outer hook",
          len(f.hooks), 1)
    check_true("hooks_installed/overlapping blocks: and it is the outer one",
               f.hooks[0] is outer)
check("hooks_installed/overlapping blocks: outer exit leaves nothing", len(f.hooks), 0)

# a hook added INSIDE the block is not the block's to remove, so it outlives it
log = []
f = make_fake()
added_inside = Tag(log, "added-inside")
with f.hooks_installed(Tag(log, "temp")):
    f.add_hook(added_inside)
    check("hooks_installed/add_hook inside: both present", len(f.hooks), 2)
check("hooks_installed/add_hook inside: survives the block", len(f.hooks), 1)
check_true("hooks_installed/add_hook inside: and it is the one that was added",
           f.hooks[0] is added_inside)
log.clear()
f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/add_hook inside: still fires after the block", log, ["added-inside"])

# sequences are flattened, matching add_hook and the hooks= parameter
log = []
f = make_fake()
with f.hooks_installed([Tag(log, "x"), Tag(log, "y")]):
    f.predict_batch(["s0"], QUESTIONS)
f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/list of hooks fires during the block", log, ["x", "y"])
check("hooks_installed/list of hooks removed after the block", len(f.hooks), 0)

log = []
f = make_fake()
with f.hooks_installed((Tag(log, "a"),), Tag(log, "b")):
    f.predict_batch(["s0"], QUESTIONS)
check("hooks_installed/tuple arg and varargs mix in order", log, ["a", "b"])

# and the same hook passed twice is the same case with no pre-install at all
log = []
f = make_fake()
with f.hooks_installed(Tag(log, "t"), Tag(log, "t")):
    pass
check("hooks_installed/no residue when nothing was installed before", len(f.hooks), 0)


# --------------------------------------------------------------- skip() counts
# `skip()` replaces the whole call, so the count is part of the contract its docstring
# states: one result per state, or a single result for the whole call (the shape
# `predict_long` takes as the document's answer -- its scan hands the hook every window
# as a state). Anything else used to pass through unchecked: `Router.predict` then
# indexed `results[0]` of an empty list (an `IndexError`, a 500 over serve), and
# `predict_batch` returned a shorter list than it was given states, silently dropping
# rows the caller was about to zip against.

def _skipper(*results):
    def hook(ctx):
        ctx.skip(list(results))
    return hook


CACHED = {"model": "cache", "usage": {},
          "answers": {"a": {"type": "noul", "noul": 0.9}, "b": {"type": "noul", "noul": 0.1}}}

# one per state: the docs' cache pattern, and the shape `predict_batch` returns
f = make_fake()
res = f.predict_batch(["s0", "s1", "s2"], QUESTIONS, on_predict_start=_skipper(CACHED, CACHED, CACHED))
check("skip/one per state is accepted", len(res), 3)
check("skip/forward never ran", len(f._encode_states), 0)
check("skip/the payload comes back untouched", res[0], CACHED)

# one result for the whole call: what a `predict_long` scan's hook answers with, even
# though `ctx.states` holds every window. Pinned here because the scan's own check
# (`predict_long: a start hook answered this state with N results`) reads the other
# shape as a mistake, and this is the path it accepts.
f = make_fake()
res = f.predict_batch(["s0", "s1"], QUESTIONS, on_predict_start=_skipper(CACHED))
check("skip/one result for the whole call is accepted", len(res), 1)
check("skip/whole-call answer: forward never ran", len(f._encode_states), 0)

# short and long counts are refused at the hook, with the contract in the message
f = make_fake()
err = None
try:
    f.predict_batch(["s0", "s1", "s2"], QUESTIONS, on_predict_start=_skipper(CACHED, CACHED))
except ValueError as exc:
    err = exc
check_true("skip/a short list is refused", err is not None, repr(err))
check_true("skip/the refusal names the contract",
           err is not None and "one per state" in str(err), repr(err))
check("skip/a refused skip leaves inference untouched", len(f._encode_states), 0)

f = make_fake()
err = None
try:
    f.predict_batch(["s0"], QUESTIONS, on_predict_start=_skipper())
except ValueError as exc:
    err = exc
check_true("skip/an empty answer for a non-empty call is refused", err is not None, repr(err))
check_true("skip/the refusal counts the states",
           err is not None and "(1); got 0" in str(err), repr(err))

# under hooks_raise=False a refusal warns like any other hook failure and the call still
# gets an answer: the cache is wrong, not the request.
f = make_fake()
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    res = f.predict_batch(["s0"], QUESTIONS, on_predict_start=_skipper(), hooks_raise=False)
check("skip/refusal under hooks_raise=False falls back to inference", len(res), 1)
check_true("skip/refusal under hooks_raise=False is warned",
           any(issubclass(w.category, RuntimeWarning) and "ctx.skip()" in str(w.message)
               for w in caught), [str(w.message) for w in caught])

# Router.predict used to turn an empty answer into `ctx.results[0]` -- IndexError, a 500
# over serve. The same refusal, raised where the contract is written.
_skip_router = Router(default="english")
_skip_router.attach("english", FakeAgent())
check_raises("router/skip empty is a ValueError, not an IndexError",
             ValueError,
             lambda: _skip_router.predict("hello", QUESTIONS,
                                          on_predict_start=lambda ctx: ctx.skip([])))

log = []
r = Router(default="english")
r.add_hook(Tag(log, "router"))
r.attach("english", FakeAgent())
r.predict("hello", QUESTIONS)
check("router/add_hook fires", log, ["router"])


# --------------------------------------------------------------- per-call token budget
def make_len_fake():
    fake = make_fake()
    fake._seen = []

    def _encode(state, ids, internal, max_len=None, head_max_len=None):
        fake._seen.append((max_len, head_max_len))
        return [{"ids": [1, 2, 3], "markers": [0, 1], "qtype": 2, "state_stats": NO_STATE_STATS} for _ in ids]

    fake._encode_state = _encode
    return fake


f = make_len_fake()
f.predict_batch(["s"], QUESTIONS, max_len=128, head_max_len=64)
check("budget/per-call kwargs reach _encode_state", f._seen, [(128, 64)])

f = make_len_fake()
f.predict_batch(["s"], QUESTIONS, on_predict_start=lambda c: setattr(c, "max_len", 200))
check("budget/hook-set ctx reaches _encode_state", f._seen, [(200, None)])

f = make_len_fake()
f.predict_batch(["s"], QUESTIONS)
check("budget/default passes no override", f._seen, [(None, None)])


class LenFake:
    def __init__(self):
        self.seen = []

    def system_one(self, state, questions, max_len=None, head_max_len=None):
        self.seen.append((max_len, head_max_len))
        return {"model": "x", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}


lf = LenFake()
r = Router(default="english")
r.attach("english", lf)
r.predict("hello", QUESTIONS, max_len=256, head_max_len=128)
check("budget/router per-call reaches the agent", lf.seen, [(256, 128)])

lf = LenFake()
r = Router(default="english")
r.attach("english", lf)
r.predict("hello", QUESTIONS, on_predict_start=lambda c: setattr(c, "head_max_len", 96))
check("budget/router hook-set reaches the agent", lf.seen, [(None, 96)])


class StrictFake:
    """An agent-like object that does not accept the override kwargs."""

    def system_one(self, state, questions):
        return {"model": "x", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}


r = Router(default="english")
r.attach("english", StrictFake())
r.predict("hello", QUESTIONS)
check("budget/default does not pass override kwargs", True, True)


# --------------------------------------------------------------- context semantics
from laya.hooks import PredictContext  # noqa: E402

_c1 = PredictContext(states=[], questions={})
_c2 = PredictContext(states=[], questions={})
check_true("context/hashable by identity", isinstance(hash(_c1), int))
check("context/two contexts are never equal", _c1 == _c2, False)


# --------------------------------------------------------------- validation
class NotAHook:
    pass


check_raises("validation/hooks= rejects a class", TypeError, lambda: normalise_hooks(hooks=[NotAHook]))
check_raises("validation/hooks= rejects a plain callable", TypeError,
             lambda: normalise_hooks(hooks=[lambda ctx: None]))
check_raises("validation/on_predict_start must be callable", TypeError,
             lambda: normalise_hooks(on_predict_start=123))


class BadMethod:
    on_predict_start = 5


check_raises("validation/hook method must be callable", TypeError,
             lambda: normalise_hooks(hooks=[BadMethod()]))


# ------------------------------------------------- docs/hooks/errors.md's table, executed
# The "Configuration errors" table is the page's only statement about which bad configuration
# raises what, and its `example` column is the part a reader copies. Row "non-callable event"
# used to read `on_predict_start = 5`, which is the row beneath it: both raise
# `on_predict_start must be callable, got int` from `_StartAdapter.__init__`, so the branch that
# validates an event attribute on a `hooks=` entry (laya/hooks.py:186-190) was unreachable from
# the page while the page still claimed it. This gate parses the table, calls
# `normalise_hooks(<example>)` for every row exactly as the page spells it, and pins the message
# each row produces -- a row whose example drifts onto another row's error fails here rather
# than in a reader's terminal. Weight-free: `normalise_hooks` builds no model.
import re as _re  # noqa: E402
from pathlib import Path as _CfgPath  # noqa: E402

_cfg_doc = _CfgPath(__file__).resolve().parents[1] / "docs" / "hooks" / "errors.md"
_cfg_section = _cfg_doc.read_text(encoding="utf-8").split("## Configuration errors", 1)[1] \
    .split("\n## ", 1)[0]
_cfg_rows = [[c.strip() for c in line.strip().strip("|").split("|")]
             for line in _cfg_section.split("\n") if line.strip().startswith("|")][2:]


def _cfg_message(cells):
    """The TypeError text one row's example raises, or 'NO ERROR' if it raises nothing."""
    parts = _re.split(r"`\s*,\s*with\s*`", cells[2].strip("`"), maxsplit=1)
    ns = {"normalise_hooks": normalise_hooks, "MyHook": type("MyHook", (), {})}
    if len(parts) > 1:
        exec(parts[1], ns)                       # the class or value the example needs
    try:
        eval("normalise_hooks(%s)" % parts[0], ns)
    except TypeError as exc:
        return str(exc)
    return "NO ERROR"


_cfg_events = "on_predict_start, on_predict_end, on_route, on_load, on_evict, on_error"
_cfg_implements = ("hooks entries must implement at least one of %s; got %%s. "
                   "Pass a plain callable as on_predict_start=/on_predict_end= instead."
                   % _cfg_events)
_CFG_EXPECT = [
    ("class instead of instance", "hooks entries must be instances, not classes; got MyHook. "
                                  "Instantiate it first."),
    ("no lifecycle method", _cfg_implements % "object"),
    ("non-callable event", "hooks entry BadMethod.on_predict_start must be callable, got int"),
    ("non-callable convenience hook", "on_predict_start must be callable, got int"),
    ("plain callable in `hooks=`", _cfg_implements % "function"),
]

_cfg_msgs = [_cfg_message(c) for c in _cfg_rows]
check("errors.md's configuration table still names these five cases, in order",
      [c[0] for c in _cfg_rows], [c for c, _ in _CFG_EXPECT])
check("every row is raised at construction, as its column claims",
      sorted({c[1] for c in _cfg_rows}), ["construction"])
for (case, want), got in zip(_CFG_EXPECT, _cfg_msgs):
    check("errors.md row %r reaches its own message" % case, got, want)
check("the event-attribute row does not raise the convenience hook's error",
      _cfg_msgs[2] == _cfg_msgs[3], False)
def _cfg_check_id(msg):
    """The check a message came from, with the `got <type>` token it embeds stripped."""
    return msg.split("; got")[0]


check("an object and a lambda trip the same check, and no two rows share a message",
      [_cfg_check_id(_cfg_msgs[1]) == _cfg_check_id(_cfg_msgs[4]), len(set(_cfg_msgs))],
      [True, 5])


# ------------------------------------------- docs/hooks/patterns.md's audit hook actually runs
# The "Audit log" block is that page's answer to "how do I record every decision", and a reader
# pastes it as written. It imported `json` only, while the body it documents writes to
# `sys.stdout`, so the first call raised NameError inside the hook -- and `hooks_raise` defaults
# to True, so the recording hook failed the very request it was recording. `docs/hooks/examples.md`
# carries the same hook and does import sys. The gate execs the block from the page with a stub
# `laya` -- 10 of the page's 21 python blocks end in a bare `laya.load(...)` and none of those
# imports it, so that is the page's own convention, not an accident here -- then installs the hook
# it hands to `laya.load` through the real `normalise_hooks` + `dispatch` and calls it with a real
# PredictContext over two states -- so what runs is the page's code on the library's path.
import ast as _A  # noqa: E402
import builtins as _B  # noqa: E402
import contextlib as _CL  # noqa: E402
import io as _IO  # noqa: E402
import json as _JSON  # noqa: E402
import types as _T  # noqa: E402
from laya.hooks import dispatch as _dispatch  # noqa: E402
from pathlib import Path as _DocPath  # noqa: E402

_pat_doc = _DocPath(__file__).resolve().parents[1] / "docs" / "hooks" / "patterns.md"
_pat_section = _pat_doc.read_text(encoding="utf-8").split("### Audit log", 1)[1]
_pat_block = _pat_section.split("```python\n", 1)[1].split("\n```", 1)[0]


def _pat_free_names(src):
    """Names the block reads but never binds, builtins excluded."""
    tree = _A.parse(src)
    bound = set(dir(_B))
    for node in _A.walk(tree):
        if isinstance(node, (_A.Import, _A.ImportFrom)):
            bound.update((a.asname or a.name).split(".")[0] for a in node.names)
        elif isinstance(node, _A.Name) and isinstance(node.ctx, (_A.Store, _A.Del)):
            bound.add(node.id)
        elif isinstance(node, _A.arg):
            bound.add(node.arg)
        elif isinstance(node, (_A.FunctionDef, _A.AsyncFunctionDef, _A.ClassDef)):
            bound.add(node.name)
        elif isinstance(node, _A.ExceptHandler) and node.name:
            bound.add(node.name)
    return sorted({n.id for n in _A.walk(tree)
                   if isinstance(n, _A.Name) and isinstance(n.ctx, _A.Load)} - bound)


check("the audit block's only free name is the `laya` its `laya.load` line never imports",
      _pat_free_names(_pat_block), ["laya"])

_pat_registered = []
_pat_ns = {"laya": _T.SimpleNamespace(load=lambda *a, **kw: _pat_registered.append(kw))}
try:
    exec(compile(_pat_block, "docs/hooks/patterns.md", "exec"), _pat_ns)
    _pat_hooks = normalise_hooks(**_pat_registered[0])
except Exception as _pat_exc:  # noqa: BLE001
    _pat_hooks = []
    _pat_install_error = "%s: %s" % (type(_pat_exc).__name__, _pat_exc)
else:
    _pat_install_error = None

_pat_hook = next(iter(_pat_hooks), None)
check("the block installs without raising, through the real normalise_hooks",
      _pat_install_error, None)
check("the page's `laya.load(...)` call carries exactly one keyword, `on_predict_end`",
      [sorted(_pat_registered[0]) if _pat_registered else None], [["on_predict_end"]])
check("it becomes exactly one hook, and it is the `audit` the block defines",
      [len(_pat_hooks), getattr(_pat_hook, "fn", None) is _pat_ns.get("audit")], [1, True])

_pat_ctx = PredictContext(states=["charged twice", "cancel my plan"], questions={})
_pat_ctx.results = [{"answers": {"intent": "billing"}, "routing": {"model": "english"}, "usage": None},
                    {"answers": {"intent": "support"}}]
_pat_ctx.model = "english"
_pat_ctx.usage = {"input_tokens": 30, "output_tokens": 0}
_pat_ctx.elapsed_ms = 1.5
_pat_out = _IO.StringIO()
try:
    with _CL.redirect_stdout(_pat_out):
        _dispatch(_pat_hooks, "on_predict_end", _pat_ctx)
    _pat_records = [line for line in _pat_out.getvalue().split("\n") if line]
    _pat_error = None
except Exception as _pat_exc:  # noqa: BLE001
    _pat_records = []
    _pat_error = "%s: %s" % (type(_pat_exc).__name__, _pat_exc)

check("the page's hook records both states without raising", _pat_error, None)
check("one JSON record per state", len(_pat_records), 2)
check("each record parses, and carries the call's identity plus the state it describes",
      [sorted(_JSON.loads(_pat_records[0])) if _pat_records else None],
      [["answers", "call_elapsed_ms", "call_usage", "model", "routing", "run_id", "state", "usage"]])
check("the second record is the second state",
      _JSON.loads(_pat_records[1])["state"] if len(_pat_records) > 1 else None, "cancel my plan")


# --------------------------------------------------------------- Router
class RouteHook:
    def __init__(self):
        self.decisions = []

    def on_route(self, ctx):
        self.decisions.append(dict(ctx.decision))
        ctx.decision = RouteDecision(model="multilingual", repo="convaiinnovations/laya/multilingual",
                                     reason="pinned by hook", detection=None, workflow=None)


rh = RouteHook()
r = Router(default="english", hooks=[rh])
decision = r.route("hello", QUESTIONS)
check("router/on_route fired", len(rh.decisions), 1)
check("router/on_route saw the original", rh.decisions[0]["model"], "english")
check("router/on_route can replace the decision", decision["model"], "multilingual")


class LoadHook:
    def __init__(self):
        self.loads = []
        self.evicts = []

    def on_load(self, ctx):
        self.loads.append(ctx.model)

    def on_evict(self, ctx):
        self.evicts.append(ctx.model)


class BuiltAgent(FakeAgent):
    def __init__(self, *args, **kwargs):
        pass


lh = LoadHook()
real_agent = _agent_mod.Agent
_agent_mod.Agent = BuiltAgent
try:
    r = Router(max_loaded=1, default="english", hooks=[lh])
    r.load("english")
    r.load("multilingual")  # evicts english
finally:
    _agent_mod.Agent = real_agent
check("router/on_load fired per build", lh.loads, ["english", "multilingual"])
check("router/on_evict fired on eviction", lh.evicts, ["english"])


predict_seen = {}
r = Router(default="english",
           on_predict_start=lambda ctx: predict_seen.update(decision=dict(ctx.decision)),
           on_predict_end=lambda ctx: predict_seen.update(results=ctx.results))
r.attach("english", FakeAgent())
out = r.predict("hello", QUESTIONS)
check("router/predict start sees the decision", predict_seen["decision"]["model"], "english")
check("router/predict end sees results", len(predict_seen["results"]), 1)
check("router/predict keeps routing", out["routing"]["model"], "english")


class PredictSuccessTrace:
    def __init__(self):
        self.events = []
        self.contexts = []

    def on_predict_start(self, ctx):
        self.events.append("start")
        self.contexts.append(ctx)

    def on_predict_end(self, ctx):
        self.events.append("end")
        self.contexts.append(ctx)


success_trace = PredictSuccessTrace()
r = Router(default="english", hooks=[success_trace])
r.attach("english", FakeAgent())
success_out = r.predict("hello", QUESTIONS)
check("router/predict success lifecycle", success_trace.events, ["start", "end"])
check_true("router/predict success shares one context", success_trace.contexts[0] is success_trace.contexts[1])
check("router/predict success shares one run_id", success_trace.contexts[0].run_id,
      success_trace.contexts[1].run_id)
check("router/predict success keeps the normal result", success_out["routing"]["model"], "english")


class TimedAgent:
    def system_one(self, state, questions, **kwargs):
        return {"model": "timed", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}


class TimedRouter(Router):
    def load(self, model):
        time.sleep(0.001)
        self.load_finished = time.perf_counter()
        return TimedAgent()


timed_trace = PredictSuccessTrace()
timed_router = TimedRouter(default="english", hooks=[timed_trace])
timed_router.predict("hello", QUESTIONS)
timed_ctx = timed_trace.contexts[0]
check_true("router/success elapsed starts after load", timed_ctx.started_at >= timed_router.load_finished)


cached = [{"model": "cached", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}]
r = Router(default="english")
r.attach("english", FakeAgent())
skipped = r.predict("hello", QUESTIONS, on_predict_start=lambda c: c.skip(cached))
check("router/skip returns the cached payload", skipped, cached[0])
check("router/skip still adds routing", skipped.get("routing", {}).get("model"), "english")


class PerCallRoute:
    def __init__(self):
        self.decisions = []

    def on_route(self, ctx):
        self.decisions.append(dict(ctx.decision))


pcr = PerCallRoute()
r = Router(default="english")
r.attach("english", FakeAgent())
r.predict("hello", QUESTIONS, hooks=[pcr])
check("router/per-call hooks apply to on_route", len(pcr.decisions), 1)


class PredictFailureTrace:
    def __init__(self):
        self.events = []
        self.contexts = {}

    def on_predict_start(self, ctx):
        self.events.append("start")

    def on_error(self, ctx):
        self.events.append("error")
        self.contexts["error"] = ctx

    def on_predict_end(self, ctx):
        self.events.append("end")
        self.contexts["end"] = ctx


class RaiseOnRoute(PredictFailureTrace):
    def on_route(self, ctx):
        raise RuntimeError("route failed")


route_trace = RaiseOnRoute()
route_error = None
try:
    Router(hooks=[route_trace]).predict("hello", QUESTIONS)
except RuntimeError as exc:
    route_error = exc
check_true("router/route failure propagates", isinstance(route_error, RuntimeError))
check("router/route failure lifecycle", route_trace.events, ["error", "end"])
check_true("router/route failure has no start", "start" not in route_trace.events)
route_ctx = route_trace.contexts.get("error")
check_true("router/route failure records the original error",
           getattr(route_ctx, "error", None) is route_error)
check("router/route failure has no decision", getattr(route_ctx, "decision", "missing"), None)
check("router/route failure has no model", getattr(route_ctx, "model", "missing"), None)
check("router/route failure has no agent", getattr(route_ctx, "agent", "missing"), None)


class LoadFailRouter(Router):
    def load(self, model):
        raise RuntimeError("load failed")


load_trace = PredictFailureTrace()
load_error = None
try:
    LoadFailRouter(default="english", hooks=[load_trace]).predict("hello", QUESTIONS)
except RuntimeError as exc:
    load_error = exc
check_true("router/load failure propagates", isinstance(load_error, RuntimeError))
check("router/load failure lifecycle", load_trace.events, ["error", "end"])
check_true("router/load failure has no start", "start" not in load_trace.events)
load_ctx = load_trace.contexts.get("error")
check_true("router/load failure records the original error",
           getattr(load_ctx, "error", None) is load_error)
check("router/load failure retains the routed decision",
      (getattr(load_ctx, "decision", None) or {}).get("model"), "english")
check("router/load failure exposes the routed model", getattr(load_ctx, "model", "missing"), "english")
check("router/load failure has no agent", getattr(load_ctx, "agent", "missing"), None)


# --------------------------------------------------------------- Router.predict_batch
# `predict_batch` promises each result is what `predict` returns for that request, so Router-level
# predict hooks must run per request there too. It used to skip them: a redaction hook never ran,
# and the raw state reached the model.
class BatchFake:
    """Records every `predict_batch` call and answers with the state it was given."""

    def __init__(self):
        self.calls = []

    def predict_batch(self, states, questions, batch_size=None, **overrides):
        self.calls.append((list(states), questions, overrides))
        if "boom" in states:
            raise RuntimeError("inference failed")
        return [{"model": "fake", "answers": {"seen": s},
                 "usage": {"input_tokens": len(s), "output_tokens": 0}} for s in states]

    def system_one(self, state, questions, **overrides):
        return self.predict_batch([state], questions, **overrides)[0]


def batch_router(**kwargs):
    r = Router(**kwargs)
    en, ml = BatchFake(), BatchFake()
    r.attach("english", en)
    r.attach("multilingual", ml)
    return r, en, ml


def req(state, model="english", questions=QUESTIONS):
    return {"state": state, "questions": questions, "model": model}


def redact_start(ctx):
    ctx.states = [s.replace("secret", "[redacted]") for s in ctx.states]


r, en, ml = batch_router(on_predict_start=redact_start)
out = r.predict_batch([req("a secret"), req("b secret", "multilingual"), req("c secret")])
check("router_batch/start hook rewrite reaches the agent",
      [c[0] for c in en.calls + ml.calls], [["a [redacted]", "c [redacted]"], ["b [redacted]"]])
check("router_batch/results follow the rewrite", [o["answers"]["seen"] for o in out],
      ["a [redacted]", "b [redacted]", "c [redacted]"])

batch_events = []
batch_results_at_start = {}


class BatchTrace:
    def on_predict_start(self, ctx):
        batch_events.append(("start", ctx.states[0], ctx))
        batch_results_at_start[ctx.states[0]] = ctx.results

    def on_predict_end(self, ctx):
        batch_events.append(("end", ctx.states[0], ctx))

    def on_error(self, ctx):
        batch_events.append(("error", ctx.states[0], ctx))


r, en, ml = batch_router(hooks=[BatchTrace()])
out = r.predict_batch([req("one"), req("two", "multilingual"), req("three")])
check("router_batch/one start and one end per request, per checkpoint group, ends in reverse",
      [(e[0], e[1]) for e in batch_events],
      [("start", "one"), ("start", "three"), ("end", "three"), ("end", "one"),
       ("start", "two"), ("end", "two")])
starts = {e[1]: e[2] for e in batch_events if e[0] == "start"}
ends = {e[1]: e[2] for e in batch_events if e[0] == "end"}
check("router_batch/every request starts and ends", (sorted(starts), sorted(ends)),
      (["one", "three", "two"], ["one", "three", "two"]))
if len(starts) == len(ends) == 3:
    check("router_batch/start sees its own state", starts["two"].states, ["two"])
    check("router_batch/start sees its own questions", starts["two"].questions, QUESTIONS)
    check("router_batch/start sees its own decision", starts["two"].decision["model"], "multilingual")
    check("router_batch/context model is the routed checkpoint", starts["two"].model, "multilingual")
    check_true("router_batch/context agent is the routed agent", starts["two"].agent is ml)
    check_true("router_batch/context router is set", starts["two"].router is r)
    check("router_batch/start has no results", batch_results_at_start, {"one": None, "two": None, "three": None})
    check_true("router_batch/start and end share one context per request", ends["two"] is starts["two"])
    check("router_batch/end sees its own result", ends["two"].results[0]["answers"]["seen"], "two")
    check("router_batch/end result carries routing", ends["two"].results[0]["routing"]["model"], "multilingual")
    check("router_batch/usage is per request", ends["three"].usage, {"input_tokens": 5, "output_tokens": 0})
    check_true("router_batch/elapsed_ms set", ends["one"].elapsed_ms is not None)
    check("router_batch/run_id differs per request", len({c.run_id for c in starts.values()}), 3)
check("router_batch/still one agent call per checkpoint", [c[0] for c in en.calls + ml.calls],
      [["one", "three"], ["two"]])


class PlainDictPin:
    """An on_route hook replacing the decision with a plain dict, which `predict` accepts."""

    def on_route(self, ctx):
        ctx.decision = {**ctx.decision, "model": "multilingual"}


r, en, ml = batch_router(hooks=[PlainDictPin()])
try:
    out = r.predict_batch([req("pinned")])
    got = ([c[0] for c in ml.calls], out[0]["routing"]["model"])
except AttributeError as e:
    got = repr(e)
check("router_batch/an on_route hook may replace the decision with a plain dict", got, ([["pinned"]], "multilingual"))

group_ctxs = []
elapsed_when_first_end_ran = []


def remember_start(ctx):
    group_ctxs.append(ctx)


def first_end(ctx):
    if not elapsed_when_first_end_ran:
        elapsed_when_first_end_ran.append([c.elapsed_ms is not None for c in group_ctxs])


r, en, ml = batch_router(on_predict_start=remember_start, on_predict_end=first_end)
r.predict_batch([req("a"), req("b"), req("c")])
check("router_batch/elapsed_ms is set for the whole group before any end hook runs",
      elapsed_when_first_end_ran, [[True, True, True]])


def replace_result(ctx):
    ctx.results = [{"replaced": ctx.states[0]}]


r, en, ml = batch_router(on_predict_end=replace_result)
check("router_batch/an end hook's replacement is what is returned",
      r.predict_batch([req("x"), req("y", "multilingual")]), [{"replaced": "x"}, {"replaced": "y"}])

cached_x = {"model": "cached", "answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}
r, en, ml = batch_router(on_predict_start=lambda c: c.skip([dict(cached_x)]) if c.states == ["x"] else None)
out = r.predict_batch([req("x"), req("y")])
check("router_batch/skip keeps that state from the agent", [c[0] for c in en.calls], [["y"]])
check("router_batch/skip returns the cached payload", out[0]["model"], "cached")
check("router_batch/skip still adds routing", out[0].get("routing", {}).get("model"), "english")
check("router_batch/the other request is inferred", out[1]["answers"]["seen"], "y")


def annotate_end(ctx):
    ctx.results[0]["audited"] = ctx.decision["model"]


mixed = [req("a secret"), req("b secret", "multilingual"), req("c", "english")]
r, en, ml = batch_router(on_predict_start=redact_start, on_predict_end=annotate_end)
batched = r.predict_batch(mixed)
one_by_one = [r.predict(m["state"], m["questions"], model=m["model"]) for m in mixed]
check("router_batch/identical to one predict call per request", batched, one_by_one)


def budget_start(ctx):
    if ctx.states == ["long"]:
        ctx.max_len = 1024


r, en, ml = batch_router(on_predict_start=budget_start)
r.predict_batch([req("short"), req("long"), req("short again")])
check("router_batch/hook-set token budget reaches the agent for that request only",
      [(c[0], c[2]) for c in en.calls], [(["short", "short again"], {}), (["long"], {"max_len": 1024})])

Q_OTHER = {"other": {"type": "noul", "instructions": "Other?"}}
r, en, ml = batch_router(on_predict_start=lambda c: setattr(c, "questions", Q_OTHER) if c.states == ["b"] else None)
r.predict_batch([req("a"), req("b"), req("c")])
check("router_batch/rewritten questions are batched on their own",
      [(c[0], c[1]) for c in en.calls], [(["a", "c"], QUESTIONS), (["b"], Q_OTHER)])


class StrictBatchFake(BatchFake):
    """An agent-like object whose predict_batch takes no token-budget kwargs."""

    def predict_batch(self, states, questions, batch_size=None):
        return BatchFake.predict_batch(self, states, questions, batch_size)


r = Router(on_predict_start=lambda c: None)
strict = StrictBatchFake()
r.attach("english", strict)
r.predict_batch([req("a"), req("b")], batch_size=8)
check("router_batch/default passes no override kwargs", [c[0] for c in strict.calls], [["a", "b"]])

batch_events = []
r, en, ml = batch_router(hooks=[BatchTrace()])
check_raises("router_batch/inference failure propagates", RuntimeError,
             lambda: r.predict_batch([req("ok", "multilingual"), req("boom"), req("also")]))
check("router_batch/failure pairs every started request with on_error then on_predict_end",
      [(e[0], e[1]) for e in batch_events],
      [("start", "ok"), ("end", "ok"), ("start", "boom"), ("start", "also"),
       ("error", "also"), ("end", "also"), ("error", "boom"), ("end", "boom")])
ends = {e[1]: e[2] for e in batch_events if e[0] == "end"}
check_true("router_batch/end of a failed request sees the error",
           all(isinstance(getattr(ends.get(s), "error", None), RuntimeError) for s in ("boom", "also")))
check_true("router_batch/an earlier group that finished ends without an error",
           "ok" in ends and ends["ok"].error is None)

batch_events = []
r, en, ml = batch_router(hooks=[BatchTrace()],
                         on_predict_start=lambda c: c.skip([dict(cached_x)]) if c.states == ["cached"] else None)
check_raises("router_batch/inference failure with a cache hit in the group propagates", RuntimeError,
             lambda: r.predict_batch([req("cached"), req("boom")]))
ends = {e[1]: e[2] for e in batch_events if e[0] == "end"}
# The caller gets the exception and no result at all, so a cache hit of the failed group was not
# delivered either: reporting it as a success would record a decision nobody received.
check("router_batch/every request of a failed group gets on_error, a cache hit included",
      sorted(e[1] for e in batch_events if e[0] == "error"), ["boom", "cached"])
check_true("router_batch/a cache hit in a failed group ends with the batch's error",
           "cached" in ends and isinstance(ends["cached"].error, RuntimeError))

batch_events = []
r, en, ml = batch_router(hooks=[BatchTrace()],
                         on_predict_start=lambda c: setattr(c, "questions", Q_OTHER) if c.states == ["boom"] else None)
check_raises("router_batch/a later question group's failure propagates", RuntimeError,
             lambda: r.predict_batch([req("inferred"), req("boom")]))
check("router_batch/the earlier question group did run", [c[0] for c in en.calls], [["inferred"], ["boom"]])
ends = {e[1]: e[2] for e in batch_events if e[0] == "end"}
check_true("router_batch/a request inferred before its group failed ends with the batch's error",
           "inferred" in ends and isinstance(ends["inferred"].error, RuntimeError))

batch_events = []
bad_usage = {"model": "cached", "answers": {}, "usage": {"input_tokens": "n/a", "output_tokens": 0}}
r, en, ml = batch_router(hooks=[BatchTrace()],
                         on_predict_start=lambda c: c.skip([dict(bad_usage)]) if c.states == ["bad"] else None)
check_raises("router_batch/a malformed usage block fails the batch", ValueError,
             lambda: r.predict_batch([req("a"), req("bad"), req("c")]))
check("router_batch/a malformed usage block still ends every started request",
      sorted(e[1] for e in batch_events if e[0] == "end"), ["a", "bad", "c"])
check("router_batch/a malformed usage block fails every request of its group",
      sorted(e[1] for e in batch_events if e[0] == "error"), ["a", "bad", "c"])

batch_events = []


def fail_end_on_a(ctx):
    if ctx.states == ["a"]:
        raise ValueError("end hook failed")


r, en, ml = batch_router(on_predict_end=fail_end_on_a, hooks=[BatchTrace()])
check_raises("router_batch/end hook failure propagates", ValueError,
             lambda: r.predict_batch([req("a"), req("b")]))
check("router_batch/end hook failure still ends the other requests",
      [(e[0], e[1]) for e in batch_events if e[0] == "end"], [("end", "b"), ("end", "a")])

batch_events = []
r, en, ml = batch_router(hooks=[BatchTrace()])
check_raises("router_batch/inference failure propagates before a later group", RuntimeError,
             lambda: r.predict_batch([req("boom"), req("later", "multilingual")]))
check("router_batch/a later group never starts", ("start", "later") in [(e[0], e[1]) for e in batch_events], False)
check("router_batch/a later group runs no inference", ml.calls, [])

batch_events = []


def fail_on_b(ctx):
    if ctx.states == ["b"]:
        raise ValueError("start hook failed")


r, en, ml = batch_router(hooks=[BatchTrace()], on_predict_start=fail_on_b)
check_raises("router_batch/start hook failure propagates", ValueError,
             lambda: r.predict_batch([req("a"), req("b"), req("c")]))
check("router_batch/start hook failure still ends every started request",
      [(e[0], e[1]) for e in batch_events],
      [("start", "a"), ("start", "b"), ("error", "b"), ("end", "b"), ("error", "a"), ("end", "a")])
check("router_batch/start hook failure runs no inference", en.calls, [])

# A hook that sets something in start and resets it in end (a contextvar, an OpenTelemetry
# context attach/detach, a logging MDC) is only correct if the requests unwind in reverse: all
# of a group's starts run before any of its ends, so ending in input order resets the wrong layer.
_batch_cv = contextvars.ContextVar("batch_cv", default=None)
_cv_tokens = {}


class CvStack:
    def on_predict_start(self, ctx):
        _cv_tokens[ctx] = _batch_cv.set(ctx.states[0])

    def on_predict_end(self, ctx):
        _batch_cv.reset(_cv_tokens.pop(ctx))


r, en, ml = batch_router(hooks=[CvStack()])
r.predict_batch([req("a"), req("b"), req("c")])
check("router_batch/set-in-start, reset-in-end hooks unwind to the caller's value", _batch_cv.get(), None)
_cv_tokens.clear()
r, en, ml = batch_router(hooks=[CvStack()])
check_raises("router_batch/unwinding a failed batch propagates", RuntimeError,
             lambda: r.predict_batch([req("a"), req("boom"), req("c")]))
check("router_batch/a failed batch also unwinds to the caller's value", _batch_cv.get(), None)
_cv_tokens.clear()

failed_ctxs = []
elapsed_when_first_error_ran = []


def remember_failed_start(ctx):
    failed_ctxs.append(ctx)


class FirstError:
    def on_error(self, ctx):
        if not elapsed_when_first_error_ran:
            elapsed_when_first_error_ran.append([c.elapsed_ms is not None for c in failed_ctxs])


r, en, ml = batch_router(hooks=[FirstError()], on_predict_start=remember_failed_start)
check_raises("router_batch/a failed group propagates", RuntimeError,
             lambda: r.predict_batch([req("boom"), req("b"), req("c")]))
check("router_batch/elapsed_ms is set for a failed group before any on_error runs",
      elapsed_when_first_error_ran, [[True, True, True]])

r, en, ml = batch_router(on_predict_end=lambda c: setattr(c, "results", [None]) if c.states == ["x"] else None)
try:
    got = r.predict_batch([req("x"), req("y")])
    got = (got[0], got[1]["answers"]["seen"])
except Exception as e:  # noqa: BLE001
    got = repr(e)
check("router_batch/a None result an end hook leaves is returned, as predict returns it", got, (None, "y"))


class AliasPin:
    """An on_route hook pinning a request with an alias, as a plain dict."""

    def on_route(self, ctx):
        if ctx.states == ["alias"]:
            ctx.decision = {**ctx.decision, "model": "ml"}


alias_models = []
r, en, ml = batch_router(hooks=[AliasPin()], on_predict_start=lambda c: alias_models.append(c.model))
r.predict_batch([req("alias"), req("full", "multilingual")])
check("router_batch/an aliased pin shares its checkpoint's forward pass", [c[0] for c in ml.calls],
      [["alias", "full"]])
check("router_batch/an aliased pin reports the resolved checkpoint", alias_models,
      ["multilingual", "multilingual"])

r, en, ml = batch_router(on_predict_start=fail_on_b, hooks_raise=False)
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    out = r.predict_batch([req("a"), req("b")])
check("router_batch/hooks_raise=False keeps the batch going", [o["answers"]["seen"] for o in out], ["a", "b"])
check_true("router_batch/hooks_raise=False warns", any("start hook failed" in str(w.message) for w in caught))


# --------------------------------------------------------------- hooks_concurrent storage
r = Router(default="english")
check("router/hooks_concurrent default True", r.hooks_concurrent, True)
check_true("router/hooks_concurrent default has no lock", r._hooks_lock is None)
r = Router(hooks_concurrent=False)
check("router/hooks_concurrent=False stored", r.hooks_concurrent, False)
check_true("router/hooks_concurrent=False installs a lock", r._hooks_lock is not None)


# --------------------------------------------------------------- concurrency
contexts = []


def slow_start(ctx):
    time.sleep(0.01)
    # Keep the context itself, not id(ctx): once a call returns its context can be freed and
    # a later call's context can reuse the address, so ids alone undercount on a busy machine.
    contexts.append(ctx)


f = make_fake()
threads = [threading.Thread(target=lambda: f.predict_batch(["s0"], QUESTIONS,
                                                           on_predict_start=slow_start))
           for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()
check("concurrency/one independent context per call", len({id(c) for c in contexts}), 5)


class ConcHook:
    def __init__(self):
        self.active = 0
        self.max_active = 0
        self._lock = threading.Lock()

    def on_predict_start(self, ctx):
        with self._lock:
            self.active += 1
            self.max_active = max(self.max_active, self.active)
        time.sleep(0.02)
        with self._lock:
            self.active -= 1


conc = ConcHook()
f = make_fake()
f.hooks = [conc]
f._hooks_lock = threading.RLock()  # what hooks_concurrent=False installs
threads = [threading.Thread(target=lambda: f.predict_batch(["s0"], QUESTIONS)) for _ in range(5)]
for t in threads:
    t.start()
for t in threads:
    t.join()
check("concurrency/hooks_concurrent=False serialises", conc.max_active, 1)


# --------------------------------------------------------------- ONNXAgent parity
from laya.onnx_agent import ONNXAgent  # noqa: E402

o = ONNXAgent.__new__(ONNXAgent)
o.model_id = "convaiinnovations/laya-onnx"


def _fake_onnx_batch(states, questions, **kwargs):
    # `system_one` runs through `predict_batch` -> `_infer_batch`, as `Agent.system_one` does,
    # so the batch seam is what a hook test stubs.
    return [{"model": "onnx", "answers": {},
             "usage": {"input_tokens": 0, "output_tokens": 0}} for _ in states]


o._infer_batch = _fake_onnx_batch
onnx_seen = []
onnx_models = []
onnx_out = o.system_one("s", QUESTIONS,
                        on_predict_start=lambda c: onnx_seen.append("start"),
                        on_predict_end=lambda c: (onnx_seen.append("end"), onnx_models.append(c.model)))
check("onnx/hooks fire", onnx_seen, ["start", "end"])
check("onnx/returns the inference result", onnx_out["model"], "onnx")
check("onnx/context model is the agent model_id", onnx_models, ["convaiinnovations/laya-onnx"])

o = ONNXAgent.__new__(ONNXAgent)


def _never(*args, **kwargs):
    raise AssertionError("inference should have been skipped")


o._infer_batch = _never
check("onnx/skip short-circuits",
      o.system_one("s", QUESTIONS, on_predict_start=lambda c: c.skip([{"model": "cached"}])),
      {"model": "cached"})


# --------------------------------------------------------------- BaseHook
from laya import BaseHook  # noqa: E402


class OnlyEnd(BaseHook):
    def __init__(self, log, tag):
        self.log = log
        self.tag = tag

    def on_predict_end(self, ctx):
        self.log.append(self.tag)


log = []
f = make_fake()
f.add_hook(OnlyEnd(log, "end"))
f.predict_batch(["s0"], QUESTIONS)
check("BaseHook/overridden event fires", log, ["end"])

f = make_fake()
f.add_hook(BaseHook())  # every method is a no-op
f.predict_batch(["s0"], QUESTIONS)
check("BaseHook/no-op instance is harmless", f._forward_calls, [2])


# --------------------------------------------------------------- process-wide defaults
from laya import hooks as _hooks  # noqa: E402

log = []
_hooks.set_default_hooks(on_predict_end=lambda ctx: log.append("default"))
try:
    f = make_fake()
    f.add_hook(Tag(log, "installed"))
    f.predict_batch(["s0"], QUESTIONS, on_predict_end=lambda ctx: log.append("percall"))
    check("defaults/run before installed and per-call", log, ["default", "installed", "percall"])
finally:
    _hooks.clear_default_hooks()
check("defaults/clear empties the registry", _hooks.default_hooks(), [])

log = []
_hooks.add_default_hook(Tag(log, "a"))
_hooks.add_default_hook(Tag(log, "b"))
try:
    f = make_fake()
    f.predict_batch(["s0"], QUESTIONS)
    check("defaults/add in order", log, ["a", "b"])
finally:
    _hooks.clear_default_hooks()

# A default hook has to reach the Router as well as the Agent: `set_default_hooks` documents
# "every Agent, Router and ONNXAgent in the process", and `predict_batch` promises each request
# its own PredictContext. It read `list(self.hooks)` at its dispatch site instead of composing
# with the registry, so a process-wide hook saw the Agent-level events and none of the
# Router-level ones -- invisible unless the hook records which level it ran at, which is why
# the checks above never caught it.
events = []


class LevelTag:
    def __init__(self, tag):
        self.tag = tag

    def on_predict_start(self, ctx):
        events.append((self.tag, "start", "router" if getattr(ctx, "router", None) is not None
                                         else "agent"))

    def on_predict_end(self, ctx):
        events.append((self.tag, "end", "router" if getattr(ctx, "router", None) is not None
                                       else "agent"))


_hooks.set_default_hooks([LevelTag("default")])
try:
    r, en, ml = batch_router()
    events.clear()
    r.predict_batch([req("a"), req("b")])
    # `BatchFake` replaces the agent wholesale, so the only events that can come from this
    # Router are its own. That is exactly what the defect removed.
    check("defaults/reach the Router on predict_batch",
          events, [("default", "start", "router"), ("default", "start", "router"),
                   ("default", "end", "router"), ("default", "end", "router")])

    # `predict` was already correct; assert the two entry points agree, which is the property
    # that was actually violated.
    events.clear()
    r.predict("a", QUESTIONS, model="english")
    via_predict = list(events)
    events.clear()
    r.predict_batch([req("a")])
    check("defaults/predict and predict_batch give the same event shape",
          events, via_predict)

    # An instance hook is composed the same way and must not be affected either way.
    events.clear()
    r2, _, _ = batch_router(hooks=[LevelTag("instance")])
    r2.predict_batch([req("a")])
    check("defaults/instance hooks still fire once alongside defaults",
          [e for e in events if e[0] == "instance"],
          [("instance", "start", "router"), ("instance", "end", "router")])
finally:
    _hooks.clear_default_hooks()


class LifeDefaults(BaseHook):
    def __init__(self):
        self.events = []

    def on_load(self, ctx):
        self.events.append(("load", ctx.model))

    def on_evict(self, ctx):
        self.events.append(("evict", ctx.model))


ld = LifeDefaults()
_hooks.set_default_hooks(hooks=[ld])
try:
    _agent_mod.Agent = BuiltAgent
    r = Router(max_loaded=1)
    r.load("english")
    r.load("multilingual")  # evicts english
finally:
    _agent_mod.Agent = real_agent
    _hooks.clear_default_hooks()
check("defaults/cover router lifecycle", ld.events,
      [("load", "english"), ("evict", "english"), ("load", "multilingual")])

events = []
_hooks.set_default_hooks([LevelTag("default")])
r = Router(default="english")
r.attach("english", make_fake())
r.predict("a", QUESTIONS, model="english")
r.predict_batch([req("b")])
_hooks.clear_default_hooks()
check("defaults/fire once per request", events, [("default", "start", "router"), ("default", "end", "router")] * 2)


# --------------------------------------------------------------- async hooks
import asyncio  # noqa: E402

from laya import AsyncHook  # noqa: E402
from laya.hooks import run_coroutine_sync  # noqa: E402

calls = []


class AsyncAudit:
    async def on_predict_end(self, ctx):
        await asyncio.sleep(0)
        calls.append("wrapped")


f = make_fake()
f.add_hook(AsyncHook(AsyncAudit()))
f.predict_batch(["s0"], QUESTIONS)
check("async/wrapped hook awaited", calls, ["wrapped"])

calls.clear()


async def async_end(ctx):
    await asyncio.sleep(0)
    calls.append("plain")


f = make_fake()
f.predict_batch(["s0"], QUESTIONS, on_predict_end=async_end)
check("async/plain callable awaited", calls, ["plain"])

calls.clear()


async def async_start(ctx):
    calls.append("loop")


f = make_fake()


async def _in_loop():
    f.predict_batch(["s0"], QUESTIONS, on_predict_start=async_start)


asyncio.run(_in_loop())
check("async/works inside a running loop", calls, ["loop"])


async def _seven():
    return 7


check("async/run_coroutine_sync returns", run_coroutine_sync(_seven()), 7)
check_raises("async/AsyncHook rejects a class", TypeError, lambda: AsyncHook(AsyncAudit))


# --------------------------------------------------------------- hook timeout
def slow_hook(ctx):
    time.sleep(0.3)


f = make_fake()
raised = None
try:
    f.predict_batch(["s0"], QUESTIONS, on_predict_start=slow_hook, hooks_timeout=0.05)
except TimeoutError as exc:
    raised = str(exc)
check_true("timeout/raises TimeoutError", isinstance(raised, str) and "exceeded" in raised)

f = make_fake()
with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    res = f.predict_batch(["s0"], QUESTIONS, on_predict_start=slow_hook,
                          hooks_timeout=0.05, hooks_raise=False)
check("timeout/hooks_raise=False continues", len(res), 1)
check_true("timeout/hooks_raise=False warns",
           any(issubclass(w.category, RuntimeWarning) for w in caught))

f = make_fake()
f.hooks_timeout = 0.05
raised = None
try:
    f.predict_batch(["s0"], QUESTIONS, on_predict_start=slow_hook)
except TimeoutError:
    raised = True
check("timeout/instance-level applies", raised, True)

f = make_fake()
f.hooks_timeout = 0.05
res = f.predict_batch(["s0"], QUESTIONS, on_predict_start=slow_hook, hooks_timeout=5.0)
check("timeout/per-call override wins", len(res), 1)

f = make_fake()
res = f.predict_batch(["s0"], QUESTIONS, on_predict_end=lambda ctx: None, hooks_timeout=1.0)
check("timeout/fast hook unaffected", len(res), 1)


# --------------------------------------------------------------- input validation and context
import contextvars  # noqa: E402

from laya.hooks import validate_timeout  # noqa: E402

check_raises("timeout/zero is rejected", ValueError, lambda: validate_timeout(0))
check_raises("timeout/negative is rejected", ValueError, lambda: validate_timeout(-0.5))
check_raises("timeout/NaN is rejected", ValueError, lambda: validate_timeout(float("nan")))
check_raises("timeout/infinity is rejected", ValueError, lambda: validate_timeout(float("inf")))
check_raises("timeout/-infinity is rejected", ValueError, lambda: validate_timeout(float("-inf")))
check_raises("timeout/True is rejected", ValueError, lambda: validate_timeout(True))
check_raises("timeout/False is rejected", ValueError, lambda: validate_timeout(False))
# A shape `float()` cannot read is still a bad timeout: a list/object used to leak TypeError and a
# JSON integer too large for a float leaked OverflowError. Both must raise the same ValueError, and
# the OverflowError case is what let a giant JSON number reach `laya/mcp/tools.py` (which catches
# only TypeError/ValueError) and surface as `internal_error`.
check_raises("timeout/list is rejected", ValueError, lambda: validate_timeout([10]))
check_raises("timeout/dict is rejected", ValueError, lambda: validate_timeout({"a": 1}))
check_raises("timeout/oversized int is rejected", ValueError, lambda: validate_timeout(10 ** 1000))


# The refusal has to say *why*. `False` raises either way -- as a wrong type here, as a non-positive
# number in the branch below -- so an arm that only checks the exception type cannot tell the two
# apart, and a guard that simply fell through would pass it. `0` keeps the original wording.
def _timeout_message(value):
    try:
        validate_timeout(value)
    except ValueError as exc:
        return str(exc)
    return "<accepted>"


check_true("timeout/a bool is refused as a bool", "not a bool" in _timeout_message(True),
           _timeout_message(True))
check_true("timeout/False is refused as a bool too", "not a bool" in _timeout_message(False),
           _timeout_message(False))
check_true("timeout/zero keeps the non-positive wording",
           "not a bool" not in _timeout_message(0) and "positive finite" in _timeout_message(0),
           _timeout_message(0))
check("timeout/positive passes through", validate_timeout(1.5), 1.5)
check("timeout/None means no limit", validate_timeout(None), None)

f = make_fake()
check_raises("timeout/zero per call is rejected", ValueError,
             lambda: f.predict_batch(["s0"], QUESTIONS, hooks_timeout=0))
check_raises("timeout/NaN per call is rejected", ValueError,
             lambda: f.predict_batch(["s0"], QUESTIONS, hooks_timeout=float("nan")))
check_raises("timeout/infinity per call is rejected", ValueError,
             lambda: f.predict_batch(["s0"], QUESTIONS, hooks_timeout=float("inf")))

# `float(True) == 1.0`, so `hooks_timeout=True` -- which reads like "yes, time the hooks" -- used to
# install a one-second deadline on every hook call, and `False` was refused as a non-positive number,
# the wrong reason for a wrong type. Both spellings now raise where they are set, per call and at
# construction alike; an int and a numeric string are not bools and still bound the wait.
check_raises("timeout/True per call is rejected", ValueError,
             lambda: f.predict_batch(["s0"], QUESTIONS, hooks_timeout=True))
check_raises("timeout/True at construction is rejected", ValueError,
             lambda: Router(hooks_timeout=True))
check("timeout/int still bounds", Router(hooks_timeout=1).hooks_timeout, 1.0)
check("timeout/numeric string still bounds", Router(hooks_timeout="0.5").hooks_timeout, 0.5)

not_running = asyncio.new_event_loop()
try:
    c = _seven()
    check_raises("async/a non-running loop is rejected", ValueError,
                 lambda: run_coroutine_sync(c, loop=not_running))
    check_true("async/a non-running loop closes the coroutine",
               inspect.getcoroutinestate(c) == "CORO_CLOSED")
finally:
    not_running.close()


async def _own_loop():
    own = asyncio.get_running_loop()
    c = _seven()
    try:
        run_coroutine_sync(c, loop=own)
    except ValueError:
        return "closed" if inspect.getcoroutinestate(c) == "CORO_CLOSED" else "raised"
    return "no"


check("async/the calling thread's own loop is rejected", asyncio.run(_own_loop()), "closed")
check_raises("async/AsyncHook rejects an object with no events", TypeError,
             lambda: AsyncHook(object()))

_cv_seen = contextvars.ContextVar("cv_seen", default=None)
_cv_calls = []


class CvHook:
    def on_predict_start(self, ctx):
        _cv_calls.append(_cv_seen.get())


f = make_fake()
_token = _cv_seen.set("request-1")
try:
    f.predict_batch(["s0"], QUESTIONS, hooks=[CvHook()], hooks_timeout=1.0)
finally:
    _cv_seen.reset(_token)
check("timeout/a timed hook sees the caller's contextvars", _cv_calls, ["request-1"])


# ------------------------------------------- per-call timeout reaches on_route through the batches
# #277 threaded the per-call timeout through predict_batch's own dispatches, but route_batch had no
# hooks_timeout argument and predict_batch did not forward its override into it, so an on_route hook
# reached through either batch entry point saw the instance timeout instead of the caller's.
class SlowRoute:
    def on_route(self, ctx):
        time.sleep(0.3)


def slow_route_router(**kwargs):
    return batch_router(hooks=[SlowRoute()], **kwargs)[0]


# route_batch takes the per-call timeout and applies it to on_route.
raised = None
try:
    slow_route_router().route_batch([req("a")], hooks_timeout=0.05)
except TimeoutError as exc:
    raised = str(exc)
check_true("timeout/route_batch per-call reaches on_route",
           isinstance(raised, str) and "exceeded" in raised)

# predict_batch forwards the same override into route_batch, so on_route times out there too.
raised = None
try:
    slow_route_router().predict_batch([req("a")], hooks_timeout=0.05)
except TimeoutError as exc:
    raised = str(exc)
check_true("timeout/predict_batch per-call reaches on_route",
           isinstance(raised, str) and "exceeded" in raised)

# No per-call override: the instance timeout is still the fallback for the batched route path.
raised = None
try:
    slow_route_router(hooks_timeout=0.05).route_batch([req("a")])
except TimeoutError:
    raised = True
check("timeout/route_batch instance-level applies", raised, True)

# A longer per-call value overrides a shorter instance timeout, as on the other entry points.
decisions = slow_route_router(hooks_timeout=0.05).route_batch([req("a")], hooks_timeout=5.0)
check("timeout/route_batch per-call override wins", [d["model"] for d in decisions], ["english"])

# With no hooks at all both batched paths are unchanged.
plain_r, plain_en, _ = batch_router()
check("timeout/route_batch without hooks is unchanged",
      [d["model"] for d in plain_r.route_batch([req("a")])], ["english"])
plain_out = plain_r.predict_batch([req("a")])
check("timeout/predict_batch without hooks is unchanged", len(plain_out), 1)
check("timeout/predict_batch without hooks keeps routing", plain_out[0]["routing"]["model"], "english")
check("timeout/predict_batch without hooks still batches", [c[0] for c in plain_en.calls], [["a"]])

# The forwarded value is still validated by route(), exactly like a direct route() call.
check_raises("timeout/route_batch rejects a zero per-call timeout", ValueError,
             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 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", TypeError,
             lambda: r_pos.predict_batch([req("pos2")], 8, 1.0, None, False, [PerCallTrace()]))

# --------------------------------------------------------------- OptionStabilityHook (issue #635)
check_raises("stability/missing accept and escalate", TypeError, lambda: OptionStabilityHook())
check_raises("stability/negative n_shuffles", ValueError, lambda: OptionStabilityHook(accept=0.8, escalate=0.6, n_shuffles=-1))
check_raises("stability/bool n_shuffles", ValueError, lambda: OptionStabilityHook(accept=0.8, escalate=0.6, n_shuffles=True))
check_raises("stability/unknown variants", ValueError, lambda: OptionStabilityHook(accept=0.8, escalate=0.6, variants="invalid"))
check_raises("stability/empty variants", ValueError, lambda: OptionStabilityHook(accept=0.8, escalate=0.6, variants=[]))
check_raises("stability/escalate > accept", ValueError, lambda: OptionStabilityHook(accept=0.5, escalate=0.8))

stab_hook = OptionStabilityHook(accept=0.77, escalate=0.61, seed="test-seed")
stab_q = {"choice_q": {"type": "choice", "instructions": "Pick?", "criteria": {"a": "opt 1", "b": "opt 2"}}}
stab_ctx = PredictContext(states=["state 1"], questions=dict(stab_q))
stab_hook.on_predict_start(stab_ctx)
check_true("stability/injects variant questions", any(k.startswith("choice_q::rel") for k in stab_ctx.questions))

sim_answers = {}
for k, q_def in stab_ctx.questions.items():
    crit = q_def["criteria"]
    target = [name for name, desc in crit.items() if desc == "opt 1"][0]
    sim_answers[k] = {
        "type": "choice",
        "choice": target,
        "probabilities": {name: (0.9 if name == target else 0.1) for name in crit},
        "answer_confidence": 0.9,
    }

stab_ctx.results = [{
    "model": "fake",
    "answers": sim_answers,
    "usage": {"truncated_questions": ["choice_q::rel1"]},
}]
stab_hook.on_predict_end(stab_ctx)
stab_ans = stab_ctx.results[0]["answers"]
check_true("stability/cleans variant keys", not any("::rel" in k for k in stab_ans))
check("stability/keeps choice", stab_ans["choice_q"]["choice"], "a")
check_true("stability/adds reliability", "reliability" in stab_ans["choice_q"])
check("stability/accept decision", stab_ans["choice_q"]["reliability"]["decision"], "ACCEPT")
check("stability/stability 1.0", stab_ans["choice_q"]["reliability"]["stability"], 1.0)
check("stability/probes list", stab_ans["choice_q"]["reliability"]["probes"], ["reorder", "rename"])
check("stability/cleans usage", stab_ctx.results[0]["usage"]["truncated_questions"], [])


# --------------------------------------------------------------- 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:
    print("  FAIL " + f_)
if not FAIL:
    print("all hook tests passed")
sys.exit(1 if FAIL else 0)