PEFT initialises lora_B to ZERO, so an adapter that fails to load is byte-identical to a freshly built one and every assertion below would pass

Read prompts from a JSONL or plain text file.

Match ``value`` against the union allowlist case-insensitively. Returns the canonical (original-case) entry from the allowlist or ``None`` if

Inject `run` between `advise` and a non-subcommand first argument. Lets users type ``soup advise data.jsonl`` instead of the explicit ``soup

Extract (text_a, text_b) for paired ``cross_encoder`` rows. Raises: TypeError: either field present but not a string (security review M4

Point the pin DB at a tmp path and chdir so local_dir stays in cwd.

Split ``argv`` into (command, remaining_args) for the audit record. Skips the program name (argv[0]) and global options. Global options that

Capability probe: does ``model.forward`` explicitly take a KV cache? Requires BOTH ``past_key_values`` and ``use_cache`` to be declared as ex

Extract ``(audio_path, transcript)`` from an ASR row. Raises: ValueError: missing ``audio`` / ``text`` or a non-string transcript.

Stateful stub: unique instruction per call so dedup still reaches target.

A StreamingSetupMixin whose probe returns `peak`, with a close spy.

Save a tiny CPU Llama + tokenizer to ``dir_path`` for CLI smoke.

Add a repo to an existing HF Collection. Validates inputs and swallows "already exists" errors when ``ignore_duplicate`` is set (default) so

Append one audit record to ``path``. Rotates at ``cap_bytes``. Atomic-ish append: opens with ``O_APPEND | O_CREAT`` (and ``O_NOFOLLOW`` on PO

Per-token probe scores ``activations @ w``. ``threshold`` is validated here so callers cannot pass NaN; it is not applied to the projection (

Freeze every parameter EXCEPT the appended new blocks. Returns the count of trainable parameters after freezing. Intended to be called immedi

Apply long-context configuration to a model config object. Args: model_config: HF model config object (mutated in place). target_

Wrap TRL's ``DPOTrainer.dpo_loss`` so a GDPO variant is used (v0.53.2 #135). No-op when ``tcfg.gdpo_variant`` is None. Replaces the trainer's

Build a block-diagonal causal attention mask. Args: boundaries: Sorted document boundary indices in ``[0, seq_length]`` with

Build a freedesktop.org `.desktop` entry.

Wrap a DeepSpeed-MII pipeline as a minimal OpenAI-compatible FastAPI app exposing ``/v1/chat/completions`` and ``/v1/models`` (#38, v0.33.0).

Produce preference pairs from ``traces`` according to ``signal``.

Render a TrainingPlan from a soup-config-shaped dict.

Per-token loss weights for ``answer`` tokens, boosting citation spans. ``offsets`` is the per-token ``(start_char, end_char)`` mapping for the

Map a signal in ``[0, 1]`` to OK / WARN / TRAP. - signal in [0.0, _ECHO_OK_BAND=0.30): OK - signal in [_ECHO_OK_BAND, _ECHO_TRAP_BAND=0.60):

Multi-signal vote → a single drop_pct in ``[0, 1]``. Clamps each enabled, finite per-signal value to ``[0, 1]`` then returns their mean. Miss

Forget Quality ∈ ``[0, 1]`` from pre/post loss on the forget set. Higher post-unlearn loss → more forgetting. Linearly ramps from 0 (post ==

Compute per-layer Frobenius diffs for every name in both adapters. Returns ``(per_layer, only_in_a, only_in_b)``. ``per_layer`` covers the in

Return the 64-hex closure SHA over the three input hashes. Each input must be a 64-hex SHA-256 itself. The closure is ``sha256(base_model_sha

DataInf-style per-row influence score. Returns ``cos(row_grad, probe_grad) × |row_grad|``. A positive score means the row's gradient is align

Signal-to-noise ratio of a single 2-D weight matrix. Singular values above the MP threshold are "signal", the rest "noise"; ``snr = signal_su

Convert a migration result dict to soup.yaml YAML string. Strips internal keys like _warnings before serialization.

Create an SGLang Runtime for serving. Args: model_path: Path to model or LoRA adapter directory. base_model: Base model ID (requi

Class-based TF-IDF: each CLUSTER is one document. A term frequent in one cluster and rare across clusters scores high; a term frequent in EVE

Return perf flags for FlashAttention / Liger / gradient_checkpointing. - ``use_flash_attn`` and ``use_liger`` only enabled on Ampere or newer.

Return the module that owns ``.layers`` (LlamaModel / Qwen2Model). This is deliberately NOT the CausalLM wrapper. PEFT's ``LoraModel.forward``

Delete an entry. FK ``ON DELETE CASCADE`` removes child rows.

Deploy a model to Ollama via `ollama create`. Args: name: Model name for Ollama. modelfile_content: Full Modelfile content.

Return the model's architecture class name, or ``None``. Probes ``model.config.architectures[0]`` first (HF convention), then falls back to `

True when relative range of the last ``window`` losses < ``rel_tol``. Relative range = (max - min) / mean. If the window's mean is non-positive

Bytes per element. THE single dtype-size table for layer streaming — the sharder, the planner and the trainer must not each keep their own.

Effective tokens-per-second (LF metric). `unmasked_tokens` = total non-padding labels seen during training. Returns None when wall_clock <= 0

``(enabled, why_not)`` for the ``expandable_segments:True`` hint. Split out from :func:`probe_expandable_segments` because the caller used to

Compute extended statistics: length distribution, token counts, languages.

Capture residual-stream activations at ``layer`` for ``prompts``. Registers a forward hook on the resolved layer module, runs each prompt thr

Extract the teacher-facing prompt from a trace row. Handles the common trace shapes: an explicit ``prompt`` / ``input`` / ``instruction`` / `

Canonical text-extraction for dataset rows. Mirrors ``utils/_eval_text.extract_row_text`` but adds the ``instruction`` fallback used by alpac

Render a cost for display: `$0.42`, `<$0.01`, or `—`.

Render the eval-gate status row for the live training panel (#36). Returns an empty string when ``state`` is None or empty (so the row is hid

Plain-text rubric: which rule fired, evidence, what flips it. Stable text output (not Rich markup) so callers can pipe to a file or a clipboa

Model card v2 — enriched with eval scorecard, training config, lineage. This is the generator invoked by both ``soup push`` (manual upload) and

Return the bundled fixture path for a benchmark, or ``None`` if not yet bundled. TOFU ships in v0.61.0 (synthetic author profile mini-set und

SHA-256 of the config dict after canonical JSON serialisation.

Resolve the history log path, with env override + containment. Mirrors v0.36.0 ``SOUP_BATCH_CACHE_PATH`` containment: the override must sit u

Read a JSONL file and dispatch to the matching parser. Validates source name + path containment + null-byte rejection before any open. Caps t

Install a decode-time forward hook that adds ``strength * vector``. * ``residual`` (CAA / RepE) — a forward hook on the decoder layer adds the

Return True when ``fqn``'s last component names an attention projection. Defensive surface — returns False (never raises) on non-string / empty /

Return True if ``model_name`` is in the LongLoRA allowlist. The allowlist covers Llama / CodeLlama (Llama 3.x heritage), Mistral, Mixtral (v0

Return iteration ids sorted by name (timestamp-prefixed).

Read + validate a bank JSON. cwd-contained, symlink-rejected.

Load a CheckList spec from a YAML file under cwd. Uses the shared :func:`enforce_under_cwd_and_no_symlink` helper for containment, then opens

Read + validate ``<directory>/mole_manifest.json`` (serve-side). cwd-contained + symlink-rejected + size-capped (operator-supplied path).

Load + validate a TorchAO ``--quant-config`` YAML file. Enforces (per v0.53.0 docstring contract): * Shape validation via :func:`validate_qua

Load a rubric YAML file with validation.

Build a ``Trainer`` subclass with per-token weighted-CE ``compute_loss``. Cached so repeated ``raft`` runs against the same base class share one

Score one quant candidate against the baseline. Returns a :class:`MeasureResult` with classify_delta verdict. The baseline is deterministic

Run one forward+backward at the configured shape and read the real peak. This is the #349 instrument. The pre-flight's formula is fitted and, mea

Write a single BNB-4bit-quantized merged checkpoint. Unsloth ``merged_4bit`` / ``4bit_forced`` recipe — no dequant → merge → requant cycle. `

Render a compact ``k=v`` evidence string (≤4096 chars).

TIES merge: trim low magnitudes, elect majority sign, disjoint avg.

Return the set of n-grams (length-n tuples) in ``text``. Empty result when the token count is < n. Capped on ``text`` size.

Parse an evidence ``noise_floor`` block back into a ``NoiseFloor``. Returns ``None`` when the key is absent (every pre-v0.73.2 evidence file).

Install saved-tensor hooks for activation offloading; remove on exit. Args: target: 'cpu' → offload to RAM; 'disk' → offload to scratch f

Pack a loop iteration as a v0.26 Soup Can + append a Registry entry. Reads ``<base_dir>/<iteration_id>/iteration.json``, pushes a Registry en

Validate the (subject, target) pair for an edit. The subject is the prefix sentence (e.g. "Paris is the capital of France"); the target is th

Parse a GraphQL introspection ``dict`` (``__schema`` envelope OK). Treats every Query / Mutation field as a tool-calling endpoint.

Parse ``"owner/repo#42"`` into ``(owner, repo, pr_number)``. Raises ``TypeError`` for non-strings and ``ValueError`` for any string that does

Pick the fastest kernel combo given benchmarked timings. Args: candidates: List of dicts each with ``name`` and ``time_ms`` fields.

Pick the top-N rows by uncertainty. Stable on ties — earlier rows win to make the output deterministic.

Per-layer short keys that ``replace_with_bnb_linear`` actually converted. Authoritative by construction — derived from the skeleton rather than f

Read the ASR decode prefix sidecar; ``{}`` when absent/unreadable. Values are shape-validated (a shared / downloaded model directory could ca

Reload an iteration record by id.

Read a previously-written ``TrainingState`` JSON. Containment + symlink rejection BEFORE existence probe (mirrors v0.55.0 / v0.62.0 ordering

Record one reward-function call. Exception-safe by contract. Completions are normalised to strings and capped at ``_MAX_COMPLETIONS``

Replace anything resembling a token with '<redacted>'.