Estimate the judge's preference for the first slot. Returns a coefficient in ``[-1, 1]``: - 0.0 → no position bias (judge always agrees with

Freeze the bottom layers of a model. Args: model: A PyTorch model with named_parameters(). freeze_layers: Freeze the first N laye

Return the current auth token (for printing at startup).

Return a configured ``HfApi`` instance. Lazy-imports ``huggingface_hub`` so the rest of the CLI works without the optional dependency. Raises

Map a Soup config format to an Ollama template name. Returns template name (key into OLLAMA_TEMPLATES) or None if unknown.

Interleave the 3 SNAC codebooks into Orpheus token indices. ``coarse``/``medium``/``fine`` are the per-frame code sequences at the SNAC 1/2/4

KL(P || Q) over discrete distributions derived from logits. Both inputs must be the same length and contain finite floats. Returns a non-nega

Return list of runs ordered by created_at desc.

Load + validate a previously-written mix recipe. Used by ``soup data mix --apply <recipe.yaml>`` to splice the recommended mixture into a tar

Load a pre-tokenized Arrow dataset directory. Verifies cwd containment, rejects symlinks at the target path (TOCTOU — mirrors v0.33.0 #22 / v

Load a probe JSONL file with one ``{prompt: str}`` row per line. Cwd-contained + symlink-rejected + size-capped. Skips malformed rows silentl

Load a recipe YAML from a path under cwd.

Load a safetensors SAE checkpoint with cwd-containment + symlink reject. Returns a dict with at least ``W_enc`` (encoder matrix). Other keys

Load and validate an eval suite from disk.

RLVR math reward: compare extracted numeric answer to expected. Security: never uses ``eval()``. Only numeric literals that match a strict re

Compare measured bandwidth against the reference table. Returns a dict with `expected`, `measured`, `ratio`, and `status`. - status="OK"

Run the eval gate, if configured.

Pack a registry entry as a ``.can`` tarball. Args: entry_id: registry entry id (full id or prefix). out_path: destination ``.can`

Return 0 (A preferred), 1 (B preferred), or -1 (tie / disagreement). When ``swap`` is True the pair is judged in BOTH orders (A,B and B,A) and a

Parse a dict (from YAML) into a frozen ``CheckListSpec``.

Validate and normalise a sequence of curriculum-history rows. Used by ``soup runs curriculum-curve <run_id>`` to load the JSONL written by th

Parse a JSON array from LLM output, handling markdown code blocks. Handles: - Clean JSON arrays - Markdown code fences (```json ... ```)

Linear-interpolated percentile. `pct` is in [0, 100]. Returns None on empty input. Rejects non-finite samples and bool.

Pull the latest checkpoint branch from HF into ``output_dir``. Returns the local path of the checkpoint directory, or None if there's nothing

Drop parameter groups that hold no parameters. Returns how many went. HF's ``create_optimizer`` always emits two groups — decay and no-decay.

Drop decoder layers ``[start, start + block_size)`` in place. Slices ``model.model.layers`` and patches ``config.num_hidden_layers``. The fir

Probe ``config.json`` for the expert count (None when absent). Checks ``text_config.num_local_experts`` (HF Llama4TextConfig), then top-level

Refuse layer streaming when HF Trainer would wrap the model in DataParallel. ``TrainingArguments`` sets ``_n_gpu = torch.cuda.device_count()`` fo

Register a plugin. Idempotent for an identical spec; rejects re-registration with a different version or plugin object.

Render a custom Space template directory. Returns a dict mapping in-repo filename → rendered content. ``{MODEL_REPO}`` placeholder is replace

Render a reproducible install plan from a lock (v0.71.1 #209). Two formats: - ``"uv-pip"`` — a commented header (python / platform / CUDA) f

Render an applied-mixture recipe snippet for human review. Produces a YAML fragment suitable for splicing into ``soup.yaml`` under ``data:``.

Rich ``Panel`` for the terminal — a one-screen verdict card.

Resolve a gradient_checkpointing setting into TrainingArguments kwargs. Only returns keys that HuggingFace's ``TrainingArguments`` actually accep

Pick the cluster count. An explicit int is honoured (clamped to ``[1, n_rows]``). ``"auto"`` uses the standard sqrt heuristic, capped at :dat

How many replay rows to add so replay is ``ratio`` of the FINAL set. Solving ``n_replay / (n_new + n_replay) = r`` gives ``n_replay = r/(1-r)

Return realpath of `<cwd>/<base_dir>/<run_id>.snapshot.pickle`. Rejects values that escape cwd. Mirrors v0.34.0 `resolve_trace_path`.

Compute the full Chrome trace path under ``output_dir/profiles``. Validation of ``run_id`` rejects path separators, null bytes, and bare pare

Rotate ``<path>`` -> ``<path>.1`` when file size exceeds ``cap_bytes``. Symlink at the backup path is rejected via direct ``os.lstat`` (no lexist

Find the first failing checkpoint via binary search. ``eval_fn(checkpoint_id)`` MUST return ``True`` when the checkpoint passes (no regressio

Chain the two RA-DIT stages: retriever → auto-link → generator. Args: retriever_config: Path (under cwd) to the stage-1 embedding recipe.

Write a checkpoint for ``step``; returns the directory path. Pure of HF Trainer state — exercised directly by tests with a tiny peft

Persist a governor's state to ``store``.

Score memorization on a sample of training rows. Each row must contain a ``text`` (or ``content`` / ``prompt``) string field. Rows lacking te

Score 1.0 - mean pairwise overlap across K completions per prompt.

Select the active user for the decode hook. Returns ``True`` if known. The selection is request-local (stored in a ``ContextVar``) so a

Sign ``payload`` with an ed25519 private key; return a hex signature.

Smooth a scalar signal. ``none`` → new; ``ema`` → windowed EMA (alpha = ``_EMA_ALPHA`` = 0.5) folded over the RETAINED window (oldest→newest) then

Capture the current Python/CUDA/package versions as an ``EnvLock``.

Split a completion into reasoning steps (newline heuristic, v1). Drops empty / whitespace-only lines, strips each line, truncates each step t

Return the absolute trigger-file path for `output_dir`. Path containment: the resolved trigger path must stay under cwd to prevent a crafted

Raise if the Anthropic payload is malformed.

Normalise + validate a benchmark name (case-insensitive).

Validate a capability-benchmark name. Returns canonical form.

Return canonical lowercase strategy name.

Cross-validator for the distributed footgun. v0.53.5 #114: :class:`monitoring.curriculum_callback.DynamicCurriculumCallback` wires the ``all_

Validate FSDP2 + ``torch.compile`` combination. Args: use_compile: Whether ``training.use_fsdp2_compile`` is enabled. fsdp_preset

Sanity-check the ``--license-override <reason>`` payload. Defends against `--license-override y` style placeholder bypasses: the reason must

Return ``value`` when an in-bounds positive int. Rejects bool / non-int / <=0 / > ``MAX_COMPILE_ITERS``.

Schema-time gate for ``nvfp4=True``. NVFP4 is Blackwell-only and CUDA-only; the *runtime* SM-capability check fires at trainer-construction t

Schema-load-time validator for ``training.optimizer``. Returns the normalised name (lower-cased) on success, raises ValueError with an action

Validate the pretrain-anchor loss coefficient. Range [0.0, 1.0]. 0.0 = no anchor; small positive (e.g. 0.1) adds the SFT-on-pretrain term as

Validate the ``rounds`` count: int in [1, 100], bool rejected.

Bool-rejecting + bounded validator for save_every_steps. Range: ``[1, _MAX_SAVE_EVERY_STEPS=10_000_000]``.

Validate an OpenAPI / MCP / GraphQL spec path (json / yaml / yml only).

Validate and lowercase a `report_to` tracker name. Returns the canonical lower-cased name. Raises ValueError on invalid input. Mirrors v0.41.

Schema-time gate for ``task='unlearn'``. Rejects: - non-string / bool args (defence-in-depth, mirrors v0.52.0 ``validate_classifier_com

Atomically write the rendered recipe to ``output_path``. Containment + TOCTOU symlink rejection mirrors v0.46.0 Part A ``write_recipe`` and v

Write `<cwd>/<target_dir>/launch.json`. Returns the absolute path written. Raises ValueError on containment violation. Raises FileExistsE

Resolve the OnlineDPO reward signal: judge OR reward_model. Precedence: the test seam, then the judge URL, then a reward model. The s

Build generation prompt from a domain template.

ANSI-strip + collapse whitespace. Rich colourises flag names (``--card`` -> ESC-split fragments) and wraps at the CI terminal's narrow width,

Collect prompts from file and/or CLI arguments.

Compute comparison metrics between two responses.

Build exposures landing on EXACT percentiles via 100 controls.

Build a tiny Llama-shaped nn.Module with mlp.down_proj per layer.

Drive one ``on_save`` the way HF's CallbackHandler does. ``args`` / ``state`` are the two attributes the callback reads, so a SimpleNamespace

Generate parameter combinations based on strategy.

Generate a response from the model.

Return True for a GPT-2 ``Conv1D`` down-projection. transformers' ``Conv1D`` stores a transposed weight (``[in, out]`` rather than nn.Linear'

Load calibration texts from JSONL file.

Load a smaller draft model for speculative decoding.

Load an evidence JSON (cwd-contained, symlink-rejected, size-capped). Opens with ``O_NOFOLLOW`` (where available) and fstats the open fd so a

Create a mock model with named_parameters.

Create mock model and tokenizer for testing _generate.

Re-run the BASE model ``runs`` times and return the measured spread. Greedy decoding is not deterministic on GPU: measured on an H100, the same

Return ((floor_major, floor_minor), (ceiling_major, ceiling_minor)).