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.

feat(ts): port BaseHook and process-wide default hooks (follow-up to #276) (#321)

Aashish Mahato6e67c4defa4e
diff --git a/laya-ts/README.md b/laya-ts/README.md
index e41042f8..4b124855 100644
--- a/laya-ts/README.md
+++ b/laya-ts/README.md
@@ -56,6 +56,15 @@ await router.withHooks([auditHook], () => router.predict(state, questions)); //
// a start hook may rewrite ctx.states / ctx.questions, or serve a cached result:
const cache = { onPredictStart(ctx) { const hit = lookup(ctx.states[0]); if (hit) ctx.skip([hit]); } };
// an onRoute hook may replace ctx.decision (e.g. pin a checkpoint)
+
+// subclass BaseHook to override only the events you need:
+class MetricsHook extends BaseHook {
+ onPredictEnd(ctx) { record(ctx.usage); }
+}
+
+// process-wide defaults run before installed and per-call hooks for every Agent/Router,
+// so a tracer or metrics hook does not have to be threaded through every construction:
+setDefaultHooks([new MetricsHook()]); // addDefaultHook(...) appends; clearDefaultHooks() resets
```
## Shortlist (many labels)
diff --git a/laya-ts/src/agent.ts b/laya-ts/src/agent.ts
index 11a33db7..294b7ad7 100644
--- a/laya-ts/src/agent.ts
+++ b/laya-ts/src/agent.ts
@@ -17,6 +17,7 @@ import {
HookRegistry,
PredictContext,
aggregateUsage,
+ composeHooks,
dispatch,
normaliseHooks,
type HookArg,
@@ -304,10 +305,7 @@ export class Agent extends HookRegistry {
questions: Record<string, QuestionDef>,
opts: PredictOptions,
): Promise<SystemOneResult[]> {
- const active = [
- ...this.hooks,
- ...normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd),
- ];
+ const active = composeHooks(this.hooks, opts.hooks, opts.onPredictStart, opts.onPredictEnd);
const raiseErrors = opts.hooksRaise ?? this.hooksRaise;
const ctx = new PredictContext({
states,
diff --git a/laya-ts/src/hooks.ts b/laya-ts/src/hooks.ts
index 59bbffdf..8d5428ac 100644
--- a/laya-ts/src/hooks.ts
+++ b/laya-ts/src/hooks.ts
@@ -90,6 +90,21 @@ export const HOOK_EVENTS = [
] as const;
export type HookEvent = (typeof HOOK_EVENTS)[number];
+/**
+ * No-op base class: subclass it and override only the events you need.
+ *
+ * `Hook` is the structural interface; `BaseHook` is the concrete convenience when you would
+ * rather subclass than implement methods by shape. Every method does nothing by default.
+ */
+export class BaseHook implements Hook {
+ onPredictStart(_ctx: PredictContext): void {}
+ onPredictEnd(_ctx: PredictContext): void {}
+ onRoute(_ctx: PredictContext): void {}
+ onLoad(_ctx: PredictContext): void {}
+ onEvict(_ctx: PredictContext): void {}
+ onError(_ctx: PredictContext): void {}
+}
+
function isHookLike(item: unknown): item is Hook {
return (
typeof item === "object" &&
@@ -171,6 +186,54 @@ export function normaliseHooks(
return out;
}
+const defaultHooksList: Hook[] = [];
+
+/** The process-wide hooks, a copy, in order. Empty unless set via `setDefaultHooks`. */
+export function defaultHooks(): Hook[] {
+ return [...defaultHooksList];
+}
+
+/**
+ * Replace the process-wide default hooks.
+ *
+ * Defaults run before installed and per-call hooks for every `Agent` and `Router` in the
+ * process, so a tracer or metrics hook does not have to be threaded through every
+ * construction. Accepts the same arguments as the `hooks` option.
+ */
+export function setDefaultHooks(
+ hooks?: HookArg,
+ onPredictStart?: PredictHookArg,
+ onPredictEnd?: PredictHookArg,
+): void {
+ const normalised = normaliseHooks(hooks, onPredictStart, onPredictEnd);
+ defaultHooksList.length = 0;
+ defaultHooksList.push(...normalised);
+}
+
+/** Append one hook or a list of hooks to the process-wide defaults. */
+export function addDefaultHook(hook: HookArg): void {
+ defaultHooksList.push(...normaliseHooks(hook));
+}
+
+/** Remove every process-wide default hook. */
+export function clearDefaultHooks(): void {
+ defaultHooksList.length = 0;
+}
+
+/**
+ * Effective hook list for one call: defaults, then installed, then per-call hooks.
+ *
+ * Reads the process-wide defaults at call time, so hooks set after construction still apply.
+ */
+export function composeHooks(
+ installed: readonly Hook[],
+ hooks?: HookArg,
+ onPredictStart?: PredictHookArg,
+ onPredictEnd?: PredictHookArg,
+): Hook[] {
+ return [...defaultHooksList, ...installed, ...normaliseHooks(hooks, onPredictStart, onPredictEnd)];
+}
+
/**
* Base class giving a runtime-mutable hook list.
*
diff --git a/laya-ts/src/index.ts b/laya-ts/src/index.ts
index 33f16abc..6f81120b 100644
--- a/laya-ts/src/index.ts
+++ b/laya-ts/src/index.ts
@@ -22,7 +22,20 @@ export type { EmbedFn, ShortlistMeta } from "./shortlist.js";
export { analyse, isEnglish, guessLatinLanguage, detectScript } from "./lang.js";
export type { AnalyseResult, LatinProfile } from "./lang.js";
export { cleanEmailBody, emailState } from "./email.js";
-export { PredictContext, HookRegistry, normaliseHooks, dispatch, aggregateUsage, HOOK_EVENTS } from "./hooks.js";
+export {
+ PredictContext,
+ HookRegistry,
+ BaseHook,
+ normaliseHooks,
+ dispatch,
+ aggregateUsage,
+ composeHooks,
+ defaultHooks,
+ setDefaultHooks,
+ addDefaultHook,
+ clearDefaultHooks,
+ HOOK_EVENTS,
+} from "./hooks.js";
export type { Hook, HookEvent, HookArg, PredictHook, PredictHookArg } from "./hooks.js";
export { triageQuestions, emailQuestions, guardQuestions, moderationQuestions, routerQuestions } from "./presets.js";
export {
diff --git a/laya-ts/src/router.ts b/laya-ts/src/router.ts
index 8e21c218..b98941ba 100644
--- a/laya-ts/src/router.ts
+++ b/laya-ts/src/router.ts
@@ -4,6 +4,7 @@ import {
HookRegistry,
PredictContext,
aggregateUsage,
+ composeHooks,
dispatch,
normaliseHooks,
type HookArg,
@@ -215,14 +216,14 @@ export class Router extends HookRegistry {
// Lifecycle hooks fire after the maps settle, so a hook can safely call the Router.
for (const victim of evicted) {
dispatch(
- this.hooks,
+ composeHooks(this.hooks),
"onEvict",
new PredictContext({ states: [], questions: {}, model: victim, router: this }),
{ raiseErrors: this.hooksRaise },
);
}
dispatch(
- this.hooks,
+ composeHooks(this.hooks),
"onLoad",
new PredictContext({ states: [], questions: {}, model: key, agent, router: this }),
{ raiseErrors: this.hooksRaise },
@@ -308,7 +309,7 @@ export class Router extends HookRegistry {
): RouteDecision {
const decision = this._route(state, questions, opts);
const raiseErrors = opts.hooksRaise ?? this.hooksRaise;
- const active = [...this.hooks, ...normaliseHooks(opts.hooks)];
+ const active = composeHooks(this.hooks, opts.hooks);
const ctx = new PredictContext({
states: [state],
questions: (questions ?? {}) as Record<string, unknown>,
@@ -432,10 +433,7 @@ export class Router extends HookRegistry {
questions: Record<string, QuestionDef>,
opts: RouteOptions & PredictOptions = {},
): Promise<RoutedResult> {
- const active = [
- ...this.hooks,
- ...normaliseHooks(opts.hooks, opts.onPredictStart, opts.onPredictEnd),
- ];
+ const active = composeHooks(this.hooks, opts.hooks, opts.onPredictStart, opts.onPredictEnd);
const raiseErrors = opts.hooksRaise ?? this.hooksRaise;
// Per-call hooks apply to the whole call, including onRoute inside route().
diff --git a/laya-ts/tests/hooks.test.ts b/laya-ts/tests/hooks.test.ts
index 10d39690..6021a58c 100644
--- a/laya-ts/tests/hooks.test.ts
+++ b/laya-ts/tests/hooks.test.ts
@@ -1,7 +1,17 @@
import { describe, expect, it, vi } from "vitest";
import { Agent, defaultTokenizer } from "../src/agent.js";
import { Router } from "../src/router.js";
-import { HookRegistry, normaliseHooks, type Hook, type PredictContext } from "../src/hooks.js";
+import {
+ BaseHook,
+ HookRegistry,
+ addDefaultHook,
+ clearDefaultHooks,
+ defaultHooks,
+ normaliseHooks,
+ setDefaultHooks,
+ type Hook,
+ type PredictContext,
+} from "../src/hooks.js";
const QUESTIONS = { q: { type: "noul", instructions: "?" } } as never;
@@ -298,3 +308,97 @@ describe("hook registry and normalisation", () => {
expect(router.hooks).toHaveLength(0); // removed after the callback settles
});
});
+
+describe("BaseHook and process-wide default hooks (py #276 parity)", () => {
+ it("BaseHook/overridden event fires; a no-op instance is harmless", async () => {
+ const log: string[] = [];
+ class OnlyEnd extends BaseHook {
+ override onPredictEnd(): void {
+ log.push("end");
+ }
+ }
+ const agent = makeAgent();
+ agent.addHook(new OnlyEnd());
+ await agent.predict("s0", QUESTIONS);
+ expect(log).toEqual(["end"]);
+
+ const agent2 = makeAgent();
+ agent2.addHook(new BaseHook()); // every method is a no-op
+ await expect(agent2.predict("s0", QUESTIONS)).resolves.toBeTruthy();
+ });
+
+ it("defaults/run before installed and per-call hooks", async () => {
+ const log: string[] = [];
+ setDefaultHooks(undefined, undefined, () => void log.push("default"));
+ try {
+ const agent = makeAgent();
+ agent.addHook({ onPredictEnd: () => void log.push("installed") });
+ await agent.predict("s0", QUESTIONS, { onPredictEnd: () => void log.push("percall") });
+ expect(log).toEqual(["default", "installed", "percall"]);
+ } finally {
+ clearDefaultHooks();
+ }
+ expect(defaultHooks()).toEqual([]);
+ });
+
+ it("defaults/addDefaultHook appends in order; setDefaultHooks replaces", async () => {
+ const log: string[] = [];
+ addDefaultHook({ onPredictEnd: () => void log.push("a") });
+ addDefaultHook({ onPredictEnd: () => void log.push("b") });
+ try {
+ expect(defaultHooks()).toHaveLength(2);
+ await makeAgent().predict("s0", QUESTIONS);
+ expect(log).toEqual(["a", "b"]);
+ } finally {
+ clearDefaultHooks();
+ }
+ expect(defaultHooks()).toEqual([]);
+
+ // setDefaultHooks replaces rather than appends
+ setDefaultHooks({ onPredictEnd: () => void log.push("c") });
+ setDefaultHooks({ onPredictEnd: () => void log.push("d") });
+ try {
+ await makeAgent().predict("s0", QUESTIONS);
+ expect(log).toEqual(["a", "b", "d"]);
+ } finally {
+ clearDefaultHooks();
+ }
+ });
+
+ it("defaults/read at call time, so hooks set after construction still apply", async () => {
+ const log: string[] = [];
+ const agent = makeAgent(); // constructed before the default is set
+ setDefaultHooks({ onPredictStart: () => void log.push("late") });
+ try {
+ await agent.predict("s0", QUESTIONS);
+ expect(log).toEqual(["late"]);
+ } finally {
+ clearDefaultHooks();
+ }
+ });
+
+ it("defaults/cover the router lifecycle (onLoad/onEvict)", async () => {
+ const events: [string, string | undefined][] = [];
+ class LifeDefaults extends BaseHook {
+ override onLoad(ctx: PredictContext): void {
+ events.push(["load", ctx.model]);
+ }
+ override onEvict(ctx: PredictContext): void {
+ events.push(["evict", ctx.model]);
+ }
+ }
+ setDefaultHooks([new LifeDefaults()]);
+ try {
+ const { router } = makeRouter({ maxLoaded: 1 });
+ await router.load("english");
+ await router.load("multilingual"); // evicts english
+ expect(events).toEqual([
+ ["load", "english"],
+ ["evict", "english"],
+ ["load", "multilingual"],
+ ]);
+ } finally {
+ clearDefaultHooks();
+ }
+ });
+});