Raise ``ValueError`` if ``arch_name`` is not multipack-supported. Loud-fail policy (vs Axolotl's silent miss) — see module docstring.

Return the canonical lowercase optimizer name. Rejects bool / non-string / empty / null-byte / >32-char / unknown. Mirrors v0.41.0 ``validate

Validate the operator-supplied retriever-model HF repo id or local path. Bool / non-string rejected. ``None`` passes through unchanged so cal

Validate a profile name. Returns canonical form.

Raise ValueError if ``tag`` is invalid.

Validate the teacher-mix sampling ratio. Range [0.0, 1.0]. 0.0 = student-only rollouts; 1.0 = teacher-only rollouts. Typical MiniLLM recipes

Validate a TTS family name and return the canonical (lowercase) form.

Project a verdict into the ``--evidence`` INPUT schema (the inverse read). ``commands/ship.py`` reads pre-computed evidence as ``{"task": {"m

Run the daemon loop. Returns ``(final_state, iterations_run)``. Stops cleanly on: - ``config.max_iterations`` reached (test/finite mode)

Atomically write an ``EnvLock`` to JSON under cwd containment.

Write the rendered hook to ``hook_path`` with cwd + TOCTOU guards. Returns the path written. Refuses to overwrite an existing file unless ``o

Construct a minimal valid .can tarball at ``out_path``.

Build the prompt for data generation.

Capture residual-stream activations from the trained model (v0.71.8 #219). Loads the trained model at ``output_dir`` (or ``base`` + adapter when

Generate a response from the model. Returns (text, token_count).

Generate a batch of examples using the specified provider.

Return a stand-in for live_eval.make_generator. Branches base vs tuned on the adapter (or a "tuned" model id). Each side answers task prompts

Create a JSONL file with count rows, optional category field.

Write a temporary Python module and return its importable name. Registers the module in ``sys.modules`` so ``importlib.import_module`` can fi

Read JSONL ``{"text": "..."}`` rows and write a plain-text file. llama.cpp ``imatrix`` accepts a raw text file (one paragraph per line is fin

6 respondents r0..r5 (latent ability ascending) x several items. - ``const`` : everyone correct (carries ~no information). - ``split`` : co

Compute uncertainty for a single row. Priority: explicit ``uncertainty`` field > ``rm_scores`` list > ``rm_score`` scalar > 0.0.

Load model via standard transformers + peft pipeline.

Aggregate accepted-verdict outcomes per choice from prior history. Duck-typed (reads ``.choice`` / ``.accepted`` / ``.outcome`` / ``.project``

Validate and resolve image paths in vision dataset rows. Each row must have an 'image' key with a filename or path. Resolves relative paths a

Check if installed version meets minimum requirement.

Write a stub Llama-4-shaped checkpoint; return the tensor dict.

Return per-token defection scores: ``activations @ probe_w``. Threshold is validated here so callers don't accidentally pass NaN.

Advance the bang-bang controller one step given the multi-signal ``vote``. ``vote`` is the combined hacking signal in ``[0, 1]`` (see :func:`

Build a :class:`DiffReport`. When ``before_model`` AND ``after_model`` (model paths or HF ids) are both supplied alongside probes, the report

Build the live MiniLLM callback / loss helper (v0.71.11 #237). Lifts the v0.70.0 ``NotImplementedError`` stub. Validates the config type at t

Validate args and produce a frozen plan.

Map ``model.named_parameters()`` onto optimizer param groups. Each parameter is assigned to the *first* matching ``lr_groups`` entry (search

Compose a FailureReport, filling missing modes with neutral stubs.

Build a reproducibility receipt from seeds + run_id + autodetected env. ``ReproReceipt.__post_init__`` performs the canonical seeds validation;

Assemble the coverage table + gap warnings from cluster labels.

Map a relative drop in cluster-separation to OK / WARN / HACK. ``drop_pct`` is the *relative* drop: ``(baseline_signal - current_signal) / ba

Classify a Frobenius norm delta as OK / WARN / BLOWUP. Bool-rejected, NaN/Inf-rejected, negative-rejected. Matches project bool-before-numeri

End-to-end: load both adapters, compute layer diffs, rank top-K.

Walk ``adapter_dir`` and return a deterministic manifest. Containment + symlink rejection on the adapter dir (TOCTOU defence, mirrors v0.53.1

InfoRM-style cluster-separation index. Returns ``(mean_good - mean_bad) / sqrt(var_good + var_bad + eps)``. Larger = better-separated reward

Deterministic 64-hex SHA-256 over a lock's *content* (v0.71.1 #224). Excludes ``created_at`` (and the on-disk ``schema_version``) so that re-

Geometric (log-linear) LR sweep from ``start_lr`` to ``end_lr``.

Copy bundle's JSONL into `output_path`. Containment-checked. Returns the absolute path written. Refuses to overwrite existing files (caller m

Compare predicted demand against measured free VRAM. Refusing rather than warning is deliberate. On Linux an over-budget step is a hard OOM.

Probe `model_path` and return a preferred backend identifier. Resolution order: 1. Env hint `SOUP_BENCH_BACKEND` (validated against allowli

Token-level analogue of :func:`detect_common_prefix` (v0.71.5 #205). Returns the longest token-id prefix shared by >= ``min_frequency`` of ro

Enumerate document files under ``docs_dir`` (one level deep). Skips dotfiles, rejects symlinked directories, restricts to known text extensio

Shannon entropy of normalised singular-value distribution (effective rank). Returns ``exp(H)`` where H is the entropy of the SV distribution

Static analytical VRAM predictor. Returns a per-class breakdown.

Predicted ``torch.cuda.max_memory_allocated()`` for a streaming step. Assembles the GATE 2 terms. Validated against 10 real runs across two model

Build GaLore optimizer kwargs for HuggingFace Trainer. Returns dict of kwargs to pass to TrainingArguments. GaLore applies low-rank gradient

Get LoRA target modules for MoE models (ScatterMoE LoRA). Returns a list of module name patterns that includes both attention layers and expe

Return True if ``model_name`` starts with a known-safe org prefix.

Every registered draft, newest first.

Load eval-suite examples (cwd-contained, symlink-safe, O_NOFOLLOW). Accepts a JSON array of objects, a single JSON object, or a JSONL file (o

Load operator-supplied evidence JSON. Containment + size cap + symlink rejection. Mirrors v0.56.0 ``commands/diagnose.py`` evidence loader.

Reconstruct an :class:`EditGovernor` for ``base_model`` from ``store``. Returns a fresh governor (edit_count=0) when no prior state exists. When

Read a JSONL file under cwd; skip malformed lines silently.

Read a canary manifest written by :func:`write_manifest`.

Load one OR MORE reward functions from a comma-separated spec (v0.71.40 #311). ``reward_fn`` may name several rewards, e.g. ``"accuracy,format"``

Locally-trained draft for ``target``, or None. An entry whose directory no longer exists (the user moved or deleted the draft) is skipped — a

v0.53.11 #123 — build a ``_GRPOTrainerVariant`` subclass. Returns a subclass of ``trl.GRPOTrainer`` whose ``compute_loss`` routes through :fu

True on-policy MiniLLM teacher-mixed rollout (v0.71.18 #257). Unlike :func:`minillm_distill_term` (which blends the teacher distribution into

Fallback probe — when no buffer is wired, use logged reward stats. info_rm only (rm_ensemble needs per-function rewards). Reads ``rew

Parse ``"50usd"`` / ``"100 USD"`` / ``"25"`` into a USD float. Trailing ``"usd"`` (case-insensitive) is optional. Bounds: ``[0, 1_000_000]``

Parse an MCP server manifest's ``tools`` array.

Top-level batch picker. Honours strategy + cache + probe. Returns: Picked batch size (always >= 1). Falls back to ``static_estimate``

Try-halve-then-double loop. Returns the largest batch that ran OK. Strategy: 1. Try ``start``. If OOM, halve until either it fits or hits ``

Read ``base_model_name_or_path`` from an adapter's ``adapter_config.json``. Returns ``None`` when the config is absent or the field is missing. T

Read a previously-written ``EnvLock`` JSON. Containment + symlink rejection BEFORE existence probe so a crafted path cannot distinguish "outs

Register a model with the base rating.

Register a tab. Idempotent for identical (title, render); rejects re-registration with a different title or render fn.

Resolve a baseline specifier to a ``{task_name: score}`` map. - ``None`` / ``""``: return empty map - ``registry://<id>``: look up eval_resul

Resolve --gpus flag into concrete int. Accepts: - None: returns None (user did not pass --gpus) - int: returns the int -

Resolve a profile name to the ordered tuple of CapabilityBenchmark.