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
fix(java): refuse a criteria map whose iteration order is not defined
Adeshina Lasisi253b5c2d8f14
diff --git a/.github/workflows/java.yml b/.github/workflows/java.ymlindex 1182858b..cd176143 100644--- a/.github/workflows/java.yml+++ b/.github/workflows/java.yml@@ -179,7 +179,7 @@ jobs:if: ${{ !cancelled() }}run: >python laya-java/scripts/check_test_results.py- laya-java/laya-java/build/test-results/test --min-tests 933 --allow-aborted+ laya-java/laya-java/build/test-results/test --min-tests 943 --allow-aborted# The samples are single-file source programs, deliberately NOT a Gradle module: a# `samples` subproject would inherit the root build's MavenPublication and@@ -356,7 +356,7 @@ jobs:if: ${{ !cancelled() }}run: >python laya-java/scripts/check_test_results.py- laya-java/laya-java/build/test-results/test --min-tests 934 --allow-aborted+ laya-java/laya-java/build/test-results/test --min-tests 944 --allow-aborted--require-passed TestJvmVersionTest- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2if: ${{ failure() }}diff --git a/.github/workflows/release-java.yml b/.github/workflows/release-java.ymlindex bb51d071..3d700d43 100644--- a/.github/workflows/release-java.yml+++ b/.github/workflows/release-java.yml@@ -67,7 +67,7 @@ jobs:# that lane already covered.- name: Model-free testsrun: ./gradlew --no-daemon test- # 685 of the 699 registered tests run without a checkpoint. This floor has been raised+ # 943 of the 960 registered tests run without a checkpoint. This floor has been raised# as the model-free suite grew -- 440 left 191 of slack, 625 left 60 -- because a floor# that does not bind is not a gate: under 625 the whole confidence-gate family of 26# tests could have vanished from this lane with the gate still green.@@ -83,7 +83,7 @@ jobs:- name: The suite was not vacuousrun: >python3 scripts/check_test_results.py laya-java/build/test-results/test- --min-tests 680 --allow-aborted+ --min-tests 943 --allow-aborted- name: Build the jarsrun: ./gradlew --no-daemon build -x testdiff --git a/laya-java/README.md b/laya-java/README.mdindex da0c7429..dadb6e6d 100644--- a/laya-java/README.md+++ b/laya-java/README.md@@ -55,6 +55,7 @@ import java.nio.file.Path;import java.util.*;// Options are POSITIONAL, so use a LinkedHashMap: two orders are two different questions.+// A HashMap or Map.of is refused rather than silently reordered -- see Option order below.Map<String, Object> criteria = new LinkedHashMap<>();criteria.put("refund", "money back for a duplicate charge");criteria.put("escalate", "pass it to a human");@@ -476,6 +477,39 @@ and a JVM method call is already synchronous: a hook that wants asynchronous worblocks on it — `ship(ctx.results()).toCompletableFuture().join()` — bounded however your runtimewants, or by `timeout(Duration)`.+## Option order++A choice's options are positional: option N renders Nth and logit N is read back as the Nth label.+So the criteria map's iteration order decides both what is asked and how the answer is labelled, and+a map whose type does not define that order changes both silently. Measured on JDK 17:++| written | `LinkedHashMap` | `HashMap` | `Map.of` |+|---|---|---|---|+| `refund, escalate, ignore` | `refund, escalate, ignore` | `ignore, escalate, refund` | varies per JVM |++`HashMap` is exactly reversed here, so `probabilities().get("refund")` would have reported the logit+that belonged to `ignore`. It is at least reproducible, because `String.hashCode` is specified.+`Map.of` is worse: it salts its table per JVM, so three runs of one program gave three different+orders -- the same question answering differently after a restart.++`Question.choice` therefore refuses a map whose contract leaves the order unspecified -- `HashMap`,+`Map.of`/`Map.copyOf` with two or more options, `ConcurrentHashMap`, `Hashtable`, `WeakHashMap`,+`IdentityHashMap` -- and names the fix. A `LinkedHashMap`, a `SortedMap`, an unmodifiable view of+either, or any single-option map is accepted; one option cannot be out of order.++When there is no map to hand, build the question from the options directly and the order cannot be+lost at all:++```java+Question q = Question.choiceOf("What does the customer want?",+ Map.entry("refund", "money back for a duplicate charge"),+ Map.entry("escalate", "pass it to a human"),+ Map.entry("ignore", "no action needed"));+```++Two options sharing a label are refused there too: a map would have kept only the last, asking a+question with fewer options than were written.+## Threads`Agent.open(model, graph)` leaves the thread count to ONNX Runtime, which is what the Pythondiff --git a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.javaindex 84cb4116..cc6555b6 100644--- a/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java+++ b/laya-java/laya-java/src/main/java/com/convaiinnovations/laya/Question.java@@ -3,9 +3,15 @@ package com.convaiinnovations.laya;import com.convaiinnovations.laya.json.PythonJson;import com.convaiinnovations.laya.lang.UnicodeTables;import java.util.ArrayList;+import java.util.HashMap;+import java.util.Hashtable;+import java.util.IdentityHashMap;import java.util.LinkedHashMap;import java.util.List;import java.util.Map;+import java.util.SortedMap;+import java.util.WeakHashMap;+import java.util.concurrent.ConcurrentHashMap;/*** One decision to put to the model: its type, its instruction, and the options it chooses between.@@ -82,10 +88,79 @@ public final class Question {public static Question choice(String instructions, Map<String, ?> criteria) {requireInstructions(instructions);require(criteria != null && !criteria.isEmpty(), "a choice question needs criteria");+ require(!orderIsUnspecified(criteria),+ "a choice's options are positional, so the criteria map's iteration order decides "+ + "what is asked and how the answer is labelled, and "+ + criteria.getClass().getName() + " does not specify one. Use a LinkedHashMap, or "+ + "Question.choiceOf(instructions, Map.entry(label, description), ...)");return new Question(Type.CHOICE, instructions, new LinkedHashMap<>(criteria), null,null, null);}+ /**+ * A choice built from options in the order they are written, with no map to lose that order.+ *+ * <p>The counterpart of {@link #choice} for callers who would otherwise reach for+ * {@code Map.of}: there is no intermediate collection whose type could reorder the options, so+ * the Nth argument is the Nth option and index N of {@link #labels} is the label for logit N.+ *+ * @throws IllegalArgumentException if two options share a label. A map would have kept only the+ * last silently, asking a question with fewer options than were written.+ */+ @SafeVarargs+ public static Question choiceOf(String instructions, Map.Entry<String, ?>... options) {+ requireInstructions(instructions);+ require(options != null && options.length > 0, "a choice question needs criteria");+ Map<String, Object> ordered = new LinkedHashMap<>();+ for (Map.Entry<String, ?> option : options) {+ require(option != null, "a choice option must not be null");+ String label = option.getKey();+ require(label != null && !label.isEmpty(),+ "a choice option needs a label; give every option a name");+ // containsKey, not the return of put: a legitimate criterion may be null, and then put+ // returns null for a duplicate too, so the duplicate would go unreported.+ require(!ordered.containsKey(label),+ "duplicate choice label " + PythonJson.repr(label) + "; two options cannot "+ + "share one label, and a map would have kept only the last");+ ordered.put(label, option.getValue());+ }+ return new Question(Type.CHOICE, instructions, ordered, null, null, null);+ }++ /**+ * Whether this map's own contract leaves its iteration order unspecified.+ *+ * <p>Measured on JDK 17, with the options written {@code refund, escalate, ignore}: a+ * {@code HashMap} iterates {@code ignore, escalate, refund} -- exactly reversed, so option 0's+ * probability would be reported against option 2's label. That much is at least reproducible,+ * because {@code String.hashCode} is specified. {@code Map.of} is worse: it salts its table per+ * JVM, so three runs of one program gave three different orders and the same question answers+ * differently after a restart.+ *+ * <p>A denylist rather than an allowlist, because a false refusal breaks working code: Guava's+ * {@code ImmutableMap} and {@code Collections.unmodifiableMap(aLinkedHashMap)} both iterate in a+ * defined order this method cannot see, and refusing them would be wrong.+ */+ private static boolean orderIsUnspecified(Map<String, ?> criteria) {+ if (criteria.size() < 2) {+ return false; // one option cannot be in the wrong order+ }+ if (criteria instanceof LinkedHashMap || criteria instanceof SortedMap) {+ return false;+ }+ // By class, not by `instanceof`: LinkedHashMap IS a HashMap, so an instanceof test would+ // reject the very map this is meant to accept.+ Class<?> type = criteria.getClass();+ if (type == HashMap.class || type == Hashtable.class || type == WeakHashMap.class+ || type == IdentityHashMap.class || type == ConcurrentHashMap.class) {+ return true;+ }+ // `Map.of` and `Map.copyOf` with two or more entries. The class is package-private, so its+ // name is the only handle on it; it has been stable since the factories arrived in 9. The+ // single-entry form is a different class and cannot be misordered, so it is not named here.+ return "java.util.ImmutableCollections$MapN".equals(type.getName());+ }+/** A score over ordered levels, rendered as {@code "level <i>: <criterion>"}. */public static Question score(String instructions, List<?> levels) {requireInstructions(instructions);diff --git a/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.java b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.javanew file mode 100644index 00000000..618c4f40--- /dev/null+++ b/laya-java/laya-java/src/test/java/com/convaiinnovations/laya/QuestionCriteriaOrderTest.java@@ -0,0 +1,148 @@+package com.convaiinnovations.laya;++import static org.junit.jupiter.api.Assertions.assertEquals;+import static org.junit.jupiter.api.Assertions.assertThrows;+import static org.junit.jupiter.api.Assertions.assertTrue;++import java.util.ArrayList;+import java.util.Collections;+import java.util.HashMap;+import java.util.IdentityHashMap;+import java.util.LinkedHashMap;+import java.util.List;+import java.util.Map;+import java.util.TreeMap;+import java.util.concurrent.ConcurrentHashMap;+import org.junit.jupiter.api.DisplayName;+import org.junit.jupiter.api.Test;++/**+ * A choice's options are positional: option N's description renders Nth and logit N is read back as+ * the Nth label. So the criteria map's iteration order decides what the model was asked and how its+ * answer is labelled, and a map whose type does not define that order silently changes both.+ *+ * <p>How silent it is, measured on JDK 17:+ *+ * <pre>+ * insertion [refund, escalate, ignore] HashMap [ignore, escalate, refund]+ * insertion [billing, technical, sales, other] HashMap [other, technical, sales, billing]+ * </pre>+ *+ * Exactly reversed, so {@code probabilities().get("refund")} would have reported the logit that+ * belonged to {@code ignore}. {@code HashMap} is at least stable run to run, because+ * {@code String.hashCode} is specified. {@code Map.of} is not: it salts its layout per JVM, so three+ * runs of one program gave {@code [ignore, escalate, refund]}, {@code [escalate, ignore, refund]}+ * and {@code [refund, escalate, ignore]} -- the same question answering differently after a restart.+ */+class QuestionCriteriaOrderTest {++ /** The labels in the order logit N is read back as label N -- what the order actually decides. */+ private static List<String> renderedOptions(Question q) {+ return q.labels();+ }++ @Test+ @DisplayName("a LinkedHashMap keeps the caller's order, which is the contract")+ void linkedHashMapKeepsOrder() {+ Map<String, Object> c = new LinkedHashMap<>();+ c.put("refund", "money back for a duplicate charge");+ c.put("escalate", "pass it to a human");+ c.put("ignore", "no action needed");+ assertEquals(List.of("refund", "escalate", "ignore"),+ renderedOptions(Question.choice("What does the customer want?", c)));+ }++ @Test+ @DisplayName("a HashMap is refused, because its order is not the one that was written")+ void hashMapIsRefused() {+ Map<String, Object> c = new HashMap<>();+ c.put("refund", "money back for a duplicate charge");+ c.put("escalate", "pass it to a human");+ c.put("ignore", "no action needed");+ // Proof the hazard is real and not hypothetical: this is the order the model would have been+ // given, and it is the caller's reversed.+ assertEquals(List.of("ignore", "escalate", "refund"), new ArrayList<>(c.keySet()));+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,+ () -> Question.choice("What does the customer want?", c));+ assertTrue(e.getMessage().contains("iteration order"), e.getMessage());+ assertTrue(e.getMessage().contains("LinkedHashMap"), e.getMessage());+ }++ @Test+ @DisplayName("Map.of with two or more options is refused: its order is salted per JVM")+ void mapOfIsRefused() {+ Map<String, String> c = Map.of("refund", "money back", "escalate", "to a human");+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", c));+ }++ @Test+ @DisplayName("Map.copyOf is refused too: copying a LinkedHashMap does not keep its order")+ void mapCopyOfIsRefused() {+ Map<String, Object> ordered = new LinkedHashMap<>();+ ordered.put("refund", "money back");+ ordered.put("escalate", "to a human");+ // Map.copyOf returns the same salted implementation Map.of does, so the order is gone.+ assertThrows(IllegalArgumentException.class,+ () -> Question.choice("Which?", Map.copyOf(ordered)));+ }++ @Test+ @DisplayName("the other unordered JDK maps are refused on the same ground")+ void otherUnorderedMapsAreRefused() {+ Map<String, Object> chm = new ConcurrentHashMap<>();+ chm.put("a", "1");+ chm.put("b", "2");+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", chm));+ Map<String, Object> ihm = new IdentityHashMap<>();+ ihm.put("a", "1");+ ihm.put("b", "2");+ assertThrows(IllegalArgumentException.class, () -> Question.choice("Which?", ihm));+ }++ @Test+ @DisplayName("a single option is accepted from any map: one option cannot be misordered")+ void oneOptionIsAlwaysFine() {+ assertEquals(List.of("only"),+ renderedOptions(Question.choice("Which?", Map.of("only", "the only option"))));+ assertEquals(List.of("only"),+ renderedOptions(Question.choice("Which?", new HashMap<>(Map.of("only", "d")))));+ }++ @Test+ @DisplayName("a SortedMap is accepted: its contract defines the order, even if it is not insertion")+ void sortedMapIsAccepted() {+ Map<String, Object> c = new TreeMap<>();+ c.put("refund", "money back");+ c.put("escalate", "to a human");+ assertEquals(List.of("escalate", "refund"),+ renderedOptions(Question.choice("Which?", c)));+ }++ @Test+ @DisplayName("an unmodifiable view of a LinkedHashMap is accepted: it delegates iteration")+ void unmodifiableViewIsAccepted() {+ Map<String, Object> inner = new LinkedHashMap<>();+ inner.put("refund", "money back");+ inner.put("escalate", "to a human");+ assertEquals(List.of("refund", "escalate"),+ renderedOptions(Question.choice("Which?", Collections.unmodifiableMap(inner))));+ }++ @Test+ @DisplayName("the ordered-entry factory needs no map at all, so order cannot be lost")+ void orderedEntriesFactory() {+ Question q = Question.choiceOf("What does the customer want?",+ Map.entry("refund", "money back for a duplicate charge"),+ Map.entry("escalate", "pass it to a human"),+ Map.entry("ignore", "no action needed"));+ assertEquals(List.of("refund", "escalate", "ignore"), renderedOptions(q));+ }++ @Test+ @DisplayName("choiceOf refuses a duplicate label rather than silently dropping an option")+ void orderedEntriesRefuseDuplicates() {+ IllegalArgumentException e = assertThrows(IllegalArgumentException.class,+ () -> Question.choiceOf("Which?", Map.entry("a", "1"), Map.entry("a", "2")));+ assertTrue(e.getMessage().contains("duplicate"), e.getMessage());+ }+}