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(java): dispatch router lifecycle hooks, and add AsyncHook

Adeshina Lasisi8339733a3ee6
diff --git a/laya-java/README.md b/laya-java/README.md
index a72b3c4e..2f83f062 100644
--- a/laya-java/README.md
+++ b/laya-java/README.md
@@ -18,9 +18,10 @@ state builder (`LayaEmail`), the abstention gate (`ConfidenceGate`), scanning a
the context window (`predictLong`), schema-driven decisions (`Decisions.decide` / `decideBatch`),
and the prediction hooks (`hooks`).
-Not implemented yet: the `laya-java-client` HTTP module, Android. Hooks run on `predict` and
-`predictBatch`; `Router` and `predictLong` do not dispatch them, and there is no `AsyncHook` — see
-[Watching and shaping a call](#watching-and-shaping-a-call). **Not published to
+Not implemented yet: the `laya-java-client` HTTP module, Android. `predictLong` dispatches no hook:
+a scan is sized before a hook could rewrite what is asked, so it stays unhooked until the
+reference's start probe and budget check are ported — see
+[Watching and shaping a call](#watching-and-shaping-a-call) and [Router hooks](#router-hooks). **Not published to
Maven Central** — see [Installing](#installing).
## Where to go next
@@ -477,6 +478,39 @@ and a JVM method call is already synchronous: a hook that wants asynchronous wor
blocks on it — `ship(ctx.results()).toCompletableFuture().join()` — bounded however your runtime
wants, or by `timeout(Duration)`.
+## Router hooks
+
+`Router.hooks()` is its own registry, separate from any agent's. A router-level hook sees three
+events no agent can:
+
+| event | when |
+|---|---|
+| `onRoute` | after a checkpoint is chosen, from every branch of `route` |
+| `onLoad` | after a checkpoint is built — not on a cache hit |
+| `onEvict` | after one is dropped, by `maxLoaded`, `unload` or `unloadAll` |
+
+`Router.predict` also dispatches one `onPredictStart`/`onPredictEnd` pair for the whole
+route-and-answer call, with `onLoad` and `onEvict` landing inside it. The agent's own pair still
+fires for the forward pass, so a router-level hook and an agent-level hook see different spans.
+
+Hooks are dispatched outside the router's lock, so a hook may call back into the router —
+including `loaded()` or another `predict` — without deadlocking.
+
+`ctx.maxLen` / `ctx.headMaxLen` set by a router-level start hook are not honoured:
+`Agent.predict` takes no budget arguments. An agent-level hook can still set them.
+
+```java
+router.hooks().addHook(new Hook() {
+ @Override public void onRoute(PredictContext ctx) { log.info("routed to {}", ctx.model()); }
+ @Override public void onEvict(PredictContext ctx) { meter.increment("evictions"); }
+});
+```
+
+`AsyncHook.of(hook, executor)` runs a hook on a particular thread — a framework request scope, an
+actor, a UI loop. It waits for the callback, so an exception still reaches the hook policy and the
+mutable `PredictContext` is never read after the call has moved on. Pass a `Duration` to fail a
+callback that overruns.
+
## Option order
A choice's options are positional: option N renders Nth and logit N is read back as the Nth label.
diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java
index 69e807b6..8f333cef 100644
--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java
+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Router.java
@@ -1,5 +1,10 @@
package com.convaiinnovations.laya;
+import com.convaiinnovations.laya.hooks.Hook;
+import com.convaiinnovations.laya.hooks.HookCall;
+import com.convaiinnovations.laya.hooks.HookRegistry;
+import com.convaiinnovations.laya.hooks.Hooks;
+import com.convaiinnovations.laya.hooks.PredictContext;
import com.convaiinnovations.laya.json.PythonJson;
import com.convaiinnovations.laya.lang.LanguageDetection;
import com.convaiinnovations.laya.lang.UnicodeTables;
@@ -367,6 +372,12 @@ public final class Router implements AutoCloseable, Predictor {
private final LanguageHint langGuess;
private final AgentFactory agents;
+ /**
+ * This router's hooks, separate from any agent's: these see {@code on_route}, {@code on_load}
+ * and {@code on_evict}, and one predict pair for the whole route-and-answer call.
+ */
+ private final HookRegistry hooks = new HookRegistry();
+
private final ReentrantLock lock = new ReentrantLock();
/** Serialises builds, so two cold loads do not hold two checkpoints in flight at once. */
private final ReentrantLock buildLock = new ReentrantLock();
@@ -725,6 +736,16 @@ public final class Router implements AutoCloseable, Predictor {
*/
public RouteDecision route(Object state, Map<String, Question> questions,
RouteOptions options) {
+ RouteDecision decision = decide(state, questions, options);
+ // One dispatch point: `decide` returns from six branches, and a hook that fired from five
+ // of them would be worse than none.
+ dispatchLifecycle(Hooks.Event.ROUTE, decision.model());
+ return decision;
+ }
+
+ /** The routing itself, with no hooks, so {@link #route} has a single place to dispatch from. */
+ private RouteDecision decide(Object state, Map<String, Question> questions,
+ RouteOptions options) {
RouteOptions settings = options == null ? RouteOptions.none() : options;
if (settings.model() != null) {
@@ -851,7 +872,10 @@ public final class Router implements AutoCloseable, Predictor {
/** Borrow the agent for a checkpoint. */
public Lease lease(Checkpoint checkpoint) {
requireNonNull(checkpoint, "checkpoint");
- Slot slot = acquire(checkpoint);
+ Outcome outcome = new Outcome();
+ Slot slot = acquire(checkpoint, outcome);
+ // Before the Lease is handed over, so on_load precedes any use of the agent.
+ dispatchOutcome(checkpoint, outcome);
return new Lease(checkpoint, slot);
}
@@ -867,13 +891,55 @@ public final class Router implements AutoCloseable, Predictor {
*/
public Agent load(String name) {
Checkpoint checkpoint = normaliseName(name);
- Slot slot = acquire(checkpoint);
+ Outcome outcome = new Outcome();
+ Slot slot = acquire(checkpoint, outcome);
release(slot);
+ // After release: a hook calling back in must not find this call still holding a lease.
+ dispatchOutcome(checkpoint, outcome);
return slot.agent;
}
+ /**
+ * What one {@link #acquire} did, so its hooks fire after the lock is released. Dispatching
+ * under {@code lock} would let a blocking hook park every other caller.
+ */
+ private static final class Outcome {
+
+ private boolean built;
+ private final List<Checkpoint> evicted = new ArrayList<>();
+ }
+
+ /**
+ * Dispatch one router lifecycle event. MUST be called with no router lock held -- see
+ * {@link Outcome}.
+ */
+ private void dispatchLifecycle(Hooks.Event event, Checkpoint checkpoint) {
+ List<Hook> composed = hooks.composeFor(HookCall.none());
+ if (composed.isEmpty()) {
+ return; // no hooks: build no context, resolve no policy
+ }
+ PredictContext ctx = new PredictContext(List.of(), Map.of(),
+ checkpoint == null ? null : checkpoint.wireName(), this);
+ Hooks.dispatch(composed, event, ctx, hooks.policyFor(HookCall.none()));
+ }
+
+ /** The load and evict events one acquire owes, in that order. */
+ private void dispatchOutcome(Checkpoint checkpoint, Outcome outcome) {
+ if (outcome.built) {
+ dispatchLifecycle(Hooks.Event.LOAD, checkpoint);
+ }
+ for (Checkpoint evicted : outcome.evicted) {
+ dispatchLifecycle(Hooks.Event.EVICT, evicted);
+ }
+ }
+
/** The slot for a checkpoint, with one lease taken. */
private Slot acquire(Checkpoint checkpoint) {
+ return acquire(checkpoint, null);
+ }
+
+ /** The slot for a checkpoint, recording into {@code outcome} what it had to do to get it. */
+ private Slot acquire(Checkpoint checkpoint, Outcome outcome) {
while (true) {
InFlight waitFor = null;
InFlight mine = null;
@@ -903,7 +969,7 @@ public final class Router implements AutoCloseable, Predictor {
// This caller owns the build, and `mine` is the handle the others are waiting on.
// It has to be the one registered above: creating a second one here would leave
// every waiter blocked on a latch nobody ever counts down.
- return build(checkpoint, mine);
+ return build(checkpoint, mine, outcome);
}
// Someone else is building this one. Wait for them rather than build a second copy.
await(waitFor);
@@ -919,7 +985,7 @@ public final class Router implements AutoCloseable, Predictor {
}
}
- private Slot build(Checkpoint checkpoint, InFlight inflight) {
+ private Slot build(Checkpoint checkpoint, InFlight inflight, Outcome outcome) {
List<Agent> toClose = new ArrayList<>();
Slot built;
try {
@@ -964,7 +1030,11 @@ public final class Router implements AutoCloseable, Predictor {
built.leases++;
slots.put(checkpoint, built);
order.add(checkpoint);
- evictLocked(toClose);
+ List<Checkpoint> evicted = evictLocked(toClose);
+ if (outcome != null) {
+ outcome.built = true;
+ outcome.evicted.addAll(evicted);
+ }
}
} finally {
// `finish` ALWAYS, even if eviction threw. Skipping it left the new slot
@@ -1236,6 +1306,9 @@ public final class Router implements AutoCloseable, Predictor {
}
if (inflight == null) {
closeAll(toClose);
+ for (Checkpoint evicted : freed) {
+ dispatchLifecycle(Hooks.Event.EVICT, evicted);
+ }
return freed;
}
await(inflight);
@@ -1264,6 +1337,9 @@ public final class Router implements AutoCloseable, Predictor {
}
if (inflights.isEmpty()) {
closeAll(toClose);
+ for (Checkpoint evicted : freed) {
+ dispatchLifecycle(Hooks.Event.EVICT, evicted);
+ }
return freed;
}
for (InFlight inflight : inflights) {
@@ -1290,6 +1366,11 @@ public final class Router implements AutoCloseable, Predictor {
* ceiling in place. That is the reference's behaviour and is kept deliberately; a caller who
* needs the original ceiling back should build a new router.
*/
+ /** This router's hooks: install, remove, and set the error, timeout and concurrency policy. */
+ public HookRegistry hooks() {
+ return hooks;
+ }
+
public int maxLoaded() {
lock.lock();
try {
@@ -1333,9 +1414,36 @@ public final class Router implements AutoCloseable, Predictor {
if (language == null && decision.detection() != null) {
language = decision.detection().language();
}
- try (Lease lease = lease(decision.model())) {
- return lease.agent().predict(state, questions, language);
+ List<Hook> composed = hooks.composeFor(HookCall.none());
+ if (composed.isEmpty()) {
+ try (Lease lease = lease(decision.model())) {
+ return lease.agent().predict(state, questions, language); // unchanged fast path
+ }
+ }
+ // `Hooks.around` so ctx.skip, the error-before-end order, failure suppression and
+ // elapsed/usage all behave as they do on an Agent. The lease is taken inside it, so
+ // on_load and on_evict land between this call's start and end events.
+ //
+ // ctx.maxLen/headMaxLen are NOT forwarded: Agent.predict takes no budget arguments, so a
+ // Router-level start hook that sets one is ignored here.
+ PredictContext ctx = new PredictContext(Collections.singletonList(state), questions,
+ decision.model().wireName(), this);
+ String resolved = language;
+ Checkpoint target = decision.model();
+ List<Prediction> answered = Hooks.around(composed, ctx,
+ hooks.policyFor(HookCall.none()),
+ (states, asked, maxLen, headMaxLen) -> {
+ try (Lease lease = lease(target)) {
+ return List.of(lease.agent().predict(states.get(0), asked, resolved));
+ }
+ });
+ if (answered == null || answered.isEmpty()) {
+ // Only a hook can cause this, by skipping with no result. Inventing one would report
+ // a decision the model never made.
+ throw new IllegalStateException(
+ "a hook left no prediction for this call; ctx.skip(...) needs one result");
}
+ return answered.get(0);
}
/**
diff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.java
new file mode 100644
index 00000000..b27f8b63
--- /dev/null
+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/hooks/AsyncHook.java
@@ -0,0 +1,130 @@
+package com.convaiinnovations.laya.hooks;
+
+import java.time.Duration;
+import java.util.Objects;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionException;
+import java.util.concurrent.Executor;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+/**
+ * Runs another hook's callbacks on an {@link Executor}, and waits for each one.
+ *
+ * <p>For a hook that must run on a particular thread -- a framework request scope, a single-threaded
+ * actor, a UI loop -- not for making a slow hook free. The reference does the same: an async hook's
+ * coroutine is driven to completion on a background loop ({@code laya/hooks.run_coroutine_sync}), so
+ * the prediction still waits for it.
+ *
+ * <p>Waiting is what makes it safe. {@link PredictContext} is mutable and shared by one call, so a
+ * callback still reading it after the call moved on would see another call's state; a thrown
+ * exception would also be lost rather than reaching the hook policy.
+ */
+public final class AsyncHook implements Hook {
+
+ private final Hook delegate;
+ private final Executor executor;
+ private final Duration timeout;
+
+ private AsyncHook(Hook delegate, Executor executor, Duration timeout) {
+ this.delegate = Objects.requireNonNull(delegate, "delegate");
+ this.executor = Objects.requireNonNull(executor, "executor");
+ this.timeout = timeout;
+ }
+
+ /** Runs {@code delegate} on {@code executor}, waiting indefinitely for each callback. */
+ public static AsyncHook of(Hook delegate, Executor executor) {
+ return new AsyncHook(delegate, executor, null);
+ }
+
+ /**
+ * Runs {@code delegate} on {@code executor}, failing a callback that outlasts {@code timeout}.
+ *
+ * <p>Independent of {@code hooks_timeout}: that one bounds the whole dispatch and is not visible
+ * to a hook, so this one has to be given here.
+ */
+ public static AsyncHook of(Hook delegate, Executor executor, Duration timeout) {
+ if (timeout != null && (timeout.isNegative() || timeout.isZero())) {
+ throw new IllegalArgumentException("timeout must be positive, got " + timeout);
+ }
+ return new AsyncHook(delegate, executor, timeout);
+ }
+
+ /** The hook whose callbacks this runs. */
+ public Hook delegate() {
+ return delegate;
+ }
+
+ @Override
+ public void onPredictStart(PredictContext ctx) {
+ await("on_predict_start", () -> delegate.onPredictStart(ctx));
+ }
+
+ @Override
+ public void onPredictEnd(PredictContext ctx) {
+ await("on_predict_end", () -> delegate.onPredictEnd(ctx));
+ }
+
+ @Override
+ public void onRoute(PredictContext ctx) {
+ await("on_route", () -> delegate.onRoute(ctx));
+ }
+
+ @Override
+ public void onLoad(PredictContext ctx) {
+ await("on_load", () -> delegate.onLoad(ctx));
+ }
+
+ @Override
+ public void onEvict(PredictContext ctx) {
+ await("on_evict", () -> delegate.onEvict(ctx));
+ }
+
+ @Override
+ public void onError(PredictContext ctx) {
+ await("on_error", () -> delegate.onError(ctx));
+ }
+
+ private void await(String event, Runnable callback) {
+ CompletableFuture<Void> running;
+ try {
+ running = CompletableFuture.runAsync(callback, executor);
+ } catch (RuntimeException rejected) {
+ // A saturated or shut-down executor. Thrown as-is so the hook policy decides, exactly
+ // as it would for a synchronous hook that threw.
+ throw rejected;
+ }
+ try {
+ if (timeout == null) {
+ running.join();
+ } else {
+ running.get(timeout.toNanos(), TimeUnit.NANOSECONDS);
+ }
+ } catch (CompletionException | java.util.concurrent.ExecutionException wrapper) {
+ // Unwrapped, so the caller sees what the delegate threw rather than the plumbing.
+ Throwable cause = wrapper.getCause() == null ? wrapper : wrapper.getCause();
+ if (cause instanceof RuntimeException problem) {
+ throw problem;
+ }
+ if (cause instanceof Error problem) {
+ throw problem;
+ }
+ throw new IllegalStateException(delegate + " failed in " + event, cause);
+ } catch (TimeoutException expired) {
+ running.cancel(true);
+ throw new IllegalStateException(
+ delegate + " did not finish " + event + " within " + timeout, expired);
+ } catch (InterruptedException interrupted) {
+ // The flag is restored before unwinding, so a caller using interruption to cancel is
+ // not left thinking the interrupt was swallowed.
+ Thread.currentThread().interrupt();
+ running.cancel(true);
+ throw new IllegalStateException(delegate + " was interrupted in " + event, interrupted);
+ }
+ }
+
+ @Override
+ public String toString() {
+ return "AsyncHook(" + delegate + (timeout == null ? "" : ", timeout=" + timeout) + ")";
+ }
+}
diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.java
new file mode 100644
index 00000000..b599c04c
--- /dev/null
+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/AsyncHookTest.java
@@ -0,0 +1,180 @@
+package com.convaiinnovations.laya;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotEquals;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.convaiinnovations.laya.hooks.AsyncHook;
+import com.convaiinnovations.laya.hooks.Hook;
+import com.convaiinnovations.laya.hooks.PredictContext;
+import java.time.Duration;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/** {@link AsyncHook} runs a hook elsewhere but still waits for it, as the reference does. */
+class AsyncHookTest {
+
+ private static PredictContext ctx() {
+ return new PredictContext(List.of("state"), Map.of(), "english", null);
+ }
+
+ @Test
+ @DisplayName("the callback runs on the executor, not the calling thread")
+ void runsOnTheExecutor() {
+ ExecutorService pool = Executors.newSingleThreadExecutor(r -> new Thread(r, "hook-pool"));
+ try {
+ AtomicReference<String> ran = new AtomicReference<>();
+ Hook async = AsyncHook.of(new Hook() {
+ @Override
+ public void onPredictStart(PredictContext c) {
+ ran.set(Thread.currentThread().getName());
+ }
+ }, pool);
+ async.onPredictStart(ctx());
+ assertEquals("hook-pool", ran.get());
+ assertNotEquals(Thread.currentThread().getName(), ran.get());
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+
+ @Test
+ @DisplayName("the call waits: the callback has finished before the method returns")
+ void waitsForTheCallback() {
+ ExecutorService pool = Executors.newSingleThreadExecutor();
+ try {
+ CountDownLatch done = new CountDownLatch(1);
+ Hook async = AsyncHook.of(new Hook() {
+ @Override
+ public void onPredictStart(PredictContext c) {
+ try {
+ Thread.sleep(50);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ done.countDown();
+ }
+ }, pool);
+ async.onPredictStart(ctx());
+ assertEquals(0, done.getCount(), "returned before the callback finished");
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+
+ @Test
+ @DisplayName("the delegate's exception reaches the caller unwrapped, so the policy sees it")
+ void propagatesTheDelegateFailure() {
+ ExecutorService pool = Executors.newSingleThreadExecutor();
+ try {
+ IllegalStateException boom = new IllegalStateException("from the hook");
+ Hook async = AsyncHook.of(new Hook() {
+ @Override
+ public void onPredictEnd(PredictContext c) {
+ throw boom;
+ }
+ }, pool);
+ assertSame(boom, assertThrows(IllegalStateException.class,
+ () -> async.onPredictEnd(ctx())));
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+
+ @Test
+ @DisplayName("a callback that outlasts the timeout fails the dispatch")
+ void timesOut() {
+ ExecutorService pool = Executors.newSingleThreadExecutor();
+ try {
+ Hook async = AsyncHook.of(new Hook() {
+ @Override
+ public void onRoute(PredictContext c) {
+ try {
+ Thread.sleep(5_000);
+ } catch (InterruptedException e) {
+ Thread.currentThread().interrupt();
+ }
+ }
+ }, pool, Duration.ofMillis(50));
+ IllegalStateException thrown =
+ assertThrows(IllegalStateException.class, () -> async.onRoute(ctx()));
+ assertTrue(thrown.getMessage().contains("did not finish"), thrown.getMessage());
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+
+ @Test
+ @DisplayName("a non-positive timeout is refused rather than meaning 'never wait'")
+ void refusesANonPositiveTimeout() {
+ ExecutorService pool = Executors.newSingleThreadExecutor();
+ try {
+ Hook plain = new Hook() { };
+ assertThrows(IllegalArgumentException.class,
+ () -> AsyncHook.of(plain, pool, Duration.ZERO));
+ assertThrows(IllegalArgumentException.class,
+ () -> AsyncHook.of(plain, pool, Duration.ofMillis(-1)));
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+
+ @Test
+ @DisplayName("every event is forwarded, not just the predict pair")
+ void forwardsEveryEvent() {
+ ExecutorService pool = Executors.newSingleThreadExecutor();
+ try {
+ List<String> seen = new ArrayList<>();
+ Hook async = AsyncHook.of(new Hook() {
+ @Override
+ public void onPredictStart(PredictContext c) {
+ seen.add("start");
+ }
+
+ @Override
+ public void onPredictEnd(PredictContext c) {
+ seen.add("end");
+ }
+
+ @Override
+ public void onRoute(PredictContext c) {
+ seen.add("route");
+ }
+
+ @Override
+ public void onLoad(PredictContext c) {
+ seen.add("load");
+ }
+
+ @Override
+ public void onEvict(PredictContext c) {
+ seen.add("evict");
+ }
+
+ @Override
+ public void onError(PredictContext c) {
+ seen.add("error");
+ }
+ }, pool);
+ PredictContext ctx = ctx();
+ async.onPredictStart(ctx);
+ async.onRoute(ctx);
+ async.onLoad(ctx);
+ async.onEvict(ctx);
+ async.onError(ctx);
+ async.onPredictEnd(ctx);
+ assertEquals(List.of("start", "route", "load", "evict", "error", "end"), seen);
+ } finally {
+ pool.shutdownNow();
+ }
+ }
+}
diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.java
new file mode 100644
index 00000000..f7f79757
--- /dev/null
+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/RouterHooksTest.java
@@ -0,0 +1,186 @@
+package com.convaiinnovations.laya;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import com.convaiinnovations.laya.Router.Checkpoint;
+import com.convaiinnovations.laya.hooks.Hook;
+import com.convaiinnovations.laya.hooks.PredictContext;
+import java.io.IOException;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+/**
+ * A Router-level hook sees what no agent can: which checkpoint was chosen, and when one was built
+ * or dropped. Before this, {@code Router} dispatched nothing at all.
+ */
+class RouterHooksTest {
+
+ /** Records every event with the model it carried. */
+ private static final class Trace implements Hook {
+
+ final List<String> events = new ArrayList<>();
+
+ private void note(String event, PredictContext ctx) {
+ events.add(event + ":" + ctx.model());
+ }
+
+ @Override
+ public void onRoute(PredictContext ctx) {
+ note("route", ctx);
+ }
+
+ @Override
+ public void onLoad(PredictContext ctx) {
+ note("load", ctx);
+ }
+
+ @Override
+ public void onEvict(PredictContext ctx) {
+ note("evict", ctx);
+ }
+
+ @Override
+ public void onPredictStart(PredictContext ctx) {
+ note("start", ctx);
+ }
+
+ @Override
+ public void onPredictEnd(PredictContext ctx) {
+ note("end", ctx);
+ }
+ }
+
+ private static final class StubAgents implements Router.AgentFactory {
+
+ private final Path root;
+ int builds;
+
+ StubAgents(Path root) {
+ this.root = root;
+ }
+
+ @Override
+ public Agent create(Checkpoint checkpoint) throws IOException {
+ builds++;
+ return TinyCheckpoint.agent(root, new TinyCheckpoint.RecordingSession());
+ }
+ }
+
+ private static Map<String, Question> questions() {
+ return Map.of("urgent", Question.noul("Needs a human."));
+ }
+
+ @Test
+ @DisplayName("route() dispatches on_route once, naming the checkpoint it chose")
+ void routeDispatches(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ Trace trace = new Trace();
+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {
+ router.hooks().addHook(trace);
+ router.route("hello", questions());
+ assertEquals(1, trace.events.size(), trace.events.toString());
+ assertTrue(trace.events.get(0).startsWith("route:"), trace.events.toString());
+ }
+ }
+
+ @Test
+ @DisplayName("load() dispatches on_load for a build and stays quiet for a cache hit")
+ void loadDispatchesOnlyOnBuild(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ Trace trace = new Trace();
+ StubAgents agents = new StubAgents(root);
+ try (Router router = Router.builder().agents(agents).maxLoaded(2).build()) {
+ router.hooks().addHook(trace);
+ router.load("english");
+ assertEquals(List.of("load:english"), trace.events);
+ router.load("english"); // resident: no second build, no second event
+ assertEquals(List.of("load:english"), trace.events);
+ assertEquals(1, agents.builds);
+ }
+ }
+
+ @Test
+ @DisplayName("an eviction forced by maxLoaded dispatches on_evict for the victim")
+ void evictionDispatches(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ Trace trace = new Trace();
+ try (Router router = Router.builder().agents(new StubAgents(root)).maxLoaded(1).build()) {
+ router.hooks().addHook(trace);
+ router.load("english");
+ router.load("multilingual"); // maxLoaded 1, so english must go
+ assertTrue(trace.events.contains("evict:english"), trace.events.toString());
+ assertEquals(List.of("load:english", "load:multilingual", "evict:english"),
+ trace.events);
+ }
+ }
+
+ @Test
+ @DisplayName("unload dispatches on_evict for what it freed")
+ void unloadDispatches(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ Trace trace = new Trace();
+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {
+ router.load("english");
+ router.hooks().addHook(trace); // installed after the load
+ assertEquals(List.of(Checkpoint.ENGLISH), router.unload("english"));
+ assertEquals(List.of("evict:english"), trace.events);
+ }
+ }
+
+ @Test
+ @DisplayName("predict dispatches one start/end pair for the whole route-and-answer call")
+ void predictDispatchesOnePair(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ Trace trace = new Trace();
+ try (Router router = Router.builder().agents(new StubAgents(root)).build()) {
+ router.hooks().addHook(trace);
+ router.predict("hello", questions());
+ assertEquals(1, trace.events.stream().filter(e -> e.startsWith("start:")).count(),
+ trace.events.toString());
+ assertEquals(1, trace.events.stream().filter(e -> e.startsWith("end:")).count(),
+ trace.events.toString());
+ // on_load lands inside the pair, which is the order the reference dispatches in.
+ int start = trace.events.indexOf("start:english");
+ int load = trace.events.indexOf("load:english");
+ int end = trace.events.indexOf("end:english");
+ assertTrue(start >= 0 && load > start && end > load, trace.events.toString());
+ }
+ }
+
+ @Test
+ @DisplayName("a hook that calls back into the router does not deadlock")
+ void aReentrantHookDoesNotDeadlock(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ List<Integer> seen = new ArrayList<>();
+ try (Router router = Router.builder().agents(new StubAgents(root)).maxLoaded(2).build()) {
+ // Dispatching under the router lock would park this call on itself for ever.
+ router.hooks().addHook(new Hook() {
+ @Override
+ public void onLoad(PredictContext ctx) {
+ seen.add(router.loaded().size());
+ }
+ });
+ router.load("english");
+ assertEquals(List.of(1), seen);
+ }
+ }
+
+ @Test
+ @DisplayName("a router with no hooks dispatches nothing and builds no context")
+ void noHooksNoDispatch(@TempDir Path root) throws IOException {
+ TinyCheckpoint.write(root, 64, 32);
+ StubAgents agents = new StubAgents(root);
+ try (Router router = Router.builder().agents(agents).build()) {
+ assertFalse(router.hooks().hooks().iterator().hasNext());
+ router.predict("hello", questions()); // the unhooked fast path still answers
+ assertEquals(1, agents.builds);
+ }
+ }
+}