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(rust): add routing sample

kevin-gatimu7b3b4bb8405e
diff --git a/laya-rust/samples/laya-routing/Cargo.toml b/laya-rust/samples/laya-routing/Cargo.toml
new file mode 100644
index 00000000..235c740a
--- /dev/null
+++ b/laya-rust/samples/laya-routing/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "laya-routing"
+version = "0.1.0"
+edition = "2024"
+description = "Combined LayaRouter / language detection / email cleaning / shortlist sample for the Rust SDK."
+license = "Apache-2.0"
+publish = false
+
+[[bin]]
+name = "laya-routing"
+path = "src/main.rs"
+
+[dependencies]
+laya = { package = "laya-onnx", path = "../.." }
+serde_json = "1"
diff --git a/laya-rust/samples/laya-routing/README.md b/laya-rust/samples/laya-routing/README.md
new file mode 100644
index 00000000..ec6b67a7
--- /dev/null
+++ b/laya-rust/samples/laya-routing/README.md
@@ -0,0 +1,220 @@
+# laya-routing
+
+**The combined routing sample.** It exercises everything the base Rust SDK does not cover on its
+own: language/script detection, `LayaRouter` routing decisions and predictions, email cleaning,
+and the embedding shortlist.
+
+## Output contract
+
+**This is the load-bearing part of this file.** This sample's stdout format is a stable contract
+(apart from timings, which never go to stdout — see below), so anyone changing it should keep this
+section up to date.
+
+- Flags: `--model-root <dir>` (default: the `LAYA_ONNX_ROOT` env var), `--download`, `--preload`,
+ `-h`/`--help`.
+- Exit codes: `0` ok, `1` a runtime or artifact error (bad model root, missing checkpoint file),
+ `2` bad usage (unknown flag, a flag missing its value).
+- Section headers, printed in this order: `== 1. Language detection ==`, `== 2. Routing decisions
+ ==`, `== 3. Router predict ==`, `== 4. Email cleaning ==`, `== 5. Shortlist ==`. A single blank
+ line separates each section's output from the next section's header (no blank line after the
+ last section).
+- All numbers are printed with exactly 4 decimals (`0.1234`), not fewer, not scientific notation.
+- **Section 1** (language detection), one line per state:
+ `{name:<22} script={script:<10} language={language or "-":<4} is_english={true|false}`
+- **Section 2** (routing decisions, `Route` only, nothing loaded), one line per case:
+ `{name:<26} -> {model subdir} ({reason})` — two spaces before the parenthesised reason.
+- **Section 3** (router predict), per email: a routed-to header, `[{lang}] routed to {subdir}:
+ {reason}`, then one line per answered question: ` {id:<18} {value}`, where `value` is the
+ choice label for a choice question, the score to 4 decimals for a score question, or the `P(true)`
+ probability to 4 decimals for a noul question (**not** `yes`/`no`).
+- **Section 4** (email cleaning): the cleaned body verbatim between a `--- cleaned ---` line and an
+ `--- end ---` line, then the `LayaPresets.Email()` answers in the same routed-header-plus-lines
+ format as section 3.
+- **Section 5** (shortlist): `kept {k} of {n}:`, then one line per kept label in rank order —
+ ` {label:<28} {score:.4}` — then `answer: {choice} ({probability:.4})`.
+- Timings go to **stderr only**, never stdout, and are not part of the diff.
+
+Sample inputs are copied verbatim from `laya-rust/tools/routing_cases.py`'s `SAMPLE_*` constants into
+[`src/main.rs`](src/main.rs) — no runtime JSON is read, so both samples read literally the same
+bytes, recorded once from Python as `laya-rust/tools/dump_routing_golden.py`'s `sample_inputs.json`.
+
+### Verified output
+
+Run against the three exported checkpoints, this sample's stdout is:
+
+```text
+== 1. Language detection ==
+english script=latin language=en is_english=true
+spanish_accent_stripped script=latin language=es is_english=false
+french script=latin language=fr is_english=false
+romanian script=latin language=ro is_english=false
+hindi script=devanagari language=- is_english=false
+arabic script=arabic language=- is_english=false
+japanese script=kana language=- is_english=false
+dict_state script=devanagari language=- is_english=false
+
+== 2. Routing decisions ==
+auto_english -> english (English Latin text)
+auto_hindi -> multilingual (non-Latin script (devanagari, 100% of letters); the English checkpoint cannot read it)
+auto_unknown_latin_romanian -> multilingual (Latin script but language looks like 'ro', not English)
+explicit_model_multilingual -> multilingual (explicit model='multilingual')
+explicit_lang_de -> multilingual (explicit lang='de')
+workflow_opt_in_customer_service -> typed-decisions (question ids match the 'customer_service' typed-decisions workflow)
+workflow_opt_in_off_by_default -> english (English Latin text)
+
+== 3. Router predict ==
+[en] routed to english: English Latin text
+ department billing
+ urgency 1.4400
+ churn_risk 0.8248
+ refund_requested 0.8430
+[hi] routed to multilingual: non-Latin script (devanagari, 74% of letters); the English checkpoint cannot read it
+ department billing
+ urgency 1.9072
+ churn_risk 0.1489
+ refund_requested 0.9966
+
+== 4. Email cleaning ==
+--- cleaned ---
+Hi team,
+
+I was charged twice for the Pro plan this month and the second charge still has not been refunded. This is the third time I have written about it -- please resolve this today or I will need to cancel the account.
+--- end ---
+[en] routed to english: English Latin text
+ category billing
+ is_spam 0.1318
+ is_phishing 0.1345
+ urgency 1.4932
+ needs_reply 0.1545
+
+== 5. Shortlist ==
+kept 20 of 40:
+ card_swallowed 0.5369
+ compromised_card 0.5229
+ cash_withdrawal_not_recognised 0.4926
+ card_payment_not_recognised 0.4672
+ automatic_top_up 0.4631
+ card_linking 0.4371
+ atm_support 0.3783
+ direct_debit_payment_not_recognised 0.3643
+ card_payment_wrong_exchange_rate 0.3472
+ balance_not_updated_after_bank_transfer 0.3320
+ card_not_working 0.3301
+ declined_card_payment 0.3205
+ card_payment_fee_charged 0.3154
+ card_acceptance 0.2983
+ exchange_rate 0.2915
+ card_delivery_estimate 0.2862
+ activate_my_card 0.2751
+ balance_not_updated_after_cheque_or_cash_deposit 0.2737
+ card_about_to_expire 0.2668
+ country_support 0.2631
+answer: card_swallowed (0.7885)
+```
+
+### Ambiguities resolved while implementing this contract
+
+The plan's contract text left two things unspecified:
+
+1. **`{lang}` in section 3/4's routed-to header** is a short, fixed, caller-chosen tag per input
+ (`"en"`, `"hi"`) — **not** derived from `RouteDecision.detection.language`. A non-Latin-script
+ decision (the Hindi email here) never gets a `language` guess at all: routing is decided by
+ script alone, so `detection.language` is `None`/`null` and there would be nothing to print.
+2. **The shortlist question's id** (used nowhere in `laya-rust/tools/routing_cases.py`, which only records
+ state/instructions/criteria, not a question id) is `"banking_intent"`.
+
+## Run it
+
+> **`--model-root` takes the export root, not one checkpoint's folder.** Point it at the
+> directory that *contains* `english/`, `multilingual/` and `typed-decisions/` (for example
+> `onnx/`), not at `onnx/multilingual`. This is the opposite of [`laya-sample`](../laya-sample/README.md)
+> and `laya-benchmark`, which take a single checkpoint's folder with `--model-dir` and reject
+> `--model-root`.
+
+Everything after the bare `--` is passed to the app; without it, `cargo run` tries to read
+`--model-root` itself. From the `laya-rust` directory:
+
+```bash
+cargo run --release -p laya-routing -- --model-root ../onnx
+cargo run --release -p laya-routing -- --model-root ../onnx --preload
+```
+
+Or set the environment variable once and leave out the flag:
+
+```powershell
+$env:LAYA_ONNX_ROOT = "C:\path\to\onnx"
+cargo run --release -p laya-routing
+```
+
+The root must contain one subdirectory per checkpoint used by the sample (`english/`,
+`multilingual/`, `typed-decisions/`), each holding `model.onnx`, `model.onnx.data`,
+`rl_agent_config.json` and `tokenizer/tokenizer.json` — the same layout `laya-sample` expects for a
+single checkpoint. `LayaOptions` has no "root" field of its own (only a single-checkpoint
+`model_directory`), so `--model-root` works by overriding the `LAYA_ONNX_ROOT` process environment
+variable that `ModelArtifacts::resolve` already reads per checkpoint.
+
+### Command-line options
+
+| Option | Effect |
+|---|---|
+| `--model-root <dir>` | Root directory holding every checkpoint subdirectory. Overrides `LAYA_ONNX_ROOT` for this process. |
+| `--download` | Fetch missing checkpoints from Hugging Face into the local cache, with per-file progress on stderr. |
+| `--preload` | Build and load every checkpoint up front (`LayaRouterOptions::preload`) instead of on first use. |
+| `-h`, `--help` | Print usage and exit 0. |
+
+| Exit code | Meaning |
+|---|---|
+| `0` | All five sections printed. |
+| `1` | A checkpoint's artifact could not be resolved, or another runtime error occurred. The resolver's message, which lists every location tried, is printed to stderr. |
+| `2` | Bad arguments: a flag missing its value, or an unrecognized argument. |
+
+See [laya-sample's README](../laya-sample/README.md#run-it) for the two path pitfalls that apply
+here too (quoting Windows paths in a POSIX shell, and `LAYA_ONNX_ROOT` needing to be absolute).
+
+`--download` has the same limitation as in `laya-sample`: it can't succeed today, because
+`convaiinnovations/laya` publishes PyTorch weights, not an ONNX export.
+
+## What each section demonstrates
+
+1. **Language detection** — `LanguageDetection::analyse` over ~8 states (English, accent-stripped
+ Spanish, French, Romanian, Hindi, Arabic, Japanese, and a `serde_json::json!` dict state),
+ showing detected script, best-effort Latin-language guess, and whether the English checkpoint
+ can be expected to read the text. No model is loaded for this section.
+2. **Routing decisions** — `LayaRouter::route` alone (never `predict`), so nothing is loaded.
+ Covers the full precedence ladder: script/language auto-detection, an explicit `model`, an
+ explicit `lang`, and the opt-in typed-decisions workflow match (shown both with
+ `auto_task_detection` on, where it decides the route, and off, where the match is still
+ detected but does not win).
+3. **Router predict** — the same four support questions (`department`, `urgency`, `churn_risk`,
+ `refund_requested`) asked of an English and a Hindi support email through one `LayaRouter` with
+ `max_loaded: 2`, so both checkpoints stay resident and neither request evicts the other.
+4. **Email cleaning** — a raw email with quoted history, a signature, and a confidentiality
+ disclaimer goes through `LayaEmail::clean_body` (printed verbatim) and `LayaEmail::state`, then
+ `LayaPresets::email(None)` through the same router.
+5. **Shortlist** — a 40-label banking-intent choice question is narrowed to the top 20 by cosine
+ similarity (`LayaShortlist::predict`, `DEFAULT_SHORTLIST_K`), using the demo hashing embedder in
+ [`hashing_embedder.rs`](src/hashing_embedder.rs) — **demo only, replace with a real embedding
+ model**. It is a deterministic, dependency-free, hashed-character-trigram bag-of-features
+ vector, ported bit-for-bit from `laya-rust/tools/hashing_embedder.py` (the same port used by the SDK's own
+ test suite at `tests/common/hashing_embedder.rs`), chosen only because every language
+ in this repo can reproduce it identically without a network call or a bi-encoder model.
+
+## Code walkthrough
+
+[`src/main.rs`](src/main.rs) follows the same shape as
+[`laya-sample`](../laya-sample/src/main.rs): hand-parsed arguments (no argument-parsing crate,
+because an unrecognized flag should fail loudly rather than be silently dropped), a `LayaRouter`
+built once up front, then one function per section. `timed()` wraps each of the three sections
+that actually call `predict`, printing wall-clock time to stderr only — the sample's stdout is a
+stable contract, and wall-clock time never could be part of it.
+
+## Troubleshooting
+
+Same as [laya-sample's table](../laya-sample/README.md#troubleshooting), with `--model-root` /
+`LAYA_ONNX_ROOT` in place of `--model-dir` / `LAYA_ONNX_DIR`. In particular:
+
+| Symptom | Cause |
+|---|---|
+| `Laya model artifact (~1.3 GB) not found` under `LAYA_ONNX_ROOT env var <root>\<checkpoint>` | `--model-root`/`LAYA_ONNX_ROOT` points at a directory that has no `<checkpoint>/model.onnx` subdirectory for the checkpoint being routed to. |
+| Devanagari, Arabic, or CJK text prints as `?` or boxes | The console code page or font can't display it. The answers aren't affected. Run `chcp 65001` or use Windows Terminal. |
+| First `predict` call takes noticeably longer | ORT session warm-up for that checkpoint. Pass `--preload` to pay this cost once, up front, for every checkpoint instead of on first use. |
diff --git a/laya-rust/samples/laya-routing/src/hashing_embedder.rs b/laya-rust/samples/laya-routing/src/hashing_embedder.rs
new file mode 100644
index 00000000..08076796
--- /dev/null
+++ b/laya-rust/samples/laya-routing/src/hashing_embedder.rs
@@ -0,0 +1,65 @@
+//! **Demo only — replace with a real embedding model.** Deterministic, dependency-free stand-in
+//! embedder used only so this sample can call [`laya::LayaShortlist::predict`] without a network
+//! call or an ONNX bi-encoder. Ports `tools/hashing_embedder.py` bit-for-bit (the same port also
+//! lives at `tests/common/hashing_embedder.rs` for the test suite) — see that file's
+//! docstring for the exact algorithm spec this follows step by step. It is a hashed
+//! character-trigram bag-of-features vector, chosen only because it is a pure function of the
+//! input text that is trivial to reproduce identically in every language and every SDK.
+//!
+//! Every step below is precision-sensitive:
+//! - Lowercasing uses full Unicode case mapping (`str::to_lowercase`), matching Python's
+//! `str.lower()` — not a per-UTF-16-unit simple mapping.
+//! - The 3-item sliding window is over Unicode scalar values (`char`, which in Rust already *is*
+//! a Unicode scalar value), matching Python's per-code-point iteration; an astral character
+//! (outside the BMP) is one window position, not two.
+//! - The window is re-encoded to UTF-8 on its own each time (not sliced out of one pre-encoded
+//! byte buffer), because a multi-byte character's encoding does not change with position, but
+//! slicing a shared buffer at the wrong byte offset would corrupt it.
+//! - The FNV-1a multiply wraps at 32 bits (`u32::wrapping_mul`), matching Python's explicit
+//! `& 0xFFFFFFFF`.
+
+use laya::error::Result as LayaResult;
+
+/// Output vector width.
+pub const DIM: usize = 64;
+
+const FNV_OFFSET_BASIS: u32 = 0x811c_9dc5;
+const FNV_PRIME: u32 = 0x0100_0193;
+
+/// 32-bit FNV-1a over raw bytes, wrapping like an unsigned 32-bit integer.
+fn fnv1a_32(data: &[u8]) -> u32 {
+ let mut hash = FNV_OFFSET_BASIS;
+ for &byte in data {
+ hash ^= u32::from(byte);
+ hash = hash.wrapping_mul(FNV_PRIME);
+ }
+ hash
+}
+
+fn embed_one(text: &str) -> Vec<f64> {
+ let mut vector = vec![0.0f64; DIM];
+ let padded: Vec<char> = format!(" {} ", text.to_lowercase()).chars().collect();
+ let n = padded.len();
+ // Padding alone is 4 characters, so `n >= 4` always and this subtraction never underflows;
+ // the guard is defensive documentation, not a reachable branch.
+ if n < 3 {
+ return vector;
+ }
+ for start in 0..=(n - 3) {
+ let window: String = padded[start..start + 3].iter().collect();
+ let hash = fnv1a_32(window.as_bytes());
+ let bucket = (hash % DIM as u32) as usize;
+ let sign = if (hash >> 31) & 1 == 0 { 1.0 } else { -1.0 };
+ vector[bucket] += sign;
+ }
+ vector
+}
+
+/// Embed a list of strings into one `(len(texts), 64)` matrix, in input order. See the module
+/// docs for the exact algorithm.
+///
+/// Returns [`laya::error::Result`] so it can be used directly wherever [`laya::LayaShortlist`]
+/// expects an `embed_fn` closure, even though this particular embedder never fails.
+pub fn embed(texts: &[String]) -> LayaResult<Vec<Vec<f64>>> {
+ Ok(texts.iter().map(|t| embed_one(t)).collect())
+}
diff --git a/laya-rust/samples/laya-routing/src/main.rs b/laya-rust/samples/laya-routing/src/main.rs
new file mode 100644
index 00000000..a98fe43b
--- /dev/null
+++ b/laya-rust/samples/laya-routing/src/main.rs
@@ -0,0 +1,632 @@
+//! Combined `LayaRouter` / language detection / email cleaning / shortlist sample. See the
+//! README's contract section before touching output formatting: this file's stdout is checked
+//! against the Python-recorded goldens generated from `tools/routing_cases.py` (apart from
+//! timings, which go to stderr).
+//!
+//! Five sections, run in order:
+//! 1. Language detection over a handful of states — `LanguageDetection::analyse`, no engine.
+//! 2. Routing decisions — `LayaRouter::route`, no engine loaded.
+//! 3. `LayaRouter::predict` on an English and a Hindi support email (`MaxLoaded=2`).
+//! 4. `LayaEmail::clean_body` / `LayaEmail::state` on a raw email, then `LayaPresets::email()`
+//! through the same router.
+//! 5. `LayaShortlist::predict` over a 40-intent banking choice question, with the demo hashing
+//! embedder (see `hashing_embedder.rs`) standing in for a real embedding model.
+//!
+//! All sample inputs are copied verbatim from `tools/routing_cases.py`'s `SAMPLE_*` constants —
+//! no runtime JSON is read. See `tools/dump_routing_golden.py`'s `sample_inputs.json` for the
+//! same values recorded from Python.
+
+mod hashing_embedder;
+
+use laya::{
+ Answer, ArtifactDownloadProgress, LayaEmail, LayaError, LayaOptions, LayaPresets, LayaResult,
+ LayaRouter, LayaRouterOptions, LayaShortlist, Question, QuestionSet, Result as LayaResultT,
+ laya_shortlist::DEFAULT_SHORTLIST_K,
+};
+use serde_json::{Value, json};
+use std::time::Instant;
+
+const USAGE: &str = "\
+Usage: cargo run --release -p laya-routing -- [options]
+
+ --model-root <dir> Root directory holding one subdirectory per checkpoint
+ (english/, multilingual/, typed-decisions/). Overrides
+ LAYA_ONNX_ROOT for this process.
+ --download Fetch missing checkpoints from Hugging Face into the local cache.
+ --preload Build and load every checkpoint up front instead of on first use.
+ -h, --help Print this message.
+
+With no options the artifact root is resolved from LAYA_ONNX_ROOT.";
+
+fn main() {
+ std::process::exit(run());
+}
+
+fn run() -> i32 {
+ let args: Vec<String> = std::env::args().skip(1).collect();
+
+ let mut model_root: Option<String> = None;
+ let mut allow_download = false;
+ let mut preload = false;
+
+ // Parsed by hand, like laya-sample: an unrecognised argument is rejected with exit code 2
+ // rather than silently ignored.
+ let mut i = 0;
+ while i < args.len() {
+ match args[i].as_str() {
+ "--model-root" => {
+ if i + 1 >= args.len() {
+ eprintln!("--model-root needs a directory.");
+ eprintln!("{USAGE}");
+ return 2;
+ }
+ i += 1;
+ model_root = Some(args[i].clone());
+ }
+ "--download" => allow_download = true,
+ "--preload" => preload = true,
+ "-h" | "--help" => {
+ println!("{USAGE}");
+ return 0;
+ }
+ other => {
+ eprintln!("Unrecognised argument: {other}");
+ eprintln!("{USAGE}");
+ return 2;
+ }
+ }
+ i += 1;
+ }
+
+ // `LayaOptions` has no "root" field of its own (only a single-checkpoint `model_directory`),
+ // so `--model-root` is applied by overriding the `LAYA_ONNX_ROOT` env var that
+ // `ModelArtifacts::resolve` already reads per checkpoint. `set_var` is `unsafe` on this
+ // edition because it is process-global and not thread-safe with a concurrent `getenv`; this
+ // happens once, before any threads exist, so that hazard does not apply here.
+ if let Some(root) = &model_root {
+ unsafe {
+ std::env::set_var("LAYA_ONNX_ROOT", root);
+ }
+ }
+
+ let mut engine_options = LayaOptions::new();
+ engine_options.allow_download = allow_download;
+ if allow_download {
+ engine_options.download_progress =
+ Some(std::sync::Arc::new(|p: ArtifactDownloadProgress| {
+ eprintln!(
+ " {}: {}/{}",
+ p.file_name,
+ p.bytes_received,
+ p.total_bytes
+ .map(|b| b.to_string())
+ .unwrap_or_else(|| "?".to_string())
+ );
+ }));
+ }
+
+ let router = match LayaRouter::new(LayaRouterOptions {
+ engine_options,
+ max_loaded: 2,
+ preload,
+ ..LayaRouterOptions::default()
+ }) {
+ Ok(router) => router,
+ Err(e) => {
+ report_error(&e, allow_download);
+ return 1;
+ }
+ };
+
+ section1_language_detection();
+ if let Err(e) = section2_routing_decisions() {
+ report_error(&e, allow_download);
+ return 1;
+ }
+ if let Err(e) = section3_router_predict(&router) {
+ report_error(&e, allow_download);
+ return 1;
+ }
+ if let Err(e) = section4_email_cleaning(&router) {
+ report_error(&e, allow_download);
+ return 1;
+ }
+ if let Err(e) = section5_shortlist(&router) {
+ report_error(&e, allow_download);
+ return 1;
+ }
+
+ 0
+}
+
+/// A directory that exists but is missing a file, or does not exist at all, is a
+/// misconfiguration like any other, and the resolver's message already explains it better than a
+/// stack trace would (see laya-sample's `main.rs` for the same match).
+fn report_error(e: &LayaError, allow_download: bool) {
+ eprintln!("{e}");
+ if matches!(
+ e,
+ LayaError::ArtifactsNotFound { .. }
+ | LayaError::DirectoryNotFound { .. }
+ | LayaError::MissingFile { .. }
+ ) && !allow_download
+ {
+ eprintln!();
+ eprintln!("Point --model-root or LAYA_ONNX_ROOT at a directory holding every checkpoint.");
+ }
+}
+
+// ============================================================================ section 1
+
+/// ~8 states covering English, accent-stripped Spanish, French, Romanian, Hindi, Arabic,
+/// Japanese and a dict state. Copied verbatim from `tools/routing_cases.py`'s
+/// `SAMPLE_DETECTION_STATES`.
+fn section1_language_detection() {
+ println!("== 1. Language detection ==");
+
+ let states: Vec<(&str, Value)> = vec![
+ (
+ "english",
+ json!("The customer was charged twice this month and wants a refund."),
+ ),
+ (
+ "spanish_accent_stripped",
+ json!("El cliente fue cobrado dos veces y quiere que le devuelvan el dinero"),
+ ),
+ (
+ "french",
+ json!("Le client a été facturé deux fois et demande un remboursement."),
+ ),
+ (
+ "romanian",
+ json!("Am fost taxat de două ori pentru factura din luna martie și vreau banii"),
+ ),
+ (
+ "hindi",
+ json!("ग्राहक से दो बार शुल्क लिया गया और वह धनवापसी चाहता है।"),
+ ),
+ (
+ "arabic",
+ json!("تم خصم المبلغ مرتين من العميل ويريد استرداد الأموال"),
+ ),
+ (
+ "japanese",
+ json!("お客様は二重に請求されたため返金を希望しています。"),
+ ),
+ (
+ "dict_state",
+ json!({"subject": "Double charge", "body": "मुझसे दो बार शुल्क लिया गया"}),
+ ),
+ ];
+
+ for (name, state) in &states {
+ let analysis = laya::LanguageDetection::analyse(state);
+ let language = analysis.language.as_deref().unwrap_or("-");
+ println!(
+ "{name:<22} script={script:<10} language={language:<4} is_english={is_english}",
+ script = analysis.script,
+ is_english = analysis.is_english,
+ );
+ }
+}
+
+// ============================================================================ section 2
+
+/// Question ids of the `customer_service` typed-decisions workflow, used only for the two
+/// workflow-detection rows. Matches `laya::laya_router`'s private `TYPED_DECISION_WORKFLOWS` /
+/// Python's `_TD_IDS["customer_service"]`.
+const CUSTOMER_SERVICE_IDS: &[&str] =
+ &["action", "category", "churn_risk", "needs_human", "urgency"];
+
+fn workflow_questions() -> LayaResultT<QuestionSet> {
+ let mut questions = QuestionSet::new();
+ for id in CUSTOMER_SERVICE_IDS {
+ questions.insert(*id, Question::noul("x", Value::Null, Value::Null))?;
+ }
+ Ok(questions)
+}
+
+/// Routing-decision examples (`Route` only, nothing loaded), including explicit model/lang and
+/// opt-in workflow detection. Copied verbatim from `tools/routing_cases.py`'s
+/// `SAMPLE_ROUTING_DECISIONS`.
+fn section2_routing_decisions() -> LayaResultT<()> {
+ println!();
+ println!("== 2. Routing decisions ==");
+
+ let workflow_ids = workflow_questions()?;
+
+ struct Case<'a> {
+ name: &'a str,
+ auto_task_detection: bool,
+ state: Value,
+ questions: Option<&'a QuestionSet>,
+ model: Option<&'a str>,
+ lang: Option<&'a str>,
+ }
+
+ let cases = [
+ Case {
+ name: "auto_english",
+ auto_task_detection: false,
+ state: json!("Please refund the duplicate charge on invoice 4411 today."),
+ questions: None,
+ model: None,
+ lang: None,
+ },
+ Case {
+ name: "auto_hindi",
+ auto_task_detection: false,
+ state: json!("मुझसे दो बार शुल्क लिया गया, कृपया रिफंड करें।"),
+ questions: None,
+ model: None,
+ lang: None,
+ },
+ Case {
+ name: "auto_unknown_latin_romanian",
+ auto_task_detection: false,
+ state: json!("Gătește-mi o rețetă de sarmale de post pentru mâine."),
+ questions: None,
+ model: None,
+ lang: None,
+ },
+ Case {
+ name: "explicit_model_multilingual",
+ auto_task_detection: false,
+ state: json!("anything at all"),
+ questions: None,
+ model: Some("multilingual"),
+ lang: None,
+ },
+ Case {
+ name: "explicit_lang_de",
+ auto_task_detection: false,
+ state: json!("hello there"),
+ questions: None,
+ model: None,
+ lang: Some("de"),
+ },
+ Case {
+ name: "workflow_opt_in_customer_service",
+ auto_task_detection: true,
+ state: json!({"body": "I was charged twice"}),
+ questions: Some(&workflow_ids),
+ model: None,
+ lang: None,
+ },
+ Case {
+ name: "workflow_opt_in_off_by_default",
+ auto_task_detection: false,
+ state: json!({"body": "I was charged twice"}),
+ questions: Some(&workflow_ids),
+ model: None,
+ lang: None,
+ },
+ ];
+
+ for case in &cases {
+ let router = LayaRouter::new(LayaRouterOptions {
+ auto_task_detection: case.auto_task_detection,
+ ..LayaRouterOptions::default()
+ })?;
+ let decision = router.route(&case.state, case.questions, case.model, None, case.lang)?;
+ println!(
+ "{name:<26} -> {subdir} ({reason})",
+ name = case.name,
+ subdir = decision.model.subdir(),
+ reason = decision.reason,
+ );
+ }
+
+ Ok(())
+}
+
+// ============================================================================ section 3 / 4 shared
+
+/// Prints one `LayaResult` from a router `predict` call in the shared per-answer format used by
+/// sections 3 and 4: a routed-to header, then one indented line per question.
+///
+/// `tag` is a short caller-chosen label for the input's language (e.g. `"en"`, `"hi"`) — it is
+/// not derived from `RouteDecision::detection`, because a non-Latin-script decision (Hindi, in
+/// this sample) carries no `language` guess at all (script detection alone routes it), so there
+/// would be nothing to print for that case. The sample uses the same fixed tags per input as
+/// `tools/routing_cases.py`'s `SAMPLE_*` entries.
+/// Runs `f`, printing its wall-clock time to stderr (never stdout — see the README's contract:
+/// stdout must diff identically against the Python-recorded golden, and timings never will).
+fn timed<T>(label: &str, f: impl FnOnce() -> LayaResultT<T>) -> LayaResultT<T> {
+ let clock = Instant::now();
+ let result = f();
+ eprintln!(
+ "[timing] {label}: {:.0} ms",
+ clock.elapsed().as_secs_f64() * 1000.0
+ );
+ result
+}
+
+fn print_routed_result(tag: &str, result: &LayaResult) {
+ let decision = result
+ .routing()
+ .expect("router predict always records a routing decision");
+ println!(
+ "[{tag}] routed to {subdir}: {reason}",
+ subdir = decision.model.subdir(),
+ reason = decision.reason,
+ );
+ for id in result.ids() {
+ let answer = &result[id.as_str()];
+ let value = match answer {
+ Answer::Choice(choice) => choice.choice.clone(),
+ Answer::Score(score) => format!("{:.4}", score.score),
+ Answer::Noul(noul) => format!("{:.4}", noul.probability),
+ };
+ println!(" {id:<18} {value}");
+ }
+}
+
+// ============================================================================ section 3
+
+/// Copied verbatim from `tools/routing_cases.py`'s `SAMPLE_SUPPORT_QUESTIONS`.
+fn support_questions() -> LayaResultT<QuestionSet> {
+ QuestionSet::new()
+ .with(
+ "department",
+ Question::choice(
+ "Which department should handle this request?",
+ [
+ ("billing", "invoices, payments, refunds"),
+ ("technical", "bugs, outages, system errors"),
+ ("sales", "pricing, new contracts"),
+ ("other", "everything else"),
+ ],
+ )?,
+ )?
+ .with(
+ "urgency",
+ Question::score(
+ "How urgent is this request?",
+ ["not urgent", "soon", "critical deadline or blocking issue"],
+ )?,
+ )?
+ .with(
+ "churn_risk",
+ Question::noul(
+ "Does the user threaten to cancel or leave?",
+ Value::Null,
+ Value::Null,
+ ),
+ )?
+ .with(
+ "refund_requested",
+ Question::noul(
+ "Does the user explicitly request a refund?",
+ Value::Null,
+ Value::Null,
+ ),
+ )
+}
+
+/// The same support questions on an English and a Hindi email, showing which checkpoint
+/// answered and the answers (`MaxLoaded=2`, so both stay resident). Copied verbatim from
+/// `tools/routing_cases.py`'s `SAMPLE_SUPPORT_EMAIL_EN` / `SAMPLE_SUPPORT_EMAIL_HI`.
+fn section3_router_predict(router: &LayaRouter) -> LayaResultT<()> {
+ println!();
+ println!("== 3. Router predict ==");
+
+ let questions = support_questions()?;
+
+ let english = json!({
+ "from": "[email protected]",
+ "subject": "Duplicate charge on invoice #4411",
+ "body": "Hi, we were billed twice for March. Please refund the duplicate today \
+ or we will cancel our plan.",
+ });
+ let result = timed("section 3 english", || {
+ router.predict(english, &questions, None, None, None)
+ })?;
+ print_routed_result("en", &result);
+
+ // Written as escapes deliberately (see `tools/routing_cases.py`'s note on the same pitfall):
+ // a hand-retyped Devanagari string is an easy place to silently swap a similar-looking
+ // character and produce a "parity bug" that is really a transcription error.
+ let hindi = json!({
+ "from": "[email protected]",
+ "subject": "चालान में दोहरा शुल्क",
+ "body": "मार्च का बिल दो बार लिया गया, कृपया रिफंड करें।",
+ });
+ let result = timed("section 3 hindi", || {
+ router.predict(hindi, &questions, None, None, None)
+ })?;
+ print_routed_result("hi", &result);
+
+ Ok(())
+}
+
+// ============================================================================ section 4
+
+/// A raw email with quoted history, signature and disclaimer, run through
+/// `LayaEmail::clean_body` -> `LayaEmail::state` -> `LayaPresets::email()` through the router.
+/// Copied verbatim from `tools/routing_cases.py`'s `SAMPLE_RAW_EMAIL_*`.
+fn section4_email_cleaning(router: &LayaRouter) -> LayaResultT<()> {
+ println!();
+ println!("== 4. Email cleaning ==");
+
+ let subject = "Re: Refund for invoice 4411";
+ let sender = "[email protected]";
+ let body = "Hi team,\n\n\
+ I was charged twice for the Pro plan this month and the second charge still has \
+ not been refunded. This is the third time I have written about it -- please \
+ resolve this today or I will need to cancel the account.\n\n\
+ Best regards,\n\
+ Priya Sharma\n\
+ Sent from my iPhone\n\n\
+ This email and any files transmitted with it are confidential and intended \
+ solely for the use of the individual or entity to whom they are addressed. If \
+ you have received this email in error please notify the sender.\n\n\
+ On Tue, Sep 22, 2026 at 9:14 AM, Support <[email protected]> wrote:\n\
+ > Hi Priya, thanks for reaching out, we are looking into it.\n\
+ > - Support Team\n";
+
+ let cleaned = LayaEmail::clean_body(body, laya::laya_email::DEFAULT_MAX_CHARS);
+ println!("--- cleaned ---");
+ println!("{cleaned}");
+ println!("--- end ---");
+
+ let state = LayaEmail::state(subject, body, Some(sender), true, std::iter::empty());
+ let questions = LayaPresets::email(None::<[(&str, &str); 0]>);
+ let result = timed("section 4 email", || {
+ router.predict(state, &questions, None, None, None)
+ })?;
+ print_routed_result("en", &result);
+
+ Ok(())
+}
+
+// ============================================================================ section 5
+
+/// A 40-intent banking choice question through `LayaShortlist::predict` with the hashing
+/// embedder (demo only — replace with a real embedding model). Copied verbatim from
+/// `tools/routing_cases.py`'s `SAMPLE_BANKING_*`.
+///
+/// The question id (`"banking_intent"`) is not specified by the Python corpus (which only
+/// records the state/instructions/criteria, not a question id); this sample uses
+/// `"banking_intent"` as a fixed label for its per-answer output line.
+fn section5_shortlist(router: &LayaRouter) -> LayaResultT<()> {
+ println!();
+ println!("== 5. Shortlist ==");
+
+ const QUESTION_ID: &str = "banking_intent";
+ const CRITERIA: &[(&str, &str)] = &[
+ ("activate_my_card", "turn on a newly received card"),
+ ("age_limit", "minimum or maximum age to use the service"),
+ (
+ "apple_pay_or_google_pay",
+ "adding the card to a mobile wallet",
+ ),
+ ("atm_support", "which ATMs the card works at"),
+ ("automatic_top_up", "automatically topping up the balance"),
+ (
+ "balance_not_updated_after_bank_transfer",
+ "a bank transfer is missing from the balance",
+ ),
+ (
+ "balance_not_updated_after_cheque_or_cash_deposit",
+ "a deposit is missing from the balance",
+ ),
+ ("beneficiary_not_allowed", "cannot add a payment recipient"),
+ ("cancel_transfer", "wants to cancel a transfer already sent"),
+ (
+ "card_about_to_expire",
+ "the card is close to its expiry date",
+ ),
+ ("card_acceptance", "where the card is accepted"),
+ ("card_arrival", "asking when a new card will arrive"),
+ (
+ "card_delivery_estimate",
+ "asking how long delivery will take",
+ ),
+ ("card_linking", "linking a card to the account"),
+ ("card_not_working", "the card is declined or not working"),
+ (
+ "card_payment_fee_charged",
+ "an unexpected fee was charged on a card payment",
+ ),
+ (
+ "card_payment_not_recognised",
+ "a card payment the customer does not recognise",
+ ),
+ (
+ "card_payment_wrong_exchange_rate",
+ "the exchange rate used was wrong",
+ ),
+ ("card_swallowed", "the ATM kept the card"),
+ (
+ "cash_withdrawal_charge",
+ "an unexpected charge for a cash withdrawal",
+ ),
+ (
+ "cash_withdrawal_not_recognised",
+ "a cash withdrawal the customer does not recognise",
+ ),
+ ("change_pin", "wants to change the PIN"),
+ ("compromised_card", "the card may have been compromised"),
+ (
+ "contactless_not_working",
+ "contactless payment is not working",
+ ),
+ ("country_support", "which countries the service supports"),
+ ("declined_card_payment", "a card payment was declined"),
+ ("declined_cash_withdrawal", "a cash withdrawal was declined"),
+ ("declined_transfer", "a transfer was declined"),
+ (
+ "direct_debit_payment_not_recognised",
+ "a direct debit the customer does not recognise",
+ ),
+ (
+ "disposable_card_limits",
+ "limits on a disposable virtual card",
+ ),
+ (
+ "edit_personal_details",
+ "wants to edit name, address or other personal details",
+ ),
+ ("exchange_charge", "a fee charged for currency exchange"),
+ ("exchange_rate", "asking what the current exchange rate is"),
+ ("exchange_via_app", "exchanging currency inside the app"),
+ (
+ "extra_charge_on_statement",
+ "an unexplained extra charge on the statement",
+ ),
+ ("failed_transfer", "a transfer failed"),
+ (
+ "fiat_currency_support",
+ "which regular currencies are supported",
+ ),
+ (
+ "get_disposable_virtual_card",
+ "wants a disposable virtual card",
+ ),
+ ("get_physical_card", "wants a physical card"),
+ ("getting_spare_card", "wants a spare or backup card"),
+ ];
+
+ let questions = QuestionSet::new().with(
+ QUESTION_ID,
+ Question::choice(
+ "What is the customer's banking intent?",
+ CRITERIA.iter().map(|&(label, desc)| (label, desc)),
+ )?,
+ )?;
+
+ let state =
+ json!("I tried to withdraw cash from the ATM but it kept the card and gave me no money.");
+
+ let result = timed("section 5 shortlist", || {
+ LayaShortlist::predict(
+ router,
+ state,
+ &questions,
+ hashing_embedder::embed,
+ DEFAULT_SHORTLIST_K,
+ )
+ })?;
+
+ let info = result
+ .shortlist()
+ .and_then(|m| m.get(QUESTION_ID))
+ .expect("banking_intent was shortlisted");
+ println!("kept {} of {}:", info.k, info.n);
+ let scores = info
+ .scores
+ .as_ref()
+ .expect("40 options > k=20, so this question was ranked, not passed through");
+ for (label, score) in info.labels.iter().zip(scores) {
+ println!(" {label:<28} {score:.4}");
+ }
+
+ let answer = result[QUESTION_ID]
+ .as_choice()
+ .expect("banking_intent is a choice question");
+ let probability = answer.probability(&answer.choice).unwrap_or(0.0);
+ println!("answer: {} ({:.4})", answer.choice, probability);
+
+ Ok(())
+}