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.
Python calibrationclassificationdecision-modelhuggingfacejevmodernbertmultilingualnlppythonpytorchroutingtyped-decisionszero-shot
docs(java): document routing, detection, presets and shortlisting
Adeshina Lasisi5bcf40de49a1
diff --git a/laya-java/README.md b/laya-java/README.mdindex 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## StatusImplemented: 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 memoryand `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