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(dotnet): add ONNX inference engine and presets

kevin-gatimu2d969b990868
diff --git a/laya-dotnet/src/Laya/ILayaPredictor.cs b/laya-dotnet/src/Laya/ILayaPredictor.cs
new file mode 100644
index 00000000..44f4afc7
--- /dev/null
+++ b/laya-dotnet/src/Laya/ILayaPredictor.cs
@@ -0,0 +1,13 @@
+namespace Laya;
+
+/// <summary>
+/// Anything that can answer a <see cref="QuestionSet"/> about a state in one call: a single
+/// <see cref="LayaEngine"/>, or a <see cref="LayaRouter"/> that picks one first. Mirrors Python's
+/// duck-typed <c>predict</c>/<c>system_one</c> (<c>shortlist._call_predict</c>), so
+/// <see cref="LayaShortlist.Predict"/> works over either.
+/// </summary>
+public interface ILayaPredictor
+{
+ /// <summary>Answer every question in <paramref name="questions"/> about <paramref name="state"/>.</summary>
+ LayaResult Predict(object? state, QuestionSet questions);
+}
diff --git a/laya-dotnet/src/Laya/LayaEngine.cs b/laya-dotnet/src/Laya/LayaEngine.cs
new file mode 100644
index 00000000..2b04a70d
--- /dev/null
+++ b/laya-dotnet/src/Laya/LayaEngine.cs
@@ -0,0 +1,435 @@
+using Laya.Tokenization;
+using Microsoft.ML.OnnxRuntime;
+using Microsoft.ML.OnnxRuntime.Tensors;
+
+namespace Laya;
+
+/// <summary>
+/// Answers typed questions about a piece of state in one forward pass. The .NET counterpart of
+/// Python's <c>laya.Agent</c>: this library is a .NET port of the Laya Python SDK (the
+/// <c>laya</c> package on PyPI), run on ONNX Runtime instead of PyTorch.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Loading the model is expensive and the session is reusable, so create one engine and keep it:
+/// it is safe to share across threads and works well as a singleton.
+/// </para>
+/// <para>
+/// Every question in a <see cref="QuestionSet"/> is answered by a single batched inference call,
+/// matching Python's single forward pass — asking five questions costs roughly what asking one does.
+/// </para>
+/// <para>
+/// Loads either ONNX artifact layout (<see cref="LayaArtifactLayout"/>). For the fused layout,
+/// one <see cref="InferenceSession"/> runs the whole forward pass. For the split layout (the
+/// laya-ts exporter's output), two sessions run in sequence: the encoder produces
+/// <c>last_hidden_state</c>, which is fed straight into the head. Both cases go through
+/// <see cref="Run"/>, so batching, calibration and <see cref="Predict"/> do not know which
+/// layout is loaded.
+/// </para>
+/// </remarks>
+public sealed class LayaEngine : IDisposable, ILayaPredictor
+{
+ private const string ModelName = "laya-rl-agent";
+
+ // Exactly one of _fusedSession or (_encoderSession, _headSession) is non-null, matching
+ // Artifacts.Layout.
+ private readonly InferenceSession? _fusedSession;
+ private readonly InferenceSession? _encoderSession;
+ private readonly InferenceSession? _headSession;
+ private readonly ILayaTokenizer _tokenizer;
+ private readonly bool _ownsTokenizer;
+ private readonly Lock _tokenizerGate = new();
+ // 0 = live, 1 = disposed; int so Interlocked.Exchange can operate on it.
+ private int _disposed;
+
+ private LayaEngine(InferenceSession? fusedSession, InferenceSession? encoderSession,
+ InferenceSession? headSession, ILayaTokenizer tokenizer, bool ownsTokenizer,
+ LayaConfig config, ModelArtifacts artifacts)
+ {
+ _fusedSession = fusedSession;
+ _encoderSession = encoderSession;
+ _headSession = headSession;
+ _tokenizer = tokenizer;
+ _ownsTokenizer = ownsTokenizer;
+ Config = config;
+ Artifacts = artifacts;
+ }
+
+ /// <summary>The loaded checkpoint's configuration.</summary>
+ public LayaConfig Config { get; }
+
+ /// <summary>Where the loaded artifacts came from.</summary>
+ public ModelArtifacts Artifacts { get; }
+
+ /// <summary>
+ /// Which checkpoint variant was loaded, or <see langword="null"/> when loaded from an
+ /// explicit directory (via <see cref="LayaOptions.ModelDirectory"/> or the
+ /// <c>LAYA_ONNX_DIR</c> environment variable) where no checkpoint was inferred.
+ /// </summary>
+ public LayaCheckpoint? Checkpoint => Artifacts.Checkpoint;
+
+ /// <summary>
+ /// Load an engine, resolving the artifact directory from <paramref name="options"/>, the
+ /// <c>LAYA_ONNX_DIR</c> environment variable, or the local cache.
+ /// </summary>
+ /// <exception cref="InvalidOperationException">
+ /// When the loaded config's encoder contradicts the expected encoder for the requested
+ /// <see cref="LayaOptions.Checkpoint"/> — indicates the wrong artifact was loaded.
+ /// </exception>
+ public static LayaEngine Create(LayaOptions? options = null)
+ {
+ options ??= new LayaOptions();
+ var artifacts = ModelArtifacts.Resolve(options);
+ var config = LayaConfig.Load(artifacts.ConfigPath);
+
+ // When the checkpoint was resolved via a checkpoint-aware path (LAYA_ONNX_ROOT, cache,
+ // or download), validate that the artifact's encoder agrees. A mismatch here means the
+ // directory name and the contents disagree — something that happens when a user manually
+ // copies or renames a checkpoint directory.
+ if (artifacts.Checkpoint is { } expectedCheckpoint)
+ ValidateEncoder(config.Encoder, expectedCheckpoint, artifacts.Directory);
+
+ // using disposes sessionOptions on both success and failure; ORT copies the options at
+ // CreateSession time so they are not needed after the InferenceSession constructor returns.
+ using var sessionOptions = BuildSessionOptions(options);
+ InferenceSession? fusedSession = null;
+ InferenceSession? encoderSession = null;
+ InferenceSession? headSession = null;
+ HfTokenizer? tokenizer = null;
+ try
+ {
+ if (artifacts.Layout == LayaArtifactLayout.Fused)
+ {
+ // The path must point at model.onnx inside its own directory: this checkpoint is
+ // in ONNX external-data format and the runtime resolves the ~1.3 GB
+ // model.onnx.data sidecar relative to the graph file.
+ fusedSession = new InferenceSession(artifacts.ModelPath!, sessionOptions);
+ }
+ else
+ {
+ encoderSession = new InferenceSession(artifacts.EncoderPath!, sessionOptions);
+ headSession = new InferenceSession(artifacts.HeadPath!, sessionOptions);
+ }
+
+ tokenizer = new HfTokenizer(artifacts.TokenizerPath);
+ return new LayaEngine(fusedSession, encoderSession, headSession,
+ tokenizer, ownsTokenizer: true, config, artifacts);
+ }
+ catch
+ {
+ tokenizer?.Dispose();
+ fusedSession?.Dispose();
+ encoderSession?.Dispose();
+ headSession?.Dispose();
+ throw;
+ }
+ }
+
+ /// <summary>Load an engine from an artifact directory containing either ONNX layout.</summary>
+ public static LayaEngine FromDirectory(string directory) =>
+ Create(new LayaOptions { ModelDirectory = directory });
+
+ private static void ValidateEncoder(string? actualEncoder, LayaCheckpoint checkpoint, string dir)
+ {
+ // Multilingual uses mmBERT; English and TypedDecisions both use ModernBERT-large.
+ // We can only detect a family mismatch (mmBERT vs. ModernBERT), not distinguish English
+ // from TypedDecisions, since both share the same encoder string.
+ var expectModernBert = checkpoint != LayaCheckpoint.Multilingual;
+ var gotModernBert = actualEncoder is not null
+ && actualEncoder.Contains("ModernBERT", StringComparison.OrdinalIgnoreCase);
+
+ if (expectModernBert != gotModernBert)
+ {
+ var expected = checkpoint == LayaCheckpoint.Multilingual
+ ? "jhu-clsp/mmBERT-base"
+ : "answerdotai/ModernBERT-large";
+ throw new InvalidOperationException(
+ $"Checkpoint '{checkpoint}' expects encoder '{expected}' but the artifact at "
+ + $"'{dir}' declares encoder '{actualEncoder ?? "(null)"}'. "
+ + "The artifact directory may contain the wrong checkpoint.");
+ }
+ }
+
+ private static SessionOptions BuildSessionOptions(LayaOptions options)
+ {
+ var so = new SessionOptions();
+ try
+ {
+ if (options.IntraOpThreads is { } intra) so.IntraOpNumThreads = intra;
+ if (options.InterOpThreads is { } inter) so.InterOpNumThreads = inter;
+ switch (options.ExecutionProvider)
+ {
+ case LayaExecutionProvider.Cpu:
+ break;
+ case LayaExecutionProvider.Cuda:
+ so.AppendExecutionProvider_CUDA();
+ break;
+ case LayaExecutionProvider.DirectMl:
+ so.AppendExecutionProvider_DML();
+ break;
+ default:
+ throw new ArgumentOutOfRangeException(nameof(options), options.ExecutionProvider,
+ "unknown execution provider");
+ }
+ return so;
+ }
+ catch
+ {
+ so.Dispose();
+ throw;
+ }
+ }
+
+ /// <summary>Answer every question in <paramref name="questions"/> about <paramref name="state"/>.</summary>
+ /// <param name="state">
+ /// A <see cref="string"/> is used verbatim; anything else is serialized the way Python's
+ /// <c>serialize_state</c> does, so an object or a list of conversation turns both work.
+ /// </param>
+ /// <param name="questions">The questions to answer, in the order they should be returned.</param>
+ /// <exception cref="ArgumentException">
+ /// If a question's options cannot fit the head budget, rather than answering a silently
+ /// truncated question.
+ /// </exception>
+ public LayaResult Predict(object? state, QuestionSet questions)
+ {
+ ArgumentNullException.ThrowIfNull(questions);
+ ObjectDisposedException.ThrowIf(Volatile.Read(ref _disposed) == 1, this);
+ if (questions.Count == 0) throw new ArgumentException("no questions to answer", nameof(questions));
+
+ var ids = questions.Ids;
+ var items = new List<SequenceItem>(questions.Count);
+
+ // A chronological conversation list is serialized newest-last, so right-truncation
+ // (the default) would silently drop the newest turn. Matches Agent._encode_state's
+ // `truncate_left = isinstance(state, list)`: only a list-shaped state truncates from the
+ // left; string and dict states keep the existing right-truncation.
+ var truncateLeft = PythonJson.IsListState(state);
+
+ // The tokenizer wraps a native handle whose thread safety is not documented, so
+ // tokenization is serialized. Inference is not: it is the expensive part and
+ // InferenceSession.Run is thread-safe.
+ lock (_tokenizerGate)
+ {
+ foreach (var id in ids)
+ {
+ var question = questions[id];
+ var (seq, markers) = SequenceBuilder.Build(
+ _tokenizer, state, question, Config.MaxLen, Config.HeadMaxLen, truncateLeft);
+
+ // A marker dropped for landing past max_len means an option is not in the sequence
+ // at all, so its logit would score whatever token happens to sit at position 0.
+ if (markers.Length != SequenceBuilder.RenderOptions(question).Count)
+ throw new ArgumentException(
+ $"question '{id}' options exceed head_max_len={Config.HeadMaxLen}", nameof(questions));
+
+ items.Add(new SequenceItem(seq, markers, question.Type));
+ }
+ }
+
+ var batch = Collator.Collate(items, _tokenizer.PadId);
+ var (logits, actLogits) = Run(batch);
+
+ // n_act is the act_logits column count, derived from the tensor's dims[1] rather than
+ // hardcoded so the code stays correct if the graph is re-exported with a wider action head.
+ var nAct = actLogits.Length / batch.Count;
+
+ var answers = new Dictionary<string, Answer>(questions.Count, StringComparer.Ordinal);
+ for (var row = 0; row < ids.Count; row++)
+ {
+ var question = questions[ids[row]];
+ var k = batch.MarkerCounts[row];
+ var temperature = Calibration.ResolveTemperature(Config, question.Type, k);
+ var rowLogits = logits.AsSpan(row * batch.MarkerCount, batch.MarkerCount);
+ var p = Calibration.Probabilities(rowLogits, k, temperature);
+
+ var action = new ActionInfo(
+ Calibration.Round4(Calibration.Softmax(actLogits.AsSpan(row * nAct, nAct))[0]));
+ answers[ids[row]] = BuildAnswer(question, p, k, action);
+ }
+
+ return new LayaResult(ModelName, [.. ids], answers, new Usage(batch.InputTokens, 0));
+ }
+
+ private static Answer BuildAnswer(Question question, double[] p, int k, ActionInfo action)
+ {
+ var confidence = Calibration.Round4(Calibration.ConfidenceFromProbs(p, k));
+ var answerConfidence = Calibration.Round4(Calibration.AnswerConfidence(p, k));
+ switch (question)
+ {
+ case ChoiceQuestion choice:
+ {
+ var labels = choice.Labels;
+ var probabilities = new List<KeyValuePair<string, double>>(k);
+ // Python zips labels against probabilities, so a mismatch would silently drop the
+ // tail rather than misalign; take the shorter for the same reason.
+ for (var i = 0; i < Math.Min(k, labels.Count); i++)
+ probabilities.Add(new(labels[i], Calibration.Round4(p[i])));
+ return new ChoiceAnswer(labels[Calibration.ArgMax(p)], probabilities,
+ confidence, answerConfidence, action);
+ }
+
+ case ScoreQuestion score:
+ {
+ var probabilities = new double[p.Length];
+ for (var i = 0; i < p.Length; i++) probabilities[i] = Calibration.Round4(p[i]);
+ return new ScoreAnswer(Calibration.Round4(Calibration.ExpectedScore(p)),
+ score.Levels, probabilities, confidence, answerConfidence, action);
+ }
+
+ default:
+ {
+ // Noul reports the true-branch probability, and its confidence is the distance from
+ // a coin flip rather than the entropy measure the other two types use. Over two
+ // options max(p_true, 1 - p_true) equals max(p), so answerConfidence agrees here —
+ // matching the Python comment on this exact case in `_decode_answers`.
+ var pTrue = p[1];
+ return new NoulAnswer(Calibration.Round4(pTrue),
+ Calibration.Round4(Math.Max(pTrue, 1.0 - pTrue)),
+ answerConfidence, action);
+ }
+ }
+ }
+
+ /// <summary>One forward pass over a collated batch, returning the raw graph outputs.</summary>
+ /// <remarks>
+ /// Internal rather than private so the test suite can drive the graph directly — the shape sweep
+ /// and the recorded-logits comparison both need the outputs before calibration, and sharing this
+ /// session keeps them from loading a second copy of the weights.
+ /// </remarks>
+ internal (float[] Logits, float[] ActLogits) Run(CollatedBatch batch) =>
+ Artifacts.Layout == LayaArtifactLayout.Fused ? RunFused(batch) : RunSplit(batch);
+
+ private (float[] Logits, float[] ActLogits) RunFused(CollatedBatch batch)
+ {
+ var session = _fusedSession!;
+ var inputs = new List<NamedOnnxValue>(5);
+
+ if (session.InputMetadata.ContainsKey("input_ids"))
+ inputs.Add(LongInput(session, "input_ids", batch.InputIds, batch.Count, batch.SequenceLength));
+ if (session.InputMetadata.ContainsKey("attention_mask"))
+ inputs.Add(LongInput(session, "attention_mask", batch.AttentionMask, batch.Count, batch.SequenceLength));
+ if (session.InputMetadata.ContainsKey("marker_pos"))
+ inputs.Add(LongInput(session, "marker_pos", batch.MarkerPos, batch.Count, batch.MarkerCount));
+ if (session.InputMetadata.ContainsKey("marker_mask"))
+ inputs.Add(MaskInput(session, "marker_mask", batch.MarkerMask, batch.Count, batch.MarkerCount));
+ if (session.InputMetadata.ContainsKey("qtype"))
+ inputs.Add(QTypeInput(session, batch.QType, batch.Count));
+
+ using var results = session.Run(inputs);
+ return (Output(results, "logits"), Output(results, "act_logits"));
+ }
+
+ private (float[] Logits, float[] ActLogits) RunSplit(CollatedBatch batch)
+ {
+ var encoder = _encoderSession!;
+ var head = _headSession!;
+
+ var encoderInputs = new List<NamedOnnxValue>(2);
+ if (encoder.InputMetadata.ContainsKey("input_ids"))
+ encoderInputs.Add(LongInput(encoder, "input_ids", batch.InputIds, batch.Count, batch.SequenceLength));
+ if (encoder.InputMetadata.ContainsKey("attention_mask"))
+ encoderInputs.Add(LongInput(encoder, "attention_mask", batch.AttentionMask, batch.Count, batch.SequenceLength));
+
+ // Both Run calls happen inside this one using block: headResults is built and consumed
+ // while encoderResults (and the last_hidden_state tensor it owns) is still alive, so the
+ // head reads the encoder's output tensor directly with no extra copy.
+ using var encoderResults = encoder.Run(encoderInputs);
+ var hiddenState = OutputTensor(encoderResults, "last_hidden_state");
+
+ var headInputs = new List<NamedOnnxValue>(5)
+ {
+ NamedOnnxValue.CreateFromTensor("hidden_states", hiddenState),
+ };
+ if (head.InputMetadata.ContainsKey("marker_pos"))
+ headInputs.Add(LongInput(head, "marker_pos", batch.MarkerPos, batch.Count, batch.MarkerCount));
+ if (head.InputMetadata.ContainsKey("marker_mask"))
+ headInputs.Add(MaskInput(head, "marker_mask", batch.MarkerMask, batch.Count, batch.MarkerCount));
+ if (head.InputMetadata.ContainsKey("qtype"))
+ headInputs.Add(QTypeInput(head, batch.QType, batch.Count));
+ if (head.InputMetadata.ContainsKey("attention_mask"))
+ headInputs.Add(LongInput(head, "attention_mask", batch.AttentionMask, batch.Count, batch.SequenceLength));
+
+ using var headResults = head.Run(headInputs);
+ return (Output(headResults, "logits"), Output(headResults, "act_logits"));
+ }
+
+ // ── input/output helpers shared by both layouts ────────────────────────────
+
+ /// <summary>
+ /// Builds an integer input tensor, matching whichever of int64/int32 the session declares
+ /// for <paramref name="name"/> (mmBERT- and ModernBERT-family exports both use int64, but the
+ /// declared dtype — not a hardcoded assumption — decides which one is fed).
+ /// </summary>
+ private static NamedOnnxValue LongInput(InferenceSession session, string name, long[] data, params int[] shape)
+ {
+ var elementType = session.InputMetadata[name].ElementType;
+ if (elementType == typeof(long))
+ return NamedOnnxValue.CreateFromTensor(name, new DenseTensor<long>(data, shape));
+ if (elementType == typeof(int))
+ return NamedOnnxValue.CreateFromTensor(name, new DenseTensor<int>(Array.ConvertAll(data, x => (int)x), shape));
+
+ throw new InvalidOperationException(
+ $"input '{name}' is declared as {elementType} in the loaded graph; expected int64 or int32.");
+ }
+
+ /// <summary>
+ /// Builds a boolean-mask input tensor, matching whichever of bool/float32 the session
+ /// declares for <paramref name="name"/>.
+ /// </summary>
+ private static NamedOnnxValue MaskInput(InferenceSession session, string name, bool[] data, params int[] shape)
+ {
+ var elementType = session.InputMetadata[name].ElementType;
+ if (elementType == typeof(bool))
+ return NamedOnnxValue.CreateFromTensor(name, new DenseTensor<bool>(data, shape));
+ if (elementType == typeof(float))
+ {
+ var floats = new float[data.Length];
+ for (var i = 0; i < data.Length; i++) floats[i] = data[i] ? 1f : 0f;
+ return NamedOnnxValue.CreateFromTensor(name, new DenseTensor<float>(floats, shape));
+ }
+
+ throw new InvalidOperationException(
+ $"input '{name}' is declared as {elementType} in the loaded graph; expected bool or float32.");
+ }
+
+ /// <summary>
+ /// Builds the <c>qtype</c> input, reading its declared rank from session metadata rather than
+ /// hardcoding it per layout: shape <c>[batch]</c> when the graph declares rank 1 (today's
+ /// fused export), or <c>[batch, 1]</c> when it declares rank 2 (the split export's head).
+ /// </summary>
+ private static NamedOnnxValue QTypeInput(InferenceSession session, long[] data, int batchCount)
+ {
+ var rank = session.InputMetadata["qtype"].Dimensions.Length;
+ var shape = rank >= 2 ? new[] { batchCount, 1 } : new[] { batchCount };
+ return LongInput(session, "qtype", data, shape);
+ }
+
+ private static float[] Output(IDisposableReadOnlyCollection<DisposableNamedOnnxValue> results, string name)
+ {
+ foreach (var value in results)
+ if (string.Equals(value.Name, name, StringComparison.Ordinal))
+ return value.AsEnumerable<float>().ToArray();
+ throw new InvalidOperationException($"the model produced no '{name}' output");
+ }
+
+ private static Tensor<float> OutputTensor(IDisposableReadOnlyCollection<DisposableNamedOnnxValue> results, string name)
+ {
+ foreach (var value in results)
+ if (string.Equals(value.Name, name, StringComparison.Ordinal))
+ return value.AsTensor<float>();
+ throw new InvalidOperationException($"the encoder produced no '{name}' output");
+ }
+
+ /// <inheritdoc/>
+ public void Dispose()
+ {
+ // Interlocked.Exchange is the standard pattern for a one-shot teardown: it atomically
+ // sets the flag and returns the old value, so the cleanup runs exactly once even when
+ // multiple threads race to dispose.
+ if (Interlocked.Exchange(ref _disposed, 1) != 0) return;
+ if (_ownsTokenizer && _tokenizer is IDisposable disposable) disposable.Dispose();
+ _fusedSession?.Dispose();
+ _encoderSession?.Dispose();
+ _headSession?.Dispose();
+ }
+}
diff --git a/laya-dotnet/src/Laya/LayaPresets.cs b/laya-dotnet/src/Laya/LayaPresets.cs
new file mode 100644
index 00000000..b828c59b
--- /dev/null
+++ b/laya-dotnet/src/Laya/LayaPresets.cs
@@ -0,0 +1,140 @@
+namespace Laya;
+
+/// <summary>
+/// Ready-to-use question sets for common production decision workflows.
+/// </summary>
+/// <remarks>
+/// Python name mapping: <c>triage_questions</c> → <see cref="Triage"/>,
+/// <c>email_questions</c> → <see cref="Email(IReadOnlyDictionary{string, string})"/>, <c>guard_questions</c> → <see cref="Guard"/>,
+/// <c>moderation_questions</c> → <see cref="Moderation"/>,
+/// <c>router_questions</c> → <see cref="Router"/>.
+/// </remarks>
+public static class LayaPresets
+{
+ /// <summary>Preset questions for customer support ticket triage.</summary>
+ public static QuestionSet Triage() => new()
+ {
+ ["intent"] = Question.Choice("What does the customer want in `message`?",
+ ("refund", "money returned or a duplicate charge reversed"),
+ ("technical_help", "a bug, outage or integration problem"),
+ ("billing_question", "a question about an invoice, plan or payment method"),
+ ("information", "general information, pricing or how-to"),
+ ("cancellation", "wants to cancel or downgrade"),
+ ("other", "none of the other options fits")),
+ ["is_urgent"] = Question.Noul("Does `message` communicate time pressure or a deadline?"),
+ ["frustration"] = Question.Score("How frustrated does the customer sound in `message`?",
+ "calm and neutral",
+ "concerned but civil",
+ "clearly annoyed",
+ "very angry or using strong language"),
+ ["refund_requested"] = Question.Noul("Does the customer ask for money back?"),
+ ["churn_risk"] = Question.Noul("Does `message` suggest the customer may leave for a competitor or cancel?"),
+ };
+
+ /// <summary>
+ /// Preset questions for inbound email triage and threat filtering.
+ /// </summary>
+ /// <param name="categories">
+ /// Optional routing categories as label → description pairs, in the order they should be
+ /// offered. Defaults to billing, technical, sales, security, hr, other.
+ /// </param>
+ /// <remarks>
+ /// Python's default is a <c>dict</c>, whose iteration order the language guarantees; a
+ /// <see cref="Dictionary{TKey,TValue}"/> guarantees no order at all, and option order decides
+ /// which label each logit is attached to. The default is therefore an explicitly ordered
+ /// sequence, and a caller who cares about order should use the
+ /// <see cref="Email(IEnumerable{KeyValuePair{string, string}})"/> overload.
+ /// </remarks>
+ public static QuestionSet Email(IReadOnlyDictionary<string, string>? categories = null) =>
+ Email((IEnumerable<KeyValuePair<string, string>>?)categories ?? DefaultEmailCategories);
+
+ /// <summary>
+ /// <see cref="Email(IReadOnlyDictionary{string, string})"/> over an explicitly ordered category
+ /// sequence; the sequence order becomes the option order.
+ /// </summary>
+ public static QuestionSet Email(IEnumerable<KeyValuePair<string, string>> categories)
+ {
+ ArgumentNullException.ThrowIfNull(categories);
+ return new()
+ {
+ ["category"] = Question.Choice("Which team should handle the email in `body`?",
+ categories.Select(kv => new KeyValuePair<string, object?>(kv.Key, kv.Value))),
+ ["is_spam"] = Question.Noul("Is this email unsolicited spam or bulk marketing?"),
+ ["is_phishing"] = Question.Noul(
+ "Is this email a phishing or scam attempt to steal money, credentials, or personal data?",
+ ifFalse: "a legitimate email",
+ ifTrue: "phishing, scam, or fraud"),
+ ["urgency"] = Question.Score("How urgent is the request in `body`?",
+ "no time pressure",
+ "needs attention soon",
+ "blocking issue or hard deadline"),
+ ["needs_reply"] = Question.Noul("Does the sender expect a reply?"),
+ };
+ }
+
+ /// <summary>The routing categories <see cref="Email(IReadOnlyDictionary{string, string})"/> uses
+ /// when none are supplied, in offer order.</summary>
+ public static IReadOnlyList<KeyValuePair<string, string>> DefaultEmailCategories { get; } =
+ [
+ new("billing", "invoices, payments, refunds"),
+ new("technical", "bugs, outages, integrations"),
+ new("sales", "pricing, demos, new purchases"),
+ new("security", "phishing, scams, account compromise"),
+ new("hr", "hiring, leave, payroll"),
+ new("other", "none of the above"),
+ ];
+
+ /// <summary>Preset questions for real-time LLM input guardrails.</summary>
+ public static QuestionSet Guard() => new()
+ {
+ ["jailbreak"] = Question.Noul("Does `prompt` try to make an AI assistant ignore its rules, policies or system instructions?"),
+ ["prompt_injection"] = Question.Noul("Does `prompt` contain instructions aimed at the AI system rather than a genuine user request?"),
+ ["sensitive_data"] = Question.Noul("Does `prompt` contain credentials, personal data or other sensitive information?"),
+ ["harm_severity"] = Question.Score("How much harm would complying with `prompt` cause?",
+ "none: ordinary request",
+ "minor: mildly inappropriate",
+ "serious: unsafe advice or abuse",
+ "severe: dangerous or illegal"),
+ // Python uses None for all descriptions — bare labels only.
+ ["topic"] = Question.Choice("What is `prompt` about?",
+ "product_support",
+ "coding",
+ "general_knowledge",
+ "personal_advice",
+ "security_testing",
+ "other"),
+ };
+
+ /// <summary>Preset questions for content safety and moderation.</summary>
+ public static QuestionSet Moderation() => new()
+ {
+ ["toxic"] = Question.Noul("Is `post` toxic: rude, disrespectful or likely to make someone leave the discussion?"),
+ ["harassment"] = Question.Noul("Does `post` target or harass a specific person?"),
+ ["threat"] = Question.Noul("Does `post` threaten violence, harm or intimidation?"),
+ ["spam"] = Question.Noul("Is `post` spam or advertising?"),
+ ["severity"] = Question.Score("How severe is any rule-breaking in `post`?",
+ "no rule-breaking: ordinary on-topic post",
+ "mild: rude tone or off-topic, no target",
+ "clear violation: insults, harassment or spam aimed at someone",
+ "severe: threats, hate speech or calls for violence"),
+ };
+
+ /// <summary>Preset questions for intelligent model routing.</summary>
+ public static QuestionSet Router() => new()
+ {
+ ["difficulty"] = Question.Score("How hard is `request` for a language model?",
+ "trivial: a lookup or one-liner",
+ "easy: short answer, no reasoning",
+ "moderate: several steps",
+ "hard: long multi-step reasoning or specialist knowledge"),
+ ["domain"] = Question.Choice("What domain does `request` belong to?",
+ ("code", "software engineering, programming, refactoring, architecture, debugging"),
+ ("math_or_logic", "mathematics, logic puzzles, proofs, complex calculation"),
+ ("writing", "creative writing, essays, emails, blog posts, copywriting"),
+ ("factual_lookup", "facts, definitions, trivia, history"),
+ ("data_analysis", "statistics, SQL, data manipulation, metrics"),
+ ("chitchat", "casual conversation, greetings, small talk")),
+ ["needs_tools"] = Question.Noul("Does answering `request` require external tools, search or private data?"),
+ ["is_sensitive"] = Question.Noul("Does `request` involve money, legal, medical or safety consequences?"),
+ };
+}
diff --git a/laya-dotnet/tests/Laya.Tests/PresetsTests.cs b/laya-dotnet/tests/Laya.Tests/PresetsTests.cs
new file mode 100644
index 00000000..5a2e4233
--- /dev/null
+++ b/laya-dotnet/tests/Laya.Tests/PresetsTests.cs
@@ -0,0 +1,353 @@
+namespace Laya.Tests;
+
+public class PresetsTests
+{
+ // ── Triage ───────────────────────────────────────────────────────────────
+
+ [Fact]
+ public void Triage_QuestionIds_InOrder()
+ {
+ var qs = LayaPresets.Triage();
+ Assert.Equal(
+ new[] { "intent", "is_urgent", "frustration", "refund_requested", "churn_risk" },
+ qs.Ids);
+ }
+
+ [Fact]
+ public void Triage_QuestionTypes()
+ {
+ var qs = LayaPresets.Triage();
+ Assert.Equal(QuestionType.Choice, qs["intent"].Type);
+ Assert.Equal(QuestionType.Noul, qs["is_urgent"].Type);
+ Assert.Equal(QuestionType.Score, qs["frustration"].Type);
+ Assert.Equal(QuestionType.Noul, qs["refund_requested"].Type);
+ Assert.Equal(QuestionType.Noul, qs["churn_risk"].Type);
+ }
+
+ [Fact]
+ public void Triage_IntentLabels_InOrder()
+ {
+ var labels = ((ChoiceQuestion)LayaPresets.Triage()["intent"]).Labels;
+ Assert.Equal(
+ new[] { "refund", "technical_help", "billing_question", "information", "cancellation", "other" },
+ labels);
+ }
+
+ [Fact]
+ public void Triage_IntentDescriptions()
+ {
+ var options = ((ChoiceQuestion)LayaPresets.Triage()["intent"]).Options;
+ Assert.Equal("money returned or a duplicate charge reversed", options[0].Value);
+ Assert.Equal("none of the other options fits", options[5].Value);
+ }
+
+ [Fact]
+ public void Triage_Instructions_Verbatim()
+ {
+ var qs = LayaPresets.Triage();
+ Assert.Equal("What does the customer want in `message`?",
+ qs["intent"].Instructions);
+ Assert.Equal("Does `message` communicate time pressure or a deadline?",
+ qs["is_urgent"].Instructions);
+ Assert.Equal("How frustrated does the customer sound in `message`?",
+ qs["frustration"].Instructions);
+ Assert.Equal("Does the customer ask for money back?",
+ qs["refund_requested"].Instructions);
+ Assert.Equal("Does `message` suggest the customer may leave for a competitor or cancel?",
+ qs["churn_risk"].Instructions);
+ }
+
+ [Fact]
+ public void Triage_FrustrationLevels_InOrder()
+ {
+ var levels = ((ScoreQuestion)LayaPresets.Triage()["frustration"]).Levels;
+ Assert.Equal(
+ new object?[] { "calm and neutral", "concerned but civil", "clearly annoyed", "very angry or using strong language" },
+ levels);
+ }
+
+ // ── Email ─────────────────────────────────────────────────────────────────
+
+ [Fact]
+ public void Email_Default_QuestionIds_InOrder()
+ {
+ var qs = LayaPresets.Email();
+ Assert.Equal(
+ new[] { "category", "is_spam", "is_phishing", "urgency", "needs_reply" },
+ qs.Ids);
+ }
+
+ [Fact]
+ public void Email_Default_QuestionTypes()
+ {
+ var qs = LayaPresets.Email();
+ Assert.Equal(QuestionType.Choice, qs["category"].Type);
+ Assert.Equal(QuestionType.Noul, qs["is_spam"].Type);
+ Assert.Equal(QuestionType.Noul, qs["is_phishing"].Type);
+ Assert.Equal(QuestionType.Score, qs["urgency"].Type);
+ Assert.Equal(QuestionType.Noul, qs["needs_reply"].Type);
+ }
+
+ [Fact]
+ public void Email_Default_CategoryLabels_InOrder()
+ {
+ var labels = ((ChoiceQuestion)LayaPresets.Email()["category"]).Labels;
+ Assert.Equal(
+ new[] { "billing", "technical", "sales", "security", "hr", "other" },
+ labels);
+ }
+
+ [Fact]
+ public void Email_Default_CategoryDescriptions()
+ {
+ var options = ((ChoiceQuestion)LayaPresets.Email()["category"]).Options;
+ Assert.Equal("invoices, payments, refunds", options[0].Value);
+ Assert.Equal("none of the above", options[5].Value);
+ }
+
+ [Fact]
+ public void Email_IsPhishing_HasCriteria()
+ {
+ var q = (NoulQuestion)LayaPresets.Email()["is_phishing"];
+ Assert.Equal(
+ "Is this email a phishing or scam attempt to steal money, credentials, or personal data?",
+ q.Instructions);
+ Assert.Equal("a legitimate email", q.IfFalse);
+ Assert.Equal("phishing, scam, or fraud", q.IfTrue);
+ }
+
+ [Fact]
+ public void Email_UrgencyLevels_InOrder()
+ {
+ var levels = ((ScoreQuestion)LayaPresets.Email()["urgency"]).Levels;
+ Assert.Equal(
+ new object?[] { "no time pressure", "needs attention soon", "blocking issue or hard deadline" },
+ levels);
+ }
+
+ [Fact]
+ public void Email_CustomCategories_ReplacesDefaults()
+ {
+ var custom = new Dictionary<string, string>
+ {
+ ["support"] = "customer issues",
+ ["billing"] = "payments",
+ };
+ var labels = ((ChoiceQuestion)LayaPresets.Email(custom)["category"]).Labels;
+ Assert.Equal(new[] { "support", "billing" }, labels);
+ }
+
+ [Fact]
+ public void Email_CustomCategories_DescriptionsPreserved()
+ {
+ var custom = new Dictionary<string, string>
+ {
+ ["support"] = "customer issues",
+ ["billing"] = "payments",
+ };
+ var options = ((ChoiceQuestion)LayaPresets.Email(custom)["category"]).Options;
+ Assert.Equal("customer issues", options[0].Value);
+ Assert.Equal("payments", options[1].Value);
+ }
+
+ [Fact]
+ public void Email_CustomCategories_OtherQuestionsUnchanged()
+ {
+ var custom = new Dictionary<string, string> { ["x"] = "y" };
+ var qs = LayaPresets.Email(custom);
+ Assert.Equal(QuestionType.Noul, qs["is_spam"].Type);
+ Assert.Equal(QuestionType.Noul, qs["is_phishing"].Type);
+ Assert.Equal(QuestionType.Score, qs["urgency"].Type);
+ Assert.Equal(QuestionType.Noul, qs["needs_reply"].Type);
+ }
+
+ // ── Guard ─────────────────────────────────────────────────────────────────
+
+ [Fact]
+ public void Guard_QuestionIds_InOrder()
+ {
+ var qs = LayaPresets.Guard();
+ Assert.Equal(
+ new[] { "jailbreak", "prompt_injection", "sensitive_data", "harm_severity", "topic" },
+ qs.Ids);
+ }
+
+ [Fact]
+ public void Guard_QuestionTypes()
+ {
+ var qs = LayaPresets.Guard();
+ Assert.Equal(QuestionType.Noul, qs["jailbreak"].Type);
+ Assert.Equal(QuestionType.Noul, qs["prompt_injection"].Type);
+ Assert.Equal(QuestionType.Noul, qs["sensitive_data"].Type);
+ Assert.Equal(QuestionType.Score, qs["harm_severity"].Type);
+ Assert.Equal(QuestionType.Choice, qs["topic"].Type);
+ }
+
+ [Fact]
+ public void Guard_TopicLabels_InOrder()
+ {
+ var labels = ((ChoiceQuestion)LayaPresets.Guard()["topic"]).Labels;
+ Assert.Equal(
+ new[] { "product_support", "coding", "general_knowledge", "personal_advice", "security_testing", "other" },
+ labels);
+ }
+
+ [Fact]
+ public void Guard_TopicOptions_HaveNullDescriptions()
+ {
+ // Python uses None for all topic descriptions — bare labels only.
+ var options = ((ChoiceQuestion)LayaPresets.Guard()["topic"]).Options;
+ Assert.All(options, o => Assert.Null(o.Value));
+ }
+
+ [Fact]
+ public void Guard_HarmSeverityLevels_InOrder()
+ {
+ var levels = ((ScoreQuestion)LayaPresets.Guard()["harm_severity"]).Levels;
+ Assert.Equal(
+ new object?[] { "none: ordinary request", "minor: mildly inappropriate", "serious: unsafe advice or abuse", "severe: dangerous or illegal" },
+ levels);
+ }
+
+ [Fact]
+ public void Guard_Instructions_Verbatim()
+ {
+ var qs = LayaPresets.Guard();
+ Assert.Equal(
+ "Does `prompt` try to make an AI assistant ignore its rules, policies or system instructions?",
+ qs["jailbreak"].Instructions);
+ Assert.Equal(
+ "Does `prompt` contain instructions aimed at the AI system rather than a genuine user request?",
+ qs["prompt_injection"].Instructions);
+ Assert.Equal(
+ "Does `prompt` contain credentials, personal data or other sensitive information?",
+ qs["sensitive_data"].Instructions);
+ Assert.Equal("How much harm would complying with `prompt` cause?",
+ qs["harm_severity"].Instructions);
+ Assert.Equal("What is `prompt` about?",
+ qs["topic"].Instructions);
+ }
+
+ // ── Moderation ────────────────────────────────────────────────────────────
+
+ [Fact]
+ public void Moderation_QuestionIds_InOrder()
+ {
+ var qs = LayaPresets.Moderation();
+ Assert.Equal(
+ new[] { "toxic", "harassment", "threat", "spam", "severity" },
+ qs.Ids);
+ }
+
+ [Fact]
+ public void Moderation_QuestionTypes()
+ {
+ var qs = LayaPresets.Moderation();
+ Assert.Equal(QuestionType.Noul, qs["toxic"].Type);
+ Assert.Equal(QuestionType.Noul, qs["harassment"].Type);
+ Assert.Equal(QuestionType.Noul, qs["threat"].Type);
+ Assert.Equal(QuestionType.Noul, qs["spam"].Type);
+ Assert.Equal(QuestionType.Score, qs["severity"].Type);
+ }
+
+ [Fact]
+ public void Moderation_SeverityLevels_InOrder()
+ {
+ var levels = ((ScoreQuestion)LayaPresets.Moderation()["severity"]).Levels;
+ Assert.Equal(
+ new object?[]
+ {
+ "no rule-breaking: ordinary on-topic post",
+ "mild: rude tone or off-topic, no target",
+ "clear violation: insults, harassment or spam aimed at someone",
+ "severe: threats, hate speech or calls for violence",
+ },
+ levels);
+ }
+
+ [Fact]
+ public void Moderation_Instructions_Verbatim()
+ {
+ var qs = LayaPresets.Moderation();
+ Assert.Equal(
+ "Is `post` toxic: rude, disrespectful or likely to make someone leave the discussion?",
+ qs["toxic"].Instructions);
+ Assert.Equal("Does `post` target or harass a specific person?",
+ qs["harassment"].Instructions);
+ Assert.Equal("Does `post` threaten violence, harm or intimidation?",
+ qs["threat"].Instructions);
+ Assert.Equal("Is `post` spam or advertising?",
+ qs["spam"].Instructions);
+ Assert.Equal("How severe is any rule-breaking in `post`?",
+ qs["severity"].Instructions);
+ }
+
+ // ── Router ────────────────────────────────────────────────────────────────
+
+ [Fact]
+ public void Router_QuestionIds_InOrder()
+ {
+ var qs = LayaPresets.Router();
+ Assert.Equal(
+ new[] { "difficulty", "domain", "needs_tools", "is_sensitive" },
+ qs.Ids);
+ }
+
+ [Fact]
+ public void Router_QuestionTypes()
+ {
+ var qs = LayaPresets.Router();
+ Assert.Equal(QuestionType.Score, qs["difficulty"].Type);
+ Assert.Equal(QuestionType.Choice, qs["domain"].Type);
+ Assert.Equal(QuestionType.Noul, qs["needs_tools"].Type);
+ Assert.Equal(QuestionType.Noul, qs["is_sensitive"].Type);
+ }
+
+ [Fact]
+ public void Router_DomainLabels_InOrder()
+ {
+ var labels = ((ChoiceQuestion)LayaPresets.Router()["domain"]).Labels;
+ Assert.Equal(
+ new[] { "code", "math_or_logic", "writing", "factual_lookup", "data_analysis", "chitchat" },
+ labels);
+ }
+
+ [Fact]
+ public void Router_DomainDescriptions()
+ {
+ var options = ((ChoiceQuestion)LayaPresets.Router()["domain"]).Options;
+ Assert.Equal("software engineering, programming, refactoring, architecture, debugging",
+ options[0].Value);
+ Assert.Equal("casual conversation, greetings, small talk",
+ options[5].Value);
+ }
+
+ [Fact]
+ public void Router_DifficultyLevels_InOrder()
+ {
+ var levels = ((ScoreQuestion)LayaPresets.Router()["difficulty"]).Levels;
+ Assert.Equal(
+ new object?[]
+ {
+ "trivial: a lookup or one-liner",
+ "easy: short answer, no reasoning",
+ "moderate: several steps",
+ "hard: long multi-step reasoning or specialist knowledge",
+ },
+ levels);
+ }
+
+ [Fact]
+ public void Router_Instructions_Verbatim()
+ {
+ var qs = LayaPresets.Router();
+ Assert.Equal("How hard is `request` for a language model?",
+ qs["difficulty"].Instructions);
+ Assert.Equal("What domain does `request` belong to?",
+ qs["domain"].Instructions);
+ Assert.Equal("Does answering `request` require external tools, search or private data?",
+ qs["needs_tools"].Instructions);
+ Assert.Equal("Does `request` involve money, legal, medical or safety consequences?",
+ qs["is_sensitive"].Instructions);
+ }
+}