Parse a YAML string and return validated SoupConfig. Unlike load_config(), raises ValueError on errors instead of SystemExit, making it suita

Whether ``path`` is inside the current working directory.

Apply cwd containment + ``os.lstat + S_ISLNK`` rejection (TOCTOU defence). Shared helper for v0.53.1 export / merge / advanced-GGUF dispatch.

Create the Soup Web UI FastAPI application.

Convert any format to normalized structure for training. Returns: - SFT formats: {"messages": [{"role": ..., "content": ...}, ...]} - Vis

Case-insensitive search across name, base_model, task, notes. User query is parameterised AND ``%`` / ``_`` wildcards are escaped so

Append a (key, value, label) triple. Enforces dim + size caps.

Atomically write ``text`` to ``output_path`` under cwd containment. Pipeline: ``enforce_under_cwd_and_no_symlink`` -> ``mkstemp`` in the pare

Rewrite an HF checkpoint into per-layer safetensors shards. ``quant='nf4'`` quantises every per-layer key named in ``quant_suffixes`` (short

Create a new registry entry. Returns the new entry's id.

Get a recipe by name. Returns None if not found.

Build a leg-1 ``TaskWin``. ``won`` is the STRICT inequality tuned > base. With a ``noise_floor``, the margin must also clear what the instrument

Heuristic refusal detector with multilingual dispatch. By default scans for English refusal phrasings (v0.56.0 back-compat surface). Pass ``l

Auto-detect dataset format from first few rows.

Load raw data from a file into list of dicts.

Insert a new run and return its run_id.

Run soup CLI as a subprocess and return CompletedProcess.

Return the profile for ``name`` (case-insensitive).

Atomically create the local-RL SQLite schema. Idempotent.

Decide whether to pass ``trust_remote_code=True`` to HF loaders. Args: model_name: HF repo id or local path. requested: ``True``

Best-effort local probe of ``config.json`` for ``auto_map``. Returns: True if config has ``auto_map`` (HF custom-code marker). Fa

Set a nested parameter in a config dict using dot notation. Supports keys like: lr, lora.r, training.epochs, etc. Maps common short names to

Minimal valid streaming config; `training` overlays the training block.

Score suite ``name`` for one model, returning an absolute ``[0, 1]``. MCQ / arithmetic suites route through the (fixed) ``ForgettingDetector``

Fuse leg 1 + leg 2 into a single SHIP / DON'T-SHIP verdict. ``decide_ship`` is the SINGLE source of truth for the threshold: it recomputes ea

Turn two ``{benchmark: score}`` maps into sorted ``BenchmarkDelta``s. Only benchmarks present in BOTH maps are compared (a one-sided benchmark

Close the database connection.

Model size in billions: exact for a local checkpoint, else guessed. A LOCAL path is measured, not guessed — `soup merge` writes directories l

Create the FastAPI application with OpenAI-compatible endpoints. Args: auth_token: optional Bearer-token gate for the v0.53.7 tool

Snapshot a training environment as an immutable branch pointer. The config file is hashed (SHA-256) and the dataset file (if provided) is has

Parse + validate the raw schema value. Accepts: - ``None`` → returns None (feature off). - List of dicts ``[{pattern: str, lr: float}, ..

Resolve a reference (id, prefix, name:tag, or registry://id) to an id. Returns ``None`` on miss. Raises :class:`AmbiguousRefError` when a

Return the decoder-layer ``ModuleList`` for a supported model. Supports the Llama-family ``model.model.layers`` and the GPT-2-family ``model.

Compute uncertainty from K reward-model scores (``1 <= K <= 32``). - K=1: max-entropy distance from 0.5 (peak at 0.5 -> uncertainty 1.0) - K=

``device_map`` for ``from_pretrained``, correct under a distributed launch. ``device_map="auto"`` shards one model across every visible GPU. Unde

Load Whisper + processor, encode the dataset, build Seq2SeqTrainer.

Create a minimal SoupConfig for testing.

Resolve + validate an edit request into an :class:`EditPlan`. Validates every operator-supplied field at construction time so misconfigured e

Compose a RAFT row into ``(prompt, answer, golden_doc_id, doc_ids)``. ``row`` is a ``{query, golden_doc, distractor_docs, answer}`` mapping (the

Produce an :class:`EvalDesign` for a dataset + goal. Heuristic — no GPU. The dimensions are derived from the top TF-IDF terms over the output

Compute the manifest, sign it, and write ``.soup-signature.json``. Args: adapter_dir: cwd-contained adapter directory. backend: `

Strip ANSI + collapse whitespace. Rich splits flag names with color codes and wraps at terminal width; asserting on raw output has broken CI

Compute size / diversity / shape signals for a dataset. ``base_model_proximity`` is left ``None`` by default; the optional ``--probe`` path c

Detect a pre-quantized base model's quant format. Returns a canonical Quant Menu format string (``gptq`` / ``awq`` / ``hqq:4bit`` / ``aqlm``

Display a friendly error message for the given exception. In normal mode: 2-3 lines with error + fix suggestion. In verbose mode: full traceb

Load eval tasks from a JSONL file with schema validation. Each line must be a JSON object with at least a 'prompt' field. Optional: 'expected

Validate and topologically sort a recipe dict. Required shape:: { "nodes": [{"name": "...", "kind": "...", "config": {...}},

RAFT (Retrieval-Augmented Fine-Tuning) format — Stanford 2024. Schema: ``{"query": str, "golden_doc": str, "distractor_docs": [str, ...], "an

Return warmup steps clamped to [MIN_WARMUP, MAX_WARMUP]. Special case: ``ratio == 0`` means "no warmup" and returns 0 (the schema allows ``wa

Get a DeepSpeed config dict by name.

Load a soup.yaml file and return validated SoupConfig.

Return the bundled rows for a behavioural suite ``name``.

Resolve a transform name to a callable. Resolution order (first match wins): 1. Per-call ``extra`` map (operator-supplied for one ``run_buil

Resolve a ``kv_cache_type`` into a serve runtime plan (v0.71.14 #140). Args: kv_cache_type: one of ``q8_0`` / ``bf16`` / ``f16`` / ``fp8`

Return a subclass of ``base_cls`` overriding ``_get_train_sampler``. The override returns a :class:`MultipackBatchSampler` built from instanc

Append a thumbs-up/down record. cwd-contained, symlink-rejected.

Validate a HuggingFace repo ID (raises ``ValueError`` on bad input). Accepts ``owner/name`` or ``name``. Each component must start with an al

Write a minimal adapter dir (config + a tiny safetensors-ish blob).

Render a full HF model card (markdown) from a registry entry + joins. ``entry`` is a hydrated registry row; ``artifacts`` / ``eval_results`` /

Combine profile + task into a recommendation, optionally history-biased. Without ``history`` this is byte-identical to the v0.54.0 rubric (re

Snapshot-download ``repo_id`` from ``hub`` into ``local_dir``. Returns the absolute local path to the downloaded snapshot. Lazy-imports the a

Build the ``rope_scaling`` dict consumed by HF model configs. The YaRN tunables are emitted only when ``scaling_type='yarn'``; the Llama 3.1

Execute a validated :class:`RecipeDAG` end-to-end (v0.53.7 live). Per-node handlers dispatch on ``RecipeNode.kind`` against the closed ``NODE

SSRF-hardened endpoint validator. Returns the stripped endpoint. Mirrors ``utils/hf.resolve_endpoint`` exactly so all three hubs share the sa

Verify that the adapter's files match the recorded manifest. Args: adapter_dir: cwd-contained adapter directory. strict: when Tru

Atomically persist ``state`` to ``path`` (default: ``./.soup/loop.yaml``). Uses ``tempfile.mkstemp`` + ``os.replace`` so a SIGKILL mid-write