| Title: | Local Laya Decision Models via Rust |
|---|---|
| Description: | Run Laya System 1 decision models (typed choice, score and yes/no questions with calibrated probabilities) locally from R, through the laya-onnx Rust crate and ONNX Runtime. No Python or server is required at prediction time. |
| Authors: | G. Nono Ghislain [aut, cre], Convai Innovations [cph] (laya-onnx Rust crate and the test fixtures derived from its golden tests), Microsoft Corporation [cph] (ONNX Runtime), Authors of the dependency Rust crates [cph] (see LICENSE.note) |
| Maintainer: | G. Nono Ghislain <[email protected]> |
| License: | Apache License (>= 2) |
| Version: | 0.1.0 |
| Built: | 2026-11-17 13:27:23 UTC |
| Source: | https://github.com/gueyenono/layaR |
Accepts a question set in the Python SDK's format, so question sets can be
shared between Python and R: an R list, a JSON string, or the path to a
.json file.
as_laya_questions(x, ...)as_laya_questions(x, ...)
x |
A |
... |
Unused. |
A laya_questions object.
as_laya_questions('{ "urgency": {"type": "score", "instructions": "How urgent?", "criteria": ["low", "high"]} }')as_laya_questions('{ "urgency": {"type": "score", "instructions": "How urgent?", "criteria": ["low", "high"]} }')
Asks the same questions about every row of a data frame and adds the answers as new columns, one or more per question:
laya_annotate( data, questions, state, engine = laya_default_engine(), ..., prefix = "", confidence = TRUE, probabilities = FALSE )laya_annotate( data, questions, state, engine = laya_default_engine(), ..., prefix = "", confidence = TRUE, probabilities = FALSE )
data |
A data frame or tibble. A tibble stays a tibble. |
questions |
A question set ( |
state |
The column or columns the model reads. With one column, its
text is the state as is. With several, each row becomes a structured
state such as |
engine |
A |
... |
Passed to |
prefix |
A prefix for the new column names, for example |
confidence |
Add a |
probabilities |
Add a |
a choice question gives a factor whose levels are the options, in order;
a score question gives the expected level (a number from 0 to the number of levels minus one);
a yes/no question gives the probability that the statement is true.
With confidence = TRUE each answer also gets a <id>_confidence column.
With min_confidence (passed in ...), each gated answer also gets a
logical <id>_abstained column. The answer is kept either way; filter on
the column to drop low-confidence answers. The gate compares the threshold
with each answer's answer_confidence (for a choice question, the chosen
option's probability), which can differ from the <id>_confidence column.
data with the new columns. Rows whose state columns are all
missing get NA answers instead of a prediction.
laya_predict_batch() for the full results.
if (laya_model_available()) { tickets <- data.frame( subject = c("Duplicate charge", "App crashes on login"), body = c("We were billed twice. Refund it or we cancel.", "Since the update I can't log in.") ) qs <- laya_questions( department = laya_choice("Which department should handle this?", billing = "invoices, refunds", technical = "bugs, outages"), churn_risk = laya_noul("Does the customer threaten to cancel?") ) laya_annotate(tickets, qs, state = c("subject", "body")) }if (laya_model_available()) { tickets <- data.frame( subject = c("Duplicate charge", "App crashes on login"), body = c("We were billed twice. Refund it or we cancel.", "Since the update I can't log in.") ) qs <- laya_questions( department = laya_choice("Which department should handle this?", billing = "invoices, refunds", technical = "bugs, outages"), churn_risk = laya_noul("Does the customer threaten to cancel?") ) laya_annotate(tickets, qs, state = c("subject", "body")) }
min_confidence
A per-bucket min_confidence gives a threshold per question type and
option count. These are the valid names; "default" also applies to every
bucket not named.
laya_bucket_keys()laya_bucket_keys()
A character vector.
laya_bucket_keys()laya_bucket_keys()
Removes quoted replies, reply headers, signatures and legal disclaimers so
the model reads only the sender's message. A port of the Python SDK's
clean_email_body(), with the same results.
laya_clean_email(body, max_chars = 3000)laya_clean_email(body, max_chars = 3000)
body |
A character vector of email bodies. |
max_chars |
The most characters to keep, applied after cleaning.
Cleaning only looks at the first |
A character vector the same length as body.
laya_clean_email(paste( "Please refund the duplicate charge.", "", "Best,", "Ana", "", "On Mon, 3 Mar 2025 at 10:00, Support <[email protected]> wrote:", "> How can we help?", sep = "\n" ))laya_clean_email(paste( "Please refund the duplicate charge.", "", "Best,", "Ana", "", "On Mon, 3 Mar 2025 at 10:00, Support <[email protected]> wrote:", "> How can we help?", sep = "\n" ))
Returns the engine for checkpoint, loading it on first use and caching
it for the rest of the session. Prediction functions use this when no
engine is given.
laya_default_engine(checkpoint = getOption("layaR.checkpoint", "multilingual"))laya_default_engine(checkpoint = getOption("layaR.checkpoint", "multilingual"))
checkpoint |
The checkpoint; defaults to the |
A laya_engine object.
if (laya_model_available()) laya_default_engine()if (laya_model_available()) laya_default_engine()
Reads each state's text (string values only; keys are ignored) and reports
its dominant script, a best-effort language guess for Latin-script text,
and whether the English checkpoint can read it. Use it to pick a
checkpoint: "english" when is_english is TRUE, "multilingual"
otherwise. No model is needed.
laya_detect_language(states)laya_detect_language(states)
states |
A character vector of texts, a single state (a named list), a list of states, or a data frame (one state per row). |
A structured state that reads English as a whole is also checked field by
field and line by line, so a short message in another language next to a
long English stack trace still counts as non-English (mixed_segment
shows the part that decided it).
A data frame with one row per state and columns script,
language (an ISO 639-1 code, or NA when undecided or not Latin),
is_english, language_undecided, diacritic_rate,
non_latin_fraction, mixed_segment and script_profile (a list-column
of named numeric vectors: the share of letters in each script).
laya_detect_language(c( "Please refund the duplicate charge", "मार्च का बिल दो बार लिया गया", "glömt lösenord" )) laya_detect_language(list( subject = "Refund", body = "Hola, me cobraron dos veces. \u00bfPueden devolverme el dinero?" ))laya_detect_language(c( "Please refund the duplicate charge", "मार्च का बिल दो बार लिया गया", "glömt lösenord" )) laya_detect_language(list( subject = "Refund", body = "Hola, me cobraron dos veces. \u00bfPueden devolverme el dinero?" ))
Downloads an exported ONNX checkpoint (1.3 to 1.6 GB) from a Hugging Face
repository into laya_model_path(). Files go to a staging folder first,
so an interrupted download resumes where it stopped on the next call and
a partial download is never mistaken for a model.
laya_download_model( checkpoint = c("multilingual", "english", "typed-decisions"), repo = getOption("layaR.model_repo", "gueyenono/laya-onnx"), revision = "main", subfolder = NULL, token = Sys.getenv("HF_TOKEN"), overwrite = FALSE, ask = interactive() )laya_download_model( checkpoint = c("multilingual", "english", "typed-decisions"), repo = getOption("layaR.model_repo", "gueyenono/laya-onnx"), revision = "main", subfolder = NULL, token = Sys.getenv("HF_TOKEN"), overwrite = FALSE, ask = interactive() )
checkpoint |
Which checkpoint to download. |
repo |
The Hugging Face repository, |
revision |
Branch, tag or commit of the repository. |
subfolder |
Folder of the checkpoint inside the repository. |
token |
A Hugging Face access token for private or gated
repositories; defaults to the |
overwrite |
Replace an installed model? |
ask |
Ask for confirmation before downloading? Defaults to |
The Laya authors publish PyTorch weights only, so layaR downloads from
gueyenono/laya-onnx, which holds ONNX exports of the three upstream
checkpoints (unchanged weights, Apache-2.0). A repository without an
export gives a laya_error_model_not_published error that explains how
to export one and add it with laya_import_model().
The model's path, invisibly.
laya_models(), laya_import_model()
## Not run: laya_download_model("multilingual") ## End(Not run)## Not run: laya_download_model("multilingual") ## End(Not run)
Builds the state the Python SDK's email_state() builds: subject, a
cleaned body, from when a sender is given, then any extra fields. Pass
the result to laya_predict(), or use it with the "email" preset
(laya_preset()).
laya_email_state( subject, body, sender = NULL, ..., clean = TRUE, max_chars = 3000 )laya_email_state( subject, body, sender = NULL, ..., clean = TRUE, max_chars = 3000 )
subject, body
|
The email's subject and body, single strings. |
sender |
Optional sender address, stored in the state's |
... |
Extra named fields to add to the state (for example
|
clean |
Clean the body with |
max_chars |
Passed to |
A named list, ready to use as a state.
laya_email_state( subject = "Duplicate charge", body = "We were billed twice.\n\n-- \nAna Muller\nAcme Corp", sender = "[email protected]", ticket_id = 4411L )laya_email_state( subject = "Duplicate charge", body = "We were billed twice.\n\n-- \nAna Muller\nAcme Corp", sender = "[email protected]", ticket_id = 4411L )
Loads an exported ONNX checkpoint into memory (about 1 to 1.5 GB of RAM)
and returns an engine to pass to laya_predict() and friends. Create one
and reuse it: loading takes several seconds, predictions are fast.
laya_engine( checkpoint = c("multilingual", "english", "typed-decisions"), model_dir = NULL, intra_op_threads = getOption("layaR.threads"), inter_op_threads = NULL, lang_temperatures = NULL )laya_engine( checkpoint = c("multilingual", "english", "typed-decisions"), model_dir = NULL, intra_op_threads = getOption("layaR.threads"), inter_op_threads = NULL, lang_temperatures = NULL )
checkpoint |
Which checkpoint to load: |
model_dir |
Path to an exported checkpoint directory. Overrides the
lookup by |
intra_op_threads, inter_op_threads
|
ONNX Runtime thread counts.
|
lang_temperatures |
Optional per-language calibration overrides, a
named list such as
|
Most code never needs this: the prediction functions default to
laya_default_engine(), which loads the checkpoint named by the
layaR.checkpoint option ("multilingual" by default) on first use and
keeps it for the session.
Engines can't be sent to other processes. An engine restored with
readRDS(), or used in a PSOCK worker (parallel::makePSOCKcluster(),
future::multisession), reconnects to its model directory on first use,
which loads the model again in that process (another 1 to 1.5 GB each).
Engines don't work across fork() (parallel::mclapply(),
future::multicore): ONNX Runtime's thread pools don't survive it, so a
forked child could hang. Using an engine in a forked child raises a
laya_error_forked error instead. A single engine already runs one forward
pass on several cores; for more throughput use laya_predict_batch(), or
PSOCK workers that each load their own engine.
A laya_engine object.
laya_predict(), laya_engine_info(), laya_engine_close()
if (laya_model_available()) { engine <- laya_engine("multilingual", intra_op_threads = 2) engine laya_engine_close(engine) }if (laya_model_available()) { engine <- laya_engine("multilingual", intra_op_threads = 2) engine laya_engine_close(engine) }
laya_engine_info() reports what an engine loaded: checkpoint, ONNX
layout, file paths, sequence budgets (max_len, head_max_len) and
calibration temperatures. laya_engine_close() frees the model's memory
right away instead of waiting for garbage collection; the engine can't be
used afterwards.
laya_engine_info(engine) laya_engine_close(engine)laya_engine_info(engine) laya_engine_close(engine)
engine |
A |
laya_engine_info() returns a list; laya_engine_close() returns
engine, invisibly.
if (laya_model_available()) { engine <- laya_engine() str(laya_engine_info(engine), max.level = 1) laya_engine_close(engine) }if (laya_model_available()) { engine <- laya_engine() str(laya_engine_info(engine), max.level = 1) laya_engine_close(engine) }
Adds a checkpoint exported with Laya's export_onnx.py (or downloaded by
another tool) to layaR's model root, so laya_engine() finds it by name.
laya_import_model( path, checkpoint = c("multilingual", "english", "typed-decisions"), method = c("symlink", "copy"), overwrite = FALSE )laya_import_model( path, checkpoint = c("multilingual", "english", "typed-decisions"), method = c("symlink", "copy"), overwrite = FALSE )
path |
The export's folder: it holds |
checkpoint |
Which checkpoint the export is. |
method |
|
overwrite |
Replace an installed model? |
The installed path, invisibly.
## Not run: laya_import_model("~/exports/onnx/multilingual", "multilingual") ## End(Not run)## Not run: laya_import_model("~/exports/onnx/multilingual", "multilingual") ## End(Not run)
layaR keeps exported checkpoints in a model root folder with one subfolder
per checkpoint (multilingual/, english/, typed-decisions/). The root
is, in order: the layaR.model_root option, the LAYA_ONNX_ROOT
environment variable (shared with Laya's Rust SDK), or the user cache
folder tools::R_user_dir("layaR", "cache") plus onnx/. Downloads and
imports go there.
laya_model_root() laya_model_path(checkpoint = c("multilingual", "english", "typed-decisions")) laya_model_available( checkpoint = getOption("layaR.checkpoint", "multilingual") )laya_model_root() laya_model_path(checkpoint = c("multilingual", "english", "typed-decisions")) laya_model_available( checkpoint = getOption("layaR.checkpoint", "multilingual") )
checkpoint |
A checkpoint name. |
When a checkpoint isn't in the model root, layaR also looks in the cache
that Laya's other SDKs share (~/.cache/laya/onnx, or
%LOCALAPPDATA%/laya/onnx on Windows), so a model exported or downloaded
for the Rust or TypeScript SDK is reused. layaR never writes there. Set
options(layaR.shared_cache = FALSE) to turn this off.
laya_model_root() and laya_model_path() return paths (the
latter is where layaR installs checkpoint); laya_model_available()
returns TRUE when a complete export is found in either place.
laya_models(), laya_download_model(), laya_import_model()
laya_model_root() laya_model_path("english") laya_model_available()laya_model_root() laya_model_path("english") laya_model_available()
List checkpoints and whether they are installed
laya_models()laya_models()
A data frame with one row per checkpoint: checkpoint,
installed, path (where it was found, or where it would be installed),
source ("layaR" for the model root, "shared" for the cross-SDK
cache, NA when not installed), layout ("fused" or "split") and
size_gb.
laya_models()laya_models()
laya_predict() answers every question about one state in a single
forward pass. laya_predict_batch() does the same for many states.
laya_predict_long() scans a state longer than the model's context in
overlapping windows and keeps, per question, the most confident window.
laya_predict( state, questions, engine = laya_default_engine(), ..., min_confidence = NULL, lang = NULL, max_len = NULL, head_max_len = NULL ) laya_predict_batch( states, questions, engine = laya_default_engine(), ..., batch_size = getOption("layaR.batch_size", 1L), sort_by_length = FALSE, min_confidence = NULL, lang = NULL, max_len = NULL, head_max_len = NULL, chunk_size = 64L, progress = interactive() ) laya_predict_long( state, questions, engine = laya_default_engine(), ..., window = NULL, stride = NULL, batch_size = NULL, lang = NULL ) ## S3 method for class 'laya_engine' predict(object, state, questions, ...)laya_predict( state, questions, engine = laya_default_engine(), ..., min_confidence = NULL, lang = NULL, max_len = NULL, head_max_len = NULL ) laya_predict_batch( states, questions, engine = laya_default_engine(), ..., batch_size = getOption("layaR.batch_size", 1L), sort_by_length = FALSE, min_confidence = NULL, lang = NULL, max_len = NULL, head_max_len = NULL, chunk_size = 64L, progress = interactive() ) laya_predict_long( state, questions, engine = laya_default_engine(), ..., window = NULL, stride = NULL, batch_size = NULL, lang = NULL ) ## S3 method for class 'laya_engine' predict(object, state, questions, ...)
state |
A string, a named list, or a one-row data frame. |
questions |
A question set from |
engine |
A |
... |
Must be empty; the options below are named. |
min_confidence |
Optional abstention gate: a threshold in |
lang |
Optional language code (e.g. |
max_len, head_max_len
|
Optional per-call token budgets overriding the checkpoint's: the whole sequence, and the part spent on a question's options. |
states |
A character vector, a list of states, or a data frame (each row becomes a named list). |
batch_size |
States per forward pass. Defaults to the
|
sort_by_length |
Group similarly sized states within a chunk to
reduce padding (only with a |
chunk_size |
States sent to the engine per call. Between chunks R can be interrupted and the progress bar updates. |
progress |
Show a progress bar? Defaults to |
window, stride
|
Optional scan window and stride, in tokens. By default the window is the room the questions leave in one sequence and the stride is half the window. |
object |
A |
A state is either a single string, used verbatim, or a named list, which the model reads as a JSON object (field order is kept). A one-row data frame is read as a named list.
laya_predict() and laya_predict_long() return a laya_result;
laya_predict_batch() returns a laya_batch_result (a list of
laya_results, in input order). See laya_result for how to read them.
if (laya_model_available()) { qs <- laya_questions( department = laya_choice("Which department should handle this?", billing = "invoices, refunds", technical = "bugs, outages"), churn_risk = laya_noul("Does the user threaten to cancel?") ) res <- laya_predict("I was billed twice. Refund me or I cancel.", qs) res as.data.frame(res) laya_predict_batch(c("Refund please", "The app crashes"), qs) }if (laya_model_available()) { qs <- laya_questions( department = laya_choice("Which department should handle this?", billing = "invoices, refunds", technical = "bugs, outages"), churn_risk = laya_noul("Does the user threaten to cancel?") ) res <- laya_predict("I was billed twice. Refund me or I cancel.", qs) res as.data.frame(res) laya_predict_batch(c("Refund please", "The app crashes"), qs) }
Ready-made question sets ported from the Python SDK's presets. Each
preset's instructions refer to one field of the state, so pass the state
as a named list with that field (see laya_preset_fields()).
laya_preset( name = c("triage", "email", "guard", "moderation", "router"), categories = NULL ) laya_preset_fields()laya_preset( name = c("triage", "email", "guard", "moderation", "router"), categories = NULL ) laya_preset_fields()
name |
The preset name. |
categories |
For the |
| Preset | State field | Questions |
triage |
message |
intent, is_urgent, frustration, refund_requested, churn_risk |
email |
body |
category, is_spam, is_phishing, urgency, needs_reply |
guard |
prompt |
jailbreak, prompt_injection, sensitive_data, harm_severity, topic |
moderation |
post |
toxic, harassment, threat, spam, severity |
router |
request |
difficulty, domain, needs_tools, is_sensitive |
A laya_questions object.
laya_preset("triage") laya_preset("email", categories = c(orders = "order status, shipping", returns = "returns and exchanges")) laya_preset_fields()laya_preset("triage") laya_preset("email", categories = c(orders = "order status, shipping", returns = "returns and exchanges")) laya_preset_fields()
Laya answers three kinds of typed question about a state in one forward pass:
laya_choice(instructions, ..., .options = NULL) laya_score(instructions, levels) laya_noul(instructions, if_false = NULL, if_true = NULL)laya_choice(instructions, ..., .options = NULL) laya_score(instructions, levels) laya_noul(instructions, if_false = NULL, if_true = NULL)
instructions |
The question, as a string. A list is also accepted and is serialized to JSON, as the Python SDK does for structured instructions. |
... |
For |
.options |
Alternatively, the options as a named character vector or list (labels with descriptions), or an unnamed character vector (labels only). |
levels |
For |
if_false, if_true
|
For |
laya_choice(): pick one label from a fixed set of options.
laya_score(): place the state on an ordinal scale (levels lowest first);
the answer is the expected level, a number between 0 and the number of
levels minus one.
laya_noul(): a yes/no statement; the answer is the calibrated
probability that it holds.
Combine questions into a set with laya_questions().
A laya_question object.
laya_questions(), laya_preset()
laya_choice( "Which department should handle this request?", billing = "invoices, payments, refunds", technical = "bugs, outages, system errors", other = "everything else" ) laya_choice("What is this about?", "coding", "writing", "other") laya_score("How urgent is this request?", c("not urgent", "soon", "blocking")) laya_noul("Is this email a phishing attempt?", if_false = "a legitimate email", if_true = "phishing or fraud")laya_choice( "Which department should handle this request?", billing = "invoices, payments, refunds", technical = "bugs, outages, system errors", other = "everything else" ) laya_choice("What is this about?", "coding", "writing", "other") laya_score("How urgent is this request?", c("not urgent", "soon", "blocking")) laya_noul("Is this email a phishing attempt?", if_false = "a legitimate email", if_true = "phishing or fraud")
Combine questions into a question set
laya_questions(...)laya_questions(...)
... |
Named questions built with |
A laya_questions object: a named list of questions in the Python
SDK's format.
as_laya_questions() to import a Python question set, and
laya_questions_to_json() to export one.
qs <- laya_questions( department = laya_choice("Which department?", billing = "refunds", technical = "bugs"), urgency = laya_score("How urgent?", c("low", "high")), churn_risk = laya_noul("Does the user threaten to cancel?") ) qsqs <- laya_questions( department = laya_choice("Which department?", billing = "refunds", technical = "bugs"), urgency = laya_score("How urgent?", c("low", "high")), churn_risk = laya_noul("Does the user threaten to cancel?") ) qs
The output is in the Python SDK's format.
laya_questions_to_json(questions, path = NULL, pretty = TRUE)laya_questions_to_json(questions, path = NULL, pretty = TRUE)
questions |
A |
path |
Optional file path. If given, the JSON is written there. |
pretty |
Pretty-print the JSON? |
The JSON string (invisibly when path is given).
laya_questions_to_json(laya_questions(spam = laya_noul("Is this spam?")))laya_questions_to_json(laya_questions(spam = laya_noul("Is this spam?")))
Deletes a checkpoint from layaR's model root, freeing about 1.3 GB. A model imported as a symlink only loses the link. Models in the shared cross-SDK cache are never touched.
laya_remove_model( checkpoint = c("multilingual", "english", "typed-decisions"), ask = interactive() )laya_remove_model( checkpoint = c("multilingual", "english", "typed-decisions"), ask = interactive() )
checkpoint |
Which checkpoint to remove. |
ask |
Ask for confirmation first? Defaults to |
TRUE if a model was removed, invisibly.
## Not run: laya_remove_model("english") ## End(Not run)## Not run: laya_remove_model("english") ## End(Not run)
A laya_result is a list with model, answers (one entry per question,
in question order) and usage (token accounting and truncation flags),
in the Python SDK's shape. Each answer has type, confidence,
answer_confidence and action$act_probability, plus:
## S3 method for class 'laya_result' as.data.frame(x, row.names = NULL, optional = FALSE, ...) laya_probabilities(x) laya_answer(x, id) ## S3 method for class 'laya_batch_result' as.data.frame(x, row.names = NULL, optional = FALSE, ...)## S3 method for class 'laya_result' as.data.frame(x, row.names = NULL, optional = FALSE, ...) laya_probabilities(x) laya_answer(x, id) ## S3 method for class 'laya_batch_result' as.data.frame(x, row.names = NULL, optional = FALSE, ...)
x |
A |
row.names, optional
|
Ignored; part of the |
... |
Unused. |
id |
A question id. |
choice: choice (the top label) and probabilities (per label);
score: score (the expected level, from 0 to levels - 1), legend and
probabilities (per level, keyed "0", "1", ...);
noul: noul (the probability the statement holds).
With min_confidence, answers also carry abstention and
abstention_threshold; from laya_predict_long(), window.
as.data.frame() gives one row per question; laya_probabilities() one
row per option; laya_answer() extracts one answer. A
laya_batch_result (from laya_predict_batch()) is a list of
laya_results whose data-frame forms carry a state_id column.
as.data.frame() returns a data frame with columns id, type,
answer (the label, the score or TRUE/FALSE, as text), value (the
chosen label's probability, the score, or P(true)), confidence,
answer_confidence, act_probability and abstention.
laya_probabilities() returns columns id, type, option and
probability (for noul questions, options "false" and "true").
if (laya_model_available()) { res <- laya_predict("Refund me now!", laya_preset("triage")) as.data.frame(res) laya_probabilities(res) laya_answer(res, "intent")$choice }if (laya_model_available()) { res <- laya_predict("Refund me now!", laya_preset("triage")) as.data.frame(res) laya_probabilities(res) laya_answer(res, "intent")$choice }
Runs the Rust engine's own question validation, so errors surface before a model is loaded.
laya_validate_questions(questions)laya_validate_questions(questions)
questions |
A |
questions as a laya_questions object, invisibly. Errors with a
laya_error_invalid_question (or laya_error_not_supported) condition.
laya_validate_questions(laya_questions(spam = laya_noul("Is this spam?")))laya_validate_questions(laya_questions(spam = laya_noul("Is this spam?")))