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(java): document routing, detection, presets and shortlisting

Adeshina Lasisi527e74d4c841
diff --git a/laya-java/README.md b/laya-java/README.md
index 61684c53..1118b398 100644
--- a/laya-java/README.md
+++ b/laya-java/README.md
@@ -11,10 +11,12 @@ four questions about a document cost one batched encode rather than four round t
## Status
Implemented: tokenizer, sequence builder, config, ONNX inference (fused or split graph), answer
-decoding, `predict`, `predictBatch`, usage and truncation reporting.
+decoding, `predict`, `predictBatch`, usage and truncation reporting, script and language detection
+(`lang.LanguageDetection`), the question presets (`Presets`), the checkpoint `Router` with its
+load-and-evict lifecycle, and the embedding `Shortlist` with its LRU cache.
-Not implemented yet: hooks, the language `Router`, `predictLong`, shortlist, structured `decide`,
-the `laya-java-client` HTTP module, Android. **Not published to Maven Central** — see
+Not implemented yet: hooks, `predictLong`, structured `decide`, `laya.email`, the
+`laya-java-client` HTTP module, Android. **Not published to Maven Central** — see
[Installing](#installing).
## Export a graph (once per checkpoint)
@@ -138,9 +140,106 @@ List<Prediction> out2 = agent.predictBatch(states, questions, "en",
Results come back in the caller's order whatever the grouping was. `batchSize` bounds peak memory
and `sortByLength` cuts padding; neither changes an answer.
+## Routing between checkpoints
+
+The English checkpoint does not degrade gently off English, it collapses — 0.100 on 20-option
+MASSIVE Hindi intent against 0.050 for random guessing, and it reports high confidence while doing
+so. So a `Router` picks the checkpoint before the question is asked.
+
+```java
+import com.convaiinnovations.laya.Router;
+import java.nio.file.Path;
+
+try (Router router = Router.builder()
+ .checkpointsRoot(Path.of("./checkpoints")) // ./checkpoints/english, /multilingual, ...
+ .maxLoaded(2) // a memory ceiling, not a cache hint
+ .build()) {
+
+ Router.RouteDecision decided = router.route(state);
+ System.out.println(decided.model() + ": " + decided.reason());
+ // multilingual: non-Latin script (devanagari, 100% of letters); the English checkpoint
+ // cannot read it
+
+ Prediction answer = router.predict(state, questions); // routes, loads, answers
+}
+```
+
+`route` runs no model and reads no disk, so it is safe on every request. Precedence, highest
+first: an explicit model, an explicit task, a detected typed-decisions workflow (opt-in only), an
+explicit language, a caller's hint, the built-in detection, then the configured default.
+
+`maxLoaded` evicts the least recently used checkpoint, and `Router.Lease` keeps one open for as
+long as you hold it — `predict` leases internally, so the ordinary path needs no thought. An agent
+handed in with `attach` is never closed: the caller keeps ownership.
+
+A deployment whose traffic is mostly not English should set
+`defaultCheckpoint(Checkpoint.MULTILINGUAL)`: an unidentified Latin-script state is no evidence of
+English, and that is the only knob which says so.
+
+## Detection on its own
+
+`lang.LanguageDetection` is the router's evidence, usable without one:
+
+```java
+import com.convaiinnovations.laya.lang.LanguageDetection;
+
+LanguageDetection.Analysis seen = LanguageDetection.analyse(state);
+seen.script(); // "latin", "han", "devanagari", ... or "unknown"
+seen.language(); // best effort, null when undecided
+seen.english(); // whether the English checkpoint can read it
+seen.mixedSegment(); // the line or field that made a mostly-English state non-English
+```
+
+Undecided is not English: when nothing identifies the language, non-English letters or a shared
+Swedish–Danish marker still prefer the multilingual checkpoint.
+
+## Presets
+
+Five ready-made question sets, word for word the reference's:
+
+```java
+import com.convaiinnovations.laya.Presets;
+
+Map<String, Question> questions = Presets.triage(); // or email(), guard(),
+ // moderation(), router()
+Presets.stateField(questions); // "message" — the key it reads
+```
+
+Each call returns a fresh mutable map, so dropping a question you do not want is safe. A preset
+names the state key it reads in backticks, and `stateField` reads it back out — so a caller can
+place its text under the right key instead of guessing.
+
+## Shortlisting a large label set
+
+Choice options share one `head_max_len`, so a seventeen-label set leaves few tokens per label.
+`Shortlist` embeds the state and each option, keeps the top `k`, and runs one prediction over the
+reduced set — no second decision pass.
+
+```java
+import com.convaiinnovations.laya.Shortlist;
+
+Shortlist.Embedder embedder = texts -> myBiEncoder.embed(texts); // your vectors
+Shortlist.Shortlisted out = Shortlist.predict(agent, state, questions,
+ Shortlist.cached(embedder), 20);
+
+out.prediction(); // the answer, over the kept labels only
+out.shortlist().get("intent"); // which labels survived, and their scores
+```
+
+`Shortlist.cached(...)` embeds each text once under an LRU bound, so a fixed label list is
+embedded on the first call and only the new query thereafter. `k` at or above the label count is a
+passthrough: the labels come back in order and **the embedder is never called**.
+
+Both `Agent` and `Router` implement `Predictor`, so shortlisting works identically against a fixed
+checkpoint or a routed one.
+
## Lower-level pieces
```java
+import com.convaiinnovations.laya.config.AgentConfig;
+import com.convaiinnovations.laya.tokenizer.Tokenizer;
+import java.nio.file.Path;
+
Tokenizer tok = Tokenizer.fromModelDirectory(Path.of("./checkpoint"));
int[] ids = tok.encode("charged twice");
int[] capped = tok.encode(longText, 48); // stops early; same prefix as the full encoding