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(router): accept a caller-supplied language hint (#211)

PerryLinkee8369ead3da
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3a81a306..2b1536b6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -49,6 +49,7 @@ jobs:
python tests/test_shortlist.py
python tests/test_decision_model.py
python tests/test_packaging.py
+ python tests/test_lang_guess.py
- name: Email cleaning tests
run: python tests/test_email.py
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 86e93792..13faadb6 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -44,6 +44,7 @@ jobs:
python tests/test_shortlist.py
python tests/test_decision_model.py
python tests/test_packaging.py
+ python tests/test_lang_guess.py
- name: Build
run: python -m build
diff --git a/README.md b/README.md
index 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.py
index 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_guess
self._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)
+
# ------------------------------------------------------------------ routing
def 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.py
new file mode 100644
index 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)