soup-cli 0.71.28__tar.gz → 0.71.29__tar.gz

{soup_cli-0.71.28 → soup_cli-0.71.29}/CHANGELOG.md

@@ -12,6 +12,35 @@ reproducing 70+ versions of notes.
 
 ## [Unreleased]
 
+## [0.71.29] - 2026-07-05
+
+### Added
+- **`soup shrink`** — depth-prune a model + optional distill-heal
+  ("The Unreasonable Ineffectiveness of the Deeper Layers", arXiv:2403.17887).
+  Ranks decoder layers by the angular distance of the residual stream across a
+  contiguous block over a calibration set, drops the least-important block
+  (first and last layer always protected), optionally *heals* by distilling the
+  original model into the pruned student, and emits a single dense smaller model
+  plus a one-screen **SHIP / DON'T SHIP** perplexity verdict.
+  `soup shrink --model <id|path> [--drop-ratio 0.25 | --drop-layers N] --calib
+  <calib.jsonl> [--heal <heal.jsonl> --heal-steps N] [--tolerance 0.10]
+  [-o <dir>] [--device cpu] [--attach-to-registry <id>] [--plan-only]`.
+  Exit codes: 0 = SHIP, 2 = DON'T SHIP, 1 = error. The heal runs as an isolated
+  `soup train` subprocess (LoRA-student logit distillation) and the adapter is
+  fused back so the shipped artifact stays a single dense model. Arch allowlist
+  v1: Llama / Qwen / SmolLM. Validated live on SmolLM2-135M (drop 25 %: 30 -> 22
+  layers, ppl x2.98 unhealed; drop 4 + heal: ppl x1.35, recovered).
+
+### Security
+- `soup shrink` contains `--calib` / `--heal` / `--output-dir` (and every
+  derived write path: `<out>/model`, `<out>/heal_adapter`, the fuse staging dir)
+  under cwd with `os.path.realpath` + `commonpath` + O_NOFOLLOW + symlink
+  rejection, re-validating derived paths right before each write (TOCTOU). The
+  heal subprocess uses an argv list (no shell) with a timeout; its config is
+  schema-validated before spawn; subprocess output is C0/ESC-stripped before it
+  reaches the terminal. `--model` defaults `trust_remote_code=False` with a
+  probe + warn.
+
 ## [0.71.28] - 2026-07-04
 
 ### Added

{soup_cli-0.71.28 → soup_cli-0.71.29}/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 (305 files, 15140 tests)
+tests/                - Test suite (306 files, 15224 tests)
 examples/             - Real-world config examples and datasets
 ```
 
@@ -150,7 +150,7 @@ pytest tests/test_data.py::test_detect_alpaca_format -v
 pytest tests/ --cov=soup_cli --cov-report=html
 ```
 
-### Test Files (305 files)
+### Test Files (306 files)
 
 > A representative sample of the suite below. The full table lives in
 > [`.claude/CLAUDE.md`](.claude/CLAUDE.md); run `pytest tests/ -v` for the complete list.

{soup_cli-0.71.28 → soup_cli-0.71.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soup-cli
-Version: 0.71.28
+Version: 0.71.29
 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
@@ -193,25 +193,22 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.28 — Drive Soup from your coding agent: `soup mcp serve`.** A Model Context Protocol server, so Claude Code / Cursor / Cline / Continue can run Soup conversationally. No other fine-tuning CLI ships one.
-
-- **14 read-only tools, JSON out.** `advise`, `data_inspect` / `validate` / `score` / `doctor`,
-  `recipes_search` / `show`, `runs_list` / `show`, `registry_list` / `show`, `profile`,
-  `diagnose_evidence`, `ship_evidence` — your agent can inspect data, search recipes, read runs,
-  and get a ship verdict without you leaving the chat.
-- **Plan-only by default, safe by design.** stdio transport only (no network listener); the two
-  mutating tools (`train_start`, `export`) are gated behind `--allow-mutating` and only ever
-  render the exact command that would run. Every path argument re-enters cwd containment +
-  symlink rejection; output is control-char sanitized; errors are path-free.
-- **Light install.** The official `mcp` SDK lives behind a new `[mcp]` extra
-  (`pip install 'soup-cli[mcp]'`), lazy-imported so the core CLI stays torch-free and fast.
-- **Live-validated on Windows.** A real stdio MCP client drove `initialize → list_tools →
-  call` end-to-end on Windows + RTX 3050 — read tools return real JSON, the mutating tools
-  refuse without the flag, and a path-traversal argument is rejected.
-
-```jsonc
-// .mcp.json (Claude Code) or claude_desktop_config.json
-{ "mcpServers": { "soup": { "command": "soup", "args": ["mcp", "serve"] } } }
+**v0.71.29 — Make your model smaller, locally: `soup shrink`.** Depth-prune the least-important layers, then distill-heal — with a binary SHIP / DON'T-SHIP verdict. Based on "The Unreasonable Ineffectiveness of the Deeper Layers" (arXiv:2403.17887).
+
+- **Importance-ranked depth pruning.** One forward pass per calibration prompt scores each
+  contiguous layer block by the angular distance of the residual stream across it; the
+  least-important block is dropped (the first and last layer are always protected).
+- **Distill-heal, Minitron-style.** `--heal` distills the original model into the pruned
+  student (LoRA logit-KD) as an isolated `soup train` run, then fuses the adapter back so you
+  ship a single dense smaller model — not a base + adapter.
+- **A verdict, not a dashboard.** Every run ends in **SHIP** or **DON'T SHIP** on a
+  before/after perplexity ratio (`exit 0 = SHIP`, `2 = DON'T`, `1 = error`), so it drops into CI.
+- **Runs on a laptop GPU.** Live-validated on Windows + RTX 3050 with SmolLM2-135M: drop 25 %
+  (30 → 22 layers, 21 % params) and drop-4 + CPU heal (perplexity recovered to ×1.35).
+
+```bash
+soup shrink --model HuggingFaceTB/SmolLM2-135M-Instruct --drop-ratio 0.25 \
+    --calib calib.jsonl --heal heal.jsonl --heal-steps 200 -o shrunk --device cpu
 ```
 
 Full history: [CHANGELOG.md](CHANGELOG.md) · [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).

{soup_cli-0.71.28 → soup_cli-0.71.29}/README.md

@@ -49,25 +49,22 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.28 — Drive Soup from your coding agent: `soup mcp serve`.** A Model Context Protocol server, so Claude Code / Cursor / Cline / Continue can run Soup conversationally. No other fine-tuning CLI ships one.
-
-- **14 read-only tools, JSON out.** `advise`, `data_inspect` / `validate` / `score` / `doctor`,
-  `recipes_search` / `show`, `runs_list` / `show`, `registry_list` / `show`, `profile`,
-  `diagnose_evidence`, `ship_evidence` — your agent can inspect data, search recipes, read runs,
-  and get a ship verdict without you leaving the chat.
-- **Plan-only by default, safe by design.** stdio transport only (no network listener); the two
-  mutating tools (`train_start`, `export`) are gated behind `--allow-mutating` and only ever
-  render the exact command that would run. Every path argument re-enters cwd containment +
-  symlink rejection; output is control-char sanitized; errors are path-free.
-- **Light install.** The official `mcp` SDK lives behind a new `[mcp]` extra
-  (`pip install 'soup-cli[mcp]'`), lazy-imported so the core CLI stays torch-free and fast.
-- **Live-validated on Windows.** A real stdio MCP client drove `initialize → list_tools →
-  call` end-to-end on Windows + RTX 3050 — read tools return real JSON, the mutating tools
-  refuse without the flag, and a path-traversal argument is rejected.
-
-```jsonc
-// .mcp.json (Claude Code) or claude_desktop_config.json
-{ "mcpServers": { "soup": { "command": "soup", "args": ["mcp", "serve"] } } }
+**v0.71.29 — Make your model smaller, locally: `soup shrink`.** Depth-prune the least-important layers, then distill-heal — with a binary SHIP / DON'T-SHIP verdict. Based on "The Unreasonable Ineffectiveness of the Deeper Layers" (arXiv:2403.17887).
+
+- **Importance-ranked depth pruning.** One forward pass per calibration prompt scores each
+  contiguous layer block by the angular distance of the residual stream across it; the
+  least-important block is dropped (the first and last layer are always protected).
+- **Distill-heal, Minitron-style.** `--heal` distills the original model into the pruned
+  student (LoRA logit-KD) as an isolated `soup train` run, then fuses the adapter back so you
+  ship a single dense smaller model — not a base + adapter.
+- **A verdict, not a dashboard.** Every run ends in **SHIP** or **DON'T SHIP** on a
+  before/after perplexity ratio (`exit 0 = SHIP`, `2 = DON'T`, `1 = error`), so it drops into CI.
+- **Runs on a laptop GPU.** Live-validated on Windows + RTX 3050 with SmolLM2-135M: drop 25 %
+  (30 → 22 layers, 21 % params) and drop-4 + CPU heal (perplexity recovered to ×1.35).
+
+```bash
+soup shrink --model HuggingFaceTB/SmolLM2-135M-Instruct --drop-ratio 0.25 \
+    --calib calib.jsonl --heal heal.jsonl --heal-steps 200 -o shrunk --device cpu
 ```
 
 Full history: [CHANGELOG.md](CHANGELOG.md) · [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).

{soup_cli-0.71.28 → soup_cli-0.71.29}/docs/commands.md

@@ -158,6 +158,9 @@ soup ship ... --task-mode judge_score --judge-model ollama://llama3.1  Leg-1 via
 soup ship ... --general-suite mmlu,gsm8k --baseline base.json  lm-eval leg-2 + recorded base scores
 soup mcp serve                                MCP server over stdio (drive Soup from Claude Code / Cursor / Cline; requires [mcp] extra) (v0.71.28)
 soup mcp serve --allow-mutating               Also expose plan-only train_start / export tools (never execute) (v0.71.28)
+soup shrink --model <id|path> --drop-ratio 0.25 --calib c.jsonl -o shrunk  Depth-prune least-important layer block + SHIP/DON'T-SHIP ppl verdict (exit 0/2/1) (v0.71.29)
+soup shrink ... --drop-layers N --heal h.jsonl --heal-steps 200 --device cpu  Drop N layers + distill-heal (fuse LoRA back to one dense model)
+soup shrink ... --tolerance 0.10 --plan-only [--attach-to-registry <id>]  Ppl-regression tolerance / print importance table only / registry attach
 soup tui                                      Full-screen Textual dashboard (requires [tui] extra)
 soup train --config soup.yaml --profile       Record torch.profiler trace to <output>/profiles/
 soup --log-level quiet|normal|verbose|debug   Global logging tier (Rich-formatted)

{soup_cli-0.71.28 → soup_cli-0.71.29}/docs/peft-and-efficiency.md

@@ -24,6 +24,57 @@
 - [Training Stability & Auto-Tuning](#training-stability--auto-tuning)
 - [Training Intelligence (Forgetting + Checkpoint Quality)](#training-intelligence-forgetting--checkpoint-quality)
 - [GaLore (Memory-Efficient Full-Parameter Training)](#galore-memory-efficient-full-parameter-training)
+- [Depth Pruning + Distill-Heal (`soup shrink`)](#depth-pruning--distill-heal-soup-shrink)
+
+---
+
+## Depth Pruning + Distill-Heal (`soup shrink`)
+
+`soup shrink` makes a model smaller by dropping its least-important **contiguous
+block of decoder layers**, then optionally *healing* the loss with knowledge
+distillation. It implements "The Unreasonable Ineffectiveness of the Deeper
+Layers" (Gromov et al., arXiv:2403.17887), with a Minitron-style distillation
+heal instead of the paper's plain LoRA fine-tune.
+
+**How it ranks layers.** For each candidate block `[L, L+n)`, one forward pass
+per calibration prompt (`output_hidden_states=True`) measures the **angular
+distance** of the residual stream entering (`hidden_states[L]`) vs leaving
+(`hidden_states[L+n]`) the block, averaged over every non-pad token across the
+calibration set. The block with the *lowest* distance transforms the residual
+stream least, so it is the safest to drop. The first and last decoder layers are
+always protected (they carry the most transformation).
+
+```bash
+# See the importance table + chosen block without writing anything:
+soup shrink --model HuggingFaceTB/SmolLM2-135M-Instruct --drop-ratio 0.25 \
+    --calib calib.jsonl --device cpu --plan-only
+
+# Prune 25% + heal (distill the original into the pruned student, fuse to one
+# dense model) + get a SHIP/DON'T-SHIP perplexity verdict:
+soup shrink --model HuggingFaceTB/SmolLM2-135M-Instruct --drop-ratio 0.25 \
+    --calib calib.jsonl --heal heal.jsonl --heal-steps 200 \
+    --tolerance 0.10 -o shrunk --device cpu --attach-to-registry <id>
+```
+
+- **`--drop-ratio F` / `--drop-layers N`** (exactly one) — how many contiguous
+  layers to drop; the *position* is chosen automatically by the importance scan.
+- **`--calib <jsonl>`** — calibration prompts (`{"text": ...}` / `{"prompt":
+  ...}` / chat `messages`). Must stay under cwd.
+- **`--heal <jsonl> --heal-steps N`** — distill the full-depth original into the
+  pruned student (LoRA logit-KD) as an isolated `soup train` subprocess, then
+  fuse the adapter back into the pruned base so the output is a single dense
+  model. Heal keeps the teacher resident (~2× model memory); with `--device
+  cpu` the heal runs on CPU (validated ≤ 3 B on a 4 GB card).
+- **`--tolerance F`** — ship if the perplexity regression stays within `F`
+  (default `0.10` = 10 %). Exit code `0 = SHIP`, `2 = DON'T SHIP`, `1 = error`.
+- **`-o <dir>`** — the shrunk model lands in `<dir>/model`; the verdict in
+  `<dir>/shrink_report.json`.
+
+**Arch support (v1):** Llama / Qwen / SmolLM. Others are a friendly reject.
+The importance pass loads the model, so live-validated on ≤ 3 B; larger models
+work but are unvalidated on the reference hardware. Perplexity is an unweighted
+mean of per-example perplexities — valid for the before/after *ratio* the
+verdict uses, not directly comparable to `soup eval` absolute numbers.
 
 ---