soup-cli 0.71.22__tar.gz → 0.71.23__tar.gz

{soup_cli-0.71.22 → soup_cli-0.71.23}/.gitignore

@@ -41,22 +41,7 @@ report.xml
 *.key
 
 # Internal plan + Claude Code local dev instructions (not for repo)
-.claude/plan.md
-.claude/CLAUDE.md
-.claude/settings.json
-.claude/scheduled_tasks.lock
-.claude/*.lock
-.claude/settings.local.json
-
-# ECC plugin (local only)
-.claude/agents/
-.claude/commands/
-.claude/examples/
-.claude/hooks/
-.claude/mcp-configs/
-.claude/rules/
-.claude/skills/
-.claude/settings.json
+.claude/
 .coverage
 
 # Local scratch / temp scripts at repo root (e.g. _smoke.py, _scratch.py) — never committed

{soup_cli-0.71.22 → soup_cli-0.71.23}/CHANGELOG.md

@@ -12,6 +12,39 @@ reproducing 70+ versions of notes.
 
 ## [Unreleased]
 
+## [0.71.23] - 2026-06-12
+
+### Added
+- **Native Spectrum targeted training (closes #266).** A new `soup spectrum
+  scan` reads a model's `.safetensors` shards **one tensor at a time** (no
+  model load — peak RAM is the largest single weight matrix), computes a
+  singular-value SNR per weight matrix with a Marchenko-Pastur noise threshold
+  (arXiv:2406.06623), ranks layers within each module-type group and prints
+  the top `--top-percent` as a ready-to-paste `training.unfrozen_parameters`
+  YAML block. This lets you scan even a very large model's layer SNR on a CPU
+  box and then full-fine-tune only the high-signal layers.
+  - `soup spectrum scan --model <id|path> --top-percent 50 [--modules mlp,attn|all] [--output patch.yaml]`
+    — SNR table + the YAML patch; results cache at `~/.soup/spectrum/<slug>.json`
+    (override via `SOUP_SPECTRUM_CACHE_DIR`).
+  - New schema field `training.unfrozen_parameters: list[str]` — regex patterns
+    of parameter names to keep trainable; the SFT trainer freezes every
+    parameter then unfreezes the matched set (full fine-tuning, LoRA off).
+    Mutually exclusive with LoRA features / `freeze_layers` / `freeze_ratio` /
+    `train_router_only` / `expand_layers`; requires `task=sft`,
+    `backend=transformers`, `modality=text`, and `quantization=none`.
+  - The SNR kernel is pure-numpy and transpose-invariant (singular values are
+    identical for `W` and `W.T`); GPT-2 `Conv1D` naming
+    (`c_attn`/`c_fc`/`c_proj`) is recognised alongside Llama-style names.
+  - The existing `spectrum` trainer-plugin wrapper is untouched (back-compat).
+    LISA (per-step layer sampling) is tracked separately in #267.
+
+### Security
+- `soup spectrum scan` validates `unfrozen_parameters` patterns at parse time:
+  rejects nested-unbounded-quantifier regexes (ReDoS), null bytes, empties, and
+  caps count (50k) and length (512). Hub downloads route through the
+  SSRF-hardened, namespace-pinned `hubs.snapshot_download`; symlinked shards and
+  matrices above a 2^31-element SVD cap are skipped; `--output` stays under cwd.
+
 ## [0.71.22] - 2026-06-10
 
 ### Added

{soup_cli-0.71.22 → soup_cli-0.71.23}/CONTRIBUTING.md

@@ -120,7 +120,7 @@ src/soup_cli/
   templates/          - 17 built-in soup.yaml templates (YAML + manifest.json) with load_template loader (v0.39.0, +bco v0.40.0)
   ui/                 - Web UI (FastAPI + HTML/JS SPA)
 
-tests/                - Test suite (293 files, 14184 tests)
+tests/                - Test suite (294 files, 14278 tests)
 examples/             - Real-world config examples and datasets
 ```
 

{soup_cli-0.71.22 → soup_cli-0.71.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soup-cli
-Version: 0.71.22
+Version: 0.71.23
 Summary: Fine-tune and post-train LLMs in one command. No SSH, no config hell.
 Project-URL: Homepage, https://github.com/MakazhanAlpamys/Soup
 Project-URL: Repository, https://github.com/MakazhanAlpamys/Soup
@@ -189,22 +189,19 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.22 — Perf & measure polish.** Four live paths from the recent BETA lifts get tighter:
-
-- **MiniLLM on-policy distillation is fast** — the on-policy rollout
-  (`training.minillm_on_policy: true`) now threads a KV cache so each step forwards only the new
-  token instead of re-feeding the whole prefix, resolving the earlier O(L²) cost. A LoRA student
-  activates the cache too (the PEFT wrapper is unwrapped before the cache check).
-- **`soup serve --mole` uses a KV cache** — each task adapter in a served MoLE keeps its own cache
-  in lockstep, created fresh per request (no cross-request leak). Output is byte-identical to the
-  previous no-cache path.
-- **`soup deploy autopilot --measure` is real and frugal** — a first-party transformers loader
-  factory loads each candidate live (per-candidate quant config), scores the baseline **once**, and
-  pre-validates the whole `--measure-candidates` list up front, so a typo fails before any model
-  load instead of burning N loads or doubling peak VRAM.
-- **Live-codec TTS via SNAC (Orpheus)** — encoding raw audio at train time (`data.format: audio`)
-  is validated for Orpheus: audio is duration- and byte-capped from `soundfile.info` **before**
-  decoding into RAM, and read through a symlink-safe file descriptor.
+**v0.71.23 — Native Spectrum targeted training.** Fine-tune only the layers that matter — no 8×H100 needed to find them:
+
+- **`soup spectrum scan --model <id|path> --top-percent 50`** — streams a model's weights one
+  tensor at a time (no model load, runs on a CPU box even for very large models) and computes a
+  singular-value signal-to-noise ratio per weight matrix (Marchenko-Pastur, arXiv:2406.06623).
+- **Ready-to-paste patch** — prints a per-group SNR table and a `training.unfrozen_parameters`
+  YAML block; pipe it straight into your `soup.yaml`. Results cache under `~/.soup/spectrum/`.
+- **Targeted full fine-tuning** — with `training.unfrozen_parameters` set, `soup train` freezes
+  every parameter and unfreezes only the matched high-SNR layers (full FT, LoRA off) — train
+  fewer parameters, keep more of the base model intact.
+- **Honest guards** — the scan is pure-numpy and transpose-invariant; patterns are ReDoS-checked,
+  Hub downloads go through the SSRF-hardened loader, and the config gates `quantization: none` +
+  `task: sft` so a mis-set flag fails loudly, not silently.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.22 → soup_cli-0.71.23}/README.md

@@ -49,22 +49,19 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.22 — Perf & measure polish.** Four live paths from the recent BETA lifts get tighter:
-
-- **MiniLLM on-policy distillation is fast** — the on-policy rollout
-  (`training.minillm_on_policy: true`) now threads a KV cache so each step forwards only the new
-  token instead of re-feeding the whole prefix, resolving the earlier O(L²) cost. A LoRA student
-  activates the cache too (the PEFT wrapper is unwrapped before the cache check).
-- **`soup serve --mole` uses a KV cache** — each task adapter in a served MoLE keeps its own cache
-  in lockstep, created fresh per request (no cross-request leak). Output is byte-identical to the
-  previous no-cache path.
-- **`soup deploy autopilot --measure` is real and frugal** — a first-party transformers loader
-  factory loads each candidate live (per-candidate quant config), scores the baseline **once**, and
-  pre-validates the whole `--measure-candidates` list up front, so a typo fails before any model
-  load instead of burning N loads or doubling peak VRAM.
-- **Live-codec TTS via SNAC (Orpheus)** — encoding raw audio at train time (`data.format: audio`)
-  is validated for Orpheus: audio is duration- and byte-capped from `soundfile.info` **before**
-  decoding into RAM, and read through a symlink-safe file descriptor.
+**v0.71.23 — Native Spectrum targeted training.** Fine-tune only the layers that matter — no 8×H100 needed to find them:
+
+- **`soup spectrum scan --model <id|path> --top-percent 50`** — streams a model's weights one
+  tensor at a time (no model load, runs on a CPU box even for very large models) and computes a
+  singular-value signal-to-noise ratio per weight matrix (Marchenko-Pastur, arXiv:2406.06623).
+- **Ready-to-paste patch** — prints a per-group SNR table and a `training.unfrozen_parameters`
+  YAML block; pipe it straight into your `soup.yaml`. Results cache under `~/.soup/spectrum/`.
+- **Targeted full fine-tuning** — with `training.unfrozen_parameters` set, `soup train` freezes
+  every parameter and unfreezes only the matched high-SNR layers (full FT, LoRA off) — train
+  fewer parameters, keep more of the base model intact.
+- **Honest guards** — the scan is pure-numpy and transpose-invariant; patterns are ReDoS-checked,
+  Hub downloads go through the SSRF-hardened loader, and the config gates `quantization: none` +
+  `task: sft` so a mis-set flag fails loudly, not silently.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.22 → soup_cli-0.71.23}/docs/commands.md

@@ -25,6 +25,7 @@ soup push --model ./output --repo user/name --collection user/coll-abc123  Add t
 soup merge --adapter ./output                 Merge LoRA with base model
 soup merge-sharded-fsdp-weights ./shards -o merged.safetensors  Consolidate FSDP shards into one safetensors (v0.71.14; --plan-only previews)
 soup delinearize-llama4 ./src --target ./out [--num-experts N] [--plan-only]  Live Llama-4 fused-expert reshape [E*din,dout] -> [E,din,dout] + sidecar copy (v0.71.21)
+soup spectrum scan --model <id|path> --top-percent 50 [--modules mlp,attn] [-o patch.yaml]  Spectrum SNR scan (no model load) -> training.unfrozen_parameters YAML patch (v0.71.23)
 soup export --model ./output --format gguf    Export to GGUF (Ollama)
 soup export --model ./output --deploy ollama  Export GGUF + auto-deploy to Ollama
 soup export --model ./output --format onnx    Export to ONNX

{soup_cli-0.71.22 → soup_cli-0.71.23}/docs/training.md

@@ -1026,10 +1026,13 @@ prepends the family's emotion control string to the first user turn.
 **Live-codec (hardware/dependency-gated).** Setting `data.format: audio` asks
 the trainer to encode raw audio into codec tokens **at train time**, which needs
 the family's heavyweight codec package (`snac` for Orpheus, `moshi` for
-Sesame-CSM, `xcodec2` for Llasa, `sparktts` for Spark, `outetts` for Oute). This
-path surfaces a friendly per-family `RuntimeError` naming the required `pip
-install` and is not validated on the maintainer's box — use the pre-encoded
-workflow above for a runnable fine-tune.
+Sesame-CSM, `xcodec2` for Llasa, `sparktts` for Spark, `outetts` for Oute). The
+**Orpheus** path is live — install `pip install snac` and a 24 kHz mono wav is
+encoded to SNAC codec tokens end-to-end (audio is duration- and byte-capped and
+read through an `O_NOFOLLOW` fd). The other four families still surface a
+friendly per-family `RuntimeError` naming the required `pip install` and are not
+yet validated on the maintainer's box — use the pre-encoded workflow above for a
+runnable fine-tune with those.
 
 Five ready-made recipes ship: `orpheus-tts-sft`, `sesame-csm-tts`, `llasa-tts`,
 `spark-tts`, `oute-tts` — copy with `soup recipes use <name>`. Cross-validators
@@ -1142,3 +1145,48 @@ rejected at the schema gate for non-supported arches and for `use_ring_attention
 Pick one of MoD / LLaMA Pro / LongLoRA per run. (v0.71.12)
 
 
+## Spectrum — Targeted Training on Layer SNR (`soup spectrum scan`, v0.71.23)
+
+Spectrum (arXiv:2406.06623) fine-tunes only the layers with the most signal. `soup spectrum scan`
+streams a model's `.safetensors` shards **one tensor at a time** — there is no model load, so it
+runs on a CPU box even for very large models — and computes a singular-value signal-to-noise ratio
+per weight matrix with a Marchenko-Pastur noise threshold. It ranks the layers within each
+module-type group and prints the top `--top-percent` as a ready-to-paste config block:
+
+```bash
+soup spectrum scan --model HuggingFaceTB/SmolLM2-135M --top-percent 25 --modules mlp,attn -o patch.yaml
+```
+
+```yaml
+# patch.yaml — paste into your soup.yaml
+training:
+  unfrozen_parameters:
+  - model.layers.0.mlp.down_proj
+  - model.layers.29.self_attn.v_proj
+  # ...
+```
+
+Then train with the patch — the SFT trainer freezes **every** parameter and unfreezes only the
+matched set (full fine-tuning, LoRA off):
+
+```yaml
+base: HuggingFaceTB/SmolLM2-135M
+task: sft
+training:
+  quantization: none        # Spectrum trains float weights — quantization off
+  unfrozen_parameters:
+  - model.layers.0.mlp.down_proj
+  - model.layers.29.self_attn.v_proj
+```
+
+`unfrozen_parameters` entries are regex patterns matched against parameter names. It requires
+`task: sft`, `backend: transformers`, `modality: text`, and `quantization: none`, and is mutually
+exclusive with LoRA features (`use_dora` / `use_vera` / `moe_lora` / `relora_steps` / …) and the
+other freezing knobs (`freeze_layers` / `freeze_ratio` / `train_router_only` / `expand_layers`) —
+a conflicting combo is rejected loudly at config load. Scans cache under `~/.soup/spectrum/`
+(override with `SOUP_SPECTRUM_CACHE_DIR`); `--no-cache` skips it. `--modules mlp,attn` (vs the
+`all` default) is recommended for very large models — it skips the giant embedding/lm_head matrices.
+The SNR kernel is pure-numpy and transpose-invariant, so GPT-2 `Conv1D` weights score the same as
+Linear weights. (v0.71.23)
+
+

{soup_cli-0.71.22 → soup_cli-0.71.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "soup-cli"
-version = "0.71.22"
+version = "0.71.23"
 description = "Fine-tune and post-train LLMs in one command. No SSH, no config hell."
 readme = "README.md"
 license = "Apache-2.0"

{soup_cli-0.71.22 → soup_cli-0.71.23}/src/soup_cli/__init__.py

@@ -1,3 +1,3 @@
 """Soup CLI — Fine-tune and post-train LLMs in one command."""
 
-__version__ = "0.71.22"
+__version__ = "0.71.23"

{soup_cli-0.71.22 → soup_cli-0.71.23}/src/soup_cli/cli.py

@@ -58,6 +58,7 @@ from soup_cli.commands import (  # noqa: E402
 from soup_cli.commands import monitor as monitor_cmd  # noqa: E402
 from soup_cli.commands import quantize as quantize_cmd  # noqa: E402
 from soup_cli.commands import quickstart as quickstart_cmd  # noqa: E402
+from soup_cli.commands import spectrum as spectrum_cmd  # noqa: E402
 from soup_cli.commands import (  # noqa: E402
     tui as tui_cmd,
 )
@@ -136,6 +137,10 @@ app.add_typer(
 app.command(name="history")(history.history)
 app.command(name="why")(why_cmd.why)
 app.command(name="tui")(tui_cmd.tui)
+app.add_typer(
+    spectrum_cmd.app, name="spectrum",
+    help="Spectrum SNR scan for targeted training (v0.71.23).",
+)
 app.add_typer(
     can.app, name="can",
     help="Soup Cans: pack/inspect/verify/fork shareable .can artifacts.",

soup_cli-0.71.23/src/soup_cli/commands/spectrum.py

@@ -0,0 +1,174 @@
+"""soup spectrum — native Spectrum targeted-training scan (#266, v0.71.23).
+
+``soup spectrum scan`` streams a model's ``.safetensors`` shards (NO model
+load), computes a singular-value SNR per weight matrix (arXiv:2406.06623),
+ranks layers within each module-type group and prints the top ``--top-percent``
+as a ready-to-paste ``training.unfrozen_parameters`` YAML block. Paste it into
+a ``soup.yaml`` to fine-tune only the high-SNR layers (full FT, LoRA off).
+
+The scan is pure-numpy and runs on a CPU box even for very large models —
+peak RSS is the largest single weight matrix, not the whole model.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Optional
+
+import typer
+from rich.console import Console
+from rich.markup import escape
+from rich.panel import Panel
+from rich.table import Table
+
+if TYPE_CHECKING:  # static types only — the import is numpy-lazy at runtime
+    from soup_cli.utils.spectrum_scan import LayerSNR, ScanResult
+
+console = Console()
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Spectrum SNR scan for targeted training (v0.71.23).",
+)
+
+
+@app.callback()
+def _spectrum() -> None:
+    """Spectrum SNR scan for targeted training (v0.71.23).
+
+    An explicit callback keeps this a command group (Typer otherwise collapses
+    a single-command app and drops the ``scan`` subcommand name).
+    """
+
+
+def _render_table(
+    result: "ScanResult", kept: list[str], top_percent: float
+) -> None:
+    # Group by the same key as select_unfrozen_parameters (the layer-type
+    # signature), so the "Kept" column can never desync from the selection.
+    from soup_cli.utils.spectrum_scan import param_prefix
+
+    kept_set = set(kept)
+    groups: dict[str, list["LayerSNR"]] = defaultdict(list)
+    for layer in result.layers:
+        groups[layer.group].append(layer)
+
+    table = Table(
+        title=f"Spectrum SNR — {escape(result.model)} "
+        f"(top {top_percent:g}% per group)"
+    )
+    table.add_column("Type")
+    table.add_column("Group")
+    table.add_column("Layers", justify="right")
+    table.add_column("Kept", justify="right")
+    table.add_column("SNR min / mean / max", justify="right")
+
+    for group in sorted(groups):
+        items = groups[group]
+        snrs = [layer.snr for layer in items]
+        n_kept = sum(1 for layer in items if param_prefix(layer.name) in kept_set)
+        table.add_row(
+            items[0].module_type,
+            escape(group),
+            str(len(items)),
+            str(n_kept),
+            f"{min(snrs):.3f} / {sum(snrs) / len(snrs):.3f} / {max(snrs):.3f}",
+        )
+    console.print(table)
+
+
+@app.command()
+def scan(
+    model: str = typer.Option(
+        ..., "--model", "-m", help="HF Hub id or local model directory."
+    ),
+    top_percent: float = typer.Option(
+        50.0,
+        "--top-percent",
+        help="Keep the top N% of layers (by SNR) within each module type.",
+    ),
+    modules: str = typer.Option(
+        "all",
+        "--modules",
+        help="Comma list of module types to scan: e.g. 'mlp,attn' — or 'all'.",
+    ),
+    output: Optional[str] = typer.Option(
+        None,
+        "--output",
+        "-o",
+        help="Write the YAML patch to this path (must stay under cwd).",
+    ),
+    no_cache: bool = typer.Option(
+        False, "--no-cache", help="Skip the ~/.soup/spectrum scan cache."
+    ),
+) -> None:
+    """Scan a model's layer SNR and emit a ``training.unfrozen_parameters`` patch."""
+    import yaml
+
+    from soup_cli.utils.spectrum_scan import scan_model, select_unfrozen_parameters
+
+    if not (0 < top_percent <= 100):
+        console.print("[red]--top-percent must be in (0, 100].[/]")
+        raise typer.Exit(2)
+
+    # Validate the output path up front (before the scan work) so a bad
+    # destination fails fast rather than after a long scan.
+    if output is not None:
+        from soup_cli.utils.paths import enforce_under_cwd_and_no_symlink
+
+        try:
+            enforce_under_cwd_and_no_symlink(output, "output")
+        except (ValueError, TypeError) as exc:
+            console.print(f"[red]{escape(str(exc))}[/]")
+            raise typer.Exit(2) from exc
+
+    try:
+        result = scan_model(model, modules=modules, use_cache=not no_cache)
+    except (ValueError, FileNotFoundError, RuntimeError, OSError) as exc:
+        console.print(f"[red]Spectrum scan failed:[/] {escape(str(exc))}")
+        raise typer.Exit(1) from exc
+    except Exception as exc:  # hub validation / unexpected — friendly, no traceback
+        console.print(
+            f"[red]Spectrum scan failed:[/] "
+            f"{escape(type(exc).__name__)}: {escape(str(exc))}"
+        )
+        raise typer.Exit(1) from exc
+
+    if not result.layers:
+        console.print(
+            "[yellow]No scannable 2-D weight matrices found "
+            "(check --model and --modules).[/]"
+        )
+        raise typer.Exit(1)
+
+    try:
+        kept = select_unfrozen_parameters(
+            result.layers, top_percent=top_percent, modules=modules
+        )
+    except ValueError as exc:
+        console.print(f"[red]{escape(str(exc))}[/]")
+        raise typer.Exit(2) from exc
+
+    _render_table(result, kept, top_percent)
+
+    yaml_block = yaml.safe_dump(
+        {"training": {"unfrozen_parameters": kept}},
+        default_flow_style=False,
+        sort_keys=False,
+    )
+    console.print(
+        Panel(
+            escape(yaml_block.rstrip()),
+            title="training.unfrozen_parameters",
+            border_style="cyan",
+        )
+    )
+    console.print(
+        f"[dim]{len(kept)} parameter group(s) unfrozen — paste the block above "
+        f"into your soup.yaml (full fine-tuning, LoRA off).[/]"
+    )
+
+    if output is not None:
+        from soup_cli.utils.paths import atomic_write_text
+
+        atomic_write_text(yaml_block, output, field="output")
+        console.print(f"[green]Wrote patch:[/] {escape(output)}")

{soup_cli-0.71.22 → soup_cli-0.71.23}/src/soup_cli/config/schema.py

@@ -9,6 +9,15 @@ from pydantic import BaseModel, Field, field_validator, model_validator
 _MAX_LORA_RANK_PATTERN_KEYS = 256
 _MAX_LORA_RANK_PATTERN_VALUE = 1024
 
+# v0.71.23 #266 — Spectrum targeted-training unfrozen-parameter caps
+_MAX_UNFROZEN_PARAMETERS = 50_000
+_MAX_UNFROZEN_PATTERN_LEN = 512
+# Reject nested-unbounded-quantifier regexes — e.g. ``(x+)+y`` / ``(a*)*`` —
+# which catastrophically backtrack (ReDoS) when re.search'd against parameter
+# names in apply_unfrozen_parameters. soup.yaml is shareable config, so the
+# pattern *class* is rejected at parse time, not just compile failures.
+_UNFROZEN_REDOS_RE = re.compile(r"\([^)]*[+*][^)]*\)\s*[+*]")
+
 
 class LoraConfig(BaseModel):
     r: int = Field(default=64, description="LoRA rank")
@@ -2319,6 +2328,62 @@ class TrainingConfig(BaseModel):
         lt=1.0,
         description="Freeze this fraction of layers (0.75 = freeze 75% from bottom).",
     )
+    # v0.71.23 #266 — Spectrum targeted training: full FT of selected params
+    unfrozen_parameters: Optional[List[str]] = Field(
+        default=None,
+        description=(
+            "Spectrum (#266) targeted training: regex patterns of parameter "
+            "names to keep trainable — every other parameter is frozen. Full "
+            "fine-tuning, LoRA off. Generate with `soup spectrum scan`. "
+            "Mutually exclusive with LoRA features / freeze_layers / "
+            "freeze_ratio / train_router_only; sft + transformers backend only."
+        ),
+    )
+
+    @field_validator("unfrozen_parameters")
+    @classmethod
+    def _validate_unfrozen_parameters(
+        cls, value: Optional[List[str]]
+    ) -> Optional[List[str]]:
+        """v0.71.23 #266 — caps + NUL + non-empty + regex-compilability."""
+        if value is None:
+            return None
+        if len(value) > _MAX_UNFROZEN_PARAMETERS:
+            raise ValueError(
+                f"training.unfrozen_parameters: too many patterns "
+                f"({len(value)} > {_MAX_UNFROZEN_PARAMETERS})"
+            )
+        for pat in value:
+            # pydantic's List[str] already guarantees each entry is a str.
+            if not pat:
+                raise ValueError(
+                    "training.unfrozen_parameters entries must be non-empty"
+                )
+            if "\x00" in pat:
+                raise ValueError(
+                    "training.unfrozen_parameters entries must not contain "
+                    "null bytes"
+                )
+            if len(pat) > _MAX_UNFROZEN_PATTERN_LEN:
+                raise ValueError(
+                    f"training.unfrozen_parameters entries must be "
+                    f"<= {_MAX_UNFROZEN_PATTERN_LEN} chars"
+                )
+            try:
+                re.compile(pat)
+            except re.error as exc:
+                raise ValueError(
+                    f"training.unfrozen_parameters: invalid regex {pat!r}: {exc}"
+                ) from exc
+            if _UNFROZEN_REDOS_RE.search(pat):
+                raise ValueError(
+                    f"training.unfrozen_parameters: pattern {pat!r} has nested "
+                    f"unbounded quantifiers (ReDoS risk). Use a literal "
+                    f"parameter-name prefix such as "
+                    f"'model.layers.0.mlp.down_proj' (run `soup spectrum scan`)."
+                )
+        return value
+
     # Sample packing — pack multiple short samples into one sequence
     packing: bool = Field(
         default=False,
@@ -3627,6 +3692,84 @@ class SoupConfig(BaseModel):
                 raise ValueError(str(exc)) from exc
         return self
 
+    @model_validator(mode="after")
+    def _validate_unfrozen_parameters(self) -> "SoupConfig":
+        """v0.71.23 #266 — Spectrum targeted-training compatibility gates.
+
+        ``unfrozen_parameters`` is full fine-tuning of a hand-picked parameter
+        set (LoRA off), so it is mutually exclusive with the LoRA feature
+        flags and with the other parameter-freezing mechanisms. Wired only in
+        the transformers SFT trainer.
+        """
+        tcfg = self.training
+        if not tcfg.unfrozen_parameters:
+            return self
+        if self.task != "sft":
+            raise ValueError(
+                f"training.unfrozen_parameters (Spectrum targeted training) "
+                f"requires task='sft'; got task={self.task!r}"
+            )
+        if self.backend != "transformers":
+            raise ValueError(
+                f"training.unfrozen_parameters requires backend='transformers'; "
+                f"got backend={self.backend!r}"
+            )
+        if self.modality != "text":
+            raise ValueError(
+                f"training.unfrozen_parameters requires modality='text' "
+                f"(the Spectrum branch is wired in the text SFT trainer); "
+                f"got modality={self.modality!r}"
+            )
+        if tcfg.quantization != "none":
+            raise ValueError(
+                f"training.unfrozen_parameters (Spectrum full fine-tuning) "
+                f"requires quantization='none' (got {tcfg.quantization!r}); "
+                f"quantized weights cannot be trained directly. For a quantized "
+                f"run, drop unfrozen_parameters and use LoRA (QLoRA)."
+            )
+        freeze_conflicts = []
+        if tcfg.freeze_layers is not None:
+            freeze_conflicts.append("freeze_layers")
+        if tcfg.freeze_ratio is not None:
+            freeze_conflicts.append("freeze_ratio")
+        if tcfg.train_router_only:
+            freeze_conflicts.append("train_router_only")
+        if tcfg.expand_layers is not None:
+            freeze_conflicts.append("expand_layers")
+        if tcfg.freeze_trainable_layers is not None:
+            freeze_conflicts.append("freeze_trainable_layers")
+        if freeze_conflicts:
+            raise ValueError(
+                f"training.unfrozen_parameters is mutually exclusive with "
+                f"{', '.join(freeze_conflicts)} (each independently selects "
+                f"which parameters train)"
+            )
+        lcfg = tcfg.lora
+        lora_conflicts = []
+        if lcfg.use_dora:
+            lora_conflicts.append("lora.use_dora")
+        if lcfg.use_vera:
+            lora_conflicts.append("lora.use_vera")
+        if lcfg.use_olora:
+            lora_conflicts.append("lora.use_olora")
+        if lcfg.use_rslora:
+            lora_conflicts.append("lora.use_rslora")
+        if tcfg.moe_lora:
+            lora_conflicts.append("moe_lora")
+        if tcfg.use_longlora:
+            lora_conflicts.append("use_longlora")
+        if tcfg.relora_steps is not None:
+            lora_conflicts.append("relora_steps")
+        if tcfg.loraplus_lr_ratio is not None:
+            lora_conflicts.append("loraplus_lr_ratio")
+        if lora_conflicts:
+            raise ValueError(
+                f"training.unfrozen_parameters (Spectrum full fine-tuning, "
+                f"LoRA off) is mutually exclusive with LoRA features: "
+                f"{', '.join(lora_conflicts)}"
+            )
+        return self
+
     @model_validator(mode="after")
     def _validate_rollout_backend(self) -> "SoupConfig":
         """v0.50.0 Part C — ``rollout_backend`` requires task='grpo' and a