Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

docs(hooks): a predict's run_id count is the Router's cache state, not a fixed three

Aashish080b13e4c634
diff --git a/docs/hooks/tracing.md b/docs/hooks/tracing.md
index 53cd0f6d..f7ae5065 100644
--- a/docs/hooks/tracing.md
+++ b/docs/hooks/tracing.md
@@ -20,9 +20,12 @@ bookkeeping.
- Shared by every predict-event hook of that call: `on_predict_start`, `on_predict_end` and
`on_error` see one `PredictContext`, so one `run_id`.
- **Not** shared with `on_route`, `on_load` or `on_evict`. Each is dispatched with a context of
- its own, so a single `Router.predict` hands out three different `run_id`s. Correlate a routing
- decision with its prediction through `ctx.decision`, which `on_predict_start` also carries, not
- through `run_id`.
+ its own, so the count one `Router.predict` hands out is the number of contexts that call makes:
+ two when the checkpoint is already resident (`on_route` plus the prediction), three when it has
+ to load one (the load adds `on_load`), and four when that load also evicts an LRU checkpoint
+ (`on_evict` adds another). Three is the cold path; a warm Router gives two per call. Correlate a
+ routing decision with its prediction through `ctx.decision`, which `on_predict_start` also
+ carries, not through `run_id`.
- Not global and not persisted: it identifies a call within the process. Put it in your logs and
outbound payloads to correlate across systems.
- Distinct per call, so two calls never collide.
diff --git a/tests/test_router.py b/tests/test_router.py
index 63c4daa3..44d24009 100644
--- a/tests/test_router.py
+++ b/tests/test_router.py
@@ -1042,6 +1042,114 @@ check("attach/still the same object", ra._agents["english"] is sentinel, True)
check("attach/accepts aliases", stubbed_router(1).attach("en", _Stub("x")) is not None, True)
+# --------------------------------------------------------------------- run_ids per predict
+# docs/hooks/tracing.md tells a tracer to correlate a call's events by `run_id`, and claimed one
+# `Router.predict` "hands out three different `run_id`s". Three is the cold path only: `on_load` is
+# dispatched on a `PredictContext` of its own, so a call that finds its checkpoint resident -- every
+# call after the first, and `attach` fires no `on_load` -- hands out two, and a load that also evicts
+# an LRU checkpoint hands out four. The count is a property of the Router's cache rather than of
+# `predict`, so the gate runs the three cache states and then requires the page to state each
+# measured number beside the clause that earns it. Only `laya.agent.Agent` is stubbed, as above.
+import re as _re # noqa: E402
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+_WORDS = {"one": 1, "two": 2, "three": 3, "four": 4, "five": 5}
+
+
+class _RunIds:
+ """Records `(event, ctx.run_id)` for every Router event one call dispatches."""
+
+ def __init__(self):
+ self.seen = []
+
+ def _see(self, event, ctx):
+ self.seen.append((event, ctx.run_id))
+
+ def on_route(self, ctx):
+ self._see("on_route", ctx)
+
+ def on_load(self, ctx):
+ self._see("on_load", ctx)
+
+ def on_evict(self, ctx):
+ self._see("on_evict", ctx)
+
+ def on_predict_start(self, ctx):
+ self._see("on_predict_start", ctx)
+
+ def on_predict_end(self, ctx):
+ self._see("on_predict_end", ctx)
+
+
+def _one_predict(attach_name=None, max_loaded=2):
+ rec = _RunIds()
+ rr = Router(max_loaded=max_loaded, hooks=[rec])
+ if attach_name is not None:
+ rr.attach(attach_name, _Stub(attach_name))
+ del rec.seen[:] # the record starts at the call, and attach adds nothing
+ with patch("laya.agent.Agent", side_effect=lambda repo, **kw: _Stub(repo)):
+ rr.predict("I was charged twice", Q_GENERIC, model="english")
+ return rec.seen
+
+
+def _events(seen):
+ return [event for event, _ in seen]
+
+
+def _distinct(seen):
+ return len({run_id for _, run_id in seen})
+
+
+_warm = _one_predict(attach_name="english")
+_cold = _one_predict()
+_evicting = _one_predict(attach_name="multilingual", max_loaded=1)
+
+check("run_ids/attach dispatches no lifecycle event", _events(_warm),
+ ["on_route", "on_predict_start", "on_predict_end"])
+check("run_ids/a warm predict hands out two run_ids", _distinct(_warm), 2)
+check("run_ids/a cold predict adds on_load", _events(_cold)[:3],
+ ["on_route", "on_load", "on_predict_start"])
+check("run_ids/a cold predict hands out three run_ids", _distinct(_cold), 3)
+check("run_ids/an evicting cold predict adds on_evict too", _events(_evicting)[:3],
+ ["on_route", "on_evict", "on_load"])
+check("run_ids/an evicting cold predict hands out four run_ids", _distinct(_evicting), 4)
+check("run_ids/start and end share the call's run_id",
+ len({rid for e, rid in _cold if e.startswith("on_predict")}), 1)
+check("run_ids/on_route is not the prediction's run_id",
+ {rid for e, rid in _cold if e == "on_route"} == {rid for e, rid in _cold
+ if e.startswith("on_predict")}, False)
+
+with open(os.path.join(_ROOT, "docs", "hooks", "tracing.md"), encoding="utf-8") as _trace_file:
+ _trace_page = _trace_file.read()
+check("run_ids/tracing.md keeps the run_id bullet the gate reads",
+ "**Not** shared with `on_route`" in _trace_page, True)
+_bullet = _re.sub(r"\s+", " ", _trace_page.split("**Not** shared with `on_route`", 1)[1]
+ .split("\n- ", 1)[0])
+check("run_ids/the page states no single count for one predict",
+ _re.search(r"hands out \w+ different", _bullet) is None, True)
+# Each "N when ..." clause is read up to the next one, so a needle has to sit in exactly one of
+# them -- which is what makes the pairing a transcription check rather than a word search.
+_clauses = {}
+for _part in _re.split(r"(?=\b(?:one|two|three|four|five)\b when\b)", _bullet, flags=_re.I):
+ _m = _re.match(r"\b(one|two|three|four|five)\b when\b(.*)", _part, _re.I)
+ if _m:
+ _clauses[_m.group(2)] = _WORDS[_m.group(1).lower()]
+
+
+def _stated(needle):
+ """The count the page pairs with the clause holding `needle`, or None unless exactly one does."""
+ hits = {n for cond, n in _clauses.items() if needle in cond}
+ return hits.pop() if len(hits) == 1 else None
+
+
+check("run_ids/the page's resident clause states the measured warm count",
+ _stated("resident"), _distinct(_warm))
+check("run_ids/the page's on_load clause states the measured cold count",
+ _stated("on_load"), _distinct(_cold))
+check("run_ids/the page's on_evict clause states the measured evicting count",
+ _stated("on_evict"), _distinct(_evicting))
+
+
# --------------------------------------------------------------------- thread safety (issue #95)
def _concurrent_load_dedup():