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
feat(router): accept a caller-supplied language hint (#211)
PerryLinkee8369ead3da
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 3a81a306..2b1536b6 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -49,6 +49,7 @@ jobs:python tests/test_shortlist.pypython tests/test_decision_model.pypython tests/test_packaging.py+ python tests/test_lang_guess.py- name: Email cleaning testsrun: python tests/test_email.pydiff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 86e93792..13faadb6 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -44,6 +44,7 @@ jobs:python tests/test_shortlist.pypython tests/test_decision_model.pypython tests/test_packaging.py+ python tests/test_lang_guess.py- name: Buildrun: python -m builddiff --git a/README.md b/README.mdindex ee355309..17ea1483 100644--- a/README.md+++ b/README.md@@ -168,6 +168,31 @@ router.unload() # free memory| `Router(max_loaded=1)` | 7 to 10 s on every language switch | 1 per switch || `Router(preload=True)` | **32.8 ms (GPU) / 193–464 ms (CPU)** | **none** |+### Supplying Your Own Language Detection++Routing asks one question: *can the English checkpoint read this state?* The built-in detector answers it from the script and a function-word heuristic, and is deliberately dependency-free. That heuristic is best-effort on Latin-script languages it holds no word list for, so a short request can carry no usable signal:++```python+from laya.lang import analyse+analyse("Care este ora in Tokyo?")+# {'script': 'latin', 'language': 'en', 'is_english': True} -> the English checkpoint+```++If you already run a language-identification model, hand routing the answer instead of relying on the heuristic. `lang_guess` takes a language code or a callable receiving the state, and is checked after an explicit `lang=` and before detection:++```python+# A code you already know+router.predict(state, questions, lang_guess="ro")++# A callable, e.g. wrapping fastText, CLD3 or a transformer LID+router.predict(state, questions, lang_guess=lambda s: my_lid(s))++# Or install one for every request on a server+router = Router(preload=True, lang_guess=my_lid)+```++The hint only decides *English or not*: a code whose primary subtag is `en`, `eng` or `english` routes to the English checkpoint and everything else routes to the multilingual one. `"en_US"` and `"en_US.UTF-8"` are read as English, so `$LANG` can be passed straight through. Returning `None`, or an empty code, makes it abstain and the built-in detector decides as before — so a LID model that is unsure does not force a checkpoint. An explicit `model=`, `task=` or `lang=` still wins, and the default path is unchanged.+---## Single-Model Mode (Direct SDK)diff --git a/laya/router.py b/laya/router.pyindex 3d79d7cc..83659a0d 100644--- a/laya/router.py+++ b/laya/router.py@@ -120,6 +120,31 @@ def match_typed_decisions_workflow(questions: Dict[str, Any]) -> Optional[str]:return None+# Subtags that mean "the English checkpoint can read this". Routing needs one bit -- is this+# English Latin text, or something the English checkpoint cannot read -- not a language id, so+# every other code resolves to the multilingual checkpoint.+_ENGLISH_SUBTAGS = ("en", "eng", "english")+++def _english_from_code(value: Any) -> Optional[bool]:+ """True/False for a language code, or None when the code identifies nothing.++ Accepts the forms a caller is likely to have to hand: `"en"`, `"EN"`, `"en-US"`, the+ POSIX `"en_US"` (which `$LANG` holds), and `"en_US.UTF-8"`. `None` here means "no usable+ hint", which is what lets a language-identification model abstain.+ """+ if value is None:+ return None+ code = str(value).strip().lower()+ if not code:+ return None+ code = code.split(".", 1)[0] # en_US.UTF-8 -> en_US+ primary = code.replace("_", "-").split("-", 1)[0] # en_US -> en+ if not primary:+ return None+ return primary in _ENGLISH_SUBTAGS++class Router:"""Lazily loads Laya checkpoints and sends each request to the right one.@@ -159,6 +184,7 @@ class Router:auto_task_detection: bool = False,standalone_repos: bool = False,preload: bool = False,+ lang_guess: Optional[Any] = None,):self.models = dict(STANDALONE_MODELS if standalone_repos else DEFAULT_MODELS)if models:@@ -168,6 +194,11 @@ class Router:self.max_loaded = max(1, int(max_loaded))self.default = normalise_name(default)self.auto_task_detection = bool(auto_task_detection)+ # An opt-in language hint installed for every request: a code, or a callable taking the+ # state and returning one (or None to abstain). Checked before the built-in detection,+ # never before an explicit `model`, `task` or `lang`. The default path is unchanged, so+ # the heuristic stays dependency-free; this is the seam for a real LID model.+ self.lang_guess = lang_guessself._agents: Dict[str, Any] = {}self._order: List[str] = [] # least-recently-used first# Re-entrant lock guarding model lifecycle (load/unload/attach/preload) and the@@ -260,6 +291,19 @@ class Router:with self._lock:return list(self._order)+ def _resolve_hint(self, hint: Any, state: Union[str, dict, list, None]) -> Optional[bool]:+ """True/False for a hint about whether the English checkpoint can read `state`.++ `hint` is either a language code or a callable taking the state. Anything the hint+ cannot answer returns None, which makes `route` fall through to detection rather than+ picking a checkpoint on no evidence.+ """+ if hint is None:+ return None+ if callable(hint):+ hint = hint(state)+ return _english_from_code(hint)+# ------------------------------------------------------------------ routingdef route(self,@@ -268,11 +312,19 @@ class Router:model: Optional[str] = None,task: Optional[str] = None,lang: Optional[str] = None,+ lang_guess: Optional[Any] = None,) -> RouteDecision:"""Decide which checkpoint to use, without loading or running anything.Precedence: explicit `model` > explicit `task` > detected workflow (opt-in) >- explicit `lang` > detected script/language > default.+ explicit `lang` > `lang_guess` > detected script/language > default.++ `lang_guess` is an opt-in hint -- a language code or a callable taking the state --+ checked after an explicit `lang` and before the built-in detection. It only answers+ "can the English checkpoint read this?", so any non-English code routes to the+ multilingual checkpoint. A hint that resolves to nothing falls through to detection,+ which lets a language-identification model abstain. Pass one here, or set+ `Router(lang_guess=...)` to apply it to every request."""if model is not None:key = normalise_name(model)@@ -291,10 +343,22 @@ class Router:detection=None, workflow=workflow)if lang is not None:- key = "english" if str(lang).lower().split("-")[0] in ("en", "eng", "english") else "multilingual"+ key = "english" if _english_from_code(lang) else "multilingual"return RouteDecision(model=key, repo=_repo_str(self.models[key]), reason="explicit lang=%r" % lang,detection=None, workflow=workflow)+ # Caller-supplied hint, per-call first then the one installed on the Router. Only a hint+ # that actually answers the question routes here; anything else falls through.+ for source, hint in (("lang_guess", lang_guess), ("Router(lang_guess=...)", self.lang_guess)):+ resolved = self._resolve_hint(hint, state)+ if resolved is not None:+ key = "english" if resolved else "multilingual"+ return RouteDecision(+ model=key, repo=_repo_str(self.models[key]),+ reason="%s: the caller identified this as %s text" % (+ source, "English" if resolved else "non-English"),+ detection=None, workflow=workflow)+det = analyse(state)if det["script"] == "unknown":key = self.default@@ -326,12 +390,13 @@ class Router:model: Optional[str] = None,task: Optional[str] = None,lang: Optional[str] = None,+ lang_guess: Optional[Any] = None,) -> Dict[str, Any]:"""Route, then answer every question in one forward pass on the chosen checkpoint.The result is the usual `system_one` payload plus a `routing` key recording the decision."""- decision = self.route(state, questions, model=model, task=task, lang=lang)+ decision = self.route(state, questions, model=model, task=task, lang=lang, lang_guess=lang_guess)agent = self.load(decision["model"])result = agent.system_one(state, questions)result["routing"] = dict(decision)diff --git a/tests/test_lang_guess.py b/tests/test_lang_guess.pynew file mode 100644index 00000000..bd03a731--- /dev/null+++ b/tests/test_lang_guess.py@@ -0,0 +1,178 @@+"""Regression tests for the caller-supplied language hint (`lang_guess`).++A caller who already runs a language-identification model can hand routing the answer instead+of being silently misrouted by the built-in stopword heuristic:++ analyse("Care este ora in Tokyo?")+ # {'script': 'latin', 'language': 'en', 'is_english': True} -> routes to ENGLISH++The hint answers one question -- can the English checkpoint read this state -- so it is checked+after an explicit `lang` and before detection, and a hint that resolves to nothing falls+through to detection so a LID model can abstain.++Run: python tests/test_lang_guess.py+"""+import os+import sys++sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))++from laya.router import Router, _english_from_code # noqa: E402++PASS, FAIL = [], []+++def check(name, got, want):+ if got == want:+ PASS.append(name)+ else:+ FAIL.append("%s:\n got %r\n want %r" % (name, got, want))+++def check_true(name, cond, detail=""):+ if cond:+ PASS.append(name)+ else:+ FAIL.append("%s %s" % (name, detail))+++# The state the maintainer used on #35: a short Romanian request the heuristic cannot place.+ROMANIAN = "Care este ora in Tokyo?"+GENERIC = {"intent": {"type": "choice", "instructions": "x", "criteria": ["a", "b"]}}++# ------------------------------------------------------------------ the baseline+r0 = Router()+check("baseline/Romanian is not identified by the heuristic",+ r0.route(ROMANIAN, GENERIC)["detection"]["language"], "en")+check_true("baseline/Romanian therefore reaches english",+ r0.route(ROMANIAN, GENERIC)["model"] in ("english", "multilingual"),+ r0.route(ROMANIAN, GENERIC)["model"])+++# ------------------------------------------------------------------ codes+check("code/Romanian routes multilingual", r0.route(ROMANIAN, GENERIC, lang_guess="ro")["model"],+ "multilingual")+check("code/English routes english", r0.route(ROMANIAN, GENERIC, lang_guess="en")["model"], "english")+check("code/POSIX underscore is read", r0.route(ROMANIAN, GENERIC, lang_guess="en_US")["model"], "english")+check("code/POSIX with encoding is read",+ r0.route(ROMANIAN, GENERIC, lang_guess="en_US.UTF-8")["model"], "english")+check("code/hyphen subtag is read", r0.route(ROMANIAN, GENERIC, lang_guess="de-DE")["model"], "multilingual")+check("code/case is ignored", r0.route(ROMANIAN, GENERIC, lang_guess="RO")["model"], "multilingual")+check("code/whitespace is ignored", r0.route(ROMANIAN, GENERIC, lang_guess=" en ")["model"], "english")+check("code/unknown code still means non-English",+ r0.route(ROMANIAN, GENERIC, lang_guess="qq")["model"], "multilingual")++# an abstaining hint must fall through to detection, not force a checkpoint+for empty in (None, "", " "):+ d = r0.route(ROMANIAN, GENERIC, lang_guess=empty)+ check("abstain/%r falls through to detection" % (empty,), d["detection"] is not None, True)++# ------------------------------------------------------------------ callables+check("callable/code is used",+ r0.route(ROMANIAN, GENERIC, lang_guess=lambda s: "ro")["model"], "multilingual")+check("callable/receives the state",+ r0.route(ROMANIAN, GENERIC, lang_guess=lambda s: "en" if "Tokyo" in str(s) else "ro")["model"],+ "english")+check("callable/None falls through to detection",+ r0.route(ROMANIAN, GENERIC, lang_guess=lambda s: None)["detection"] is not None, True)+check("callable/empty string falls through",+ r0.route(ROMANIAN, GENERIC, lang_guess=lambda s: "")["detection"] is not None, True)+check("callable/Romanian model that returns None does not change the default route",+ r0.route(ROMANIAN, GENERIC, lang_guess=lambda s: None)["model"],+ r0.route(ROMANIAN, GENERIC)["model"])++# ------------------------------------------------------------------ installed on the Router+r_inst = Router(lang_guess="ro")+check("installed/applies without a per-call hint", r_inst.route(ROMANIAN, GENERIC)["model"], "multilingual")+check("installed/per-call overrides the installed one",+ r_inst.route(ROMANIAN, GENERIC, lang_guess="en")["model"], "english")+r_fn = Router(lang_guess=lambda s: "ro")+check("installed/callable works too", r_fn.route(ROMANIAN, GENERIC)["model"], "multilingual")+check("installed/absent by default", r0.lang_guess, None)+check("installed/a hint that abstains leaves detection intact",+ Router(lang_guess=lambda s: None).route(ROMANIAN, GENERIC)["detection"] is not None, True)++# ------------------------------------------------------------------ precedence+check("precedence/explicit model beats the hint",+ r0.route(ROMANIAN, GENERIC, model="english", lang_guess="ro")["model"], "english")+check("precedence/explicit task beats the hint",+ r0.route(ROMANIAN, GENERIC, task="typed_decisions", lang_guess="ro")["model"], "typed-decisions")+check("precedence/explicit lang beats the hint",+ r0.route(ROMANIAN, GENERIC, lang="en", lang_guess="ro")["model"], "english")+check_true("precedence/an explicit lang is still reported as explicit",+ "explicit lang" in r0.route(ROMANIAN, GENERIC, lang="en", lang_guess="ro")["reason"])++# ------------------------------------------------------------------ the decision payload+d = r0.route(ROMANIAN, GENERIC, lang_guess="ro")+check("payload/model", d["model"], "multilingual")+check("payload/repo is a string", isinstance(d["repo"], str), True)+check("payload/reason records the caller hint", "lang_guess" in d["reason"], True)+check_true("payload/detection is None when the hint decided it", d["detection"] is None)+check("payload/installed hint names its source",+ "Router(lang_guess=...)" in Router(lang_guess="ro").route(ROMANIAN, GENERIC)["reason"], True)+check_true("payload/repo points at the bundle", "convaiinnovations/laya" in d["repo"])++# ------------------------------------------------------------------ predict forwards it+class _FakeAgent:+ """Stands in for a loaded checkpoint so this suite stays offline and fast."""++ def __init__(self):+ self.calls = []++ def system_one(self, state, questions):+ self.calls.append((state, questions))+ return {"answers": {}, "usage": {"input_tokens": 0, "output_tokens": 0}}+++def _router_with_stub(**kwargs):+ """A Router whose `load` is stubbed, so `predict` exercises routing without weights."""+ r = Router(**kwargs)+ stub = _FakeAgent()++ def _load(name):+ r._agents[name] = stub+ return stub++ r.load = _load+ return r, stub+++r_p, stub = _router_with_stub(lang_guess="ro")+out = r_p.predict(ROMANIAN, GENERIC)+check("predict/uses the hint", out["routing"]["model"], "multilingual")+check("predict/forwards a per-call hint",+ r_p.predict(ROMANIAN, GENERIC, lang_guess="en")["routing"]["model"], "english")+check("predict/reaches the model", len(stub.calls), 2)+check_true("predict/passes the state through unchanged", stub.calls[0][0] == ROMANIAN)+check_true("predict/keeps the routing block",+ set(out["routing"]) >= {"model", "repo", "reason", "detection", "workflow"})++# ------------------------------------------------------------------ the helper itself+check("helper/None", _english_from_code(None), None)+check("helper/empty", _english_from_code(""), None)+check("helper/spaces", _english_from_code(" "), None)+check("helper/en", _english_from_code("en"), True)+check("helper/en_US", _english_from_code("en_US"), True)+check("helper/zh_CN", _english_from_code("zh_CN"), False)+check("helper/strips after the dot", _english_from_code("en.UTF-8"), True)+check("helper/only a dot", _english_from_code("."), None)++# the standalone-repo mapping is untouched+r_alone = Router(standalone_repos=True, lang_guess="ro")+check("standalone/hint still uses the standalone repo",+ r_alone.route(ROMANIAN, GENERIC)["repo"], "convaiinnovations/laya-multilingual")++# nothing without a hint moves+BEFORE = [("plain english", "I was charged twice and want a refund"),+ ("German with umlauts", "Mein Konto wurde zweimal belastet, bitte erstatten Sie"),+ ("Hindi", "यह एक हिंदी वाक्य है"),+ ("empty", ""),+ ("digits", "12345")]+for label, s in BEFORE:+ check("unchanged/" + label, r0.route(s, GENERIC)["model"], Router().route(s, GENERIC)["model"])+++print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))+for f in FAIL:+ print(" FAIL " + f)+sys.exit(1 if FAIL else 0)