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
namespace Laya;
/// <summary>
/// Selects which Laya checkpoint to load. Each maps to a different encoder and context length;
/// see the SDK README for the tradeoffs.
/// </summary>
public enum LayaCheckpoint
{
/// <summary>
/// mmBERT-base (322 M), 1 024-token context, 100+ languages. The safest default for
/// mixed-language traffic; covers English too, so there is no router to configure.
/// </summary>
Multilingual,
/// <summary>
/// ModernBERT-large (421 M), 512-token context, English-optimised. Higher accuracy on
/// English-only workloads; accuracy collapses on non-Latin scripts (route those through
/// the multilingual checkpoint).
/// </summary>
English,
/// <summary>
/// ModernBERT-large (421 M), 1 024-token context, fine-tuned on four typed-decisions
/// workflows. Use only for the specific workflows it was trained on.
/// </summary>
TypedDecisions,
}
/// <summary>
/// ONNX execution provider. Only <see cref="Cpu"/> is wired in v1; the others are reserved so
/// callers can opt in and receive a clear error if the matching ORT package is absent.
/// </summary>
public enum LayaExecutionProvider
{
/// <summary>CPU execution (default).</summary>
Cpu,
/// <summary>NVIDIA CUDA. Requires the <c>Microsoft.ML.OnnxRuntime.Gpu</c> package.</summary>
Cuda,
/// <summary>Windows DirectML. Requires the <c>Microsoft.ML.OnnxRuntime.DirectML</c> package.</summary>
DirectMl,
}
/// <summary>Progress report for a single file being downloaded from HuggingFace Hub.</summary>
/// <param name="FileName">The file name being fetched, e.g. <c>model.onnx.data</c>.</param>
/// <param name="BytesReceived">Bytes written to disk so far.</param>
/// <param name="TotalBytes">
/// Total file size in bytes, or <see langword="null"/> when the server omits
/// <c>Content-Length</c>.
/// </param>
public readonly record struct ArtifactDownloadProgress(
string FileName,
long BytesReceived,
long? TotalBytes);
/// <summary>
/// Controls how the Laya engine locates or downloads its ONNX artifact and how it
/// configures ONNX Runtime.
/// </summary>
public sealed class LayaOptions
{
private string? _huggingFaceSubfolder;
/// <summary>
/// The directory that contains <c>model.onnx</c>. When set, skips all other
/// resolution steps. Default <see langword="null"/> (auto-resolve).
/// </summary>
public string? ModelDirectory { get; set; }
/// <summary>
/// Which checkpoint to load. Default <see cref="LayaCheckpoint.Multilingual"/>.
/// The subdirectory, HuggingFace subfolder, and cache path all derive from this value
/// unless overridden by <see cref="HuggingFaceSubfolder"/> or <see cref="ModelDirectory"/>.
/// </summary>
public LayaCheckpoint Checkpoint { get; set; } = LayaCheckpoint.Multilingual;
/// <summary>
/// Which hardware back-end to use. Default <see cref="LayaExecutionProvider.Cpu"/>.
/// </summary>
public LayaExecutionProvider ExecutionProvider { get; set; } = LayaExecutionProvider.Cpu;
/// <summary>
/// Number of threads used within a single ONNX operator.
/// <see langword="null"/> lets ONNX Runtime choose (usually one per logical CPU).
/// </summary>
public int? IntraOpThreads { get; set; }
/// <summary>
/// Number of threads used to run independent ONNX operators in parallel.
/// <see langword="null"/> lets ONNX Runtime choose.
/// </summary>
public int? InterOpThreads { get; set; }
/// <summary>
/// Whether the engine may fetch the artifact from HuggingFace Hub when it is not
/// found locally. Default <see langword="false"/>; downloading must always be opt-in.
/// </summary>
public bool AllowDownload { get; set; } = false;
/// <summary>
/// HuggingFace repository that hosts the artifact.
/// Default <c>"convaiinnovations/laya"</c>.
/// </summary>
public string HuggingFaceRepo { get; set; } = "convaiinnovations/laya";
/// <summary>
/// Subfolder within the repository and local cache. Derived from <see cref="Checkpoint"/>
/// by default. Set explicitly only when loading a custom export that does not follow the
/// standard bundle layout — prefer setting <see cref="Checkpoint"/> instead.
/// </summary>
/// <remarks>
/// Note that the HuggingFace bundle subfolder for the English checkpoint is the bundle
/// root (empty string), not "english". When this property is left at its default,
/// download URLs are computed correctly. If you set it explicitly for English you must
/// use the empty string for the download path; for local artifact directories "english"
/// is the conventional name.
/// </remarks>
public string HuggingFaceSubfolder
{
get => _huggingFaceSubfolder ?? CheckpointSubfolder(Checkpoint);
set => _huggingFaceSubfolder = value;
}
/// <summary>
/// HuggingFace access token used in the <c>Authorization: Bearer</c> header.
/// When <see langword="null"/>, falls back to the <c>HF_TOKEN</c> environment variable.
/// Set to an empty string to suppress all auth (public repos only).
/// </summary>
public string? HuggingFaceToken { get; set; }
/// <summary>
/// Root directory under which the downloaded artifact is stored. Default
/// <see langword="null"/>, which resolves to
/// <c>%LOCALAPPDATA%\laya\onnx</c> on Windows and <c>~/.cache/laya/onnx</c>
/// elsewhere.
/// </summary>
public string? CacheDirectory { get; set; }
/// <summary>
/// Optional sink for per-file download progress. Each notification carries the
/// file name, bytes received so far, and total size when known.
/// </summary>
public IProgress<ArtifactDownloadProgress>? DownloadProgress { get; set; }
/// <summary>
/// Per-language temperature overrides, Python's <c>lang_temperatures</c> constructor option: a table from language
/// code to <see cref="LayaLangTemperature"/>, or <see langword="null"/> for a language that inherits the checkpoint's
/// own temperatures. A call that names a language through <see cref="LayaPredictOptions.Lang"/> (or a router that
/// detected one) replaces the checkpoint's temperature, and its per-bucket map, with that language's. Keys are
/// matched as Python matches them, on the part before the first <c>-</c>, lower-cased (<c>"de-AT"</c> and
/// <c>"DE"</c> are <c>"de"</c>), and the last of several keys that collapse to the same language wins; a table
/// given as a list of pairs keeps that order. Default <see langword="null"/>: no overrides.
/// </summary>
/// <remarks>
/// Checked when the engine is created, not when it is set. A malformed entry makes <see cref="LayaEngine.Create"/>
/// throw an <see cref="ArgumentException"/> carrying Python's <c>ValueError</c> text, and a value the clamp had to
/// replace is reported once per language through <see cref="System.Diagnostics.Trace"/>, as the checkpoint's own
/// temperatures are. A <see cref="LayaRouter"/> hands this table to every engine it builds.
/// </remarks>
public IEnumerable<KeyValuePair<string, LayaLangTemperature?>>? LangTemperatures { get; set; }
/// <summary>
/// Path of a calibration file, Python's <c>calibration</c> constructor option (<c>load_calibration</c>): a JSON object
/// with <c>temperature</c> (three numbers), <c>temperature_by_options</c> (bucket to number), an optional
/// <c>version</c> and an optional <c>binning_map</c> (bucket to <c>{"bins": n, "values": [n numbers in [0, 1]]}</c>).
/// It is read when the engine is created, after the checkpoint's own temperatures and the
/// <see cref="LangTemperatures"/> table, and replaces the checkpoint's temperature and its per-bucket map. The
/// binning map recalibrates <c>answer_confidence</c> (and only that) of every answer whose option-count bucket the
/// map names, after the temperature softmax; a call that names a language of <see cref="LangTemperatures"/> is not
/// binned. A file with no <c>binning_map</c> installs none. Default <see langword="null"/> or empty: no file.
/// </summary>
/// <remarks>
/// The file is read as UTF-8 and parsed as Python's <c>json.load</c> parses it (<c>NaN</c> and <c>Infinity</c>
/// accepted), like <c>rl_agent_config.json</c>. A malformed file makes <see cref="LayaEngine.Create"/> throw an
/// <see cref="InvalidDataException"/> whose message is Python's exception type and text; a temperature outside
/// <see cref="Laya.Calibration.TempMin"/>..<see cref="Laya.Calibration.TempMax"/> is clamped and reported once through
/// <see cref="System.Diagnostics.Trace"/>. A version 2 file's recorded checkpoint (<c>model_id_or_path</c>, <c>subfolder</c>,
/// <c>config</c>) is not compared with the engine's: Python's <c>model_id_or_path</c> is the string its caller passed, which this
/// SDK has no equivalent of, so that warning is not emitted. A
/// <see cref="LayaRouter"/> hands this path to every engine it builds. There is no per-call form.
/// </remarks>
public string? Calibration { get; set; }
// ── internal helpers ──────────────────────────────────────────────────────
/// <summary>
/// The local artifact subdirectory name for <paramref name="c"/>.
/// Used as the subdirectory inside the cache root and inside an <c>onnx/</c> tree.
/// </summary>
internal static string CheckpointSubfolder(LayaCheckpoint c) => c switch
{
LayaCheckpoint.Multilingual => "multilingual",
LayaCheckpoint.English => "english",
LayaCheckpoint.TypedDecisions => "typed-decisions",
_ => throw new ArgumentOutOfRangeException(nameof(c), c, null),
};
/// <summary>
/// The subfolder path to use in HuggingFace download URLs. For English the checkpoint
/// lives at the bundle root (empty string), which differs from the local directory name
/// "english". When <see cref="HuggingFaceSubfolder"/> was set explicitly that value is
/// used as-is.
/// </summary>
internal string HuggingFaceDownloadSubfolder =>
_huggingFaceSubfolder ?? HfDownloadSubfolder(Checkpoint);
private static string HfDownloadSubfolder(LayaCheckpoint c) => c switch
{
LayaCheckpoint.Multilingual => "multilingual",
LayaCheckpoint.English => "", // lives at the bundle root
LayaCheckpoint.TypedDecisions => "typed-decisions",
_ => throw new ArgumentOutOfRangeException(nameof(c), c, null),
};
}