Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: fine-tune Laya and Cloudflare Clef decision models and serve them (#12585)

Nilay6df2e235a32a
diff --git a/.github/workflows/studio-backend-ci.yml b/.github/workflows/studio-backend-ci.yml
index 7a03d2c763d..7a30863fc7c 100644
--- a/.github/workflows/studio-backend-ci.yml
+++ b/.github/workflows/studio-backend-ci.yml
@@ -285,6 +285,15 @@ jobs:
tests/test_media_auto_switch.py \
tests/test_pr5624_regressions.py
+ - name: Decision model training tests
+ # Their worker imports unsloth, so unsloth_zoo is installed here, after the suite above ran
+ # without it. trl stays at Studio's pin, which keeps datasets at the studio.txt version.
+ if: matrix.scope == 'full' && matrix.shard == 'a-k'
+ working-directory: studio/backend
+ run: |
+ pip install unsloth_zoo "$(grep -m1 -E '^trl==' requirements/extras-no-deps.txt)"
+ python -m pytest -q --tb=short --timeout=330 tests/test_decision_training.py
+
- name: Pre-3.12 branches, on the newest interpreter that takes them
if: matrix.scope == 'floor-spot-check'
working-directory: studio/backend
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 7b5ad271036..33d69d88139 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -34,7 +34,7 @@ repos:
# Mirror ruff's [tool.ruff] extend-exclude so this hook does not
# half-process files ruff itself skips (which produced churn). vendor/ is
# repeated here because this hook does not read ruff's config.
- exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$|^studio/backend/vendor/'
+ exclude: '(chat_templates|ollama_template_mappers|_auto_install|mapper)\.py$|^studio/backend/vendor/|^unsloth/_vendor/'
additional_dependencies:
- ruff==0.6.9
# Re-pins allowScripts entries after dependency bumps. pre-commit.ci
diff --git a/pyproject.toml b/pyproject.toml
index 5462165c761..ef1cf4b607a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -54,6 +54,7 @@ version = {attr = "unsloth._version.__version__"}
include-package-data = true
[tool.setuptools.package-data]
+"unsloth._vendor.clef" = ["LICENSE", "README.md", "clef_manifest.json"]
unsloth_cli = ["codex_fallback_prompt.md", "pi_subagent.ts"]
studio = [
"*.sh",
@@ -1767,6 +1768,7 @@ extend-exclude = [
"*mapper.py",
# Vendored upstream source: reformatting it would break the digest test.
"studio/backend/vendor/",
+ "unsloth/_vendor/",
]
[tool.ruff.lint]
diff --git a/scripts/clef_train_bench.py b/scripts/clef_train_bench.py
new file mode 100644
index 00000000000..752ff341b05
--- /dev/null
+++ b/scripts/clef_train_bench.py
@@ -0,0 +1,305 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+
+"""Clef training step benchmark and head parity check, one JSON line on stdout.
+
+python scripts/clef_train_bench.py --model Cloudflare/clef-flash --load-in-4bit --seq-len 8192
+python scripts/clef_train_bench.py --model tiny --fast off --dtype fp16
+
+--fast on|off sets UNSLOTH_CLEF_FAST (Unsloth's batched, chunked, checkpointed and compiled head
+vs the per-record head). Whatever the arm, the first batch's head is also run both ways on the same
+hidden states, so `parity` compares the two heads' logits and gradients in this process.
+"""
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+import time
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--model", default = "tiny", help = "tiny, a Clef repo id or folder")
+parser.add_argument("--load-in-4bit", action = "store_true")
+parser.add_argument("--fast", choices = ["on", "off"], default = "on")
+parser.add_argument("--dtype", choices = ["bf16", "fp16"], default = "bf16")
+parser.add_argument("--seq-len", type = int, default = 4096)
+parser.add_argument("--batch-size", type = int, default = 1)
+parser.add_argument("--questions", type = int, default = 8)
+parser.add_argument("--steps", type = int, default = 6)
+parser.add_argument("--warmup", type = int, default = 2)
+parser.add_argument("--log-recompiles", action = "store_true")
+args = parser.parse_args()
+os.environ["UNSLOTH_CLEF_FAST"] = "1" if args.fast == "on" else "0"
+
+import torch # noqa: E402
+
+from unsloth import FastDecisionModel # noqa: E402
+from unsloth.models import clef, decision # noqa: E402
+
+if args.log_recompiles:
+ torch._logging.set_logs(recompiles = True, graph_breaks = True)
+
+TINY = "trl-internal-testing/tiny-Qwen3_5ForConditionalGeneration"
+TINY_HEAD = dict(hidden_size = 8, width = 32, routing_layers = 2, layers = 2, heads = 4, feedforward = 64)
+
+
+def tiny_checkpoint() -> str:
+ from safetensors.torch import save_file
+ from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
+
+ folder = os.path.join(tempfile.mkdtemp(prefix = "clef_tiny_"), "clef")
+ torch.manual_seed(0)
+ backbone = Qwen3_5ForConditionalGeneration.from_pretrained(TINY, dtype = torch.bfloat16)
+ backbone.save_pretrained(folder)
+ AutoProcessor.from_pretrained(TINY).save_pretrained(folder)
+ head = clef.JointSchemaHead(
+ **{**TINY_HEAD, "hidden_size": backbone.config.text_config.hidden_size}
+ )
+ with torch.no_grad():
+ for parameter in head.parameters():
+ parameter.add_(torch.randn_like(parameter) * 0.1)
+ save_file(
+ {k: v.to(torch.bfloat16) for k, v in head.state_dict().items()},
+ f"{folder}/joint_head.safetensors",
+ )
+ with open(f"{folder}/joint_head_config.json", "w") as file:
+ json.dump(head.config, file)
+ return folder
+
+
+def rows(tokenizer, count):
+ # A long state filled to about --seq-len tokens, and --questions questions of 2 to 6 options.
+ filler = "The customer reports intermittent checkout failures across several regions. "
+ per = len(tokenizer(filler, add_special_tokens = False).input_ids)
+ state = filler * max(1, (args.seq_len - 120 * args.questions - 200) // per)
+ out = []
+ for index in range(count):
+ questions, gold = {}, {}
+ for q in range(args.questions):
+ options = [f"option {o} for field {q}" for o in range(2 + (q + index) % 5)]
+ kind = ("choice", "score", "noul")[q % 3]
+ if kind == "noul":
+ questions[f"f{q}"] = {"type": "noul", "instructions": f"Is statement {q} true?"}
+ gold[f"f{q}"] = {"label": "true" if (q + index) % 2 else "false"}
+ elif kind == "score":
+ questions[f"f{q}"] = {
+ "type": "score",
+ "instructions": f"Rate {q}",
+ "criteria": options,
+ }
+ gold[f"f{q}"] = {"label": (q + index) % len(options)}
+ else:
+ questions[f"f{q}"] = {
+ "type": "choice",
+ "instructions": f"Pick {q}",
+ "criteria": {f"o{o}": text for o, text in enumerate(options)},
+ }
+ gold[f"f{q}"] = {"label": f"o{index % len(options)}"}
+ out.append({"state": f"{index}: {state}", "questions": questions, "gold": gold})
+ return out
+
+
+def head_parity(model, batch, amp):
+ # Same hidden states into the batched and the per-record head. Each is scored against the
+ # per-record head with autocast off (fp32 head, the oracle): under bf16 autocast both heads
+ # round their matmuls, so the batched head passes when its error is at most 1.5x the
+ # per-record head's plus one bf16 rounding step (kernel_verify_workflow step 2).
+ backbone = model._backbone()
+ text_model = getattr(backbone.model, "language_model", backbone.model)
+ with torch.no_grad():
+ hidden = text_model(
+ input_ids = batch["input_ids"], attention_mask = batch["attention_mask"], use_cache = False
+ ).last_hidden_state
+ embedding = backbone.get_output_embeddings().weight.detach()
+ head = model.head
+ os.environ["UNSLOTH_CLEF_FAST"] = "1"
+
+ def run(forward, autocast):
+ head.zero_grad()
+ h = hidden.detach().clone().requires_grad_(True)
+ with torch.autocast("cuda", dtype = amp or torch.float32, enabled = autocast):
+ out = forward(
+ h, batch["input_ids"], batch["attention_mask"], batch["records"], embedding
+ )
+ flat = [q for record in out for q in record]
+ padded = torch.full((len(flat), max(len(z) for z in flat)), -1e4, device = h.device)
+ for i, z in enumerate(flat):
+ padded[i, : len(z)] = z.float()
+ generator = torch.Generator(device = h.device).manual_seed(0)
+ grad = torch.randn(padded.shape, device = h.device, generator = generator)
+ (padded * grad * (padded > -1e3)).sum().backward()
+ grads = {
+ n: p.grad.detach().float().clone()
+ for n, p in head.named_parameters()
+ if p.grad is not None
+ }
+ return padded.detach(), h.grad.detach().float(), grads
+
+ oracle = run(head.forward_per_record, False)
+ ours = run(head.forward, amp is not None)
+ reference = run(head.forward_per_record, amp is not None)
+ os.environ["UNSLOTH_CLEF_FAST"] = "1" if args.fast == "on" else "0"
+ head.zero_grad()
+ valid = oracle[0] > -1e3
+
+ def errors(got):
+ return {
+ "logits_max_abs": (got[0] - oracle[0])[valid].abs().max().item(),
+ "hidden_grad_rel_l2": ((got[1] - oracle[1]).norm() / oracle[1].norm()).item(),
+ "param_grad_rel_l2": max(
+ ((got[2][n] - oracle[2][n]).norm() / oracle[2][n].norm().clamp_min(1e-30)).item()
+ for n in oracle[2]
+ ),
+ }
+
+ ours_error, reference_error = errors(ours), errors(reference)
+ step = 2**-8 if amp is not None else 2**-20
+ scale = oracle[0][valid].abs().max().item()
+ allowed = {
+ "logits_max_abs": 1.5 * reference_error["logits_max_abs"] + step * scale,
+ "hidden_grad_rel_l2": 1.5 * reference_error["hidden_grad_rel_l2"] + step,
+ "param_grad_rel_l2": 1.5 * reference_error["param_grad_rel_l2"] + step,
+ }
+ return {
+ "batched_vs_oracle": ours_error,
+ "per_record_vs_oracle": reference_error,
+ "argmax_equal": bool(torch.equal(ours[0].argmax(-1), reference[0].argmax(-1))),
+ "verdict": "PASS" if all(ours_error[k] <= allowed[k] for k in allowed) else "FAIL",
+ }
+
+
+def head_cost(model, batch, amp):
+ # Head forward + backward alone on detached hidden states: time and memory above the inputs.
+ backbone = model._backbone()
+ text_model = getattr(backbone.model, "language_model", backbone.model)
+ with torch.no_grad():
+ hidden = text_model(
+ input_ids = batch["input_ids"], attention_mask = batch["attention_mask"], use_cache = False
+ ).last_hidden_state
+ embedding = backbone.get_output_embeddings().weight.detach()
+ times = []
+ for i in range(args.warmup + 3):
+ torch.cuda.synchronize()
+ torch.cuda.reset_peak_memory_stats()
+ base = torch.cuda.memory_allocated()
+ start = time.perf_counter()
+ h = hidden.detach().requires_grad_(True)
+ with torch.autocast("cuda", dtype = amp or torch.float32, enabled = amp is not None):
+ out = model.head(
+ h, batch["input_ids"], batch["attention_mask"], batch["records"], embedding
+ )
+ logits = getattr(out, "flat_padded", None)
+ if logits is None:
+ logits = torch.cat([q.sum().reshape(1) for record in out for q in record])
+ logits.float().sum().backward()
+ torch.cuda.synchronize()
+ if i >= args.warmup:
+ times.append(time.perf_counter() - start)
+ peak = torch.cuda.max_memory_allocated() - base
+ model.head.zero_grad()
+ times.sort()
+ return {"head_ms": 1000 * times[len(times) // 2], "head_peak_gb": peak / 2**30}
+
+
+def _graphs():
+ from torch._dynamo.utils import counters
+ return counters["stats"]["unique_graphs"]
+
+
+def main():
+ model_name = tiny_checkpoint() if args.model == "tiny" else args.model
+ dtype = torch.float16 if args.dtype == "fp16" else torch.bfloat16
+ model, processor = FastDecisionModel.from_pretrained(
+ model_name, max_seq_length = args.seq_len, load_in_4bit = args.load_in_4bit, dtype = dtype
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 16, lora_alpha = 16)
+ count = args.batch_size * (args.steps + args.warmup)
+ items, report = FastDecisionModel.build_dataset(
+ rows(processor.tokenizer, count), processor, model
+ )
+ if not items:
+ sys.exit(f"no items: {report}")
+ tokenizer = getattr(processor, "tokenizer", processor)
+ collate = decision.ClefDataCollator(tokenizer.pad_token_id)
+ device = next(model.parameters()).device
+ batches = []
+ for start in range(0, len(items), args.batch_size):
+ batch = collate(items[start : start + args.batch_size])
+ batches.append({k: v.to(device) if torch.is_tensor(v) else v for k, v in batch.items()})
+ model.train()
+ amp = torch.bfloat16 if dtype == torch.bfloat16 and torch.cuda.is_bf16_supported() else None
+ parity = head_parity(model, batches[0], amp)
+ cost = head_cost(model, batches[0], amp)
+ optimizer = torch.optim.AdamW([p for p in model.parameters() if p.requires_grad], lr = 1e-5)
+ times, losses, all_times, graphs_after_step = [], [], [], []
+ torch.cuda.reset_peak_memory_stats()
+ for index, batch in enumerate(batches[: args.steps + args.warmup]):
+ batch = dict(batch)
+ target = batch.pop("target")
+ torch.cuda.synchronize()
+ start = time.perf_counter()
+ with torch.autocast("cuda", dtype = amp or torch.float32, enabled = amp is not None):
+ logits, _ = model(**batch)
+ loss = decision._soft_cross_entropy(logits, target, batch["marker_mask"])
+ loss.backward()
+ optimizer.step()
+ optimizer.zero_grad(set_to_none = True)
+ torch.cuda.synchronize()
+ all_times.append(round(time.perf_counter() - start, 4))
+ graphs_after_step.append(_graphs())
+ if index >= args.warmup:
+ times.append(all_times[-1])
+ losses.append(round(loss.item(), 5))
+ times.sort()
+ step = times[len(times) // 2]
+ from torch._dynamo.utils import compile_times, counters
+
+ names, values = compile_times(repr = "csv", aggregate = True)
+ compiled_frames = dict(zip(names, values))
+ print(
+ "JOB_RESULT "
+ + json.dumps(
+ {
+ "model": args.model,
+ "load_in_4bit": args.load_in_4bit,
+ "fast": args.fast,
+ "dtype": args.dtype,
+ "seq_len": args.seq_len,
+ "tokens_per_row": len(items[0]["input_ids"]),
+ "batch_size": args.batch_size,
+ "s_per_step": round(step, 4),
+ "s_per_step_spread": [round(times[0], 4), round(times[-1], 4)],
+ "peak_alloc_gb": round(torch.cuda.max_memory_allocated() / 2**30, 3),
+ "peak_reserved_gb": round(torch.cuda.max_memory_reserved() / 2**30, 3),
+ "head_ms": round(cost["head_ms"], 2),
+ "head_share": round(cost["head_ms"] / 1000 / step, 4),
+ "head_peak_gb": round(cost["head_peak_gb"], 3),
+ "losses": losses,
+ "step_times": all_times,
+ "graphs_after_step": graphs_after_step,
+ "graph_breaks": sum(counters["graph_break"].values()),
+ "graph_break_reasons": list(counters["graph_break"])[:10],
+ "unique_graphs": counters["stats"]["unique_graphs"],
+ "compile_frames": compiled_frames,
+ "parity": parity,
+ "levers": {
+ "batched_head": os.environ.get("UNSLOTH_CLEF_FAST") != "0",
+ "chunked_norm_pool": os.environ.get("UNSLOTH_CLEF_FAST") != "0",
+ "head_checkpoint": os.environ.get("UNSLOTH_CLEF_FAST") != "0"
+ and os.environ.get("UNSLOTH_CLEF_CHECKPOINT", "1") != "0",
+ "head_compile": os.environ.get("UNSLOTH_CLEF_FAST") != "0"
+ and clef._compile_supported(device)
+ and "function" in clef._COMPILED,
+ },
+ "gpu": torch.cuda.get_device_name(),
+ "torch": torch.__version__,
+ "unsloth_file": sys.modules["unsloth"].__file__,
+ }
+ ),
+ flush = True,
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/risky_loaders_baseline.json b/scripts/risky_loaders_baseline.json
index e8e985fdf5a..1795904d690 100644
--- a/scripts/risky_loaders_baseline.json
+++ b/scripts/risky_loaders_baseline.json
@@ -538,6 +538,14 @@
"count": 1,
"reason": "Reads back a .pt file this function just wrote with torch.save into the local offload folder; never a downloaded file."
},
+ {
+ "file": "unsloth/models/decision.py",
+ "rule": "dynamic-import",
+ "sink": "spec_from_file_location",
+ "digest": "3738585f7559a2ad",
+ "count": 1,
+ "reason": "Imports the laya copy vendored in this repository at a fixed path (studio/backend/vendor/laya/__init__.py); never a downloaded or user-supplied file."
+ },
{
"file": "unsloth/models/loader.py",
"rule": "dynamic-import",
diff --git a/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef-flash.yaml b/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef-flash.yaml
new file mode 100644
index 00000000000..3aa639b9f08
--- /dev/null
+++ b/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef-flash.yaml
@@ -0,0 +1,29 @@
+# Model defaults for Cloudflare/clef-flash decision models (Qwen3.5 9B backbone + joint schema head)
+# Local Clef folders and Studio Clef fine-tunes use these too
+
+training:
+ max_seq_length: 4096
+ num_epochs: 1
+ learning_rate: 2e-4
+ batch_size: 4
+ gradient_accumulation_steps: 2
+ warmup_steps: 5
+ max_steps: 0
+ weight_decay: 0.01
+ random_seed: 3407
+ packing: false
+ train_on_completions: false
+ gradient_checkpointing: "unsloth"
+ optim: "adamw_8bit"
+ lr_scheduler_type: "linear"
+
+lora:
+ lora_r: 16
+ lora_alpha: 16
+ lora_dropout: 0.0
+
+logging:
+ enable_wandb: false
+ wandb_project: "decision-finetuning"
+ enable_tensorboard: false
+ log_frequency: 1
diff --git a/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef.yaml b/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef.yaml
new file mode 100644
index 00000000000..9122d05793b
--- /dev/null
+++ b/studio/backend/assets/configs/model_defaults/decision/Cloudflare_clef.yaml
@@ -0,0 +1,28 @@
+# Model defaults for Cloudflare/clef decision models (Qwen3.8 27B backbone + joint schema head)
+
+training:
+ max_seq_length: 4096
+ num_epochs: 1
+ learning_rate: 2e-4
+ batch_size: 4
+ gradient_accumulation_steps: 2
+ warmup_steps: 5
+ max_steps: 0
+ weight_decay: 0.01
+ random_seed: 3407
+ packing: false
+ train_on_completions: false
+ gradient_checkpointing: "unsloth"
+ optim: "adamw_8bit"
+ lr_scheduler_type: "linear"
+
+lora:
+ lora_r: 16
+ lora_alpha: 16
+ lora_dropout: 0.0
+
+logging:
+ enable_wandb: false
+ wandb_project: "decision-finetuning"
+ enable_tensorboard: false
+ log_frequency: 1
diff --git a/studio/backend/assets/configs/model_defaults/decision/convaiinnovations_laya.yaml b/studio/backend/assets/configs/model_defaults/decision/convaiinnovations_laya.yaml
new file mode 100644
index 00000000000..a6accfaa734
--- /dev/null
+++ b/studio/backend/assets/configs/model_defaults/decision/convaiinnovations_laya.yaml
@@ -0,0 +1,29 @@
+# Model defaults for convaiinnovations/laya decision models
+# learning_rate is for LoRA; Full Finetuning starts at 2.5e-5 instead, Laya's own encoder learning rate
+# Local Laya checkpoints, earlier Studio decision fine-tunes included, use these too
+
+training:
+ num_epochs: 4
+ learning_rate: 8e-4
+ batch_size: 8
+ gradient_accumulation_steps: 8
+ warmup_steps: 0
+ max_steps: 0
+ weight_decay: 0.01
+ random_seed: 3407
+ packing: false
+ train_on_completions: false
+ gradient_checkpointing: "unsloth"
+ optim: "adamw_torch"
+ lr_scheduler_type: "cosine"
+
+lora:
+ lora_r: 64
+ lora_alpha: 64
+ lora_dropout: 0.0
+
+logging:
+ enable_wandb: false
+ wandb_project: "decision-finetuning"
+ enable_tensorboard: false
+ log_frequency: 1
diff --git a/studio/backend/core/systemone/catalog.py b/studio/backend/core/systemone/catalog.py
index 11e3e0f3742..049e65e6c2f 100644
--- a/studio/backend/core/systemone/catalog.py
+++ b/studio/backend/core/systemone/catalog.py
@@ -10,6 +10,8 @@ from dataclasses import dataclass
from pathlib import Path
LAYA_REPO = "convaiinnovations/laya"
+# Recipe for Clef folders that have no model defaults of their own (local copies, fine-tunes).
+CLEF_DEFAULTS_REPO = "Cloudflare/clef-flash"
@dataclass(frozen = True)
@@ -19,6 +21,8 @@ class Checkpoint:
subfolder: str | None
description: str
download_bytes: int = 0
+ # "laya" (rl_agent_config.json + encoder) or "clef" (Qwen3.5 backbone + joint schema head).
+ layout: str = "laya"
@property
def is_local(self) -> bool:
@@ -49,6 +53,22 @@ CHECKPOINTS = {
"Laya English fine-tuned on four typed-decision workflows, 1024-token context.",
846_195_716,
),
+ Checkpoint(
+ "clef-flash",
+ "Cloudflare/clef-flash",
+ None,
+ "Cloudflare Clef-flash on Qwen3.5 9B: fast multimodal decisions, needs a GPU.",
+ 19_063_259_136,
+ "clef",
+ ),
+ Checkpoint(
+ "clef",
+ "Cloudflare/clef",
+ None,
+ "Cloudflare Clef on Qwen3.8 27B: the most accurate decisions, needs a large GPU.",
+ 54_976_000_000,
+ "clef",
+ ),
)
}
@@ -56,6 +76,87 @@ CHECKPOINTS = {
DEFAULT_ALIASES = frozenset({"default", "laya", "jev-latest", "jev-preview", "openjev-latest"})
LOCAL_NAME = "laya-local"
CONNECTION_PREFIX = "connection:"
+FINE_TUNE_PREFIX = "laya-ft:"
+CLEF_FINE_TUNE_PREFIX = "clef-ft:"
+FINE_TUNE_PREFIXES = (FINE_TUNE_PREFIX, CLEF_FINE_TUNE_PREFIX)
+
+
+CLEF_NEEDS_GPU = (
+ "Clef models need an NVIDIA or AMD GPU; this machine has none. Use a Laya model instead."
+)
+
+
+def clef_unsupported_reason(wait: bool = True) -> str | None:
+ # ROCm reports DeviceType.CUDA too. A failed probe answers None: detection only ever widens.
+ # wait=False reads only a finished detection, so a settings read never waits on torch import.
+ try:
+ from utils.hardware import hardware
+
+ device = hardware.get_device() if wait else hardware.DEVICE
+ if device is None:
+ return None
+ return None if device == hardware.DeviceType.CUDA else CLEF_NEEDS_GPU
+ except Exception:
+ return None
+
+
+def is_fine_tune_name(name: object) -> bool:
+ return isinstance(name, str) and name.startswith(FINE_TUNE_PREFIXES)
+
+
+def _owner_outputs() -> Path:
+ from utils.account_context import OWNER, run_as
+ from utils.paths import outputs_root
+ return run_as(OWNER, outputs_root).resolve()
+
+
+def _fine_tune_in(root: Path, folder_name: str) -> Checkpoint | None:
+ from utils.models.model_config import CLEF_MARKERS
+
+ from .laya_runtime import is_cached
+
+ # Dot folders include runs staged for deletion (.<name>.deleting-<id>).
+ if not folder_name or folder_name.startswith("."):
+ return None
+ folder = root / folder_name
+ try:
+ if folder.resolve().parent != root:
+ return None
+ except (OSError, RuntimeError, ValueError):
+ # A NUL byte or a symlink loop in a caller's name.
+ return None
+ if all((folder / name).is_file() for name in CLEF_MARKERS):
+ checkpoint = Checkpoint(
+ CLEF_FINE_TUNE_PREFIX + folder_name,
+ str(folder),
+ None,
+ "Clef fine-tuned in Studio.",
+ layout = "clef",
+ )
+ else:
+ checkpoint = Checkpoint(
+ FINE_TUNE_PREFIX + folder_name, str(folder), None, "Laya fine-tuned in Studio."
+ )
+ return checkpoint if is_cached(checkpoint) else None
+
+
+def fine_tune(name: str) -> Checkpoint | None:
+ # Either prefix finds the run; the answer carries the one for the folder's layout.
+ if not is_fine_tune_name(name):
+ return None
+ folder_name = name.partition(":")[2]
+ if "/" in folder_name or "\\" in folder_name:
+ return None
+ return _fine_tune_in(_owner_outputs(), folder_name)
+
+
+def fine_tunes() -> list[Checkpoint]:
+ root = _owner_outputs()
+ try:
+ folders = sorted(p.name for p in root.iterdir() if p.is_dir())
+ except OSError:
+ return []
+ return [c for name in folders if (c := _fine_tune_in(root, name)) is not None]
@dataclass(frozen = True)
@@ -107,7 +208,14 @@ def default_checkpoint() -> Checkpoint | Connection:
return CHECKPOINTS[configured]
if connection := parse_connection(configured):
return connection
+ if (checkpoint := fine_tune(configured)) is not None:
+ return checkpoint
subfolder = os.environ.get("UNSLOTH_SYSTEMONE_SUBFOLDER", "").strip() or None
+ from utils.models.model_config import CLEF_MARKERS
+
+ folder = Path(configured).expanduser()
+ if subfolder is None and all((folder / name).is_file() for name in CLEF_MARKERS):
+ return Checkpoint(LOCAL_NAME, configured, None, "Local Clef checkpoint.", layout = "clef")
return Checkpoint(LOCAL_NAME, configured, subfolder, "Local Laya checkpoint.")
@@ -118,4 +226,12 @@ def resolve(model: str) -> Checkpoint | Connection | None:
if name == LOCAL_NAME or name.startswith(CONNECTION_PREFIX):
checkpoint = default_checkpoint()
return checkpoint if checkpoint.name == name else None
- return CHECKPOINTS.get(name)
+ if name in CHECKPOINTS:
+ return CHECKPOINTS[name]
+ from utils.account_context import is_owner_context
+
+ checkpoint = fine_tune(name)
+ # Other accounts reach only the fine-tune the owner configured, not the owner's other outputs.
+ if checkpoint is None or is_owner_context() or checkpoint == default_checkpoint():
+ return checkpoint
+ return None
diff --git a/studio/backend/core/systemone/clef_runtime.py b/studio/backend/core/systemone/clef_runtime.py
new file mode 100644
index 00000000000..3add0cae7e4
--- /dev/null
+++ b/studio/backend/core/systemone/clef_runtime.py
@@ -0,0 +1,244 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Cloudflare Clef decision models for the Decision API, served from a spawn child.
+
+Clef is a Qwen3.5 / Qwen3.8 backbone (9B or 27B) with a joint schema head, so it only runs on a
+GPU, through Unsloth's loader and its fast linear attention kernels. Unsloth patches transformers
+process-wide and a CUDA context is never returned while its process lives, so the model gets its
+own process: unloading ends it and the memory goes with it (as core/inference/stt_transformers_worker.py).
+"""
+
+from __future__ import annotations
+
+import multiprocessing as mp
+import os
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+_CTX = mp.get_context("spawn")
+_BACKEND_PATH = str(Path(__file__).resolve().parent.parent.parent)
+LOAD_TIMEOUT_S = 1800.0
+DECIDE_TIMEOUT_S = 300.0
+CLOSE_TIMEOUT_S = 10.0
+# Clef's own default; the model reads 64K, but a longer prompt only costs prefill memory.
+MAX_LENGTH = 16384
+# bf16 weights plus activations must fit, else the backbone loads in 4-bit.
+_BF16_HEADROOM = 1.2
+
+
+class ClefWorkerError(RuntimeError):
+ pass
+
+
+def _weight_bytes(folder: Path) -> int:
+ return sum(path.stat().st_size for path in folder.glob("model*.safetensors"))
+
+
+class _Events:
+ # The training worker's installers report progress to a queue; nobody watches this one.
+ def put(self, event) -> None:
+ pass
+
+
+def _fast_paths(folder: str) -> None:
+ # The same prebuilt causal-conv1d a Qwen3.5 training run gets; the gated delta kernels ship with
+ # unsloth_zoo. A failed install leaves transformers' torch path, which is slower but right.
+ try:
+ from core.training.worker import _ensure_causal_conv1d_fast_path, _install_fast_path_hooks
+ _ensure_causal_conv1d_fast_path(_Events(), folder, required = True)
+ _install_fast_path_hooks(_Events(), folder, install_causal_conv1d = True)
+ except Exception as exc:
+ print(f"Clef: causal-conv1d fast path unavailable ({exc}); using the torch path.")
+
+
+def _load(folder: str):
+ import torch
+
+ from core.import_guards import ensure_real_packages
+
+ _fast_paths(folder)
+ ensure_real_packages("unsloth_zoo", "unsloth")
+ from unsloth import FastDecisionModel
+
+ if not torch.cuda.is_available():
+ raise ClefWorkerError("Clef needs an NVIDIA GPU; this machine has none torch can use.")
+ free, _ = torch.cuda.mem_get_info()
+ load_in_4bit = free < _weight_bytes(Path(folder)) * _BF16_HEADROOM
+ model, processor = FastDecisionModel.from_pretrained(
+ folder,
+ max_seq_length = MAX_LENGTH,
+ load_in_4bit = load_in_4bit,
+ use_gradient_checkpointing = False,
+ )
+ FastDecisionModel.for_inference(model)
+ return model, getattr(processor, "tokenizer", processor), load_in_4bit
+
+
+def _decide(model, tokenizer, state, questions: dict[str, dict[str, Any]]) -> dict[str, Any]:
+ import torch
+
+ from unsloth.models.clef import encode_record, systemone_answer
+ from unsloth.models.decision import QUESTION_TYPES, _clef_amp_dtype, _served_temperatures
+
+ encoded = encode_record(
+ tokenizer, {"state": state, "questions": questions}, max_length = MAX_LENGTH
+ )
+ device = next(model.parameters()).device
+ ids = torch.tensor([encoded.input_ids], device = device)
+ amp_dtype = _clef_amp_dtype(model, device)
+ with (
+ torch.inference_mode(),
+ torch.autocast(device.type, dtype = amp_dtype, enabled = amp_dtype is not None),
+ ):
+ logits, _ = model(input_ids = ids, attention_mask = torch.ones_like(ids), records = [encoded])
+ rows = [
+ row[: len(question.option_ids)]
+ for question, row in zip(encoded.questions, logits.float().cpu())
+ ]
+ # The trainer's own rule: per type, or per (type, option count) bucket, after any folded scale.
+ scales = _served_temperatures(
+ model.decision_config,
+ rows,
+ [{"qtype": QUESTION_TYPES.index(q["type"])} for q in questions.values()],
+ )
+ answers = {}
+ for question, row, scale in zip(encoded.questions, rows, scales):
+ probabilities = (row / scale).softmax(-1).tolist()
+ answers[question.question_id] = systemone_answer(
+ questions[question.question_id], dict(zip(question.option_ids, probabilities))
+ )
+ return {
+ "answers": answers,
+ "input_tokens": len(encoded.input_ids),
+ "truncated": _truncated(tokenizer, state, questions, encoded),
+ }
+
+
+def _truncated(tokenizer, state, questions, encoded) -> bool:
+ # A cut state fills the budget exactly, but so does one that fits exactly: one more token of
+ # room tells them apart, and is only spent on prompts at the limit.
+ if len(encoded.input_ids) < MAX_LENGTH:
+ return False
+ from unsloth.models.clef import encode_record
+
+ record = {"state": state, "questions": questions}
+ return len(encode_record(tokenizer, record, max_length = MAX_LENGTH + 1).input_ids) > MAX_LENGTH
+
+
+def run_clef_worker(conn, folder: str) -> None:
+ """Child entrypoint, imported by name in the spawn child."""
+ if _BACKEND_PATH not in sys.path:
+ sys.path.insert(0, _BACKEND_PATH)
+ try:
+ model, tokenizer, load_in_4bit = _load(folder)
+ except BaseException as exc:
+ conn.send(("error", f"{type(exc).__name__}: {exc}"))
+ return
+ conn.send(("ready", {"load_in_4bit": load_in_4bit}))
+ while True:
+ try:
+ message = conn.recv()
+ except (EOFError, OSError):
+ return
+ if message[0] == "close":
+ return
+ _, state, questions = message
+ try:
+ conn.send(("ok", _decide(model, tokenizer, state, questions)))
+ except ValueError as exc:
+ conn.send(("invalid", str(exc)))
+ except BaseException as exc:
+ conn.send(("error", f"{type(exc).__name__}: {exc}"))
+
+
+class ClefAgent:
+ """Parent-side handle; the Decision API keeps it where it keeps a laya agent."""
+
+ device = "cuda"
+
+ def __init__(
+ self,
+ folder: Path,
+ cancelled: Callable[[], bool] | None = None,
+ ):
+ self._lock = threading.Lock()
+ self._broken: str | None = None
+ self._conn, child = _CTX.Pipe()
+ env = os.environ.get("UNSLOTH_IS_PRESENT")
+ os.environ["UNSLOTH_IS_PRESENT"] = "1"
+ try:
+ self._process = _CTX.Process(
+ target = run_clef_worker,
+ args = (child, str(folder)),
+ name = "systemone-clef",
+ daemon = True,
+ )
+ self._process.start()
+ finally:
+ if env is None:
+ os.environ.pop("UNSLOTH_IS_PRESENT", None)
+ child.close()
+ try:
+ # Polled in slices so a training run starting mid-load stops the worker before both need the GPU.
+ deadline = time.monotonic() + LOAD_TIMEOUT_S
+ while time.monotonic() < deadline and not self._conn.poll(1.0):
+ if cancelled is not None and cancelled():
+ raise ClefWorkerError("A training run took the GPU while Clef loaded.")
+ if not self._conn.poll(0):
+ raise ClefWorkerError(
+ f"The Clef worker did not answer within {LOAD_TIMEOUT_S:.0f}s"
+ )
+ kind, payload = self._receive(0)
+ except BaseException:
+ self.close()
+ raise
+ if kind != "ready":
+ self.close()
+ raise ClefWorkerError(payload)
+ self.load_in_4bit = payload["load_in_4bit"]
+
+ def _receive(self, timeout: float):
+ try:
+ if not self._conn.poll(timeout):
+ raise ClefWorkerError(f"The Clef worker did not answer within {timeout:.0f}s")
+ return self._conn.recv()
+ except (EOFError, OSError):
+ raise ClefWorkerError(
+ f"The Clef worker exited (code {self._process.exitcode})"
+ ) from None
+
+ def decide(self, state, questions: dict[str, dict[str, Any]]) -> dict[str, Any]:
+ with self._lock:
+ # After a timeout the late answer is still in the pipe, so the worker is never asked again.
+ if self._broken is not None:
+ raise ClefWorkerError(self._broken)
+ try:
+ self._conn.send(("decide", state, questions))
+ kind, payload = self._receive(DECIDE_TIMEOUT_S)
+ except (OSError, ValueError, ClefWorkerError) as exc:
+ self._broken = (
+ str(exc)
+ if isinstance(exc, ClefWorkerError)
+ else (f"The Clef worker exited (code {self._process.exitcode})")
+ )
+ raise ClefWorkerError(self._broken) from None
+ if kind == "invalid":
+ raise ValueError(payload)
+ if kind != "ok":
+ raise ClefWorkerError(payload)
+ return payload
+
+ def close(self) -> None:
+ try:
+ self._conn.send(("close",))
+ except (OSError, ValueError):
+ pass
+ self._process.join(CLOSE_TIMEOUT_S)
+ if self._process.is_alive():
+ self._process.kill()
+ self._process.join(CLOSE_TIMEOUT_S)
+ self._conn.close()
diff --git a/studio/backend/core/systemone/laya_runtime.py b/studio/backend/core/systemone/laya_runtime.py
index c951f227cf1..9b420714a67 100644
--- a/studio/backend/core/systemone/laya_runtime.py
+++ b/studio/backend/core/systemone/laya_runtime.py
@@ -76,6 +76,14 @@ def _device() -> str:
return candidate if device_can_allocate(candidate) else "cpu"
+def _training_active() -> bool:
+ try:
+ from core.training import get_training_backend
+ return bool(get_training_backend().is_training_active())
+ except Exception:
+ return False
+
+
def _mlx_available() -> bool:
try:
import unsloth_zoo.mlx.decision # noqa: F401
@@ -95,7 +103,47 @@ def _wanted(path: str, subfolder: str | None) -> bool:
return rest in _WEIGHT_FILES or rest.startswith(tuple(f"{name}/" for name in _REQUIRED_DIRS))
+def _clef_complete(folder: Path) -> bool:
+ import json
+
+ from utils.models.model_config import CLEF_MARKERS
+
+ if not all((folder / name).is_file() for name in CLEF_MARKERS):
+ return False
+ index = folder / "model.safetensors.index.json"
+ if not index.is_file():
+ return (folder / "model.safetensors").is_file()
+ try:
+ shards = set(json.loads(index.read_text(encoding = "utf-8"))["weight_map"].values())
+ except (OSError, ValueError, KeyError, TypeError):
+ return False
+ return all((folder / shard).is_file() for shard in shards)
+
+
+def _clef_dir(checkpoint: Checkpoint, local_only: bool) -> Path:
+ if checkpoint.is_local:
+ root = Path(checkpoint.source).expanduser()
+ else:
+ from huggingface_hub import snapshot_download
+
+ from utils.hf_cache_settings import active_hf_hub_cache
+ from utils.utils import hf_env_offline
+
+ root = Path(
+ snapshot_download(
+ checkpoint.source,
+ cache_dir = active_hf_hub_cache(),
+ local_files_only = local_only or hf_env_offline(),
+ )
+ )
+ if not _clef_complete(root):
+ raise FileNotFoundError(f"No complete Clef checkpoint at {root}")
+ return root
+
+
def _checkpoint_dir(checkpoint: Checkpoint, *, local_only: bool = False) -> Path:
+ if checkpoint.layout == "clef":
+ return _clef_dir(checkpoint, local_only)
if checkpoint.name == LOCAL_NAME and not checkpoint.is_local:
raise FileNotFoundError(
f"UNSLOTH_SYSTEMONE_MODEL={checkpoint.source} is neither a known model nor a directory"
@@ -194,6 +242,8 @@ def is_cached(checkpoint: Checkpoint) -> bool:
root = _checkpoint_dir(checkpoint, local_only = True)
except Exception:
return False
+ if checkpoint.layout == "clef":
+ return True
folder = root / checkpoint.subfolder if checkpoint.subfolder else root
return all((folder / name).is_file() for name in _WEIGHT_FILES)
@@ -201,9 +251,10 @@ def is_cached(checkpoint: Checkpoint) -> bool:
def download_plan(checkpoint: Checkpoint) -> dict[str, Any]:
cached = is_cached(checkpoint)
plan = {"repo": None, "files": [], "size_bytes": 0, "cached": cached, "error": None}
- if checkpoint.name == LOCAL_NAME:
+ if checkpoint.name == LOCAL_NAME or checkpoint.is_local:
if not cached:
- plan["error"] = f"No complete Laya checkpoint at {checkpoint.source}"
+ kind = "Clef" if checkpoint.layout == "clef" else "Laya"
+ plan["error"] = f"No complete {kind} checkpoint at {checkpoint.source}"
return plan
plan["repo"] = checkpoint.source
plan["size_bytes"] = checkpoint.download_bytes
@@ -215,7 +266,8 @@ def download_plan(checkpoint: Checkpoint) -> dict[str, Any]:
files = [
(entry.path, getattr(entry, "size", 0) or 0)
for entry in entries
- if hasattr(entry, "size") and _wanted(entry.path, checkpoint.subfolder)
+ if hasattr(entry, "size")
+ and (checkpoint.layout == "clef" or _wanted(entry.path, checkpoint.subfolder))
]
except Exception as exc:
plan["error"] = f"Could not list {checkpoint.source}: {type(exc).__name__}"
@@ -247,10 +299,17 @@ def _release_memory() -> None:
logger.debug("Could not clear the Decision API device cache", exc_info = True)
+def _close(agent) -> None:
+ # A Clef agent is a worker process; ending it returns its GPU memory.
+ if agent is not None and hasattr(agent, "close"):
+ agent.close()
+
+
def _evict() -> None:
global _agent, _loaded, _device_name
with _run_lock:
- _agent = _loaded = _device_name = None
+ agent, _agent, _loaded, _device_name = _agent, None, None, None
+ _close(agent)
_release_memory()
@@ -291,12 +350,28 @@ class _MLXAgent:
def _load_checkpoint(checkpoint: Checkpoint):
+ from utils.systemone_settings import get_device as preferred_device
+
root = _checkpoint_dir(checkpoint)
+ if checkpoint.layout == "clef":
+ from .clef_runtime import ClefAgent, ClefWorkerError
+
+ _evict()
+ agent = ClefAgent(root, cancelled = _training_active)
+ # Training may have started while this loaded, and Clef has no CPU fallback.
+ if _training_active():
+ agent.close()
+ raise ClefWorkerError(
+ f"{checkpoint.name} needs the GPU, which a training run took while it loaded."
+ )
+ return agent, "cuda"
_laya()
# Evict only once the new checkpoint is on disk, so a long or failed download leaves the resident model serving.
_evict()
- device = _device()
+ # While training holds the GPU, a GPU model loads on CPU, as dictation does; see _misplaced.
+ for_training = _training_active() and preferred_device() == "gpu"
+ device = "cpu" if for_training else _device()
folder = root / checkpoint.subfolder if checkpoint.subfolder else root
fp16_checkpoint = checkpoint.name in CHECKPOINTS or _stored_fp16(folder)
if device == "mlx":
@@ -310,7 +385,11 @@ def _load_checkpoint(checkpoint: Checkpoint):
agent = _load_laya(
str(root), subfolder = checkpoint.subfolder, device = "cpu", embedding_dtype = weights
)
+ # Training may have started while this built.
+ if device != "cpu" and _training_active():
+ device, for_training = "cpu", True
_place(agent, torch.device(device), fp16_checkpoint)
+ agent.__dict__["_unsloth_for_training"] = for_training
return agent, str(agent.device.type)
@@ -557,10 +636,40 @@ def _load(checkpoint: Checkpoint) -> None:
)
+def _misplaced() -> bool:
+ # The resident model follows the same rule: off the GPU while training holds it, back on it after.
+ if getattr(_agent, "_unsloth_for_training", False):
+ return not _training_active()
+ return _device_name not in (None, "cpu") and _training_active()
+
+
+def _clef_blocked_by_training(checkpoint: Checkpoint) -> None:
+ if checkpoint.layout != "clef":
+ return
+ from .catalog import clef_unsupported_reason
+
+ if (reason := clef_unsupported_reason()) is not None:
+ raise Unavailable(400, "api_usage_error", reason)
+ if not _training_active():
+ return
+ # Clef has no CPU fallback: it waits for the GPU instead of taking it from the run.
+ if _loaded is not None and _loaded.layout == "clef":
+ _evict()
+ raise Unavailable(
+ 503,
+ "model_unavailable",
+ f"{checkpoint.name} needs the GPU, which a training run is using; it answers again when the run ends.",
+ retry_after = 30,
+ )
+
+
def _ensure_loading(checkpoint: Checkpoint) -> threading.Thread | None:
global _loader, _loading
+ # Asked before _state_lock: the training backend takes its own lock.
+ _clef_blocked_by_training(checkpoint)
+ misplaced = _misplaced()
with _state_lock:
- if _loaded == checkpoint and _agent is not None:
+ if _loaded == checkpoint and _agent is not None and not misplaced:
return None
if _failure and _failure[0] == checkpoint and time.monotonic() < _failure[2]:
raise Unavailable(
@@ -1198,6 +1307,8 @@ def _decide(checkpoint: Checkpoint, state, questions: dict[str, dict[str, Any]])
raise Unavailable(
503, "model_loading", f"{checkpoint.name} is reloading", retry_after = 5
)
+ if checkpoint.layout == "clef":
+ return _decide_clef(checkpoint, agent, state, questions)
laya_questions = {name: _to_laya(q) for name, q in questions.items()}
try:
result, truncated = _predict(agent, state, laya_questions)
@@ -1213,6 +1324,34 @@ def _decide(checkpoint: Checkpoint, state, questions: dict[str, dict[str, Any]])
}
+def _decide_clef(checkpoint: Checkpoint, agent, state, questions) -> dict[str, Any]:
+ from .clef_runtime import ClefWorkerError
+ try:
+ result = agent.decide(state, questions)
+ except ValueError as exc:
+ raise Unavailable(422, "invalid_request_error", str(exc)) from None
+ except ClefWorkerError as exc:
+ # A dead or hung worker is dropped, so the next request starts a fresh one.
+ threading.Thread(target = _evict_agent, args = (agent,), daemon = True).start()
+ raise Unavailable(503, "model_unavailable", str(exc), retry_after = 5) from None
+ return {
+ "model": checkpoint.name,
+ "answers": {name: _wire_answer(result["answers"][name]) for name in questions},
+ "usage": {"input_tokens": int(result["input_tokens"]), "output_tokens": 0},
+ "truncated": bool(result["truncated"]),
+ }
+
+
+def _evict_agent(agent) -> None:
+ global _agent, _loaded, _device_name
+ # Waits for _decide to release _run_lock.
+ with _run_lock:
+ if _agent is not agent:
+ return
+ _agent = _loaded = _device_name = None
+ _close(agent)
+
+
def status() -> dict[str, Any]:
with _state_lock:
failure = _failure if _failure and time.monotonic() < _failure[2] else None
@@ -1238,8 +1377,9 @@ def unload() -> bool:
global _agent, _loaded, _device_name, _failure
ensure_can_unload()
with _run_lock:
- was_loaded = _agent is not None
+ agent, was_loaded = _agent, _agent is not None
_agent = _loaded = _device_name = None
_failure = None
+ _close(agent)
_release_memory()
return was_loaded
diff --git a/studio/backend/core/training/decision_trainer.py b/studio/backend/core/training/decision_trainer.py
new file mode 100644
index 00000000000..051d91d7ed4
--- /dev/null
+++ b/studio/backend/core/training/decision_trainer.py
@@ -0,0 +1,523 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from __future__ import annotations
+
+import contextlib
+import json
+import math
+import os
+import random
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable
+
+from loggers import get_logger
+
+logger = get_logger(__name__)
+
+EVAL_MAX = 2000
+MIN_REPORTED_ITEMS = 50
+STRUCT_COLUMNS_WARNING = (
+ "The state, questions or gold columns are stored as objects rather than JSON strings, so "
+ "missing fields come back as nulls and choice options can change order. Store them as JSON "
+ "strings to train on what the Decision API sees."
+)
+
+
+class _Stopped(Exception):
+ pass
+
+
+def _decision_count(items: list) -> int:
+ # A Clef item holds every question of its row, as split_holdout counts them.
+ return sum(len(item.get("labels", (None,))) for item in items)
+
+
+def _studio_validate(name: str, question) -> None:
+ from fastapi import HTTPException
+ from pydantic import ValidationError
+
+ from routes.systemone import QuestionIn, _validate
+
+ # The Decision API's own checks, so every trained question is one it will serve.
+ try:
+ _validate(name, QuestionIn.model_validate(question))
+ except ValidationError:
+ raise ValueError("is not a valid question") from None
+ except HTTPException as exc:
+ raise ValueError(exc.detail["message"]) from None
+
+
+def _without_nulls(value):
+ if isinstance(value, dict):
+ return {k: _without_nulls(v) for k, v in value.items() if v is not None}
+ if isinstance(value, list):
+ return [_without_nulls(v) for v in value]
+ return value
+
+
+def _has_struct(feature) -> bool:
+ if isinstance(feature, dict):
+ return True
+ inner = getattr(feature, "feature", None)
+ return inner is not None and _has_struct(inner)
+
+
+def _from_arrow(rows, warn: Callable[[str], None]) -> list[dict]:
+ features = getattr(rows, "features", None) or {}
+ if any(
+ _has_struct(features[key])
+ for key in ("state", "questions", "gold", "answers")
+ if key in features
+ ):
+ warn(STRUCT_COLUMNS_WARNING)
+ # Arrow pads each row with every row's keys as None; drop those, but keep "" descriptions.
+ return [
+ {
+ **row,
+ **{
+ key: _without_nulls(row[key])
+ for key in ("questions", "gold", "answers")
+ if isinstance(row.get(key), dict)
+ },
+ }
+ for row in rows
+ ]
+
+
+def _local_files(paths: list[str]) -> list[Path]:
+ from utils.paths import dataset_files_in_dir, datasets_root
+
+ files: list[Path] = []
+ for entry in paths:
+ path = Path(entry if os.path.isabs(entry) else os.path.join(str(datasets_root()), entry))
+ files.extend(dataset_files_in_dir(path) if path.is_dir() else [path])
+ return files
+
+
+def _read_local_rows(paths: list[str], load_dataset, warn: Callable[[str], None]) -> list[dict]:
+ from utils.datasets.cells import csv_as_text_kwargs
+
+ files = _local_files(paths)
+ if not files:
+ raise ValueError("No local dataset files found")
+ rows: list[dict] = []
+ for path in files:
+ suffix = path.suffix.lower()
+ if suffix in (".json", ".jsonl"):
+ # Read directly: Arrow would merge every question's criteria keys into one struct.
+ text = path.read_text(encoding = "utf-8-sig")
+ try:
+ data = json.loads(text)
+ rows.extend(data if isinstance(data, list) else [data])
+ except ValueError:
+ rows.extend(json.loads(line) for line in text.splitlines() if line.strip())
+ elif suffix in (".csv", ".parquet"):
+ dataset = load_dataset(
+ suffix[1:],
+ data_files = [str(path)],
+ split = "train",
+ **csv_as_text_kwargs([str(path)]),
+ )
+ rows.extend(_from_arrow(dataset, warn))
+ else:
+ raise ValueError(f"Unsupported local dataset format: {path.name}")
+ return [row for row in rows if isinstance(row, dict)]
+
+
+def _eval_sample(rows, seed: int):
+ # Every row holds at least one decision, so EVAL_MAX rows can fill the eval set.
+ if len(rows) <= EVAL_MAX:
+ return rows
+ return [rows[i] for i in sorted(random.Random(seed).sample(range(len(rows)), EVAL_MAX))]
+
+
+def _load_rows(
+ config: dict,
+ should_stop: Callable[[], bool],
+ status: Callable[[str], None],
+ warn: Callable[[str], None],
+) -> tuple[list, list | None]:
+ from core.training.eval_dataset import evaluation_enabled
+ from core.training.s3_dataset import S3DownloadCancelled, prepare_s3_dataset_download
+ from core.training.worker import _load_embedding_hf_dataset
+ from utils.datasets.cache_safe import load_dataset_cache_safe as load_dataset
+
+ evaluate = evaluation_enabled(config.get("eval_steps"))
+ seed = config["random_seed"]
+ eval_rows = None
+ # Local files, then S3, then the Hub: the order the route's cached-dataset check relies on.
+ if config.get("local_datasets"):
+ rows = _read_local_rows(config["local_datasets"], load_dataset, warn)
+ elif config.get("s3_config"):
+ status("Downloading dataset from S3...")
+ try:
+ download = prepare_s3_dataset_download(config["s3_config"], cancel_callback = should_stop)
+ except S3DownloadCancelled:
+ raise _Stopped("Training cancelled") from None
+ try:
+ rows = _read_local_rows(download.files, load_dataset, warn)
+ finally:
+ download.cleanup()
+ elif config.get("hf_dataset"):
+ rows = _from_arrow(_load_embedding_hf_dataset(config, load_dataset, status), warn)
+ eval_split = config.get("eval_split") if evaluate else None
+ if eval_split and eval_split == (config.get("train_split") or "train"):
+ warn(
+ "The evaluation split is the training split, so part of it is held out "
+ "of training for evaluation instead."
+ )
+ elif eval_split:
+ # Loaded like the train split, from the same cached snapshot, without the row slice.
+ held = {
+ **config,
+ "train_split": eval_split,
+ "dataset_slice_start": None,
+ "dataset_slice_end": None,
+ }
+ eval_rows = _from_arrow(
+ _eval_sample(_load_embedding_hf_dataset(held, load_dataset, status), seed), warn
+ )
+ else:
+ raise ValueError("No dataset specified for decision training.")
+ if (
+ evaluate
+ and config.get("local_eval_datasets")
+ and config.get("local_datasets")
+ and {p.resolve() for p in _local_files(config["local_eval_datasets"])}
+ & {p.resolve() for p in _local_files(config["local_datasets"])}
+ ):
+ # Scoring or calibrating on training rows would report the fit, not held-out accuracy.
+ warn(
+ "The evaluation files include training files, so part of the training data is "
+ "held out for evaluation instead."
+ )
+ elif evaluate and config.get("local_eval_datasets"):
+ eval_rows = _eval_sample(
+ _read_local_rows(config["local_eval_datasets"], load_dataset, warn), seed
+ )
+
+ start, end = config.get("dataset_slice_start"), config.get("dataset_slice_end")
+ if start is not None or end is not None:
+ rows = rows[start or 0 : (len(rows) if end is None else end + 1)]
+ return rows, eval_rows
+
+
+def run_decision_training(event_queue: Any, stop_queue: Any, config: dict) -> None:
+ import torch
+
+ from utils.paths import is_local_path, resolve_output_dir
+ from utils.training_runs import build_default_output_dir_name
+
+ model_name, subfolder = config["model_name"], config.get("model_subfolder")
+ output_dir = str(
+ resolve_output_dir(
+ config.get("output_dir")
+ or build_default_output_dir_name(
+ model_name
+ if is_local_path(model_name) or not subfolder
+ else f"{model_name}-{subfolder}",
+ config.get("project_name"),
+ )
+ )
+ )
+ try:
+ _run(event_queue, stop_queue, config, output_dir)
+ except _Stopped as stopped:
+ event_queue.put(
+ {
+ "type": "complete",
+ "output_dir": None,
+ "status_message": str(stopped),
+ "ts": time.time(),
+ }
+ )
+ except torch.cuda.OutOfMemoryError:
+ event_queue.put(
+ {
+ "type": "error",
+ "error": (
+ "Out of GPU memory while training the decision model. Lower the batch size "
+ "and raise gradient accumulation to keep the same effective batch."
+ ),
+ "stack": "",
+ "ts": time.time(),
+ }
+ )
+ finally:
+ # The trainer creates the folder at init; a run that saved nothing leaves none behind.
+ with contextlib.suppress(OSError):
+ os.rmdir(output_dir)
+
+
+def _run(event_queue: Any, stop_queue: Any, config: dict, output_dir: str) -> None:
+ from core.import_guards import ensure_real_packages
+
+ ensure_real_packages("unsloth_zoo", "unsloth")
+ from unsloth import DecisionTrainer, FastDecisionModel, is_bfloat16_supported
+
+ import torch
+ from huggingface_hub.errors import LocalEntryNotFoundError
+ from transformers import TrainingArguments
+
+ from core.systemone import laya_runtime
+ from core.systemone.catalog import Checkpoint
+ from core.training.eval_dataset import evaluation_enabled
+ from core.training.trainer import (
+ _drop_hf_stdout_callbacks,
+ _hf_stdout_progress_disabled,
+ normalize_gradient_checkpointing,
+ )
+ from core.training.worker import (
+ _create_embedding_progress_callback,
+ _emit_output_dir,
+ _send_status,
+ _start_worker_stop_poller,
+ _worker_hf_token,
+ )
+
+ def send(kind: str, **payload) -> None:
+ event_queue.put({"type": kind, **payload, "ts": time.time()})
+
+ def status(message: str) -> None:
+ _send_status(event_queue, message)
+
+ def warn(message: str) -> None:
+ send("warning", message = message)
+
+ stop = {"requested": False, "save": True}
+
+ def on_stop(save: bool) -> None:
+ stop["requested"], stop["save"] = True, save
+ logger.info("Decision training: stop signal received (save=%s)", save)
+
+ def check_stop() -> None:
+ if stop["requested"]:
+ raise _Stopped("Training stopped" if stop["save"] else "Training cancelled")
+
+ def validate(name: str, question) -> None:
+ # build_dataset calls this for every decision, so a stop does not wait for the whole dataset.
+ check_stop()
+ _studio_validate(name, question)
+
+ _start_worker_stop_poller(stop_queue, on_stop)
+
+ model_name = config["model_name"]
+ subfolder = config.get("model_subfolder") or None
+ clef = config.get("decision_layout") == "clef"
+ hf_token = _worker_hf_token(config)
+ if hf_token:
+ os.environ["HF_TOKEN"] = hf_token
+ seed = config["random_seed"]
+ use_lora = config["training_type"] == "LoRA/QLoRA"
+ gradient_checkpointing = normalize_gradient_checkpointing(config["gradient_checkpointing"])
+
+ status("Loading decision model...")
+ try:
+ root = laya_runtime._checkpoint_dir(
+ Checkpoint("base", model_name, subfolder, "", layout = "clef" if clef else "laya")
+ )
+ except LocalEntryNotFoundError as exc:
+ send("error", error = f"Could not download {model_name}: {exc}", stack = "")
+ return
+ except FileNotFoundError as exc:
+ kind = "Clef" if clef else "Laya"
+ send("error", error = f"Not a {kind} decision checkpoint: {exc}", stack = "")
+ return
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(root),
+ subfolder = subfolder,
+ full_finetuning = not use_lora,
+ use_gradient_checkpointing = gradient_checkpointing,
+ # Clef trains through Unsloth's Qwen3.5 loader, in 4-bit for QLoRA; Laya is always 16-bit.
+ **(
+ {
+ "load_in_4bit": use_lora and bool(config.get("load_in_4bit")),
+ "max_seq_length": config.get("max_seq_length") or None,
+ }
+ if clef
+ else {}
+ ),
+ )
+ if use_lora:
+ model = FastDecisionModel.get_peft_model(
+ model,
+ r = config["lora_r"],
+ lora_alpha = config["lora_alpha"],
+ lora_dropout = config["lora_dropout"],
+ use_gradient_checkpointing = gradient_checkpointing,
+ random_state = seed,
+ use_rslora = config["use_rslora"],
+ )
+ check_stop()
+
+ status("Loading dataset...")
+ rows, eval_rows = _load_rows(config, lambda: stop["requested"], status, warn)
+ check_stop()
+ status("Preparing decisions...")
+ items, report = FastDecisionModel.build_dataset(rows, tokenizer, model, validate)
+ eval_items = []
+ if eval_rows is not None:
+ eval_items, eval_report = FastDecisionModel.build_dataset(
+ eval_rows, tokenizer, model, validate
+ )
+ report = {
+ "total": report["total"] + eval_report["total"],
+ "skipped": report["skipped"] + eval_report["skipped"],
+ "reason": report["reason"] or eval_report["reason"],
+ }
+ if not items:
+ reason = f" ({report['reason']})" if report["reason"] else ""
+ send(
+ "error",
+ error = f"No usable decisions in the dataset{reason}. Each row needs state, questions and gold.",
+ stack = "",
+ )
+ return
+ if report["skipped"]:
+ warn(f"Skipped {report['skipped']:,} of {report['total']:,} decisions: {report['reason']}.")
+ if not eval_items:
+ items, eval_items = FastDecisionModel.split_holdout(items, seed)
+ if eval_items:
+ status(
+ f"Holding out {_decision_count(eval_items):,} decisions to calibrate confidence..."
+ )
+ elif len(eval_items) > EVAL_MAX:
+ eval_items = random.Random(seed).sample(eval_items, EVAL_MAX)
+
+ batch_size, accumulation = config["batch_size"], config["gradient_accumulation_steps"]
+ max_steps, epochs = config["max_steps"] or 0, max(1, config["num_epochs"])
+ steps_per_epoch = max(1, math.ceil(math.ceil(len(items) / batch_size) / accumulation))
+ total_steps = max_steps if max_steps > 0 else steps_per_epoch * epochs
+ bf16 = is_bfloat16_supported()
+ arguments = {
+ "output_dir": output_dir,
+ "per_device_train_batch_size": batch_size,
+ # A Clef record is every question of a row over a 9B-27B backbone, so it evaluates at the train batch.
+ "per_device_eval_batch_size": batch_size if clef else 16,
+ "gradient_accumulation_steps": accumulation,
+ "learning_rate": float(config["learning_rate"]),
+ "weight_decay": config["weight_decay"],
+ "lr_scheduler_type": config["lr_scheduler_type"],
+ "optim": config["optim"],
+ "seed": seed,
+ "bf16": bf16,
+ "fp16": torch.cuda.is_available() and not bf16,
+ "logging_steps": 1,
+ "report_to": "none",
+ "disable_tqdm": _hf_stdout_progress_disabled(),
+ "warmup_steps": config["warmup_steps"]
+ or round((config["warmup_ratio"] or 0.0) * total_steps),
+ "save_strategy": "no",
+ }
+ if max_steps > 0:
+ arguments["max_steps"] = max_steps
+ else:
+ arguments["num_train_epochs"] = epochs
+ if config["max_grad_norm"] is not None:
+ arguments["max_grad_norm"] = config["max_grad_norm"]
+ if eval_items:
+ if evaluation_enabled(config["eval_steps"]):
+ arguments.update(eval_strategy = "steps", eval_steps = float(config["eval_steps"]))
+ else:
+ arguments["eval_strategy"] = "epoch"
+ send("eval_configured")
+ report_to = []
+ if config.get("enable_tensorboard"):
+ from utils.paths import resolve_tensorboard_dir
+ report_to.append("tensorboard")
+ # transformers 5 ignores logging_dir; its TensorBoard callback reads this instead.
+ os.environ["TENSORBOARD_LOGGING_DIR"] = str(
+ resolve_tensorboard_dir(config.get("tensorboard_dir"))
+ )
+ if config["enable_wandb"]:
+ try:
+ import wandb
+
+ if config.get("wandb_token"):
+ os.environ["WANDB_API_KEY"] = config["wandb_token"]
+ wandb.init(project = config.get("wandb_project") or "unsloth-training")
+ report_to.append("wandb")
+ except Exception as exc:
+ warn(f"Weights & Biases logging is off: {exc}")
+ arguments["report_to"] = report_to or "none"
+
+ base_metrics = None
+ if eval_items:
+ status(
+ f"Evaluating the base model on {_decision_count(eval_items):,} held-out decisions..."
+ )
+ base_metrics = FastDecisionModel.evaluate(
+ model, tokenizer, eval_items, batch_size = config["batch_size"]
+ )
+ logger.info("Base held-out metrics: %s", base_metrics)
+ check_stop()
+
+ _emit_output_dir(event_queue, output_dir)
+ trainer = DecisionTrainer(
+ model = model,
+ args = TrainingArguments(**arguments),
+ train_dataset = items,
+ eval_dataset = eval_items or None,
+ processing_class = tokenizer,
+ callbacks = [
+ _create_embedding_progress_callback(
+ event_queue,
+ total_steps = total_steps,
+ training_start_time = time.time(),
+ should_stop = lambda: stop["requested"],
+ )
+ ],
+ )
+ _drop_hf_stdout_callbacks(trainer)
+ start = time.time()
+ trainer.train()
+ if stop["requested"] and not stop["save"]:
+ raise _Stopped("Training cancelled")
+
+ tuned_metrics = None
+ if eval_items:
+ status("Calibrating confidence...")
+ tuned_metrics = FastDecisionModel.calibrate(
+ model, tokenizer, eval_items, batch_size = config["batch_size"]
+ )
+ logger.info("Fine-tuned held-out metrics: %s", tuned_metrics)
+ # A cancel during calibration still saves nothing; a stop with save keeps the model.
+ if stop["requested"] and not stop["save"]:
+ raise _Stopped("Training cancelled")
+
+ status("Saving model...")
+ peak_gb = torch.cuda.max_memory_allocated() / 1e9 if torch.cuda.is_available() else None
+ model.decision_config["training"] = {
+ "base": model_name,
+ "subfolder": subfolder,
+ "method": ("qlora" if clef and config.get("load_in_4bit") else "lora")
+ if use_lora
+ else "full",
+ "objective": "soft_cross_entropy",
+ "dataset": [Path(path).name for path in config.get("local_datasets") or []]
+ or config.get("hf_dataset")
+ or None,
+ "steps": trainer.state.global_step,
+ "epochs": round(trainer.state.epoch or 0, 2),
+ "heldout_decisions": _decision_count(eval_items),
+ "heldout_accuracy_base": base_metrics and round(base_metrics["accuracy"], 4),
+ "heldout_accuracy": tuned_metrics and round(tuned_metrics["accuracy"], 4),
+ "heldout_ece_base": base_metrics and round(base_metrics["ece"], 4),
+ "heldout_ece": tuned_metrics and round(tuned_metrics["ece"], 4),
+ "seconds": round(time.time() - start, 1),
+ "peak_memory_gb": peak_gb and round(peak_gb, 2),
+ "date": datetime.now(timezone.utc).isoformat(timespec = "seconds"),
+ }
+ model.save_pretrained_merged(output_dir, tokenizer)
+ logger.info("Decision model saved to %s: %s", output_dir, model.decision_config["training"])
+
+ message = "Decision training completed"
+ if base_metrics and tuned_metrics and _decision_count(eval_items) >= MIN_REPORTED_ITEMS:
+ message = (
+ f"Held-out accuracy {base_metrics['accuracy']:.2f} -> {tuned_metrics['accuracy']:.2f}, "
+ f"calibration error {tuned_metrics['ece']:.2f}"
+ )
+ send("complete", output_dir = output_dir, status_message = message)
diff --git a/studio/backend/core/training/training.py b/studio/backend/core/training/training.py
index f8dd871c538..4dce66fad2f 100644
--- a/studio/backend/core/training/training.py
+++ b/studio/backend/core/training/training.py
@@ -268,6 +268,9 @@ def _build_training_worker_config(values: dict[str, Any]) -> dict[str, Any]:
"is_dataset_image": values.get("is_dataset_image", False),
"is_dataset_audio": values.get("is_dataset_audio", False),
"is_embedding": values.get("is_embedding", False),
+ "is_decision": values.get("is_decision", False),
+ "model_subfolder": values.get("model_subfolder"),
+ "decision_layout": values.get("decision_layout"),
"num_epochs": values.get("num_epochs", 3),
"learning_rate": values.get("learning_rate", "2e-4"),
"embedding_learning_rate": values.get("embedding_learning_rate"),
@@ -436,7 +439,8 @@ def _resolve_model_snapshot(model_name: str, local_path: Optional[str]) -> Optio
def _apply_model_cache_pin(config: dict[str, Any], warnings: list[str]) -> None:
resume = bool(config.get("resume_from_checkpoint"))
model_name = config["model_name"]
- if is_local_path(model_name):
+ # The decision trainer resolves its own Laya cache, which holds no config.json to pin.
+ if is_local_path(model_name) or config.get("is_decision"):
config["actual_model_repo_id"] = None
config["model_snapshot_path"] = None
config["model_revision"] = None
diff --git a/studio/backend/core/training/worker.py b/studio/backend/core/training/worker.py
index 466c013a045..6f3988d4321 100644
--- a/studio/backend/core/training/worker.py
+++ b/studio/backend/core/training/worker.py
@@ -1180,6 +1180,20 @@ if sys.platform == "win32":
del _add_rocm_dll_dirs_worker
+def _decision_has_llm_backbone(model_load_target: str, hf_token: str | None) -> bool:
+ # Clef ships joint_head_config.json next to its Qwen3.5 backbone; Laya never does.
+ marker = "joint_head_config.json"
+ try:
+ if (Path(model_load_target) / marker).is_file():
+ return True
+ from huggingface_hub import HfApi
+
+ siblings = HfApi(token = hf_token).model_info(model_load_target).siblings or ()
+ return any(getattr(s, "rfilename", None) == marker for s in siblings)
+ except Exception:
+ return False
+
+
def _model_wants_causal_conv1d(model_name: str) -> bool:
name = model_name.lower()
return any(key in name for key in _CAUSAL_CONV1D_MODEL_SUBSTRINGS)
@@ -2617,6 +2631,10 @@ def _run_mlx_training(event_queue, stop_queue, config):
message = "Embedding model training is not supported for MLX training yet."
_send("error", error = message)
raise NotImplementedError(message)
+ if config.get("is_decision"):
+ message = "Decision model training is not supported for MLX training yet."
+ _send("error", error = message)
+ raise NotImplementedError(message)
if config.get("training_type") == "Continued Pretraining":
message = "Continued Pretraining is not supported for MLX training yet."
_send("error", error = message)
@@ -3465,6 +3483,44 @@ def _recorded_local_base(model_name) -> "tuple[str | None, bool]":
return None, True
+def _download_decision_checkpoint(event_queue: Any, config: dict) -> None:
+ from core.systemone import laya_runtime
+ from core.systemone.catalog import Checkpoint
+ from utils.hf_xet_fallback import start_watchdog
+ from utils.paths import is_local_path
+
+ model_name = config["model_name"]
+ if is_local_path(model_name):
+ return
+ hf_token = _worker_hf_token(config)
+ if hf_token:
+ os.environ["HF_TOKEN"] = hf_token
+ _send_status(event_queue, "Loading decision model...")
+ # Under the stall watchdog, so the parent can retry a stalled Xet download over HTTP.
+ event_queue.put({"type": "model_load_started", "ts": time.time()})
+ watchdog_stop = start_watchdog(
+ repo_ids = [model_name],
+ on_stall = lambda msg: event_queue.put({"type": "stall", "message": msg, "ts": time.time()}),
+ xet_disabled = os.environ.get("HF_HUB_DISABLE_XET") == "1",
+ )
+ try:
+ laya_runtime._checkpoint_dir(
+ Checkpoint(
+ "base",
+ model_name,
+ config.get("model_subfolder") or None,
+ "",
+ layout = config.get("decision_layout") or "laya",
+ )
+ )
+ except Exception as exc:
+ # The trainer's own load reports it.
+ logger.info("Could not download %s ahead of the trainer: %s", model_name, exc)
+ finally:
+ watchdog_stop.set()
+ event_queue.put({"type": "model_load_completed", "ts": time.time()})
+
+
def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) -> None:
"""Subprocess entrypoint. Fresh Python, no stale module state. ``event_queue`` carries
progress/status/error events to the parent, ``stop_queue`` carries stop commands from it, and
@@ -3554,7 +3610,17 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
mark_log_record_continuations()
- apply_gpu_ids(config.get("resolved_gpu_ids"), backend = config.get("device_backend"))
+ gpu_ids = config.get("resolved_gpu_ids")
+ if config.get("is_decision") and gpu_ids and len(gpu_ids) > 1:
+ gpu_ids = gpu_ids[:1]
+ event_queue.put(
+ {
+ "type": "warning",
+ "message": f"Decision models train on one GPU; using GPU {gpu_ids[0]}.",
+ "ts": time.time(),
+ }
+ )
+ apply_gpu_ids(gpu_ids, backend = config.get("device_backend"))
if not _validate_training_worker_config(config, event_queue):
return
@@ -3643,44 +3709,51 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
# lazy_load it without calling is_causal_conv1d_available.
# 2) mamba-ssm + flash-attn keep their substring / size gates.
# 3) FLA gated-delta kernels: vendored by unsloth_zoo, nothing to install.
- try:
- from utils.ssm_runtime import resolved_model_wants_causal_conv1d
+ # Laya decision models are ModernBERT encoders: none of these apply.
+ # Clef decision models are Qwen3.5 backbones and need the same gated-delta / conv kernels.
+ if (
+ not config.get("is_decision")
+ or config.get("decision_layout") == "clef"
+ or _decision_has_llm_backbone(model_load_target, _worker_hf_token(config))
+ ):
+ try:
+ from utils.ssm_runtime import resolved_model_wants_causal_conv1d
- wants_causal_conv1d = resolved_model_wants_causal_conv1d(
- model_name,
- model_load_target,
- _worker_hf_token(config),
- )
- _ensure_causal_conv1d_fast_path(
- event_queue,
- model_name,
- required = wants_causal_conv1d,
- )
- _install_fast_path_hooks(
- event_queue,
- model_name,
- install_causal_conv1d = wants_causal_conv1d,
- )
- _ensure_mamba_ssm(event_queue, model_name)
- _ensure_flash_attn_for_long_context(
- event_queue,
- int(config.get("max_seq_length", 2048)),
- )
- except Exception as exc:
- event_queue.put(
- {
- "type": "error",
- "error": (
- f"Please choose another model to train, since "
- f"a fast-path kernel library "
- f"(causal-conv1d / mamba-ssm) failed to install "
- f"with error: {exc}"
- ),
- "stack": traceback.format_exc(limit = 20),
- "ts": time.time(),
- }
- )
- return
+ wants_causal_conv1d = resolved_model_wants_causal_conv1d(
+ model_name,
+ model_load_target,
+ _worker_hf_token(config),
+ )
+ _ensure_causal_conv1d_fast_path(
+ event_queue,
+ model_name,
+ required = wants_causal_conv1d,
+ )
+ _install_fast_path_hooks(
+ event_queue,
+ model_name,
+ install_causal_conv1d = wants_causal_conv1d,
+ )
+ _ensure_mamba_ssm(event_queue, model_name)
+ _ensure_flash_attn_for_long_context(
+ event_queue,
+ int(config.get("max_seq_length", 2048)),
+ )
+ except Exception as exc:
+ event_queue.put(
+ {
+ "type": "error",
+ "error": (
+ f"Please choose another model to train, since "
+ f"a fast-path kernel library "
+ f"(causal-conv1d / mamba-ssm) failed to install "
+ f"with error: {exc}"
+ ),
+ "stack": traceback.format_exc(limit = 20),
+ "ts": time.time(),
+ }
+ )
+ return
# No start-method override: Dataset.map() imports Pool from `multiprocess`, so forcing stdlib multiprocessing onto
# "fork" never reached it; the guard now asks multiprocess.
@@ -4109,6 +4182,22 @@ def run_training_process(*, event_queue: Any, stop_queue: Any, config: dict) ->
)
return
+ if config.get("is_decision", False):
+ try:
+ _download_decision_checkpoint(event_queue, config)
+ from core.training.decision_trainer import run_decision_training
+ run_decision_training(event_queue, stop_queue, config)
+ except Exception as exc:
+ event_queue.put(
+ {
+ "type": "error",
+ "error": str(exc),
+ "stack": traceback.format_exc(limit = 20),
+ "ts": time.time(),
+ }
+ )
+ return
+
# Embedding models use a different pipeline (FastSentenceTransformer + SentenceTransformerTrainer +
# MultipleNegativesRankingLoss), so branch early.
if config.get("is_embedding", False):
diff --git a/studio/backend/models/models.py b/studio/backend/models/models.py
index 37bdbfb6539..b614e8a4936 100644
--- a/studio/backend/models/models.py
+++ b/studio/backend/models/models.py
@@ -6,7 +6,7 @@
from pydantic import BaseModel, Field
from typing import Optional, List, Dict, Any, Literal
-ModelType = Literal["text", "vision", "audio", "embeddings"]
+ModelType = Literal["text", "vision", "audio", "embeddings", "decision"]
class CheckpointInfo(BaseModel):
@@ -91,6 +91,13 @@ class ModelDetails(BaseModel):
is_embedding: bool = Field(
False, description = "Whether model is an embedding/sentence-transformer model"
)
+ is_decision: bool = Field(False, description = "Whether model is a decision model")
+ decision_layout: Optional[Literal["laya", "clef"]] = Field(
+ None, description = "Checkpoint layout of a decision model: Laya or Cloudflare Clef"
+ )
+ decision_checkpoints: Optional[List[Dict[str, Any]]] = Field(
+ None, description = "Checkpoints a decision model repo offers for training"
+ )
is_lora: bool = Field(False, description = "Whether model is a LoRA adapter")
is_gguf: bool = Field(False, description = "Whether model is a GGUF model (llama.cpp format)")
is_mlx: bool = Field(
@@ -109,7 +116,7 @@ class ModelDetails(BaseModel):
)
has_audio_input: bool = Field(False, description = "Whether model accepts audio input (ASR)")
model_type: Optional[ModelType] = Field(
- None, description = "Collapsed model modality: text, vision, audio, or embeddings"
+ None, description = "Collapsed model modality: text, vision, audio, embeddings or decision"
)
base_model: Optional[str] = Field(None, description = "Base model if this is a LoRA adapter")
max_position_embeddings: Optional[int] = Field(
diff --git a/studio/backend/models/training.py b/studio/backend/models/training.py
index 8be9b5f79aa..a1a67d3d8a0 100644
--- a/studio/backend/models/training.py
+++ b/studio/backend/models/training.py
@@ -585,6 +585,14 @@ class TrainingStartRequest(BaseModel):
is_embedding: bool = Field(
False, description = "Whether model is an embedding/sentence-transformer model"
)
+ is_decision: bool = Field(False, description = "Whether model is a decision model (Laya or Clef)")
+ model_subfolder: Optional[str] = Field(
+ None, description = "Checkpoint subfolder of a decision model repo"
+ )
+ decision_layout: Optional[Literal["laya", "clef"]] = Field(
+ None,
+ description = "Set by the server from the checkpoint files; a caller's value is replaced",
+ )
enable_wandb: bool = Field(False, description = "Enable Weights & Biases logging")
wandb_token: Optional[str] = Field(None, description = "W&B token")
diff --git a/studio/backend/routes/models.py b/studio/backend/routes/models.py
index 7c6f411e390..b78f60d8806 100644
--- a/studio/backend/routes/models.py
+++ b/studio/backend/routes/models.py
@@ -260,6 +260,8 @@ try:
_is_imatrix_path,
_is_mtp_drafter,
is_audio_input_type,
+ decision_layout,
+ is_decision_model,
)
from core.inference import get_inference_backend
from utils.paths import (
@@ -292,6 +294,8 @@ except ImportError:
_is_imatrix_path,
_is_mtp_drafter,
is_audio_input_type,
+ decision_layout,
+ is_decision_model,
)
from core.inference import get_inference_backend
from utils.paths import (
@@ -346,7 +350,10 @@ def derive_model_type(
is_vision: bool,
audio_type: Optional[str],
is_embedding: bool = False,
+ is_decision: bool = False,
) -> ModelType:
+ if is_decision:
+ return "decision"
if is_embedding:
return "embeddings"
if audio_type is not None:
@@ -2290,6 +2297,9 @@ def _model_config_inspection_target(
with_load_subdirs(model_name, ("config.json", "adapter_config.json")),
)
if snapshot is None:
+ # A cached Laya checkpoint has no config.json; the probes read it by repo id.
+ if is_decision_model(model_name, hf_token, local_files_only = True):
+ return model_name
raise HTTPException(
status_code = 404,
detail = "Selected cached model is no longer available.",
@@ -2421,6 +2431,25 @@ async def get_model_config(
local_files_only = probe_local_only,
)
is_embedding = is_embedding_model(inspection_target, hf_token = hf_token)
+ layout = decision_layout(
+ model_name, hf_token = hf_token, local_files_only = probe_local_only
+ )
+ is_decision = layout is not None
+ decision_checkpoints = None
+ if layout == "clef":
+ from core.systemone.catalog import CLEF_DEFAULTS_REPO
+
+ # Local Clef folders and Studio fine-tunes start from Clef-flash's recipe.
+ if config_dict == load_model_defaults("default"):
+ config_dict = load_model_defaults(CLEF_DEFAULTS_REPO)
+ elif is_decision:
+ from core.systemone.catalog import CHECKPOINTS, LAYA_REPO
+ config_dict = load_model_defaults(LAYA_REPO)
+ decision_checkpoints = [
+ {"name": c.name, "subfolder": c.subfolder, "description": c.description}
+ for c in CHECKPOINTS.values()
+ if c.source == model_name
+ ] or None
audio_type, audio_type_definitive = detect_audio_type_checked(
_audio_probe_target(inspection_target),
hf_token = hf_token,
@@ -2468,12 +2497,15 @@ async def get_model_config(
config = config_dict,
is_vision = is_vision,
is_embedding = is_embedding,
+ is_decision = is_decision,
+ decision_layout = layout,
+ decision_checkpoints = decision_checkpoints,
is_lora = is_lora,
is_audio = audio_type is not None,
audio_type = audio_type,
audio_type_known = audio_type_definitive,
has_audio_input = is_audio_input_type(audio_type),
- model_type = derive_model_type(is_vision, audio_type, is_embedding),
+ model_type = derive_model_type(is_vision, audio_type, is_embedding, is_decision),
base_model = base_model,
max_position_embeddings = max_position_embeddings,
# Keyed on the target, not the flag: the bare repo id an anonymous caller
diff --git a/studio/backend/routes/settings.py b/studio/backend/routes/settings.py
index 444a5d6ac46..ac7c62bb0e7 100644
--- a/studio/backend/routes/settings.py
+++ b/studio/backend/routes/settings.py
@@ -37,7 +37,13 @@ from auth.authentication import (
)
from auth.storage import rotate_preview_link_secret
from auth import policy
-from utils.account_context import OWNER, bind_account, current_account, reset_account
+from utils.account_context import (
+ OWNER,
+ bind_account,
+ current_account,
+ is_owner_context,
+ reset_account,
+)
from hub.utils.hf_tokens import cache_reads_authorized, cached_read_refused, hf_token_arg
from routes.provider_credentials import current_credential_write, require_ui_session
@@ -646,6 +652,10 @@ class SystemOneModelOption(BaseModel):
name: str
description: str
download_bytes: int
+ kind: Literal["catalog", "fine_tune"] = "catalog"
+ label: Optional[str] = None
+ available: bool = True
+ unavailable_reason: Optional[str] = None
class SystemOneConnectionOption(BaseModel):
@@ -1455,13 +1465,32 @@ def update_helper_precache(
return _helper_precache_response(enabled)
+def _clef_availability(checkpoint, reason: Optional[str]) -> dict:
+ if reason is None or getattr(checkpoint, "layout", "laya") != "clef":
+ return {}
+ return {"available": False, "unavailable_reason": reason}
+
+
def _systemone_response(request: Request) -> SystemOneSettingsResponse:
+ from pathlib import Path
+
from core.systemone import catalog, laya_runtime
from routes.systemone import MCP_PATH
+ clef_reason = catalog.clef_unsupported_reason(wait = False)
enabled = systemone_settings.get_enabled()
runtime = laya_runtime.status()
- model = catalog.default_checkpoint().name
+ configured = catalog.default_checkpoint()
+ model = configured.name
+ if is_owner_context():
+ fine_tunes = catalog.fine_tunes()
+ else:
+ # Other accounts see only the configured model, never the owner's other output folders.
+ fine_tunes = [configured] if catalog.is_fine_tune_name(configured.name) else []
+ if runtime["loaded_model"] != model:
+ runtime["loaded_model"] = runtime["device"] = None
+ if runtime["loading_model"] != model:
+ runtime["loading_model"] = None
error = runtime["error"]
if runtime["error_model"] not in (None, model):
error = None
@@ -1476,9 +1505,23 @@ def _systemone_response(request: Request) -> SystemOneSettingsResponse:
gpu_available = systemone_settings.gpu_available(),
models = [
SystemOneModelOption(
- name = c.name, description = c.description, download_bytes = c.download_bytes
+ name = c.name,
+ description = c.description,
+ download_bytes = c.download_bytes,
+ **_clef_availability(c, clef_reason),
)
for c in catalog.CHECKPOINTS.values()
+ ]
+ + [
+ SystemOneModelOption(
+ name = c.name,
+ description = c.description,
+ download_bytes = 0,
+ kind = "fine_tune",
+ label = Path(c.source).name,
+ **_clef_availability(c, clef_reason),
+ )
+ for c in fine_tunes
],
loaded_model = runtime["loaded_model"],
loaded_device = runtime["device"],
@@ -1520,7 +1563,8 @@ def _check_systemone_expectations(payload: SystemOneSettingsPayload) -> None:
raise HTTPException(status_code = 409, detail = "Decision API settings changed. Try again.")
-@_shared_settings_router.get("/systemone", response_model = SystemOneSettingsResponse)
+# Not the shared router, which reads as the owner for everyone: this answer depends on who asks.
+@_account_settings_router.get("/systemone", response_model = SystemOneSettingsResponse)
def get_systemone_settings(
request: Request, current_subject: str = Depends(get_current_subject)
) -> SystemOneSettingsResponse:
diff --git a/studio/backend/routes/systemone.py b/studio/backend/routes/systemone.py
index 0033d07851f..7b14b60a3c0 100644
--- a/studio/backend/routes/systemone.py
+++ b/studio/backend/routes/systemone.py
@@ -138,11 +138,10 @@ async def system_one(
f"Unsupported field(s): {', '.join(sorted(payload.model_extra))}",
)
checkpoint = await asyncio.to_thread(catalog.resolve, payload.model)
- if checkpoint is None:
- raise _error(400, "api_usage_error", f"Unknown model: {payload.model}")
from auth.authentication import request_admitted_without_credential
# Same rule as the OpenAI routes: a keyless caller never downloads or swaps in another model.
+ # Checked before the unknown-model answer, so it cannot tell which owner fine-tunes exist.
if checkpoint != await asyncio.to_thread(
catalog.default_checkpoint
) and await asyncio.to_thread(request_admitted_without_credential, request):
@@ -151,6 +150,8 @@ async def system_one(
"permission_error",
"Keyless requests can only use the configured Decision API model; send an API key to pick another.",
)
+ if checkpoint is None:
+ raise _error(400, "api_usage_error", f"Unknown model: {payload.model}")
result = await _decide(checkpoint, payload.state, payload.questions)
return JSONResponse(result, headers = {"x-typesafe-request-id": str(uuid4())})
diff --git a/studio/backend/routes/training.py b/studio/backend/routes/training.py
index c9442486f1e..4bdecc9716f 100644
--- a/studio/backend/routes/training.py
+++ b/studio/backend/routes/training.py
@@ -62,7 +62,11 @@ try:
training_run_config,
)
from storage.studio_db import get_resumable_run_by_output_dir
- from utils.models.model_config import detect_gguf_model, load_model_defaults
+ from utils.models.model_config import (
+ detect_gguf_model,
+ is_decision_model,
+ load_model_defaults,
+ )
from utils.paths import is_local_path, normalize_path, resolve_dataset_path
except ImportError:
parent_backend = backend_path.parent / "backend"
@@ -84,7 +88,11 @@ except ImportError:
training_run_config,
)
from storage.studio_db import get_resumable_run_by_output_dir
- from utils.models.model_config import detect_gguf_model, load_model_defaults
+ from utils.models.model_config import (
+ detect_gguf_model,
+ is_decision_model,
+ load_model_defaults,
+ )
from utils.paths import is_local_path, normalize_path, resolve_dataset_path
from auth.authentication import authenticated_via_api_key, get_current_subject
@@ -1035,6 +1043,22 @@ def _reject_untrainable_model_request(
)
refuse_unauthorized_cache(has_cached_model)
+ if request.is_decision:
+ from core.systemone import laya_runtime
+ from core.systemone.catalog import Checkpoint
+
+ # Laya caches only the files a checkpoint loads, which the snapshot lookup above misses.
+ if laya_runtime.is_cached(
+ Checkpoint(
+ "base",
+ request.model_name,
+ request.model_subfolder,
+ "",
+ layout = request.decision_layout or "laya",
+ )
+ ):
+ refuse_unauthorized_cache(lambda: True)
+ return _ModelPreflightResult(model_name, model_local_path, None)
if path is None and offline_mode:
raise _hf_preflight_error(
409,
@@ -1059,10 +1083,15 @@ def _reject_untrainable_model_request(
"Retry before starting training."
),
)
- remote_format = _remote_untrainable_model_format(
- request.model_name,
- hf_token,
- is_embedding = bool(getattr(request, "is_embedding", False)),
+ # A decision checkpoint is checked at its subfolder below, whatever the repo root holds.
+ remote_format = (
+ None
+ if request.is_decision
+ else _remote_untrainable_model_format(
+ request.model_name,
+ hf_token,
+ is_embedding = bool(getattr(request, "is_embedding", False)),
+ )
)
except HTTPException as error:
metadata_error = error
@@ -1086,6 +1115,14 @@ def _reject_untrainable_model_request(
)
else:
if remote_format is None:
+ if request.is_decision and not is_decision_model(
+ request.model_name, hf_token, subfolder = request.model_subfolder
+ ):
+ raise _training_start_error(
+ 400,
+ "training_remote_model_not_decision",
+ f"{request.model_name} is not a decision model (Laya or Clef).",
+ )
return _ModelPreflightResult(model_name, model_local_path, cached_model_pin)
if remote_format == "gguf":
raise _training_start_error(
@@ -1098,6 +1135,17 @@ def _reject_untrainable_model_request(
"training_remote_model_adapter_only",
"Adapter models are inference-only and cannot be trained as base models.",
)
+ if request.is_decision:
+ folder = path / request.model_subfolder if request.model_subfolder else path
+ if not is_decision_model(str(folder)):
+ raise _training_start_error(
+ 400,
+ "training_local_model_not_decision",
+ "The selected model is not a decision checkpoint: Laya needs "
+ "rl_agent_config.json, model.safetensors, encoder/ and tokenizer/, and Clef "
+ "needs config.json, joint_head.safetensors and joint_head_config.json.",
+ )
+ return _ModelPreflightResult(model_name, model_local_path, None)
has_trainable_weights = _has_trainable_local_weights(path, request.model_name)
if has_trainable_weights:
return _ModelPreflightResult(model_name, model_local_path, cached_model_pin)
@@ -1148,6 +1196,11 @@ def _validate_training_platform(request: TrainingStartRequest) -> None:
status_code = 400,
detail = "Embedding model training is not supported for MLX training yet.",
)
+ if request.is_decision:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision model training is not supported for MLX training yet.",
+ )
if request.is_dataset_audio:
raise HTTPException(
status_code = 400,
@@ -1160,6 +1213,125 @@ def _validate_training_platform(request: TrainingStartRequest) -> None:
)
+# A plain folder name: no separators, globs, drive letters or dot segments.
+_CHECKPOINT_SUBFOLDER = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
+# The frontend's LR_DEFAULT_DECISION_FULL; the model defaults hold the LoRA rate.
+_DECISION_FULL_FINETUNING_LR = "2.5e-5"
+
+
+def _validate_decision_request(request: TrainingStartRequest, via_api_key: bool = False) -> None:
+ request.decision_layout = None
+ if not request.is_decision:
+ return
+ # Decision models train on one GPU, so admission and chat coexistence are sized for that one.
+ if request.gpu_ids and len(request.gpu_ids) > 1:
+ request.gpu_ids = request.gpu_ids[:1]
+ from core.systemone.catalog import CHECKPOINTS, CLEF_DEFAULTS_REPO, LAYA_REPO
+ from utils.account_context import is_owner_context
+ from utils.models.model_config import decision_layout
+
+ if not is_owner_context():
+ raise HTTPException(
+ status_code = 403,
+ detail = "Only the Studio owner can fine-tune decision models, since only the "
+ "owner's fine-tunes can be served by the Decision API.",
+ )
+ if sys.version_info < (3, 10):
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision model training needs Python 3.10 or newer, like the Decision "
+ "API that serves the fine-tunes.",
+ )
+ if request.training_type == "Continued Pretraining":
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision models train with LoRA or full fine-tuning; continued "
+ "pretraining is not available for them.",
+ )
+ if request.resume_from_checkpoint:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision model runs cannot be resumed; start a new run instead.",
+ )
+ if request.dataset_streaming:
+ raise HTTPException(
+ status_code = 400,
+ detail = "dataset_streaming is not supported for decision model training.",
+ )
+ unset = TrainingStartRequest.model_fields.keys() - request.model_fields_set
+ # Unknown (offline, no access) stays Laya: the preflight then names what is missing.
+ layout = decision_layout(
+ request.model_name,
+ hf_token_arg(request.hf_token, allow_ambient_token = via_api_key is not True),
+ subfolder = request.model_subfolder,
+ )
+ if layout == "clef":
+ from core.systemone.catalog import clef_unsupported_reason
+
+ if (reason := clef_unsupported_reason()) is not None:
+ raise HTTPException(status_code = 400, detail = reason)
+ request.decision_layout = "clef"
+ if request.model_subfolder is not None:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Clef repos hold one checkpoint, so model_subfolder must be left out.",
+ )
+ if request.use_dora or request.use_loftq:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision models train with plain LoRA, so DoRA and LoftQ are not "
+ "available for them.",
+ )
+ defaults = load_model_defaults(request.model_name)
+ if defaults == load_model_defaults("default"):
+ defaults = load_model_defaults(CLEF_DEFAULTS_REPO)
+ for section in ("training", "lora", "logging"):
+ for key, value in (defaults.get(section) or {}).items():
+ if key in unset:
+ setattr(request, key, value)
+ if "learning_rate" in unset and request.training_type == "Full Finetuning":
+ request.learning_rate = _DECISION_FULL_FINETUNING_LR
+ return
+ request.decision_layout = "laya"
+ if (
+ request.training_type == "LoRA/QLoRA"
+ and request.load_in_4bit
+ and "load_in_4bit" not in unset
+ ):
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision models train in 16-bit, so QLoRA is not available for them. "
+ "Set load_in_4bit to false to train with LoRA.",
+ )
+ subfolder = request.model_subfolder
+ if subfolder is not None and (
+ not _CHECKPOINT_SUBFOLDER.fullmatch(subfolder)
+ or (
+ request.model_name == LAYA_REPO
+ and subfolder not in {c.subfolder for c in CHECKPOINTS.values()}
+ )
+ ):
+ raise HTTPException(
+ status_code = 400,
+ detail = f"Invalid checkpoint subfolder {subfolder!r} for {request.model_name}.",
+ )
+ if request.use_dora or request.use_loftq:
+ raise HTTPException(
+ status_code = 400,
+ detail = "Decision models train with plain LoRA, so DoRA and LoftQ are not "
+ "available for them.",
+ )
+ request.load_in_4bit = False
+ # Fields an API or MCP caller left out take the Laya recipe the UI starts from.
+ defaults = load_model_defaults(LAYA_REPO)
+ for section in ("training", "lora", "logging"):
+ for key, value in (defaults.get(section) or {}).items():
+ if key in unset:
+ setattr(request, key, value)
+ if "learning_rate" in unset and request.training_type == "Full Finetuning":
+ request.learning_rate = _DECISION_FULL_FINETUNING_LR
+
+
_RESUME_DATASET_DEFAULTS = {
"hf_dataset": None,
"local_datasets": [],
@@ -1434,6 +1606,7 @@ async def start_training(
Initiates training in the background and returns immediately. Use /status
to check progress.
"""
+ await asyncio.to_thread(_validate_decision_request, request, via_api_key)
if managed_account():
from utils.paths import tensorboard_root
@@ -1797,6 +1970,9 @@ async def start_training(
"is_dataset_image": request.is_dataset_image,
"is_dataset_audio": request.is_dataset_audio,
"is_embedding": request.is_embedding,
+ "is_decision": request.is_decision,
+ "model_subfolder": request.model_subfolder,
+ "decision_layout": request.decision_layout,
"enable_wandb": request.enable_wandb,
"wandb_token": request.wandb_token or "",
"wandb_project": request.wandb_project or "",
@@ -1918,6 +2094,14 @@ async def start_training(
except Exception as e:
logger.warning("Could not unload video model for training: %s", e)
+ try:
+ from core.systemone import laya_runtime
+ if laya_runtime.status()["device"] not in (None, "cpu"):
+ logger.info("Unloading the Decision API model to free GPU memory for training")
+ laya_runtime.unload()
+ except Exception as e:
+ logger.warning("Could not unload the Decision API model for training: %s", e)
+
try:
from routes.training_vram import (
can_keep_chat_during_training,
diff --git a/studio/backend/tests/multi_account/test_decision_api_fine_tunes.py b/studio/backend/tests/multi_account/test_decision_api_fine_tunes.py
new file mode 100644
index 00000000000..587a238d60b
--- /dev/null
+++ b/studio/backend/tests/multi_account/test_decision_api_fine_tunes.py
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+from types import SimpleNamespace
+
+import pytest
+from fastapi.testclient import TestClient
+
+from core.systemone import catalog, laya_runtime
+from utils import systemone_settings
+from utils.account_context import OWNER, run_as
+from utils.paths import outputs_root
+
+from .support import make_app
+
+QUESTIONS = {"urgent": {"type": "noul", "instructions": "Does this need a reply now?"}}
+
+
+def _answer(agent, state, questions):
+ answers = {name: {"type": "noul", "noul": 0.5, "confidence": 0.5} for name in questions}
+ return {"answers": answers, "usage": {"input_tokens": 1, "output_tokens": 0}}, False
+
+
+def client(accounts, monkeypatch):
+ from routes import systemone
+ from routes.settings import router as settings_router
+
+ for name in (
+ "UNSLOTH_SYSTEMONE_MODEL",
+ "UNSLOTH_SYSTEMONE_DISABLE",
+ "UNSLOTH_SYSTEMONE_DEVICE",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ for name in ("_agent", "_loaded", "_device_name", "_loader", "_loading", "_failure"):
+ monkeypatch.setattr(laya_runtime, name, None)
+ monkeypatch.setattr(systemone_settings, "runtime_unavailable_reason", lambda: None)
+ monkeypatch.setattr(
+ laya_runtime, "_load_checkpoint", lambda checkpoint: (SimpleNamespace(), "cpu")
+ )
+ monkeypatch.setattr(laya_runtime, "_predict", _answer)
+ app = make_app()
+ app.include_router(systemone.router, prefix = "/v1")
+ app.include_router(settings_router, prefix = "/api/settings")
+ with TestClient(app) as client:
+ yield client
+ if laya_runtime._loader is not None:
+ laya_runtime._loader.join(5)
+
+
+def _fine_tune(folder):
+ path = run_as(OWNER, outputs_root) / folder
+ for name in ("encoder", "tokenizer"):
+ (path / name).mkdir(parents = True)
+ (path / "model.safetensors").write_bytes(b"x")
+ (path / "rl_agent_config.json").write_text("{}", encoding = "utf-8")
+ return catalog.FINE_TUNE_PREFIX + folder
+
+
+def _login(client, username):
+ response = client.post(
+ "/api/auth/login", json = {"username": username, "password": "account-password"}
+ )
+ assert response.status_code == 200, response.text
+ return {"Authorization": f"Bearer {response.json()['access_token']}"}
+
+
+def test_a_managed_account_sees_only_the_configured_fine_tune(client):
+ served = _fine_tune("laya_served_1")
+ private = _fine_tune("laya_hr_layoffs_q4_2")
+ owner, bob = _login(client, "unsloth"), _login(client, "bob")
+ saved = client.put(
+ "/api/settings/systemone", json = {"enabled": True, "model": served}, headers = owner
+ )
+ assert saved.status_code == 200, saved.text
+ # The owner's own API call makes the other fine-tune the resident model.
+ decided = client.post(
+ "/v1/systemone",
+ json = {"model": private, "state": "x", "questions": QUESTIONS},
+ headers = owner,
+ )
+ assert decided.status_code == 200, decided.text
+
+ def view(headers):
+ settings = client.get("/api/settings/systemone", headers = headers).json()
+ listed = [m["name"] for m in settings["models"] if m["kind"] == "fine_tune"]
+ return settings["model"], listed, settings["loaded_model"]
+
+ assert view(owner) == (served, [private, served], private)
+ assert view(bob) == (served, [served], None)
diff --git a/studio/backend/tests/test_decision_serving.py b/studio/backend/tests/test_decision_serving.py
new file mode 100644
index 00000000000..069da20101c
--- /dev/null
+++ b/studio/backend/tests/test_decision_serving.py
@@ -0,0 +1,590 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import json
+import os
+import shutil
+import struct
+import sys
+import time
+from types import SimpleNamespace
+
+import httpx
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from auth.authentication import get_current_subject
+from core.inference import external_provider
+from core.systemone import catalog, laya_runtime
+from routes import systemone
+from storage import credential_secrets, providers_db
+from utils import systemone_settings
+from utils.account_context import OWNER, run_as
+from utils.paths import outputs_root
+
+_REAL_LOAD = laya_runtime._load_checkpoint
+QUESTIONS = {"urgent": {"type": "noul", "instructions": "Does this need a reply now?"}}
+UPSTREAM = {
+ "model": "jev-1.13",
+ "answers": {"urgent": {"type": "noul", "noul": 0.93}},
+ "usage": {"input_tokens": 5, "output_tokens": 0},
+}
+
+
+def _answer(agent, state, questions):
+ answers = {name: {"type": "noul", "noul": 0.5, "confidence": 0.5} for name in questions}
+ return {"answers": answers, "usage": {"input_tokens": 1, "output_tokens": 0}}, False
+
+
+def home(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "home"))
+ for name in (
+ "UNSLOTH_SYSTEMONE_MODEL",
+ "UNSLOTH_SYSTEMONE_DISABLE",
+ "UNSLOTH_SYSTEMONE_DEVICE",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ for name in ("_agent", "_loaded", "_device_name", "_loader", "_loading", "_failure"):
+ monkeypatch.setattr(laya_runtime, name, None)
+ monkeypatch.setattr(systemone_settings, "runtime_unavailable_reason", lambda: None)
+ monkeypatch.setattr(
+ laya_runtime, "_load_checkpoint", lambda checkpoint: (SimpleNamespace(), "cpu")
+ )
+ monkeypatch.setattr(laya_runtime, "_predict", _answer)
+ outputs = run_as(OWNER, outputs_root)
+ outputs.mkdir(parents = True)
+ yield outputs
+ if laya_runtime._loader is not None:
+ laya_runtime._loader.join(5)
+
+
+def client(home):
+ from routes.settings import router as settings_router
+
+ app = FastAPI()
+ app.include_router(systemone.router, prefix = "/v1")
+ app.include_router(settings_router, prefix = "/api/settings")
+ app.dependency_overrides[get_current_subject] = lambda: "unsloth"
+ return TestClient(app)
+
+
+def _fine_tune(outputs, folder):
+ path = outputs / folder
+ for name in ("encoder", "tokenizer"):
+ (path / name).mkdir(parents = True)
+ # A float16 safetensors header, as the trainer saves.
+ header = json.dumps({"w": {"dtype": "F16", "shape": [1], "data_offsets": [0, 2]}}).encode()
+ (path / "model.safetensors").write_bytes(struct.pack("<Q", len(header)) + header + bytes(2))
+ (path / "rl_agent_config.json").write_text("{}", encoding = "utf-8")
+ return catalog.FINE_TUNE_PREFIX + folder
+
+
+def _post(client, model = "default"):
+ return client.post(
+ "/v1/systemone", json = {"model": model, "state": "The site is down.", "questions": QUESTIONS}
+ )
+
+
+def _put(client, **settings):
+ return client.put("/api/settings/systemone", json = settings)
+
+
+def _listed(client):
+ models = client.get("/api/settings/systemone").json()["models"]
+ return [m["name"] for m in models if m["kind"] == "fine_tune"]
+
+
+def test_hidden_and_staged_folders_are_not_models(home, client):
+ kept = _fine_tune(home, "laya_kept_1")
+ staged = _fine_tune(home, ".laya_gone_2.deleting-" + "0" * 32)
+ hidden = _fine_tune(home, ".laya_hidden_3")
+ assert _listed(client) == [kept]
+ for name in (staged, hidden):
+ assert _put(client, model = name).status_code == 400, name
+
+
[email protected]("folder", ["ft\x001", "loop"])
+def test_unusable_fine_tune_names_are_unknown_models(home, client, folder):
+ # outputs/loop -> loop
+ os.symlink("loop", home / "loop")
+ name = catalog.FINE_TUNE_PREFIX + folder
+ assert _put(client, enabled = True).status_code == 200
+ assert _post(client, name).status_code == 400
+ assert client.get("/api/settings/systemone/resolve", params = {"model": name}).status_code == 400
+ assert _put(client, model = name).status_code == 400
+
+
+def test_keyless_callers_cannot_probe_fine_tune_names(home, client, monkeypatch):
+ import auth.authentication
+
+ served = _fine_tune(home, "laya_served_1")
+ _fine_tune(home, "laya_private_2")
+ assert _put(client, enabled = True, model = served).status_code == 200
+ monkeypatch.setattr(auth.authentication, "request_admitted_without_credential", lambda r: True)
+ existing = _post(client, catalog.FINE_TUNE_PREFIX + "laya_private_2")
+ missing = _post(client, catalog.FINE_TUNE_PREFIX + "laya_missing_3")
+ assert existing.status_code == missing.status_code == 403
+ assert existing.json() == missing.json()
+ assert _post(client, served).status_code == 200
+
+
+def gpu(home, monkeypatch):
+ pytest.importorskip("torch")
+ from utils import torch_device_probe
+ from utils.hardware import hardware
+
+ monkeypatch.setenv("UNSLOTH_SYSTEMONE_DEVICE", "gpu")
+ monkeypatch.setattr(hardware, "get_device", lambda: hardware.DeviceType.CUDA)
+ monkeypatch.setattr(torch_device_probe, "device_can_allocate", lambda device: True)
+ # The real loader around a stand-in model; placing it only records where it would go.
+ state = SimpleNamespace(training = False, placed = [], on_build = None)
+
+ def build(path, **kwargs):
+ if state.on_build:
+ state.on_build()
+ return SimpleNamespace()
+
+ def place(agent, device, fp16_checkpoint):
+ state.placed.append(device.type)
+ agent.device = device
+
+ monkeypatch.setattr(laya_runtime, "_load_checkpoint", _REAL_LOAD)
+ monkeypatch.setattr(laya_runtime, "_load_laya", build)
+ monkeypatch.setattr(laya_runtime, "_place", place)
+ monkeypatch.setattr(laya_runtime, "_training_active", lambda: state.training)
+ # Imported here, so a cold import does not count against a request's load wait.
+ laya_runtime._laya()
+ return state
+
+
+def test_the_model_returns_to_the_gpu_after_training(home, client, gpu):
+ assert _put(client, enabled = True, model = _fine_tune(home, "laya_served_1")).status_code == 200
+ assert _post(client).status_code == 200
+ gpu.training = True
+ # What the training start hook does with a model on the GPU.
+ laya_runtime.unload()
+ assert _post(client).status_code == 200
+ assert _post(client).status_code == 200
+ assert gpu.placed == ["cuda", "cpu"]
+ gpu.training = False
+ assert _post(client).status_code == 200
+ assert _post(client).status_code == 200
+ assert gpu.placed == ["cuda", "cpu", "cuda"]
+ assert client.get("/api/settings/systemone").json()["loaded_device"] == "cuda"
+
+
+def test_training_takes_the_gpu_from_a_load_in_flight_or_a_model_it_missed(home, client, gpu):
+ def training_starts():
+ gpu.training, gpu.on_build = True, None
+
+ gpu.on_build = training_starts
+ assert _put(client, enabled = True, model = _fine_tune(home, "laya_served_1")).status_code == 200
+ assert _post(client).status_code == 200
+ assert gpu.placed == ["cpu"]
+ gpu.training = False
+ assert _post(client).status_code == 200
+ gpu.training = True
+ assert _post(client).status_code == 200
+ assert gpu.placed == ["cpu", "cuda", "cpu"]
+
+
+def upstream(home, monkeypatch):
+ for module in (credential_secrets, providers_db):
+ monkeypatch.setattr(module, "_schema_ready", set())
+ monkeypatch.setattr(
+ credential_secrets, "get_or_create_credential_encryption_key", lambda: b"k" * 32
+ )
+ calls = []
+
+ def handle(request):
+ calls.append(request)
+ return httpx.Response(200, json = UPSTREAM)
+
+ monkeypatch.setattr(
+ external_provider,
+ "_http_client",
+ httpx.AsyncClient(transport = httpx.MockTransport(handle)),
+ )
+ providers_db.create_provider(
+ id = "deciders",
+ provider_type = "typesafe",
+ display_name = "TypeSafe",
+ base_url = "https://api.typesafe.ai/v1",
+ models = ["jev-latest"],
+ api_type = "chat_completions",
+ )
+ credential_secrets.save_provider_api_key("deciders", "ts-key")
+ return calls
+
+
+def _mcp_model():
+ from fastmcp import Client
+ async def call():
+ async with Client(systemone.decisions_mcp) as mcp:
+ return await mcp.call_tool("decide", {"state": "x", "questions": QUESTIONS})
+
+ return asyncio.run(call()).structured_content["model"]
+
+
+def test_connections_and_fine_tunes_work_side_by_side(home, client, upstream):
+ connection = "connection:deciders:jev-latest"
+ served = _fine_tune(home, "laya_served_1")
+ other = _fine_tune(home, "laya_other_2")
+ assert _listed(client) == [other, served]
+ listed = client.get("/api/settings/systemone/connections").json()
+ assert [option["name"] for option in listed] == [connection]
+
+ assert _put(client, enabled = True, model = connection).status_code == 200
+ assert _post(client, "jev-latest").json() == UPSTREAM
+ assert _post(client, connection).json() == UPSTREAM
+ assert _post(client, served).json()["model"] == served
+ assert _mcp_model() == "jev-1.13"
+ assert _listed(client) == [other, served]
+
+ assert _put(client, model = served).status_code == 200
+ assert client.get("/api/settings/systemone").json()["model"] == served
+ assert _post(client, "jev-latest").json()["model"] == served
+ assert _post(client, other).json()["model"] == other
+ assert _post(client, connection).status_code == 400
+ assert _mcp_model() == served
+ for bad in ("connection:deciders:jev-1.13", "connection:gone:jev-latest", "laya-ft:laya_gone"):
+ response = client.post("/api/settings/systemone/validate", json = {"model": bad})
+ assert response.status_code == 400, bad
+ assert len(upstream) == 3
+
+ # A removed connection stays configured and says so; a deleted fine-tune falls back.
+ assert _put(client, model = connection).status_code == 200
+ providers_db.delete_provider("deciders")
+ assert client.get("/api/settings/systemone").json()["model"] == connection
+ assert "removed" in _post(client).json()["detail"]["message"]
+ assert _put(client, model = served).status_code == 200
+ shutil.rmtree(home / "laya_served_1")
+ assert client.get("/api/settings/systemone").json()["model"] == "laya-multilingual"
+
+
+def test_the_environment_can_pin_a_fine_tune_or_a_folder(home, client, monkeypatch):
+ served = _fine_tune(home, "laya_served_1")
+ assert _put(client, enabled = True).status_code == 200
+ monkeypatch.setenv("UNSLOTH_SYSTEMONE_MODEL", served)
+ settings = client.get("/api/settings/systemone").json()
+ assert (settings["model"], settings["model_locked"]) == (served, True)
+ assert _post(client).json()["model"] == served
+ assert _put(client, model = "laya-english").status_code == 400
+
+ monkeypatch.setenv("UNSLOTH_SYSTEMONE_MODEL", str(home / "laya_served_1"))
+ assert client.get("/api/settings/systemone").json()["model"] == catalog.LOCAL_NAME
+ assert _post(client, catalog.LOCAL_NAME).json()["model"] == catalog.LOCAL_NAME
+ assert _post(client, served).json()["model"] == served
+
+
+def _clef_fine_tune(outputs, folder):
+ path = outputs / folder
+ path.mkdir(parents = True)
+ for name in ("config.json", "joint_head.safetensors", "joint_head_config.json"):
+ (path / name).write_text("{}", encoding = "utf-8")
+ (path / "model.safetensors").write_bytes(b"")
+ return catalog.CLEF_FINE_TUNE_PREFIX + folder
+
+
+def _spoof_device(monkeypatch, kind):
+ # ROCm hosts report DeviceType.CUDA, like NVIDIA ones.
+ from utils.hardware import hardware
+
+ device = {
+ "cuda": hardware.DeviceType.CUDA,
+ "rocm": hardware.DeviceType.CUDA,
+ "mlx": hardware.DeviceType.MLX,
+ "xpu": hardware.DeviceType.XPU,
+ "cpu": hardware.DeviceType.CPU,
+ }[kind]
+ monkeypatch.setattr(hardware, "get_device", lambda: device)
+ monkeypatch.setattr(hardware, "DEVICE", device)
+
+
+def clef(home, monkeypatch):
+ from core.systemone import clef_runtime
+
+ state = SimpleNamespace(training = False, agents = [])
+
+ class Agent:
+ device = "cuda"
+
+ def __init__(
+ self,
+ folder,
+ cancelled = None,
+ ):
+ self.folder, self.closed, self.cancelled = folder, False, cancelled
+ state.agents.append(self)
+
+ def decide(self, state_, questions):
+ answers = {name: {"type": "noul", "noul": 0.25} for name in questions}
+ return {"answers": answers, "input_tokens": 7, "truncated": False}
+
+ def close(self):
+ self.closed = True
+
+ monkeypatch.setattr(clef_runtime, "ClefAgent", Agent)
+ _spoof_device(monkeypatch, "cuda")
+ monkeypatch.setattr(laya_runtime, "_load_checkpoint", _REAL_LOAD)
+ monkeypatch.setattr(laya_runtime, "_training_active", lambda: state.training)
+ return state
+
+
+def test_a_clef_fine_tune_serves_through_its_worker(home, client, clef):
+ served = _clef_fine_tune(home, "clef_served_1")
+ assert _listed(client) == [served]
+ # The trainer's "Use in Decision API" names every run laya-ft:; the layout picks the prefix.
+ assert _put(client, enabled = True, model = "laya-ft:clef_served_1").status_code == 200
+ assert client.get("/api/settings/systemone").json()["model"] == served
+
+ answer = _post(client).json()
+ assert answer["model"] == served
+ assert answer["answers"]["urgent"] == {"type": "noul", "noul": 0.25}
+ assert answer["usage"] == {"input_tokens": 7, "output_tokens": 0}
+ assert client.get("/api/settings/systemone").json()["loaded_device"] == "cuda"
+
+ # Clef has no CPU fallback: during training it waits, and its worker is ended.
+ clef.training = True
+ busy = _post(client)
+ assert busy.status_code == 503
+ assert "training run" in busy.json()["detail"]["message"]
+ assert clef.agents[0].closed
+ clef.training = False
+ assert _post(client).status_code == 200
+ assert len(clef.agents) == 2
+ laya_runtime.unload()
+ assert clef.agents[1].closed
+
+
+def test_a_clef_load_that_training_overtakes_frees_the_gpu(home, clef, monkeypatch):
+ from core.systemone import clef_runtime
+
+ # The loader thread outlives the request that started it, so no later request evicts it.
+ checkpoint = catalog.resolve(_clef_fine_tune(home, "clef_overtaken_1"))
+ real = clef_runtime.ClefAgent
+
+ def overtaken(folder, cancelled = None):
+ agent = real(folder, cancelled)
+ clef.training = True
+ return agent
+
+ monkeypatch.setattr(clef_runtime, "ClefAgent", overtaken)
+ laya_runtime._load(checkpoint)
+ assert clef.agents[0].closed
+ assert laya_runtime._agent is None and laya_runtime._device_name is None
+ # The loader also stops the worker mid-load, not only once it reports ready.
+ assert clef.agents[0].cancelled is laya_runtime._training_active
+
+
+def test_a_clef_worker_that_never_reports_ready_is_stopped(monkeypatch):
+ from core.systemone import clef_runtime
+
+ calls = []
+
+ class Process:
+ exitcode = None
+
+ def __init__(self, **kwargs):
+ self.child = kwargs["args"][0]
+
+ def start(self):
+ # A live child holds its own end of the pipe, so the parent sees silence, not EOF.
+ # Keeping the parent's close from releasing it works on Windows too, where a pipe
+ # end is a handle os.dup cannot copy.
+ held.append(self.child)
+ self.child.close = lambda: None
+
+ def join(self, timeout = None):
+ calls.append("join")
+
+ def is_alive(self):
+ return "kill" not in calls
+
+ def kill(self):
+ calls.append("kill")
+
+ held = []
+ monkeypatch.setattr(clef_runtime._CTX, "Process", Process)
+ monkeypatch.setattr(clef_runtime, "LOAD_TIMEOUT_S", 0.01)
+ try:
+ with pytest.raises(clef_runtime.ClefWorkerError, match = "did not answer"):
+ clef_runtime.ClefAgent("unused")
+ finally:
+ for child in held:
+ del child.close
+ child.close()
+ assert "kill" in calls
+
+
+def test_a_training_run_stops_a_clef_worker_still_loading(monkeypatch):
+ from core.systemone import clef_runtime
+
+ calls = []
+
+ class Process:
+ exitcode = None
+
+ def __init__(self, **kwargs):
+ self.child = kwargs["args"][0]
+
+ def start(self):
+ # A live child holds its own end of the pipe, so the parent sees silence, not EOF.
+ # Keeping the parent's close from releasing it works on Windows too, where a pipe
+ # end is a handle os.dup cannot copy.
+ held.append(self.child)
+ self.child.close = lambda: None
+
+ def join(self, timeout = None):
+ calls.append("join")
+
+ def is_alive(self):
+ return "kill" not in calls
+
+ def kill(self):
+ calls.append("kill")
+
+ held = []
+ monkeypatch.setattr(clef_runtime._CTX, "Process", Process)
+ monkeypatch.setattr(clef_runtime, "LOAD_TIMEOUT_S", 600)
+ try:
+ started = time.monotonic()
+ with pytest.raises(clef_runtime.ClefWorkerError, match = "training run"):
+ clef_runtime.ClefAgent("unused", cancelled = lambda: True)
+ assert time.monotonic() - started < 30
+ finally:
+ for child in held:
+ del child.close
+ child.close()
+ assert "kill" in calls
+
+
+def test_the_catalog_offers_the_stock_clef_models():
+ for name, repo in (("clef", "Cloudflare/clef"), ("clef-flash", "Cloudflare/clef-flash")):
+ checkpoint = catalog.CHECKPOINTS[name]
+ assert (checkpoint.source, checkpoint.layout, checkpoint.subfolder) == (repo, "clef", None)
+ assert all(c.layout == "laya" for n, c in catalog.CHECKPOINTS.items() if n.startswith("laya"))
+
+
[email protected]("kind", ["mlx", "xpu", "cpu"])
+def test_clef_refuses_a_machine_without_an_nvidia_or_amd_gpu(home, client, clef, monkeypatch, kind):
+ served = _clef_fine_tune(home, "clef_nogpu_1")
+ assert _put(client, enabled = True, model = served).status_code == 200
+ _spoof_device(monkeypatch, kind)
+
+ refused = _post(client)
+ assert refused.status_code == 400
+ assert refused.json()["detail"]["message"] == catalog.CLEF_NEEDS_GPU
+ assert clef.agents == []
+ models = {m["name"]: m for m in client.get("/api/settings/systemone").json()["models"]}
+ for name in (served, "clef", "clef-flash"):
+ assert models[name]["available"] is False
+ assert models[name]["unavailable_reason"] == catalog.CLEF_NEEDS_GPU
+ assert all(m["available"] for n, m in models.items() if n.startswith("laya"))
+
+
[email protected]("kind", ["cuda", "rocm"])
+def test_clef_serves_on_nvidia_and_amd_gpus(home, client, clef, monkeypatch, kind):
+ served = _clef_fine_tune(home, "clef_gpu_1")
+ assert _put(client, enabled = True, model = served).status_code == 200
+ _spoof_device(monkeypatch, kind)
+ assert _post(client).status_code == 200
+ models = client.get("/api/settings/systemone").json()["models"]
+ assert all(m["available"] and m["unavailable_reason"] is None for m in models)
+
+
+def test_a_failed_device_probe_does_not_refuse_clef(monkeypatch):
+ from utils.hardware import hardware
+
+ def broken():
+ raise RuntimeError("probe failed")
+
+ monkeypatch.setattr(hardware, "get_device", broken)
+ assert catalog.clef_unsupported_reason() is None
+
+
+def test_settings_never_wait_on_device_detection(monkeypatch):
+ from utils.hardware import hardware
+
+ def slow():
+ raise AssertionError("Settings must not run device detection")
+
+ monkeypatch.setattr(hardware, "get_device", slow)
+ monkeypatch.setattr(hardware, "DEVICE", None)
+ assert catalog.clef_unsupported_reason(wait = False) is None
+ monkeypatch.setattr(hardware, "DEVICE", hardware.DeviceType.MLX)
+ assert catalog.clef_unsupported_reason(wait = False) == catalog.CLEF_NEEDS_GPU
+
+
+def _clef_agent(conn):
+ import threading
+
+ from core.systemone import clef_runtime
+
+ agent = object.__new__(clef_runtime.ClefAgent)
+ agent._lock, agent._broken, agent._conn = threading.Lock(), None, conn
+ agent._process = SimpleNamespace(exitcode = 1)
+ return agent
+
+
+def test_a_timed_out_clef_worker_is_never_asked_again(monkeypatch):
+ from core.systemone import clef_runtime
+
+ class Conn:
+ sent = 0
+
+ def send(self, message):
+ self.sent += 1
+
+ def poll(self, timeout):
+ return self.sent > 1 # the first answer comes late, after its request timed out
+
+ def recv(self):
+ return ("ok", {"answers": "for the request that timed out"})
+
+ monkeypatch.setattr(clef_runtime, "DECIDE_TIMEOUT_S", 0.01)
+ conn = Conn()
+ agent = _clef_agent(conn)
+ for _ in range(2):
+ with pytest.raises(clef_runtime.ClefWorkerError, match = "did not answer"):
+ agent.decide("state", {})
+ assert conn.sent == 1
+
+
+def test_a_clef_worker_that_died_after_loading_is_a_worker_error():
+ from core.systemone import clef_runtime
+ class Conn:
+ def send(self, message):
+ raise BrokenPipeError(32, "Broken pipe")
+
+ with pytest.raises(clef_runtime.ClefWorkerError, match = "exited"):
+ _clef_agent(Conn()).decide("state", {})
+
+
+def test_a_clef_prompt_that_fits_exactly_is_not_truncated(monkeypatch):
+ import types
+
+ from core.systemone import clef_runtime
+
+ def encode(tokenizer, record, max_length):
+ # The state needs `natural` tokens; anything over max_length is cut to fit.
+ return SimpleNamespace(input_ids = [0] * min(record["state"], max_length))
+
+ # Studio's backend CI has no unsloth_zoo, so the real module may not import: stand it in.
+ for name in ("unsloth", "unsloth.models"):
+ monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
+ monkeypatch.setitem(sys.modules, "unsloth.models.clef", SimpleNamespace(encode_record = encode))
+ size = clef_runtime.MAX_LENGTH
+
+ def truncated(natural):
+ encoded = encode(None, {"state": natural}, size)
+ return clef_runtime._truncated(None, natural, {}, encoded)
+
+ assert (truncated(size - 1), truncated(size), truncated(size + 1)) == (False, False, True)
diff --git a/studio/backend/tests/test_decision_training.py b/studio/backend/tests/test_decision_training.py
new file mode 100644
index 00000000000..8bdcc1e01f4
--- /dev/null
+++ b/studio/backend/tests/test_decision_training.py
@@ -0,0 +1,757 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import importlib.util
+import json
+import shutil
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+torch = pytest.importorskip("torch")
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from safetensors import safe_open
+
+from auth.authentication import get_current_subject
+from core.systemone import catalog, laya_runtime
+
+WORDS = (
+ "the server is down again refund my card charge twice please help now "
+ "angry calm fine login broken slow outage billing account password"
+).split()
+QUESTIONS = {
+ "urgent": {"type": "noul", "instructions": "Does this need a reply now?"},
+ "team": {
+ "type": "choice",
+ "instructions": "Which team should handle it?",
+ "criteria": {"outage": "service down", "billing": "charges and refunds"},
+ },
+ "mood": {
+ "type": "score",
+ "instructions": "How upset is the customer?",
+ "criteria": ["calm", "annoyed", "angry"],
+ },
+}
+
+
+def _row(i):
+ outage = i % 2 == 0
+ return {
+ "state": "the server is down again help now" if outage else "refund my card charge twice",
+ "questions": json.dumps(QUESTIONS),
+ "gold": json.dumps(
+ {
+ "urgent": {"label": "true" if outage else "false"},
+ "team": {
+ "label": "outage" if outage else "billing",
+ "probabilities": {"outage": 0.9, "billing": 0.1}
+ if outage
+ else {"outage": 0.2, "billing": 0.8},
+ },
+ "mood": {"label": 2 if outage else 0},
+ }
+ ),
+ }
+
+
+def _base_checkpoint(folder):
+ from tokenizers import Tokenizer, models, pre_tokenizers
+ from transformers import ModernBertConfig, PreTrainedTokenizerFast
+ from safetensors.torch import save_file
+
+ laya = laya_runtime._laya()
+ specials = ["[PAD]", "[SEP]", "[CLS]", "[UNK]", "[MASK]"]
+ vocab = {token: i for i, token in enumerate(specials + sorted(set(WORDS)))}
+ tokenizer = Tokenizer(models.WordLevel(vocab, unk_token = "[UNK]"))
+ tokenizer.pre_tokenizer = pre_tokenizers.Whitespace()
+ PreTrainedTokenizerFast(
+ tokenizer_object = tokenizer,
+ pad_token = "[PAD]",
+ sep_token = "[SEP]",
+ cls_token = "[CLS]",
+ unk_token = "[UNK]",
+ mask_token = "[MASK]",
+ ).save_pretrained(str(folder / "tokenizer"))
+ ModernBertConfig(
+ vocab_size = 64,
+ hidden_size = 64,
+ intermediate_size = 96,
+ num_hidden_layers = 2,
+ num_attention_heads = 4,
+ pad_token_id = 0,
+ cls_token_id = 2,
+ sep_token_id = 1,
+ global_attn_every_n_layers = 2,
+ local_attention = 16,
+ ).save_pretrained(str(folder / "encoder"))
+ cfg = {
+ "encoder": "tiny",
+ "head_layers": 1,
+ "act_costs": {"escalate": 0.5},
+ "max_len": 96,
+ "head_max_len": 48,
+ "temperature": [1.2, 1.1, 1.3],
+ "temperature_by_options": {"noul:2": 0.1},
+ }
+ torch.manual_seed(0)
+ model = laya.common.build_model(cfg, encoder_dir = str(folder / "encoder"))
+ save_file(
+ {k: v.half().contiguous() for k, v in model.state_dict().items()},
+ str(folder / "model.safetensors"),
+ )
+ (folder / "rl_agent_config.json").write_text(json.dumps(cfg), encoding = "utf-8")
+ return folder
+
+
+def studio_home(tmp_path, monkeypatch):
+ monkeypatch.setenv("UNSLOTH_STUDIO_HOME", str(tmp_path / "home"))
+ for name in (
+ "UNSLOTH_SYSTEMONE_MODEL",
+ "UNSLOTH_SYSTEMONE_DISABLE",
+ "UNSLOTH_SYSTEMONE_DEVICE",
+ ):
+ monkeypatch.delenv(name, raising = False)
+ for name in ("_agent", "_loaded", "_device_name", "_loader", "_loading", "_failure"):
+ monkeypatch.setattr(laya_runtime, name, None)
+ yield tmp_path
+ if laya_runtime._loader is not None:
+ laya_runtime._loader.join(30)
+
+
+def base(studio_home):
+ return _base_checkpoint(studio_home / "base")
+
+
+def _dataset(folder, rows):
+ path = folder / "decisions.jsonl"
+ path.write_text("\n".join(json.dumps(row) for row in rows), encoding = "utf-8")
+ return str(path)
+
+
+def _config(base, dataset, **overrides):
+ return {
+ "model_name": str(base),
+ "model_subfolder": None,
+ "is_decision": True,
+ "hf_dataset": "",
+ "local_datasets": [dataset],
+ "batch_size": 8,
+ "gradient_accumulation_steps": 2,
+ "num_epochs": 1,
+ "max_steps": 3,
+ "learning_rate": "1e-3",
+ "warmup_steps": 0,
+ "weight_decay": 0.01,
+ "lr_scheduler_type": "cosine",
+ "optim": "adamw_torch",
+ "random_seed": 3407,
+ "gradient_checkpointing": "none",
+ "eval_steps": 0,
+ "project_name": None,
+ **overrides,
+ }
+
+
+# The worker imports unsloth; CI installs unsloth_zoo only for the step that runs this file.
+needs_worker = pytest.mark.skipif(
+ sys.platform == "darwin" or importlib.util.find_spec("unsloth_zoo") is None,
+ reason = "trains in a worker that imports unsloth (Apple Silicon trains with MLX)",
+)
+
+
+def _train(
+ config,
+ stop = None,
+ when = lambda event: event["type"] == "progress",
+):
+ import multiprocessing as mp
+
+ from core.training.training import _build_training_worker_config
+ from core.training.worker import run_training_process
+
+ context = mp.get_context("spawn")
+ events, stops = context.Queue(), context.Queue()
+ process = context.Process(
+ target = run_training_process,
+ kwargs = {
+ "event_queue": events,
+ "stop_queue": stops,
+ "config": _build_training_worker_config({"training_type": "Full Finetuning", **config}),
+ },
+ )
+ process.start()
+ received = []
+ try:
+ while not received or received[-1]["type"] not in ("complete", "error"):
+ received.append(events.get(timeout = 600))
+ if stop is not None and when(received[-1]):
+ stops.put({"type": "stop", "save": stop})
+ stop = None
+ finally:
+ process.join(60)
+ return received
+
+
+def _of(events, kind):
+ return [e for e in events if e["type"] == kind]
+
+
+def client(studio_home):
+ from routes import systemone
+ from routes.settings import router as settings_router
+
+ app = FastAPI()
+ app.include_router(systemone.router, prefix = "/v1")
+ app.include_router(settings_router, prefix = "/api/settings")
+ app.dependency_overrides[get_current_subject] = lambda: "tester"
+ return TestClient(app)
+
+
+def _decide(client, model = "default"):
+ for _ in range(120):
+ response = client.post(
+ "/v1/systemone",
+ json = {"model": model, "state": "the server is down again", "questions": QUESTIONS},
+ )
+ if response.status_code != 503:
+ return response
+ time.sleep(0.5)
+ return response
+
+
+@needs_worker
+def test_fine_tune_is_calibrated_saved_and_served(base, studio_home, client):
+ rows = [_row(i) for i in range(200)]
+ rows += [
+ {"state": "slow login", "questions": "not json", "gold": "{}"},
+ {"state": "slow login", "questions": json.dumps(QUESTIONS), "gold": json.dumps({})},
+ {
+ "state": "slow login",
+ "questions": json.dumps({"q": {"type": "maybe", "instructions": "?"}}),
+ "gold": json.dumps({"q": "yes"}),
+ },
+ ]
+ events = _train(_config(base, _dataset(studio_home, rows)))
+
+ assert not _of(events, "error"), _of(events, "error")
+ progress = [e for e in _of(events, "progress") if e["loss"] is not None]
+ assert [e["step"] for e in progress] == [1, 2, 3]
+ assert all(e["total_steps"] == 3 and e["loss"] > 0 for e in progress)
+ assert any(e["eval_loss"] is not None for e in _of(events, "progress"))
+ assert _of(events, "warning")[0]["message"] == (
+ 'Skipped 5 of 605 decisions: row 202: "urgent" has no gold (and 2 more like it).'
+ )
+ complete = _of(events, "complete")[-1]
+ assert complete["status_message"].startswith("Held-out accuracy ")
+ output = complete["output_dir"]
+ assert _of(events, "output_dir")[0]["output_dir"] == output
+
+ from utils.paths import outputs_root
+
+ folder = outputs_root() / output.rsplit("/", 1)[-1]
+ assert str(folder) == output
+ cfg = json.loads((folder / "rl_agent_config.json").read_text(encoding = "utf-8"))
+ assert cfg["fine_tuned"] is True
+ assert "temperature_by_options" not in cfg
+ assert cfg["max_len"] == 1024 and cfg["head_max_len"] == 256
+ assert all(0.5 <= t <= 5.0 for t in cfg["temperature"])
+ assert cfg["temperature"] != [1.2, 1.1, 1.3]
+ assert cfg["training"]["heldout_decisions"] == 60
+ assert cfg["training"]["objective"] == "soft_cross_entropy"
+ assert cfg["training"]["steps"] == 3
+ with safe_open(str(folder / "model.safetensors"), "pt") as weights:
+ assert {weights.get_tensor(k).dtype for k in weights.keys()} == {torch.float16}
+
+ name = catalog.FINE_TUNE_PREFIX + folder.name
+ settings = client.get("/api/settings/systemone").json()
+ assert {"name": name, "kind": "fine_tune", "label": folder.name}.items() <= next(
+ m for m in settings["models"] if m["name"] == name
+ ).items()
+ response = client.put("/api/settings/systemone", json = {"enabled": True, "model": name})
+ assert response.status_code == 200, response.text
+ assert response.json()["model"] == name
+ plan = client.get("/api/settings/systemone/resolve").json()
+ assert plan["cached"] is True and plan["repo"] is None
+
+ response = _decide(client)
+ assert response.status_code == 200, response.text
+ body = response.json()
+ assert body["model"] == name
+ assert set(body["answers"]) == set(QUESTIONS)
+ assert body["answers"]["team"]["choice"] in ("outage", "billing")
+ assert _decide(client, name).json()["model"] == name
+
+
+@needs_worker
+def test_lora_run_merges_into_the_served_layout(base, studio_home, client, monkeypatch):
+ from safetensors.torch import load_file
+
+ # The spawned worker inherits sys.path and imports this wandb, whose init fails like a bad key.
+ offline = studio_home / "offline" / "wandb"
+ offline.mkdir(parents = True)
+ (offline / "__init__.py").write_text(
+ 'def init(**kwargs):\n raise RuntimeError("cannot reach W&B")\n', encoding = "utf-8"
+ )
+ monkeypatch.syspath_prepend(str(offline.parent))
+ rows = [_row(i) for i in range(120)]
+ events = _train(
+ _config(
+ base,
+ _dataset(studio_home, rows),
+ training_type = "LoRA/QLoRA",
+ lora_r = 4,
+ lora_alpha = 4,
+ enable_wandb = True,
+ )
+ )
+
+ assert not _of(events, "error"), _of(events, "error")
+ assert [e["message"] for e in _of(events, "warning")] == [
+ "Weights & Biases logging is off: cannot reach W&B"
+ ]
+ checkpoint = catalog.fine_tune(
+ catalog.FINE_TUNE_PREFIX + _of(events, "complete")[-1]["output_dir"].rsplit("/", 1)[-1]
+ )
+ folder = Path(checkpoint.source)
+ cfg = json.loads((folder / "rl_agent_config.json").read_text(encoding = "utf-8"))
+ assert cfg["training"]["method"] == "lora"
+ tuned = load_file(str(folder / "model.safetensors"))
+ original = load_file(str(base / "model.safetensors"))
+ assert tuned.keys() == original.keys()
+ assert {t.dtype for t in tuned.values()} == {torch.float16}
+ assert not torch.equal(
+ tuned["encoder.layers.0.attn.Wqkv.weight"], original["encoder.layers.0.attn.Wqkv.weight"]
+ )
+ assert torch.equal(
+ tuned["encoder.embeddings.tok_embeddings.weight"],
+ original["encoder.embeddings.tok_embeddings.weight"],
+ )
+
+ name = catalog.FINE_TUNE_PREFIX + folder.name
+ response = client.put("/api/settings/systemone", json = {"enabled": True, "model": name})
+ assert response.status_code == 200, response.text
+ response = _decide(client)
+ assert response.status_code == 200, response.text
+ assert response.json()["model"] == name
+
+
+@needs_worker
+ importlib.util.find_spec("tensorboard") is None
+ and importlib.util.find_spec("tensorboardX") is None,
+ reason = "needs tensorboard",
+)
+def test_tensorboard_logs_a_decision_run(base, studio_home):
+ from utils.paths import tensorboard_root
+
+ rows = [_row(i) for i in range(60)]
+ events = _train(
+ _config(
+ base,
+ _dataset(studio_home, rows),
+ max_steps = 2,
+ enable_tensorboard = True,
+ tensorboard_dir = "decision-tb",
+ )
+ )
+
+ assert not _of(events, "error"), _of(events, "error")
+ assert list((tensorboard_root() / "decision-tb").rglob("events.out.tfevents.*"))
+
+
+@needs_worker
+def test_an_unusable_eval_file_falls_back_to_the_hold_out(base, studio_home):
+ held = studio_home / "held"
+ held.mkdir()
+ rows = [_row(i) for i in range(120)]
+ events = _train(
+ _config(
+ base,
+ _dataset(studio_home, rows),
+ eval_steps = 0.5,
+ local_eval_datasets = [_dataset(held, [{"state": "slow"}] * 4)],
+ )
+ )
+
+ assert not _of(events, "error"), _of(events, "error")
+ assert "Holding out 36 decisions to calibrate confidence..." in [
+ e["message"] for e in _of(events, "status")
+ ]
+ folder = Path(_of(events, "complete")[-1]["output_dir"])
+ cfg = json.loads((folder / "rl_agent_config.json").read_text(encoding = "utf-8"))
+ assert cfg["training"]["heldout_decisions"] == 36
+
+
+@needs_worker
+def test_all_invalid_rows_are_an_error_and_save_nothing(base, studio_home):
+ from utils.paths import outputs_root
+
+ rows = [{"state": "slow", "questions": json.dumps(QUESTIONS)}] * 4
+ events = _train(_config(base, _dataset(studio_home, rows)))
+
+ assert "No usable decisions" in _of(events, "error")[0]["error"]
+ assert not _of(events, "complete")
+ assert not outputs_root().exists() or not any(outputs_root().iterdir())
+
+
+@needs_worker
[email protected]("training_type", ["Full Finetuning", "LoRA/QLoRA"])
+def test_stop_with_save_leaves_a_servable_checkpoint(base, studio_home, training_type):
+ rows = [_row(i) for i in range(120)]
+ events = _train(
+ _config(
+ base,
+ _dataset(studio_home, rows),
+ max_steps = 0,
+ num_epochs = 3,
+ training_type = training_type,
+ ),
+ True,
+ )
+
+ complete = _of(events, "complete")[-1]
+ last = _of(events, "progress")[-1]
+ assert last["step"] < last["total_steps"]
+ checkpoint = catalog.fine_tune(
+ catalog.FINE_TUNE_PREFIX + complete["output_dir"].rsplit("/", 1)[-1]
+ )
+ assert checkpoint is not None and laya_runtime.is_cached(checkpoint)
+ folder = Path(checkpoint.source)
+ with (
+ safe_open(str(folder / "model.safetensors"), "pt") as tuned,
+ safe_open(str(base / "model.safetensors"), "pt") as original,
+ ):
+ assert set(tuned.keys()) == set(original.keys())
+
+
+@needs_worker
+def test_cancel_leaves_no_output_folder(base, studio_home):
+ from utils.paths import outputs_root
+
+ rows = [_row(i) for i in range(120)]
+ events = _train(_config(base, _dataset(studio_home, rows), max_steps = 0, num_epochs = 3), False)
+
+ complete = _of(events, "complete")[-1]
+ assert complete["output_dir"] is None
+ assert complete["status_message"] == "Training cancelled"
+ assert _of(events, "output_dir")
+ assert not outputs_root().exists() or not any(outputs_root().iterdir())
+
+
+@needs_worker
+def test_stop_while_preparing_decisions_ends_the_run(base, studio_home):
+ from utils.paths import outputs_root
+
+ # Seconds of preparation; the bad row comes last, so a skip warning means it ran to the end.
+ rows = [_row(i) for i in range(6000)] + [{"state": "slow", "questions": QUESTIONS, "gold": {}}]
+ events = _train(
+ _config(base, _dataset(studio_home, rows)),
+ False,
+ lambda event: event.get("message") == "Preparing decisions...",
+ )
+
+ assert _of(events, "complete")[-1]["status_message"] == "Training cancelled"
+ assert not _of(events, "warning") and not _of(events, "output_dir")
+ assert not outputs_root().exists() or not any(outputs_root().iterdir())
+
+
+def _fake_output(
+ root,
+ name,
+ complete = True,
+):
+ folder = root / name
+ for sub in ("encoder", "tokenizer"):
+ (folder / sub).mkdir(parents = True)
+ (folder / "model.safetensors").write_bytes(b"x")
+ if complete:
+ (folder / "rl_agent_config.json").write_text("{}", encoding = "utf-8")
+ return folder
+
+
+def test_settings_accept_only_complete_owner_fine_tunes(studio_home, client, tmp_path):
+ from utils.paths import outputs_root
+
+ root = outputs_root()
+ _fake_output(root, "laya_done_1")
+ _fake_output(root, "laya_half_2", complete = False)
+ outside = _fake_output(tmp_path, "elsewhere")
+ (root / "linked").symlink_to(outside, target_is_directory = True)
+
+ names = [m["name"] for m in client.get("/api/settings/systemone").json()["models"]]
+ assert "laya-ft:laya_done_1" in names
+ assert not any(n in names for n in ("laya-ft:laya_half_2", "laya-ft:linked"))
+ for bad in (
+ "laya-ft:laya_half_2",
+ "laya-ft:linked",
+ "laya-ft:../elsewhere",
+ f"laya-ft:{outside}",
+ "laya-ft:",
+ ):
+ response = client.put("/api/settings/systemone", json = {"model": bad})
+ assert response.status_code == 400, bad
+
+ response = client.put("/api/settings/systemone", json = {"model": "laya-ft:laya_done_1"})
+ assert response.status_code == 200
+ assert client.get("/api/settings/systemone").json()["model"] == "laya-ft:laya_done_1"
+ shutil.rmtree(root / "laya_done_1")
+ assert client.get("/api/settings/systemone").json()["model"] == "laya-multilingual"
+
+
+def test_llm_output_scans_skip_decision_outputs(studio_home):
+ from utils.models.checkpoints import scan_checkpoints
+ from utils.models.model_config import scan_trained_models
+ from utils.paths import outputs_root
+
+ root = outputs_root()
+ _fake_output(root, "laya_done_1")
+ merged = root / "llama_merged_1"
+ merged.mkdir()
+ (merged / "config.json").write_text("{}", encoding = "utf-8")
+ (merged / "model.safetensors").write_bytes(b"x")
+
+ assert [name for name, _, _ in scan_trained_models(str(root))] == ["llama_merged_1"]
+ assert [name for name, _, _ in scan_checkpoints(str(root))] == ["llama_merged_1"]
+
+
+def test_model_config_classifies_a_local_laya_folder(base):
+ import asyncio
+
+ from routes.models import get_model_config
+
+ result = asyncio.run(
+ get_model_config(model_name = str(base), hf_token = None, current_subject = "tester")
+ )
+ assert result.model_type == "decision" and result.is_decision is True
+ assert float(result.config["training"]["learning_rate"]) == 8e-4
+ assert result.config["training"]["optim"] == "adamw_torch"
+ assert result.config["lora"]["lora_r"] == 64
+ assert result.decision_checkpoints is None
+
+
+def test_start_preflight_accepts_a_local_laya_folder(base):
+ from models.training import TrainingStartRequest
+ from routes.training import _reject_untrainable_model_request
+
+ request = TrainingStartRequest(
+ model_name = str(base),
+ training_type = "Full Finetuning",
+ is_decision = True,
+ hf_dataset = "org/decisions",
+ format_type = "auto",
+ )
+ assert _reject_untrainable_model_request(request).model_name == str(base.resolve())
+
+
+def test_arrow_merged_criteria_are_not_trained_as_options(tmp_path):
+ pa = pytest.importorskip("pyarrow")
+ import pyarrow.parquet as pq
+
+ from core.training.decision_trainer import STRUCT_COLUMNS_WARNING, _read_local_rows
+ from utils.datasets.cache_safe import load_dataset_cache_safe
+
+ rows = [
+ {
+ "state": "refund my card",
+ "questions": {"q": {"type": "choice", "instructions": "Team?", "criteria": crit}},
+ "gold": {"q": {"label": label, "probabilities": probs}},
+ }
+ for crit, label, probs in (
+ ({"billing": "charges", "outage": ""}, "billing", {"billing": 0.9, "outage": 0.1}),
+ ({"login": "accounts", "slow": "speed"}, "slow", {"login": 0.2, "slow": 0.8}),
+ )
+ ]
+ path = tmp_path / "decisions.parquet"
+ pq.write_table(pa.Table.from_pylist(rows), str(path))
+
+ warnings = []
+ loaded = _read_local_rows([str(path)], load_dataset_cache_safe, warnings.append)
+ assert [row["questions"]["q"]["criteria"] for row in loaded] == [
+ {"billing": "charges", "outage": ""},
+ {"login": "accounts", "slow": "speed"},
+ ]
+ assert loaded[1]["gold"]["q"]["probabilities"] == {"login": 0.2, "slow": 0.8}
+ assert warnings == [STRUCT_COLUMNS_WARNING]
+
+ strings = tmp_path / "strings.parquet"
+ pq.write_table(
+ pa.Table.from_pylist(
+ [{key: json.dumps(value) for key, value in row.items()} for row in rows]
+ ),
+ str(strings),
+ )
+ warnings.clear()
+ _read_local_rows([str(strings)], load_dataset_cache_safe, warnings.append)
+ assert not warnings
+
+
+def _load(should_stop = lambda: False, **config):
+ from core.training.decision_trainer import _load_rows
+
+ warnings = []
+ rows, eval_rows = _load_rows(
+ {"random_seed": 3407, "eval_steps": 0, **config},
+ should_stop,
+ lambda message: None,
+ warnings.append,
+ )
+ return rows, eval_rows, warnings
+
+
+def test_local_files_are_read_before_a_hub_dataset(tmp_path):
+ rows, _, _ = _load(
+ local_datasets = [_dataset(tmp_path, [_row(0)])], hf_dataset = "nobody/not-a-dataset"
+ )
+ assert rows == [_row(0)]
+
+
+def test_the_train_split_is_never_the_held_out_set(tmp_path):
+ hub = tmp_path / "decisions"
+ hub.mkdir()
+ for split, count in (("train", 30), ("test", 10)):
+ (hub / f"{split}.jsonl").write_text(
+ "\n".join(json.dumps(_row(i)) for i in range(count)), encoding = "utf-8"
+ )
+
+ rows, eval_rows, warnings = _load(
+ hf_dataset = str(hub), train_split = "train", eval_split = "train", eval_steps = 0.1
+ )
+ assert len(rows) == 30 and eval_rows is None
+ assert warnings == [
+ "The evaluation split is the training split, so part of it is held out "
+ "of training for evaluation instead."
+ ]
+
+ rows, eval_rows, warnings = _load(
+ hf_dataset = str(hub), train_split = "train", eval_split = "test", eval_steps = 0.1
+ )
+ assert len(rows) == 30 and len(eval_rows) == 10 and not warnings
+
+
+def test_eval_rows_are_sampled_before_they_are_prepared(tmp_path):
+ from core.training.decision_trainer import EVAL_MAX
+
+ held = tmp_path / "held"
+ held.mkdir()
+ _, eval_rows, _ = _load(
+ local_datasets = [_dataset(tmp_path, [_row(0)])],
+ local_eval_datasets = [_dataset(held, [_row(i) for i in range(EVAL_MAX + 500)])],
+ eval_steps = 0.1,
+ )
+ assert len(eval_rows) == EVAL_MAX
+
+
+def test_csv_cells_are_read_as_text(tmp_path):
+ import csv
+
+ path = tmp_path / "decisions.csv"
+ with path.open("w", newline = "", encoding = "utf-8") as file:
+ writer = csv.writer(file)
+ writer.writerow(["state", "questions", "gold"])
+ for state in ("NA", "00501", "null"):
+ writer.writerow([state, _row(0)["questions"], _row(0)["gold"]])
+
+ rows, _, _ = _load(local_datasets = [str(path)])
+ assert [row["state"] for row in rows] == ["NA", "00501", "null"]
+
+
+def test_a_stop_during_the_s3_download_cancels_the_run(monkeypatch):
+ from core.training import s3_dataset
+ from core.training.decision_trainer import _Stopped
+
+ def download(s3_config, cancel_callback):
+ assert cancel_callback()
+ raise s3_dataset.S3DownloadCancelled("S3 dataset download cancelled")
+
+ monkeypatch.setattr(s3_dataset, "prepare_s3_dataset_download", download)
+ with pytest.raises(_Stopped, match = "Training cancelled"):
+ _load(lambda: True, s3_config = {"bucket": "b"})
+
+
+def test_other_accounts_reach_only_the_configured_fine_tune(studio_home, client):
+ from utils.account_context import AccountContext, bind_account, reset_account
+ from utils.paths import outputs_root
+
+ root = outputs_root()
+ _fake_output(root, "laya_done_1")
+ _fake_output(root, "laya_done_2")
+ assert (
+ client.put("/api/settings/systemone", json = {"model": "laya-ft:laya_done_1"}).status_code
+ == 200
+ )
+
+ token = bind_account(AccountContext("b" * 32, "bob"))
+ try:
+ assert catalog.resolve("laya-ft:laya_done_1") is not None
+ assert catalog.resolve("laya-ft:laya_done_2") is None
+ finally:
+ reset_account(token)
+ assert catalog.resolve("laya-ft:laya_done_2") is not None
+
+
+def test_only_the_owner_can_start_decision_training():
+ from fastapi import HTTPException
+
+ from models.training import TrainingStartRequest
+ from routes.training import _validate_decision_request
+ from utils.account_context import AccountContext, bind_account, reset_account
+
+ request = TrainingStartRequest(
+ model_name = catalog.LAYA_REPO,
+ model_subfolder = "multilingual",
+ training_type = "Full Finetuning",
+ is_decision = True,
+ hf_dataset = "org/decisions",
+ format_type = "auto",
+ )
+ _validate_decision_request(request)
+ token = bind_account(AccountContext("b" * 32, "bob"))
+ try:
+ with pytest.raises(HTTPException) as refused:
+ _validate_decision_request(request)
+ finally:
+ reset_account(token)
+ assert refused.value.status_code == 403
+
+
+def test_eval_files_that_are_training_files_are_never_the_held_out_set(tmp_path):
+ train = _dataset(tmp_path, [_row(i) for i in range(30)])
+ for eval_files in ([train], [str(tmp_path)], [str(tmp_path / "." / "decisions.jsonl")]):
+ rows, eval_rows, warnings = _load(
+ local_datasets = [train], local_eval_datasets = eval_files, eval_steps = 0.1
+ )
+ assert len(rows) == 30 and eval_rows is None, eval_files
+ assert warnings == [
+ "The evaluation files include training files, so part of the training data is "
+ "held out for evaluation instead."
+ ]
+
+
+@needs_worker
+def test_cancel_during_calibration_saves_nothing(base, studio_home):
+ from utils.paths import outputs_root
+
+ rows = [_row(i) for i in range(120)]
+ events = _train(
+ _config(base, _dataset(studio_home, rows)),
+ False,
+ when = lambda event: event.get("message") == "Calibrating confidence...",
+ )
+
+ complete = _of(events, "complete")[-1]
+ assert (complete["output_dir"], complete["status_message"]) == (None, "Training cancelled")
+ assert not outputs_root().exists() or not any(outputs_root().iterdir())
+
+
+def test_held_out_decisions_count_every_clef_question():
+ from core.training.decision_trainer import _decision_count
+
+ laya = [{"row": 0}, {"row": 1}]
+ clef = [{"row": 0, "labels": [0, 1, 2]}, {"row": 1, "labels": [1]}]
+ assert (_decision_count(laya), _decision_count(clef)) == (2, 4)
diff --git a/studio/backend/tests/test_decision_training_route.py b/studio/backend/tests/test_decision_training_route.py
new file mode 100644
index 00000000000..7bf0cdefd3b
--- /dev/null
+++ b/studio/backend/tests/test_decision_training_route.py
@@ -0,0 +1,569 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import asyncio
+import importlib.util
+import os
+import sys
+import threading
+from pathlib import Path
+from types import SimpleNamespace
+from unittest.mock import patch
+
+import pytest
+from fastapi import HTTPException
+
+from core.systemone.catalog import LAYA_REPO
+from models.training import TrainingStartRequest
+
+_BACKEND_ROOT = Path(__file__).resolve().parent.parent
+
+
[email protected](autouse = True)
+def hub_cache(monkeypatch, tmp_path):
+ from hub.utils import hf_cache_state
+ from utils import hf_cache_settings
+
+ root = tmp_path / "hub"
+ root.mkdir()
+ monkeypatch.setattr(hf_cache_settings, "active_hf_hub_cache", lambda: str(root))
+ monkeypatch.setattr(hf_cache_state, "hf_cache_roots", lambda **kwargs: [root])
+ monkeypatch.delenv("HF_HUB_OFFLINE", raising = False)
+ monkeypatch.delenv("TRANSFORMERS_OFFLINE", raising = False)
+ return root
+
+
+def route():
+ spec = importlib.util.spec_from_file_location(
+ "decision_training_route", _BACKEND_ROOT / "routes" / "training.py"
+ )
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+ module._hub_unreachable = lambda: False
+ return module
+
+
+def _request(**overrides) -> TrainingStartRequest:
+ return TrainingStartRequest(
+ **{
+ "model_name": LAYA_REPO,
+ "training_type": "LoRA/QLoRA",
+ "format_type": "auto",
+ "hf_dataset": "org/decisions",
+ "is_decision": True,
+ **overrides,
+ }
+ )
+
+
+def _laya_folder(folder: Path) -> Path:
+ for name in ("encoder", "tokenizer"):
+ (folder / name).mkdir(parents = True)
+ for name in ("rl_agent_config.json", "model.safetensors"):
+ (folder / name).write_text("{}", encoding = "utf-8")
+ return folder
+
+
+def _cache_laya(hub_cache: Path, subfolder = None) -> Path:
+ repo = hub_cache / "models--convaiinnovations--laya"
+ snapshot = repo / "snapshots" / "rev"
+ _laya_folder(snapshot / subfolder if subfolder else snapshot)
+ (repo / "refs").mkdir()
+ (repo / "refs" / "main").write_text("rev", encoding = "utf-8")
+ return repo
+
+
+async def _inline_to_thread(function, *args, **kwargs):
+ return function(*args, **kwargs)
+
+
+def _started_config(route, request) -> dict:
+ captured = {}
+ backend = SimpleNamespace(
+ current_job_id = None,
+ is_training_active = lambda: False,
+ start_training = lambda **kwargs: captured.update(kwargs) or True,
+ )
+ with (
+ patch.object(route, "get_training_backend", return_value = backend),
+ patch.object(route, "_preflight_hf_dataset_request", return_value = None),
+ patch.object(route.asyncio, "to_thread", _inline_to_thread),
+ ):
+ response = asyncio.run(route.start_training(request, current_subject = "test-user"))
+ assert response.status == "queued", response
+ return captured
+
+
+ "subfolder",
+ [
+ "*",
+ "**",
+ "[mt]*",
+ "?ultilingual",
+ " multilingual",
+ "multilingual ",
+ "encoder",
+ "~",
+ "C:",
+ "D:evil",
+ "multi\x00lingual",
+ pytest.param("m" * 5000, id = "5000 characters"),
+ "",
+ ".",
+ "..",
+ "../other",
+ "multilingual/../..",
+ "..\\other",
+ ],
+)
+def test_subfolder_must_be_one_of_the_laya_checkpoints(route, subfolder):
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(_request(model_subfolder = subfolder))
+
+ assert refused.value.status_code == 400
+ assert "Invalid checkpoint subfolder" in refused.value.detail
+
+
[email protected]("subfolder", [None, "multilingual", "typed-decisions"])
+def test_catalog_checkpoints_are_accepted(route, subfolder):
+ route._validate_decision_request(_request(model_subfolder = subfolder))
+
+
+def test_other_sources_take_a_plain_folder_name_only(route, tmp_path):
+ route._validate_decision_request(_request(model_name = str(tmp_path), model_subfolder = "v2"))
+ with pytest.raises(HTTPException):
+ route._validate_decision_request(_request(model_name = str(tmp_path), model_subfolder = "v*"))
+
+
+ ("request_overrides", "expected"),
+ [
+ ({"training_type": "Continued Pretraining"}, "continued pretraining is not available"),
+ ({"resume_from_checkpoint": "outputs/run"}, "cannot be resumed"),
+ ({"dataset_streaming": True, "max_steps": 10}, "dataset_streaming"),
+ ({"load_in_4bit": True}, "QLoRA is not available"),
+ ({"use_dora": True}, "DoRA and LoftQ are not available"),
+ ({"use_loftq": True}, "DoRA and LoftQ are not available"),
+ ],
+)
+def test_start_refuses_what_the_recipe_cannot_run(route, request_overrides, expected):
+ refusing = SimpleNamespace(
+ current_job_id = None,
+ is_training_active = lambda: False,
+ start_training = lambda **kwargs: pytest.fail("backend should not start"),
+ )
+ with (
+ patch.object(route, "get_training_backend", return_value = refusing),
+ patch.object(route.asyncio, "to_thread", _inline_to_thread),
+ pytest.raises(HTTPException) as refused,
+ ):
+ asyncio.run(
+ route.start_training(_request(**request_overrides), current_subject = "test-user")
+ )
+
+ assert refused.value.status_code == 400
+ assert expected in refused.value.detail
+
+
+ ("request_overrides", "requested"),
+ [
+ ({}, True),
+ ({"training_type": "Full Finetuning", "load_in_4bit": True}, True),
+ ({"load_in_4bit": False}, False),
+ ],
+)
+def test_decision_models_train_in_16_bit(route, request_overrides, requested):
+ request = _request(**request_overrides)
+ assert request.load_in_4bit is requested
+
+ route._validate_decision_request(request)
+
+ assert request.load_in_4bit is False
+
+
+def test_a_managed_account_is_told_decision_training_is_owner_only(route, monkeypatch):
+ from utils import account_context
+
+ monkeypatch.setattr(account_context, "is_owner_context", lambda: False)
+ monkeypatch.setattr(route, "managed_account", lambda: True)
+ with pytest.raises(HTTPException) as refused:
+ asyncio.run(route.start_training(_request(), current_subject = "managed-user"))
+
+ assert refused.value.status_code == 403
+ assert "Only the Studio owner" in refused.value.detail
+
+
+def test_python_older_than_3_10_cannot_train_decision_models(route, monkeypatch):
+ request = _request()
+ with monkeypatch.context() as patched:
+ patched.setattr(route.sys, "version_info", (3, 9, 18))
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(request)
+
+ assert refused.value.status_code == 400
+ assert "Python 3.10" in refused.value.detail
+
+
+ ("training_type", "learning_rate"),
+ [("LoRA/QLoRA", 8e-4), ("Full Finetuning", 2.5e-5)],
+)
+def test_api_runs_without_hyperparameters_get_the_laya_recipe(
+ route, device, tmp_path, training_type, learning_rate
+):
+ base = _laya_folder(tmp_path / "laya")
+ config = _started_config(route, _request(model_name = str(base), training_type = training_type))
+
+ assert float(config["learning_rate"]) == learning_rate
+ assert config["load_in_4bit"] is False
+ assert (config["num_epochs"], config["max_steps"], config["warmup_steps"]) == (4, 0, 0)
+ assert (config["batch_size"], config["gradient_accumulation_steps"]) == (8, 8)
+ assert (config["optim"], config["lr_scheduler_type"]) == ("adamw_torch", "cosine")
+ assert config["weight_decay"] == 0.01
+ assert config["gradient_checkpointing"] == "unsloth"
+ assert (config["lora_r"], config["lora_alpha"], config["lora_dropout"]) == (64, 64, 0.0)
+
+
+def test_api_runs_keep_the_hyperparameters_they_set(route, device, tmp_path):
+ base = _laya_folder(tmp_path / "laya")
+ config = _started_config(
+ route,
+ _request(
+ model_name = str(base),
+ training_type = "Full Finetuning",
+ learning_rate = "1e-5",
+ batch_size = 2,
+ optim = "adamw_8bit",
+ lora_r = 16,
+ ),
+ )
+
+ assert float(config["learning_rate"]) == 1e-5
+ assert (config["batch_size"], config["optim"], config["lora_r"]) == (2, "adamw_8bit", 16)
+ assert config["gradient_accumulation_steps"] == 8
+
+
[email protected]("subfolder", [None, "multilingual"])
[email protected]("hub_state", ["offline", "unreachable"])
+def test_a_cached_laya_checkpoint_starts_without_the_hub(
+ route, hub_cache, monkeypatch, subfolder, hub_state
+):
+ # Only the requested checkpoint is cached, as the Decision API leaves it.
+ repo = _cache_laya(hub_cache, subfolder)
+ if hub_state == "offline":
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ else:
+ route._hub_unreachable = lambda: True
+ request = _request(
+ model_subfolder = subfolder, model_known_cached = True, model_local_path = str(repo)
+ )
+
+ result = route._reject_untrainable_model_request(request)
+
+ assert result.model_name == LAYA_REPO
+ assert result.cached_model_pin is None
+
+
[email protected](("hub_state", "status"), [("offline", 409), ("unreachable", 503)])
+def test_an_uncached_laya_checkpoint_still_needs_the_hub(
+ route, hub_cache, monkeypatch, hub_state, status
+):
+ _cache_laya(hub_cache, "multilingual")
+ if hub_state == "offline":
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ else:
+ route._hub_unreachable = lambda: True
+
+ with pytest.raises(HTTPException) as refused:
+ route._reject_untrainable_model_request(_request(model_subfolder = "typed-decisions"))
+
+ assert refused.value.status_code == status
+
+
+def test_a_cached_decision_run_reports_no_download(hub_cache):
+ from core.training.training import _apply_cache_pins, _build_training_worker_config
+
+ repo = _cache_laya(hub_cache, "multilingual")
+ config = _build_training_worker_config(
+ {
+ "model_name": LAYA_REPO,
+ "model_subfolder": "multilingual",
+ "is_decision": True,
+ "model_known_cached": True,
+ "model_local_path": str(repo),
+ }
+ )
+
+ _apply_cache_pins(config)
+
+ assert config["cache_pin_warnings"] == []
+ assert config["model_snapshot_path"] is None
+
+
+ ("files", "subfolder", "accepted"),
+ [
+ (["config.json", "model.safetensors"], None, False),
+ (["rl_agent_config.json", "model.safetensors", "encoder/config.json"], None, True),
+ (["v2/rl_agent_config.json", "v2/model.safetensors"], "v2", True),
+ (["v2/rl_agent_config.json", "v2/model.safetensors"], None, False),
+ (["rl_agent_config.json", "model.safetensors"], "v2", False),
+ ],
+)
+def test_a_hub_repo_must_be_a_decision_model(route, files, subfolder, accepted):
+ from utils.models import model_config
+
+ info = SimpleNamespace(siblings = [SimpleNamespace(rfilename = name) for name in files])
+ request = _request(model_name = "org/model", model_subfolder = subfolder)
+ with (
+ patch.object(route, "_remote_untrainable_model_format", return_value = None),
+ patch.object(model_config, "_hub_model_info", return_value = info),
+ ):
+ if accepted:
+ route._reject_untrainable_model_request(request)
+ return
+ with pytest.raises(HTTPException) as refused:
+ route._reject_untrainable_model_request(request)
+
+ assert refused.value.status_code == 400
+ assert refused.value.detail["code"] == "training_remote_model_not_decision"
+
+
[email protected]("root_format", ["adapter", "gguf"])
+def test_a_hub_subfolder_checkpoint_is_not_judged_by_the_repo_root(route, root_format):
+ from utils.models import model_config
+
+ files = ["adapter_config.json", "v2/rl_agent_config.json", "v2/model.safetensors"]
+ info = SimpleNamespace(siblings = [SimpleNamespace(rfilename = name) for name in files])
+ with (
+ patch.object(route, "_remote_untrainable_model_format", return_value = root_format),
+ patch.object(model_config, "_hub_model_info", return_value = info),
+ ):
+ route._reject_untrainable_model_request(
+ _request(model_name = "org/model", model_subfolder = "v2")
+ )
+
+
+def test_a_local_checkpoint_is_checked_at_its_subfolder(route, tmp_path):
+ root = tmp_path / "laya"
+ _laya_folder(root / "multilingual")
+ request = _request(model_name = str(root), model_subfolder = "multilingual")
+
+ assert route._reject_untrainable_model_request(request).model_name == str(root.resolve())
+
+ with pytest.raises(HTTPException) as refused:
+ route._reject_untrainable_model_request(_request(model_name = str(root)))
+ assert refused.value.detail["code"] == "training_local_model_not_decision"
+
+
+def test_a_local_llm_is_not_trained_as_a_decision_model(route, tmp_path):
+ llm = tmp_path / "llm"
+ llm.mkdir()
+ (llm / "config.json").write_text("{}", encoding = "utf-8")
+ (llm / "model.safetensors").write_bytes(b"x")
+
+ with pytest.raises(HTTPException) as refused:
+ route._reject_untrainable_model_request(_request(model_name = str(llm)))
+
+ assert refused.value.status_code == 400
+ assert refused.value.detail["code"] == "training_local_model_not_decision"
+
+
+def test_a_hub_checkpoint_downloads_under_the_stall_watchdog(monkeypatch, tmp_path):
+ from core.systemone import laya_runtime
+ from core.training import worker
+ from utils import hf_xet_fallback
+
+ events, watchdogs, downloads = [], [], []
+
+ def start_watchdog(**kwargs):
+ watchdogs.append({**kwargs, "stop": threading.Event()})
+ return watchdogs[-1]["stop"]
+
+ def checkpoint_dir(checkpoint, **kwargs):
+ downloads.append(
+ (
+ checkpoint.source,
+ checkpoint.subfolder,
+ os.environ.get("HF_TOKEN"),
+ watchdogs[-1]["stop"].is_set(),
+ )
+ )
+ watchdogs[-1]["on_stall"]("No download progress for 30s")
+ return tmp_path
+
+ monkeypatch.setattr(hf_xet_fallback, "start_watchdog", start_watchdog)
+ monkeypatch.setattr(laya_runtime, "_checkpoint_dir", checkpoint_dir)
+ # Set first so monkeypatch removes what the download leaves behind.
+ monkeypatch.setenv("HF_TOKEN", "")
+ queue = SimpleNamespace(put = events.append)
+
+ worker._download_decision_checkpoint(
+ queue,
+ {"model_name": LAYA_REPO, "model_subfolder": "multilingual", "hf_token": "hf_private"},
+ )
+
+ assert [w["repo_ids"] for w in watchdogs] == [[LAYA_REPO]]
+ assert downloads == [(LAYA_REPO, "multilingual", "hf_private", False)]
+ assert [e["type"] for e in events] == [
+ "status",
+ "model_load_started",
+ "stall",
+ "model_load_completed",
+ ]
+ assert watchdogs[0]["stop"].is_set()
+
+ events.clear()
+ worker._download_decision_checkpoint(queue, {"model_name": str(tmp_path)})
+ assert events == [] and len(downloads) == 1
+
+
[email protected](sys.platform == "darwin", reason = "Apple Silicon trains with MLX")
+def test_decision_worker_uses_one_gpu_and_no_llm_kernel_installs(monkeypatch, tmp_path):
+ import multiprocessing as mp
+
+ from core.training.training import _build_training_worker_config
+ from core.training.worker import run_training_process
+
+ # Offline, so an LLM-path flash-attn install reports itself instead of downloading.
+ monkeypatch.setenv("HF_HUB_OFFLINE", "1")
+ not_laya = tmp_path / "not-laya"
+ not_laya.mkdir()
+ config = _build_training_worker_config(
+ {
+ "model_name": str(not_laya),
+ "training_type": "LoRA/QLoRA",
+ "is_decision": True,
+ "max_seq_length": 32768,
+ }
+ )
+ config.update(resolved_gpu_ids = [0, 1], device_backend = "cuda")
+ context = mp.get_context("spawn")
+ events, stops = context.Queue(), context.Queue()
+ process = context.Process(
+ target = run_training_process,
+ kwargs = {"event_queue": events, "stop_queue": stops, "config": config},
+ )
+ process.start()
+ received = []
+ try:
+ while not received or received[-1]["type"] not in ("complete", "error"):
+ received.append(events.get(timeout = 300))
+ finally:
+ process.join(60)
+
+ statuses = [e["message"] for e in received if e["type"] == "status"]
+ assert [e["message"] for e in received if e["type"] == "warning"] == [
+ "Decision models train on one GPU; using GPU 0."
+ ]
+ assert "Importing Unsloth..." in statuses
+ assert not any("flash-attn" in status for status in statuses)
+ assert received[-1]["type"] == "error"
+
+
+def device(monkeypatch):
+ from utils.hardware import hardware
+
+ def use(kind):
+ value = {
+ "cuda": hardware.DeviceType.CUDA,
+ "cpu": hardware.DeviceType.CPU,
+ "xpu": hardware.DeviceType.XPU,
+ }[kind]
+ monkeypatch.setattr(hardware, "get_device", lambda: value)
+ monkeypatch.setattr(hardware, "DEVICE", value)
+
+ use("cuda")
+ return use
+
+
+def _clef_folder(folder: Path) -> Path:
+ folder.mkdir(parents = True)
+ for name in ("config.json", "joint_head.safetensors", "joint_head_config.json"):
+ (folder / name).write_text("{}", encoding = "utf-8")
+ return folder
+
+
+def test_api_clef_runs_get_the_clef_recipe_and_keep_qlora(route, device, tmp_path):
+ config = _started_config(route, _request(model_name = str(_clef_folder(tmp_path / "clef"))))
+
+ assert config["decision_layout"] == "clef"
+ assert config["load_in_4bit"] is True
+ assert float(config["learning_rate"]) == 2e-4
+ assert (config["batch_size"], config["gradient_accumulation_steps"]) == (4, 2)
+ assert (config["lora_r"], config["lora_alpha"]) == (16, 16)
+ assert config["max_seq_length"] == 4096
+
+ laya = _started_config(route, _request(model_name = str(_laya_folder(tmp_path / "laya"))))
+ assert (laya["decision_layout"], laya["load_in_4bit"]) == ("laya", False)
+
+
+def test_api_clef_full_finetuning_gets_the_full_finetuning_rate(route, device, tmp_path):
+ clef = str(_clef_folder(tmp_path / "clef"))
+ config = _started_config(route, _request(model_name = clef, training_type = "Full Finetuning"))
+
+ assert float(config["learning_rate"]) == 2.5e-5
+
+
+def test_a_caller_cannot_claim_a_layout_or_a_clef_subfolder(route, device, tmp_path):
+ clef = _clef_folder(tmp_path / "clef")
+ laya = _laya_folder(tmp_path / "laya")
+ claimed = _request(model_name = str(laya), decision_layout = "clef")
+ route._validate_decision_request(claimed)
+ assert claimed.decision_layout == "laya"
+
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(_request(model_name = str(clef), model_subfolder = "v2"))
+ assert "model_subfolder" in refused.value.detail
+
+
+def test_a_decision_run_is_planned_on_the_one_gpu_it_uses(route, device, tmp_path):
+ request = _request(model_name = str(_laya_folder(tmp_path / "laya")), gpu_ids = [2, 3])
+ route._validate_decision_request(request)
+ assert request.gpu_ids == [2]
+
+
+def test_a_local_clef_in_a_subfolder_is_detected_as_clef(route, device, tmp_path):
+ _clef_folder(tmp_path / "parent" / "clef")
+ request = _request(model_name = str(tmp_path / "parent"), model_subfolder = "clef")
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(request)
+ assert "Clef repos hold one checkpoint" in refused.value.detail
+
+
+def test_a_hub_clef_repo_is_a_decision_model(route, device):
+ from utils.models import model_config
+
+ files = [
+ "config.json",
+ "joint_head.safetensors",
+ "joint_head_config.json",
+ "model-00001-of-00004.safetensors",
+ ]
+ info = SimpleNamespace(siblings = [SimpleNamespace(rfilename = name) for name in files])
+ request = _request(model_name = "Cloudflare/clef-flash")
+ with (
+ patch.object(route, "_remote_untrainable_model_format", return_value = None),
+ patch.object(model_config, "_hub_model_info", return_value = info),
+ ):
+ route._validate_decision_request(request)
+ assert request.decision_layout == "clef"
+ route._reject_untrainable_model_request(request)
+ assert model_config.decision_layout("Cloudflare/clef-flash") == "clef"
+
+
[email protected]("kind", ["cpu", "xpu"])
+def test_clef_training_is_refused_without_an_nvidia_or_amd_gpu(route, device, tmp_path, kind):
+ from core.systemone.catalog import CLEF_NEEDS_GPU
+
+ device(kind)
+ with pytest.raises(HTTPException) as refused:
+ route._validate_decision_request(_request(model_name = str(_clef_folder(tmp_path / "c"))))
+ assert (refused.value.status_code, refused.value.detail) == (400, CLEF_NEEDS_GPU)
+ laya = _request(model_name = str(_laya_folder(tmp_path / "laya")))
+ route._validate_decision_request(laya)
+ assert laya.decision_layout == "laya"
diff --git a/studio/backend/tests/test_export_absolute_paths.py b/studio/backend/tests/test_export_absolute_paths.py
index a8e3ee74c79..99c5f737e53 100644
--- a/studio/backend/tests/test_export_absolute_paths.py
+++ b/studio/backend/tests/test_export_absolute_paths.py
@@ -185,6 +185,8 @@ def _install_lightweight_backend_stubs(monkeypatch):
utils_model_config._is_imatrix_path = lambda *args, **kwargs: False
utils_model_config._is_mtp_drafter = lambda *args, **kwargs: False
utils_model_config.is_audio_input_type = lambda *args, **kwargs: None
+ utils_model_config.is_decision_model = lambda *args, **kwargs: False
+ utils_model_config.decision_layout = lambda *args, **kwargs: None
monkeypatch.setitem(
sys.modules,
"utils.models.model_config",
diff --git a/studio/backend/tests/test_systemone.py b/studio/backend/tests/test_systemone.py
index c4fa39f4529..56a273a3a34 100644
--- a/studio/backend/tests/test_systemone.py
+++ b/studio/backend/tests/test_systemone.py
@@ -2070,3 +2070,13 @@ def test_mlx_overflow_in_a_later_chunk_reruns_the_whole_request_in_fp32(monkeypa
("float32", 2),
("float32", 1),
]
+
+
+def test_an_env_pinned_local_clef_folder_keeps_the_clef_layout(monkeypatch, tmp_path):
+ from core.systemone import catalog
+
+ for name in ("config.json", "joint_head.safetensors", "joint_head_config.json"):
+ (tmp_path / name).write_text("{}", encoding = "utf-8")
+ monkeypatch.setenv("UNSLOTH_SYSTEMONE_MODEL", str(tmp_path))
+ monkeypatch.delenv("UNSLOTH_SYSTEMONE_SUBFOLDER", raising = False)
+ assert catalog.default_checkpoint().layout == "clef"
diff --git a/studio/backend/tests/test_training_cached_start.py b/studio/backend/tests/test_training_cached_start.py
index a4ae0750527..18c4c413617 100644
--- a/studio/backend/tests/test_training_cached_start.py
+++ b/studio/backend/tests/test_training_cached_start.py
@@ -1326,6 +1326,7 @@ def test_streaming_rejects_cached_dataset_hints(cache_overrides):
({"is_embedding": True}, "Embedding model training"),
({"is_dataset_audio": True}, "Audio dataset training"),
({"use_loftq": True}, "LoftQ"),
+ ({"is_decision": True, "training_type": "Full Finetuning"}, "Decision model training"),
],
)
def test_mlx_start_rejects_unsupported_training_config(request_overrides, expected):
diff --git a/studio/backend/utils/models/model_config.py b/studio/backend/utils/models/model_config.py
index 62d9e3ae303..0e5329ffe16 100644
--- a/studio/backend/utils/models/model_config.py
+++ b/studio/backend/utils/models/model_config.py
@@ -3751,6 +3751,68 @@ def is_embedding_model(model_name: str, hf_token: Optional[str] = None) -> bool:
return is_emb
+_LAYA_MARKER = "rl_agent_config.json"
+# Cloudflare's Clef layout: a Qwen3.5 backbone plus the joint schema head.
+CLEF_MARKERS = ("config.json", "joint_head.safetensors", "joint_head_config.json")
+
+
+def _folder_decision_layout(folder: Path) -> Optional[str]:
+ if all((folder / name).is_file() for name in CLEF_MARKERS):
+ return "clef"
+ if all((folder / name).is_file() for name in (_LAYA_MARKER, "model.safetensors")) and all(
+ (folder / name).is_dir() for name in ("encoder", "tokenizer")
+ ):
+ return "laya"
+ return None
+
+
+def decision_layout(
+ model_name: str,
+ hf_token: Optional[str] = None,
+ local_files_only: bool = False,
+ subfolder: Optional[str] = None,
+) -> Optional[str]:
+ """ "laya", "clef" or None for a model that is not a decision model."""
+ if is_local_path(model_name):
+ folder = Path(normalize_path(model_name))
+ # The subfolder first, as on the Hub; an escaping one is refused later by request validation.
+ nested = None
+ if subfolder and not Path(subfolder).is_absolute() and ".." not in Path(subfolder).parts:
+ nested = _folder_decision_layout(folder / subfolder)
+ return nested or _folder_decision_layout(folder)
+ from utils.utils import hf_cache_snapshot_dir, hf_env_offline
+
+ prefix = f"{subfolder}/" if subfolder else ""
+ if not (local_files_only or hf_env_offline()):
+ try:
+ info = _hub_model_info(model_name, hf_token)
+ files = {getattr(sibling, "rfilename", None) for sibling in info.siblings or ()}
+ if all(prefix + name in files for name in CLEF_MARKERS):
+ return "clef"
+ return "laya" if prefix + _LAYA_MARKER in files else None
+ except Exception as e:
+ logger.warning(f"Could not determine if {model_name} is a decision model: {e}")
+ if not cache_reads_authorized(hf_token, repo_id = model_name):
+ return None
+ snapshot = hf_cache_snapshot_dir(model_name)
+ if snapshot is None:
+ return None
+ if all((snapshot / prefix / name).is_file() for name in CLEF_MARKERS):
+ return "clef"
+ # The Decision API caches only the checkpoint subfolder it serves.
+ laya = (snapshot / _LAYA_MARKER, *snapshot.glob(f"*/{_LAYA_MARKER}"))
+ return "laya" if any(path.is_file() for path in laya) else None
+
+
+def is_decision_model(
+ model_name: str,
+ hf_token: Optional[str] = None,
+ local_files_only: bool = False,
+ subfolder: Optional[str] = None,
+) -> bool:
+ return decision_layout(model_name, hf_token, local_files_only, subfolder) is not None
+
+
def _has_model_weight_files(model_dir: Path) -> bool:
"""Return True when a directory contains loadable model weights."""
diff --git a/studio/backend/utils/systemone_settings.py b/studio/backend/utils/systemone_settings.py
index 3394383f487..8748c2b73f2 100644
--- a/studio/backend/utils/systemone_settings.py
+++ b/studio/backend/utils/systemone_settings.py
@@ -72,10 +72,14 @@ def get_enabled() -> bool:
def get_model() -> str:
if model_locked():
return _env(ENV_MODEL)
- from core.systemone.catalog import CHECKPOINTS, parse_connection
+ from core.systemone.catalog import CHECKPOINTS, fine_tune, parse_connection
stored = _owner_setting(MODEL_KEY)
- return stored if stored in CHECKPOINTS or parse_connection(stored) else DEFAULT_MODEL
+ if stored in CHECKPOINTS or parse_connection(stored):
+ return stored
+ if isinstance(stored, str) and fine_tune(stored) is not None:
+ return stored
+ return DEFAULT_MODEL
def get_device() -> str:
@@ -91,7 +95,12 @@ def validate(
model: str | None = None,
device: str | None = None,
) -> dict[str, Any]:
- from core.systemone.catalog import CHECKPOINTS, decision_connections, parse_connection
+ from core.systemone.catalog import (
+ CHECKPOINTS,
+ decision_connections,
+ fine_tune,
+ parse_connection,
+ )
values: dict[str, Any] = {}
if enabled is not None:
@@ -102,11 +111,19 @@ def validate(
if model_locked():
raise ValueError(f"The Decision API model is set by {ENV_MODEL}.")
connection = parse_connection(model)
- if model not in CHECKPOINTS and not (
- connection
- and any(
- row["id"] == connection.provider_id and connection.model in models
- for row, models in decision_connections()
+ tuned = None if model in CHECKPOINTS else fine_tune(model)
+ if tuned is not None:
+ # Stored under the prefix for the folder's layout, whichever one the caller used.
+ model = tuned.name
+ if (
+ model not in CHECKPOINTS
+ and tuned is None
+ and not (
+ connection
+ and any(
+ row["id"] == connection.provider_id and connection.model in models
+ for row, models in decision_connections()
+ )
)
):
raise ValueError(f"Unknown Decision API model: {model}")
diff --git a/studio/frontend/src/config/training.ts b/studio/frontend/src/config/training.ts
index c3b5baf1f0f..397c7d986fc 100644
--- a/studio/frontend/src/config/training.ts
+++ b/studio/frontend/src/config/training.ts
@@ -139,6 +139,7 @@ export const LR_SCHEDULER_OPTIONS: ReadonlyArray<{
export const LR_DEFAULT_LORA = 2e-4;
export const LR_DEFAULT_FULL = 2e-5;
export const LR_DEFAULT_CPT = 5e-5;
+export const LR_DEFAULT_DECISION_FULL = 2.5e-5;
// Also the advanced-settings summary's "unchanged" reference while CPT is selected.
export const CPT_LORA_HYPERPARAMS = {
@@ -205,6 +206,7 @@ export const MODEL_TYPE_TO_HF_TASKS: Record<
"text-to-audio",
],
embeddings: ["feature-extraction"],
+ decision: ["text-classification"],
};
export const PRIORITY_TRAINING_MODELS: readonly string[] = [
@@ -219,6 +221,7 @@ export const PRIORITY_TRAINING_MODELS: readonly string[] = [
"unsloth/Qwen3-0.6B",
"unsloth/gemma-3-4b-it",
"unsloth/embeddinggemma-300m",
+ "convaiinnovations/laya",
"unsloth/orpheus-3b-0.1-ft",
"unsloth/Llama-3.1-8B-Instruct",
"unsloth/Llama-3.2-3B-Instruct",
diff --git a/studio/frontend/src/features/auth/index.ts b/studio/frontend/src/features/auth/index.ts
index 8e95afd9e4e..e96fa473c0a 100644
--- a/studio/frontend/src/features/auth/index.ts
+++ b/studio/frontend/src/features/auth/index.ts
@@ -26,4 +26,10 @@ export {
getTauriAuthFailure,
tauriAutoAuth,
} from "./tauri-auto-auth";
-export { OWNER_USERNAME, sessionAccount, useIsAccountOwner, useLoginMode } from "./account-session";
+export {
+ OWNER_USERNAME,
+ isAccountOwner,
+ sessionAccount,
+ useIsAccountOwner,
+ useLoginMode,
+} from "./account-session";
diff --git a/studio/frontend/src/features/dataset-picker/components/dataset-selector.tsx b/studio/frontend/src/features/dataset-picker/components/dataset-selector.tsx
index db5f7e0c087..572df07db07 100644
--- a/studio/frontend/src/features/dataset-picker/components/dataset-selector.tsx
+++ b/studio/frontend/src/features/dataset-picker/components/dataset-selector.tsx
@@ -90,7 +90,9 @@ export function DatasetSelector() {
const dataset = useTrainingConfigStore((s) => s.dataset);
const uploadedFile = useTrainingConfigStore((s) => s.uploadedFile);
const datasetSource = useTrainingConfigStore((s) => s.datasetSource);
- const modelType = useTrainingConfigStore((s) => s.modelType);
+ const modelType = useTrainingConfigStore((s) =>
+ s.modelType === "decision" ? null : s.modelType,
+ );
const selectHfDataset = useTrainingConfigStore((s) => s.selectHfDataset);
const selectLocalDataset = useTrainingConfigStore(
(s) => s.selectLocalDataset,
diff --git a/studio/frontend/src/features/settings/api/systemone.ts b/studio/frontend/src/features/settings/api/systemone.ts
index 3e987e95efc..78467878c10 100644
--- a/studio/frontend/src/features/settings/api/systemone.ts
+++ b/studio/frontend/src/features/settings/api/systemone.ts
@@ -10,6 +10,10 @@ export type SystemOneModel = {
name: string;
description: string;
downloadBytes: number;
+ kind: "catalog" | "fine_tune";
+ label: string | null;
+ available: boolean;
+ unavailableReason: string | null;
};
export type SystemOneSettings = {
@@ -72,8 +76,17 @@ type ApiSystemOneSettings = {
device_locked: boolean;
// biome-ignore lint/style/useNamingConvention: API schema
gpu_available: boolean;
- // biome-ignore lint/style/useNamingConvention: API schema
- models: { name: string; description: string; download_bytes: number }[];
+ models: {
+ name: string;
+ description: string;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ download_bytes: number;
+ kind?: "catalog" | "fine_tune";
+ label?: string | null;
+ available?: boolean;
+ // biome-ignore lint/style/useNamingConvention: API schema
+ unavailable_reason?: string | null;
+ }[];
// biome-ignore lint/style/useNamingConvention: API schema
loaded_model: string | null;
// biome-ignore lint/style/useNamingConvention: API schema
@@ -105,7 +118,8 @@ export function subscribeSystemOneSettings(
listener((event as CustomEvent<SystemOneSettings>).detail);
};
window.addEventListener(SYSTEMONE_SETTINGS_EVENT, handleChange);
- return () => window.removeEventListener(SYSTEMONE_SETTINGS_EVENT, handleChange);
+ return () =>
+ window.removeEventListener(SYSTEMONE_SETTINGS_EVENT, handleChange);
}
function publishSystemOneSettings(settings: SystemOneSettings) {
@@ -139,6 +153,10 @@ function fromApi(settings: ApiSystemOneSettings): SystemOneSettings {
name: m.name,
description: m.description,
downloadBytes: m.download_bytes,
+ kind: m.kind ?? "catalog",
+ label: m.label ?? null,
+ available: m.available ?? true,
+ unavailableReason: m.unavailable_reason ?? null,
})),
loadedModel: settings.loaded_model,
loadedDevice: settings.loaded_device,
diff --git a/studio/frontend/src/features/settings/components/decision-api-section.tsx b/studio/frontend/src/features/settings/components/decision-api-section.tsx
index 4c2bf3ac3e1..d6e33916eb0 100644
--- a/studio/frontend/src/features/settings/components/decision-api-section.tsx
+++ b/studio/frontend/src/features/settings/components/decision-api-section.tsx
@@ -32,7 +32,7 @@ import {
scopedVariant,
useDownloadManagerStore,
} from "@/features/hub";
-import { type TranslationKey, translate, useT } from "@/i18n";
+import { translate, useT } from "@/i18n";
import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import { TaskDone01Icon } from "@hugeicons/core-free-icons";
@@ -51,16 +51,15 @@ import {
updateSystemOneSettings,
validateSystemOneSettings,
} from "../api/systemone";
+import {
+ DECISION_MODEL_LABELS,
+ isClefDecisionModel,
+} from "../lib/decision-model-labels";
import { SettingsRow } from "./settings-row";
const DOWNLOAD_SCOPE = "systemone";
const POLL_MS = 5000;
const RECOMMENDED_MODEL = "laya-multilingual";
-const MODEL_LABELS: Record<string, TranslationKey> = {
- "laya-multilingual": "settings.apiKeys.decisionApi.modelMultilingual",
- "laya-english": "settings.apiKeys.decisionApi.modelEnglish",
- "laya-typed-decisions": "settings.apiKeys.decisionApi.modelTypedDecisions",
-};
const ENV_DISABLE = "UNSLOTH_SYSTEMONE_DISABLE";
const ENV_MODEL = "UNSLOTH_SYSTEMONE_MODEL";
const ENV_DEVICE = "UNSLOTH_SYSTEMONE_DEVICE";
@@ -76,9 +75,9 @@ function errorMessage(error: unknown): string | null {
export function DecisionApiSection(): ReactElement | null {
const t = useT();
const [settings, setSettings] = useState<SystemOneSettings | null>(null);
- const [connections, setConnections] = useState<
- SystemOneConnection[] | null
- >(null);
+ const [connections, setConnections] = useState<SystemOneConnection[] | null>(
+ null,
+ );
const [planState, setPlanState] = useState<{
model: string;
plan: SystemOneDownloadPlan;
@@ -120,7 +119,10 @@ export function DecisionApiSection(): ReactElement | null {
useEffect(() => {
if (scrollTarget !== "api-keys-decision-api" || !settings) return;
const frame = window.requestAnimationFrame(() => {
- sectionRef.current?.scrollIntoView({ block: "start", behavior: "smooth" });
+ sectionRef.current?.scrollIntoView({
+ block: "start",
+ behavior: "smooth",
+ });
useSettingsDialogStore
.getState()
.consumeScrollTarget("api-keys-decision-api");
@@ -160,9 +162,11 @@ export function DecisionApiSection(): ReactElement | null {
}, [enabled, model, downloadDone]);
const modelLabel = (name: string) => {
- const option = connections?.find((c) => c.name === name);
- if (option) return `${option.provider} · ${option.model}`;
- return MODEL_LABELS[name] ? t(MODEL_LABELS[name]) : name;
+ const connection = connections?.find((c) => c.name === name);
+ if (connection) return `${connection.provider} · ${connection.model}`;
+ const option = settings?.models.find((m) => m.name === name);
+ if (option?.kind === "fine_tune" && option.label) return option.label;
+ return DECISION_MODEL_LABELS[name] ? t(DECISION_MODEL_LABELS[name]) : name;
};
const resyncSettingsAfterError = async (message: string) => {
@@ -340,6 +344,7 @@ export function DecisionApiSection(): ReactElement | null {
const isRemote = settings.model.startsWith("connection:");
const remote = connections?.find((c) => c.name === settings.model);
const knownModel = current !== undefined || isRemote;
+ const longLabel = isRemote || current?.kind === "fine_tune";
const connectionGroups = [
...new Set(connections?.map((c) => c.providerId)),
].map((id) => connections?.filter((c) => c.providerId === id) ?? []);
@@ -388,7 +393,10 @@ export function DecisionApiSection(): ReactElement | null {
action = "download";
} else {
tone = "ready";
- status = t("settings.apiKeys.decisionApi.downloaded");
+ status =
+ current?.kind === "fine_tune"
+ ? t("settings.apiKeys.decisionApi.ready")
+ : t("settings.apiKeys.decisionApi.downloaded");
}
return (
@@ -488,14 +496,16 @@ export function DecisionApiSection(): ReactElement | null {
>
<SelectTrigger
className={cn(
- isRemote ? "w-64" : "w-48",
+ longLabel ? "w-64" : "w-48",
"max-[420px]:flex-1",
)}
aria-label={t("settings.apiKeys.decisionApi.model")}
- title={isRemote ? modelLabel(settings.model) : undefined}
+ title={longLabel ? modelLabel(settings.model) : undefined}
>
<SelectValue className="min-w-0">
- <span className="truncate">{modelLabel(settings.model)}</span>
+ <span className="truncate">
+ {modelLabel(settings.model)}
+ </span>
</SelectValue>
</SelectTrigger>
<SelectContent>
@@ -504,12 +514,19 @@ export function DecisionApiSection(): ReactElement | null {
{t("settings.apiKeys.decisionApi.thisMachine")}
</SelectLabel>
{settings.models.map((option) => (
- <SelectItem key={option.name} value={option.name}>
+ <SelectItem
+ key={option.name}
+ value={option.name}
+ disabled={!option.available}
+ title={option.unavailableReason ?? undefined}
+ >
<span className="flex items-center gap-2">
{modelLabel(option.name)}
- <span className="text-ui-10 tabular-nums text-muted-foreground">
- {formatBytes(option.downloadBytes)}
- </span>
+ {option.kind === "fine_tune" ? null : (
+ <span className="text-ui-10 tabular-nums text-muted-foreground">
+ {formatBytes(option.downloadBytes)}
+ </span>
+ )}
{option.name === RECOMMENDED_MODEL ? (
<span className="rounded-full bg-emerald-500/12 px-1.5 py-px text-ui-9 font-medium text-emerald-600 dark:text-emerald-400">
{t("settings.apiKeys.decisionApi.recommended")}
@@ -605,9 +622,12 @@ export function DecisionApiSection(): ReactElement | null {
<HugeiconsIcon icon={TaskDone01Icon} strokeWidth={1.75} />
</AlertDialogMedia>
<AlertDialogTitle>
- {t("settings.apiKeys.decisionApi.downloadConfirmTitle", {
- model: modelLabel(confirm?.model ?? settings.model),
- })}
+ {t(
+ isClefDecisionModel(confirm?.model ?? settings.model)
+ ? "settings.apiKeys.decisionApi.downloadConfirmTitleModel"
+ : "settings.apiKeys.decisionApi.downloadConfirmTitle",
+ { model: modelLabel(confirm?.model ?? settings.model) },
+ )}
</AlertDialogTitle>
<AlertDialogDescription>
{t("settings.apiKeys.decisionApi.downloadConfirmBody", {
diff --git a/studio/frontend/src/features/settings/index.ts b/studio/frontend/src/features/settings/index.ts
index 28ad15ba469..c135eea2e6f 100644
--- a/studio/frontend/src/features/settings/index.ts
+++ b/studio/frontend/src/features/settings/index.ts
@@ -22,7 +22,9 @@ export { listOpenAIModels } from "./api/openai-models";
export {
loadSystemOneSettings,
subscribeSystemOneSettings,
+ updateSystemOneSettings,
} from "./api/systemone";
+export { DECISION_MODEL_LABELS } from "./lib/decision-model-labels";
export {
loadHuggingFaceCacheSettings,
updateHuggingFaceCacheSettings,
diff --git a/studio/frontend/src/features/settings/lib/decision-model-labels.ts b/studio/frontend/src/features/settings/lib/decision-model-labels.ts
new file mode 100644
index 00000000000..b2a3c37a7c5
--- /dev/null
+++ b/studio/frontend/src/features/settings/lib/decision-model-labels.ts
@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import type { TranslationKey } from "@/i18n";
+
+export const DECISION_MODEL_LABELS: Record<string, TranslationKey> = {
+ "laya-multilingual": "settings.apiKeys.decisionApi.modelMultilingual",
+ "laya-english": "settings.apiKeys.decisionApi.modelEnglish",
+ "laya-typed-decisions": "settings.apiKeys.decisionApi.modelTypedDecisions",
+ "clef-flash": "settings.apiKeys.decisionApi.modelClefFlash",
+ clef: "settings.apiKeys.decisionApi.modelClef",
+};
+
+/** Cloudflare Clef models are named by themselves; the Laya labels read as "Laya <label>". */
+export function isClefDecisionModel(name: string | null | undefined): boolean {
+ return (
+ name === "clef" || name === "clef-flash" || !!name?.startsWith("clef-ft:")
+ );
+}
diff --git a/studio/frontend/src/features/studio/historical-training-view.tsx b/studio/frontend/src/features/studio/historical-training-view.tsx
index 3470a145a18..1646372e15c 100644
--- a/studio/frontend/src/features/studio/historical-training-view.tsx
+++ b/studio/frontend/src/features/studio/historical-training-view.tsx
@@ -100,6 +100,7 @@ function mapToViewData(
detail.config?.training_type,
detail.config?.load_in_4bit,
),
+ isDecision: detail.config?.is_decision === true,
lossHistory,
lrHistory,
gradNormHistory,
diff --git a/studio/frontend/src/features/studio/live-training-view.tsx b/studio/frontend/src/features/studio/live-training-view.tsx
index 76fdb7984fe..61b8cff3dc7 100644
--- a/studio/frontend/src/features/studio/live-training-view.tsx
+++ b/studio/frontend/src/features/studio/live-training-view.tsx
@@ -74,6 +74,7 @@ export function LiveTrainingView(): ReactElement {
selectedModel: state.selectedModel,
projectName: state.projectName,
trainingMethod: state.trainingMethod,
+ modelType: state.modelType,
})),
);
@@ -157,6 +158,8 @@ export function LiveTrainingView(): ReactElement {
// run started, which would relabel the run and hide its saved LoRA rows in the popover.
trainingMethod:
runConfigOverride?.trainingMethod ?? config.trainingMethod ?? "",
+ isDecision:
+ runConfigOverride?.isDecision ?? config.modelType === "decision",
lossHistory: runtime.lossHistory,
lrHistory: runtime.lrHistory,
gradNormHistory: runtime.gradNormHistory,
diff --git a/studio/frontend/src/features/studio/sections/dataset-advanced-settings-section.tsx b/studio/frontend/src/features/studio/sections/dataset-advanced-settings-section.tsx
index 2832a45d7d2..56e39fd4361 100644
--- a/studio/frontend/src/features/studio/sections/dataset-advanced-settings-section.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-advanced-settings-section.tsx
@@ -26,6 +26,7 @@ export function DatasetAdvancedSettingsSection() {
isDatasetAudio,
isDatasetImage,
isEmbeddingModel,
+ isDecisionModel,
isVisionModel,
maxSteps,
setDatasetFormat,
@@ -47,6 +48,7 @@ export function DatasetAdvancedSettingsSection() {
isDatasetAudio: state.isDatasetAudio,
isDatasetImage: state.isDatasetImage,
isEmbeddingModel: state.isEmbeddingModel,
+ isDecisionModel: state.modelType === "decision",
isVisionModel: state.isVisionModel,
maxSteps: state.maxSteps,
setDatasetFormat: state.setDatasetFormat,
@@ -97,6 +99,7 @@ export function DatasetAdvancedSettingsSection() {
datasetSliceEnd={datasetSliceEnd}
datasetSliceStart={datasetSliceStart}
datasetStreaming={datasetStreaming}
+ isDecisionModel={isDecisionModel}
isStreamingSupported={isStreamingSupported}
setDatasetFormat={setDatasetFormat}
setDatasetSliceEnd={setDatasetSliceEnd}
diff --git a/studio/frontend/src/features/studio/sections/dataset-advanced-settings.tsx b/studio/frontend/src/features/studio/sections/dataset-advanced-settings.tsx
index 47f99758738..55692242fc6 100644
--- a/studio/frontend/src/features/studio/sections/dataset-advanced-settings.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-advanced-settings.tsx
@@ -54,6 +54,7 @@ export function DatasetAdvancedSettings({
datasetSliceEnd,
datasetSliceStart,
datasetStreaming,
+ isDecisionModel,
isStreamingSupported,
setDatasetFormat,
setDatasetSliceEnd,
@@ -65,6 +66,7 @@ export function DatasetAdvancedSettings({
datasetSliceEnd: string | null;
datasetSliceStart: string | null;
datasetStreaming: boolean;
+ isDecisionModel: boolean;
isStreamingSupported: boolean;
setDatasetFormat: (format: DatasetFormat) => void;
setDatasetSliceEnd: (value: string | null) => void;
@@ -92,60 +94,62 @@ export function DatasetAdvancedSettings({
<CollapsibleContent className="mt-4 data-[state=open]:overflow-visible">
<div className="flex flex-col gap-5">
<div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
- <div className="flex flex-col gap-2">
- <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
- {t("studio.dataset.targetFormat")}
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <button
- type="button"
- aria-label={t("studio.dataset.targetFormatTooltip")}
- className={cn(
- "rounded-sm text-foreground/70 hover:text-foreground",
- PICKER_FOCUS_VISIBLE_CLASS,
- )}
- >
- <HugeiconsIcon
- icon={InformationCircleIcon}
- className="size-3"
- />
- </button>
- </TooltipTrigger>
- <TooltipContent>
- {t("studio.dataset.targetFormatTooltip")}{" "}
- <a
- href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/datasets-guide"
- target="_blank"
- rel="noopener noreferrer"
- className="text-primary underline"
- >
- {t("studio.params.readMore")}
- </a>
- </TooltipContent>
- </Tooltip>
- </span>
- <Select
- value={datasetFormat}
- onValueChange={(value) =>
- setDatasetFormat(value as DatasetFormat)
- }
- >
- <SelectTrigger className="w-full">
- <SelectValue />
- </SelectTrigger>
- <SelectContent>
- <SelectItem value="auto">
- {t("studio.dataset.auto")}
- </SelectItem>
- <SelectItem value="alpaca">Alpaca</SelectItem>
- <SelectItem value="chatml">ChatML</SelectItem>
- <SelectItem value="sharegpt">ShareGPT</SelectItem>
- <SelectItem value="raw">
- {t("studio.dataset.rawText")}
- </SelectItem>
- </SelectContent>
- </Select>
- </div>
+ {!isDecisionModel && (
+ <div className="flex flex-col gap-2">
+ <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+ {t("studio.dataset.targetFormat")}
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ aria-label={t("studio.dataset.targetFormatTooltip")}
+ className={cn(
+ "rounded-sm text-foreground/70 hover:text-foreground",
+ PICKER_FOCUS_VISIBLE_CLASS,
+ )}
+ >
+ <HugeiconsIcon
+ icon={InformationCircleIcon}
+ className="size-3"
+ />
+ </button>
+ </TooltipTrigger>
+ <TooltipContent>
+ {t("studio.dataset.targetFormatTooltip")}{" "}
+ <a
+ href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/datasets-guide"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-primary underline"
+ >
+ {t("studio.params.readMore")}
+ </a>
+ </TooltipContent>
+ </Tooltip>
+ </span>
+ <Select
+ value={datasetFormat}
+ onValueChange={(value) =>
+ setDatasetFormat(value as DatasetFormat)
+ }
+ >
+ <SelectTrigger className="w-full">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ <SelectItem value="auto">
+ {t("studio.dataset.auto")}
+ </SelectItem>
+ <SelectItem value="alpaca">Alpaca</SelectItem>
+ <SelectItem value="chatml">ChatML</SelectItem>
+ <SelectItem value="sharegpt">ShareGPT</SelectItem>
+ <SelectItem value="raw">
+ {t("studio.dataset.rawText")}
+ </SelectItem>
+ </SelectContent>
+ </Select>
+ </div>
+ )}
<div className="flex flex-col gap-1.5">
<span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
{t("studio.dataset.trainSplitStart")}
@@ -219,59 +223,61 @@ export function DatasetAdvancedSettings({
/>
</div>
</div>
- <div className="flex items-center gap-2">
- <Checkbox
- id="datasetStreaming"
- checked={datasetStreaming}
- disabled={!isStreamingSupported}
- onCheckedChange={(value) => setDatasetStreaming(Boolean(value))}
- />
- <label
- htmlFor="datasetStreaming"
- className={`text-xs text-muted-foreground ${
- isStreamingSupported
- ? "cursor-pointer"
- : "cursor-not-allowed opacity-60"
- }`}
- >
- {t("studio.dataset.streaming.label")}
- </label>
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <button
- type="button"
- aria-label={t("studio.dataset.streamingInfoAriaLabel")}
- className={cn(
- "rounded-sm text-foreground/70 hover:text-foreground",
- PICKER_FOCUS_VISIBLE_CLASS,
+ {!isDecisionModel && (
+ <div className="flex items-center gap-2">
+ <Checkbox
+ id="datasetStreaming"
+ checked={datasetStreaming}
+ disabled={!isStreamingSupported}
+ onCheckedChange={(value) => setDatasetStreaming(Boolean(value))}
+ />
+ <label
+ htmlFor="datasetStreaming"
+ className={`text-xs text-muted-foreground ${
+ isStreamingSupported
+ ? "cursor-pointer"
+ : "cursor-not-allowed opacity-60"
+ }`}
+ >
+ {t("studio.dataset.streaming.label")}
+ </label>
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ aria-label={t("studio.dataset.streamingInfoAriaLabel")}
+ className={cn(
+ "rounded-sm text-foreground/70 hover:text-foreground",
+ PICKER_FOCUS_VISIBLE_CLASS,
+ )}
+ >
+ <HugeiconsIcon
+ icon={InformationCircleIcon}
+ className="size-3"
+ />
+ </button>
+ </TooltipTrigger>
+ <TooltipContent>
+ {isStreamingSupported ? (
+ <span>{t("studio.dataset.streaming.description")}</span>
+ ) : (
+ <div className="max-w-xs">
+ <p className="font-medium">
+ {t("studio.dataset.streaming.unavailable")}
+ </p>
+ <ul className="mt-1 list-disc space-y-0.5 pl-4">
+ {streamingBlockers.map((reason) => (
+ <li key={reason}>
+ {t(DATASET_STREAMING_BLOCKER_KEYS[reason])}
+ </li>
+ ))}
+ </ul>
+ </div>
)}
- >
- <HugeiconsIcon
- icon={InformationCircleIcon}
- className="size-3"
- />
- </button>
- </TooltipTrigger>
- <TooltipContent>
- {isStreamingSupported ? (
- <span>{t("studio.dataset.streaming.description")}</span>
- ) : (
- <div className="max-w-xs">
- <p className="font-medium">
- {t("studio.dataset.streaming.unavailable")}
- </p>
- <ul className="mt-1 list-disc space-y-0.5 pl-4">
- {streamingBlockers.map((reason) => (
- <li key={reason}>
- {t(DATASET_STREAMING_BLOCKER_KEYS[reason])}
- </li>
- ))}
- </ul>
- </div>
- )}
- </TooltipContent>
- </Tooltip>
- </div>
+ </TooltipContent>
+ </Tooltip>
+ </div>
+ )}
</div>
</CollapsibleContent>
</Collapsible>
diff --git a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
index afc3b1ac995..f2903638be4 100644
--- a/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
+++ b/studio/frontend/src/features/studio/sections/dataset-preview-dialog.tsx
@@ -192,10 +192,12 @@ export function DatasetPreviewDialog({
const effectiveIsVlm = isVlm || !!data?.is_image;
const isRawFormat = isRawTextDatasetFormat(datasetFormat);
+ const isDecisionModel = modelType === "decision";
const hasHeuristicMapping =
!data?.requires_manual_mapping && !!data?.suggested_mapping;
const mappingEnabled =
- !isRawFormat && (!!data?.requires_manual_mapping || hasHeuristicMapping);
+ !(isRawFormat || isDecisionModel) &&
+ (!!data?.requires_manual_mapping || hasHeuristicMapping);
const showMappingFooter = mode === "mapping" && mappingEnabled;
const mappingOk =
isRawFormat ||
@@ -401,7 +403,7 @@ export function DatasetPreviewDialog({
// Pre-fill mapping from suggested_mapping when data arrives (never overwriting existing entries).
useEffect(() => {
- if (!open || !datasetName) return;
+ if (!open || !datasetName || isDecisionModel) return;
if (!data?.requires_manual_mapping && !data?.suggested_mapping) return;
if (Object.keys(manualMapping).length > 0) return;
const derived = deriveDefaultMapping(
@@ -415,6 +417,7 @@ export function DatasetPreviewDialog({
}, [
open,
datasetName,
+ isDecisionModel,
data,
effectiveIsVlm,
datasetFormat,
@@ -662,7 +665,7 @@ export function DatasetPreviewDialog({
</div>
)}
- {data.warning && !isRawFormat && (
+ {data.warning && !isRawFormat && !isDecisionModel && (
<div className="rounded-lg border border-amber-200 bg-amber-50 px-4 py-3 text-xs text-amber-700 dark:border-amber-800 dark:bg-amber-950 dark:text-amber-400 mb-4 flex items-start gap-2.5">
<HugeiconsIcon
icon={AlertCircleIcon}
diff --git a/studio/frontend/src/features/studio/sections/lora-params-section.tsx b/studio/frontend/src/features/studio/sections/lora-params-section.tsx
index 934dcd97d13..dac781af1eb 100644
--- a/studio/frontend/src/features/studio/sections/lora-params-section.tsx
+++ b/studio/frontend/src/features/studio/sections/lora-params-section.tsx
@@ -32,6 +32,7 @@ export function LoraParamsSection(): ReactElement | null {
const store = useTrainingConfigStore(
useShallow((state) => ({
trainingMethod: state.trainingMethod,
+ isDecision: state.modelType === "decision",
isVisionModel: state.isVisionModel,
isDatasetImage: state.isDatasetImage,
loraRank: state.loraRank,
@@ -190,7 +191,7 @@ export function LoraParamsSection(): ReactElement | null {
</div>
)}
- {!showVisionLora && (
+ {!(showVisionLora || store.isDecision) && (
<div className="flex flex-col gap-2 pt-1">
<span className="text-xs font-medium text-muted-foreground">
{t("studio.params.targetModules")}
@@ -223,59 +224,62 @@ export function LoraParamsSection(): ReactElement | null {
</div>
)}
- <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
- {(
- [
- {
- value: "lora",
- label: t("studio.params.enableLora"),
- desc: t("studio.params.trainWithLora"),
- },
- {
- value: "rslora",
- label: "RS-LoRA",
- desc: t("studio.params.stableRank"),
- },
- {
- value: "loftq",
- label: "LoftQ",
- desc: t("studio.params.memoryEfficient"),
- },
- {
- value: "dora",
- label: "DoRA",
- desc: t("studio.params.weightDecomposed"),
- },
- ] as const
- ).map((option) => {
- const unsupportedOnMlx = !isTrainingLoraVariantSupportedOnDevice(
- option.value,
- store.trainingMethod,
- deviceType,
- );
- const needsVisionOff =
- option.value === "dora" && doraNeedsVisionOff;
- return (
- <button
- key={option.value}
- type="button"
- disabled={unsupportedOnMlx || needsVisionOff}
- aria-pressed={store.loraVariant === option.value}
- onClick={() => store.setLoraVariant(option.value)}
- className={`flex-1 corner-squircle rounded-[14px] border px-3 py-2 text-left transition-colors cursor-pointer disabled:cursor-not-allowed disabled:opacity-60 ${selectableOptionStateClassName(store.loraVariant === option.value)}`}
- >
- <p className="text-xs font-medium">{option.label}</p>
- <p className="text-ui-10 text-muted-foreground">
- {unsupportedOnMlx
- ? t("studio.params.notSupportedAppleSilicon")
- : needsVisionOff
- ? t("studio.params.doraNeedsVisionLayersOff")
- : option.desc}
- </p>
- </button>
- );
- })}
- </div>
+ {!store.isDecision && (
+ <div className="grid grid-cols-1 gap-2 sm:grid-cols-2">
+ {(
+ [
+ {
+ value: "lora",
+ label: t("studio.params.enableLora"),
+ desc: t("studio.params.trainWithLora"),
+ },
+ {
+ value: "rslora",
+ label: "RS-LoRA",
+ desc: t("studio.params.stableRank"),
+ },
+ {
+ value: "loftq",
+ label: "LoftQ",
+ desc: t("studio.params.memoryEfficient"),
+ },
+ {
+ value: "dora",
+ label: "DoRA",
+ desc: t("studio.params.weightDecomposed"),
+ },
+ ] as const
+ ).map((option) => {
+ const unsupportedOnMlx =
+ !isTrainingLoraVariantSupportedOnDevice(
+ option.value,
+ store.trainingMethod,
+ deviceType,
+ );
+ const needsVisionOff =
+ option.value === "dora" && doraNeedsVisionOff;
+ return (
+ <button
+ key={option.value}
+ type="button"
+ disabled={unsupportedOnMlx || needsVisionOff}
+ aria-pressed={store.loraVariant === option.value}
+ onClick={() => store.setLoraVariant(option.value)}
+ className={`flex-1 corner-squircle rounded-[14px] border px-3 py-2 text-left transition-colors cursor-pointer disabled:cursor-not-allowed disabled:opacity-60 ${selectableOptionStateClassName(store.loraVariant === option.value)}`}
+ >
+ <p className="text-xs font-medium">{option.label}</p>
+ <p className="text-ui-10 text-muted-foreground">
+ {unsupportedOnMlx
+ ? t("studio.params.notSupportedAppleSilicon")
+ : needsVisionOff
+ ? t("studio.params.doraNeedsVisionLayersOff")
+ : option.desc}
+ </p>
+ </button>
+ );
+ })}
+ </div>
+ )}
</div>
</CollapsibleContent>
</Collapsible>
diff --git a/studio/frontend/src/features/studio/sections/params-section.tsx b/studio/frontend/src/features/studio/sections/params-section.tsx
index 0214acb7459..b1690e94c55 100644
--- a/studio/frontend/src/features/studio/sections/params-section.tsx
+++ b/studio/frontend/src/features/studio/sections/params-section.tsx
@@ -51,6 +51,7 @@ export function ParamsSection({
useShallow((state) => ({
projectName: state.projectName,
trainingMethod: state.trainingMethod,
+ isDecision: state.modelType === "decision",
epochs: state.epochs,
contextLength: state.contextLength,
learningRate: state.learningRate,
@@ -269,86 +270,88 @@ export function ParamsSection({
</div>
</div>
- <div className="flex flex-col gap-2">
- <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
- {t("studio.params.contextLength")}
- <Tooltip>
- <TooltipTrigger asChild={true}>
- <button
- type="button"
- className="text-foreground/70 hover:text-foreground"
- >
- <HugeiconsIcon
- icon={InformationCircleIcon}
- className="size-3"
- />
- </button>
- </TooltipTrigger>
- <TooltipContent>
- {t("studio.params.contextLengthTooltip")}{" "}
- <a
- href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
- target="_blank"
- rel="noopener noreferrer"
- className="text-primary underline"
- >
- {t("studio.params.readMore")}
- </a>
- </TooltipContent>
- </Tooltip>
- </span>
- <div ref={contextAnchorRef}>
- <Combobox
- items={contextItems}
- filteredItems={contextItems}
- filter={null}
- value={String(store.contextLength)}
- onValueChange={(value) => {
- if (value && trySetContextLength(value)) {
- setContextInput(value);
- }
- }}
- onInputValueChange={setContextInput}
- itemToStringValue={(id) => Number(id).toLocaleString()}
- autoHighlight={false}
- >
- <ComboboxInput
- placeholder={String(store.contextLength)}
- className="w-full font-mono"
- onBlur={() => {
- trySetContextLength(contextInput);
- setContextInput(String(store.contextLength));
- }}
- onKeyDown={(event) => {
- if (event.key !== "Enter") {
- return;
- }
- const value = trySetContextLength(contextInput);
- if (value === null) {
- return;
- }
- if (!contextItems.includes(contextInput.trim())) {
- event.stopPropagation();
- event.preventDefault();
+ {!store.isDecision && (
+ <div className="flex flex-col gap-2">
+ <span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
+ {t("studio.params.contextLength")}
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <button
+ type="button"
+ className="text-foreground/70 hover:text-foreground"
+ >
+ <HugeiconsIcon
+ icon={InformationCircleIcon}
+ className="size-3"
+ />
+ </button>
+ </TooltipTrigger>
+ <TooltipContent>
+ {t("studio.params.contextLengthTooltip")}{" "}
+ <a
+ href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-primary underline"
+ >
+ {t("studio.params.readMore")}
+ </a>
+ </TooltipContent>
+ </Tooltip>
+ </span>
+ <div ref={contextAnchorRef}>
+ <Combobox
+ items={contextItems}
+ filteredItems={contextItems}
+ filter={null}
+ value={String(store.contextLength)}
+ onValueChange={(value) => {
+ if (value && trySetContextLength(value)) {
+ setContextInput(value);
}
- setContextInput(String(value));
}}
- />
- <ComboboxContent anchor={contextAnchorRef}>
- <ComboboxEmpty>
- {t("studio.params.customContextLength")}
- </ComboboxEmpty>
- <ComboboxList className="p-1">
- {(id: string) => (
- <ComboboxItem key={id} value={id} className="font-mono">
- {Number(id).toLocaleString()}
- </ComboboxItem>
- )}
- </ComboboxList>
- </ComboboxContent>
- </Combobox>
+ onInputValueChange={setContextInput}
+ itemToStringValue={(id) => Number(id).toLocaleString()}
+ autoHighlight={false}
+ >
+ <ComboboxInput
+ placeholder={String(store.contextLength)}
+ className="w-full font-mono"
+ onBlur={() => {
+ trySetContextLength(contextInput);
+ setContextInput(String(store.contextLength));
+ }}
+ onKeyDown={(event) => {
+ if (event.key !== "Enter") {
+ return;
+ }
+ const value = trySetContextLength(contextInput);
+ if (value === null) {
+ return;
+ }
+ if (!contextItems.includes(contextInput.trim())) {
+ event.stopPropagation();
+ event.preventDefault();
+ }
+ setContextInput(String(value));
+ }}
+ />
+ <ComboboxContent anchor={contextAnchorRef}>
+ <ComboboxEmpty>
+ {t("studio.params.customContextLength")}
+ </ComboboxEmpty>
+ <ComboboxList className="p-1">
+ {(id: string) => (
+ <ComboboxItem key={id} value={id} className="font-mono">
+ {Number(id).toLocaleString()}
+ </ComboboxItem>
+ )}
+ </ComboboxList>
+ </ComboboxContent>
+ </Combobox>
+ </div>
</div>
- </div>
+ )}
<div className="flex flex-col gap-2">
<span className="flex items-center gap-1.5 text-xs font-medium text-muted-foreground">
diff --git a/studio/frontend/src/features/studio/sections/progress-section.tsx b/studio/frontend/src/features/studio/sections/progress-section.tsx
index 11e71fd0438..e1505b42452 100644
--- a/studio/frontend/src/features/studio/sections/progress-section.tsx
+++ b/studio/frontend/src/features/studio/sections/progress-section.tsx
@@ -21,7 +21,9 @@ import {
import { Progress } from "@/components/ui/progress";
import { usePlatformStore } from "@/config/env";
import { MLX_OPTIMIZER_OPTIONS, OPTIMIZER_OPTIONS } from "@/config/training";
+import { useIsAccountOwner } from "@/features/auth";
import { setTrainingCompareHandoff } from "@/features/chat";
+import { updateSystemOneSettings } from "@/features/settings";
import {
getTrainingMethodLabel,
type TrainingViewData,
@@ -32,6 +34,7 @@ import {
import { useGpuUtilization } from "@/hooks";
import type { GpuUtilization } from "@/hooks/use-gpu-utilization";
import { type TranslationKey, useT } from "@/i18n";
+import { toast } from "@/lib/toast";
import { cn } from "@/lib/utils";
import {
Alert02Icon,
@@ -41,6 +44,7 @@ import {
Notebook01Icon,
RamMemoryIcon,
StopIcon,
+ TaskDone01Icon,
TemperatureIcon,
ZapIcon,
} from "@hugeicons/core-free-icons";
@@ -98,6 +102,7 @@ export function ProgressSection({
const t = useT();
const navigate = useNavigate();
const platformDeviceType = usePlatformStore((s) => s.deviceType);
+ const isOwner = useIsAccountOwner();
const trainingMethodLabel = getTrainingMethodLabel(data.trainingMethod);
const config = useTrainingConfigStore(
@@ -118,6 +123,7 @@ export function ProgressSection({
const [stopDialogOpen, setStopDialogOpen] = useState(false);
const [stopRequestedLocal, setStopRequestedLocal] = useState(false);
+ const [enablingDecisionApi, setEnablingDecisionApi] = useState(false);
const stopRequested = data.isTrainingRunning && stopRequestedLocal;
@@ -154,7 +160,7 @@ export function ProgressSection({
);
const showHalfwayHint =
data.phase === "training" && pct >= 50 && pct < 100;
- const showCompletedHint = data.phase === "completed";
+ const showCompletedHint = data.phase === "completed" && !data.isDecision;
const handleCompareInChat = async () => {
setTrainingCompareHandoff(data.modelName, data.outputDir);
await navigate({ to: "/chat" });
@@ -164,15 +170,38 @@ export function ProgressSection({
const exportRunName = data.outputDir
? (data.outputDir.replace(/[/\\]+$/, "").split(/[/\\]/).pop() || null)
: null;
- const canExportGguf =
+ const hasFinishedOutput =
!data.isTrainingRunning &&
!!exportRunName &&
!data.resumedLater &&
(data.phase === "completed" || data.phase === "stopped");
+ const canExportGguf = hasFinishedOutput && !data.isDecision;
+ const canUseInDecisionApi = hasFinishedOutput && !!data.isDecision && isOwner;
const handleExportGguf = () => {
if (!exportRunName) return;
void navigate({ to: "/export", search: { run: exportRunName } });
};
+ const handleUseInDecisionApi = async () => {
+ if (!exportRunName) {
+ return;
+ }
+ setEnablingDecisionApi(true);
+ try {
+ await updateSystemOneSettings({
+ enabled: true,
+ model: `laya-ft:${exportRunName}`,
+ });
+ toast.success(
+ t("studio.progress.decisionApiEnabled", { name: exportRunName }),
+ );
+ } catch (error) {
+ toast.error(t("studio.progress.decisionApiFailed"), {
+ description: error instanceof Error ? error.message : undefined,
+ });
+ } finally {
+ setEnablingDecisionApi(false);
+ }
+ };
const stoppedLoss = getDisplayMetric(
data.isTrainingRunning,
@@ -220,9 +249,13 @@ export function ProgressSection({
configRow(t("studio.progress.epochs"), cfgEpochs),
configRow(t("studio.progress.batchSize"), cfgBatchSize),
configRow(t("studio.progress.learningRate"), cfgLearningRate),
- configRow(t("studio.progress.optimizer"), optimizerLabel),
+ ...(data.isDecision
+ ? []
+ : [configRow(t("studio.progress.optimizer"), optimizerLabel)]),
configRow(t("studio.progress.maxSteps"), cfgMaxSteps),
- configRow(t("studio.progress.contextLength"), cfgContextLength),
+ ...(data.isDecision
+ ? []
+ : [configRow(t("studio.progress.contextLength"), cfgContextLength)]),
configRow(t("studio.progress.warmupSteps"), cfgWarmupSteps),
],
},
@@ -234,7 +267,9 @@ export function ProgressSection({
configRow(t("studio.progress.rank"), cfgLoraRank),
configRow(t("studio.progress.alpha"), cfgLoraAlpha),
configRow(t("studio.progress.dropout"), cfgLoraDropout),
- configRow(t("studio.progress.variant"), cfgLoraVariant),
+ ...(data.isDecision
+ ? []
+ : [configRow(t("studio.progress.variant"), cfgLoraVariant)]),
],
},
]
@@ -261,6 +296,18 @@ export function ProgressSection({
{t("studio.progress.exportGguf")}
</Button>
)}
+ {canUseInDecisionApi && (
+ <Button
+ size="sm"
+ variant="outline"
+ className="h-8 gap-1.5 text-xs"
+ disabled={enablingDecisionApi}
+ onClick={handleUseInDecisionApi}
+ >
+ <HugeiconsIcon icon={TaskDone01Icon} className="size-3.5" />
+ {t("studio.progress.useInDecisionApi")}
+ </Button>
+ )}
{isHistorical ? (
<ConfigPopoverButton configItems={configItems} />
) : (
diff --git a/studio/frontend/src/features/studio/sections/run-config-override.ts b/studio/frontend/src/features/studio/sections/run-config-override.ts
index 8ef3d9d1b6d..f3b3860c073 100644
--- a/studio/frontend/src/features/studio/sections/run-config-override.ts
+++ b/studio/frontend/src/features/studio/sections/run-config-override.ts
@@ -7,6 +7,7 @@ import { parseBackendTrainingMethod } from "@/features/training";
* run snapshot instead of the editable form store. */
export interface RunConfigOverride {
trainingMethod?: string;
+ isDecision?: boolean;
epochs?: number;
batchSize?: number;
learningRate?: string;
@@ -35,6 +36,7 @@ export function mapRunConfigToOverride(
config.training_type,
config.load_in_4bit,
),
+ isDecision: config.is_decision === true,
epochs: config.num_epochs as number | undefined,
batchSize: config.batch_size as number | undefined,
learningRate: config.learning_rate as string | undefined,
diff --git a/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx b/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
index 418063c6ba5..4184767e69a 100644
--- a/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
+++ b/studio/frontend/src/features/studio/sections/training-hyperparameters-section.tsx
@@ -84,6 +84,7 @@ export function TrainingHyperparametersSection({
const store = useTrainingConfigStore(
useShallow((state) => ({
epochs: state.epochs,
+ isDecision: state.modelType === "decision",
optimizerType: state.optimizerType,
lrSchedulerType: state.lrSchedulerType,
batchSize: state.batchSize,
@@ -149,42 +150,44 @@ export function TrainingHyperparametersSection({
value="optimization"
className="mt-3 flex flex-col gap-3"
>
- <ParamsRow
- label={t("studio.params.optimizer")}
- tooltip={
- <>
- {t(
- isMac
- ? "studio.params.optimizerTooltipMlx"
- : "studio.params.optimizerTooltip",
- )}{" "}
- <a
- href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
- target="_blank"
- rel="noopener noreferrer"
- className="text-primary underline"
- >
- {t("studio.params.readMore")}
- </a>
- </>
- }
- >
- <Select
- value={selectedOptimizer}
- onValueChange={store.setOptimizerType}
+ {!store.isDecision && (
+ <ParamsRow
+ label={t("studio.params.optimizer")}
+ tooltip={
+ <>
+ {t(
+ isMac
+ ? "studio.params.optimizerTooltipMlx"
+ : "studio.params.optimizerTooltip",
+ )}{" "}
+ <a
+ href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-primary underline"
+ >
+ {t("studio.params.readMore")}
+ </a>
+ </>
+ }
>
- <SelectTrigger className="w-48">
- <SelectValue />
- </SelectTrigger>
- <SelectContent>
- {optimizerOptions.map((option) => (
- <SelectItem key={option.value} value={option.value}>
- {formatOptimizerLabel(option.value, option.label, t)}
- </SelectItem>
- ))}
- </SelectContent>
- </Select>
- </ParamsRow>
+ <Select
+ value={selectedOptimizer}
+ onValueChange={store.setOptimizerType}
+ >
+ <SelectTrigger className="w-48">
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {optimizerOptions.map((option) => (
+ <SelectItem key={option.value} value={option.value}>
+ {formatOptimizerLabel(option.value, option.label, t)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ </ParamsRow>
+ )}
<ParamsRow
label={t("studio.params.lrScheduler")}
tooltip={
@@ -332,31 +335,33 @@ export function TrainingHyperparametersSection({
step={1}
/>
)}
- <ParamsRow
- label={t("studio.params.saveSteps")}
- tooltip={
- <>
- {t("studio.params.saveStepsTooltip")}{" "}
- <a
- href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
- target="_blank"
- rel="noopener noreferrer"
- className="text-primary underline"
- >
- {t("studio.params.readMore")}
- </a>
- </>
- }
- >
- <Input
- type="number"
- value={store.saveSteps}
- onChange={(event) =>
- store.setSaveSteps(Number(event.target.value))
+ {!store.isDecision && (
+ <ParamsRow
+ label={t("studio.params.saveSteps")}
+ tooltip={
+ <>
+ {t("studio.params.saveStepsTooltip")}{" "}
+ <a
+ href="https://unsloth.ai/docs/get-started/fine-tuning-llms-guide/lora-hyperparameters-guide"
+ target="_blank"
+ rel="noopener noreferrer"
+ className="text-primary underline"
+ >
+ {t("studio.params.readMore")}
+ </a>
+ </>
}
- className="w-28 font-mono"
- />
- </ParamsRow>
+ >
+ <Input
+ type="number"
+ value={store.saveSteps}
+ onChange={(event) =>
+ store.setSaveSteps(Number(event.target.value))
+ }
+ className="w-28 font-mono"
+ />
+ </ParamsRow>
+ )}
<ParamsRow
label={t("studio.params.evalSteps")}
tooltip={t("studio.params.evalStepsTooltip")}
diff --git a/studio/frontend/src/features/studio/sections/training-memory-params.tsx b/studio/frontend/src/features/studio/sections/training-memory-params.tsx
index c67f0caa0b2..b15e794ed37 100644
--- a/studio/frontend/src/features/studio/sections/training-memory-params.tsx
+++ b/studio/frontend/src/features/studio/sections/training-memory-params.tsx
@@ -125,6 +125,7 @@ export function TrainingMemoryParams(): ReactElement {
gradientCheckpointing: state.gradientCheckpointing,
isVisionModel: state.isVisionModel,
isEmbeddingModel: state.isEmbeddingModel,
+ isDecision: state.modelType === "decision",
isDatasetImage: state.isDatasetImage,
visionImageSize: state.visionImageSize,
setVisionImageSize: state.setVisionImageSize,
@@ -141,9 +142,14 @@ export function TrainingMemoryParams(): ReactElement {
selectedModelLower.includes("deepseek") &&
selectedModelLower.includes("ocr")
);
- const showPacking = !(showVisionLora || store.isEmbeddingModel);
+ const showPacking = !(
+ showVisionLora ||
+ store.isEmbeddingModel ||
+ store.isDecision
+ );
const showTrainOnCompletions = !(
store.isEmbeddingModel ||
+ store.isDecision ||
store.trainingMethod === "cpt" ||
isRawTextDatasetFormat(store.datasetFormat)
);
diff --git a/studio/frontend/src/features/studio/wizard/advanced-settings-summary.ts b/studio/frontend/src/features/studio/wizard/advanced-settings-summary.ts
index b3689dfd6e3..16dbb1ae6d3 100644
--- a/studio/frontend/src/features/studio/wizard/advanced-settings-summary.ts
+++ b/studio/frontend/src/features/studio/wizard/advanced-settings-summary.ts
@@ -15,7 +15,8 @@ import { isAdapterMethod } from "@/types/training";
type AdvancedSettingsState = Pick<
TrainingConfigState,
"trainingMethod" | keyof AdvancedSettingsBaseline
->;
+> &
+ Partial<Pick<TrainingConfigState, "modelType">>;
const SCALAR_DEFAULTS = {
optimizerType: DEFAULT_HYPERPARAMS.optimizerType,
@@ -35,6 +36,20 @@ const SCALAR_DEFAULTS = {
finetuneMLPModules: DEFAULT_HYPERPARAMS.finetuneMLPModules,
} as const;
+const DECISION_IGNORED_SETTINGS: ReadonlySet<string> = new Set([
+ "optimizerType",
+ "saveSteps",
+ "packing",
+ "trainOnCompletions",
+ "visionImageSize",
+ "finetuneVisionLayers",
+ "finetuneLanguageLayers",
+ "finetuneAttentionModules",
+ "finetuneMLPModules",
+ "loraVariant",
+ "targetModules",
+]);
+
function sameValues(
left: readonly string[],
right: readonly string[],
@@ -47,6 +62,10 @@ function sameValues(
return sortedLeft.every((value, index) => value === sortedRight[index]);
}
+function isIgnored(state: AdvancedSettingsState, key: string): boolean {
+ return state.modelType === "decision" && DECISION_IGNORED_SETTINGS.has(key);
+}
+
function baselineValue<K extends keyof AdvancedSettingsBaseline>(
baseline: AdvancedSettingsBaseline | null,
key: K,
@@ -62,6 +81,9 @@ function countNonDefaultScalarSettings(
): number {
return Object.entries(SCALAR_DEFAULTS).reduce((total, [rawKey, value]) => {
const key = rawKey as keyof typeof SCALAR_DEFAULTS;
+ if (isIgnored(state, key)) {
+ return total;
+ }
const expected =
key === "trainOnCompletions" && state.trainingMethod === "cpt"
? false
@@ -93,9 +115,14 @@ function countNonDefaultLoraSettings(
} as const;
const count = Object.entries(loraDefaults).reduce(
(total, [key, value]) =>
- state[key as keyof typeof loraDefaults] === value ? total : total + 1,
+ isIgnored(state, key) || state[key as keyof typeof loraDefaults] === value
+ ? total
+ : total + 1,
0,
);
+ if (isIgnored(state, "targetModules")) {
+ return count;
+ }
const defaultTargetModules = isCpt
? resolveCptTargetModules(
baselineValue(
diff --git a/studio/frontend/src/features/studio/wizard/run-preview-card.tsx b/studio/frontend/src/features/studio/wizard/run-preview-card.tsx
index 6f6284939bb..0eb8ed16eb5 100644
--- a/studio/frontend/src/features/studio/wizard/run-preview-card.tsx
+++ b/studio/frontend/src/features/studio/wizard/run-preview-card.tsx
@@ -356,6 +356,7 @@ export function RunPreviewCard({
gradientAccumulation,
learningRate,
contextLength,
+ isDecision,
} = useTrainingConfigStore(
useShallow((s) => ({
selectedModel: s.selectedModel,
@@ -374,6 +375,7 @@ export function RunPreviewCard({
gradientAccumulation: s.gradientAccumulation,
learningRate: s.learningRate,
contextLength: s.contextLength,
+ isDecision: s.modelType === "decision",
})),
);
@@ -490,11 +492,13 @@ export function RunPreviewCard({
/>
}
/>
- <MetaRow
- label={t("studio.preview.context")}
- value={numberFormatter.format(contextLength)}
- mono={true}
- />
+ {!isDecision && (
+ <MetaRow
+ label={t("studio.preview.context")}
+ value={numberFormatter.format(contextLength)}
+ mono={true}
+ />
+ )}
<MetaRow
label={t("studio.preview.lr")}
value={formatLearningRate(learningRate)}
diff --git a/studio/frontend/src/features/studio/wizard/training-wizard.tsx b/studio/frontend/src/features/studio/wizard/training-wizard.tsx
index e40a418984e..c5af34b8c15 100644
--- a/studio/frontend/src/features/studio/wizard/training-wizard.tsx
+++ b/studio/frontend/src/features/studio/wizard/training-wizard.tsx
@@ -17,9 +17,13 @@ import {
} from "@/components/ui/tooltip";
import { usePlatformStore } from "@/config/env";
import { HfTokenIndicator } from "@/features/hub";
-import { useSettingsDialogStore } from "@/features/settings";
+import {
+ DECISION_MODEL_LABELS,
+ useSettingsDialogStore,
+} from "@/features/settings";
import { TrainModelSelector } from "@/features/train-model-picker";
import {
+ type DecisionCheckpoint,
TRAINING_METHOD_META,
TRAINING_METHOD_ORDER,
isTrainingMethodSupportedOnDevice,
@@ -161,6 +165,10 @@ function TrainingMethodSelect() {
const t = useT();
const trainingMethod = useTrainingConfigStore((s) => s.trainingMethod);
const setTrainingMethod = useTrainingConfigStore((s) => s.setTrainingMethod);
+ const isDecision = useTrainingConfigStore((s) => s.modelType === "decision");
+ const isClef = useTrainingConfigStore(
+ (s) => s.modelType === "decision" && s.decisionLayout === "clef",
+ );
const deviceType = usePlatformStore((state) => state.deviceType);
const activeMeta = TRAINING_METHOD_META[trainingMethod];
const activeLabel = activeMeta ? t(activeMeta.labelKey) : trainingMethod;
@@ -197,7 +205,13 @@ function TrainingMethodSelect() {
sideOffset={8}
className="rounded-[14px] ring-0"
>
- {TRAINING_METHOD_ORDER.map((method) => {
+ {TRAINING_METHOD_ORDER.filter(
+ (method) =>
+ !isDecision ||
+ method === "lora" ||
+ method === "full" ||
+ (isClef && method === "qlora"),
+ ).map((method) => {
const meta = TRAINING_METHOD_META[method];
const unsupportedOnMlx = !isTrainingMethodSupportedOnDevice(
method,
@@ -241,9 +255,62 @@ function TrainingMethodSelect() {
);
}
+function CheckpointSelect({
+ checkpoints,
+}: {
+ checkpoints: DecisionCheckpoint[];
+}) {
+ const t = useT();
+ const modelSubfolder = useTrainingConfigStore((s) => s.modelSubfolder);
+ const setModelSubfolder = useTrainingConfigStore((s) => s.setModelSubfolder);
+ const active =
+ checkpoints.find((checkpoint) => checkpoint.subfolder === modelSubfolder) ??
+ checkpoints[0];
+ const checkpointLabel = (checkpoint: DecisionCheckpoint) =>
+ DECISION_MODEL_LABELS[checkpoint.name]
+ ? t(DECISION_MODEL_LABELS[checkpoint.name])
+ : checkpoint.name;
+ return (
+ <Select
+ value={active.name}
+ onValueChange={(name) => {
+ const next = checkpoints.find((checkpoint) => checkpoint.name === name);
+ if (next) {
+ setModelSubfolder(next.subfolder);
+ }
+ }}
+ >
+ <SelectTrigger
+ aria-label={`${t("studio.wizard.checkpointLabel")}: ${checkpointLabel(active)}`}
+ className={cn(PICKER_TRIGGER_CLASS, "w-full justify-between")}
+ >
+ <span className="truncate font-medium text-foreground">
+ {checkpointLabel(active)}
+ </span>
+ </SelectTrigger>
+ <SelectContent
+ position="popper"
+ side="bottom"
+ align="start"
+ sideOffset={8}
+ className="rounded-[14px] ring-0"
+ >
+ {checkpoints.map((checkpoint) => (
+ <SelectItem key={checkpoint.name} value={checkpoint.name}>
+ {checkpointLabel(checkpoint)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ );
+}
+
function ModelPanel() {
const t = useT();
const openSettings = useSettingsDialogStore((s) => s.openDialog);
+ const decisionCheckpoints = useTrainingConfigStore((s) =>
+ s.modelType === "decision" ? s.decisionCheckpoints : null,
+ );
return (
<div className="grid grid-cols-1 gap-4 @md/train-section:grid-cols-2 @2xl/train-section:grid-cols-[minmax(0,1fr)_180px_200px]">
<div className="@md/train-section:col-span-2 @2xl/train-section:col-span-1">
@@ -269,6 +336,14 @@ function ModelPanel() {
onOpenSettings={() => openSettings("general")}
/>
</SetupField>
+ {decisionCheckpoints && decisionCheckpoints.length > 0 ? (
+ <SetupField
+ label={t("studio.wizard.checkpointLabel")}
+ hint={t("studio.wizard.checkpointTooltip")}
+ >
+ <CheckpointSelect checkpoints={decisionCheckpoints} />
+ </SetupField>
+ ) : null}
</div>
);
}
diff --git a/studio/frontend/src/features/training/api/datasets-api.ts b/studio/frontend/src/features/training/api/datasets-api.ts
index 08c81d3c588..fc499b7bf50 100644
--- a/studio/frontend/src/features/training/api/datasets-api.ts
+++ b/studio/frontend/src/features/training/api/datasets-api.ts
@@ -138,7 +138,7 @@ type AiAssistMappingArgs = {
datasetName?: string | null;
hfToken?: string | null;
modelName?: string | null;
- modelType?: "text" | "vision" | "audio" | "embeddings" | null;
+ modelType?: "text" | "vision" | "audio" | "embeddings" | "decision" | null;
signal?: AbortSignal;
};
diff --git a/studio/frontend/src/features/training/api/mappers.ts b/studio/frontend/src/features/training/api/mappers.ts
index 38e2a0b8e88..cfd1f0f8064 100644
--- a/studio/frontend/src/features/training/api/mappers.ts
+++ b/studio/frontend/src/features/training/api/mappers.ts
@@ -54,8 +54,17 @@ export function buildTrainingStartPayload(
config: TrainingConfigState,
hfToken: string | null,
): TrainingStartRequest {
- const isCpt = config.trainingMethod === "cpt";
- const adapterMethod = config.trainingMethod !== "full";
+ const isDecision = config.modelType === "decision";
+ const isClef = isDecision && config.decisionLayout === "clef";
+ const trainingMethod =
+ isDecision &&
+ config.trainingMethod !== "full" &&
+ !(isClef && config.trainingMethod === "qlora")
+ ? "lora"
+ : config.trainingMethod;
+ const isCpt = trainingMethod === "cpt";
+ const adapterMethod = trainingMethod !== "full";
+ const loraVariants = adapterMethod && !isDecision;
const _selectedModelLower = (config.selectedModel ?? "").toLowerCase();
// DeepSeek OCR ignores user-selected image size; do not send it.
const isDeepseekOcr =
@@ -72,7 +81,7 @@ export function buildTrainingStartPayload(
: [];
const s3Config = buildS3PayloadConfig(config);
const customFormatMapping: Record<string, unknown> | undefined =
- Object.keys(config.datasetManualMapping).length > 0
+ !isDecision && Object.keys(config.datasetManualMapping).length > 0
? { ...config.datasetManualMapping }
: undefined;
@@ -92,13 +101,14 @@ export function buildTrainingStartPayload(
return {
model_name: config.selectedModel ?? "",
project_name: (config.projectName || "").trim() || null,
- training_type: toBackendTrainingType(config.trainingMethod),
+ training_type: toBackendTrainingType(trainingMethod),
hf_token: hfToken,
model_known_cached: config.modelKnownCached,
model_local_path: config.modelKnownCached ? config.modelLocalPath : null,
model_format: config.modelFormat,
- load_in_4bit: trainingLoadsIn4Bit(config),
- max_seq_length: config.contextLength,
+ load_in_4bit: trainingLoadsIn4Bit({ ...config, trainingMethod }),
+ // Hidden for decision runs: Laya always trains at 1024 tokens, Clef at its recipe's length.
+ max_seq_length: isDecision && !isClef ? 1024 : config.contextLength,
vision_image_size:
config.isVisionModel && config.isDatasetImage === true && !isDeepseekOcr
? config.visionImageSize
@@ -114,7 +124,8 @@ export function buildTrainingStartPayload(
subset: hfDataset ? config.datasetSubset : null,
train_split: hfDataset ? config.datasetSplit : null,
eval_split: hfDataset ? config.datasetEvalSplit : null,
- dataset_streaming: hfDataset ? config.datasetStreaming : false,
+ dataset_streaming:
+ hfDataset && !isDecision ? config.datasetStreaming : false,
dataset_slice_start: parseSliceValue(config.datasetSliceStart),
dataset_slice_end: parseSliceValue(config.datasetSliceEnd),
local_datasets: localDatasets,
@@ -144,8 +155,12 @@ export function buildTrainingStartPayload(
// that. Guarded by tests/training-start-payload-grad-norm.test.ts.
max_grad_value: null,
random_seed: config.randomSeed,
- packing: isEmbedding ? false : config.packing,
- optim: config.optimizerType,
+ packing: isEmbedding || isDecision ? false : config.packing,
+ // Laya's recipe needs torch AdamW; Clef keeps its recipe's (8-bit) optimizer.
+ optim:
+ isDecision && config.decisionLayout !== "clef"
+ ? "adamw_torch"
+ : config.optimizerType,
lr_scheduler_type: config.lrSchedulerType,
use_lora: adapterMethod,
lora_r: config.loraRank,
@@ -153,19 +168,23 @@ export function buildTrainingStartPayload(
lora_dropout: config.loraDropout,
target_modules: adapterMethod ? config.targetModules : [],
gradient_checkpointing: config.gradientCheckpointing,
- use_rslora: adapterMethod && config.loraVariant === "rslora",
- use_loftq: adapterMethod && config.loraVariant === "loftq",
- use_dora: adapterMethod && config.loraVariant === "dora",
+ use_rslora: loraVariants && config.loraVariant === "rslora",
+ use_loftq: loraVariants && config.loraVariant === "loftq",
+ use_dora: loraVariants && config.loraVariant === "dora",
// CPT always trains on full sequences (no chat format masking)
train_on_completions:
- isEmbedding || isCpt || isRawText ? false : config.trainOnCompletions,
+ isEmbedding || isDecision || isCpt || isRawText
+ ? false
+ : config.trainOnCompletions,
finetune_vision_layers: config.finetuneVisionLayers,
finetune_language_layers: config.finetuneLanguageLayers,
finetune_attention_modules: config.finetuneAttentionModules,
finetune_mlp_modules: config.finetuneMLPModules,
is_dataset_image: isEmbedding ? false : !!config.isDatasetImage,
is_dataset_audio: isEmbedding ? false : config.isDatasetAudio,
- is_embedding: isEmbedding,
+ is_embedding: isEmbedding && !isDecision,
+ is_decision: isDecision,
+ model_subfolder: isDecision ? config.modelSubfolder : null,
enable_wandb: config.enableWandb,
wandb_token: config.enableWandb ? config.wandbToken.trim() || null : null,
wandb_project: config.enableWandb
diff --git a/studio/frontend/src/features/training/api/models-api.ts b/studio/frontend/src/features/training/api/models-api.ts
index a6ba9d52b55..42b9449bf81 100644
--- a/studio/frontend/src/features/training/api/models-api.ts
+++ b/studio/frontend/src/features/training/api/models-api.ts
@@ -67,19 +67,28 @@ export interface BackendModelConfig {
logging?: BackendLoggingDefaults;
}
+export interface DecisionCheckpoint {
+ name: string;
+ subfolder: string | null;
+ description: string;
+}
+
export interface ModelConfigResponse {
id: string;
model_name?: string | null;
config?: BackendModelConfig | null;
is_vision: boolean;
is_embedding?: boolean;
+ is_decision?: boolean;
+ decision_checkpoints?: DecisionCheckpoint[] | null;
+ decision_layout?: "laya" | "clef" | null;
is_audio: boolean;
// False when the repo's tokenizer_config.json was unreadable (gated, offline,
// upstream error), so is_audio false means unknown rather than "not audio".
audio_type_known?: boolean;
is_lora: boolean;
base_model?: string | null;
- model_type?: "text" | "vision" | "audio" | "embeddings" | null;
+ model_type?: "text" | "vision" | "audio" | "embeddings" | "decision" | null;
max_position_embeddings?: number | null;
model_size_bytes?: number | null;
}
diff --git a/studio/frontend/src/features/training/hooks/use-training-readiness.ts b/studio/frontend/src/features/training/hooks/use-training-readiness.ts
index 6128ef44ca3..cd0d1153064 100644
--- a/studio/frontend/src/features/training/hooks/use-training-readiness.ts
+++ b/studio/frontend/src/features/training/hooks/use-training-readiness.ts
@@ -2,6 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { usePlatformStore } from "@/config/env";
+import { useIsAccountOwner } from "@/features/auth";
import { useMemo } from "react";
import {
type StartValidationResult,
@@ -24,11 +25,12 @@ export interface TrainingReadiness {
configValidation: StartValidationResult;
}
-function deriveTrainingReadiness(
+export function deriveTrainingReadiness(
state: TrainingConfigState,
deviceType: string,
+ isOwner: boolean,
): TrainingReadiness {
- const configValidation = validateTrainingConfig(state, deviceType);
+ const configValidation = validateTrainingConfig(state, deviceType, isOwner);
const hasModel = !!state.selectedModel;
const hasDataset =
state.datasetSource === "upload"
@@ -38,6 +40,9 @@ function deriveTrainingReadiness(
: !!state.dataset;
const isLoadingModel = state.isLoadingModelDefaults || state.isCheckingVision;
const modelError = state.modelDefaultsError;
+ // Without its config a decision model has no recipe or checkpoint, so the run would train the wrong one.
+ const decisionConfigMissing =
+ state.modelType === "decision" && modelError !== null;
const isModelCapabilitiesSettled = hasModel && !isLoadingModel;
const isIncompatible =
isModelCapabilitiesSettled && hasIncompatibleTrainingModalities(state);
@@ -56,6 +61,7 @@ function deriveTrainingReadiness(
!isLoadingModel &&
!state.isCheckingDataset &&
!isIncompatible &&
+ !decisionConfigMissing &&
configValidation.ok,
isLoadingModel,
isCheckingDataset: state.isCheckingDataset,
@@ -86,7 +92,7 @@ function readinessEqual(
);
}
-function createTrainingReadinessSelector(deviceType: string) {
+function createTrainingReadinessSelector(deviceType: string, isOwner: boolean) {
let cachedReadiness: Readonly<TrainingReadiness> | null = null;
let cachedState: TrainingConfigState | null = null;
@@ -94,7 +100,7 @@ function createTrainingReadinessSelector(deviceType: string) {
if (state === cachedState && cachedReadiness) {
return cachedReadiness;
}
- const next = deriveTrainingReadiness(state, deviceType);
+ const next = deriveTrainingReadiness(state, deviceType, isOwner);
if (!(cachedReadiness && readinessEqual(cachedReadiness, next))) {
cachedReadiness = Object.freeze(next);
}
@@ -105,9 +111,10 @@ function createTrainingReadinessSelector(deviceType: string) {
export function useTrainingReadiness(): Readonly<TrainingReadiness> {
const deviceType = usePlatformStore((state) => state.deviceType);
+ const isOwner = useIsAccountOwner();
const selector = useMemo(
- () => createTrainingReadinessSelector(deviceType),
- [deviceType],
+ () => createTrainingReadinessSelector(deviceType, isOwner),
+ [deviceType, isOwner],
);
return useTrainingConfigStore(selector);
}
diff --git a/studio/frontend/src/features/training/index.ts b/studio/frontend/src/features/training/index.ts
index 2cf896e028b..cabf6f01ec1 100644
--- a/studio/frontend/src/features/training/index.ts
+++ b/studio/frontend/src/features/training/index.ts
@@ -51,7 +51,11 @@ export type {
TrainingConfigState,
} from "./types/config";
export { getModelConfig, listLocalModels } from "./api/models-api";
-export type { LocalModelInfo, ModelConfigResponse } from "./api/models-api";
+export type {
+ DecisionCheckpoint,
+ LocalModelInfo,
+ ModelConfigResponse,
+} from "./api/models-api";
export type {
TrainingPhase,
TrainingViewData,
diff --git a/studio/frontend/src/features/training/lib/decision-dataset.ts b/studio/frontend/src/features/training/lib/decision-dataset.ts
new file mode 100644
index 00000000000..48ab4db713e
--- /dev/null
+++ b/studio/frontend/src/features/training/lib/decision-dataset.ts
@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { DatasetFormatError } from "../api/datasets-api";
+
+const JSON_FILE = /\.jsonl?$/i;
+
+export function missingDecisionColumns(columns: readonly string[]): string[] {
+ const present = new Set(columns);
+ const missing = ["state", "questions"].filter(
+ (column) => !present.has(column),
+ );
+ if (!(present.has("gold") || present.has("answers"))) {
+ missing.push("gold");
+ }
+ return missing;
+}
+
+// The decision trainer parses uploaded JSON itself, so a failed format check must not block it.
+export async function checkDecisionDatasetColumns(
+ check: () => Promise<{ columns: readonly string[] } | null>,
+ uploadedFile: string | null,
+): Promise<string[] | null> {
+ let result: { columns: readonly string[] } | null;
+ try {
+ result = await check();
+ } catch (error) {
+ if (
+ error instanceof DatasetFormatError &&
+ uploadedFile !== null &&
+ JSON_FILE.test(uploadedFile)
+ ) {
+ return [];
+ }
+ throw error;
+ }
+ return result ? missingDecisionColumns(result.columns) : null;
+}
diff --git a/studio/frontend/src/features/training/lib/model-type-capabilities.ts b/studio/frontend/src/features/training/lib/model-type-capabilities.ts
index 7191c4a7507..3ba7c888b4a 100644
--- a/studio/frontend/src/features/training/lib/model-type-capabilities.ts
+++ b/studio/frontend/src/features/training/lib/model-type-capabilities.ts
@@ -5,6 +5,7 @@ import type { ModelType } from "@/types/training";
export interface ModelTypeCapabilityFlags {
isEmbedding?: boolean | null;
+ isDecision?: boolean | null;
isAudio?: boolean | null;
isVision?: boolean | null;
hasModelTypeSignal?: boolean;
@@ -12,9 +13,13 @@ export interface ModelTypeCapabilityFlags {
export function inferTrainingModelTypeFromFlags({
isEmbedding,
+ isDecision,
isAudio,
isVision,
}: ModelTypeCapabilityFlags): ModelType {
+ if (isDecision) {
+ return "decision";
+ }
if (isEmbedding) {
return "embeddings";
}
diff --git a/studio/frontend/src/features/training/lib/model-type-constraint.ts b/studio/frontend/src/features/training/lib/model-type-constraint.ts
index f62967dc3a8..2543385a1ed 100644
--- a/studio/frontend/src/features/training/lib/model-type-constraint.ts
+++ b/studio/frontend/src/features/training/lib/model-type-constraint.ts
@@ -14,6 +14,8 @@ export function trainingModelMatchesTypeConstraint(
switch (requiredType) {
case "embeddings":
return capabilities.isEmbedding === true;
+ case "decision":
+ return capabilities.isDecision === true;
case "audio":
return capabilities.isAudio === true;
case "vision":
@@ -21,6 +23,7 @@ export function trainingModelMatchesTypeConstraint(
case "text":
return !(
capabilities.isEmbedding ||
+ capabilities.isDecision ||
capabilities.isAudio ||
capabilities.isVision
);
diff --git a/studio/frontend/src/features/training/lib/model-type-inference.ts b/studio/frontend/src/features/training/lib/model-type-inference.ts
index 52192c641f2..b289d430b07 100644
--- a/studio/frontend/src/features/training/lib/model-type-inference.ts
+++ b/studio/frontend/src/features/training/lib/model-type-inference.ts
@@ -9,9 +9,14 @@ import {
import type { ModelTypeCapabilityFlags } from "./model-type-capabilities";
const TEXT_MODEL_TAGS = new Set(["text-generation"]);
+const DECISION_MODEL_TAGS = new Set(["laya"]);
export type TrainingModelTypeMetadata = TrainingModelModalityMetadata;
+function hasDecisionHint({ tags }: TrainingModelTypeMetadata): boolean {
+ return (tags ?? []).some((tag) => DECISION_MODEL_TAGS.has(tag.toLowerCase()));
+}
+
function hasEmbeddingHint({
tags,
pipelineTag,
@@ -37,12 +42,15 @@ export function trainingModelTypeFlagsFromMetadata(
): ModelTypeCapabilityFlags {
const capabilities = inferTrainingModelModalityFlags(metadata);
const isEmbedding = hasEmbeddingHint(metadata);
+ const isDecision = hasDecisionHint(metadata);
const hasModelTypeSignal =
+ isDecision ||
isEmbedding ||
capabilities.isAudio ||
capabilities.isVision ||
hasTextModelHint(metadata);
return {
+ isDecision: hasModelTypeSignal ? isDecision : undefined,
isEmbedding: hasModelTypeSignal ? isEmbedding : undefined,
isAudio: hasModelTypeSignal ? capabilities.isAudio : undefined,
isVision: hasModelTypeSignal ? capabilities.isVision : undefined,
diff --git a/studio/frontend/src/features/training/lib/start-fresh-training-run.ts b/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
index ae1fedf1b7b..8585ee0212d 100644
--- a/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
+++ b/studio/frontend/src/features/training/lib/start-fresh-training-run.ts
@@ -2,6 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { usePlatformStore } from "@/config/env";
+import { isAccountOwner } from "@/features/auth";
import { prepareHfTokenForUse } from "@/features/hf-auth";
import { getHfToken, useHfTokenStore } from "@/features/hub";
import { confirmRemoteCodeIfNeeded } from "@/features/security";
@@ -28,6 +29,7 @@ import {
createDatasetCacheUsabilityIdentity,
trainingDatasetCacheRejections,
} from "./dataset-cache-rejection";
+import { checkDecisionDatasetColumns } from "./decision-dataset";
import { shouldUseVisionDatasetCheck } from "./fresh-dataset-check";
import { isMissingLocalDatasetCacheError } from "./local-cache-errors";
import { isRawTextDatasetFormat } from "./training-methods";
@@ -260,6 +262,7 @@ export async function startFreshTrainingRun(): Promise<boolean> {
const validation = validateTrainingConfig(
attempt.config,
usePlatformStore.getState().deviceType,
+ isAccountOwner(),
);
if (!validation.ok) {
return attempt.cancel(translate(validation.errorKey));
@@ -359,6 +362,21 @@ async function prepareSelectedDataset(
}
const isVlm = shouldUseVisionDatasetCheck(attempt.config);
+ if (attempt.config.modelType === "decision") {
+ const missing = await checkDecisionDatasetColumns(
+ () => checkSelectedDataset(attempt, datasetName, hfToken, isVlm),
+ attempt.config.datasetSource === "upload" ? datasetName : null,
+ );
+ return (
+ missing !== null &&
+ (missing.length === 0 ||
+ attempt.cancel(
+ translate("studio.training.validation.decisionColumnsMissing", {
+ columns: missing.join(", "),
+ }),
+ ))
+ );
+ }
const check = await checkSelectedDataset(
attempt,
datasetName,
@@ -523,6 +541,7 @@ async function submitFreshTrainingRun(
const validation = validateTrainingConfig(
attempt.config,
usePlatformStore.getState().deviceType,
+ isAccountOwner(),
);
if (!validation.ok) {
return attempt.cancel(translate(validation.errorKey));
diff --git a/studio/frontend/src/features/training/lib/training-methods.ts b/studio/frontend/src/features/training/lib/training-methods.ts
index 6272246daaa..ea259dae7b1 100644
--- a/studio/frontend/src/features/training/lib/training-methods.ts
+++ b/studio/frontend/src/features/training/lib/training-methods.ts
@@ -50,7 +50,9 @@ export function isTrainingModelTypeSupportedOnDevice(
): boolean {
return (
deviceType !== "mac" ||
- (modelType !== "audio" && modelType !== "embeddings")
+ (modelType !== "audio" &&
+ modelType !== "embeddings" &&
+ modelType !== "decision")
);
}
diff --git a/studio/frontend/src/features/training/lib/validation.ts b/studio/frontend/src/features/training/lib/validation.ts
index 61b86a0c8b8..c5639ab031b 100644
--- a/studio/frontend/src/features/training/lib/validation.ts
+++ b/studio/frontend/src/features/training/lib/validation.ts
@@ -157,6 +157,7 @@ function validateDatasetSelection(
export function validateTrainingConfig(
config: TrainingConfigState,
deviceType?: string,
+ isOwner = true,
): StartValidationResult {
if (!config.selectedModel) {
return {
@@ -193,6 +194,12 @@ export function validateTrainingConfig(
errorKey: "studio.params.notSupportedAppleSilicon",
};
}
+ if (config.modelType === "decision" && !isOwner) {
+ return {
+ ok: false,
+ errorKey: "studio.training.validation.decisionOwnerOnly",
+ };
+ }
if (!Number.isFinite(config.learningRate) || config.learningRate <= 0) {
return {
diff --git a/studio/frontend/src/features/training/stores/training-config-persistence.ts b/studio/frontend/src/features/training/stores/training-config-persistence.ts
index 6879a3b736e..27ed53f7d0a 100644
--- a/studio/frontend/src/features/training/stores/training-config-persistence.ts
+++ b/studio/frontend/src/features/training/stores/training-config-persistence.ts
@@ -41,6 +41,8 @@ const NON_PERSISTED_STATE_KEYS: ReadonlySet<keyof TrainingConfigState> =
"manualDatasetOptionsValid",
"trainOnCompletionsDefaultPendingFor",
"maxPositionEmbeddings",
+ "decisionCheckpoints",
+ "decisionLayout",
"s3Config",
"wandbToken",
]);
@@ -366,6 +368,16 @@ function normalizeTrainingMethodProvenance(
};
}
+function normalizeSettingsBeforeDecision(
+ value: unknown,
+): TrainingConfigState["settingsBeforeDecision"] {
+ if (value === null || typeof value !== "object") return null;
+ const { trainingMethod, datasetStreaming } = value as Record<string, unknown>;
+ return isTrainingMethod(trainingMethod)
+ ? { trainingMethod, datasetStreaming: datasetStreaming === true }
+ : null;
+}
+
export function migrateTrainingConfig(
persisted: unknown,
version: number,
@@ -430,6 +442,9 @@ export function mergeTrainingConfig(
trainingMethod: isTrainingMethod(persistedState.trainingMethod)
? persistedState.trainingMethod
: current.trainingMethod,
+ settingsBeforeDecision: normalizeSettingsBeforeDecision(
+ persistedState.settingsBeforeDecision,
+ ),
};
return {
...merged,
diff --git a/studio/frontend/src/features/training/stores/training-config-policy.ts b/studio/frontend/src/features/training/stores/training-config-policy.ts
index 57e756df1e2..b40f6da211d 100644
--- a/studio/frontend/src/features/training/stores/training-config-policy.ts
+++ b/studio/frontend/src/features/training/stores/training-config-policy.ts
@@ -59,6 +59,10 @@ export const initialTrainingConfigState: TrainingConfigState = {
modelKnownCached: false,
modelLocalPath: null,
modelFormat: null,
+ modelSubfolder: null,
+ decisionCheckpoints: null,
+ decisionLayout: null,
+ settingsBeforeDecision: null,
projectName: "",
trainingMethod: "qlora",
trainingMethodProvenance: {
diff --git a/studio/frontend/src/features/training/stores/training-config-store.ts b/studio/frontend/src/features/training/stores/training-config-store.ts
index 445ebde7f5b..8882a5c1e65 100644
--- a/studio/frontend/src/features/training/stores/training-config-store.ts
+++ b/studio/frontend/src/features/training/stores/training-config-store.ts
@@ -3,6 +3,7 @@
import {
DEFAULT_HYPERPARAMS,
+ LR_DEFAULT_DECISION_FULL,
LR_DEFAULT_FULL,
LR_DEFAULT_LORA,
} from "@/config/training";
@@ -10,12 +11,12 @@ import { getHfToken } from "@/features/hub";
import { translate } from "@/i18n";
import { toast } from "@/lib/toast";
import { isAdapterMethod } from "@/types/training";
-import type { ModelType } from "@/types/training";
+import type { ModelType, TrainingMethod } from "@/types/training";
import { create } from "zustand";
import { persist } from "zustand/middleware";
import { DatasetFormatError, checkDatasetFormat } from "../api/datasets-api";
import { checkVisionModel, getModelConfig } from "../api/models-api";
-import type { BackendModelConfig } from "../api/models-api";
+import type { BackendModelConfig, DecisionCheckpoint } from "../api/models-api";
import { cacheReferenceMatchesSelection } from "../lib/cache-reference";
import {
createDatasetCacheUsabilityIdentity,
@@ -30,7 +31,11 @@ import { resolveDeletedLocalDatasetSelection } from "../lib/dataset-selection";
import { requiresExplicitCachedDatasetSplit } from "../lib/dataset-split-policy";
import { isMissingLocalDatasetCacheError } from "../lib/local-cache-errors";
import { mapBackendModelConfigToTrainingPatch } from "../lib/model-defaults";
-import { trainingConfigPatchTouchesModelDefaults } from "../lib/model-defaults-edit-policy";
+import {
+ MODEL_DEFAULT_STATE_KEYS,
+ type ModelDefaultsPatch,
+ trainingConfigPatchTouchesModelDefaults,
+} from "../lib/model-defaults-edit-policy";
import {
inferTrainingModelTypeFromFlags,
resolveTrainingModelType,
@@ -105,6 +110,58 @@ function canReapplyModelDefaults(modelName: string): boolean {
);
}
+const DEFAULT_DECISION_CHECKPOINT = "laya-multilingual";
+
+// evalSteps is left alone: it follows the chosen eval split, not the model.
+const GENERIC_MODEL_DEFAULTS = Object.fromEntries(
+ MODEL_DEFAULT_STATE_KEYS.filter((key) => key !== "evalSteps").map((key) => [
+ key,
+ DEFAULT_HYPERPARAMS[key],
+ ]),
+) as ModelDefaultsPatch;
+
+// No defaults could be loaded to replace the decision recipe, so fall back to the generic ones.
+function leaveDecisionWithoutDefaults(
+ state: TrainingConfigState,
+ method: TrainingMethod,
+): Partial<TrainingConfigState> {
+ const generic = {
+ ...state,
+ ...GENERIC_MODEL_DEFAULTS,
+ modelType: null,
+ trainingMethodProvenance: {
+ ...state.trainingMethodProvenance,
+ learningRateManuallySet: false,
+ modelAdapterLearningRate: null,
+ },
+ };
+ return {
+ ...GENERIC_MODEL_DEFAULTS,
+ ...buildTrainingMethodPatch(generic, method),
+ modelSubfolder: null,
+ decisionCheckpoints: null,
+ decisionLayout: null,
+ settingsBeforeDecision: null,
+ };
+}
+
+function resolveDecisionSubfolder(
+ checkpoints: DecisionCheckpoint[] | null,
+ current: string | null,
+ keepCurrent: boolean,
+): string | null {
+ if (!checkpoints || checkpoints.length === 0) {
+ return null;
+ }
+ if (keepCurrent && checkpoints.some((c) => c.subfolder === current)) {
+ return current;
+ }
+ const preferred =
+ checkpoints.find((c) => c.name === DEFAULT_DECISION_CHECKPOINT) ??
+ checkpoints[0];
+ return preferred.subfolder;
+}
+
// streamingCompatiblePatch can silently flip streaming-coupled fields, so toast when it does,
// matching setDatasetStreaming's "tell the user what changed" behavior.
function notifyStreamingCompat(patch: Partial<TrainingConfigState>): void {
@@ -155,7 +212,10 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
const loadAndApplyModelDefaults = (
modelName: string,
- options?: { applyTrainingDefaults?: boolean },
+ options?: {
+ applyTrainingDefaults?: boolean;
+ keepModelSubfolder?: boolean;
+ },
) => {
const applyTrainingDefaults = options?.applyTrainingDefaults ?? true;
_modelConfigController?.abort();
@@ -222,7 +282,56 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
if (controller.signal.aborted) return;
if (!requestMatchesSelection()) return;
- const shouldApplyTrainingDefaults = canApplyTrainingDefaults();
+ const isDecision = modelDetails.model_type === "decision";
+ const settingsBeforeDecision = get().settingsBeforeDecision;
+ // Moving to or from a decision model replaces the whole recipe, even over edits made during the load.
+ const recipeChanged = isDecision
+ ? !(
+ get().modelDefaultsAppliedFor === modelName &&
+ get().modelType === "decision"
+ )
+ : settingsBeforeDecision !== null;
+ const shouldApplyTrainingDefaults =
+ recipeChanged || canApplyTrainingDefaults();
+ if (isDecision) {
+ const method = get().trainingMethod;
+ const methodWasEdited =
+ _trainingMethodEditGeneration !== trainingMethodEditGeneration;
+ // Clef has a Qwen3.5 backbone, so it takes QLoRA like a chat model; Laya is 16-bit only.
+ const isClef = modelDetails.decision_layout === "clef";
+ const keepMethod =
+ method === "lora" ||
+ (isClef && method === "qlora") ||
+ (method === "full" && (!recipeChanged || methodWasEdited));
+ set({
+ ...(keepMethod
+ ? {}
+ : buildTrainingMethodPatch(get(), isClef ? "qlora" : "lora")),
+ settingsBeforeDecision: settingsBeforeDecision ?? {
+ trainingMethod: method,
+ datasetStreaming: get().datasetStreaming,
+ },
+ });
+ } else if (settingsBeforeDecision) {
+ const restoredMethod = settingsBeforeDecision.trainingMethod;
+ set({
+ ...(get().trainingMethod !== restoredMethod
+ ? buildTrainingMethodPatch(
+ {
+ ...get(),
+ modelType: null,
+ trainingMethodProvenance: {
+ ...get().trainingMethodProvenance,
+ modelAdapterLearningRate: null,
+ },
+ },
+ restoredMethod,
+ )
+ : {}),
+ settingsBeforeDecision: null,
+ });
+ }
+
const shouldApplyCptTargetDefaults =
applyTrainingDefaults &&
!shouldApplyTrainingDefaults &&
@@ -276,7 +385,9 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
// YAML LRs are tuned for adapters (LoRA/QLoRA); full fine-tune uses its own default.
if (modelConfigHasLR && !isAdapterMethod(get().trainingMethod)) {
- modelDefaultsPatch.learningRate = LR_DEFAULT_FULL;
+ modelDefaultsPatch.learningRate = isDecision
+ ? LR_DEFAULT_DECISION_FULL
+ : LR_DEFAULT_FULL;
}
// Vision model + known image dataset: force trainOnCompletions off.
@@ -298,12 +409,22 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
const inferredModelType = resolveTrainingModelType({
modelType: modelDetails.model_type,
isEmbedding,
+ isDecision,
isVision: modelDetails.is_vision,
isAudio: modelDetails.is_audio,
});
+ const decisionCheckpoints = isDecision
+ ? (modelDetails.decision_checkpoints ?? null)
+ : null;
+ const modelSubfolder = resolveDecisionSubfolder(
+ decisionCheckpoints,
+ get().modelSubfolder,
+ !recipeChanged || options?.keepModelSubfolder === true,
+ );
const modelSizeBytes = modelDetails.model_size_bytes;
const autoSelectionPromise =
+ !isDecision &&
shouldApplyTrainingDefaults &&
typeof modelSizeBytes === "number" &&
modelSizeBytes > 0 &&
@@ -416,11 +537,34 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
: {}),
};
+ const nextStreamingState = {
+ ...get(),
+ ...patch,
+ ...cptOverrides,
+ ...deferredCompletionDefault,
+ datasetStreaming: true,
+ };
+ const restoreStreaming =
+ !isDecision &&
+ settingsBeforeDecision?.datasetStreaming === true &&
+ nextStreamingState.datasetSource === "huggingface" &&
+ nextStreamingState.maxSteps > 0;
+
set({
...patch,
...cptOverrides,
...cptTargetOverrides,
...deferredCompletionDefault,
+ ...(isDecision ? { datasetStreaming: false } : {}),
+ ...(restoreStreaming
+ ? {
+ ...streamingCompatiblePatch(nextStreamingState),
+ datasetStreaming: true,
+ isDatasetImage: null,
+ isDatasetAudio: false,
+ datasetCheckFailed: false,
+ }
+ : {}),
...(shouldApplyTrainingDefaults
? {
trainingMethodProvenance: {
@@ -447,6 +591,11 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
}
: advancedSettingsBaseline,
modelType: inferredModelType,
+ modelSubfolder,
+ decisionCheckpoints,
+ decisionLayout: isDecision
+ ? (modelDetails.decision_layout ?? "laya")
+ : null,
isVisionModel: modelDetails.is_vision,
isEmbeddingModel: isEmbedding,
isAudioModel: isAudio,
@@ -461,6 +610,10 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
maxPositionEmbeddings:
modelDetails.max_position_embeddings ?? null,
});
+ if (restoreStreaming) {
+ trainingDatasetCacheRejections.reset(get().dataset);
+ recheckSelectedDatasetForStreamingMode(true);
+ }
if (autoSelectionPromise) {
void autoSelectionPromise.then((method) => {
@@ -499,6 +652,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
if (controller.signal.aborted) return;
if (!requestMatchesSelection()) return;
+ const { settingsBeforeDecision } = get();
set({
isLoadingModelDefaults: false,
modelDefaultsError:
@@ -508,6 +662,12 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
...(canApplyTrainingDefaults()
? { visionImageSize: DEFAULT_HYPERPARAMS.visionImageSize }
: {}),
+ ...(settingsBeforeDecision && get().modelType !== "decision"
+ ? leaveDecisionWithoutDefaults(
+ get(),
+ settingsBeforeDecision.trainingMethod,
+ )
+ : {}),
});
if (preferLocalCache) {
@@ -525,6 +685,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
set({
modelType: inferTrainingModelTypeFromFlags({
isEmbedding: state.isEmbeddingModel,
+ isDecision: state.modelType === "decision",
isAudio: state.isAudioModel,
isVision,
}),
@@ -1049,6 +1210,7 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
canReapplyModelDefaults(state.selectedModel),
});
},
+ setModelSubfolder: (modelSubfolder) => setUserEdit({ modelSubfolder }),
setProjectName: (projectName) => setUserEdit({ projectName }),
setTrainingMethod: (trainingMethod) => {
_trainingMethodEditGeneration += 1;
@@ -1435,7 +1597,9 @@ export const useTrainingConfigStore = create<TrainingConfigStore>()(
advancedSettingsBaseline: null,
visionImageSize: DEFAULT_HYPERPARAMS.visionImageSize,
});
- loadAndApplyModelDefaults(selectedModel);
+ loadAndApplyModelDefaults(selectedModel, {
+ keepModelSubfolder: true,
+ });
},
applyConfigPatch: (config: BackendModelConfig) => {
const patch = mapBackendModelConfigToTrainingPatch(config);
diff --git a/studio/frontend/src/features/training/stores/training-method-transition.ts b/studio/frontend/src/features/training/stores/training-method-transition.ts
index ae4c5e472fa..e281919f559 100644
--- a/studio/frontend/src/features/training/stores/training-method-transition.ts
+++ b/studio/frontend/src/features/training/stores/training-method-transition.ts
@@ -5,6 +5,7 @@ import {
CPT_LORA_HYPERPARAMS,
DEFAULT_HYPERPARAMS,
LR_DEFAULT_CPT,
+ LR_DEFAULT_DECISION_FULL,
LR_DEFAULT_FULL,
LR_DEFAULT_LORA,
TARGET_MODULES,
@@ -70,6 +71,7 @@ function resolveTrainingMethodLearningRate(
nextMethod: TrainingMethod,
learningRateManuallySet: boolean,
modelAdapterLearningRate: number | null,
+ isDecision: boolean,
): number | undefined {
if (learningRateManuallySet) {
return undefined;
@@ -88,9 +90,10 @@ function resolveTrainingMethodLearningRate(
if (wasAdapter && nowAdapter) {
return undefined;
}
- return nowAdapter
- ? (modelAdapterLearningRate ?? LR_DEFAULT_LORA)
- : LR_DEFAULT_FULL;
+ if (nowAdapter) {
+ return modelAdapterLearningRate ?? LR_DEFAULT_LORA;
+ }
+ return isDecision ? LR_DEFAULT_DECISION_FULL : LR_DEFAULT_FULL;
}
// Re-checked at exit: modality or streaming learned inside CPT still vetoes a saved true.
@@ -127,6 +130,7 @@ export function buildTrainingMethodPatch(
| "datasetStreaming"
| "selectedModel"
| "modelDefaultsAppliedFor"
+ | "modelType"
| "isEmbeddingModel"
| "isVisionModel"
| "isAudioModel"
@@ -179,6 +183,7 @@ export function buildTrainingMethodPatch(
nextMethod,
provenance.learningRateManuallySet,
provenance.modelAdapterLearningRate,
+ state.modelType === "decision",
);
if (learningRate !== undefined) {
patch.learningRate = learningRate;
diff --git a/studio/frontend/src/features/training/types/api.ts b/studio/frontend/src/features/training/types/api.ts
index 573cf68945f..2781d21660d 100644
--- a/studio/frontend/src/features/training/types/api.ts
+++ b/studio/frontend/src/features/training/types/api.ts
@@ -72,6 +72,8 @@ export interface TrainingStartRequest {
is_dataset_image: boolean;
is_dataset_audio: boolean;
is_embedding: boolean;
+ is_decision: boolean;
+ model_subfolder: string | null;
enable_wandb: boolean;
wandb_token: string | null;
wandb_project: string | null;
diff --git a/studio/frontend/src/features/training/types/config.ts b/studio/frontend/src/features/training/types/config.ts
index 21f6f150cc5..d581cd37736 100644
--- a/studio/frontend/src/features/training/types/config.ts
+++ b/studio/frontend/src/features/training/types/config.ts
@@ -10,7 +10,7 @@ import type {
S3Config,
TrainingMethod,
} from "@/types/training";
-import type { BackendModelConfig } from "../api/models-api";
+import type { BackendModelConfig, DecisionCheckpoint } from "../api/models-api";
export type LoraVariant = "lora" | "rslora" | "loftq" | "dora";
@@ -66,6 +66,14 @@ export interface TrainingConfigState {
modelKnownCached: boolean;
modelLocalPath: string | null;
modelFormat: ModelInventoryFormat | null;
+ modelSubfolder: string | null;
+ decisionCheckpoints: DecisionCheckpoint[] | null;
+ /** "clef" for Cloudflare Clef (Qwen3.5 backbone, QLoRA allowed), "laya" otherwise. */
+ decisionLayout: "laya" | "clef" | null;
+ settingsBeforeDecision: {
+ trainingMethod: TrainingMethod;
+ datasetStreaming: boolean;
+ } | null;
projectName: string;
trainingMethod: TrainingMethod;
trainingMethodProvenance: TrainingMethodProvenance;
@@ -193,6 +201,7 @@ export interface TrainingConfigActions {
dataset: string,
localPath: string | null,
) => void;
+ setModelSubfolder: (subfolder: string | null) => void;
setProjectName: (value: string) => void;
ensureModelDefaultsLoaded: () => void;
ensureDatasetChecked: () => void;
diff --git a/studio/frontend/src/features/training/types/runtime.ts b/studio/frontend/src/features/training/types/runtime.ts
index 35a8c62f51e..81bc0e68891 100644
--- a/studio/frontend/src/features/training/types/runtime.ts
+++ b/studio/frontend/src/features/training/types/runtime.ts
@@ -183,6 +183,7 @@ export interface TrainingViewData {
modelName: string;
projectName: string | null;
trainingMethod: string;
+ isDecision?: boolean;
lossHistory: TrainingSeriesPoint[];
lrHistory: TrainingSeriesPoint[];
diff --git a/studio/frontend/src/i18n/locales/ar.ts b/studio/frontend/src/i18n/locales/ar.ts
index 8cf21d32b26..cb51e138e24 100644
--- a/studio/frontend/src/i18n/locales/ar.ts
+++ b/studio/frontend/src/i18n/locales/ar.ts
@@ -2736,6 +2736,8 @@ export const ar = {
modelMultilingual: "متعدد اللغات",
modelEnglish: "إنجليزي",
modelTypedDecisions: "قرارات مُصنَّفة",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "موصى به",
device: "التشغيل على",
deviceDescription: "وحدة GPU أسرع في الإجابة، لكنها تحتفظ بذاكرتها محجوزة حتى إعادة التشغيل.",
@@ -2745,11 +2747,13 @@ export const ar = {
notDownloaded: "غير مُنزَّل · {size}",
downloading: "جارٍ التنزيل…",
downloaded: "مُنزَّل · يُحمَّل عند أول طلب",
+ ready: "جاهز · يُحمَّل عند أول طلب",
installing: "جارٍ التثبيت…",
loading: "جارٍ التحميل…",
loadedOn: "مُحمَّل على {device}",
download: "تنزيل",
downloadConfirmTitle: "هل تريد تنزيل Laya {model}؟",
+ downloadConfirmTitleModel: "هل تريد تنزيل {model}؟",
downloadConfirmBody:
"تحتاج واجهة API للقرارات إلى هذا النموذج للرد على الطلبات. حجمه نحو {size}، ويُنزَّل مرة واحدة إلى ذاكرة Hugging Face المؤقتة.",
unload: "إلغاء التحميل",
@@ -2875,6 +2879,9 @@ export const ar = {
datasetLabel: "مجموعة البيانات",
modelTooltip: "النموذج الأساسي الذي تريد ضبطه.",
methodTooltip: "طريقة تدريب النموذج. يحدّث LoRA وQLoRA محوّلات صغيرة بدلاً من جميع الأوزان.",
+ checkpointLabel: "نقطة التحقق",
+ checkpointTooltip:
+ "نقطة تحقق Laya التي سيتم ضبطها. يناسب الإصدار متعدد اللغات معظم مجموعات البيانات.",
datasetTooltip: "بيانات التدريب المستخدمة لضبط النموذج.",
hfTokenDescription:
"مطلوب للنماذج ومجموعات البيانات المقيّدة أو الخاصة.",
@@ -3345,6 +3352,9 @@ export const ar = {
learningRatePositive: "أدخل معدل تعلم أكبر من صفر.",
embeddingLearningRateRange:
"أدخل معدل تعلم تضمين أكبر من 0 وأقل من 1.",
+ decisionColumnsMissing:
+ "تحتاج نماذج القرارات إلى الأعمدة state وquestions وgold (أو answers). الأعمدة الناقصة: {columns}.",
+ decisionOwnerOnly: "يمكن لمالك Studio فقط ضبط نماذج القرارات.",
hfDatasetRequired: "اختر مجموعة بيانات Hugging Face أولًا.",
hfDatasetSplitRequired: "اختر قسم التدريب أو أدخله أولًا.",
localDatasetRequired: "اختر مجموعة بيانات محلية أولًا.",
@@ -3489,6 +3499,9 @@ export const ar = {
title: "تقدم التدريب",
liveMetrics: "مقاييس التدريب المباشرة",
exportGguf: "التصدير إلى GGUF",
+ useInDecisionApi: "استخدام في واجهة القرارات البرمجية",
+ decisionApiEnabled: "تستخدم واجهة القرارات البرمجية الآن {name}.",
+ decisionApiFailed: "تعذّر تبديل واجهة القرارات البرمجية إلى هذا النموذج.",
openConfig: "فتح تكوين التدريب",
configLabel: "تكوين التدريب",
hyperparams: "المعلمات الفائقة",
diff --git a/studio/frontend/src/i18n/locales/de.ts b/studio/frontend/src/i18n/locales/de.ts
index 6b64a71bbce..59e0b14f239 100644
--- a/studio/frontend/src/i18n/locales/de.ts
+++ b/studio/frontend/src/i18n/locales/de.ts
@@ -2780,6 +2780,8 @@ export const de = {
modelMultilingual: "Multilingual",
modelEnglish: "Englisch",
modelTypedDecisions: "Typisierte Entscheidungen",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Empfohlen",
device: "Ausführen auf",
deviceDescription: "Die GPU antwortet schneller, hält ihren Speicher aber bis zum Neustart reserviert.",
@@ -2789,11 +2791,13 @@ export const de = {
notDownloaded: "Nicht heruntergeladen · {size}",
downloading: "Wird heruntergeladen…",
downloaded: "Heruntergeladen · wird bei der ersten Anfrage geladen",
+ ready: "Bereit · wird bei der ersten Anfrage geladen",
installing: "Wird installiert…",
loading: "Wird geladen…",
loadedOn: "Geladen auf {device}",
download: "Herunterladen",
downloadConfirmTitle: "Laya {model} herunterladen?",
+ downloadConfirmTitleModel: "{model} herunterladen?",
downloadConfirmBody:
"Die Entscheidungs-API braucht dieses Modell, um Anfragen zu beantworten. Etwa {size}, einmalig in deinen Hugging-Face-Cache geladen.",
unload: "Entladen",
@@ -2922,6 +2926,9 @@ export const de = {
datasetLabel: "Datensatz",
modelTooltip: "Das Basismodell, das du feinabstimmen möchtest.",
methodTooltip: "Wie das Modell trainiert wird. LoRA und QLoRA aktualisieren kleine Adapter statt aller Gewichte.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "Der Laya-Checkpoint, der feinabgestimmt wird. Multilingual passt zu den meisten Datensätzen.",
datasetTooltip: "Die Trainingsdaten für die Feinabstimmung des Modells.",
hfTokenDescription:
"Erforderlich für zugriffsbeschränkte oder private Modelle und Datensätze.",
@@ -3404,6 +3411,10 @@ export const de = {
learningRatePositive: "Geben Sie eine Lernrate größer als null ein.",
embeddingLearningRateRange:
"Geben Sie eine Embedding-Lernrate größer als 0 und kleiner als 1 ein.",
+ decisionColumnsMissing:
+ "Entscheidungsmodelle brauchen die Spalten state, questions und gold (oder answers). Es fehlen: {columns}.",
+ decisionOwnerOnly:
+ "Nur der Studio-Inhaber kann Entscheidungsmodelle feinabstimmen.",
hfDatasetRequired:
"Wählen Sie zuerst einen Hugging Face-Datensatz aus.",
hfDatasetSplitRequired:
@@ -3557,6 +3568,10 @@ export const de = {
title: "Trainingsfortschritt",
liveMetrics: "Live-Trainingsmetriken",
exportGguf: "Nach GGUF exportieren",
+ useInDecisionApi: "In der Entscheidungs-API verwenden",
+ decisionApiEnabled: "Die Entscheidungs-API verwendet jetzt {name}.",
+ decisionApiFailed:
+ "Die Entscheidungs-API konnte nicht auf dieses Modell umgestellt werden.",
openConfig: "Trainingskonfiguration öffnen",
configLabel: "Trainingskonfiguration",
hyperparams: "Hyperparameter",
diff --git a/studio/frontend/src/i18n/locales/en.ts b/studio/frontend/src/i18n/locales/en.ts
index 0b7f1b33fdc..a3bbcb8eae1 100644
--- a/studio/frontend/src/i18n/locales/en.ts
+++ b/studio/frontend/src/i18n/locales/en.ts
@@ -2771,6 +2771,8 @@ export const en = {
modelMultilingual: "Multilingual",
modelEnglish: "English",
modelTypedDecisions: "Typed decisions",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Recommended",
device: "Run on",
deviceDescription: "GPU answers faster, but keeps its memory reserved until restart.",
@@ -2780,11 +2782,13 @@ export const en = {
notDownloaded: "Not downloaded · {size}",
downloading: "Downloading…",
downloaded: "Downloaded · loads on first request",
+ ready: "Ready · loads on first request",
installing: "Installing…",
loading: "Loading…",
loadedOn: "Loaded on {device}",
download: "Download",
downloadConfirmTitle: "Download Laya {model}?",
+ downloadConfirmTitleModel: "Download {model}?",
downloadConfirmBody:
"The Decision API needs this model to answer requests. About {size}, fetched once into your Hugging Face cache.",
unload: "Unload",
@@ -2908,6 +2912,9 @@ export const en = {
methodLabel: "Method",
methodTooltip:
"How the model is trained. LoRA and QLoRA update small adapters instead of every weight.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "The Laya checkpoint to fine-tune. Multilingual suits most datasets.",
datasetLabel: "Dataset",
datasetTooltip: "The training data used to fine-tune the model.",
hfTokenDescription: "Required for gated or private models and datasets.",
@@ -3354,6 +3361,10 @@ export const en = {
learningRatePositive: "Enter a learning rate greater than zero.",
embeddingLearningRateRange:
"Enter an embedding learning rate greater than 0 and less than 1.",
+ decisionColumnsMissing:
+ "Decision models need state, questions and gold (or answers) columns. Missing: {columns}.",
+ decisionOwnerOnly:
+ "Only the Studio owner can fine-tune decision models.",
hfDatasetRequired: "Select a Hugging Face dataset first.",
hfDatasetSplitRequired: "Select or enter a train split first.",
localDatasetRequired: "Select a local dataset first.",
@@ -3513,6 +3524,9 @@ export const en = {
title: "Training Progress",
liveMetrics: "Live training metrics",
exportGguf: "Export to GGUF",
+ useInDecisionApi: "Use in Decision API",
+ decisionApiEnabled: "The Decision API now serves {name}.",
+ decisionApiFailed: "Couldn't switch the Decision API to this model.",
openConfig: "Open training config",
configLabel: "Training Config",
hyperparams: "Hyperparams",
diff --git a/studio/frontend/src/i18n/locales/es.ts b/studio/frontend/src/i18n/locales/es.ts
index ad4ae18c2ae..e4d69670c73 100644
--- a/studio/frontend/src/i18n/locales/es.ts
+++ b/studio/frontend/src/i18n/locales/es.ts
@@ -2773,6 +2773,8 @@ export const es = {
modelMultilingual: "Multilingüe",
modelEnglish: "Inglés",
modelTypedDecisions: "Decisiones tipadas",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Recomendado",
device: "Ejecutar en",
deviceDescription: "La GPU responde más rápido, pero mantiene su memoria reservada hasta reiniciar.",
@@ -2782,11 +2784,13 @@ export const es = {
notDownloaded: "No descargado · {size}",
downloading: "Descargando…",
downloaded: "Descargado · se carga con la primera solicitud",
+ ready: "Listo · se carga con la primera solicitud",
installing: "Instalando…",
loading: "Cargando…",
loadedOn: "Cargado en {device}",
download: "Descargar",
downloadConfirmTitle: "¿Descargar Laya {model}?",
+ downloadConfirmTitleModel: "¿Descargar {model}?",
downloadConfirmBody:
"La API de decisiones necesita este modelo para responder solicitudes. Unos {size}, se descarga una vez en tu caché de Hugging Face.",
unload: "Descargar de memoria",
@@ -2916,6 +2920,9 @@ export const es = {
datasetLabel: "Conjunto de datos",
modelTooltip: "El modelo base que quieres ajustar.",
methodTooltip: "Cómo se entrena el modelo. LoRA y QLoRA actualizan adaptadores pequeños en lugar de todos los pesos.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "El checkpoint de Laya que se ajustará. Multilingüe sirve para la mayoría de los conjuntos de datos.",
datasetTooltip: "Los datos de entrenamiento usados para ajustar el modelo.",
hfTokenDescription:
"Necesario para modelos y conjuntos de datos restringidos o privados.",
@@ -3399,6 +3406,10 @@ export const es = {
learningRatePositive: "Introduce una tasa de aprendizaje mayor que cero.",
embeddingLearningRateRange:
"Introduce una tasa de aprendizaje de embeddings mayor que 0 y menor que 1.",
+ decisionColumnsMissing:
+ "Los modelos de decisión necesitan las columnas state, questions y gold (o answers). Faltan: {columns}.",
+ decisionOwnerOnly:
+ "Solo el propietario de Studio puede ajustar modelos de decisión.",
hfDatasetRequired:
"Selecciona primero un conjunto de datos de Hugging Face.",
hfDatasetSplitRequired:
@@ -3554,6 +3565,10 @@ export const es = {
title: "Progreso del entrenamiento",
liveMetrics: "Métricas de entrenamiento en vivo",
exportGguf: "Exportar a GGUF",
+ useInDecisionApi: "Usar en la API de decisiones",
+ decisionApiEnabled: "La API de decisiones ahora usa {name}.",
+ decisionApiFailed:
+ "No se pudo cambiar la API de decisiones a este modelo.",
openConfig: "Abrir configuración de entrenamiento",
configLabel: "Configuración de entrenamiento",
hyperparams: "Hiperparámetros",
diff --git a/studio/frontend/src/i18n/locales/fr.ts b/studio/frontend/src/i18n/locales/fr.ts
index 4b1a5fba9d9..48541fa2648 100644
--- a/studio/frontend/src/i18n/locales/fr.ts
+++ b/studio/frontend/src/i18n/locales/fr.ts
@@ -2781,6 +2781,8 @@ export const fr = {
modelMultilingual: "Multilingue",
modelEnglish: "Anglais",
modelTypedDecisions: "Décisions typées",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Recommandé",
device: "Exécuter sur",
deviceDescription: "Le GPU répond plus vite, mais garde sa mémoire réservée jusqu'au redémarrage.",
@@ -2790,11 +2792,13 @@ export const fr = {
notDownloaded: "Non téléchargé · {size}",
downloading: "Téléchargement…",
downloaded: "Téléchargé · chargé à la première requête",
+ ready: "Prêt · chargé à la première requête",
installing: "Installation…",
loading: "Chargement…",
loadedOn: "Chargé sur {device}",
download: "Télécharger",
downloadConfirmTitle: "Télécharger Laya {model} ?",
+ downloadConfirmTitleModel: "Télécharger {model} ?",
downloadConfirmBody:
"L'API de décision a besoin de ce modèle pour répondre aux requêtes. Environ {size}, téléchargé une seule fois dans votre cache Hugging Face.",
unload: "Décharger",
@@ -2926,6 +2930,9 @@ export const fr = {
datasetLabel: "Jeu de données",
modelTooltip: "Le modèle de base que vous souhaitez affiner.",
methodTooltip: "Comment le modèle est entraîné. LoRA et QLoRA mettent à jour de petits adaptateurs au lieu de tous les poids.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "Le checkpoint Laya à affiner. Multilingue convient à la plupart des jeux de données.",
datasetTooltip: "Les données d'entraînement utilisées pour affiner le modèle.",
hfTokenDescription:
"Nécessaire pour les modèles et jeux de données restreints ou privés.",
@@ -3414,6 +3421,10 @@ export const fr = {
learningRatePositive: "Saisissez un taux d'apprentissage supérieur à zéro.",
embeddingLearningRateRange:
"Saisissez un taux d'apprentissage des embeddings supérieur à 0 et inférieur à 1.",
+ decisionColumnsMissing:
+ "Les modèles de décision ont besoin des colonnes state, questions et gold (ou answers). Colonnes manquantes : {columns}.",
+ decisionOwnerOnly:
+ "Seul le propriétaire de Studio peut affiner des modèles de décision.",
hfDatasetRequired:
"Sélectionnez d'abord un jeu de données Hugging Face.",
hfDatasetSplitRequired:
@@ -3568,6 +3579,10 @@ export const fr = {
title: "Progression de l'entraînement",
liveMetrics: "Métriques d'entraînement en direct",
exportGguf: "Exporter en GGUF",
+ useInDecisionApi: "Utiliser dans l'API de décision",
+ decisionApiEnabled: "L'API de décision utilise maintenant {name}.",
+ decisionApiFailed:
+ "Impossible de passer l'API de décision sur ce modèle.",
openConfig: "Ouvrir la configuration d'entraînement",
configLabel: "Configuration d'entraînement",
hyperparams: "Hyperparamètres",
diff --git a/studio/frontend/src/i18n/locales/hi.ts b/studio/frontend/src/i18n/locales/hi.ts
index 61acd66c468..d6b699e4422 100644
--- a/studio/frontend/src/i18n/locales/hi.ts
+++ b/studio/frontend/src/i18n/locales/hi.ts
@@ -2742,6 +2742,8 @@ export const hi = {
modelMultilingual: "बहुभाषी",
modelEnglish: "अंग्रेज़ी",
modelTypedDecisions: "टाइप्ड निर्णय",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "सुझाया गया",
device: "यहाँ चलाएँ",
deviceDescription: "GPU तेज़ जवाब देता है, लेकिन रीस्टार्ट होने तक अपनी मेमोरी आरक्षित रखता है।",
@@ -2751,11 +2753,13 @@ export const hi = {
notDownloaded: "डाउनलोड नहीं हुआ · {size}",
downloading: "डाउनलोड हो रहा है…",
downloaded: "डाउनलोड हो गया · पहले अनुरोध पर लोड होगा",
+ ready: "तैयार · पहले अनुरोध पर लोड होगा",
installing: "इंस्टॉल हो रहा है…",
loading: "लोड हो रहा है…",
loadedOn: "{device} पर लोड हुआ",
download: "डाउनलोड करें",
downloadConfirmTitle: "Laya {model} डाउनलोड करें?",
+ downloadConfirmTitleModel: "{model} डाउनलोड करें?",
downloadConfirmBody:
"Decision API को अनुरोधों का जवाब देने के लिए इस मॉडल की ज़रूरत है। लगभग {size}, आपके Hugging Face कैश में एक बार डाउनलोड होता है।",
unload: "अनलोड करें",
@@ -2883,6 +2887,9 @@ export const hi = {
datasetLabel: "डेटासेट",
modelTooltip: "वह बेस मॉडल जिसे आप फ़ाइन-ट्यून करना चाहते हैं।",
methodTooltip: "मॉडल को कैसे ट्रेन किया जाता है। LoRA और QLoRA सभी वेट्स के बजाय छोटे अडैप्टर अपडेट करते हैं।",
+ checkpointLabel: "चेकपॉइंट",
+ checkpointTooltip:
+ "वह Laya चेकपॉइंट जिसे फ़ाइन-ट्यून करना है। ज़्यादातर डेटासेट के लिए बहुभाषी ठीक रहता है।",
datasetTooltip: "मॉडल को फ़ाइन-ट्यून करने के लिए उपयोग किया जाने वाला ट्रेनिंग डेटा।",
hfTokenDescription:
"गेटेड या निजी मॉडल और डेटासेट के लिए आवश्यक।",
@@ -3352,6 +3359,10 @@ export const hi = {
learningRatePositive: "शून्य से अधिक लर्निंग रेट दर्ज करें।",
embeddingLearningRateRange:
"0 से अधिक और 1 से कम एम्बेडिंग लर्निंग रेट दर्ज करें।",
+ decisionColumnsMissing:
+ "निर्णय मॉडल को state, questions और gold (या answers) कॉलम चाहिए। गायब कॉलम: {columns}।",
+ decisionOwnerOnly:
+ "केवल Studio स्वामी ही निर्णय मॉडल को फ़ाइन-ट्यून कर सकते हैं।",
hfDatasetRequired: "पहले Hugging Face डेटासेट चुनें।",
hfDatasetSplitRequired: "पहले ट्रेनिंग स्प्लिट चुनें या दर्ज करें।",
localDatasetRequired: "पहले स्थानीय डेटासेट चुनें।",
@@ -3496,6 +3507,9 @@ export const hi = {
title: "ट्रेनिंग प्रगति",
liveMetrics: "लाइव ट्रेनिंग मेट्रिक्स",
exportGguf: "GGUF में एक्सपोर्ट करें",
+ useInDecisionApi: "निर्णय API में इस्तेमाल करें",
+ decisionApiEnabled: "निर्णय API अब {name} इस्तेमाल करता है।",
+ decisionApiFailed: "निर्णय API को इस मॉडल पर नहीं बदला जा सका।",
openConfig: "ट्रेनिंग कॉन्फ़िग खोलें",
configLabel: "ट्रेनिंग कॉन्फ़िग",
hyperparams: "हाइपरपैराम्स",
diff --git a/studio/frontend/src/i18n/locales/it.ts b/studio/frontend/src/i18n/locales/it.ts
index 85a94be5d0f..8be0b3c6944 100644
--- a/studio/frontend/src/i18n/locales/it.ts
+++ b/studio/frontend/src/i18n/locales/it.ts
@@ -2738,6 +2738,8 @@ export const it = {
modelMultilingual: "Multilingue",
modelEnglish: "Inglese",
modelTypedDecisions: "Decisioni tipizzate",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Consigliato",
device: "Esegui su",
deviceDescription: "La GPU risponde più velocemente, ma tiene la memoria riservata fino al riavvio.",
@@ -2747,11 +2749,13 @@ export const it = {
notDownloaded: "Non scaricato · {size}",
downloading: "Download in corso…",
downloaded: "Scaricato · si carica alla prima richiesta",
+ ready: "Pronto · si carica alla prima richiesta",
installing: "Installazione…",
loading: "Caricamento…",
loadedOn: "Caricato su {device}",
download: "Scarica",
downloadConfirmTitle: "Scaricare Laya {model}?",
+ downloadConfirmTitleModel: "Scaricare {model}?",
downloadConfirmBody:
"L'API decisionale ha bisogno di questo modello per rispondere alle richieste. Circa {size}, scaricato una sola volta nella cache di Hugging Face.",
unload: "Rimuovi dalla memoria",
@@ -2923,6 +2927,9 @@ export const it = {
methodLabel: "Metodo",
methodTooltip:
"Il modo in cui viene addestrato il modello. LoRA e QLoRA aggiornano piccoli adattatori anziché tutti i pesi.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "Il checkpoint Laya da sottoporre a fine-tuning. Multilingue va bene per la maggior parte dei dataset.",
datasetLabel: "Dataset",
datasetTooltip:
"I dati di addestramento usati per il fine-tuning del modello.",
@@ -3387,6 +3394,10 @@ export const it = {
"Inserisci un tasso di apprendimento maggiore di zero.",
embeddingLearningRateRange:
"Inserisci un tasso di apprendimento degli embedding maggiore di 0 e minore di 1.",
+ decisionColumnsMissing:
+ "I modelli decisionali richiedono le colonne state, questions e gold (o answers). Mancano: {columns}.",
+ decisionOwnerOnly:
+ "Solo il proprietario di Studio può eseguire il fine-tuning dei modelli decisionali.",
hfDatasetRequired: "Seleziona prima un dataset Hugging Face.",
hfDatasetSplitRequired:
"Seleziona o inserisci prima uno split di addestramento.",
@@ -3558,6 +3569,10 @@ export const it = {
title: "Avanzamento dell'addestramento",
liveMetrics: "Metriche di addestramento in tempo reale",
exportGguf: "Esporta in GGUF",
+ useInDecisionApi: "Usa nell'API decisionale",
+ decisionApiEnabled: "L'API decisionale ora usa {name}.",
+ decisionApiFailed:
+ "Impossibile passare l'API decisionale a questo modello.",
openConfig: "Apri la configurazione di addestramento",
configLabel: "Configurazione di addestramento",
hyperparams: "Iperparametri",
diff --git a/studio/frontend/src/i18n/locales/ja.ts b/studio/frontend/src/i18n/locales/ja.ts
index 066a084102e..c613e652dca 100644
--- a/studio/frontend/src/i18n/locales/ja.ts
+++ b/studio/frontend/src/i18n/locales/ja.ts
@@ -2707,6 +2707,8 @@ export const ja = {
modelMultilingual: "多言語",
modelEnglish: "英語",
modelTypedDecisions: "型付き判定",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "推奨",
device: "実行先",
deviceDescription: "GPU の方が高速ですが、再起動するまでメモリを確保し続けます。",
@@ -2716,11 +2718,13 @@ export const ja = {
notDownloaded: "未ダウンロード · {size}",
downloading: "ダウンロード中…",
downloaded: "ダウンロード済み · 最初のリクエストで読み込み",
+ ready: "準備完了 · 最初のリクエストで読み込み",
installing: "インストール中…",
loading: "読み込み中…",
loadedOn: "{device} に読み込み済み",
download: "ダウンロード",
downloadConfirmTitle: "Laya {model} をダウンロードしますか?",
+ downloadConfirmTitleModel: "{model} をダウンロードしますか?",
downloadConfirmBody:
"Decision API がリクエストに応答するにはこのモデルが必要です。約 {size}、Hugging Face キャッシュに一度だけダウンロードされます。",
unload: "アンロード",
@@ -2843,6 +2847,9 @@ export const ja = {
datasetLabel: "データセット",
modelTooltip: "ファインチューニングするベースモデルです。",
methodTooltip: "モデルの学習方法です。LoRA と QLoRA はすべての重みではなく小さなアダプターを更新します。",
+ checkpointLabel: "チェックポイント",
+ checkpointTooltip:
+ "ファインチューニングする Laya のチェックポイントです。多くのデータセットには多言語が適しています。",
datasetTooltip: "モデルのファインチューニングに使う学習データです。",
hfTokenDescription:
"アクセス制限付きまたは非公開のモデルとデータセットに必要です。",
@@ -3309,6 +3316,10 @@ export const ja = {
learningRatePositive: "0 より大きい学習率を入力してください。",
embeddingLearningRateRange:
"0 より大きく 1 より小さい埋め込み学習率を入力してください。",
+ decisionColumnsMissing:
+ "判定モデルには state、questions、gold(または answers)列が必要です。不足している列: {columns}",
+ decisionOwnerOnly:
+ "判定モデルをファインチューニングできるのは Studio の所有者だけです。",
hfDatasetRequired:
"先に Hugging Face データセットを選択してください。",
hfDatasetSplitRequired:
@@ -3438,6 +3449,9 @@ export const ja = {
title: "トレーニング進捗",
liveMetrics: "リアルタイムトレーニングメトリクス",
exportGguf: "GGUF へエクスポート",
+ useInDecisionApi: "判定 API で使う",
+ decisionApiEnabled: "判定 API で {name} を使うようになりました。",
+ decisionApiFailed: "判定 API をこのモデルに切り替えられませんでした。",
openConfig: "トレーニング構成を開く",
configLabel: "トレーニング構成",
hyperparams: "ハイパーパラメーター",
diff --git a/studio/frontend/src/i18n/locales/ko.ts b/studio/frontend/src/i18n/locales/ko.ts
index a4c6113dc1a..98df5802a82 100644
--- a/studio/frontend/src/i18n/locales/ko.ts
+++ b/studio/frontend/src/i18n/locales/ko.ts
@@ -2726,6 +2726,8 @@ export const ko = {
modelMultilingual: "다국어",
modelEnglish: "영어",
modelTypedDecisions: "유형별 판단",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "추천",
device: "실행 위치",
deviceDescription: "GPU가 더 빠르지만 다시 시작할 때까지 메모리를 계속 차지합니다.",
@@ -2735,11 +2737,13 @@ export const ko = {
notDownloaded: "다운로드 안 됨 · {size}",
downloading: "다운로드 중…",
downloaded: "다운로드됨 · 첫 요청 때 로드",
+ ready: "준비됨 · 첫 요청 때 로드",
installing: "설치 중…",
loading: "로드 중…",
loadedOn: "{device}에 로드됨",
download: "다운로드",
downloadConfirmTitle: "Laya {model}을(를) 다운로드할까요?",
+ downloadConfirmTitleModel: "{model}을(를) 다운로드할까요?",
downloadConfirmBody:
"Decision API가 요청에 응답하려면 이 모델이 필요합니다. 약 {size}이며 Hugging Face 캐시에 한 번만 다운로드됩니다.",
unload: "언로드",
@@ -2866,6 +2870,9 @@ export const ko = {
datasetLabel: "데이터셋",
modelTooltip: "파인튜닝할 기본 모델입니다.",
methodTooltip: "모델 학습 방식입니다. LoRA와 QLoRA는 전체 가중치 대신 작은 어댑터를 업데이트합니다.",
+ checkpointLabel: "체크포인트",
+ checkpointTooltip:
+ "파인튜닝할 Laya 체크포인트입니다. 대부분의 데이터셋에는 다국어가 적합합니다.",
datasetTooltip: "모델을 파인튜닝하는 데 사용하는 학습 데이터입니다.",
hfTokenDescription:
"액세스가 제한되거나 비공개인 모델 및 데이터 세트에 필요합니다.",
@@ -3347,6 +3354,10 @@ export const ko = {
learningRatePositive: "0보다 큰 학습률을 입력하세요.",
embeddingLearningRateRange:
"0보다 크고 1보다 작은 임베딩 학습률을 입력하세요.",
+ decisionColumnsMissing:
+ "판단 모델에는 state, questions, gold(또는 answers) 열이 필요합니다. 누락된 열: {columns}",
+ decisionOwnerOnly:
+ "판단 모델은 Studio 소유자만 파인튜닝할 수 있습니다.",
hfDatasetRequired: "Hugging Face 데이터셋을 먼저 선택하세요.",
hfDatasetSplitRequired: "먼저 학습 분할을 선택하거나 입력하세요.",
localDatasetRequired: "로컬 데이터셋을 먼저 선택하세요.",
@@ -3480,6 +3491,9 @@ export const ko = {
title: "학습 진행률",
liveMetrics: "실시간 학습 지표",
exportGguf: "GGUF로 내보내기",
+ useInDecisionApi: "판단 API에서 사용",
+ decisionApiEnabled: "이제 판단 API가 {name}을(를) 사용합니다.",
+ decisionApiFailed: "판단 API를 이 모델로 전환하지 못했습니다.",
openConfig: "학습 구성 열기",
configLabel: "학습 구성",
hyperparams: "하이퍼파라미터",
diff --git a/studio/frontend/src/i18n/locales/pt-br.ts b/studio/frontend/src/i18n/locales/pt-br.ts
index 531b18edabe..d0c3a2cf145 100644
--- a/studio/frontend/src/i18n/locales/pt-br.ts
+++ b/studio/frontend/src/i18n/locales/pt-br.ts
@@ -2752,6 +2752,8 @@ export const ptBR = {
modelMultilingual: "Multilíngue",
modelEnglish: "Inglês",
modelTypedDecisions: "Decisões tipadas",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Recomendado",
device: "Executar em",
deviceDescription: "A GPU responde mais rápido, mas mantém a memória reservada até reiniciar.",
@@ -2761,11 +2763,13 @@ export const ptBR = {
notDownloaded: "Não baixado · {size}",
downloading: "Baixando…",
downloaded: "Baixado · carrega na primeira solicitação",
+ ready: "Pronto · carrega na primeira solicitação",
installing: "Instalando…",
loading: "Carregando…",
loadedOn: "Carregado em {device}",
download: "Baixar",
downloadConfirmTitle: "Baixar Laya {model}?",
+ downloadConfirmTitleModel: "Baixar {model}?",
downloadConfirmBody:
"A API de decisão precisa deste modelo para responder às solicitações. Cerca de {size}, baixado uma única vez no seu cache do Hugging Face.",
unload: "Descarregar",
@@ -2896,6 +2900,9 @@ export const ptBR = {
datasetLabel: "Dataset",
modelTooltip: "O modelo base que você quer ajustar.",
methodTooltip: "Como o modelo é treinado. LoRA e QLoRA atualizam adaptadores pequenos em vez de todos os pesos.",
+ checkpointLabel: "Checkpoint",
+ checkpointTooltip:
+ "O checkpoint do Laya que será ajustado. Multilíngue serve para a maioria dos conjuntos de dados.",
datasetTooltip: "Os dados de treinamento usados para ajustar o modelo.",
hfTokenDescription:
"Necessário para modelos e conjuntos de dados restritos ou privados.",
@@ -3370,6 +3377,10 @@ export const ptBR = {
learningRatePositive: "Insira uma taxa de aprendizado maior que zero.",
embeddingLearningRateRange:
"Insira uma taxa de aprendizado do embedding maior que 0 e menor que 1.",
+ decisionColumnsMissing:
+ "Modelos de decisão precisam das colunas state, questions e gold (ou answers). Faltando: {columns}.",
+ decisionOwnerOnly:
+ "Só o proprietário do Studio pode ajustar modelos de decisão.",
hfDatasetRequired: "Selecione primeiro um dataset do Hugging Face.",
hfDatasetSplitRequired:
"Selecione ou insira primeiro uma divisão de treino.",
@@ -3517,6 +3528,10 @@ export const ptBR = {
title: "Progresso do Treinamento",
liveMetrics: "Métricas de treino em tempo real",
exportGguf: "Exportar para GGUF",
+ useInDecisionApi: "Usar na API de decisões",
+ decisionApiEnabled: "A API de decisões agora usa {name}.",
+ decisionApiFailed:
+ "Não foi possível trocar a API de decisões para este modelo.",
openConfig: "Abrir configuração de treino",
configLabel: "Configuração de Treino",
hyperparams: "Hiperparâmetros",
diff --git a/studio/frontend/src/i18n/locales/ru.ts b/studio/frontend/src/i18n/locales/ru.ts
index 86b5e825f15..560f16a9140 100644
--- a/studio/frontend/src/i18n/locales/ru.ts
+++ b/studio/frontend/src/i18n/locales/ru.ts
@@ -2747,6 +2747,8 @@ export const ru = {
modelMultilingual: "Многоязычная",
modelEnglish: "Английская",
modelTypedDecisions: "Типизированные решения",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "Рекомендуется",
device: "Запускать на",
deviceDescription: "GPU отвечает быстрее, но держит память зарезервированной до перезапуска.",
@@ -2756,11 +2758,13 @@ export const ru = {
notDownloaded: "Не скачана · {size}",
downloading: "Скачивание…",
downloaded: "Скачана · загрузится при первом запросе",
+ ready: "Готова · загрузится при первом запросе",
installing: "Установка…",
loading: "Загрузка…",
loadedOn: "Загружена на {device}",
download: "Скачать",
downloadConfirmTitle: "Скачать Laya {model}?",
+ downloadConfirmTitleModel: "Скачать {model}?",
downloadConfirmBody:
"API решений нужна эта модель, чтобы отвечать на запросы. Около {size}, загружается один раз в кэш Hugging Face.",
unload: "Выгрузить",
@@ -2892,6 +2896,9 @@ export const ru = {
datasetLabel: "Датасет",
modelTooltip: "Базовая модель, которую вы хотите дообучить.",
methodTooltip: "Как обучается модель. LoRA и QLoRA обновляют небольшие адаптеры вместо всех весов.",
+ checkpointLabel: "Чекпоинт",
+ checkpointTooltip:
+ "Чекпоинт Laya для дообучения. Многоязычная подходит для большинства наборов данных.",
datasetTooltip: "Обучающие данные для дообучения модели.",
hfTokenDescription:
"Необходим для моделей и наборов данных с ограниченным или закрытым доступом.",
@@ -3380,6 +3387,10 @@ export const ru = {
learningRatePositive: "Введите скорость обучения больше нуля.",
embeddingLearningRateRange:
"Введите скорость обучения эмбеддингов больше 0 и меньше 1.",
+ decisionColumnsMissing:
+ "Моделям решений нужны столбцы state, questions и gold (или answers). Не хватает: {columns}.",
+ decisionOwnerOnly:
+ "Дообучать модели решений может только владелец Studio.",
hfDatasetRequired: "Сначала выберите датасет Hugging Face.",
hfDatasetSplitRequired:
"Сначала выберите или введите обучающую выборку.",
@@ -3515,6 +3526,9 @@ export const ru = {
title: "Прогресс обучения",
liveMetrics: "Метрики обучения в реальном времени",
exportGguf: "Экспортировать в GGUF",
+ useInDecisionApi: "Использовать в API решений",
+ decisionApiEnabled: "API решений теперь использует {name}.",
+ decisionApiFailed: "Не удалось переключить API решений на эту модель.",
openConfig: "Открыть конфигурацию обучения",
configLabel: "Конфигурация обучения",
hyperparams: "Гиперпараметры",
diff --git a/studio/frontend/src/i18n/locales/zh-CN.ts b/studio/frontend/src/i18n/locales/zh-CN.ts
index 1d5b2c83524..5c69d3c8201 100644
--- a/studio/frontend/src/i18n/locales/zh-CN.ts
+++ b/studio/frontend/src/i18n/locales/zh-CN.ts
@@ -2685,6 +2685,8 @@ export const zhCN = {
modelMultilingual: "多语言",
modelEnglish: "英语",
modelTypedDecisions: "类型化决策",
+ modelClefFlash: "Clef-flash",
+ modelClef: "Clef",
recommended: "推荐",
device: "运行于",
deviceDescription: "GPU 响应更快,但在重启前会一直占用显存。",
@@ -2694,11 +2696,13 @@ export const zhCN = {
notDownloaded: "未下载 · {size}",
downloading: "正在下载…",
downloaded: "已下载 · 首次请求时加载",
+ ready: "就绪 · 首次请求时加载",
installing: "正在安装…",
loading: "正在加载…",
loadedOn: "已加载到 {device}",
download: "下载",
downloadConfirmTitle: "下载 Laya {model}?",
+ downloadConfirmTitleModel: "下载 {model}?",
downloadConfirmBody:
"决策 API 需要此模型来响应请求。约 {size},只需下载一次到你的 Hugging Face 缓存。",
unload: "卸载",
@@ -2819,6 +2823,8 @@ export const zhCN = {
datasetLabel: "数据集",
modelTooltip: "要微调的基础模型。",
methodTooltip: "模型的训练方式。LoRA 和 QLoRA 只更新小型适配器,而不是全部权重。",
+ checkpointLabel: "检查点",
+ checkpointTooltip: "要微调的 Laya 检查点。多语言版本适合大多数数据集。",
datasetTooltip: "用于微调模型的训练数据。",
hfTokenDescription: "访问受限或私有模型和数据集时需要。",
uploadLocalLabel: "或上传本地文件",
@@ -3269,6 +3275,9 @@ export const zhCN = {
learningRatePositive: "请输入大于零的学习率。",
embeddingLearningRateRange:
"请输入大于 0 且小于 1 的 Embedding 学习率。",
+ decisionColumnsMissing:
+ "决策模型需要 state、questions 和 gold(或 answers)列。缺少:{columns}。",
+ decisionOwnerOnly: "只有 Studio 所有者可以微调决策模型。",
hfDatasetRequired: "请先选择 Hugging Face 数据集。",
hfDatasetSplitRequired: "请先选择或输入训练拆分。",
localDatasetRequired: "请先选择本地数据集。",
@@ -3396,6 +3405,9 @@ export const zhCN = {
title: "训练进度",
liveMetrics: "实时训练指标",
exportGguf: "导出为 GGUF",
+ useInDecisionApi: "在决策 API 中使用",
+ decisionApiEnabled: "决策 API 现在使用 {name}。",
+ decisionApiFailed: "无法将决策 API 切换到此模型。",
openConfig: "打开训练配置",
configLabel: "训练配置",
hyperparams: "超参数",
diff --git a/studio/frontend/src/types/training.ts b/studio/frontend/src/types/training.ts
index cc096f29492..5ce0de621dc 100644
--- a/studio/frontend/src/types/training.ts
+++ b/studio/frontend/src/types/training.ts
@@ -1,7 +1,7 @@
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
-export type ModelType = "vision" | "audio" | "embeddings" | "text";
+export type ModelType = "vision" | "audio" | "embeddings" | "text" | "decision";
export type TrainingMethod = "qlora" | "lora" | "full" | "cpt";
export function isTrainingMethod(value: unknown): value is TrainingMethod {
diff --git a/studio/frontend/tests/helpers/store-stubs/auth.ts b/studio/frontend/tests/helpers/store-stubs/auth.ts
index f7f484b6035..b1720755a5a 100644
--- a/studio/frontend/tests/helpers/store-stubs/auth.ts
+++ b/studio/frontend/tests/helpers/store-stubs/auth.ts
@@ -23,3 +23,7 @@ export function authFetch(input: string, init?: RequestInit): Promise<Response>
export async function prepareHfTokenForUse(): Promise<null> {
return null;
}
+
+export function useIsAccountOwner(): boolean {
+ return true;
+}
diff --git a/studio/frontend/tests/helpers/store-stubs/hub.ts b/studio/frontend/tests/helpers/store-stubs/hub.ts
index 6724a5ce6c8..2919e3d4381 100644
--- a/studio/frontend/tests/helpers/store-stubs/hub.ts
+++ b/studio/frontend/tests/helpers/store-stubs/hub.ts
@@ -2,6 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
// Real logic, re-exported: only the barrel it normally comes from needs stubbing.
+export { EMBEDDING_TAGS } from "../../../src/features/hub/lib/hf-model-meta.ts";
export { normalizeModelIdentity } from "../../../src/features/hub/lib/model-identity.ts";
/** Minimal HF-token store. */
diff --git a/studio/frontend/tests/training-decision-model.test.ts b/studio/frontend/tests/training-decision-model.test.ts
new file mode 100644
index 00000000000..07ab5f9c921
--- /dev/null
+++ b/studio/frontend/tests/training-decision-model.test.ts
@@ -0,0 +1,716 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test, { after } from "node:test";
+
+import {
+ installLocalStorageFake,
+ registerStoreStubResolver,
+} from "./helpers/kit.ts";
+
+registerStoreStubResolver();
+installLocalStorageFake();
+
+const yaml = await import("js-yaml");
+const { DEFAULT_HYPERPARAMS, LR_DEFAULT_DECISION_FULL, LR_DEFAULT_LORA } =
+ await import("../src/config/training.ts");
+const { setAuthFetchHandler } = await import("./helpers/store-stubs/auth.ts");
+const { useTrainingConfigStore } = await import(
+ "../src/features/training/stores/training-config-store.ts"
+);
+const { buildTrainingStartPayload } = await import(
+ "../src/features/training/api/mappers.ts"
+);
+const { DatasetFormatError } = await import(
+ "../src/features/training/api/datasets-api.ts"
+);
+const { validateTrainingConfig } = await import(
+ "../src/features/training/lib/validation.ts"
+);
+const { deriveTrainingReadiness } = await import(
+ "../src/features/training/hooks/use-training-readiness.ts"
+);
+const { checkDecisionDatasetColumns, missingDecisionColumns } = await import(
+ "../src/features/training/lib/decision-dataset.ts"
+);
+const { trainingModelTypeFlagsFromMetadata } = await import(
+ "../src/features/training/lib/model-type-inference.ts"
+);
+const { inferTrainingModelTypeFromFlags } = await import(
+ "../src/features/training/lib/model-type-capabilities.ts"
+);
+const { isTrainingModelTypeSupportedOnDevice } = await import(
+ "../src/features/training/lib/training-methods.ts"
+);
+const { countNonDefaultAdvancedSettings } = await import(
+ "../src/features/studio/wizard/advanced-settings-summary.ts"
+);
+
+type TrainingState = ReturnType<typeof useTrainingConfigStore.getState>;
+
+const LAYA = "convaiinnovations/laya";
+
+const LAYA_YAML = yaml.load(
+ readFileSync(
+ new URL(
+ "../../backend/assets/configs/model_defaults/decision/convaiinnovations_laya.yaml",
+ import.meta.url,
+ ),
+ "utf8",
+ ),
+) as {
+ training: Record<string, number>;
+ lora: Record<string, number>;
+};
+
+const LAYA_CONFIG = {
+ id: LAYA,
+ config: LAYA_YAML,
+ is_vision: false,
+ is_embedding: false,
+ is_decision: true,
+ decision_checkpoints: [
+ { name: "laya-multilingual", subfolder: "multilingual", description: "" },
+ { name: "laya-english", subfolder: null, description: "" },
+ {
+ name: "laya-typed-decisions",
+ subfolder: "typed-decisions",
+ description: "",
+ },
+ ],
+ is_audio: false,
+ audio_type_known: true,
+ is_lora: false,
+ model_type: "decision",
+ model_size_bytes: 600_000_000,
+ max_position_embeddings: null,
+};
+
+const LLM = "unsloth/Qwen3-0.6B";
+
+const LLM_CONFIG = {
+ id: LLM,
+ config: { training: { max_steps: 60 } },
+ is_vision: false,
+ is_embedding: false,
+ is_audio: false,
+ audio_type_known: true,
+ is_lora: false,
+ model_type: "text",
+ model_size_bytes: 1_200_000_000,
+ max_position_embeddings: 32768,
+};
+
+async function waitFor(done: (state: TrainingState) => boolean): Promise<void> {
+ for (let attempt = 0; attempt < 100; attempt += 1) {
+ if (done(useTrainingConfigStore.getState())) {
+ return;
+ }
+ await new Promise((resolve) => setTimeout(resolve, 5));
+ }
+ throw new Error("the training config did not settle");
+}
+
+const waitForModelDefaults = (model: string) =>
+ waitFor(
+ (state) =>
+ !state.isLoadingModelDefaults && state.modelDefaultsAppliedFor === model,
+ );
+
+function serveConfigs(laya: object = LAYA_CONFIG): string[] {
+ const requested: string[] = [];
+ setAuthFetchHandler((input) => {
+ requested.push(input);
+ if (input.startsWith("/api/models/config/")) {
+ return Response.json(input.includes("laya") ? laya : LLM_CONFIG);
+ }
+ return Response.json({});
+ });
+ return requested;
+}
+
+function serveConfigsLater(): () => void {
+ let release: (() => void) | undefined;
+ const loaded = new Promise<void>((resolve) => {
+ release = resolve;
+ });
+ setAuthFetchHandler(async (input) => {
+ await loaded;
+ return Response.json(input.includes("laya") ? LAYA_CONFIG : LLM_CONFIG);
+ });
+ return () => release?.();
+}
+
+async function selectModel(
+ model: string,
+ laya: object = LAYA_CONFIG,
+): Promise<string[]> {
+ const requested = serveConfigs(laya);
+ useTrainingConfigStore.getState().selectTrainingModel(model, "text");
+ await waitForModelDefaults(model);
+ return requested;
+}
+
+const selectLaya = () => selectModel(LAYA);
+
+const HF_DECISION_DATASET = {
+ datasetSource: "huggingface" as const,
+ dataset: "LocalLLaMA/typed-decisions",
+ datasetKnownCached: false,
+ manualDatasetOptionsValid: true,
+};
+
+after(() => setAuthFetchHandler(null));
+
+test("picking a decision model starts a LoRA run with the model's defaults", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.setState({
+ trainingMethod: "qlora",
+ packing: true,
+ datasetStreaming: true,
+ });
+
+ const requested = await selectLaya();
+
+ assert.deepEqual(
+ requested.filter((url) => !url.startsWith("/api/models/config/")),
+ [],
+ "a decision model must not ask the hardware for a LoRA/QLoRA pick",
+ );
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.modelType, "decision");
+ assert.equal(state.trainingMethod, "lora");
+ assert.equal(state.learningRate, LAYA_YAML.training.learning_rate);
+ assert.equal(state.epochs, LAYA_YAML.training.num_epochs);
+ assert.equal(state.maxSteps, LAYA_YAML.training.max_steps);
+ assert.equal(state.batchSize, LAYA_YAML.training.batch_size);
+ assert.equal(
+ state.gradientAccumulation,
+ LAYA_YAML.training.gradient_accumulation_steps,
+ );
+ assert.equal(state.loraRank, LAYA_YAML.lora.lora_r);
+ assert.equal(state.loraAlpha, LAYA_YAML.lora.lora_alpha);
+ assert.equal(state.datasetStreaming, false);
+ assert.equal(state.decisionCheckpoints?.length, 3);
+ assert.equal(state.modelSubfolder, "multilingual");
+});
+
+test("leaving CPT for a decision model does not keep CPT's learning rate", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.getState().setTrainingMethod("cpt");
+
+ await selectLaya();
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "lora");
+ assert.equal(state.learningRate, LAYA_YAML.training.learning_rate);
+});
+
+test("a fresh decision pick defaults to LoRA even from full fine-tuning", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.getState().setTrainingMethod("full");
+
+ await selectLaya();
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "lora");
+ assert.equal(state.learningRate, LAYA_YAML.training.learning_rate);
+});
+
+test("LoRA takes the model's learning rate and full fine-tuning the decision one", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectModel(LAYA, {
+ ...LAYA_CONFIG,
+ config: {
+ ...LAYA_YAML,
+ training: { ...LAYA_YAML.training, learning_rate: 5e-4 },
+ },
+ });
+ assert.equal(useTrainingConfigStore.getState().learningRate, 5e-4);
+
+ useTrainingConfigStore.getState().setTrainingMethod("full");
+ let payload = buildTrainingStartPayload(
+ useTrainingConfigStore.getState(),
+ null,
+ );
+ assert.equal(payload.training_type, "Full Finetuning");
+ assert.equal(payload.use_lora, false);
+ assert.equal(payload.learning_rate, String(LR_DEFAULT_DECISION_FULL));
+
+ useTrainingConfigStore.getState().setTrainingMethod("lora");
+ payload = buildTrainingStartPayload(useTrainingConfigStore.getState(), null);
+ assert.equal(payload.training_type, "LoRA/QLoRA");
+ assert.equal(payload.use_lora, true);
+ assert.equal(payload.learning_rate, "0.0005");
+});
+
+test("a checkpoint pick survives defaults reloads and resets on a model change", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+ useTrainingConfigStore.getState().setModelSubfolder(null);
+
+ useTrainingConfigStore.getState().ensureModelDefaultsLoaded();
+ await waitForModelDefaults(LAYA);
+ assert.equal(useTrainingConfigStore.getState().modelSubfolder, null);
+
+ useTrainingConfigStore.getState().setSelectedModelCacheReference(LAYA, {
+ localPath: "/cache/convaiinnovations/laya",
+ modelFormat: null,
+ });
+ await waitForModelDefaults(LAYA);
+ assert.equal(useTrainingConfigStore.getState().modelSubfolder, null);
+
+ await selectModel(LLM);
+ await selectLaya();
+ assert.equal(
+ useTrainingConfigStore.getState().modelSubfolder,
+ "multilingual",
+ );
+});
+
+test("Reset to defaults keeps the chosen checkpoint", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+
+ for (const subfolder of ["typed-decisions", null]) {
+ useTrainingConfigStore.getState().setModelSubfolder(subfolder);
+ useTrainingConfigStore.getState().setBatchSize(4);
+ useTrainingConfigStore.getState().resetToModelDefaults();
+ await waitForModelDefaults(LAYA);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.modelSubfolder, subfolder);
+ assert.equal(state.batchSize, LAYA_YAML.training.batch_size);
+ }
+});
+
+test("a method picked while a decision model loads still gets the model's defaults", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectModel(LLM);
+ const release = serveConfigsLater();
+
+ useTrainingConfigStore.getState().selectTrainingModel(LAYA, "text");
+ useTrainingConfigStore.getState().setTrainingMethod("full");
+ release();
+ await waitForModelDefaults(LAYA);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "full");
+ assert.equal(state.learningRate, LR_DEFAULT_DECISION_FULL);
+ assert.equal(state.epochs, LAYA_YAML.training.num_epochs);
+ assert.equal(state.maxSteps, LAYA_YAML.training.max_steps);
+ assert.equal(state.batchSize, LAYA_YAML.training.batch_size);
+ assert.equal(state.modelSubfolder, "multilingual");
+});
+
+test("leaving a decision model restores the method and streaming it overrode", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.setState({
+ datasetSource: "huggingface",
+ dataset: "roneneldan/TinyStories",
+ maxSteps: 60,
+ datasetStreaming: true,
+ });
+ useTrainingConfigStore.getState().setTrainingMethod("cpt");
+
+ await selectLaya();
+ assert.equal(useTrainingConfigStore.getState().trainingMethod, "lora");
+ assert.equal(useTrainingConfigStore.getState().datasetStreaming, false);
+ useTrainingConfigStore.getState().setTrainingMethod("full");
+
+ await selectModel(LLM);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.modelType, "text");
+ assert.equal(state.trainingMethod, "cpt");
+ assert.equal(state.learningRate, 5e-5);
+ assert.equal(state.datasetStreaming, true);
+ assert.equal(state.settingsBeforeDecision, null);
+});
+
+test("an edit made while leaving a decision model does not keep its recipe", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+ const release = serveConfigsLater();
+
+ useTrainingConfigStore.getState().selectTrainingModel(LLM, "text");
+ useTrainingConfigStore.getState().setBatchSize(2);
+ release();
+ await waitForModelDefaults(LLM);
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "qlora");
+ assert.equal(state.maxSteps, LLM_CONFIG.config.training.max_steps);
+ assert.equal(state.batchSize, 2);
+ assert.equal(state.settingsBeforeDecision, null);
+});
+
+test("leaving a decision model for one whose config fails drops the decision recipe", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+ useTrainingConfigStore.getState().setModelSubfolder("typed-decisions");
+ setAuthFetchHandler(() => new Response("upstream error", { status: 502 }));
+
+ useTrainingConfigStore.getState().selectTrainingModel(LLM, "text");
+ await waitFor(
+ (state) =>
+ state.modelDefaultsError !== null &&
+ !state.isLoadingModelDefaults &&
+ !state.isCheckingVision,
+ );
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "qlora");
+ assert.equal(state.learningRate, LR_DEFAULT_LORA);
+ assert.equal(state.epochs, DEFAULT_HYPERPARAMS.epochs);
+ assert.equal(state.maxSteps, DEFAULT_HYPERPARAMS.maxSteps);
+ assert.equal(state.batchSize, DEFAULT_HYPERPARAMS.batchSize);
+ assert.equal(state.loraRank, DEFAULT_HYPERPARAMS.loraRank);
+ assert.equal(state.optimizerType, DEFAULT_HYPERPARAMS.optimizerType);
+ assert.equal(state.modelSubfolder, null);
+ assert.equal(state.decisionCheckpoints, null);
+ assert.equal(state.settingsBeforeDecision, null);
+ const payload = buildTrainingStartPayload(state, null);
+ assert.equal(payload.is_decision, false);
+ assert.equal(payload.load_in_4bit, true);
+});
+
+test("a decision model whose config fails cannot start until it loads", async () => {
+ useTrainingConfigStore.getState().reset();
+ setAuthFetchHandler(() => new Response("upstream error", { status: 502 }));
+
+ useTrainingConfigStore.getState().selectTrainingModel(LAYA, "decision");
+ await waitFor(
+ (state) =>
+ state.modelDefaultsError !== null &&
+ !state.isLoadingModelDefaults &&
+ !state.isCheckingVision,
+ );
+ useTrainingConfigStore.setState(HF_DECISION_DATASET);
+
+ const failed = useTrainingConfigStore.getState();
+ assert.equal(failed.modelType, "decision");
+ assert.equal(failed.modelSubfolder, null);
+ const blocked = deriveTrainingReadiness(failed, "cuda", true);
+ assert.equal(blocked.isReady, false);
+ assert.equal(blocked.configValidation.ok, true);
+ assert.notEqual(blocked.modelError, null);
+
+ serveConfigs();
+ useTrainingConfigStore.getState().ensureModelDefaultsLoaded();
+ await waitForModelDefaults(LAYA);
+ const loaded = useTrainingConfigStore.getState();
+ assert.equal(loaded.modelDefaultsError, null);
+ assert.equal(loaded.modelSubfolder, "multilingual");
+ assert.equal(loaded.learningRate, LAYA_YAML.training.learning_rate);
+ assert.equal(deriveTrainingReadiness(loaded, "cuda", true).isReady, true);
+});
+
+test("a decision model last loaded as a chat model gets its defaults on reload", async () => {
+ useTrainingConfigStore.getState().reset();
+ // What a build without decision models persisted for Laya: a text model on default.yaml.
+ useTrainingConfigStore.setState({
+ selectedModel: LAYA,
+ modelType: "text",
+ modelDefaultsAppliedFor: LAYA,
+ trainingMethod: "qlora",
+ maxSteps: 30,
+ batchSize: 2,
+ });
+ serveConfigs();
+
+ useTrainingConfigStore.getState().ensureModelDefaultsLoaded();
+ await waitFor(
+ (state) => !state.isLoadingModelDefaults && state.modelType === "decision",
+ );
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.trainingMethod, "lora");
+ assert.equal(state.maxSteps, LAYA_YAML.training.max_steps);
+ assert.equal(state.batchSize, LAYA_YAML.training.batch_size);
+ assert.equal(state.modelSubfolder, "multilingual");
+});
+
+test("a decision run sends the decision fields and switches off the LLM-only options", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+ useTrainingConfigStore.getState().setTrainingMethod("lora");
+ useTrainingConfigStore.getState().setModelSubfolder(null);
+ useTrainingConfigStore.setState({
+ datasetSource: "huggingface",
+ dataset: "LocalLLaMA/typed-decisions",
+ datasetStreaming: true,
+ packing: true,
+ trainOnCompletions: true,
+ loraVariant: "dora",
+ optimizerType: "paged_adamw_8bit",
+ contextLength: 32768,
+ datasetManualMapping: { state: "user", gold: "assistant" },
+ });
+
+ const payload = buildTrainingStartPayload(
+ useTrainingConfigStore.getState(),
+ null,
+ );
+
+ assert.equal(payload.is_decision, true);
+ assert.equal(payload.model_subfolder, null);
+ assert.equal(payload.is_embedding, false);
+ assert.equal(payload.training_type, "LoRA/QLoRA");
+ assert.equal(payload.load_in_4bit, false);
+ assert.equal(payload.use_lora, true);
+ assert.equal(payload.lora_r, LAYA_YAML.lora.lora_r);
+ assert.equal(payload.use_dora, false);
+ assert.equal(payload.packing, false);
+ assert.equal(payload.train_on_completions, false);
+ assert.equal(payload.dataset_streaming, false);
+ assert.equal(payload.custom_format_mapping, undefined);
+ assert.equal(payload.optim, "adamw_torch");
+ assert.equal(payload.max_seq_length, 1024);
+ assert.equal(payload.learning_rate, String(LAYA_YAML.training.learning_rate));
+});
+
+test("an LLM run keeps its method and sends no decision fields", () => {
+ useTrainingConfigStore.getState().reset();
+ const payload = buildTrainingStartPayload(
+ {
+ ...useTrainingConfigStore.getState(),
+ selectedModel: LLM,
+ modelType: "text",
+ trainingMethod: "qlora",
+ modelSubfolder: "multilingual",
+ optimizerType: "paged_adamw_8bit",
+ contextLength: 32768,
+ },
+ null,
+ );
+
+ assert.equal(payload.is_decision, false);
+ assert.equal(payload.model_subfolder, null);
+ assert.equal(payload.training_type, "LoRA/QLoRA");
+ assert.equal(payload.load_in_4bit, true);
+ assert.equal(payload.optim, "paged_adamw_8bit");
+ assert.equal(payload.max_seq_length, 32768);
+});
+
+test("decision training is refused on Apple Silicon only", () => {
+ const config = {
+ ...useTrainingConfigStore.getState(),
+ ...HF_DECISION_DATASET,
+ selectedModel: LAYA,
+ modelType: "decision" as const,
+ trainingMethod: "full" as const,
+ };
+
+ assert.deepEqual(validateTrainingConfig(config, "mac"), {
+ ok: false,
+ errorKey: "studio.params.notSupportedAppleSilicon",
+ });
+ assert.deepEqual(validateTrainingConfig(config, "cuda"), {
+ ok: true,
+ errorKey: null,
+ });
+});
+
+test("the model picker knows Laya is a decision model before its config loads", () => {
+ const flags = trainingModelTypeFlagsFromMetadata({
+ pipelineTag: "text-classification",
+ tags: ["transformers", "safetensors", "laya", "system-one"],
+ identifiers: [LAYA],
+ });
+ const modelType = inferTrainingModelTypeFromFlags(flags);
+
+ assert.equal(modelType, "decision");
+ assert.equal(isTrainingModelTypeSupportedOnDevice(modelType, "mac"), false);
+ assert.equal(isTrainingModelTypeSupportedOnDevice(modelType, "cuda"), true);
+});
+
+test("only the Studio owner can start a decision run", () => {
+ const config = {
+ ...useTrainingConfigStore.getState(),
+ ...HF_DECISION_DATASET,
+ selectedModel: LAYA,
+ modelType: "decision" as const,
+ trainingMethod: "lora" as const,
+ };
+
+ assert.deepEqual(validateTrainingConfig(config, "cuda", false), {
+ ok: false,
+ errorKey: "studio.training.validation.decisionOwnerOnly",
+ });
+ assert.deepEqual(
+ validateTrainingConfig(
+ { ...config, selectedModel: LLM, modelType: "text" },
+ "cuda",
+ false,
+ ),
+ { ok: true, errorKey: null },
+ );
+});
+
+test("the start check names the decision columns a dataset lacks", () => {
+ assert.deepEqual(missingDecisionColumns(["state", "questions", "gold"]), []);
+ assert.deepEqual(
+ missingDecisionColumns(["state", "questions", "answers", "id"]),
+ [],
+ );
+ assert.deepEqual(missingDecisionColumns(["messages"]), [
+ "state",
+ "questions",
+ "gold",
+ ]);
+ assert.deepEqual(missingDecisionColumns(["state", "gold"]), ["questions"]);
+});
+
+test("a decision start skips the column check only for an uploaded JSON file it cannot read", async () => {
+ const unreadable = () =>
+ Promise.reject(
+ new DatasetFormatError(
+ "JSON parse error: Column(/gold/q1) changed from string to object",
+ 400,
+ ),
+ );
+ assert.deepEqual(
+ await checkDecisionDatasetColumns(unreadable, "0a1b_decisions.jsonl"),
+ [],
+ );
+ await assert.rejects(
+ checkDecisionDatasetColumns(unreadable, "0a1b_decisions.csv"),
+ DatasetFormatError,
+ );
+ await assert.rejects(
+ checkDecisionDatasetColumns(
+ () => Promise.reject(new DatasetFormatError("Dataset is gated.", 401)),
+ null,
+ ),
+ DatasetFormatError,
+ );
+ await assert.rejects(
+ checkDecisionDatasetColumns(
+ () => Promise.reject(new TypeError("Failed to fetch")),
+ "0a1b_decisions.jsonl",
+ ),
+ TypeError,
+ );
+ assert.deepEqual(
+ await checkDecisionDatasetColumns(
+ () => Promise.resolve({ columns: ["messages"] }),
+ null,
+ ),
+ ["state", "questions", "gold"],
+ );
+ assert.equal(
+ await checkDecisionDatasetColumns(() => Promise.resolve(null), null),
+ null,
+ );
+});
+
+test("the run summary does not count settings the decision trainer ignores", async () => {
+ useTrainingConfigStore.getState().reset();
+ await selectLaya();
+ useTrainingConfigStore.getState().setTrainingMethod("lora");
+ useTrainingConfigStore.setState({
+ packing: true,
+ trainOnCompletions: true,
+ saveSteps: 50,
+ optimizerType: "paged_adamw_8bit",
+ loraVariant: "dora",
+ targetModules: ["q_proj"],
+ });
+ const state = useTrainingConfigStore.getState();
+
+ assert.equal(
+ countNonDefaultAdvancedSettings(state, state.advancedSettingsBaseline),
+ 0,
+ );
+ assert.equal(buildTrainingStartPayload(state, null).optim, "adamw_torch");
+ assert.equal(
+ countNonDefaultAdvancedSettings(
+ { ...state, modelType: "text" },
+ state.advancedSettingsBaseline,
+ ),
+ 6,
+ );
+});
+
+const CLEF = "Cloudflare/clef-flash";
+
+const CLEF_YAML = yaml.load(
+ readFileSync(
+ new URL(
+ "../../backend/assets/configs/model_defaults/decision/Cloudflare_clef-flash.yaml",
+ import.meta.url,
+ ),
+ "utf8",
+ ),
+) as {
+ training: Record<string, number>;
+ lora: Record<string, number>;
+};
+
+async function selectClef(): Promise<void> {
+ setAuthFetchHandler((input) =>
+ Response.json(
+ input.startsWith("/api/models/config/")
+ ? {
+ ...LAYA_CONFIG,
+ id: CLEF,
+ config: CLEF_YAML,
+ decision_checkpoints: null,
+ decision_layout: "clef",
+ model_size_bytes: 19_000_000_000,
+ }
+ : {},
+ ),
+ );
+ useTrainingConfigStore.getState().selectTrainingModel(CLEF, "text");
+ await waitForModelDefaults(CLEF);
+}
+
+test("a Clef run keeps QLoRA, sends 4-bit and the recipe's context, and has no checkpoint picker", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.setState({ trainingMethod: "qlora" });
+ await selectClef();
+ useTrainingConfigStore.setState({
+ ...HF_DECISION_DATASET,
+ loraVariant: "dora",
+ });
+
+ const state = useTrainingConfigStore.getState();
+ assert.equal(state.modelType, "decision");
+ assert.equal(state.decisionLayout, "clef");
+ assert.equal(state.trainingMethod, "qlora");
+ assert.equal(state.decisionCheckpoints, null);
+ assert.equal(state.modelSubfolder, null);
+ const payload = buildTrainingStartPayload(state, null);
+ assert.equal(payload.is_decision, true);
+ assert.equal(payload.training_type, "LoRA/QLoRA");
+ assert.equal(payload.load_in_4bit, true);
+ assert.equal(payload.use_dora, false);
+ assert.equal(payload.model_subfolder, null);
+ assert.equal(payload.max_seq_length, CLEF_YAML.training.max_seq_length);
+ assert.equal(payload.lora_r, CLEF_YAML.lora.lora_r);
+ assert.equal(payload.optim, "adamw_8bit");
+
+ useTrainingConfigStore.getState().setTrainingMethod("lora");
+ const lora = buildTrainingStartPayload(
+ useTrainingConfigStore.getState(),
+ null,
+ );
+ assert.equal(lora.load_in_4bit, false);
+});
+
+test("a fresh Clef pick from full fine-tuning starts as QLoRA, a Laya pick as LoRA", async () => {
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.setState({ trainingMethod: "full" });
+ await selectClef();
+ assert.equal(useTrainingConfigStore.getState().trainingMethod, "qlora");
+
+ useTrainingConfigStore.getState().reset();
+ useTrainingConfigStore.setState({ trainingMethod: "qlora" });
+ await selectLaya();
+ assert.equal(useTrainingConfigStore.getState().trainingMethod, "lora");
+ assert.equal(useTrainingConfigStore.getState().decisionLayout, "laya");
+});
diff --git a/tests/test_decision_clef_head.py b/tests/test_decision_clef_head.py
new file mode 100644
index 00000000000..b12fdfe9bfb
--- /dev/null
+++ b/tests/test_decision_clef_head.py
@@ -0,0 +1,274 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+
+# Unsloth's batched Clef head against Cloudflare's per-record head (vendored unmodified).
+
+import hashlib
+import json
+import random
+from pathlib import Path
+
+import pytest
+from real_accelerator import has_real_cuda
+
+torch = pytest.importorskip("torch")
+
+from unsloth._vendor.clef import joint_schema_model as reference
+from unsloth.models import clef
+
+HIDDEN, WIDTH, VOCAB = 64, 32, 500
+VENDOR = Path(reference.__file__).parent
+
+
+def test_vendored_files_match_the_manifest():
+ manifest = json.loads((VENDOR / "clef_manifest.json").read_text(encoding = "utf-8"))
+ for name, digest in manifest["files"].items():
+ assert hashlib.sha256((VENDOR / name).read_bytes()).hexdigest() == digest, name
+
+
+def _records(seed, batch = 3):
+ rng = random.Random(seed)
+ records = []
+ for _ in range(batch):
+ length = rng.randint(130, 220)
+ ids = tuple(rng.randrange(VOCAB) for _ in range(length))
+ questions, position = [], 5
+ for q in range(rng.randint(1, 4)):
+ span = (position, position + rng.randint(1, 4))
+ position = span[1] + 1
+ options = []
+ for _ in range(2 if q % 3 == 0 else rng.randint(2, 6)):
+ options.append((position, position + rng.randint(1, 5)))
+ position = options[-1][1] + 1
+ questions.append(
+ reference.EncodedQuestion(
+ f"q{q}", q % 3, span, tuple(options), tuple(map(str, range(len(options))))
+ )
+ )
+ records.append(reference.EncodedRecord(ids, tuple(questions), "r"))
+ return records
+
+
+def _inputs(
+ seed,
+ dtype,
+ hidden_dtype = None,
+ scale = 3.0,
+):
+ torch.manual_seed(seed)
+ head = clef.JointSchemaHead(HIDDEN, WIDTH, 2, 2, 4, 64).to(dtype)
+ with torch.no_grad():
+ for parameter in head.parameters():
+ parameter.add_(torch.randn_like(parameter) * 0.05)
+ records = _records(seed)
+ length = max(len(r.input_ids) for r in records)
+ hidden = (torch.randn(len(records), length, HIDDEN, dtype = dtype) * scale + 1).to(
+ hidden_dtype or dtype
+ )
+ ids = torch.zeros(len(records), length, dtype = torch.long)
+ mask = torch.zeros(len(records), length, dtype = torch.long)
+ for b, record in enumerate(records):
+ ids[b, : len(record.input_ids)] = torch.tensor(record.input_ids)
+ mask[b, : len(record.input_ids)] = 1
+ embedding = torch.randn(VOCAB, HIDDEN, dtype = dtype)
+ return head, hidden, ids, mask, records, embedding
+
+
+def _padded(per_record, dtype):
+ flat = [question for record in per_record for question in record]
+ padded = torch.full((len(flat), max(len(z) for z in flat)), -1e4, dtype = dtype)
+ for i, z in enumerate(flat):
+ padded[i, : len(z)] = z
+ return padded
+
+
+def _run(head, forward, hidden, ids, mask, records, embedding, grad_out):
+ head.zero_grad()
+ hidden = hidden.clone().requires_grad_(True)
+ out = forward(hidden, ids, mask, records, embedding)
+ logits = out.flat_padded if hasattr(out, "flat_padded") else _padded(out, grad_out.dtype)
+ valid = logits > -1e3
+ (logits.to(grad_out.dtype) * grad_out * valid).sum().backward()
+ grads = {n: p.grad.clone() for n, p in head.named_parameters() if p.grad is not None}
+ return logits.detach(), hidden.grad.detach(), grads, valid
+
+
+def _max_error(a, b):
+ logits = (a[0] - b[0]).abs().max().item()
+ hidden = (a[1] - b[1]).abs().max().item()
+ grads = max(((a[2][n] - b[2][n]).abs().max()).item() for n in b[2])
+ return logits, hidden, grads
+
+
[email protected]("checkpoint", ["1", "0"])
[email protected]("seed", [0, 1])
+def test_batched_head_matches_cloudflares_head(monkeypatch, seed, checkpoint):
+ monkeypatch.setenv("UNSLOTH_CLEF_CHECKPOINT", checkpoint)
+ monkeypatch.setenv("UNSLOTH_CLEF_CHUNK", "16") # several chunks per row
+ results = {}
+ for dtype in (torch.float64, torch.float32):
+ head, hidden, ids, mask, records, embedding = _inputs(seed, dtype)
+ generator = torch.Generator().manual_seed(seed)
+ grad_out = torch.randn(
+ sum(len(r.questions) for r in records), _o(records), generator = generator
+ ).to(dtype)
+ ours = _run(head, head.forward, hidden, ids, mask, records, embedding, grad_out)
+ theirs = _run(
+ head,
+ lambda *a: reference.JointSchemaHead.forward(head, *a),
+ hidden,
+ ids,
+ mask,
+ records,
+ embedding,
+ grad_out,
+ )
+ assert torch.equal(ours[3], theirs[3])
+ results[dtype] = (ours, theirs)
+ # fp64: the same math up to summation order.
+ logits, hidden_grad, grads = _max_error(*results[torch.float64])
+ assert logits < 1e-12 and hidden_grad < 1e-12 and grads < 1e-10
+ # fp32: no further from the fp64 oracle than Cloudflare's own fp32 head, plus one rounding step.
+ oracle = results[torch.float64][1]
+ for index, tolerance in ((0, 1e-6), (1, 1e-7)):
+ ours_error = (results[torch.float32][0][index].double() - oracle[index]).abs().max().item()
+ theirs_error = (
+ (results[torch.float32][1][index].double() - oracle[index]).abs().max().item()
+ )
+ assert ours_error <= 1.5 * theirs_error + tolerance
+ assert torch.equal(
+ results[torch.float32][0][0].argmax(-1), results[torch.float32][1][0].argmax(-1)
+ )
+
+
+def _o(records):
+ return max(len(q.option_spans) for r in records for q in r.questions)
+
+
+def test_negative_control_is_caught():
+ head, hidden, ids, mask, records, embedding = _inputs(0, torch.float64)
+ grad_out = torch.randn(sum(len(r.questions) for r in records), _o(records), dtype = torch.float64)
+ ours = _run(head, head.forward, hidden, ids, mask, records, embedding, grad_out)
+ theirs = _run(
+ head,
+ lambda *a: reference.JointSchemaHead.forward(head, *a),
+ hidden,
+ ids,
+ mask,
+ records,
+ embedding,
+ grad_out,
+ )
+ perturbed = (ours[0] * (1 + 2**-7), *ours[1:])
+ assert _max_error(perturbed, theirs)[0] > 1e-6
+
+
[email protected]("hidden_dtype", [torch.float16, torch.bfloat16])
+def test_16bit_hidden_states_into_fp32_head(monkeypatch, hidden_dtype):
+ monkeypatch.setenv("UNSLOTH_CLEF_CHUNK", "16")
+ # Large but finite fp16 activations, as a Qwen3.5 backbone produces.
+ head, hidden, ids, mask, records, embedding = _inputs(
+ 2, torch.float32, hidden_dtype, scale = 1e4 if hidden_dtype == torch.float16 else 3.0
+ )
+ embedding = embedding.to(hidden_dtype)
+ assert torch.isfinite(hidden).all() and hidden.abs().max() > 1e3 ** (
+ hidden_dtype == torch.float16
+ )
+ grad_out = torch.randn(sum(len(r.questions) for r in records), _o(records))
+ ours = _run(head, head.forward, hidden, ids, mask, records, embedding, grad_out)
+ theirs = _run(head, head.forward_per_record, hidden, ids, mask, records, embedding, grad_out)
+ assert torch.isfinite(ours[0]).all() and torch.isfinite(ours[1].float()).all()
+ logits, _, grads = _max_error(ours, theirs)
+ assert logits < 1e-4 and grads < 1e-3
+ assert ours[1].dtype == hidden_dtype
+ assert torch.equal(ours[0].argmax(-1), theirs[0].argmax(-1))
+
+
+def test_kill_switch_runs_the_per_record_head(monkeypatch):
+ head, hidden, ids, mask, records, embedding = _inputs(0, torch.float32)
+ fast = head(hidden, ids, mask, records, embedding)
+ monkeypatch.setenv("UNSLOTH_CLEF_FAST", "0")
+ slow = head(hidden, ids, mask, records, embedding)
+ assert hasattr(fast, "flat_padded") and not hasattr(slow, "flat_padded")
+ for a, b in zip(fast, slow):
+ for x, y in zip(a, b):
+ torch.testing.assert_close(x, y, rtol = 1e-5, atol = 1e-6)
+
+
+def test_compile_gating(monkeypatch):
+ import torch.utils._triton as triton_utils
+
+ monkeypatch.setattr(triton_utils, "has_triton", lambda: True)
+ assert not clef._compile_supported(torch.device("cpu"))
+ assert clef._compile_supported(torch.device("cuda"))
+ # ROCm reports cuda devices: compiled when its Triton is present.
+ monkeypatch.setattr(torch.version, "hip", "6.4", raising = False)
+ assert clef._compile_supported(torch.device("cuda"))
+ # Windows ROCm / CUDA wheels without Triton: eager.
+ monkeypatch.setattr(triton_utils, "has_triton", lambda: False)
+ assert not clef._compile_supported(torch.device("cuda"))
+ monkeypatch.setattr(triton_utils, "has_triton", lambda: True)
+ monkeypatch.setenv("UNSLOTH_CLEF_COMPILE", "0")
+ assert not clef._compile_supported(torch.device("cuda"))
+
+
+def test_a_failed_compile_falls_back_to_eager(monkeypatch):
+ head, hidden, ids, mask, records, embedding = _inputs(1, torch.float32)
+ expected = head(hidden, ids, mask, records, embedding).flat_padded
+
+ def broken(*args):
+ raise RuntimeError("inductor failed")
+
+ monkeypatch.setattr(clef, "_compiled_logits", lambda device: broken)
+ monkeypatch.setenv("UNSLOTH_CLEF_COMPILE", "1")
+ head.train()
+ with pytest.warns(UserWarning, match = "running it eagerly"):
+ got = head(hidden, ids, mask, records, embedding).flat_padded
+ torch.testing.assert_close(got, expected)
+ assert clef.os.environ["UNSLOTH_CLEF_COMPILE"] == "0"
+
+
+ not has_real_cuda(), reason = "Inductor CPU codegen for the head takes over 5 minutes"
+)
+def test_compiled_head_has_no_graph_breaks_and_matches(monkeypatch):
+ from torch._dynamo.utils import counters
+
+ cases = []
+ # As the head's forward does: once Unsloth has patched torch's checkpoint (any model load in
+ # this process), compiling needs torch's own one back.
+ with clef._torch_checkpoint(True):
+ for seed in (0, 1, 2):
+ head, hidden, ids, mask, records, embedding = _inputs(seed, torch.float32)
+ layout = clef.build_layout(records, hidden.device)
+ eager = clef.batched_logits(head, hidden, embedding, layout, True, 16)
+ cases.append((head, hidden, embedding, layout, eager))
+ # Eager references first: after a model load Unsloth's patched layer_norm compiles itself
+ # when called eagerly, which would add its own graphs to the count.
+ torch._dynamo.reset()
+ counters.clear()
+ compiled = torch.compile(clef.batched_logits, fullgraph = True, dynamic = True)
+ for head, hidden, embedding, layout, eager in cases:
+ got = compiled(head, hidden, embedding, layout, True, 16)
+ torch.testing.assert_close(got, eager, rtol = 1e-5, atol = 1e-5)
+ assert not counters["graph_break"]
+ # Three batches of different shapes, one graph.
+ assert counters["stats"]["unique_graphs"] == 1
+
+
+def test_autocast_matches_the_per_record_head(monkeypatch):
+ # Training runs the head under bf16 autocast: the chunked memory projection must run in bf16
+ # like the Linear it replaces, the norm and span means in fp32.
+ monkeypatch.setenv("UNSLOTH_CLEF_CHUNK", "16")
+ head, hidden, ids, mask, records, embedding = _inputs(3, torch.float32, torch.bfloat16)
+ embedding = embedding.to(torch.bfloat16)
+ grad_out = torch.randn(sum(len(r.questions) for r in records), _o(records))
+ with torch.autocast("cpu", dtype = torch.bfloat16):
+ ours = _run(head, head.forward, hidden, ids, mask, records, embedding, grad_out)
+ theirs = _run(
+ head, head.forward_per_record, hidden, ids, mask, records, embedding, grad_out
+ )
+ logits, _, grads = _max_error(ours, theirs)
+ scale = theirs[0][theirs[3]].abs().max().item()
+ assert logits <= 2e-2 * scale and grads < 5e-2
+ assert torch.equal(ours[0].argmax(-1), theirs[0].argmax(-1))
diff --git a/tests/test_decision_model.py b/tests/test_decision_model.py
new file mode 100644
index 00000000000..c8348e664f3
--- /dev/null
+++ b/tests/test_decision_model.py
@@ -0,0 +1,1289 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.
+
+import copy
+import json
+import math
+import sys
+import types
+from pathlib import Path
+
+import pytest
+from real_accelerator import has_real_cuda
+
+torch = pytest.importorskip("torch")
+
+from transformers import TrainerCallback, TrainingArguments
+
+from unsloth import DecisionTrainer, FastDecisionModel
+from unsloth.models import decision
+from unsloth.models.decision import (
+ DecisionDataCollator,
+ DecisionDataError,
+ _LengthGroupedBatches,
+ _laya,
+ _target,
+)
+
+laya = _laya()
+# Every word the states, questions and options use, so the toy task below is learnable.
+WORDS = (
+ "the server is down again refund my card charge twice please help now noul choice score "
+ "question : ? , does this need a reply which team should handle it how upset customer outage "
+ "service billing charges and refunds level 0 1 2 calm annoyed angry false no statement not hold "
+ "true yes holds"
+).split()
+QUESTIONS = {
+ "urgent": {"type": "noul", "instructions": "Does this need a reply now?"},
+ "team": {
+ "type": "choice",
+ "instructions": "Which team should handle it?",
+ "criteria": {"outage": "service down", "billing": "charges and refunds"},
+ },
+ "mood": {
+ "type": "score",
+ "instructions": "How upset is the customer?",
+ "criteria": ["calm", "annoyed", "angry"],
+ },
+}
+
+
+def _row(i):
+ outage = i % 2 == 0
+ return {
+ "state": "the server is down again help now" if outage else "refund my card charge twice",
+ "questions": QUESTIONS,
+ "gold": {
+ "urgent": {"label": "true" if outage else "false"},
+ "team": {"label": "outage" if outage else "billing"},
+ "mood": 2 if outage else 0,
+ },
+ }
+
+
+def _args(tmp_path, **overrides):
+ return TrainingArguments(
+ **{
+ "output_dir": str(tmp_path / "run"),
+ "per_device_train_batch_size": 8,
+ "max_steps": 4,
+ "learning_rate": 1e-3,
+ "report_to": "none",
+ "save_strategy": "no",
+ **overrides,
+ }
+ )
+
+
+def _tiny_encoder_config(**rope):
+ from transformers import ModernBertConfig
+
+ config = ModernBertConfig(
+ vocab_size = 64,
+ hidden_size = 64,
+ intermediate_size = 96,
+ num_hidden_layers = 2,
+ num_attention_heads = 4,
+ pad_token_id = 0,
+ cls_token_id = 2,
+ sep_token_id = 1,
+ global_attn_every_n_layers = 2,
+ local_attention = 16,
+ ).to_dict()
+ for key in ("rope_parameters", "global_rope_theta", "local_rope_theta", "rope_theta"):
+ config.pop(key, None)
+ return {**config, **rope}
+
+
+def checkpoint(tmp_path):
+ from safetensors.torch import save_file
+ from tokenizers import Tokenizer, models, normalizers, pre_tokenizers
+ from transformers import PreTrainedTokenizerFast
+
+ specials = ["[PAD]", "[SEP]", "[CLS]", "[UNK]", "[MASK]"]
+ vocab = {token: i for i, token in enumerate(specials + sorted(set(WORDS)))}
+ tokenizer = Tokenizer(models.WordLevel(vocab, unk_token = "[UNK]"))
+ tokenizer.normalizer = normalizers.Lowercase()
+ tokenizer.pre_tokenizer = pre_tokenizers.Whitespace()
+ PreTrainedTokenizerFast(
+ tokenizer_object = tokenizer,
+ pad_token = "[PAD]",
+ sep_token = "[SEP]",
+ cls_token = "[CLS]",
+ unk_token = "[UNK]",
+ mask_token = "[MASK]",
+ ).save_pretrained(str(tmp_path / "base" / "tokenizer"))
+ (tmp_path / "base" / "encoder").mkdir()
+ # The layout transformers 5 writes, as the published Laya checkpoints have it.
+ (tmp_path / "base" / "encoder" / "config.json").write_text(
+ json.dumps(
+ _tiny_encoder_config(
+ rope_parameters = {
+ "full_attention": {"rope_theta": 160000.0, "rope_type": "default"},
+ "sliding_attention": {"rope_theta": 160000.0, "rope_type": "default"},
+ }
+ ),
+ indent = 2,
+ )
+ )
+ config = {
+ "encoder": "tiny",
+ "head_layers": 1,
+ "act_costs": {"escalate": 0.5},
+ "max_len": 96,
+ "head_max_len": 48,
+ "temperature": [1.2, 1.1, 1.3],
+ "temperature_by_options": {"noul:2": 0.7, "score:3-5": 0.9},
+ "training": {"updates": 1000},
+ }
+ torch.manual_seed(0)
+ model = laya.common.build_model(config, encoder_dir = str(tmp_path / "base" / "encoder"))
+ save_file(
+ {k: v.half().contiguous() for k, v in model.state_dict().items()},
+ str(tmp_path / "base" / "model.safetensors"),
+ )
+ (tmp_path / "base" / "rl_agent_config.json").write_text(json.dumps(config))
+ return tmp_path / "base"
+
+
+def fresh_laya():
+ decision._laya.cache_clear()
+ yield
+ decision._laya.cache_clear()
+
+
+def test_laya_is_the_copy_vendored_with_unsloth(monkeypatch, fresh_laya):
+ # A pip installed laya (0.3.9+ has no agent or common attributes) is ignored and left in place.
+ pip_laya = types.ModuleType("laya")
+ monkeypatch.setitem(sys.modules, "laya", pip_laya)
+ vendored = decision._laya()
+ assert vendored is not pip_laya and sys.modules["laya"] is pip_laya
+ assert Path(vendored.__file__).resolve() == decision._VENDORED_LAYA
+ assert vendored.__version__ == "0.3.5" and hasattr(vendored.agent.Agent, "_to_internal")
+ # Studio registers the same files as "laya" before training, and that module is the one used.
+ studio_laya = types.ModuleType("laya")
+ studio_laya.__file__ = str(decision._VENDORED_LAYA)
+ monkeypatch.setitem(sys.modules, "laya", studio_laya)
+ decision._laya.cache_clear()
+ assert decision._laya() is studio_laya
+
+
+def test_missing_vendored_laya_is_a_clear_error(monkeypatch, tmp_path, fresh_laya):
+ monkeypatch.setattr(decision, "_VENDORED_LAYA", tmp_path / "laya" / "__init__.py")
+ with pytest.raises(ImportError, match = "Unsloth: decision models need laya"):
+ decision._laya()
+
+
+def test_gold_labels_and_probabilities():
+ noul, team, mood = (
+ laya.agent.Agent._to_internal(QUESTIONS[n]) for n in ("urgent", "team", "mood")
+ )
+ assert _target(noul, {"probabilities": {"true": 0.3}}) == ([pytest.approx(0.7), 0.3], 0)
+ assert _target(noul, {"noul": 0.8}) == ([pytest.approx(0.2), 0.8], 1)
+ assert _target(team, {"probabilities": {"outage": 3, "billing": 1}}) == ([0.75, 0.25], 0)
+ for label in (True, "TRUE", "True", " true"):
+ assert _target(noul, label) == ([0.0, 1.0], 1)
+ for label in (2, 2.0, "2", "2.0"):
+ assert _target(mood, {"label": label}) == ([0.0, 0.0, 1.0], 2)
+ unusable = [
+ (mood, {"label": 2.5}),
+ (mood, {"label": True}),
+ (mood, math.inf),
+ (mood, {"label": math.nan}),
+ (noul, 1),
+ (noul, {"noul": math.inf}),
+ (noul, {"probabilities": {"true": math.inf}}),
+ (team, {"probabilities": {"outage": math.nan, "billing": 1}}),
+ ]
+ for internal, gold in unusable:
+ with pytest.raises(DecisionDataError):
+ _target(internal, gold)
+
+
+def test_temperature_fit_finds_the_temperature_of_the_soft_gold():
+ # softmax([2, 0] / T) is [0.6, 0.4] at T = 2 / ln(1.5).
+ logits = [torch.tensor([2.0, 0.0])] * 10
+ items = [{"target": [0.6, 0.4]}] * 10
+ assert decision._fit_temperature(logits, items) == pytest.approx(2 / math.log(1.5), rel = 1e-2)
+
+
+def test_dataset_skips_bad_rows_and_names_the_most_common_reason(checkpoint):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ assert model.decision_config["max_len"] == 1024
+ assert model.decision_config["head_max_len"] == 256
+ assert "training" not in model.decision_config
+
+ nested = {**QUESTIONS, "team": {**QUESTIONS["team"], "criteria": [["outage"], ["billing"]]}}
+ numbered = {**QUESTIONS, "team": {**QUESTIONS["team"], "criteria": [1, 2]}}
+ rows = [
+ {**_row(0), "gold": {"urgent": "true", "team": "outage"}},
+ *[{**_row(i), "questions": nested} for i in range(1, 4)],
+ {**_row(4), "questions": numbered},
+ "not a row",
+ {**_row(6), "gold": {**_row(6)["gold"], "urgent": {"noul": math.inf}}},
+ {**_row(7), "gold": {**_row(7)["gold"], "mood": 1.5}},
+ {"state": "x", "questions": "{}", "gold": {}},
+ *[_row(i) for i in range(9, 30)],
+ ]
+ items, report = FastDecisionModel.build_dataset(rows, tokenizer, model)
+ assert report["total"] == 3 * 28 + 1 and report["skipped"] == 8
+ assert len(items) == report["total"] - report["skipped"]
+ assert (
+ report["reason"] == 'row 2: "team" needs criteria naming its options (and 3 more like it)'
+ )
+
+ batch = DecisionDataCollator(tokenizer.pad_token_id)(items[-3:])
+ assert batch["marker_mask"].sum(-1).tolist() == [2, 2, 3]
+ assert torch.allclose(batch["target"].sum(-1), torch.ones(3))
+
+
+def test_holdout_takes_whole_rows_and_never_overshoots():
+ items = [{"row": row} for row in range(50) for _ in range(3)]
+ train, held = FastDecisionModel.split_holdout(items, 3407)
+ assert len(held) == 15 and not {i["row"] for i in train} & {i["row"] for i in held}
+ # One row with 100 decisions among single-decision rows: the target is 10.
+ items = [{"row": row} for row, size in enumerate([1] * 9 + [100]) for _ in range(size)]
+ for seed in range(20):
+ train, held = FastDecisionModel.split_holdout(items, seed)
+ assert len(held) <= 10 and len(train) >= 100
+ single = [{"row": 0}, {"row": 0}]
+ assert FastDecisionModel.split_holdout(single, 3407, fraction = 0.5) == (single, [])
+
+
+def test_full_finetuning_trains_every_weight(checkpoint, capsys):
+ model, _ = FastDecisionModel.from_pretrained(
+ str(checkpoint), full_finetuning = True, use_gradient_checkpointing = False
+ )
+ assert all(p.requires_grad and p.dtype == torch.float32 for p in model.parameters())
+ assert FastDecisionModel.get_peft_model(model) is model
+ assert "Full finetuning is enabled" in capsys.readouterr().out
+ assert not hasattr(model.encoder, "peft_config")
+ with pytest.raises(NotImplementedError, match = "16-bit"):
+ FastDecisionModel.from_pretrained(str(checkpoint), load_in_4bit = True)
+
+
+def test_lora_freezes_a_16_bit_encoder_and_trains_the_head_in_fp32(checkpoint):
+ model, _ = FastDecisionModel.from_pretrained(str(checkpoint), use_gradient_checkpointing = False)
+ stored = torch.float32 if decision._device().type == "cpu" else torch.float16
+ assert {p.dtype for p in model.encoder.parameters()} == {stored}
+ assert not any(p.requires_grad for p in model.encoder.parameters())
+ head = [p for n, p in model.named_parameters() if not n.startswith("encoder.")]
+ assert head and all(p.requires_grad and p.dtype == torch.float32 for p in head)
+
+ model, _ = FastDecisionModel.from_pretrained(
+ str(checkpoint), dtype = torch.float16, use_gradient_checkpointing = False
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 4, lora_alpha = 4)
+ lora = [p for n, p in model.named_parameters() if "lora_" in n]
+ assert lora and all(p.requires_grad and p.dtype == torch.float32 for p in lora)
+ frozen = [p for n, p in model.encoder.named_parameters() if "lora_" not in n]
+ assert all(not p.requires_grad and p.dtype == torch.float16 for p in frozen)
+ assert all(b.dtype == torch.float32 for b in model.encoder.buffers() if b.is_floating_point())
+ targets = {n.split(".")[-1] for n, m in model.encoder.named_modules() if hasattr(m, "lora_A")}
+ assert targets == {"Wqkv", "Wo", "Wi"}
+ with pytest.raises(RuntimeError, match = "already added LoRA"):
+ FastDecisionModel.get_peft_model(model)
+
+
[email protected]("lora", [True, False])
+def test_head_learning_rate_and_weight_decay(checkpoint, tmp_path, lora):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), full_finetuning = not lora, use_gradient_checkpointing = False
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 4, lora_alpha = 4)
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(4)], tokenizer, model)
+ names = {id(p): n for n, p in model.named_parameters()}
+ no_decay = {
+ f"{prefix}.{name}"
+ for prefix, module in model.named_modules()
+ for name, _ in module.named_parameters(recurse = False)
+ if isinstance(module, torch.nn.LayerNorm) or name.endswith("bias")
+ }
+ for head_learning_rate, head_lr in ((None, 1e-4), (0.0, 0.0)):
+ trainer = DecisionTrainer(
+ model = model,
+ args = _args(tmp_path, learning_rate = 8e-4, weight_decay = 0.01),
+ train_dataset = items,
+ processing_class = tokenizer,
+ head_learning_rate = head_learning_rate,
+ )
+ optimizer = trainer.create_optimizer()
+ grouped = [
+ (names[id(p)], group) for group in optimizer.param_groups for p in group["params"]
+ ]
+ assert {name for name, _ in grouped} == {
+ n for n, p in model.named_parameters() if p.requires_grad
+ }
+ for name, group in grouped:
+ assert group["lr"] == (8e-4 if name.startswith("encoder.") else head_lr)
+ assert group["weight_decay"] == (0.0 if name in no_decay else 0.01)
+
+
+def test_length_grouping_only_with_gradient_accumulation(checkpoint, tmp_path):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(8)], tokenizer, model)
+ for accumulation in (1, 4):
+ trainer = DecisionTrainer(
+ model = model,
+ args = _args(tmp_path, gradient_accumulation_steps = accumulation),
+ train_dataset = items,
+ processing_class = tokenizer,
+ )
+ assert isinstance(trainer._get_train_sampler(), _LengthGroupedBatches) == (accumulation > 1)
+
+
+def test_length_grouped_batches_mix_lengths_and_replay_an_epoch():
+ lengths = [10] * 64 + [500] * 64
+ sampler = _LengthGroupedBatches(lengths, 8, 3407)
+ order = list(sampler)
+ assert sorted(order) == list(range(128))
+ batches = [order[i : i + 8] for i in range(0, 128, 8)]
+ assert all(len({lengths[i] for i in batch}) == 1 for batch in batches)
+ assert lengths[batches[0][0]] == 500
+ assert {lengths[i] for batch in batches[:8] for i in batch} == {10, 500}
+ # The order depends only on the epoch, so a resumed run replays the epoch it stopped in.
+ assert list(sampler) == order
+ sampler.set_epoch(1)
+ assert list(sampler) != order
+ sampler.set_epoch(0)
+ assert list(sampler) == order
+
+
[email protected]("lora", [True, False])
+def test_train_calibrate_save_and_serve(checkpoint, tmp_path, lora):
+ from safetensors.torch import load_file
+
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), full_finetuning = not lora, use_gradient_checkpointing = False
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 4, lora_alpha = 4)
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(80)], tokenizer, model)
+ train, held = FastDecisionModel.split_holdout(items, 3407, fraction = 0.5)
+ midway = {}
+
+ class SaveMidway(TrainerCallback):
+ def on_step_end(
+ self,
+ args,
+ state,
+ control,
+ model = None,
+ **kwargs,
+ ):
+ if state.global_step == 2:
+ model.save_pretrained_merged(tmp_path / "midway")
+ midway.update(
+ {n: p.detach().clone() for n, p in model.named_parameters() if p.requires_grad}
+ )
+
+ def accuracy(prediction):
+ hits = prediction.predictions.argmax(-1) == prediction.label_ids.argmax(-1)
+ return {"accuracy": float(hits.mean())}
+
+ trainer = DecisionTrainer(
+ model = model,
+ args = _args(tmp_path),
+ train_dataset = train,
+ eval_dataset = held,
+ tokenizer = tokenizer,
+ compute_metrics = accuracy,
+ callbacks = [SaveMidway()],
+ )
+ trainer.train()
+ # Saving midway kept the adapters on the model, so the steps after it still trained them.
+ assert decision.is_decision_checkpoint(tmp_path / "midway")
+ after = dict(model.named_parameters())
+ assert set(midway) <= set(after)
+ assert any(not torch.equal(after[n], p) for n, p in midway.items() if n.startswith("encoder."))
+
+ metrics = trainer.evaluate()
+ assert metrics["eval_loss"] > 0 and 0 <= metrics["eval_accuracy"] <= 1
+ assert trainer.predict(held).predictions.shape == (len(held), 3)
+
+ calibrated = FastDecisionModel.calibrate(model, tokenizer, held)
+ assert calibrated["fitted_types"] == [0, 1, 2] and 0 <= calibrated["accuracy"] <= 1
+ assert model.decision_config["temperature"] != [1.2, 1.1, 1.3]
+ assert "temperature_by_options" not in model.decision_config
+
+ model.decision_config["training"] = {"steps": 4}
+ model.save_pretrained_merged(tmp_path / "out")
+ saved = json.loads((tmp_path / "out" / "rl_agent_config.json").read_text())
+ assert saved["fine_tuned"] is True and saved["training"] == {"steps": 4}
+ assert saved["temperature"] == model.decision_config["temperature"]
+ encoder_config = (checkpoint / "encoder" / "config.json").read_bytes()
+ assert (tmp_path / "out" / "encoder" / "config.json").read_bytes() == encoder_config
+ agent = laya.load(str(tmp_path / "out"), device = "cpu")
+ assert agent.predict("the server is down again", QUESTIONS)["answers"]["team"]["choice"] in (
+ "outage",
+ "billing",
+ )
+
+ FastDecisionModel.for_inference(model)
+ assert not model.training
+ FastDecisionModel.for_training(model)
+ assert model.training
+ weights = load_file(str(tmp_path / "out" / "model.safetensors"))
+ merged = model.encoder.merge_and_unload() if lora else model.encoder
+ expected = {f"encoder.{k}": v for k, v in merged.state_dict().items()}
+ expected.update((k, v) for k, v in model.state_dict().items() if not k.startswith("encoder."))
+ assert weights.keys() == expected.keys()
+ assert all(torch.equal(weights[k], v.detach().cpu().half()) for k, v in expected.items())
+
+
+def test_a_resized_laya_vocabulary_saves_and_reloads(checkpoint, tmp_path):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ grown = model.encoder.get_input_embeddings().num_embeddings + 8
+ # The fixture's vocab equals its hidden size, so the covariance mean resizing samples from
+ # is singular and can come out NaN on some GPUs.
+ model.encoder.resize_token_embeddings(grown, mean_resizing = False)
+ model.save_pretrained_merged(str(tmp_path / "out"), tokenizer)
+ reloaded, _ = FastDecisionModel.from_pretrained(str(tmp_path / "out"))
+ assert reloaded.encoder.get_input_embeddings().num_embeddings == grown
+
+
+def test_full_clef_finetuning_never_quantizes_the_backbone(tmp_path, monkeypatch):
+ from unsloth.models import loader
+
+ seen = []
+
+ class Captured(Exception):
+ pass
+
+ def capture(*args, **kwargs):
+ seen.append(kwargs)
+ raise Captured
+
+ monkeypatch.setattr(decision, "_device", lambda: torch.device("cuda"))
+ monkeypatch.setattr(loader.FastModel, "from_pretrained", capture)
+ for full in (True, False):
+ with pytest.raises(Captured):
+ decision._load_clef(tmp_path, None, torch.bfloat16, True, full, None, False, {})
+ assert seen[0].get("quantization_config") is None
+ assert seen[1].get("quantization_config") is not None
+
+
+def test_clef_backbone_stays_on_one_device_unless_the_caller_places_it(tmp_path, monkeypatch):
+ from unsloth.models import loader, loader_utils
+
+ seen = []
+
+ class Captured(Exception):
+ pass
+
+ def capture(*args, **kwargs):
+ seen.append(kwargs.get("device_map"))
+ raise Captured
+
+ monkeypatch.setattr(decision, "_device", lambda: torch.device("cuda"))
+ monkeypatch.setattr(loader.FastModel, "from_pretrained", capture)
+ index = torch.cuda.current_device() if torch.cuda.is_available() else 0
+ for kwargs in ({}, {"device_map": None}, {"device_map": "auto"}):
+ with pytest.raises(Captured):
+ decision._load_clef(tmp_path, None, torch.bfloat16, False, False, None, False, kwargs)
+ monkeypatch.setattr(loader_utils, "prepare_device_map", lambda: ({"": "cuda:1"}, True))
+ with pytest.raises(Captured):
+ decision._load_clef(tmp_path, None, torch.bfloat16, False, False, None, False, {})
+ assert seen == [{"": f"cuda:{index}"}, {"": f"cuda:{index}"}, "auto", {"": "cuda:1"}]
+
+
+def test_toy_task_beats_the_base_model(checkpoint, tmp_path, monkeypatch):
+ # On CPU everywhere: the toy task plateaus near loss 0.45 and leaves it by step ~70 on CPU but
+ # only after ~100 steps on a GPU (same curve otherwise, any precision), so 80 steps is a threshold
+ # tuned to CPU arithmetic, not a GPU defect.
+ monkeypatch.setattr(decision, "_device", lambda: torch.device("cpu"))
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 8, lora_alpha = 16)
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(120)], tokenizer, model)
+ train, held = FastDecisionModel.split_holdout(items, 3407, fraction = 0.25)
+ base = FastDecisionModel.evaluate(model, tokenizer, held)
+ DecisionTrainer(
+ model = model,
+ args = _args(
+ tmp_path,
+ max_steps = 80,
+ learning_rate = 5e-3,
+ per_device_train_batch_size = 16,
+ use_cpu = True,
+ ),
+ train_dataset = train,
+ processing_class = tokenizer,
+ head_learning_rate = 5e-3,
+ ).train()
+ tuned = FastDecisionModel.evaluate(model, tokenizer, held)
+ # The random base can already score high on some transformers versions; 1.0 is the ceiling.
+ assert tuned["accuracy"] >= min(base["accuracy"] + 0.25, 1.0)
+ assert tuned["loss"] < base["loss"] / 2
+
+
+def test_trainer_leaves_the_callers_arguments_alone(checkpoint, tmp_path, monkeypatch):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ items, _ = FastDecisionModel.build_dataset([_row(i) for i in range(4)], tokenizer, model)
+ args = _args(tmp_path, max_steps = 1, gradient_checkpointing = True)
+ trainer = DecisionTrainer(model = model, args = args, train_dataset = items)
+ assert args.remove_unused_columns is True and args.label_names is None
+ assert args.gradient_checkpointing is True
+ trainer.train()
+ assert model.encoder.is_gradient_checkpointing
+ # Without arguments, as Trainer allows.
+ monkeypatch.chdir(tmp_path)
+ trainer = DecisionTrainer(model = model, train_dataset = items, processing_class = tokenizer)
+ batch = next(iter(trainer.get_train_dataloader()))
+ assert {"marker_pos", "marker_mask", "target"} <= set(batch)
+
+
+def test_for_training_turns_gradient_checkpointing_back_on(checkpoint):
+ model, _ = FastDecisionModel.from_pretrained(str(checkpoint), use_gradient_checkpointing = False)
+ assert not model.encoder.is_gradient_checkpointing
+ FastDecisionModel.for_training(model)
+ assert model.training and model.encoder.is_gradient_checkpointing
+ FastDecisionModel.for_training(model, use_gradient_checkpointing = False)
+ assert not model.encoder.is_gradient_checkpointing
+
+
+def test_trainer_uses_one_gpu_and_the_set_batch_on_a_multi_gpu_machine(checkpoint, tmp_path):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ args = _args(tmp_path, max_steps = 1)
+ args._n_gpu = 2
+ trainer = DecisionTrainer(model = model, args = args, processing_class = tokenizer)
+ assert trainer.args.n_gpu == 1 and args.n_gpu == 2
+ assert trainer.args.train_batch_size == args.per_device_train_batch_size
+ assert trainer._wrap_model(model) is model
+
+
[email protected](not has_real_cuda(), reason = "measures GPU memory")
+def test_lora_save_does_not_copy_the_encoder_on_the_gpu(checkpoint, tmp_path):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 8, lora_alpha = 16)
+ torch.cuda.synchronize()
+ before = torch.cuda.memory_allocated()
+ torch.cuda.reset_peak_memory_stats()
+ model.save_pretrained_merged(tmp_path / "out", tokenizer)
+ torch.cuda.synchronize()
+ assert torch.cuda.max_memory_allocated() <= before
+ assert next(model.encoder.parameters()).is_cuda and hasattr(model.encoder, "peft_config")
+
+
+def test_save_refuses_weights_float16_cannot_hold(checkpoint, tmp_path):
+ model, _ = FastDecisionModel.from_pretrained(
+ str(checkpoint), full_finetuning = True, use_gradient_checkpointing = False
+ )
+ model.save_pretrained_merged(tmp_path / "out")
+ with torch.no_grad():
+ model.scorer[1].weight[0, 0] = 7e4
+ with pytest.raises(ValueError, match = "float16"):
+ model.save_pretrained_merged(tmp_path / "out")
+ assert decision.is_decision_checkpoint(tmp_path / "out")
+
+
+def test_push_to_hub_merged_uploads_a_complete_checkpoint(checkpoint, monkeypatch):
+ import huggingface_hub
+
+ pushed = {}
+
+ class Api:
+ def __init__(self, token = None):
+ pushed["token"] = token
+
+ def create_repo(
+ self,
+ repo_id,
+ private = None,
+ exist_ok = False,
+ ):
+ pushed["private"] = private
+ return types.SimpleNamespace(repo_id = f"me/{repo_id}")
+
+ def upload_folder(self, folder_path, repo_id, **kwargs):
+ pushed["repo_id"] = repo_id
+ pushed["complete"] = decision.is_decision_checkpoint(folder_path)
+
+ monkeypatch.setattr(huggingface_hub, "HfApi", Api)
+ model, _ = FastDecisionModel.from_pretrained(str(checkpoint), use_gradient_checkpointing = False)
+ model.push_to_hub_merged("laya-ft", token = "hf_token", private = True)
+ assert pushed == {
+ "token": "hf_token",
+ "private": True,
+ "repo_id": "me/laya-ft",
+ "complete": True,
+ }
+
+
+def test_gradient_accumulation_matches_one_large_batch(checkpoint, tmp_path):
+ grads = {}
+
+ class Grab(TrainerCallback):
+ def __init__(self, key):
+ self.key = key
+
+ def on_pre_optimizer_step(
+ self,
+ args,
+ state,
+ control,
+ model = None,
+ **kwargs,
+ ):
+ grads[self.key] = torch.cat(
+ [p.grad.flatten() for p in model.parameters() if p.grad is not None]
+ )
+
+ for lora in (False, True):
+ for accumulation in (1, 4):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint),
+ full_finetuning = not lora,
+ dtype = torch.float32,
+ use_gradient_checkpointing = False,
+ )
+ model = FastDecisionModel.get_peft_model(model, r = 4, lora_alpha = 4)
+ model.eval()
+ items, _ = FastDecisionModel.build_dataset(
+ [_row(i) for i in range(16)], tokenizer, model
+ )
+ trainer = DecisionTrainer(
+ model = model,
+ args = _args(
+ tmp_path,
+ per_device_train_batch_size = 48 // accumulation,
+ gradient_accumulation_steps = accumulation,
+ max_steps = 1,
+ max_grad_norm = 0.0,
+ use_cpu = True,
+ ),
+ train_dataset = items,
+ processing_class = tokenizer,
+ callbacks = [Grab((lora, accumulation))],
+ )
+ trainer.model.train = lambda mode = True: trainer.model
+ trainer.train()
+ torch.testing.assert_close(grads[(lora, 1)], grads[(lora, 4)], rtol = 1e-3, atol = 1e-6)
+
+
+def test_rope_parameters_build_the_trained_rope_on_every_transformers(tmp_path):
+ from transformers import AutoModel
+
+ def build(name, **rope):
+ folder = tmp_path / name
+ folder.mkdir()
+ (folder / "config.json").write_text(json.dumps(_tiny_encoder_config(**rope)))
+ return AutoModel.from_config(decision._encoder_config(folder), attn_implementation = "sdpa")
+
+ def rope_parameters(sliding):
+ return {
+ "full_attention": {"rope_theta": 160000.0, "rope_type": "default"},
+ "sliding_attention": {"rope_theta": sliding, "rope_type": "default"},
+ }
+
+ # How transformers 5 saves mmBERT, the same with both key styles, and with the 10000 default.
+ saved = build("saved", rope_parameters = rope_parameters(160000.0))
+ both = build(
+ "both",
+ rope_parameters = rope_parameters(160000.0),
+ global_rope_theta = 160000.0,
+ local_rope_theta = 160000.0,
+ )
+ default = build(
+ "default",
+ rope_parameters = rope_parameters(10000.0),
+ global_rope_theta = 160000.0,
+ local_rope_theta = 10000.0,
+ )
+ with torch.no_grad():
+ # Random weights attend almost uniformly, which hides the rotary angles; sharpen the attention.
+ for name, weight in saved.named_parameters():
+ if name.endswith("Wqkv.weight"):
+ weight.mul_(10)
+ for model in (both, default):
+ model.load_state_dict(saved.state_dict())
+ ids = torch.randint(5, 64, (2, 24))
+ outputs = [model.eval()(input_ids = ids).last_hidden_state for model in (saved, both, default)]
+ torch.testing.assert_close(outputs[0], outputs[1])
+ assert not torch.allclose(outputs[0], outputs[2], atol = 1e-2)
+
+
+TINY_QWEN3_5 = "trl-internal-testing/tiny-Qwen3_5ForConditionalGeneration"
+CLEF_HEAD = {
+ "hidden_size": 16,
+ "width": 32,
+ "routing_layers": 1,
+ "layers": 1,
+ "heads": 4,
+ "feedforward": 64,
+}
+
+
+def _clef_reference():
+ from huggingface_hub import hf_hub_download
+
+ try:
+ path = hf_hub_download("Cloudflare/clef-flash", "joint_schema_model.py")
+ except Exception as exc:
+ pytest.skip(f"Clef reference code unavailable: {exc}")
+ import importlib.util
+
+ spec = importlib.util.spec_from_file_location("clef_reference", path)
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ return module, path
+
+
+def clef_checkpoint(tmp_path):
+ import shutil
+
+ from safetensors.torch import save_file
+ from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
+
+ from unsloth.models.clef import JointSchemaHead
+
+ if not has_real_cuda():
+ try:
+ import causal_conv1d # noqa: F401
+ except ImportError:
+ pass
+ else:
+ pytest.skip("transformers calls causal_conv1d's CUDA-only kernel on CPU tensors")
+ reference, path = _clef_reference()
+ folder = tmp_path / "clef"
+ torch.manual_seed(0)
+ Qwen3_5ForConditionalGeneration.from_pretrained(
+ TINY_QWEN3_5, dtype = torch.bfloat16
+ ).save_pretrained(str(folder))
+ AutoProcessor.from_pretrained(TINY_QWEN3_5).save_pretrained(str(folder))
+ head = JointSchemaHead(**CLEF_HEAD)
+ with torch.no_grad():
+ for param in head.parameters():
+ param.add_(torch.randn_like(param) * 0.1)
+ save_file(
+ {k: v.to(torch.bfloat16).contiguous() for k, v in head.state_dict().items()},
+ str(folder / "joint_head.safetensors"),
+ )
+ (folder / "joint_head_config.json").write_text(json.dumps(CLEF_HEAD))
+ shutil.copyfile(path, folder / "joint_schema_model.py")
+ return folder
+
+
+def _clef_rows(n):
+ rows = [_row(i) for i in range(n)]
+ for row in rows:
+ row["questions"] = {
+ **QUESTIONS,
+ "tags": {"type": "choice", "criteria": ["billing", "outage", "other"]},
+ }
+ row["gold"]["tags"] = row["gold"]["team"]["label"]
+ return rows
+
+
+def test_clef_encoding_is_token_identical_to_cloudflares():
+ from transformers import AutoTokenizer
+
+ from unsloth.models.clef import encode_record
+
+ reference, _ = _clef_reference()
+ tokenizer = AutoTokenizer.from_pretrained(TINY_QWEN3_5)
+ for record in (
+ {"state": {"invoice": {"total": 1250.0, "vendor": "Acmé"}}, "questions": QUESTIONS},
+ {"state": "plain text", "questions": {"x": {"type": "noul", "criteria": {"true": "yes"}}}},
+ {
+ "state": "s" * 500,
+ "questions": {"lvl": {"type": "score", "instructions": "", "criteria": [1, "b"]}},
+ },
+ ):
+ for max_length in (100, 400, 16384):
+ if max_length == 100:
+ with pytest.raises(ValueError):
+ reference.encode_record(tokenizer, record, max_length = max_length)
+ with pytest.raises(ValueError):
+ encode_record(tokenizer, record, max_length = max_length)
+ continue
+ ours = encode_record(tokenizer, record, max_length = max_length)
+ theirs = reference.encode_record(tokenizer, record, max_length = max_length)
+ assert ours.input_ids == theirs.input_ids
+ assert [
+ (q.question_id, q.question_type, q.question_span, q.option_spans, q.option_ids)
+ for q in ours.questions
+ ] == [
+ (q.question_id, q.question_type, q.question_span, q.option_spans, q.option_ids)
+ for q in theirs.questions
+ ]
+
+
+ "option",
+ [
+ {"use_dora": True},
+ {"layers_to_transform": [0]},
+ {"layers_pattern": "layers"},
+ {"loftq_config": {"loftq_bits": 4}},
+ {"init_lora_weights": "gaussian"},
+ ],
+)
+def test_clef_lora_refuses_options_it_would_drop(monkeypatch, option):
+ monkeypatch.setattr(decision, "_clef_peft_model", lambda model, **kwargs: "plain lora")
+ model = types.SimpleNamespace(is_clef = True, encoder = types.SimpleNamespace())
+ with pytest.raises(NotImplementedError, match = next(iter(option))):
+ FastDecisionModel.get_peft_model(model, **option)
+ assert FastDecisionModel.get_peft_model(model) == "plain lora"
+
+
+def test_clef_metrics_score_in_the_runs_batch_size(monkeypatch):
+ seen = []
+
+ def clef_logits(
+ model,
+ items,
+ pad_token_id,
+ batch_size = 4,
+ ):
+ seen.append(batch_size)
+ raise StopIteration
+
+ monkeypatch.setattr(decision, "_clef_logits", clef_logits)
+ model = types.SimpleNamespace(is_clef = True, decision_config = {})
+ tokenizer = types.SimpleNamespace(pad_token_id = 0)
+ for call in (FastDecisionModel.evaluate, FastDecisionModel.calibrate):
+ with pytest.raises(StopIteration):
+ call(model, tokenizer, [], batch_size = 1)
+ with pytest.raises(StopIteration):
+ FastDecisionModel.evaluate(model, tokenizer, [])
+ assert seen == [1, 1, 4]
+
+
+def test_clef_loads_scores_like_cloudflares_model_and_trains(clef_checkpoint, tmp_path):
+ reference, _ = _clef_reference()
+ model, processor = FastDecisionModel.from_pretrained(str(clef_checkpoint), max_seq_length = 512)
+ assert getattr(model, "is_clef", False) and model.head.hidden_norm.weight.dtype == torch.float32
+ device = next(model.parameters()).device
+ backbone_dtype = next(model.encoder.parameters()).dtype
+ released, _ = reference.load_release_model(
+ str(clef_checkpoint), device = device, dtype = backbone_dtype
+ )
+ record = {"state": "the server is down again", "questions": QUESTIONS}
+ encoded = reference.encode_record(processor.tokenizer, record)
+ batch = reference.collate_records([encoded], processor.tokenizer.pad_token_id, device)
+ with torch.no_grad():
+ theirs = [z.float() for z in released(batch)[0]]
+ ours, _ = model(batch["input_ids"], batch["attention_mask"], batch["records"])
+ fp32_head = model.head
+ model.head = copy.deepcopy(fp32_head).to(backbone_dtype)
+ ours_same_dtype, _ = model(batch["input_ids"], batch["attention_mask"], batch["records"])
+ model.head = fp32_head
+ for row, z in enumerate(theirs):
+ assert torch.allclose(ours_same_dtype[row, : len(z)].float(), z, atol = 2e-2, rtol = 2e-2)
+ assert torch.allclose(ours[row, : len(z)].float(), z, atol = 0.1)
+
+ items, report = FastDecisionModel.build_dataset(_clef_rows(64), processor, model)
+ assert report["skipped"] == 0 and len(items) == 64 and len(items[0]["targets"]) == 4
+ train, holdout = FastDecisionModel.split_holdout(items, fraction = 0.25)
+ assert sum(len(i["labels"]) for i in holdout) <= 64
+ before = FastDecisionModel.evaluate(model, processor, holdout)
+ model = FastDecisionModel.get_peft_model(model, r = 8, lora_alpha = 8)
+ losses = []
+
+ class Losses(TrainerCallback):
+ def on_log(
+ self,
+ args,
+ state,
+ control,
+ logs = None,
+ **kwargs,
+ ):
+ if logs and "loss" in logs:
+ losses.append(logs["loss"])
+
+ trainer = DecisionTrainer(
+ model = model,
+ tokenizer = processor,
+ train_dataset = train,
+ args = _args(tmp_path, max_steps = 30, learning_rate = 5e-3, logging_steps = 1),
+ head_learning_rate = 5e-3,
+ callbacks = [Losses()],
+ )
+ trainer.train()
+ after = FastDecisionModel.evaluate(model, processor, holdout)
+ assert min(losses[-5:]) < losses[0] and after["loss"] < before["loss"]
+ calibration = FastDecisionModel.calibrate(model, processor, holdout)
+ assert "accuracy" in calibration
+ # Fitted to the gold labels, so the calibrated confidence tracks being right.
+ head_temperature = model.decision_config["head_temperature"]
+ assert (
+ decision.HEAD_TEMPERATURE_RANGE[0] <= head_temperature <= decision.HEAD_TEMPERATURE_RANGE[1]
+ )
+
+ model.decision_config["training"] = {"steps": 30}
+ model.save_pretrained_merged(str(tmp_path / "out"))
+ assert (tmp_path / "out" / "joint_schema_model.py").is_file()
+ reloaded, _ = FastDecisionModel.from_pretrained(str(tmp_path / "out"), max_seq_length = 512)
+ # The parent run's record stays on disk but does not describe the next fine-tune.
+ assert "training" not in reloaded.decision_config
+ # The calibrated temperature over all questions is folded into the saved head; the per-type
+ # temperatures are relative to it, so the reload serves the same probabilities.
+ folded = reloaded.decision_config["folded_temperature"]
+ assert folded == pytest.approx(model.decision_config["head_temperature"])
+ assert "head_temperature" not in reloaded.decision_config
+ assert reloaded.decision_config["temperature"] == model.decision_config["temperature"]
+ released, _ = reference.load_release_model(
+ str(tmp_path / "out"), device = device, dtype = torch.float32
+ )
+ with torch.no_grad():
+ trained, _ = model(batch["input_ids"], batch["attention_mask"], batch["records"])
+ again, _ = reloaded(batch["input_ids"], batch["attention_mask"], batch["records"])
+ theirs = released(batch)[0]
+ # Saved in bf16, so the reload rounds the trained weights.
+ # Compared as served probabilities: the folded head is trained / folded, and a small folded
+ # temperature would magnify bf16 rounding if the logits were compared directly.
+ mask = trained > -1e3
+ served = torch.softmax((trained / folded).masked_fill(~mask, -1e4), -1)
+ reloaded_served = torch.softmax(again.masked_fill(~mask, -1e4), -1)
+ assert torch.allclose(served, reloaded_served, atol = 0.02)
+ for row, z in enumerate(theirs):
+ assert int(z.argmax()) == int(again[row, : len(z)].argmax())
+
+
[email protected](not has_real_cuda(), reason = "the fast kernels need a CUDA device")
+def test_clef_backbone_runs_the_compiled_gated_delta_and_conv_kernels(clef_checkpoint):
+ from transformers.utils.import_utils import is_causal_conv1d_available
+
+ model, _ = FastDecisionModel.from_pretrained(str(clef_checkpoint), max_seq_length = 512)
+ from transformers.utils.import_utils import is_flash_linear_attention_available
+
+ if not is_flash_linear_attention_available():
+ pytest.skip("flash-linear-attention is disabled on this GPU / Triton")
+ layers = [m for m in model.encoder.modules() if type(m).__name__.endswith("GatedDeltaNet")]
+ assert layers
+ for layer in layers:
+ forward = type(layer).forward
+ assert forward.__code__.co_filename.endswith("unsloth_compiled_module_qwen3_5.py")
+ delta = _chosen_kernel(
+ layer, forward, "torch_chunk_gated_delta_rule", "chunk_gated_delta_rule"
+ )
+ conv = _chosen_kernel(layer, forward, "causal_conv1d_fn", "causal_conv1d_fn")
+ assert delta is not None and ".fla." in "." + delta, delta
+ if is_causal_conv1d_available():
+ assert conv is not None and conv.startswith("causal_conv1d"), conv
+
+
+def _chosen_kernel(layer, forward, global_name, attr):
+ # transformers < 5.6 stores the picked kernel on the layer; later versions freeze it in a
+ # closure under the hub-kernel wrappers of the module-level function.
+ fn = vars(layer)[attr] if attr in vars(layer) else forward.__globals__.get(global_name)
+ top = fn
+ while fn is not None and hasattr(fn, "__code__"):
+ cells = dict(zip(fn.__code__.co_freevars, fn.__closure__ or ()))
+ if "implementation" in cells:
+ return cells["implementation"].cell_contents.__module__
+ fn = getattr(fn, "__wrapped__", None)
+ return getattr(top, "__module__", None)
+
+
+def test_decision_loss_recipe_terms():
+ torch.manual_seed(0)
+ logits = torch.randn(5, 4)
+ mask = torch.tensor([[1, 1, 1, 0]] * 3 + [[1, 1, 0, 0]] * 2, dtype = torch.bool)
+ target = torch.zeros(5, 4)
+ target[torch.arange(5), torch.tensor([0, 2, 1, 1, 0])] = 1.0
+ ordinal = torch.tensor([True, True, False, False, False])
+ plain = decision._soft_cross_entropy(logits, target, mask)
+ assert torch.equal(decision._decision_loss(logits, target, mask, ordinal), plain)
+
+ log_p = torch.log_softmax(logits.masked_fill(~mask, -1e4), -1)
+ p = log_p.exp()
+ k = mask.sum(-1, keepdim = True).float()
+ smoothed = 0.9 * target + 0.1 * mask.float() / k
+ expected_ce = -(smoothed * log_p).sum(-1).mean()
+ expected_brier = ((p - target) ** 2 * mask).sum(-1).mean()
+ levels = torch.arange(4.0)
+ gold = target.argmax(-1).float()
+ distance = (p * (levels - gold[:, None]).abs()).sum(-1) / (k[:, 0] - 1)
+ expected_ordinal = distance[ordinal].mean()
+ got = decision._decision_loss(
+ logits,
+ target,
+ mask,
+ ordinal,
+ label_smoothing = 0.1,
+ brier_weight = 0.5,
+ ordinal_weight = 2.0,
+ )
+ torch.testing.assert_close(got, expected_ce + 0.5 * expected_brier + 2.0 * expected_ordinal)
+
+
+def test_record_accuracy_needs_every_question_of_a_row_right():
+ logits = [torch.tensor([2.0, 0.0]), torch.tensor([0.0, 2.0]), torch.tensor([2.0, 0.0])]
+ items = [
+ {"label": 0, "target": [1.0, 0.0], "row": 0, "qtype": 0},
+ {"label": 0, "target": [1.0, 0.0], "row": 0, "qtype": 0},
+ {"label": 0, "target": [1.0, 0.0], "row": 1, "qtype": 0},
+ ]
+ metrics = decision._metrics(logits, items, [1.0] * 3)
+ assert metrics["accuracy"] == pytest.approx(2 / 3) and metrics["record_accuracy"] == 0.5
+
+
+def _clef_head_inputs():
+ from transformers import AutoTokenizer
+
+ from unsloth.models.clef import JointSchemaHead, encode_record
+
+ tokenizer = AutoTokenizer.from_pretrained(TINY_QWEN3_5)
+ encoded = [
+ encode_record(tokenizer, {"state": "state " * (i + 1), "questions": QUESTIONS})
+ for i in range(2)
+ ]
+ batch = decision.ClefDataCollator(tokenizer.pad_token_id)(
+ [
+ {"input_ids": list(r.input_ids), "record": r, "targets": [[1.0]], "qtypes": [0]}
+ for r in encoded
+ ]
+ )
+ torch.manual_seed(0)
+ head = JointSchemaHead(**CLEF_HEAD)
+ with torch.no_grad():
+ for param in head.parameters():
+ param.add_(torch.randn_like(param) * 0.1)
+ hidden = torch.randn(*batch["input_ids"].shape, CLEF_HEAD["hidden_size"])
+ lexical = torch.randn(int(batch["input_ids"].max()) + 1, CLEF_HEAD["hidden_size"])
+
+ def run(module):
+ with torch.no_grad():
+ return [
+ z
+ for record in module(
+ hidden, batch["input_ids"], batch["attention_mask"], batch["records"], lexical
+ )
+ for z in record
+ ]
+
+ return head, run
+
+
[email protected]("temperature", [1.7, 0.6])
+def test_clef_temperature_folds_into_the_head_exactly(temperature):
+ head, run = _clef_head_inputs()
+ state = {k: v.detach().clone() for k, v in head.state_dict().items()}
+ assert decision._fold_temperature(state, temperature)
+ folded = copy.deepcopy(head)
+ folded.load_state_dict(state)
+ for original, scaled in zip(run(head), run(folded)):
+ torch.testing.assert_close(scaled, original / temperature, rtol = 1e-5, atol = 1e-6)
+
+
+def test_clef_temperature_is_not_folded_past_the_heads_scale_clamp():
+ head, _ = _clef_head_inputs()
+ state = {k: v.detach().clone() for k, v in head.state_dict().items()}
+ state["joint_logit_scale"] = torch.tensor(math.log(90.0))
+ before = {k: v.clone() for k, v in state.items()}
+ # Sharpening by 2 would need a scale of 180, past the clamp at 100.
+ assert not decision._fold_temperature(state, 0.5)
+ assert all(torch.equal(before[k], v) for k, v in state.items())
+
+
+def test_clef_collator_permutes_fields_but_keeps_targets_with_their_questions():
+ from transformers import AutoTokenizer
+
+ tokenizer = AutoTokenizer.from_pretrained(TINY_QWEN3_5)
+ model = types.SimpleNamespace(is_clef = True, decision_config = {"max_len": 2048})
+ items, report = FastDecisionModel.build_dataset(_clef_rows(4), tokenizer, model)
+ assert report["skipped"] == 0
+ fixed = decision.ClefDataCollator(tokenizer.pad_token_id)
+ shuffled = decision.ClefDataCollator(
+ tokenizer.pad_token_id, tokenizer = tokenizer, max_len = 2048, permute_fields = True, seed = 1
+ )
+ orders = set()
+ for _ in range(8):
+ batch = shuffled(items[:1])
+ record = batch["records"][0]
+ orders.add(tuple(q.question_id for q in record.questions))
+ by_name = dict(zip(items[0]["source"]["questions"], items[0]["targets"]))
+ for row, question in enumerate(record.questions):
+ assert (
+ batch["target"][row, : len(question.option_ids)].tolist()
+ == by_name[question.question_id]
+ )
+ assert bool(batch["ordinal"][row]) == (question.question_type == 2)
+ assert len(orders) > 1
+ assert fixed(items[:1])["records"][0] == items[0]["record"]
+
+
+def test_a_failed_save_leaves_the_previous_laya_checkpoint_loadable(
+ checkpoint, tmp_path, monkeypatch
+):
+ model, tokenizer = FastDecisionModel.from_pretrained(
+ str(checkpoint), use_gradient_checkpointing = False
+ )
+ out = tmp_path / "out"
+ model.save_pretrained_merged(out)
+ before = sorted(p.name for p in out.iterdir())
+ original = (out / "model.safetensors").read_bytes()
+ with torch.no_grad():
+ for param in model.head.parameters():
+ param.add_(1.0)
+
+ def broken(*args, **kwargs):
+ raise OSError("disk full")
+
+ monkeypatch.setattr(type(tokenizer), "save_pretrained", broken)
+ with pytest.raises(OSError):
+ model.save_pretrained_merged(out)
+ assert sorted(p.name for p in out.iterdir()) == before
+ assert (out / "model.safetensors").read_bytes() == original
+ assert decision.is_decision_checkpoint(out)
+ FastDecisionModel.from_pretrained(str(out), use_gradient_checkpointing = False)
+
+
+def test_a_failed_save_leaves_the_previous_clef_checkpoint_loadable(
+ clef_checkpoint, tmp_path, monkeypatch
+):
+ import safetensors.torch
+
+ model, processor = FastDecisionModel.from_pretrained(str(clef_checkpoint), max_seq_length = 512)
+ out = tmp_path / "out"
+ model.save_pretrained_merged(str(out))
+ head = (out / "joint_head.safetensors").read_bytes()
+ before = sorted(p.name for p in out.iterdir())
+ with torch.no_grad():
+ for param in model.head.parameters():
+ param.add_(1.0)
+ # The backbone shards save, then the head write fails.
+ original = safetensors.torch.save_file
+
+ def failing_head(tensors, path, *args, **kwargs):
+ if str(path).endswith("joint_head.safetensors"):
+ raise OSError("disk full")
+ return original(tensors, path, *args, **kwargs)
+
+ monkeypatch.setattr(safetensors.torch, "save_file", failing_head)
+ with pytest.raises(OSError):
+ model.save_pretrained_merged(str(out))
+ assert sorted(p.name for p in out.iterdir()) == before
+ assert (out / "joint_head.safetensors").read_bytes() == head
+ FastDecisionModel.from_pretrained(str(out), max_seq_length = 512)
+
+
+def test_kl_regularization_needs_a_lora_clef(clef_checkpoint, tmp_path):
+ model, processor = FastDecisionModel.from_pretrained(
+ str(clef_checkpoint), max_seq_length = 512, full_finetuning = True
+ )
+ with pytest.raises(NotImplementedError, match = "LoRA Clef"):
+ DecisionTrainer(model = model, args = _args(tmp_path), train_dataset = [], kl_weight = 0.1)
+
+
[email protected](not has_real_cuda(), reason = "Unsloth's float16 path for Qwen3.5 needs a GPU")
[email protected]("dtype", [torch.float16, torch.bfloat16])
+def test_clef_trains_in_float16_and_bfloat16(clef_checkpoint, tmp_path, dtype):
+ if dtype == torch.bfloat16 and not torch.cuda.is_bf16_supported(including_emulation = False):
+ pytest.skip("this GPU has no bfloat16")
+ model, processor = FastDecisionModel.from_pretrained(
+ str(clef_checkpoint), max_seq_length = 512, dtype = dtype
+ )
+ # float16 puts Qwen3.5 on Unsloth's float32 path (bfloat16 weights, no autocast), as on a T4.
+ assert decision._clef_forced_float32(model) == (dtype == torch.float16)
+ model = FastDecisionModel.get_peft_model(model, r = 8, lora_alpha = 8)
+ items, _ = FastDecisionModel.build_dataset(_clef_rows(32), processor, model)
+ grads = []
+
+ class Grads(TrainerCallback):
+ def on_log(
+ self,
+ args,
+ state,
+ control,
+ logs = None,
+ **kwargs,
+ ):
+ if logs and "loss" in logs:
+ grads.append((logs["loss"], logs.get("grad_norm")))
+
+ trainer = DecisionTrainer(
+ model = model,
+ tokenizer = processor,
+ train_dataset = items,
+ args = _args(
+ tmp_path,
+ max_steps = 6,
+ logging_steps = 1,
+ fp16 = dtype == torch.float16,
+ bf16 = dtype == torch.bfloat16,
+ ),
+ callbacks = [Grads()],
+ )
+ assert trainer.args.fp16 is False and trainer.args.bf16 == (dtype == torch.bfloat16)
+ trainer.train()
+ assert grads and all(math.isfinite(loss) and math.isfinite(g) and g > 0 for loss, g in grads)
+ assert math.isfinite(FastDecisionModel.evaluate(model, processor, items)["loss"])
+
+
+def test_clef_calibration_fits_being_right_and_serves_through_the_head_temperature():
+ # Underconfident logits: right 80% of the time with a soft gold that says 60%.
+ generator = torch.Generator().manual_seed(0)
+ logits, items = [], []
+ for i in range(400):
+ label = int(torch.randint(0, 3, (1,), generator = generator))
+ right = bool(torch.rand(1, generator = generator) < 0.8)
+ top = label if right else (label + 1) % 3
+ z = torch.zeros(3)
+ z[top] = 0.6
+ target = [0.2, 0.2, 0.2]
+ target[label] = 0.6
+ logits.append(z)
+ items.append({"label": label, "target": target, "qtype": i % 3, "row": i // 2})
+ config = {"temperature": [1.0] * 3}
+ plain = decision._metrics(logits, items, [1.0] * len(items))
+ calibrated = decision._calibrate_clef(config, logits, items)
+ assert calibrated["ece"] < plain["ece"] / 2 and calibrated["accuracy"] == plain["accuracy"]
+ assert config["head_temperature"] < 1.0
+ served = decision._served_temperatures(config, logits, items)
+ assert served[0] == pytest.approx(
+ config["head_temperature"]
+ * decision._laya().common.clamp_temperature(config["temperature"][0])
+ )
+
+
+def test_clef_autocasts_only_in_bfloat16_and_never_on_the_float32_path(monkeypatch):
+ model = torch.nn.Linear(1, 1)
+ cuda = torch.device("cuda")
+ monkeypatch.setattr(decision, "is_bfloat16_supported", lambda: True)
+ assert decision._clef_amp_dtype(model, cuda) == torch.bfloat16
+ model._unsloth_forced_float32 = True
+ assert decision._clef_amp_dtype(model, cuda) is None
+ model._unsloth_forced_float32 = False
+ monkeypatch.setattr(decision, "is_bfloat16_supported", lambda: False)
+ assert decision._clef_amp_dtype(model, cuda) is None
+ assert decision._clef_amp_dtype(model, torch.device("cpu")) is None
+
+
+def test_clef_calibration_with_every_holdout_decision_from_one_row():
+ # A holdout row with many questions passes the item minimum with nothing to cross-validate on.
+ logits = [torch.tensor([1.0, 0.0, -1.0]) for _ in range(12)]
+ items = [{"label": i % 3, "target": [1 / 3] * 3, "qtype": i % 3, "row": 0} for i in range(12)]
+ config = {"temperature": [1.0] * 3}
+ calibrated = decision._calibrate_clef(config, logits, items)
+ assert math.isfinite(calibrated["ece"]) and "head_temperature" in config
+
+
+def test_clef_save_keeps_the_source_tokenizer_files_byte_identical(clef_checkpoint, tmp_path):
+ model, processor = FastDecisionModel.from_pretrained(str(clef_checkpoint), max_seq_length = 512)
+ out = tmp_path / "out"
+ model.save_pretrained_merged(str(out))
+ for name in ("tokenizer.json", "tokenizer_config.json", "processor_config.json"):
+ if (clef_checkpoint / name).is_file():
+ assert (out / name).read_bytes() == (clef_checkpoint / name).read_bytes(), name
+ # Without it transformers warns of an "incorrect regex pattern" when loading the tokenizer.
+ assert "transformers_version" in json.loads((out / "config.json").read_text())
diff --git a/tests/test_public_api_surface.py b/tests/test_public_api_surface.py
index 3218e5d2040..07da3b629ca 100644
--- a/tests/test_public_api_surface.py
+++ b/tests/test_public_api_surface.py
@@ -180,3 +180,36 @@ def test_is_bf16_supported_or_alias_callable():
"unsloth.is_bfloat16_supported is callable; dtype probing "
"in 50+ notebooks fails."
)
+
+
+# FastDecisionModel: decision model (Laya) fine-tuning, called like the other Fast*Model classes.
+def test_fast_decision_model_follows_the_fast_model_api():
+ unsloth = pytest.importorskip("unsloth")
+ if getattr(unsloth, "_IS_MLX", False):
+ pytest.skip("FastDecisionModel is a stub on MLX")
+ cls = getattr(unsloth, "FastDecisionModel", None)
+ if cls is None or not hasattr(unsloth, "DecisionTrainer"):
+ pytest.fail(
+ "DRIFT DETECTED: unsloth.FastDecisionModel or unsloth.DecisionTrainer is missing."
+ )
+ methods = [
+ m
+ for m in ("from_pretrained", "get_peft_model", "for_inference", "for_training")
+ if not callable(getattr(cls, m, None))
+ ]
+ load = {"model_name", "max_seq_length", "dtype", "load_in_4bit", "full_finetuning"}
+ peft = {
+ "r",
+ "lora_alpha",
+ "lora_dropout",
+ "target_modules",
+ "bias",
+ "use_gradient_checkpointing",
+ }
+ load -= _signature_param_names(getattr(cls, "from_pretrained", None))
+ peft -= _signature_param_names(getattr(cls, "get_peft_model", None))
+ if methods or load or peft:
+ pytest.fail(
+ f"DRIFT DETECTED: FastDecisionModel is missing methods {methods}, from_pretrained "
+ f"kwargs {sorted(load)} or get_peft_model kwargs {sorted(peft)}."
+ )
diff --git a/tests/test_runtime_text_encoding.py b/tests/test_runtime_text_encoding.py
index 5ff24482c63..5bd40b5dcef 100644
--- a/tests/test_runtime_text_encoding.py
+++ b/tests/test_runtime_text_encoding.py
@@ -60,6 +60,9 @@ REVIEWED_VENDORED_OFFENDERS = {
"studio/backend/vendor/laya/agent.py:31: open()",
"studio/backend/vendor/laya/agent.py:47: open()",
"studio/backend/vendor/laya/agent.py:156: open()",
+ # Cloudflare's Clef loader (sha256 in unsloth/_vendor/clef/clef_manifest.json) reading
+ # joint_head_config.json, which json.dumps writes as ASCII, so every locale decodes it.
+ "unsloth/_vendor/clef/joint_schema_model.py:515: read_text()",
}
# keyed on path + expression, not line, so unrelated edits above it do not break the scan.
REVIEWED_NON_FILE_OPEN = (
diff --git a/unsloth/__init__.py b/unsloth/__init__.py
index 15b94a1ba02..a472b09c267 100644
--- a/unsloth/__init__.py
+++ b/unsloth/__init__.py
@@ -391,6 +391,23 @@ if _IS_MLX:
"Unsloth: FastSentenceTransformer is not yet supported on MLX."
)
+ class FastDecisionModel:
+ @staticmethod
+ def from_pretrained(*args, **kwargs):
+ raise NotImplementedError(
+ "Unsloth: FastDecisionModel training is not yet supported on MLX."
+ )
+
+ @staticmethod
+ def get_peft_model(*args, **kwargs):
+ raise NotImplementedError(
+ "Unsloth: FastDecisionModel training is not yet supported on MLX."
+ )
+
+ class DecisionTrainer:
+ def __init__(self, *args, **kwargs):
+ raise NotImplementedError("Unsloth: DecisionTrainer is not yet supported on MLX.")
+
def is_bfloat16_supported():
try:
import mlx.core as mx
diff --git a/unsloth/_vendor/__init__.py b/unsloth/_vendor/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/unsloth/_vendor/clef/LICENSE b/unsloth/_vendor/clef/LICENSE
new file mode 100644
index 00000000000..f938136e3ad
--- /dev/null
+++ b/unsloth/_vendor/clef/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright 2026 Alibaba Cloud
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
\ No newline at end of file
diff --git a/unsloth/_vendor/clef/README.md b/unsloth/_vendor/clef/README.md
new file mode 100644
index 00000000000..0fcf56a8eb6
--- /dev/null
+++ b/unsloth/_vendor/clef/README.md
@@ -0,0 +1,11 @@
+# Cloudflare Clef joint schema model (Apache-2.0)
+
+- Upstream: https://huggingface.co/Cloudflare/clef (`joint_schema_model.py`, identical in
+ https://huggingface.co/Cloudflare/clef-flash), revision and sha256 in `clef_manifest.json`.
+- Licence: `LICENSE` beside this file, copied unmodified from the upstream repo.
+
+`joint_schema_model.py` is byte-identical to upstream and is the reference implementation:
+`unsloth/models/clef.py` imports its record encoding and layers, and subclasses its head with
+Unsloth's batched, memory-bounded forward. Ruff and the kwargs formatter skip this directory
+(`[tool.ruff] extend-exclude` and the `ruff-format-with-kwargs` hook in `.pre-commit-config.yaml`)
+so the bytes keep matching the manifest; `tests/test_decision_clef_head.py` checks the digests.
diff --git a/unsloth/_vendor/clef/__init__.py b/unsloth/_vendor/clef/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/unsloth/_vendor/clef/clef_manifest.json b/unsloth/_vendor/clef/clef_manifest.json
new file mode 100644
index 00000000000..140f7dd5e61
--- /dev/null
+++ b/unsloth/_vendor/clef/clef_manifest.json
@@ -0,0 +1,11 @@
+{
+ "package": "clef",
+ "source": "https://huggingface.co/Cloudflare/clef",
+ "revision": "6a3ac5fc030a3f33f7fa860a1271886b64a6606d",
+ "also_identical_in": "https://huggingface.co/Cloudflare/clef-flash",
+ "license": "Apache-2.0",
+ "files": {
+ "LICENSE": "bbedc3fda3305820b977265f01b8619d87570a6739de3a5582c3464840f1e57a",
+ "joint_schema_model.py": "0e304cf7c6500e8bb59bef7e2afd2c6373f82596dfb3b57d1aa93c175e2dc3a3"
+ }
+}
diff --git a/unsloth/_vendor/clef/joint_schema_model.py b/unsloth/_vendor/clef/joint_schema_model.py
new file mode 100644
index 00000000000..6a3ac5fc030
--- /dev/null
+++ b/unsloth/_vendor/clef/joint_schema_model.py
@@ -0,0 +1,576 @@
+"""Clef: a multimodal Qwen backbone with a joint schema head for typed decisions.
+
+A record provides a ``state`` (any JSON value), optional ``images`` and ``videos``,
+and ``questions``. Each question has a ``type`` (``noul``, ``choice``, or ``score``),
+``instructions``, and, for ``choice`` and ``score``, ``criteria`` describing the
+allowed options. The model returns one logit per allowed option for every question.
+``systemone`` answers a Jev/SystemOne ``/v1/systemone`` request body with the same
+response body.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from pathlib import Path
+from typing import Any
+
+import torch
+import torch.nn.functional as functional
+
+
+SYSTEM_PROMPT = (
+ "Read the complete state and schema. Decide every field jointly. Each answer "
+ "must be exactly one of that field's allowed options."
+)
+IMAGE_PLACEHOLDER = "<|vision_start|><|image_pad|><|vision_end|>"
+VIDEO_PLACEHOLDER = "<|vision_start|><|video_pad|><|vision_end|>"
+MEDIA_BATCH_KEYS = ("pixel_values", "image_grid_thw", "pixel_values_videos", "video_grid_thw")
+MEDIA_TOKEN_KEYS = ("mm_token_type_ids",)
+QUESTION_TYPES = {"noul": 0, "choice": 1, "score": 2}
+
+
+def render(value: Any) -> str:
+ if isinstance(value, str):
+ return value
+ return json.dumps(
+ value,
+ ensure_ascii=False,
+ separators=(",", ":"),
+ sort_keys=True,
+ )
+
+
+def question_options(question: dict[str, Any]) -> list[tuple[str, Any]]:
+ question_type = str(question["type"])
+ if question_type == "noul":
+ criteria = {
+ "true": "The proposition is true or the answer is yes.",
+ "false": "The proposition is false or the answer is no.",
+ }
+ criteria.update(question.get("criteria") or {})
+ return [(key, criteria[key]) for key in ("true", "false")]
+ if question_type == "choice":
+ return sorted((str(key), value) for key, value in question["criteria"].items())
+ return [(str(index), value) for index, value in enumerate(question["criteria"])]
+
+
+@dataclass(frozen=True)
+class EncodedQuestion:
+ question_id: str
+ question_type: int
+ question_span: tuple[int, int]
+ option_spans: tuple[tuple[int, int], ...]
+ option_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class EncodedRecord:
+ input_ids: tuple[int, ...]
+ questions: tuple[EncodedQuestion, ...]
+ record_id: str
+ media: dict[str, Any] | None = dataclass_field(default=None, compare=False, repr=False)
+
+
+def _tokens(tokenizer: Any, text: str) -> list[int]:
+ return tokenizer(text, add_special_tokens=False).input_ids
+
+
+def _encode_media(processor: Any, record: dict[str, Any]) -> tuple[list[int], dict[str, Any] | None]:
+ images = list(record.get("images") or [])
+ videos = list(record.get("videos") or [])
+ if not images and not videos:
+ return [], None
+ if processor is None:
+ raise ValueError("records with images or videos require a processor")
+ text = IMAGE_PLACEHOLDER * len(images) + VIDEO_PLACEHOLDER * len(videos) + "\n"
+ encoded = processor(
+ text=[text],
+ images=images or None,
+ videos=videos or None,
+ return_tensors="pt",
+ **(record.get("media_kwargs") or {}),
+ )
+ media = {key: encoded[key] for key in MEDIA_BATCH_KEYS if key in encoded}
+ for key in MEDIA_TOKEN_KEYS:
+ if key in encoded:
+ media[key] = encoded[key][0].tolist()
+ return encoded["input_ids"][0].tolist(), media
+
+
+def encode_record(
+ tokenizer: Any,
+ record: dict[str, Any],
+ max_length: int = 16384,
+ max_state_tokens: int | None = None,
+ processor: Any | None = None,
+) -> EncodedRecord:
+ schema_ids = _tokens(tokenizer, "\n\nSCHEMA FIELDS:\n")
+ questions: list[EncodedQuestion] = []
+ for question_index, (question_id, question) in enumerate(record["questions"].items()):
+ schema_ids.extend(
+ _tokens(
+ tokenizer,
+ f"\nFIELD {question_index + 1}\nID: {question_id}\nTYPE: {question['type']}\nINSTRUCTION: ",
+ )
+ )
+ question_start = len(schema_ids)
+ instructions = question.get("instructions")
+ if instructions is None or instructions == "":
+ instructions = str(question_id)
+ schema_ids.extend(_tokens(tokenizer, render(instructions)))
+ question_end = len(schema_ids)
+ schema_ids.extend(_tokens(tokenizer, "\nALLOWED OPTIONS:\n"))
+
+ option_spans: list[tuple[int, int]] = []
+ option_ids: list[str] = []
+ for option_index, (option_id, description) in enumerate(question_options(question)):
+ schema_ids.extend(_tokens(tokenizer, f"OPTION {option_index + 1}: "))
+ option_start = len(schema_ids)
+ semantics = {"option_id": option_id}
+ if description is not None:
+ semantics["description"] = description
+ schema_ids.extend(_tokens(tokenizer, render(semantics)))
+ option_spans.append((option_start, len(schema_ids)))
+ option_ids.append(option_id)
+ schema_ids.extend(_tokens(tokenizer, "\n"))
+ schema_ids.extend(_tokens(tokenizer, "END FIELD\n"))
+ questions.append(
+ EncodedQuestion(
+ question_id=str(question_id),
+ question_type=QUESTION_TYPES[str(question["type"])],
+ question_span=(question_start, question_end),
+ option_spans=tuple(option_spans),
+ option_ids=tuple(option_ids),
+ )
+ )
+
+ prefix_ids = _tokens(
+ tokenizer,
+ f"<|im_start|>system\n{SYSTEM_PROMPT}<|im_end|>\n<|im_start|>user\nSTATE:\n",
+ )
+ suffix_ids = _tokens(
+ tokenizer,
+ "\n<|im_end|>\n<|im_start|>assistant\n<think>\n\n</think>\n\nJOINT SCHEMA DECISIONS:",
+ )
+ media_ids, media = _encode_media(processor, record)
+ if media is not None:
+ media["token_offset"] = len(prefix_ids)
+ prefix_ids = prefix_ids + media_ids
+ state_ids = _tokens(tokenizer, render(record["state"]))
+ if max_state_tokens is not None:
+ state_ids = state_ids[:max_state_tokens]
+ fixed_length = len(prefix_ids) + len(schema_ids) + len(suffix_ids)
+ if fixed_length > max_length:
+ raise ValueError(
+ f"schema requires {fixed_length} tokens before state; maximum is {max_length}"
+ )
+ state_ids = state_ids[: max_length - fixed_length]
+ schema_offset = len(prefix_ids) + len(state_ids)
+ shifted_questions = tuple(
+ EncodedQuestion(
+ question_id=question.question_id,
+ question_type=question.question_type,
+ question_span=(
+ question.question_span[0] + schema_offset,
+ question.question_span[1] + schema_offset,
+ ),
+ option_spans=tuple(
+ (start + schema_offset, end + schema_offset)
+ for start, end in question.option_spans
+ ),
+ option_ids=question.option_ids,
+ )
+ for question in questions
+ )
+ input_ids = tuple(prefix_ids + state_ids + schema_ids + suffix_ids)
+ if not input_ids or not shifted_questions:
+ raise ValueError("record produced no model input or questions")
+ return EncodedRecord(
+ input_ids=input_ids,
+ questions=shifted_questions,
+ record_id=str(record.get("id", "unknown")),
+ media=media,
+ )
+
+
+def collate_records(
+ records: list[EncodedRecord],
+ pad_token_id: int,
+ device: torch.device,
+) -> dict[str, Any]:
+ maximum_length = max(len(record.input_ids) for record in records)
+ input_ids = torch.full(
+ (len(records), maximum_length),
+ pad_token_id,
+ dtype=torch.long,
+ device=device,
+ )
+ attention_mask = torch.zeros(
+ (len(records), maximum_length),
+ dtype=torch.long,
+ device=device,
+ )
+ for index, record in enumerate(records):
+ length = len(record.input_ids)
+ input_ids[index, :length] = torch.tensor(record.input_ids, device=device)
+ attention_mask[index, :length] = 1
+ media: dict[str, torch.Tensor] = {}
+ for key in MEDIA_BATCH_KEYS:
+ values = [record.media[key] for record in records if record.media and key in record.media]
+ if values:
+ media[key] = torch.cat(values, dim=0).to(device)
+ for key in MEDIA_TOKEN_KEYS:
+ if any(record.media and key in record.media for record in records):
+ token_values = torch.zeros((len(records), maximum_length), dtype=torch.long, device=device)
+ for index, record in enumerate(records):
+ if record.media and key in record.media:
+ offset = record.media["token_offset"]
+ values = torch.tensor(record.media[key], dtype=torch.long, device=device)
+ token_values[index, offset : offset + len(values)] = values
+ media[key] = token_values
+ return {
+ "input_ids": input_ids,
+ "attention_mask": attention_mask,
+ "records": records,
+ "media": media,
+ }
+
+
+class EvidenceRoutingLayer(torch.nn.Module):
+ def __init__(
+ self,
+ width: int,
+ heads: int,
+ feedforward: int,
+ dropout: float = 0.0,
+ ) -> None:
+ super().__init__()
+ self.query_norm = torch.nn.LayerNorm(width)
+ self.memory_norm = torch.nn.LayerNorm(width)
+ self.attention = torch.nn.MultiheadAttention(
+ width,
+ heads,
+ dropout=dropout,
+ batch_first=True,
+ )
+ self.attention_dropout = torch.nn.Dropout(dropout)
+ self.feedforward_norm = torch.nn.LayerNorm(width)
+ self.feedforward = torch.nn.Sequential(
+ torch.nn.Linear(width, feedforward),
+ torch.nn.GELU(),
+ torch.nn.Dropout(dropout),
+ torch.nn.Linear(feedforward, width),
+ torch.nn.Dropout(dropout),
+ )
+
+ def forward(self, queries: torch.Tensor, memory: torch.Tensor) -> torch.Tensor:
+ normalized_queries = self.query_norm(queries)
+ routed, _ = self.attention(
+ normalized_queries,
+ self.memory_norm(memory),
+ self.memory_norm(memory),
+ need_weights=False,
+ )
+ queries = queries + self.attention_dropout(routed)
+ return queries + self.feedforward(self.feedforward_norm(queries))
+
+
+class JointSchemaHead(torch.nn.Module):
+ def __init__(
+ self,
+ hidden_size: int,
+ width: int,
+ routing_layers: int,
+ layers: int,
+ heads: int,
+ feedforward: int,
+ dropout: float = 0.0,
+ ) -> None:
+ super().__init__()
+ self.hidden_norm = torch.nn.LayerNorm(hidden_size)
+ self.memory_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.question_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.option_question_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.global_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.option_context_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.option_lexical_projection = torch.nn.Linear(hidden_size, width, bias=False)
+ self.type_embedding = torch.nn.Embedding(3, width)
+ self.evidence_layers = torch.nn.ModuleList(
+ [
+ EvidenceRoutingLayer(
+ width=width,
+ heads=heads,
+ feedforward=feedforward,
+ dropout=dropout,
+ )
+ for _ in range(routing_layers)
+ ]
+ )
+ self.option_summary_norm = torch.nn.LayerNorm(width)
+ self.layers = torch.nn.ModuleList(
+ [
+ torch.nn.TransformerDecoderLayer(
+ d_model=width,
+ nhead=heads,
+ dim_feedforward=feedforward,
+ dropout=dropout,
+ activation="gelu",
+ batch_first=True,
+ norm_first=True,
+ )
+ for _ in range(layers)
+ ]
+ )
+ self.field_norm = torch.nn.LayerNorm(width)
+ self.option_norm = torch.nn.LayerNorm(width)
+ self.residual_scorer = torch.nn.Sequential(
+ torch.nn.Linear(width * 4, width),
+ torch.nn.GELU(),
+ torch.nn.Dropout(dropout),
+ torch.nn.Linear(width, 1),
+ )
+ self.prior_logit_scale = torch.nn.Parameter(torch.zeros(()))
+ self.joint_logit_scale = torch.nn.Parameter(torch.zeros(()))
+ self.residual_gate = torch.nn.Parameter(torch.zeros(()))
+
+ @staticmethod
+ def _mean_span(values: torch.Tensor, span: tuple[int, int]) -> torch.Tensor:
+ start, end = span
+ return values[start:end].mean(dim=0)
+
+ def forward(
+ self,
+ hidden_states: torch.Tensor,
+ input_ids: torch.Tensor,
+ attention_mask: torch.Tensor,
+ records: list[EncodedRecord],
+ output_embedding_weight: torch.Tensor,
+ ) -> list[list[torch.Tensor]]:
+ results: list[list[torch.Tensor]] = []
+ normalized_hidden = self.hidden_norm(hidden_states)
+ for batch_index, record in enumerate(records):
+ sequence_length = int(attention_mask[batch_index].sum().item())
+ sequence_hidden = normalized_hidden[batch_index, :sequence_length]
+ memory = self.memory_projection(sequence_hidden).unsqueeze(0)
+ global_vector = sequence_hidden[-1]
+ question_vectors = torch.stack(
+ [
+ self._mean_span(sequence_hidden, question.question_span)
+ for question in record.questions
+ ]
+ )
+ type_ids = torch.tensor(
+ [question.question_type for question in record.questions],
+ device=hidden_states.device,
+ )
+ option_contexts: list[torch.Tensor] = []
+ lexical_options: list[torch.Tensor] = []
+ option_counts = []
+ for question in record.questions:
+ context_vectors = torch.stack(
+ [
+ self._mean_span(sequence_hidden, span)
+ for span in question.option_spans
+ ]
+ )
+ lexical_vectors = []
+ for start, end in question.option_spans:
+ token_ids = input_ids[batch_index, start:end]
+ lexical_vectors.append(output_embedding_weight[token_ids].mean(dim=0))
+ lexical = torch.stack(lexical_vectors)
+ option_contexts.append(context_vectors)
+ lexical_options.append(lexical)
+ option_counts.append(len(question.option_spans))
+
+ option_queries = []
+ for question_index, (context_vectors, lexical) in enumerate(
+ zip(option_contexts, lexical_options)
+ ):
+ option_queries.append(
+ self.option_context_projection(context_vectors)
+ + self.option_lexical_projection(lexical)
+ + self.option_question_projection(
+ question_vectors[question_index]
+ ).unsqueeze(0)
+ )
+ routed_options = torch.cat(option_queries, dim=0).unsqueeze(0)
+ for layer in self.evidence_layers:
+ routed_options = layer(routed_options, memory)
+ routed_options = routed_options[0]
+ split_options = list(torch.split(routed_options, option_counts, dim=0))
+
+ base_fields = self.question_projection(question_vectors)
+ option_summaries = []
+ for field, options in zip(base_fields, split_options):
+ routing_weights = torch.softmax(
+ torch.matmul(options, field) / math.sqrt(options.shape[-1]),
+ dim=0,
+ )
+ option_summaries.append(
+ torch.sum(routing_weights.unsqueeze(-1) * options, dim=0)
+ )
+ fields = (
+ base_fields
+ + self.option_summary_norm(torch.stack(option_summaries))
+ + self.global_projection(global_vector).unsqueeze(0)
+ + self.type_embedding(type_ids)
+ )
+ fields = fields.unsqueeze(0)
+ for layer in self.layers:
+ fields = layer(fields, memory)
+ fields = self.field_norm(fields[0])
+
+ record_logits: list[torch.Tensor] = []
+ for field, question, lexical, routed in zip(
+ fields,
+ record.questions,
+ lexical_options,
+ split_options,
+ ):
+ anchor = functional.normalize(
+ question_vectors[len(record_logits)] + global_vector,
+ dim=-1,
+ )
+ lexical_anchor = functional.normalize(lexical, dim=-1)
+ prior_scale = self.prior_logit_scale.clamp(max=math.log(100.0)).exp()
+ prior = prior_scale * torch.matmul(lexical_anchor, anchor)
+ options = self.option_norm(routed)
+ repeated_field = field.unsqueeze(0).expand_as(options)
+ cosine = functional.cosine_similarity(repeated_field, options, dim=-1)
+ features = torch.cat(
+ [
+ repeated_field,
+ options,
+ repeated_field * options,
+ torch.abs(repeated_field - options),
+ ],
+ dim=-1,
+ )
+ residual = self.residual_scorer(features).squeeze(-1)
+ joint_scale = self.joint_logit_scale.clamp(max=math.log(100.0)).exp()
+ joint = joint_scale * cosine + residual
+ record_logits.append(
+ prior + torch.sigmoid(self.residual_gate) * joint
+ )
+ results.append(record_logits)
+ return results
+
+
+class ClefModel(torch.nn.Module):
+ def __init__(self, language_model: Any, head: JointSchemaHead) -> None:
+ super().__init__()
+ self.language_model = language_model
+ self.head = head
+
+ def forward(self, batch: dict[str, Any]) -> list[list[torch.Tensor]]:
+ base_model = (
+ self.language_model.get_base_model()
+ if hasattr(self.language_model, "get_base_model")
+ else self.language_model
+ )
+ media = batch.get("media") or {}
+ text_model = base_model.model
+ if not media and hasattr(text_model, "language_model"):
+ text_model = text_model.language_model
+ outputs = text_model(
+ input_ids=batch["input_ids"],
+ attention_mask=batch["attention_mask"],
+ use_cache=False,
+ return_dict=True,
+ **media,
+ )
+ return self.head(
+ outputs.last_hidden_state,
+ batch["input_ids"],
+ batch["attention_mask"],
+ batch["records"],
+ base_model.get_output_embeddings().weight,
+ )
+
+
+def load_release_model(
+ model_path: str | Path,
+ device: str | torch.device = "cuda",
+ dtype: torch.dtype = torch.bfloat16,
+ **from_pretrained_kwargs: Any,
+) -> tuple[ClefModel, Any]:
+ """Load a Clef release (merged backbone, joint schema head, and processor)."""
+ from huggingface_hub import snapshot_download
+ from safetensors.torch import load_file
+ from transformers import AutoProcessor, Qwen3_5ForConditionalGeneration
+
+ path = Path(model_path)
+ if not path.is_dir():
+ path = Path(snapshot_download(str(model_path)))
+ backbone = Qwen3_5ForConditionalGeneration.from_pretrained(
+ path,
+ dtype=dtype,
+ device_map={"": str(device)},
+ **from_pretrained_kwargs,
+ )
+ backbone.config.use_cache = False
+ head_config = json.loads((path / "joint_head_config.json").read_text())
+ head = JointSchemaHead(**head_config)
+ head.load_state_dict(load_file(path / "joint_head.safetensors"), strict=True)
+ head = head.to(device=device, dtype=dtype)
+ processor = AutoProcessor.from_pretrained(path)
+ return ClefModel(backbone, head).eval(), processor
+
+
+def systemone_answer(question: dict[str, Any], probabilities: dict[str, float]) -> dict[str, Any]:
+ """Convert per-option probabilities for one question into a SystemOne answer."""
+ if question["type"] == "noul":
+ return {"type": "noul", "noul": round(probabilities["true"], 4)}
+ if question["type"] == "choice":
+ options = [str(option) for option in question["criteria"]]
+ choice = max(options, key=probabilities.__getitem__)
+ return {
+ "type": "choice",
+ "choice": choice,
+ "confidence": round(probabilities[choice], 4),
+ "probabilities": {option: round(probabilities[option], 4) for option in options},
+ }
+ levels = [str(index) for index in range(len(question["criteria"]))]
+ return {
+ "type": "score",
+ "score": round(sum(index * probabilities[level] for index, level in enumerate(levels)), 4),
+ "confidence": round(max(probabilities[level] for level in levels), 4),
+ "legend": dict(zip(levels, question["criteria"])),
+ "probabilities": {level: round(probabilities[level], 4) for level in levels},
+ }
+
+
+def systemone(model: ClefModel, processor: Any, request: dict[str, Any], max_length: int = 16384) -> dict[str, Any]:
+ """Answer a Jev/SystemOne ``/v1/systemone`` request body with a SystemOne response body.
+
+ The request has ``model``, ``state``, and ``questions``, plus optional ``images`` and ``videos``.
+ """
+ questions = request.get("questions")
+ if not isinstance(request.get("model"), str) or "state" not in request:
+ raise ValueError("model and state are required")
+ if not isinstance(questions, dict) or not questions:
+ raise ValueError("at least one question is required")
+ for question_id, question in questions.items():
+ if question.get("type") not in QUESTION_TYPES:
+ raise ValueError(f"{question_id}: type must be noul, choice, or score")
+ if question["type"] != "noul" and not question.get("criteria"):
+ raise ValueError(f"{question_id}: criteria must not be empty")
+ encoded = encode_record(processor.tokenizer, request, max_length=max_length, processor=processor)
+ device = next(model.parameters()).device
+ logits = model(collate_records([encoded], processor.tokenizer.pad_token_id, device))[0]
+ answers = {
+ question.question_id: systemone_answer(
+ questions[question.question_id],
+ dict(zip(question.option_ids, question_logits.float().softmax(-1).tolist())),
+ )
+ for question, question_logits in zip(encoded.questions, logits)
+ }
+ return {
+ "model": request["model"],
+ "answers": answers,
+ "usage": {"input_tokens": len(encoded.input_ids), "output_tokens": 0},
+ }
diff --git a/unsloth/models/__init__.py b/unsloth/models/__init__.py
index 6d4af1e84f1..cdbecea261a 100644
--- a/unsloth/models/__init__.py
+++ b/unsloth/models/__init__.py
@@ -17,6 +17,7 @@ from .qwen3 import FastQwen3Model
from .qwen3_moe import FastQwen3MoeModel
from .granite import FastGraniteModel
from .sentence_transformer import FastSentenceTransformer
+from .decision import *
try:
from .falcon_h1 import FastFalconH1Model
diff --git a/unsloth/models/clef.py b/unsloth/models/clef.py
new file mode 100644
index 00000000000..c932d50c4db
--- /dev/null
+++ b/unsloth/models/clef.py
@@ -0,0 +1,591 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+
+# Portions are derived from Cloudflare's joint_schema_model.py (https://huggingface.co/Cloudflare/clef),
+# Copyright 2026 Cloudflare, Inc., licensed under the Apache License, Version 2.0; the license text
+# is in unsloth/_vendor/clef/LICENSE. That file is vendored unmodified in unsloth/_vendor/clef: this
+# module imports its record encoding, layers and SystemOne answers, and adds Unsloth's head forward.
+
+import contextlib
+import math
+import os
+import warnings
+
+import torch
+import torch.nn.functional as functional
+
+from .._vendor.clef.joint_schema_model import ( # noqa: F401
+ IMAGE_PLACEHOLDER,
+ MEDIA_BATCH_KEYS,
+ QUESTION_TYPES,
+ SYSTEM_PROMPT,
+ VIDEO_PLACEHOLDER,
+ ClefModel,
+ EncodedQuestion,
+ EncodedRecord,
+ EvidenceRoutingLayer,
+ collate_records,
+ encode_record,
+ question_options,
+ render,
+ systemone,
+ systemone_answer,
+)
+from .._vendor.clef.joint_schema_model import JointSchemaHead as ReferenceJointSchemaHead
+
+HEAD_FILES = ("joint_head.safetensors", "joint_head_config.json")
+
+
+def _fast_enabled() -> bool:
+ return os.environ.get("UNSLOTH_CLEF_FAST", "1") != "0"
+
+
+_COMPILED = {}
+
+
+def _compile_supported(device) -> bool:
+ if os.environ.get("UNSLOTH_CLEF_COMPILE", "1") == "0" or device.type != "cuda":
+ return False
+ try:
+ from torch.utils._triton import has_triton
+ except ImportError:
+ return False
+ return has_triton()
+
+
+def _compiled_logits(device):
+ # Training only: one fullgraph compile with dynamic shapes; inference stays eager.
+ if not _compile_supported(device):
+ return None
+ if "function" not in _COMPILED:
+ _COMPILED["function"] = torch.compile(batched_logits, fullgraph = True, dynamic = True)
+ return _COMPILED["function"]
+
+
+def _disable_compile(error) -> None:
+ warnings.warn(f"Unsloth: Clef head compile failed, running it eagerly: {error}")
+ os.environ["UNSLOTH_CLEF_COMPILE"] = "0"
+ _COMPILED.clear()
+
+
+class ClefLogits(list):
+ # Per record, per question logits like Cloudflare's head returns, plus the padded
+ # [questions, options] tensor they are views of (-1e4 past each question's options).
+ def __init__(self, flat_padded, records):
+ rows = iter(range(flat_padded.shape[0]))
+ super().__init__(
+ [flat_padded[next(rows), : len(q.option_spans)] for q in record.questions]
+ for record in records
+ )
+ self.flat_padded = flat_padded
+
+
+def _span_mask(starts, ends, begin, end, dtype):
+ # [B, S, C]: 1 where token begin + c lies in [start, end) of span s.
+ positions = torch.arange(begin, end, device = starts.device)
+ inside = (positions >= starts.unsqueeze(-1)) & (positions < ends.unsqueeze(-1))
+ return inside.to(dtype)
+
+
+def _norm_pool_forward(hidden, weight, bias, memory_weight, starts, ends, eps, chunk, matmul_dtype):
+ # hidden_norm in fp32 one chunk of tokens at a time: only the [B, L, width] memory and the span
+ # means are kept, never the [B, L, hidden] fp32 copy. The memory projection runs in
+ # matmul_dtype, as autocast runs Cloudflare's head.
+ batch, length, _ = hidden.shape
+ memory = hidden.new_empty((batch, length, memory_weight.shape[0]), dtype = matmul_dtype)
+ pooled = hidden.new_zeros((batch, starts.shape[1], hidden.shape[-1]), dtype = weight.dtype)
+ projection = memory_weight.to(matmul_dtype).t()
+ for begin in range(0, length, chunk):
+ end = min(length, begin + chunk)
+ # aten directly, as the backward does: Unsloth patches F.layer_norm into a function that
+ # compiles itself, which would add a graph inside this opaque op.
+ normalized = torch.ops.aten.native_layer_norm(
+ hidden[:, begin:end].to(weight.dtype), weight.shape, weight, bias, eps
+ )[0]
+ memory[:, begin:end] = normalized.to(matmul_dtype) @ projection
+ pooled += _span_mask(starts, ends, begin, end, weight.dtype) @ normalized
+ counts = (ends - starts).clamp(min = 1).unsqueeze(-1).to(weight.dtype)
+ return memory, pooled / counts
+
+
+def _norm_pool_backward(
+ grad_memory,
+ grad_pooled,
+ hidden,
+ weight,
+ bias,
+ memory_weight,
+ starts,
+ ends,
+ eps,
+ chunk,
+ matmul_dtype,
+):
+ length = hidden.shape[1]
+ counts = (ends - starts).clamp(min = 1).unsqueeze(-1).to(weight.dtype)
+ grad_pooled = grad_pooled / counts
+ grad_hidden = torch.empty_like(hidden)
+ grad_weight = torch.zeros_like(weight)
+ grad_bias = torch.zeros_like(bias)
+ grad_memory_weight = torch.zeros_like(memory_weight)
+ projection = memory_weight.to(matmul_dtype)
+ for begin in range(0, length, chunk):
+ end = min(length, begin + chunk)
+ x = hidden[:, begin:end].to(weight.dtype)
+ normalized, mean, rstd = torch.ops.aten.native_layer_norm(
+ x, weight.shape, weight, bias, eps
+ )
+ grad_chunk = grad_memory[:, begin:end].to(matmul_dtype)
+ grad_normalized = (grad_chunk @ projection).to(weight.dtype)
+ grad_normalized = (
+ grad_normalized
+ + _span_mask(starts, ends, begin, end, weight.dtype).transpose(1, 2) @ grad_pooled
+ )
+ grad_memory_weight += (
+ grad_chunk.flatten(0, 1).t() @ normalized.to(matmul_dtype).flatten(0, 1)
+ ).to(memory_weight.dtype)
+ grad_x, grad_w, grad_b = torch.ops.aten.native_layer_norm_backward(
+ grad_normalized, x, weight.shape, mean, rstd, weight, bias, [True, True, True]
+ )
+ grad_hidden[:, begin:end] = grad_x.to(hidden.dtype)
+ grad_weight += grad_w
+ grad_bias += grad_b
+ return grad_hidden, grad_weight, grad_bias, grad_memory_weight
+
+
[email protected]_op("unsloth::clef_norm_pool", mutates_args = ())
+def _norm_pool_op(
+ hidden: torch.Tensor,
+ weight: torch.Tensor,
+ bias: torch.Tensor,
+ memory_weight: torch.Tensor,
+ starts: torch.Tensor,
+ ends: torch.Tensor,
+ eps: float,
+ chunk: int,
+ matmul_dtype: torch.dtype,
+) -> tuple[torch.Tensor, torch.Tensor]:
+ return _norm_pool_forward(
+ hidden, weight, bias, memory_weight, starts, ends, eps, chunk, matmul_dtype
+ )
+
+
+@_norm_pool_op.register_fake
+def _norm_pool_fake(hidden, weight, bias, memory_weight, starts, ends, eps, chunk, matmul_dtype):
+ batch, length, size = hidden.shape
+ return (
+ hidden.new_empty((batch, length, memory_weight.shape[0]), dtype = matmul_dtype),
+ hidden.new_empty((batch, starts.shape[1], size), dtype = weight.dtype),
+ )
+
+
[email protected]_op("unsloth::clef_norm_pool_backward", mutates_args = ())
+def _norm_pool_backward_op(
+ grad_memory: torch.Tensor,
+ grad_pooled: torch.Tensor,
+ hidden: torch.Tensor,
+ weight: torch.Tensor,
+ bias: torch.Tensor,
+ memory_weight: torch.Tensor,
+ starts: torch.Tensor,
+ ends: torch.Tensor,
+ eps: float,
+ chunk: int,
+ matmul_dtype: torch.dtype,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+ return _norm_pool_backward(
+ grad_memory,
+ grad_pooled,
+ hidden,
+ weight,
+ bias,
+ memory_weight,
+ starts,
+ ends,
+ eps,
+ chunk,
+ matmul_dtype,
+ )
+
+
+@_norm_pool_backward_op.register_fake
+def _norm_pool_backward_fake(
+ grad_memory,
+ grad_pooled,
+ hidden,
+ weight,
+ bias,
+ memory_weight,
+ starts,
+ ends,
+ eps,
+ chunk,
+ matmul_dtype,
+):
+ return (
+ torch.empty_like(hidden),
+ torch.empty_like(weight),
+ torch.empty_like(bias),
+ torch.empty_like(memory_weight),
+ )
+
+
+def _norm_pool_setup(ctx, inputs, output):
+ hidden, weight, bias, memory_weight, starts, ends, eps, chunk, matmul_dtype = inputs
+ ctx.save_for_backward(hidden, weight, bias, memory_weight, starts, ends)
+ ctx.eps, ctx.chunk, ctx.matmul_dtype = eps, chunk, matmul_dtype
+
+
+def _norm_pool_grad(ctx, grad_memory, grad_pooled):
+ hidden, weight, bias, memory_weight, starts, ends = ctx.saved_tensors
+ grads = _norm_pool_backward_op(
+ grad_memory.contiguous(),
+ grad_pooled.contiguous(),
+ hidden,
+ weight,
+ bias,
+ memory_weight,
+ starts,
+ ends,
+ ctx.eps,
+ ctx.chunk,
+ ctx.matmul_dtype,
+ )
+ return (*grads, None, None, None, None, None)
+
+
+_norm_pool_op.register_autograd(_norm_pool_grad, setup_context = _norm_pool_setup)
+
+
+def norm_pool(hidden, norm, memory_projection, starts, ends, chunk):
+ # Custom ops skip autocast, so ask it which dtype Linear would run in.
+ matmul_dtype = norm.weight.dtype
+ if torch.is_autocast_enabled(hidden.device.type):
+ matmul_dtype = torch.get_autocast_dtype(hidden.device.type)
+ return _norm_pool_op(
+ hidden,
+ norm.weight,
+ norm.bias,
+ memory_projection.weight,
+ starts,
+ ends,
+ norm.eps,
+ chunk,
+ matmul_dtype,
+ )
+
+
+def build_layout(records, device) -> dict:
+ # Host metadata from the records, sent in one pinned copy: no device sync before the head.
+ batch = len(records)
+ q_max = max(len(r.questions) for r in records)
+ p_max = max(sum(len(q.option_spans) for q in r.questions) for r in records)
+ o_max = max(len(q.option_spans) for r in records for q in r.questions)
+ spans = q_max + p_max + 1
+ starts, ends = [[0] * spans for _ in range(batch)], [[0] * spans for _ in range(batch)]
+ lengths, types = [], [[0] * q_max for _ in range(batch)]
+ owner = [[0] * p_max for _ in range(batch)]
+ option_index = [[[0] * o_max for _ in range(q_max)] for _ in range(batch)]
+ option_valid = [[[0] * o_max for _ in range(q_max)] for _ in range(batch)]
+ question_valid = [[0] * q_max for _ in range(batch)]
+ lexical_tokens, lexical_segments, output_rows = [], [], []
+ for b, record in enumerate(records):
+ length = len(record.input_ids)
+ lengths.append(length)
+ starts[b][-1], ends[b][-1] = length - 1, length
+ p = 0
+ for q, question in enumerate(record.questions):
+ starts[b][q], ends[b][q] = question.question_span
+ types[b][q] = question.question_type
+ question_valid[b][q] = 1
+ output_rows.append(b * q_max + q)
+ for o, (start, end) in enumerate(question.option_spans):
+ starts[b][q_max + p], ends[b][q_max + p] = start, end
+ owner[b][p], option_index[b][q][o], option_valid[b][q][o] = q, p, 1
+ lexical_tokens.extend(record.input_ids[start:end])
+ lexical_segments.extend([b * p_max + p] * (end - start))
+ p += 1
+ parts = {
+ "starts": (starts, (batch, spans)),
+ "ends": (ends, (batch, spans)),
+ "lengths": (lengths, (batch,)),
+ "types": (types, (batch, q_max)),
+ "owner": (owner, (batch, p_max)),
+ "option_index": (option_index, (batch, q_max, o_max)),
+ "option_valid": (option_valid, (batch, q_max, o_max)),
+ "question_valid": (question_valid, (batch, q_max)),
+ "lexical_tokens": (lexical_tokens, (len(lexical_tokens),)),
+ "lexical_segments": (lexical_segments, (len(lexical_segments),)),
+ "output_rows": (output_rows, (len(output_rows),)),
+ }
+ flat = []
+ for value, _ in parts.values():
+ while value and isinstance(value[0], list):
+ value = [x for row in value for x in row]
+ flat.extend(value)
+ packed = torch.tensor(flat, dtype = torch.long)
+ if device.type == "cuda":
+ packed = packed.pin_memory()
+ packed = packed.to(device, non_blocking = True)
+ layout, offset = {}, 0
+ for name, (_, shape) in parts.items():
+ size = math.prod(shape)
+ layout[name] = packed[offset : offset + size].view(shape)
+ offset += size
+ layout["option_valid"] = layout["option_valid"].bool()
+ layout["question_valid"] = layout["question_valid"].bool()
+ return layout
+
+
+def _route(layer, queries, memory, padding):
+ memory = layer.memory_norm(memory)
+ routed, _ = layer.attention(
+ layer.query_norm(queries), memory, memory, key_padding_mask = padding, need_weights = False
+ )
+ queries = queries + layer.attention_dropout(routed)
+ return queries + layer.feedforward(layer.feedforward_norm(queries))
+
+
+def _decode(layer, fields, memory, field_padding, padding):
+ return layer(
+ fields, memory, tgt_key_padding_mask = field_padding, memory_key_padding_mask = padding
+ )
+
+
+def _pristine_checkpoint():
+ module = torch.utils.checkpoint
+ for candidate in (
+ getattr(module, "_unsloth_pristine_checkpoint", None),
+ module.checkpoint,
+ getattr(module, "_old_checkpoint", None),
+ ):
+ if getattr(candidate, "__module__", None) == "torch.utils.checkpoint":
+ return candidate
+ return None
+
+
+def _torch_checkpoint(enabled):
+ # Unsloth swaps torch.utils.checkpoint.checkpoint for its offloaded one, which rejects
+ # use_reentrant = False and which dynamo does not recognise as activation checkpointing
+ # (it matches the module attribute by identity), so the head runs under torch's own.
+ module, pristine = torch.utils.checkpoint, _pristine_checkpoint() if enabled else None
+ current = module.checkpoint
+ if pristine is None or pristine is current:
+ yield
+ return
+ module.checkpoint = pristine
+ try:
+ yield
+ finally:
+ module.checkpoint = current
+
+
+def _maybe_checkpoint(function, checkpoint, *args):
+ if checkpoint:
+ return torch.utils.checkpoint.checkpoint(function, *args, use_reentrant = False)
+ return function(*args)
+
+
+def batched_logits(head, hidden_states, output_embedding_weight, layout, checkpoint, chunk):
+ dtype = head.hidden_norm.weight.dtype
+ batch, length = hidden_states.shape[:2]
+ q_max, p_max = layout["types"].shape[1], layout["owner"].shape[1]
+ starts, ends = layout["starts"], layout["ends"]
+ memory, pooled = norm_pool(
+ hidden_states, head.hidden_norm, head.memory_projection, starts, ends, chunk
+ )
+ padding = torch.arange(length, device = hidden_states.device) >= layout["lengths"].unsqueeze(-1)
+ question_vectors = pooled[:, :q_max]
+ contexts = pooled[:, q_max : q_max + p_max]
+ global_vector = pooled[:, -1]
+
+ rows = output_embedding_weight[layout["lexical_tokens"]].to(dtype)
+ lexical = rows.new_zeros((batch * p_max, rows.shape[-1]))
+ lexical.index_add_(0, layout["lexical_segments"], rows)
+ lexical_counts = (ends[:, q_max : q_max + p_max] - starts[:, q_max : q_max + p_max]).clamp(
+ min = 1
+ )
+ lexical = lexical.view(batch, p_max, -1) / lexical_counts.unsqueeze(-1).to(dtype)
+
+ owner = layout["owner"]
+ owner_questions = torch.gather(
+ question_vectors, 1, owner.unsqueeze(-1).expand(-1, -1, question_vectors.shape[-1])
+ )
+ routed = (
+ head.option_context_projection(contexts)
+ + head.option_lexical_projection(lexical)
+ + head.option_question_projection(owner_questions)
+ )
+ for layer in head.evidence_layers:
+ routed = _maybe_checkpoint(_route, checkpoint, layer, routed, memory, padding)
+
+ width = routed.shape[-1]
+ option_index, option_valid = layout["option_index"], layout["option_valid"]
+ o_max = option_index.shape[-1]
+ options = torch.gather(routed, 1, option_index.view(batch, -1, 1).expand(-1, -1, width)).view(
+ batch, q_max, o_max, width
+ )
+ base_fields = head.question_projection(question_vectors)
+ scores = (options @ base_fields.unsqueeze(-1)).squeeze(-1) / math.sqrt(width)
+ scores = scores.masked_fill(~option_valid, torch.finfo(scores.dtype).min)
+ weights = torch.softmax(scores, dim = -1)
+ summaries = (weights.unsqueeze(-1) * options).sum(2)
+ fields = (
+ base_fields
+ + head.option_summary_norm(summaries)
+ + head.global_projection(global_vector).unsqueeze(1)
+ + head.type_embedding(layout["types"])
+ )
+ field_padding = ~layout["question_valid"]
+ for layer in head.layers:
+ fields = _maybe_checkpoint(
+ _decode, checkpoint, layer, fields, memory, field_padding, padding
+ )
+ fields = head.field_norm(fields)
+
+ anchors = functional.normalize(question_vectors + global_vector.unsqueeze(1), dim = -1)
+ owner_anchors = torch.gather(anchors, 1, owner.unsqueeze(-1).expand(-1, -1, anchors.shape[-1]))
+ prior_scale = head.prior_logit_scale.clamp(max = math.log(100.0)).exp()
+ prior = prior_scale * (functional.normalize(lexical, dim = -1) * owner_anchors).sum(-1)
+ owner_fields = torch.gather(fields, 1, owner.unsqueeze(-1).expand(-1, -1, width))
+ normed = head.option_norm(routed)
+ cosine = functional.cosine_similarity(owner_fields, normed, dim = -1)
+ features = torch.cat(
+ [owner_fields, normed, owner_fields * normed, torch.abs(owner_fields - normed)], dim = -1
+ )
+ residual = head.residual_scorer(features).squeeze(-1)
+ joint_scale = head.joint_logit_scale.clamp(max = math.log(100.0)).exp()
+ per_option = prior + torch.sigmoid(head.residual_gate) * (joint_scale * cosine + residual)
+ logits = torch.gather(per_option, 1, option_index.view(batch, -1)).view(batch, q_max, o_max)
+ logits = logits.masked_fill(~option_valid, -1e4)
+ return logits.view(batch * q_max, o_max).index_select(0, layout["output_rows"])
+
+
+class JointSchemaHead(ReferenceJointSchemaHead):
+ # Same parameters and state dict as Cloudflare's head; the forward also takes an fp32 copy of
+ # the head over 16-bit hidden states.
+ def __init__(
+ self,
+ hidden_size: int,
+ width: int,
+ routing_layers: int,
+ layers: int,
+ heads: int,
+ feedforward: int,
+ dropout: float = 0.0,
+ ):
+ super().__init__(hidden_size, width, routing_layers, layers, heads, feedforward, dropout)
+ self.config = dict(
+ hidden_size = hidden_size,
+ width = width,
+ routing_layers = routing_layers,
+ layers = layers,
+ heads = heads,
+ feedforward = feedforward,
+ )
+
+ def forward(
+ self, hidden_states, input_ids, attention_mask, records, output_embedding_weight
+ ) -> list:
+ if not _fast_enabled():
+ return self.forward_per_record(
+ hidden_states, input_ids, attention_mask, records, output_embedding_weight
+ )
+ layout = build_layout(records, hidden_states.device)
+ training = self.training and torch.is_grad_enabled()
+ checkpoint = training and os.environ.get("UNSLOTH_CLEF_CHECKPOINT", "1") != "0"
+ chunk = int(os.environ.get("UNSLOTH_CLEF_CHUNK", "2048"))
+ function = _compiled_logits(hidden_states.device) if training else None
+ args = (self, hidden_states, output_embedding_weight, layout, checkpoint, chunk)
+ with _torch_checkpoint(checkpoint):
+ if function is not None:
+ try:
+ flat = function(*args)
+ except Exception as error:
+ if isinstance(error, torch.cuda.OutOfMemoryError):
+ raise
+ _disable_compile(error)
+ flat = batched_logits(*args)
+ else:
+ flat = batched_logits(*args)
+ return ClefLogits(flat, records)
+
+ def forward_per_record(
+ self, hidden_states, input_ids, attention_mask, records, output_embedding_weight
+ ) -> list:
+ dtype = self.hidden_norm.weight.dtype
+ normalized_hidden = self.hidden_norm(hidden_states.to(dtype))
+ lengths = attention_mask.sum(-1).tolist()
+ prior_scale = self.prior_logit_scale.clamp(max = math.log(100.0)).exp()
+ joint_scale = self.joint_logit_scale.clamp(max = math.log(100.0)).exp()
+ gate = torch.sigmoid(self.residual_gate)
+ results = []
+ for batch_index, record in enumerate(records):
+ sequence_hidden = normalized_hidden[batch_index, : int(lengths[batch_index])]
+ memory = self.memory_projection(sequence_hidden).unsqueeze(0)
+ global_vector = sequence_hidden[-1]
+ question_vectors = torch.stack(
+ [sequence_hidden[slice(*q.question_span)].mean(0) for q in record.questions]
+ )
+ type_ids = torch.tensor(
+ [q.question_type for q in record.questions], device = hidden_states.device
+ )
+ spans = [span for q in record.questions for span in q.option_spans]
+ option_counts = [len(q.option_spans) for q in record.questions]
+ contexts = torch.stack([sequence_hidden[start:end].mean(0) for start, end in spans])
+ lexical = torch.stack(
+ [
+ output_embedding_weight[input_ids[batch_index, start:end]].to(dtype).mean(0)
+ for start, end in spans
+ ]
+ )
+ owner = torch.repeat_interleave(
+ torch.arange(len(option_counts), device = hidden_states.device),
+ torch.tensor(option_counts, device = hidden_states.device),
+ )
+ routed = (
+ self.option_context_projection(contexts)
+ + self.option_lexical_projection(lexical)
+ + self.option_question_projection(question_vectors)[owner]
+ ).unsqueeze(0)
+ for layer in self.evidence_layers:
+ routed = layer(routed, memory)
+ split_options = torch.split(routed[0], option_counts, dim = 0)
+
+ base_fields = self.question_projection(question_vectors)
+ summaries = []
+ for field, options in zip(base_fields, split_options):
+ weights = torch.softmax(
+ torch.matmul(options, field) / math.sqrt(options.shape[-1]), dim = 0
+ )
+ summaries.append(torch.sum(weights.unsqueeze(-1) * options, dim = 0))
+ fields = (
+ base_fields
+ + self.option_summary_norm(torch.stack(summaries))
+ + self.global_projection(global_vector).unsqueeze(0)
+ + self.type_embedding(type_ids)
+ ).unsqueeze(0)
+ for layer in self.layers:
+ fields = layer(fields, memory)
+ fields = self.field_norm(fields[0])
+
+ anchors = functional.normalize(question_vectors + global_vector, dim = -1)
+ lexical_split = torch.split(lexical, option_counts, dim = 0)
+ record_logits = []
+ for index, (field, options, lexical_options) in enumerate(
+ zip(fields, split_options, lexical_split)
+ ):
+ prior = prior_scale * torch.matmul(
+ functional.normalize(lexical_options, dim = -1), anchors[index]
+ )
+ options = self.option_norm(options)
+ repeated = field.unsqueeze(0).expand_as(options)
+ cosine = functional.cosine_similarity(repeated, options, dim = -1)
+ features = torch.cat(
+ [repeated, options, repeated * options, torch.abs(repeated - options)], dim = -1
+ )
+ residual = self.residual_scorer(features).squeeze(-1)
+ record_logits.append(prior + gate * (joint_scale * cosine + residual))
+ results.append(record_logits)
+ return results
diff --git a/unsloth/models/decision.py b/unsloth/models/decision.py
new file mode 100644
index 00000000000..a5fece628b6
--- /dev/null
+++ b/unsloth/models/decision.py
@@ -0,0 +1,1631 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2023-present Daniel Han-Chen & the Unsloth team. All rights reserved.
+
+__all__ = [
+ "FastDecisionModel",
+ "DecisionTrainer",
+]
+
+import contextlib
+import copy
+import functools
+import importlib.util
+import json
+import math
+import os
+import random
+import sys
+import tempfile
+import types
+from collections import Counter
+from pathlib import Path
+from typing import Callable, Optional
+
+import torch
+from transformers import Trainer, TrainingArguments
+from transformers.training_args import ParallelMode
+
+from ._utils import (
+ _mark_full_finetuning,
+ apply_unsloth_gradient_checkpointing,
+ is_bfloat16_supported,
+)
+from .loader_utils import is_distributed
+
+TRAIN_MAX_LEN, TRAIN_HEAD_MAX_LEN = 1024, 256
+HOLDOUT_MAX = 400
+MIN_CALIBRATION_ITEMS = 10
+HEAD_LEARNING_RATE = 1e-4
+QUESTION_TYPES = ("choice", "score", "noul")
+# DecisionTrainer defaults for Clef; every key is also a DecisionTrainer argument.
+CLEF_RECIPE = {}
+_FILES = ("rl_agent_config.json", "model.safetensors")
+_DIRS = ("encoder", "tokenizer")
+_CLEF_HEAD_FILES = ("joint_head.safetensors", "joint_head_config.json")
+# Copied byte for byte from the checkpoint a Clef fine-tune started from: Cloudflare's loader and
+# license, and the tokenizer / processor files, which transformers would otherwise rewrite (a
+# re-saved tokenizer_config.json trips transformers' "incorrect regex pattern" warning).
+_CLEF_EXTRA_FILES = (
+ "joint_schema_model.py",
+ "LICENSE",
+ "chat_template.jinja",
+ "tokenizer.json",
+ "tokenizer_config.json",
+ "processor_config.json",
+ "generation_config.json",
+)
+CLEF_MAX_LEN = 4096
+# laya 0.3.5 ships inside Unsloth for Studio's Decision API (studio/backend/vendor/README.md).
+_VENDORED_LAYA = (
+ Path(__file__).resolve().parents[2] / "studio" / "backend" / "vendor" / "laya" / "__init__.py"
+).resolve()
+
+
+class DecisionDataError(ValueError):
+ pass
+
+
[email protected]_cache(maxsize = None)
+def _laya():
+ # By path, so a pip installed "laya" is never used or replaced; Studio registers this copy.
+ for name in ("laya", "unsloth._laya"):
+ module = sys.modules.get(name)
+ if getattr(module, "__file__", None) and Path(module.__file__).resolve() == _VENDORED_LAYA:
+ return module
+ if not _VENDORED_LAYA.is_file():
+ raise ImportError(
+ f"Unsloth: decision models need laya, which ships with Unsloth at {_VENDORED_LAYA.parent}. "
+ "Please reinstall Unsloth."
+ )
+ spec = importlib.util.spec_from_file_location(
+ "unsloth._laya", _VENDORED_LAYA, submodule_search_locations = [str(_VENDORED_LAYA.parent)]
+ )
+ module = importlib.util.module_from_spec(spec)
+ sys.modules[spec.name] = module
+ spec.loader.exec_module(module)
+ # laya's JSON reads and writes use a bare open(), which is the locale encoding on Windows.
+ module.agent.open = functools.partial(open, encoding = "utf-8")
+ return module
+
+
+def is_decision_checkpoint(folder) -> bool:
+ folder = Path(folder)
+ return is_clef_checkpoint(folder) or (
+ all((folder / name).is_file() for name in _FILES)
+ and all((folder / name).is_dir() for name in _DIRS)
+ )
+
+
+def is_clef_checkpoint(folder) -> bool:
+ # Cloudflare's Clef layout: a Qwen3.5 backbone plus a joint schema head.
+ folder = Path(folder)
+ return all((folder / name).is_file() for name in ("config.json", *_CLEF_HEAD_FILES))
+
+
+def _is_clef_repo(model_name, prefix, token, revision) -> Optional[bool]:
+ # Asked up front: Unsloth's download wrapper rejects a snapshot that lacks an exact file it was
+ # asked for, so a Laya pattern on a Clef repo (or the reverse) would fail as "incomplete".
+ from huggingface_hub import HfApi, constants
+
+ if constants.HF_HUB_OFFLINE:
+ return None
+ try:
+ files = HfApi(token = token).list_repo_files(model_name, revision = revision)
+ except Exception:
+ return None
+ return prefix + _CLEF_HEAD_FILES[1] in files
+
+
+def _checkpoint_folder(model_name, subfolder, token, revision, local_files_only) -> Path:
+ root = Path(model_name).expanduser()
+ if not root.is_dir():
+ from huggingface_hub import snapshot_download as cached_snapshot
+
+ try:
+ from unsloth_zoo.hf_xet_fallback import (
+ snapshot_download_with_xet_fallback as snapshot_download,
+ )
+ except ImportError:
+ snapshot_download = cached_snapshot
+ prefix = f"{subfolder}/" if subfolder else ""
+ laya = [prefix + name for name in _FILES] + [f"{prefix}{name}/*" for name in _DIRS]
+ clef = None if local_files_only else _is_clef_repo(model_name, prefix, token, revision)
+ if clef is None:
+ # Offline: the cache already holds one layout or the other.
+ root = Path(
+ cached_snapshot(
+ model_name,
+ token = token,
+ revision = revision,
+ local_files_only = True,
+ allow_patterns = laya + [prefix + "*.json"],
+ )
+ )
+ clef = (root / prefix / _CLEF_HEAD_FILES[1]).is_file()
+ # Laya repos hold several checkpoints in subfolders, so only the asked one is fetched.
+ root = Path(
+ snapshot_download(
+ model_name,
+ token = token,
+ revision = revision,
+ local_files_only = local_files_only,
+ allow_patterns = [prefix + "*"] if clef else laya,
+ )
+ )
+ folder = root / subfolder if subfolder else root
+ if not is_decision_checkpoint(folder):
+ raise ValueError(
+ f"Unsloth: {folder} is not a decision model checkpoint "
+ "(rl_agent_config.json, model.safetensors, encoder/ and tokenizer/, "
+ "or a Clef backbone with joint_head.safetensors and joint_head_config.json)."
+ )
+ return folder
+
+
+def _encoder_config(folder):
+ from transformers import AutoConfig
+
+ config = AutoConfig.from_pretrained(str(folder))
+ # transformers 4 ignores transformers 5's rope_parameters; copy the trained thetas over.
+ rope = getattr(config, "rope_parameters", None)
+ if isinstance(rope, dict):
+ for layer_type, name in (
+ ("full_attention", "global_rope_theta"),
+ ("sliding_attention", "local_rope_theta"),
+ ):
+ theta = (rope.get(layer_type) or {}).get("rope_theta")
+ if theta is not None and hasattr(config, name):
+ setattr(config, name, float(theta))
+ return config
+
+
+def _device():
+ if torch.cuda.is_available():
+ return torch.device("cuda")
+ if hasattr(torch, "xpu") and torch.xpu.is_available():
+ return torch.device("xpu")
+ return torch.device("cpu")
+
+
+def _pin_device_map(kwargs) -> None:
+ """Without a caller's device_map, FastModel's planner may split the backbone over every visible GPU, but the decision head reads its embedding rows on one device. Pin the load to this process's device, its LOCAL_RANK under torchrun."""
+ if kwargs.get("device_map") is not None:
+ return
+ from .loader_utils import prepare_device_map
+
+ device_map, _ = prepare_device_map()
+ if device_map is None:
+ device = _device()
+ backend = getattr(torch, device.type, None)
+ index = backend.current_device() if backend is not None and backend.is_available() else 0
+ device_map = {"": f"{device.type}:{index}"}
+ kwargs["device_map"] = device_map
+
+
+def _amp_dtype(device):
+ if device.type == "cuda":
+ return torch.bfloat16 if is_bfloat16_supported() else torch.float16
+ return torch.bfloat16 if device.type == "xpu" else None
+
+
+def _gradient_checkpointing(model, use_gradient_checkpointing) -> None:
+ device = next(model.parameters()).device
+ # Unsloth's offloaded checkpointing needs an accelerator, and its re-entrant backward breaks DDP (#3713).
+ if use_gradient_checkpointing == "unsloth" and (device.type == "cpu" or is_distributed()):
+ use_gradient_checkpointing = True
+ mode = apply_unsloth_gradient_checkpointing(
+ use_gradient_checkpointing, model.decision_config["max_len"], _amp_dtype(device)
+ )
+ if mode == "unsloth" or mode is True:
+ model.encoder.gradient_checkpointing_enable(
+ gradient_checkpointing_kwargs = {"use_reentrant": mode == "unsloth"}
+ )
+ if mode == "unsloth":
+ model.encoder.enable_input_require_grads()
+ else:
+ model.encoder.gradient_checkpointing_disable()
+
+
+def _parsed(value):
+ if isinstance(value, str) and value.strip()[:1] in ("{", "["):
+ try:
+ return json.loads(value)
+ except ValueError:
+ return value
+ return value
+
+
+def _internal(question) -> dict:
+ if not isinstance(question, dict) or question.get("type") not in QUESTION_TYPES:
+ raise DecisionDataError("is not a valid question")
+ kind, criteria = question["type"], question.get("criteria")
+ if kind == "choice" and not (
+ isinstance(criteria, (dict, list))
+ and criteria
+ and all(isinstance(option, str) for option in criteria)
+ ):
+ raise DecisionDataError("needs criteria naming its options")
+ if kind == "score" and not (isinstance(criteria, list) and criteria):
+ raise DecisionDataError("needs a list of criteria levels")
+ if kind == "noul" and criteria is not None and not isinstance(criteria, dict):
+ raise DecisionDataError('criteria may only have "true" and "false"')
+ laya_question = {"type": kind, "instructions": question.get("instructions") or ""}
+ if criteria is not None:
+ laya_question["criteria"] = criteria
+ return _laya().agent.Agent._to_internal(laya_question)
+
+
+def _option_keys(internal: dict) -> list:
+ if internal["t"] == "choice":
+ return [str(key) for key in internal["crit"]]
+ if internal["t"] == "noul":
+ return ["false", "true"]
+ return [str(i) for i in range(len(internal["crit"]))]
+
+
+def _label(kind: str, label):
+ if kind == "score" and isinstance(label, (int, float, str)) and not isinstance(label, bool):
+ try:
+ level = float(label)
+ except ValueError:
+ return None
+ return str(int(level)) if level.is_integer() else None
+ if label is None:
+ return None
+ return str(label).strip().lower() if kind == "noul" else str(label)
+
+
+def _target(internal: dict, gold) -> tuple:
+ return _target_for(internal["t"], _option_keys(internal), gold)
+
+
+def _target_for(kind: str, keys: list, gold) -> tuple:
+ if not isinstance(gold, dict):
+ gold = {"label": gold}
+ label = _label(kind, gold.get("label"))
+ probabilities = gold.get("probabilities")
+ if kind == "noul" and not isinstance(probabilities, dict):
+ noul = gold.get("noul")
+ probabilities = {"true": noul} if isinstance(noul, (int, float)) else None
+ if isinstance(probabilities, dict):
+ try:
+ values = {str(key): float(value) for key, value in probabilities.items()}
+ except (TypeError, ValueError):
+ values = {}
+ if not all(math.isfinite(value) for value in values.values()):
+ raise DecisionDataError("gold has probabilities that are not finite numbers")
+ if kind == "noul" and len(values.keys() & {"false", "true"}) == 1:
+ known = "true" if "true" in values else "false"
+ values[{"true": "false", "false": "true"}[known]] = 1.0 - values[known]
+ target = [max(0.0, values.get(key, 0.0)) for key in keys]
+ total = sum(target)
+ if 0 < total < math.inf:
+ target = [value / total for value in target]
+ return target, keys.index(label) if label in keys else target.index(max(target))
+ if label in keys:
+ return [1.0 if key == label else 0.0 for key in keys], keys.index(label)
+ raise DecisionDataError("gold has no usable label or probabilities")
+
+
+def _soft_cross_entropy(logits, target, mask):
+ logits = logits.float().masked_fill(~mask, -1e4)
+ return -(target * torch.log_softmax(logits, -1)).sum(-1).mean()
+
+
+def _decision_loss(
+ logits,
+ target,
+ mask,
+ ordinal = None,
+ label_smoothing = 0.0,
+ brier_weight = 0.0,
+ ordinal_weight = 0.0,
+):
+ # Cloudflare's Clef recipe: label-smoothed cross entropy, a Brier term for calibration, and
+ # partial credit on score questions (expected distance from the gold level).
+ if not (label_smoothing or brier_weight or ordinal_weight):
+ return _soft_cross_entropy(logits, target, mask)
+ log_p = torch.log_softmax(logits.float().masked_fill(~mask, -1e4), -1)
+ smoothed = target
+ if label_smoothing:
+ uniform = mask.float() / mask.sum(-1, keepdim = True).clamp(min = 1)
+ smoothed = (1.0 - label_smoothing) * target + label_smoothing * uniform
+ loss = -(smoothed * log_p).sum(-1).mean()
+ p = log_p.exp()
+ if brier_weight:
+ loss = loss + brier_weight * ((p - target) ** 2 * mask).sum(-1).mean()
+ if ordinal_weight and ordinal is not None and ordinal.any():
+ levels = torch.arange(p.shape[-1], device = p.device, dtype = p.dtype)
+ distance = (levels[:, None] - levels[None, :]).abs()
+ span = (mask.sum(-1) - 1).clamp(min = 1).to(p.dtype)
+ expected = torch.einsum("ri,ij,rj->r", p, distance, target) / span
+ loss = loss + ordinal_weight * (expected * ordinal).sum() / ordinal.sum()
+ return loss
+
+
+class DecisionDataCollator:
+ def __init__(self, pad_token_id: int):
+ self.pad_token_id = pad_token_id
+
+ def __call__(self, items: list) -> dict:
+ rows, length = len(items), max(len(item["input_ids"]) for item in items)
+ options = max(len(item["markers"]) for item in items)
+ batch = {
+ "input_ids": torch.full((rows, length), self.pad_token_id, dtype = torch.long),
+ "attention_mask": torch.zeros((rows, length), dtype = torch.long),
+ "marker_pos": torch.zeros((rows, options), dtype = torch.long),
+ "marker_mask": torch.zeros((rows, options), dtype = torch.bool),
+ "qtype": torch.tensor([item["qtype"] for item in items]),
+ "target": torch.zeros((rows, options), dtype = torch.float32),
+ }
+ for i, item in enumerate(items):
+ ids, markers = item["input_ids"], item["markers"]
+ batch["input_ids"][i, : len(ids)] = torch.tensor(ids)
+ batch["attention_mask"][i, : len(ids)] = 1
+ batch["marker_pos"][i, : len(markers)] = torch.tensor(markers)
+ batch["marker_mask"][i, : len(markers)] = True
+ batch["target"][i, : len(item["target"])] = torch.tensor(item["target"])
+ return batch
+
+
+class ClefDataCollator:
+ # One row per record: every question of the record is scored jointly, as Clef serves them.
+ # permute_fields re-encodes each training record with its fields shuffled, as Cloudflare's
+ # training data permutes field order; evaluation always keeps the dataset's order.
+ def __init__(
+ self,
+ pad_token_id: int,
+ tokenizer = None,
+ max_len = None,
+ permute_fields = False,
+ seed = 3407,
+ ):
+ self.pad_token_id = pad_token_id
+ self.tokenizer, self.max_len = getattr(tokenizer, "tokenizer", tokenizer), max_len
+ self.permute_fields = permute_fields and tokenizer is not None
+ self.random = random.Random(seed)
+
+ def _permuted(self, item) -> dict:
+ from .clef import encode_record
+
+ order = list(range(len(item["targets"])))
+ self.random.shuffle(order)
+ names = list(item["source"]["questions"])
+ questions = {names[i]: item["source"]["questions"][names[i]] for i in order}
+ try:
+ record = encode_record(
+ self.tokenizer,
+ {"state": item["source"]["state"], "questions": questions},
+ max_length = self.max_len,
+ )
+ except ValueError:
+ return item
+ return {
+ **item,
+ "input_ids": list(record.input_ids),
+ "record": record,
+ "qtypes": [item["qtypes"][i] for i in order],
+ "targets": [item["targets"][i] for i in order],
+ }
+
+ def __call__(self, items: list) -> dict:
+ from .clef import QUESTION_TYPES as CLEF_TYPES
+
+ if self.permute_fields:
+ items = [self._permuted(item) if "source" in item else item for item in items]
+ rows, length = len(items), max(len(item["input_ids"]) for item in items)
+ targets = [target for item in items for target in item["targets"]]
+ options = max(len(target) for target in targets)
+ batch = {
+ "input_ids": torch.full((rows, length), self.pad_token_id, dtype = torch.long),
+ "attention_mask": torch.zeros((rows, length), dtype = torch.long),
+ "records": [item["record"] for item in items],
+ "marker_mask": torch.zeros((len(targets), options), dtype = torch.bool),
+ "target": torch.zeros((len(targets), options), dtype = torch.float32),
+ "ordinal": torch.tensor(
+ [qtype == CLEF_TYPES["score"] for item in items for qtype in item["qtypes"]],
+ dtype = torch.bool,
+ ),
+ }
+ for i, item in enumerate(items):
+ batch["input_ids"][i, : len(item["input_ids"])] = torch.tensor(item["input_ids"])
+ batch["attention_mask"][i, : len(item["input_ids"])] = 1
+ for i, target in enumerate(targets):
+ batch["marker_mask"][i, : len(target)] = True
+ batch["target"][i, : len(target)] = torch.tensor(target)
+ return batch
+
+
+class ClefDecisionModel(torch.nn.Module):
+ # `encoder` is the Qwen3.5 backbone, named like Laya's so the trainer treats both alike.
+ is_clef = True
+
+ def __init__(self, encoder, head):
+ super().__init__()
+ self.encoder = encoder
+ self.head = head
+
+ def _backbone(self):
+ return (
+ self.encoder.get_base_model()
+ if hasattr(self.encoder, "get_base_model")
+ else self.encoder
+ )
+
+ def forward(
+ self,
+ input_ids,
+ attention_mask,
+ records,
+ head = None,
+ **kwargs,
+ ):
+ head = self.head if head is None else head
+ backbone = self._backbone()
+ text_model = backbone.model
+ text_model = getattr(text_model, "language_model", text_model)
+ hidden = text_model(
+ input_ids = input_ids,
+ attention_mask = attention_mask,
+ use_cache = False,
+ return_dict = True,
+ ).last_hidden_state
+ logits = head(
+ hidden,
+ input_ids,
+ attention_mask,
+ records,
+ backbone.get_output_embeddings().weight.detach(),
+ )
+ if hasattr(logits, "flat_padded"):
+ return logits.flat_padded, None
+ flat = [question for record in logits for question in record]
+ padded = torch.full(
+ (len(flat), max(len(z) for z in flat)), -1e4, dtype = flat[0].dtype, device = flat[0].device
+ )
+ for i, z in enumerate(flat):
+ padded[i, : len(z)] = z
+ return padded, None
+
+
+def _clef_question(question) -> dict:
+ if not isinstance(question, dict) or question.get("type") not in QUESTION_TYPES:
+ raise DecisionDataError("is not a valid question")
+ kind, criteria = question["type"], question.get("criteria")
+ if kind == "choice":
+ if isinstance(criteria, list) and criteria and all(isinstance(c, str) for c in criteria):
+ criteria = dict.fromkeys(criteria)
+ if not (isinstance(criteria, dict) and criteria):
+ raise DecisionDataError("needs criteria naming its options")
+ if len({str(key) for key in criteria}) != len(criteria):
+ raise DecisionDataError("has repeated options")
+ if kind == "score" and not (isinstance(criteria, list) and criteria):
+ raise DecisionDataError("needs a list of criteria levels")
+ if kind == "noul" and criteria is not None:
+ if not isinstance(criteria, dict) or set(criteria) - {"true", "false"}:
+ raise DecisionDataError('criteria may only have "true" and "false"')
+ clef_question = {"type": kind, "instructions": question.get("instructions")}
+ if criteria is not None:
+ clef_question["criteria"] = criteria
+ return clef_question
+
+
+def _clef_items(rows, tokenizer, max_len, validate, report, skip) -> list:
+ from .clef import QUESTION_TYPES as CLEF_TYPES, encode_record, question_options
+
+ tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
+ items = []
+ for index, row in enumerate(rows):
+ row = row if isinstance(row, dict) else {}
+ state = _parsed(row.get("state"))
+ questions = _parsed(row.get("questions"))
+ gold = _parsed(row["gold"] if row.get("gold") is not None else row.get("answers"))
+ if state is None or not isinstance(questions, dict) or not isinstance(gold, dict):
+ report["total"] += 1
+ skip(index, "needs state, questions and gold")
+ continue
+ kept, targets, labels = {}, [], []
+ for name, question in questions.items():
+ report["total"] += 1
+ if name not in gold:
+ skip(index, "has no gold", name)
+ continue
+ try:
+ if validate is not None:
+ validate(name, question)
+ clef_question = _clef_question(question)
+ keys = [key for key, _ in question_options(clef_question)]
+ target, label = _target_for(clef_question["type"], keys, _parsed(gold[name]))
+ except (TypeError, ValueError, KeyError) as exc:
+ skip(index, str(exc) or "is not a valid question", name)
+ continue
+ kept[str(name)], targets, labels = clef_question, targets + [target], labels + [label]
+ if not kept:
+ continue
+ try:
+ record = encode_record(
+ tokenizer, {"state": state, "questions": kept}, max_length = max_len
+ )
+ except (TypeError, ValueError) as exc:
+ for name in kept:
+ skip(index, f"does not fit: {exc}", name)
+ continue
+ items.append(
+ {
+ "input_ids": list(record.input_ids),
+ "record": record,
+ "qtypes": [CLEF_TYPES[q["type"]] for q in kept.values()],
+ "targets": targets,
+ "labels": labels,
+ "row": index,
+ "source": {"state": state, "questions": kept},
+ }
+ )
+ return items
+
+
+def _clef_logits(
+ model,
+ items: list,
+ pad_token_id: int,
+ batch_size: int = 4,
+) -> tuple:
+ # Per question logits plus one Laya-shaped item per question for the shared metrics.
+ from .clef import QUESTION_TYPES as CLEF_TYPES
+
+ device = next(model.parameters()).device
+ amp_dtype = _clef_amp_dtype(model, device)
+ collate = ClefDataCollator(pad_token_id)
+ # Clef numbers question types noul, choice, score; Laya's metrics use choice, score, noul.
+ laya_type = {CLEF_TYPES[kind]: QUESTION_TYPES.index(kind) for kind in QUESTION_TYPES}
+ was_training = model.training
+ model.eval()
+ logits, questions = [], []
+ for start in range(0, len(items), batch_size):
+ chunk = items[start : start + batch_size]
+ batch = collate(chunk)
+ batch.pop("target")
+ inputs = {k: v.to(device) if torch.is_tensor(v) else v for k, v in batch.items()}
+ with torch.autocast(device.type, dtype = amp_dtype, enabled = amp_dtype is not None):
+ z, _ = model(**inputs)
+ z = z.float().cpu()
+ flat = [
+ (target, label, qtype, item["row"])
+ for item in chunk
+ for target, label, qtype in zip(item["targets"], item["labels"], item["qtypes"])
+ ]
+ for row, (target, label, qtype, record_row) in enumerate(flat):
+ logits.append(z[row, : len(target)])
+ questions.append(
+ {"target": target, "label": label, "qtype": laya_type[qtype], "row": record_row}
+ )
+ model.train(was_training)
+ return logits, questions
+
+
+def _decision_logits(
+ model,
+ tokenizer,
+ items: list,
+ batch_size = None,
+) -> tuple:
+ pad_token_id = getattr(tokenizer, "tokenizer", tokenizer).pad_token_id
+ if getattr(model, "is_clef", False):
+ # A run that lowered its batch to fit a 9B / 27B backbone scores in that batch too.
+ return _clef_logits(model, items, pad_token_id, batch_size or 4)
+ return _logits(model, items, pad_token_id), items
+
+
+# Kept in 16-bit like unsloth/Qwen3.8-27B-unsloth-bnb-4bit: Clef's backbone is a merged
+# fine-tune, not stock Qwen, so it is quantized on load with the same dynamic list.
+CLEF_4BIT_SKIP_MODULES = (
+ "model.visual",
+ r".*\.visual\..*",
+ "in_proj_a",
+ "in_proj_b",
+ "in_proj_qkv",
+)
+
+
+def _clef_bnb_config(dtype):
+ from transformers import BitsAndBytesConfig
+ from unsloth_zoo.peft_utils import SKIP_QUANTIZATION_MODULES
+
+ float16 = dtype == torch.float16 or not is_bfloat16_supported()
+ return BitsAndBytesConfig(
+ load_in_4bit = True,
+ bnb_4bit_use_double_quant = True,
+ bnb_4bit_quant_type = "nf4",
+ bnb_4bit_compute_dtype = torch.float16 if float16 else torch.bfloat16,
+ llm_int8_skip_modules = list(SKIP_QUANTIZATION_MODULES) + list(CLEF_4BIT_SKIP_MODULES),
+ )
+
+
+def _clef_forced_float32(model) -> bool:
+ return bool(getattr(model, "_unsloth_forced_float32", False))
+
+
+def _clef_amp_dtype(model, device):
+ # Never fp16 autocast: the gated delta net overflows in pure fp16, so a model on Unsloth's
+ # float32 path runs as Unsloth loaded it. Serving uses this too, to match calibration.
+ amp_dtype = _amp_dtype(device)
+ return None if amp_dtype != torch.bfloat16 or _clef_forced_float32(model) else amp_dtype
+
+
+def _load_clef(
+ folder,
+ max_seq_length,
+ dtype,
+ load_in_4bit,
+ full_finetuning,
+ token,
+ use_gradient_checkpointing,
+ kwargs,
+):
+ from safetensors.torch import load_file
+
+ from .clef import JointSchemaHead
+
+ max_len = int(max_seq_length or CLEF_MAX_LEN)
+ fast = _device().type != "cpu"
+ if fast:
+ from .loader import FastModel
+
+ # FastModel drops load_in_4bit for full finetuning, but not an explicit quantization config.
+ if load_in_4bit and not full_finetuning and kwargs.get("quantization_config") is None:
+ kwargs["quantization_config"] = _clef_bnb_config(dtype)
+ _pin_device_map(kwargs)
+ # A float16 request (or a GPU without bfloat16) puts Qwen3.5 on Unsloth's float32 path,
+ # which stores bfloat16 weights: the gated delta net NaNs in pure float16.
+ backbone, processor = FastModel.from_pretrained(
+ str(folder),
+ max_seq_length = max_len,
+ dtype = dtype,
+ load_in_4bit = load_in_4bit,
+ full_finetuning = full_finetuning,
+ token = token,
+ use_gradient_checkpointing = use_gradient_checkpointing,
+ **kwargs,
+ )
+ else:
+ from transformers import AutoModelForImageTextToText, AutoProcessor
+
+ backbone = AutoModelForImageTextToText.from_pretrained(
+ str(folder), dtype = dtype or torch.float32
+ )
+ processor = AutoProcessor.from_pretrained(str(folder))
+ if not full_finetuning:
+ backbone.requires_grad_(False)
+ backbone.config.use_cache = False
+ head_config = json.loads((folder / _CLEF_HEAD_FILES[1]).read_text(encoding = "utf-8"))
+ head = JointSchemaHead(**head_config)
+ head.load_state_dict(load_file(str(folder / _CLEF_HEAD_FILES[0])), strict = True)
+ device = next(backbone.parameters()).device
+ # The head trains in fp32 over the 16-bit backbone, as the Laya head does.
+ model = ClefDecisionModel(backbone, head.to(device = device, dtype = torch.float32))
+ config = {"layout": "clef", "max_len": max_len, "temperature": [1.0] * 3}
+ saved = folder / "unsloth_decision_config.json"
+ if saved.is_file():
+ config.update(json.loads(saved.read_text(encoding = "utf-8")), max_len = max_len)
+ # The parent run's training record does not describe the next fine-tune, as for Laya.
+ config.pop("training", None)
+ model.decision_config = config
+ _mark_full_finetuning(model, full_finetuning)
+ model._unsloth_forced_float32 = bool(getattr(backbone, "_unsloth_forced_float32", False))
+ model._unsloth_fast_backbone = fast
+ model._saved_temp_tokenizer = processor
+ model._unsloth_source_folder = str(folder)
+ model._unsloth_source_vocab = len(getattr(processor, "tokenizer", processor))
+ model.save_pretrained_merged = types.MethodType(save_pretrained_merged, model)
+ model.push_to_hub_merged = types.MethodType(push_to_hub_merged, model)
+ return model, processor
+
+
+def _clef_peft_model(model, target_modules, use_gradient_checkpointing, random_state, **kwargs):
+ # LoRA on the language model only; the vision tower and the lm_head the head reads stay frozen.
+ if target_modules == "all-linear":
+ target_modules = None
+ backbone = model.encoder
+ if getattr(model, "_unsloth_fast_backbone", False):
+ from .loader import FastModel
+ model.encoder = FastModel.get_peft_model(
+ backbone,
+ target_modules = target_modules,
+ finetune_vision_layers = False,
+ finetune_language_layers = True,
+ use_gradient_checkpointing = use_gradient_checkpointing,
+ random_state = random_state,
+ **kwargs,
+ )
+ else:
+ from peft import LoraConfig, get_peft_model
+ from transformers import set_seed
+
+ set_seed(random_state)
+ kwargs.pop("max_seq_length", None)
+ model.encoder = get_peft_model(
+ backbone,
+ LoraConfig(
+ target_modules = target_modules
+ or r"model\.language_model\.layers\.\d+\..*\.(q_proj|k_proj|v_proj|o_proj|in_proj_qkv|in_proj_z|out_proj|gate_proj|up_proj|down_proj)",
+ **kwargs,
+ ),
+ )
+ return model
+
+
+def _commit_staged(
+ staging: Path,
+ output: Path,
+ marker: str,
+ stale = (),
+) -> None:
+ # Old files stay until the new ones are complete; the marker that makes a folder a
+ # checkpoint moves in last, so a failed save leaves the previous checkpoint loadable.
+ import shutil
+
+ staged = sorted(staging.iterdir(), key = lambda path: path.name == marker)
+ names = {path.name for path in staged}
+ for path in staged:
+ target = output / path.name
+ if path.is_dir() and target.is_dir():
+ old = output / f".{path.name}.unsloth-old"
+ shutil.rmtree(old, ignore_errors = True)
+ os.replace(target, old)
+ os.replace(path, target)
+ shutil.rmtree(old, ignore_errors = True)
+ else:
+ os.replace(path, target)
+ for path in output.iterdir():
+ if path.name not in names and any(path.match(pattern) for pattern in stale):
+ path.unlink()
+
+
+def _staging(output: Path):
+ import shutil
+
+ output.mkdir(parents = True, exist_ok = True)
+ staging = Path(tempfile.mkdtemp(prefix = ".unsloth-save-", dir = output))
+ try:
+ yield staging
+ finally:
+ shutil.rmtree(staging, ignore_errors = True)
+
+
+def _fold_temperature(state: dict, temperature: float) -> bool:
+ # logits / T == prior / T + gate * (joint_scale / T * cosine + residual / T): exact while the
+ # rescaled log-scales stay under the head's clamp(max = log 100).
+ cap = math.log(100.0)
+ scales = {}
+ for name in ("prior_logit_scale", "joint_logit_scale"):
+ value = min(float(state[name]), cap) - math.log(temperature)
+ if value > cap:
+ return False
+ scales[name] = value
+ for name, value in scales.items():
+ state[name] = torch.tensor(value, dtype = state[name].dtype)
+ last = max(int(key.split(".")[1]) for key in state if key.startswith("residual_scorer."))
+ for kind in ("weight", "bias"):
+ state[f"residual_scorer.{last}.{kind}"] = (
+ state[f"residual_scorer.{last}.{kind}"] / temperature
+ )
+ return True
+
+
+def _stamp_transformers_version(config_file: Path) -> None:
+ # Unsloth's merged save writes config.json without transformers_version; transformers then
+ # cannot rule out an old Mistral tokenizer and warns of an "incorrect regex pattern" on load.
+ import transformers
+
+ if not config_file.is_file():
+ return
+ config = json.loads(config_file.read_text(encoding = "utf-8"))
+ if "transformers_version" not in config:
+ config["transformers_version"] = transformers.__version__
+ config_file.write_text(json.dumps(config, indent = 2) + "\n", encoding = "utf-8")
+
+
+def _save_clef(self, save_directory, tokenizer) -> None:
+ import shutil
+
+ from safetensors.torch import save_file
+
+ output = Path(save_directory)
+ config = {**self.decision_config, "fine_tuned": True}
+ state = {k: v.detach().to("cpu", torch.float32) for k, v in self.head.state_dict().items()}
+ # Folded in, so Cloudflare's loader serves calibrated confidences too; the per-type
+ # temperatures Unsloth applies are already relative to it.
+ temperature = config.pop("head_temperature", None)
+ if temperature and temperature != 1.0:
+ if _fold_temperature(state, temperature):
+ config["folded_temperature"] = config.get("folded_temperature", 1.0) * temperature
+ else:
+ config["head_temperature"] = temperature
+ weights = {}
+ for name, value in state.items():
+ # The logit scales stay float32: a folded temperature moves them, and bfloat16's 8 bit
+ # mantissa would turn that into a few percent on every logit.
+ value = value.to(torch.float32 if value.dim() == 0 else torch.bfloat16).contiguous()
+ if not torch.isfinite(value).all():
+ raise ValueError(
+ f"Unsloth: head weight {name} is not finite, so the model cannot be saved."
+ )
+ weights[name] = value
+ source = Path(getattr(self, "_unsloth_source_folder", "") or output)
+ with _staging(output) as staging:
+ encoder = self.encoder
+ if hasattr(encoder, "save_pretrained_merged"):
+ # Unsloth's merge dequantizes a 4-bit base and writes the processor files too.
+ encoder.save_pretrained_merged(str(staging), tokenizer, save_method = "merged_16bit")
+ else:
+ if hasattr(encoder, "merge_and_unload"):
+ encoder = copy.deepcopy(encoder).merge_and_unload()
+ encoder.save_pretrained(str(staging))
+ tokenizer.save_pretrained(str(staging))
+ text_tokenizer = getattr(tokenizer, "tokenizer", tokenizer)
+ # A tokenizer the caller grew (added tokens) is saved as it is.
+ same_tokenizer = len(text_tokenizer) == getattr(self, "_unsloth_source_vocab", -1)
+ for name in _CLEF_EXTRA_FILES:
+ if not same_tokenizer and name.startswith("tokenizer"):
+ continue
+ if (source / name).is_file():
+ shutil.copyfile(source / name, staging / name)
+ _stamp_transformers_version(staging / "config.json")
+ (staging / "unsloth_decision_config.json").write_text(
+ json.dumps(config, indent = 2), encoding = "utf-8"
+ )
+ (staging / _CLEF_HEAD_FILES[1]).write_text(
+ json.dumps(self.head.config, indent = 2), encoding = "utf-8"
+ )
+ save_file(weights, str(staging / _CLEF_HEAD_FILES[0]))
+ _commit_staged(
+ staging,
+ output,
+ _CLEF_HEAD_FILES[0],
+ stale = ("model*.safetensors", "model.safetensors.index.json"),
+ )
+
+
+def _clef_mixed_precision(model, args) -> None:
+ # Unsloth's rule for Qwen3.5 (rl.py): on its float32 path a model never autocasts, since
+ # float16 NaNs the gated delta net; otherwise its bfloat16 weights pair with bf16 only.
+ if _clef_forced_float32(model):
+ if args.fp16 or args.bf16:
+ print("Unsloth: Clef trains in float32 here, since Qwen3.5 cannot train in float16.")
+ args.fp16 = args.bf16 = False
+ elif args.fp16:
+ print("Unsloth: Clef is in bfloat16, so fp16 = True is switched to bf16 = True.")
+ args.fp16, args.bf16 = False, True
+ # transformers 5 reads the accelerator's precision from here (4.x from fp16 / bf16).
+ if hasattr(args, "mixed_precision"):
+ args.mixed_precision = "bf16" if args.bf16 else "no"
+
+
+class _LengthGroupedBatches(torch.utils.data.Sampler):
+ # Similar-length micro-batches, shuffled so a step mixes lengths; longest first to show OOM.
+ def __init__(self, lengths: list, batch_size: int, seed: int):
+ self.lengths, self.batch_size, self.seed, self.epoch = lengths, batch_size, seed, 0
+
+ def __len__(self):
+ return len(self.lengths)
+
+ def set_epoch(self, epoch: int) -> None:
+ self.epoch = epoch
+
+ def __iter__(self):
+ from transformers.trainer_pt_utils import get_length_grouped_indices
+
+ seed = self.seed + self.epoch
+ order = get_length_grouped_indices(
+ self.lengths, self.batch_size, generator = torch.Generator().manual_seed(seed)
+ )
+ batches = [order[i : i + self.batch_size] for i in range(0, len(order), self.batch_size)]
+ short = batches.pop() if len(batches) > 1 and len(batches[-1]) < self.batch_size else []
+ rest = batches[1:]
+ random.Random(seed).shuffle(rest)
+ return iter([index for batch in batches[:1] + rest + [short] for index in batch])
+
+
+class DecisionTrainer(Trainer):
+ def __init__(
+ self,
+ model = None,
+ args = None,
+ *,
+ head_learning_rate: Optional[float] = None,
+ tokenizer = None,
+ label_smoothing: Optional[float] = None,
+ brier_weight: Optional[float] = None,
+ ordinal_weight: Optional[float] = None,
+ kl_weight: float = 0.0,
+ permute_fields: Optional[bool] = None,
+ **kwargs,
+ ):
+ # Laya never loads through FastLanguageModel / FastModel, which apply this patch: without it
+ # transformers 5.0 - 5.5 divides accumulated gradients by gradient_accumulation_steps twice.
+ from ._utils import patch_gradient_accumulation_fix
+
+ patch_gradient_accumulation_fix(Trainer)
+ args = copy.copy(args) if args is not None else TrainingArguments(output_dir = "tmp_trainer")
+ recipe = CLEF_RECIPE if getattr(model, "is_clef", False) else {}
+ if label_smoothing is None:
+ label_smoothing = args.label_smoothing_factor or recipe.get("label_smoothing", 0.0)
+ self.label_smoothing = float(label_smoothing)
+ self.brier_weight = float(
+ recipe.get("brier_weight", 0.0) if brier_weight is None else brier_weight
+ )
+ self.ordinal_weight = float(
+ recipe.get("ordinal_weight", 0.0) if ordinal_weight is None else ordinal_weight
+ )
+ self.kl_weight = float(kl_weight)
+ if permute_fields is None:
+ permute_fields = recipe.get("permute_fields", False)
+ # Opt in: a KL penalty to the starting model (adapters off, the head as loaded), against
+ # forgetting what the base model knew outside the fine-tuning data.
+ self._reference_head = None
+ if self.kl_weight:
+ if not getattr(model, "is_clef", False):
+ raise NotImplementedError("Unsloth: kl_weight needs a Clef decision model.")
+ # The reference is the backbone with its adapters off, which full finetuning does not have.
+ if not hasattr(model.encoder, "disable_adapter"):
+ raise NotImplementedError(
+ "Unsloth: kl_weight needs a LoRA Clef model, not full finetuning."
+ )
+ self._reference_head = copy.deepcopy(model.head).requires_grad_(False)
+ args.remove_unused_columns = False
+ # The model trains on one GPU: no DataParallel, and the batch stays per_device_train_batch_size.
+ if args.parallel_mode == ParallelMode.NOT_DISTRIBUTED:
+ args._n_gpu = 1
+ if args.label_names is None:
+ args.label_names = ["target"]
+ clef = getattr(model, "is_clef", False)
+ if clef:
+ _clef_mixed_precision(model, args)
+ if args.gradient_checkpointing:
+ # Trainer would call model.gradient_checkpointing_enable, which only the encoder has.
+ # Clef's backbone already got Unsloth's checkpointing when it loaded.
+ args.gradient_checkpointing = False
+ if not clef and not model.encoder.is_gradient_checkpointing:
+ _gradient_checkpointing(model, True)
+ if kwargs.get("processing_class") is None:
+ kwargs["processing_class"] = tokenizer
+ if kwargs.get("data_collator") is None:
+ processing_class = kwargs["processing_class"]
+ if processing_class is None:
+ pad_token_id = getattr(model, "_saved_temp_tokenizer", None)
+ pad_token_id = (
+ getattr(pad_token_id, "tokenizer", pad_token_id).pad_token_id
+ if clef
+ else model.encoder.config.pad_token_id
+ )
+ else:
+ pad_token_id = getattr(processing_class, "tokenizer", processing_class).pad_token_id
+ if clef:
+ kwargs["data_collator"] = ClefDataCollator(
+ pad_token_id,
+ tokenizer = kwargs["processing_class"]
+ or getattr(model, "_saved_temp_tokenizer", None),
+ max_len = model.decision_config["max_len"],
+ permute_fields = permute_fields,
+ seed = args.seed,
+ )
+ else:
+ kwargs["data_collator"] = DecisionDataCollator(pad_token_id)
+ self.head_learning_rate = head_learning_rate
+ super().__init__(model = model, args = args, **kwargs)
+
+ @contextlib.contextmanager
+ def _dataset_field_order(self):
+ collator = self.data_collator
+ permute = getattr(collator, "permute_fields", False)
+ if permute:
+ collator.permute_fields = False
+ try:
+ yield
+ finally:
+ if permute:
+ collator.permute_fields = True
+
+ def evaluate(self, *args, **kwargs):
+ with self._dataset_field_order():
+ return super().evaluate(*args, **kwargs)
+
+ def predict(self, *args, **kwargs):
+ with self._dataset_field_order():
+ return super().predict(*args, **kwargs)
+
+ def _get_train_sampler(self, train_dataset = None):
+ dataset = self.train_dataset if train_dataset is None else train_dataset
+ # With one micro-batch per step, length grouping would make each step one question type.
+ if dataset is None or self.args.gradient_accumulation_steps == 1:
+ return super()._get_train_sampler(train_dataset)
+ return _LengthGroupedBatches(
+ [len(item["input_ids"]) for item in dataset], self.args.train_batch_size, self.args.seed
+ )
+
+ def compute_loss(
+ self,
+ model,
+ inputs,
+ return_outputs = False,
+ num_items_in_batch = None,
+ ):
+ target = inputs.pop("target")
+ ordinal = inputs.pop("ordinal", None)
+ logits, _ = model(**inputs)
+ mask = inputs["marker_mask"]
+ loss = _decision_loss(
+ logits,
+ target,
+ mask,
+ ordinal,
+ self.label_smoothing,
+ self.brier_weight,
+ self.ordinal_weight,
+ )
+ if self._reference_head is not None:
+ unwrapped = self.accelerator.unwrap_model(model)
+ with torch.no_grad(), unwrapped.encoder.disable_adapter():
+ reference, _ = unwrapped(**inputs, head = self._reference_head)
+ log_ref = torch.log_softmax(reference.float().masked_fill(~mask, -1e4), -1)
+ log_p = torch.log_softmax(logits.float().masked_fill(~mask, -1e4), -1)
+ kl = (log_ref.exp() * (log_ref - log_p) * mask).sum(-1).mean()
+ loss = loss + self.kl_weight * kl
+ return (loss, {"loss": loss, "logits": logits}) if return_outputs else loss
+
+ def create_optimizer(self, model = None):
+ if self.optimizer is not None:
+ return self.optimizer
+ model = self.model if model is None else model
+ decay = set(self.get_decay_parameter_names(model))
+ head_lr = HEAD_LEARNING_RATE if self.head_learning_rate is None else self.head_learning_rate
+ groups = {}
+ for name, param in model.named_parameters():
+ if param.requires_grad:
+ groups.setdefault((name.startswith("encoder."), name in decay), []).append(param)
+ optimizer_cls, optimizer_kwargs = (
+ self.optimizer_cls_and_kwargs or self.get_optimizer_cls_and_kwargs(self.args, model)
+ )
+ self.optimizer = optimizer_cls(
+ [
+ {
+ "params": params,
+ "weight_decay": self.args.weight_decay if decayed else 0.0,
+ **({} if encoder else {"lr": head_lr}),
+ }
+ for (encoder, decayed), params in groups.items()
+ ],
+ **optimizer_kwargs,
+ )
+ return self.optimizer
+
+
+def _logits(
+ model,
+ items: list,
+ pad_token_id: int,
+ batch_size: int = 16,
+) -> list:
+ device = next(model.parameters()).device
+ amp_dtype = _amp_dtype(device)
+ collate = DecisionDataCollator(pad_token_id)
+ was_training = model.training
+ model.eval()
+ out = []
+ for start in range(0, len(items), batch_size):
+ chunk = items[start : start + batch_size]
+ batch = collate(chunk)
+ batch.pop("target")
+ with torch.autocast(device.type, dtype = amp_dtype, enabled = amp_dtype is not None):
+ logits, _ = model(**{k: v.to(device) for k, v in batch.items()})
+ logits = logits.float().cpu()
+ out.extend(logits[row, : len(item["markers"])] for row, item in enumerate(chunk))
+ model.train(was_training)
+ return out
+
+
+def _metrics(logits, items, temperatures) -> dict:
+ import numpy as np
+
+ conf, correct, loss, records = [], [], [], {}
+ for z, item, temperature in zip(logits, items, temperatures):
+ log_p = torch.log_softmax(z / temperature, -1)
+ conf.append(float(log_p.exp().max()))
+ correct.append(float(int(log_p.argmax()) == item["label"]))
+ loss.append(float(-(torch.tensor(item["target"]) * log_p).sum()))
+ row = item.get("row", ("item", len(correct)))
+ records[row] = records.get(row, True) and bool(correct[-1])
+ return {
+ "accuracy": float(np.mean(correct)),
+ "ece": _laya().common.ece_score(np.array(conf), np.array(correct)),
+ "loss": float(np.mean(loss)),
+ # Every question of a row right, the record-level precision Cloudflare rewards.
+ "record_accuracy": float(np.mean(list(records.values()))),
+ }
+
+
+def _fit_temperature(
+ logits,
+ items,
+ line_search = None,
+) -> float:
+ options = max(len(z) for z in logits)
+ z = torch.full((len(logits), options), -1e4)
+ target = torch.zeros((len(logits), options))
+ for i, (row, item) in enumerate(zip(logits, items)):
+ z[i, : len(row)] = row
+ target[i, : len(row)] = torch.tensor(item["target"])
+ log_t = torch.zeros(1, requires_grad = True)
+ # Clef's hard-label fit passes "strong_wolfe": plain LBFGS can overshoot on peaked targets.
+ optimizer = torch.optim.LBFGS([log_t], lr = 0.1, max_iter = 100, line_search_fn = line_search)
+
+ def closure():
+ optimizer.zero_grad()
+ loss = -(target * torch.log_softmax(z / log_t.exp(), -1)).sum(-1).mean()
+ loss.backward()
+ return loss
+
+ optimizer.step(closure)
+ return float(log_t.exp().item())
+
+
+def _fit_temperatures(logits, items, indices, fallback: list) -> tuple:
+ clamp = _laya().common.clamp_temperature
+ temperature, fitted = list(fallback), set()
+ for qtype in range(3):
+ chosen = [i for i in indices if items[i]["qtype"] == qtype]
+ if len(chosen) >= MIN_CALIBRATION_ITEMS:
+ temperature[qtype] = clamp(
+ _fit_temperature([logits[i] for i in chosen], [items[i] for i in chosen])
+ )
+ fitted.add(qtype)
+ return temperature, fitted
+
+
+def _served_temperatures(config: dict, logits, items) -> list:
+ common = _laya().common
+ per_type = [common.clamp_temperature(t) for t in config.get("temperature", [1.0] * 3)]
+ buckets = {
+ key: common.clamp_temperature(value)
+ for key, value in (config.get("temperature_by_options") or {}).items()
+ }
+ # A Clef temperature not yet folded into the head (_save_clef folds it on save).
+ head = config.get("head_temperature", 1.0)
+ return [
+ head * buckets.get(common.temp_bucket(item["qtype"], len(z)), per_type[item["qtype"]])
+ for z, item in zip(logits, items)
+ ]
+
+
+HEAD_TEMPERATURE_RANGE = (0.05, 20.0)
+
+
+def _calibrate_clef(config: dict, logits, items) -> dict:
+ # Calibrated against being right (the gold label), not the soft gold distribution: Clef's
+ # confidence is read as the chance the answer is correct, and soft gold targets left a tuned
+ # model underconfident (confidence 0.61 at accuracy 0.78 on typed-decisions).
+ common = _laya().common
+ hard = [
+ {**item, "target": [float(j == item["label"]) for j in range(len(z))]}
+ for z, item in zip(logits, items)
+ ]
+
+ def fit(indices) -> tuple:
+ chosen = list(indices)
+ head = _fit_temperature(
+ [logits[i] for i in chosen], [hard[i] for i in chosen], line_search = "strong_wolfe"
+ )
+ head = min(max(head, HEAD_TEMPERATURE_RANGE[0]), HEAD_TEMPERATURE_RANGE[1])
+ scaled = [z / head for z in logits]
+ relative, fitted = _fit_temperatures(scaled, hard, chosen, [1.0] * 3)
+ return head, relative, fitted
+
+ everything = range(len(items))
+ if len(items) < MIN_CALIBRATION_ITEMS:
+ return {
+ **_metrics(logits, items, _served_temperatures(config, logits, items)),
+ "fitted_types": [],
+ }
+ head, relative, fitted = fit(everything)
+ half = {row: i % 2 for i, row in enumerate(sorted({item["row"] for item in items}))}
+ per_item = [head * common.clamp_temperature(relative[item["qtype"]]) for item in items]
+ for side in (0, 1) if len(half) > 1 else ():
+ side_head, side_relative, _ = fit(i for i in everything if half[items[i]["row"]] != side)
+ for i in everything:
+ if half[items[i]["row"]] == side:
+ per_item[i] = side_head * common.clamp_temperature(side_relative[items[i]["qtype"]])
+ config["head_temperature"] = head
+ config["temperature"] = relative
+ config.pop("temperature_by_options", None)
+ return {**_metrics(logits, items, per_item), "fitted_types": sorted(fitted)}
+
+
+def save_pretrained_merged(
+ self,
+ save_directory,
+ tokenizer = None,
+ save_method = "merged_16bit",
+ **kwargs,
+) -> None:
+ from safetensors.torch import save_file
+
+ if save_method != "merged_16bit":
+ raise NotImplementedError(
+ f"Unsloth: decision models are saved merged in 16-bit, not as {save_method!r}."
+ )
+ tokenizer = self._saved_temp_tokenizer if tokenizer is None else tokenizer
+ if getattr(self, "is_clef", False):
+ return _save_clef(self, save_directory, tokenizer)
+ encoder = self.encoder
+ if hasattr(encoder, "merge_and_unload"):
+ # Merged on a CPU copy: the model keeps its adapters and the GPU never holds a second encoder.
+ device = next(encoder.parameters()).device
+ encoder.to("cpu")
+ try:
+ encoder = copy.deepcopy(encoder).merge_and_unload()
+ finally:
+ self.encoder.to(device)
+ state = {f"encoder.{k}": v for k, v in encoder.state_dict().items()}
+ state.update((k, v) for k, v in self.state_dict().items() if not k.startswith("encoder."))
+ weights = {}
+ for name, value in state.items():
+ value = value.detach().to("cpu", torch.float16).contiguous()
+ if not torch.isfinite(value).all():
+ raise ValueError(
+ f"Unsloth: {name} has NaN or values too large for float16, so the model cannot be saved."
+ )
+ weights[name] = value
+ encoder_config = self._unsloth_encoder_config
+ vocab = encoder.get_input_embeddings().num_embeddings
+ if json.loads(encoder_config).get("vocab_size") != vocab:
+ # A caller-grown tokenizer resized the embedding; the source config keeps its bytes otherwise.
+ encoder_config = json.dumps({**json.loads(encoder_config), "vocab_size": vocab}, indent = 2)
+ del encoder, state
+ config = json.dumps({**self.decision_config, "fine_tuned": True}, indent = 2)
+
+ with _staging(Path(save_directory)) as staging:
+ save_file(weights, str(staging / "model.safetensors"))
+ (staging / "encoder").mkdir()
+ (staging / "encoder" / "config.json").write_text(encoder_config, encoding = "utf-8")
+ tokenizer.save_pretrained(str(staging / "tokenizer"))
+ _laya().agent._fix_tokenizer_config(str(staging))
+ (staging / "rl_agent_config.json").write_text(config, encoding = "utf-8")
+ # A folder with rl_agent_config.json is a complete checkpoint, so it moves in last.
+ _commit_staged(staging, Path(save_directory), "rl_agent_config.json")
+
+
+def push_to_hub_merged(
+ self,
+ repo_id,
+ tokenizer = None,
+ save_method = "merged_16bit",
+ token = None,
+ private = None,
+ **kwargs,
+) -> None:
+ from huggingface_hub import HfApi
+
+ api = HfApi(token = token)
+ repo_id = api.create_repo(repo_id, private = private, exist_ok = True).repo_id
+ with tempfile.TemporaryDirectory() as folder:
+ self.save_pretrained_merged(folder, tokenizer, save_method)
+ api.upload_folder(folder_path = folder, repo_id = repo_id)
+ print(f"Unsloth: Saved the decision model to https://huggingface.co/{repo_id}")
+
+
+# Decision models in Laya's rl_agent_config.json layout: any encoder plus a typed decision head.
+class FastDecisionModel:
+ @staticmethod
+ def from_pretrained(
+ model_name: str,
+ subfolder: Optional[str] = None,
+ max_seq_length: Optional[int] = None,
+ dtype = None,
+ load_in_4bit: bool = False,
+ load_in_8bit: bool = False,
+ full_finetuning: bool = False,
+ token: Optional[str] = None,
+ revision: Optional[str] = None,
+ local_files_only: bool = False,
+ use_gradient_checkpointing = "unsloth",
+ random_state: int = 3407,
+ **kwargs,
+ ):
+ if load_in_8bit:
+ raise NotImplementedError("Unsloth: decision models do not support load_in_8bit.")
+ from safetensors.torch import load_file
+ from transformers import AutoModel, AutoTokenizer
+
+ folder = _checkpoint_folder(model_name, subfolder, token, revision, local_files_only)
+ if load_in_4bit and not is_clef_checkpoint(folder):
+ raise NotImplementedError(
+ "Unsloth: Laya decision models train in 16-bit, so load_in_4bit is not supported."
+ )
+ if is_clef_checkpoint(folder):
+ return _load_clef(
+ folder,
+ max_seq_length,
+ dtype,
+ load_in_4bit,
+ full_finetuning,
+ token,
+ use_gradient_checkpointing,
+ kwargs,
+ )
+ config = json.loads((folder / "rl_agent_config.json").read_text(encoding = "utf-8"))
+ # The base model's training record does not describe the fine-tune.
+ config.pop("training", None)
+ tokenizer = AutoTokenizer.from_pretrained(str(folder / "tokenizer"))
+ encoder = AutoModel.from_config(
+ _encoder_config(folder / "encoder"), attn_implementation = "sdpa"
+ )
+ model = _laya().common.DecisionModel(
+ encoder, config.get("head_layers", 2), len(config.get("act_costs", {})) + 1
+ )
+ model.load_state_dict(load_file(str(folder / "model.safetensors")), strict = True)
+ # ModernBERT would otherwise torch.compile parts of the encoder.
+ model.encoder.config.reference_compile = False
+
+ positions = int(getattr(model.encoder.config, "max_position_embeddings", TRAIN_MAX_LEN))
+ wanted = max_seq_length or max(int(config.get("max_len", 512)), TRAIN_MAX_LEN)
+ config["max_len"] = min(positions, int(wanted))
+ config["head_max_len"] = min(
+ config["max_len"] // 2, max(int(config.get("head_max_len", 192)), TRAIN_HEAD_MAX_LEN)
+ )
+ model.decision_config = config
+
+ device = _device()
+ model.float()
+ if not full_finetuning:
+ dtype = dtype or (torch.float32 if device.type == "cpu" else torch.float16)
+ # Weights only: the rotary buffers stay fp32, as they are when the model is served.
+ for param in model.encoder.parameters():
+ param.requires_grad_(False)
+ param.data = param.data.to(dtype)
+ model.to(device)
+ _mark_full_finetuning(model, full_finetuning)
+ _gradient_checkpointing(model, use_gradient_checkpointing)
+
+ model._saved_temp_tokenizer = tokenizer
+ model._unsloth_encoder_config = (folder / "encoder" / "config.json").read_text(
+ encoding = "utf-8"
+ )
+ model.save_pretrained_merged = types.MethodType(save_pretrained_merged, model)
+ model.push_to_hub_merged = types.MethodType(push_to_hub_merged, model)
+ return model, tokenizer
+
+ @staticmethod
+ def get_peft_model(
+ model,
+ r = 64,
+ target_modules = "all-linear",
+ lora_alpha = 64,
+ lora_dropout = 0.0,
+ bias = "none",
+ layers_to_transform = None,
+ layers_pattern = None,
+ use_gradient_checkpointing = "unsloth",
+ random_state = 3407,
+ max_seq_length = None,
+ use_rslora = False,
+ use_dora = False,
+ modules_to_save = None,
+ init_lora_weights = True,
+ loftq_config = {},
+ **kwargs,
+ ):
+ if getattr(model, "_unsloth_full_finetuning", False):
+ print("Unsloth: Full finetuning is enabled, so .get_peft_model has no effect")
+ return model
+ if hasattr(model.encoder, "peft_config"):
+ raise RuntimeError("Unsloth: You already added LoRA adapters to your model!")
+ if getattr(model, "is_clef", False):
+ unsupported = {
+ "use_dora": use_dora,
+ "layers_to_transform": layers_to_transform,
+ "layers_pattern": layers_pattern,
+ "loftq_config": loftq_config,
+ "init_lora_weights": init_lora_weights is not True,
+ }
+ unsupported = [name for name, value in unsupported.items() if value]
+ if unsupported:
+ raise NotImplementedError(
+ f"Unsloth: Clef LoRA does not support {', '.join(unsupported)} yet."
+ )
+ return _clef_peft_model(
+ model,
+ r = r,
+ target_modules = target_modules,
+ lora_alpha = lora_alpha,
+ lora_dropout = lora_dropout,
+ bias = bias,
+ use_gradient_checkpointing = use_gradient_checkpointing,
+ random_state = random_state,
+ use_rslora = use_rslora,
+ modules_to_save = modules_to_save,
+ **kwargs,
+ )
+ from peft import LoraConfig, get_peft_model
+ from transformers import set_seed
+
+ set_seed(random_state)
+ model.encoder = get_peft_model(
+ model.encoder,
+ LoraConfig(
+ r = r,
+ target_modules = target_modules,
+ lora_alpha = lora_alpha,
+ lora_dropout = lora_dropout,
+ bias = bias,
+ layers_to_transform = layers_to_transform,
+ layers_pattern = layers_pattern,
+ use_rslora = use_rslora,
+ use_dora = use_dora,
+ modules_to_save = modules_to_save,
+ init_lora_weights = init_lora_weights,
+ loftq_config = {} if loftq_config is None else loftq_config,
+ **kwargs,
+ ),
+ )
+ _gradient_checkpointing(model, use_gradient_checkpointing)
+ return model
+
+ @staticmethod
+ def for_inference(model):
+ model.eval()
+ return model
+
+ @staticmethod
+ def for_training(model, use_gradient_checkpointing = True):
+ model.train()
+ if getattr(model, "is_clef", False):
+ return model
+ if not use_gradient_checkpointing:
+ model.encoder.gradient_checkpointing_disable()
+ elif not model.encoder.is_gradient_checkpointing:
+ _gradient_checkpointing(model, use_gradient_checkpointing)
+ return model
+
+ @staticmethod
+ def build_dataset(
+ rows,
+ tokenizer,
+ model,
+ validate: Optional[Callable[[str, dict], None]] = None,
+ ) -> tuple:
+ max_len = int(model.decision_config.get("max_len", 512))
+ head_max_len = int(model.decision_config.get("head_max_len", 192))
+ items, report, skips = [], {"total": 0, "skipped": 0, "reason": None}, {}
+
+ def skip(
+ index,
+ reason,
+ name = None,
+ ):
+ report["skipped"] += 1
+ where = f"row {index + 1}" if name is None else f'row {index + 1}: "{name}"'
+ skips.setdefault(reason, [0, f"{where} {reason}"])[0] += 1
+
+ if getattr(model, "is_clef", False):
+ items = _clef_items(rows, tokenizer, max_len, validate, report, skip)
+ rows = ()
+ else:
+ common = _laya().common
+ for index, row in enumerate(rows):
+ row = row if isinstance(row, dict) else {}
+ state = _parsed(row.get("state"))
+ questions = _parsed(row.get("questions"))
+ gold = _parsed(row["gold"] if row.get("gold") is not None else row.get("answers"))
+ if state is None or not isinstance(questions, dict) or not isinstance(gold, dict):
+ report["total"] += 1
+ skip(index, "needs state, questions and gold")
+ continue
+ for name, question in questions.items():
+ report["total"] += 1
+ if name not in gold:
+ skip(index, "has no gold", name)
+ continue
+ try:
+ if validate is not None:
+ validate(name, question)
+ internal = _internal(question)
+ target, label = _target(internal, _parsed(gold[name]))
+ ids, markers = common.build_sequence(
+ tokenizer, state, internal, max_len, head_max_len
+ )
+ except (TypeError, ValueError) as exc:
+ skip(index, str(exc), name)
+ continue
+ if len(markers) != len(target):
+ skip(index, f"options exceed the {max_len}-token context", name)
+ continue
+ items.append(
+ {
+ "input_ids": ids,
+ "markers": markers,
+ "qtype": common.QTYPES[internal["t"]],
+ "target": target,
+ "label": label,
+ "row": index,
+ }
+ )
+ if skips:
+ # The most common reason, shown with the first decision it applied to.
+ count, example = max(skips.values(), key = lambda skipped: skipped[0])
+ report["reason"] = (
+ example if count == 1 else f"{example} (and {count - 1:,} more like it)"
+ )
+ return items, report
+
+ @staticmethod
+ def split_holdout(
+ items: list,
+ seed: int = 3407,
+ fraction: float = 0.1,
+ max_items: int = HOLDOUT_MAX,
+ ):
+ # Counted in decisions: a Clef item holds every question of its row.
+ sizes = Counter()
+ for item in items:
+ sizes[item["row"]] += len(item.get("labels", (None,)))
+ target = min(max_items, int(sum(sizes.values()) * fraction))
+ rows = sorted(sizes)
+ random.Random(seed).shuffle(rows)
+ held, count = set(), 0
+ # Whole rows that still fit under the target; the last row always stays in training.
+ for row in rows[:-1]:
+ if count + sizes[row] <= target:
+ held.add(row)
+ count += sizes[row]
+ return (
+ [item for item in items if item["row"] not in held],
+ [item for item in items if item["row"] in held],
+ )
+
+ @staticmethod
+ def evaluate(
+ model,
+ tokenizer,
+ items: list,
+ batch_size = None,
+ ) -> dict:
+ logits, items = _decision_logits(model, tokenizer, items, batch_size)
+ return _metrics(logits, items, _served_temperatures(model.decision_config, logits, items))
+
+ @staticmethod
+ def calibrate(
+ model,
+ tokenizer,
+ items: list,
+ batch_size = None,
+ ) -> dict:
+ common = _laya().common
+ config = model.decision_config
+ fallback = [common.clamp_temperature(t) for t in config.get("temperature", [1.0] * 3)]
+ logits, items = _decision_logits(model, tokenizer, items, batch_size)
+ clef = getattr(model, "is_clef", False)
+ if clef:
+ return _calibrate_clef(config, logits, items)
+ everything = range(len(items))
+ temperature, fitted = _fit_temperatures(logits, items, everything, fallback)
+ # Reported numbers score each half of the rows with temperatures fitted on the other half.
+ half = {row: i % 2 for i, row in enumerate(sorted({item["row"] for item in items}))}
+ per_item = [1.0] * len(items)
+ for side in (0, 1):
+ other = [i for i in everything if half[items[i]["row"]] != side]
+ side_temperature, _ = _fit_temperatures(logits, items, other, fallback)
+ for i in everything:
+ if half[items[i]["row"]] == side:
+ per_item[i] = side_temperature[items[i]["qtype"]]
+ config["temperature"] = temperature
+ buckets = {
+ key: value
+ for key, value in (config.pop("temperature_by_options", None) or {}).items()
+ if common.QTYPES.get(key.split(":")[0]) not in fitted
+ }
+ if buckets:
+ config["temperature_by_options"] = buckets
+ return {**_metrics(logits, items, per_item), "fitted_types": sorted(fitted)}