PyPI - soup-cli - Versions diffs - 0.72.2__tar.gz → 0.72.4__tar.gz - Mend

soup-cli 0.72.2tar.gz → 0.72.4tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (925) hide show

soup_cli-0.72.4/.github/FUNDING.yml ADDED Viewed

@@ -0,0 +1,5 @@
+# Sponsor button shown in the repo sidebar and on every issue / PR.
+#
+# Renders only once the account is enrolled in GitHub Sponsors
+# (https://github.com/sponsors). Until then the button stays hidden.
+github: MakazhanAlpamys

{soup_cli-0.72.2 → soup_cli-0.72.4}/CHANGELOG.md RENAMED Viewed

@@ -12,6 +12,129 @@ reproducing 70+ versions of notes.
 ## [Unreleased]
+## [0.72.4] - 2026-08-03
+**Added — preference losses over layer streaming: DPO, ORPO, SimPO and KTO.**
+Layer streaming kept the frozen base in CPU RAM and fed it to the GPU one decoder
+layer at a time, but only for `task: sft`. This release opens it to the four
+preference losses. The whole risk was one thing: **DPO needs a reference model, and a
+second model instance would double memory and defeat the feature entirely.**
+- **The reference is the same streamed base with its adapters disabled** — one set of
+  weights, one stream, no second pass. Measured on an RTX 3050 4 GB with a 730 MB
+  model: streamed DPO peaked at **0.914x** the SFT peak, with a byte-identical RAM
+  store and buffer pool. Forcing a real second instance in the same harness cost
+  **+730.44 MB against 730.44 MB of weights** — exactly one copy. That control is what
+  makes the first number mean something.
+- **KTO is *not* reference-free**, contrary to how it is usually described: it selects
+  its reference exactly the way DPO does, so it gets the same treatment and the same
+  memory assertion. ORPO and SimPO genuinely are reference-free.
+- **Bit-exact against a resident run of the same loss** — `0.0` difference for all
+  four, the standard every slot in this series inherits.
+- **The pre-flight now knows that a paired loss is twice the rows.** DPO, ORPO and
+  SimPO concatenate chosen and rejected into one tensor, so a VRAM budget computed at
+  one row per example would have under-predicted by half — and on Windows the
+  consequence is not an error but a silent spill to host memory that makes the run an
+  order of magnitude slower.
+- **KTO requires `batch_size >= 2`** (its KL term is degenerate at 1). Soup now says so
+  when your config is read, rather than minutes later after sharding the checkpoint.
+  KTO is streamable at all only because v0.72.3 lifted the batch-1 restriction.
+- **`grpo` and `ppo` remain excluded permanently**, not "not yet": generation rollouts
+  re-read every layer once per generated token, which destroys the amortisation
+  streaming depends on. The refusal says so and deliberately names no release.
+The streaming setup now lives in one shared place instead of being copied per trainer,
+so the NF4 pre-flight, the RAM/disk tier choice and the VRAM fit refusal cannot drift
+between SFT and the preference losses.
+**Fixed — `trl` is now capped below 0.25, and that is a real bug fix, not a CI tweak.**
+Six trainers (`bco`, `dpo`, `ipo`, `kto`, `orpo`, `simpo`) pass `max_prompt_length` to
+their `trl` config, and `trl` removed it in stages: `bco` at 0.25, `kto`/`orpo`/`simpo`
+at 0.26, `dpo`/`ipo` at 0.29 — which also deleted `ORPOConfig` and `CPOConfig`
+outright. So anyone who ran `pip install 'soup-cli[train]'` and resolved to a recent
+`trl` had `soup train --task orpo` fail on import.
+That was already true before this release and nothing caught it: the `trl` imports
+live inside `setup()`, which no test had ever called on those wrappers, so CI stayed
+green while the code only worked on older `trl`. This release's end-to-end preference
+tests are what surfaced it.
+The boundary was read off the published wheels per config rather than inferred from a
+version number — the removal being staged is exactly why a single spot-check gives the
+wrong answer. Supporting the newer API is its own piece of work; declaring a dependency
+the code actually works with comes first.
+Honest costs: streaming makes the reference free in **memory**, not in **time** — DPO
+traverses the layer stack three times per step against SFT's two, measured at **1.52x**
+the layer reads. And the VRAM pre-flight is a sound *upper* bound for preference
+losses rather than a tight estimate; see Known Limitations in the release notes.
+## [0.72.3] - 2026-07-28
+**Added — layer streaming breadth: more architectures, bigger batches, resume, and a
+disk tier.**
+Layer streaming (v0.72.0–.2) was deliberately narrow: Llama/Qwen only, batch 1, no
+gradient accumulation, no resume, RAM only. This release lifts all of it, and each
+capability was gated against a streamed-vs-resident bit-exactness reference before any
+of it was written.
+- **Six more model families.** `mistral`, `gemma`, `gemma2`, `gemma3_text`, `phi` and
+  `phi3` join the allowlist, each verified **bit-exact** against the same checkpoint
+  loaded resident, under both bf16 and NF4. Phi-3 is the notable one: it fuses Q/K/V
+  into a single `qkv_proj`, so there is no `q_proj` to find, and it is bit-exact anyway.
+  Multimodal `gemma3` is deliberately *not* accepted — only `gemma3_text`.
+- **`batch_size` above 1, and gradient accumulation.** Both previously refused.
+- **A pre-flight VRAM budget that accounts for batch and vocabulary.** Streaming bounds
+  the *weights*; activations and the logits tensor are untouched by it and both scale
+  with `batch × seq`. On a 152k-vocab model at batch 8 the logits term alone measured
+  **8.71 GB — 146× the entire layer-buffer pool**. `soup train` now predicts peak VRAM
+  and refuses a run that will not fit, naming the two knobs that scale it.
+- **A throughput forecast**, quoted as a range from a GEMM ceiling measured on your own
+  card in that session, alongside the SM clock — never a compiled-in per-card constant.
+- **`--resume` and `--hf-resume` work with streaming.**
+- **A disk overflow tier.** `stream_source: auto` (the default) uses RAM when the base
+  fits and falls back to an NVMe disk tier when it does not, holding nothing resident.
+  `stream_source: ram` refuses instead of falling back. Non-NVMe disks are still
+  refused outright.
+- **`soup doctor --disk`** reports the detected media type.
+**Fixed**
+- `estimate_logits_bytes` charged 6 bytes per logit element; the measured peak is **14**
+  (`transformers` holds the bf16 logits, the fp32 upcast, log-softmax's fp32 output and
+  the fp32 gradient live at once). The old figure under-predicted that term by 2.33×.
+- Adapters could not be loaded *into* a streamed model: `load_state_dict` narrows keys
+  by child name, so a canonical checkpoint matched **0 of N** tensors and PEFT reported
+  only a warning — a resumed run reproduced the from-scratch loss curve exactly. The
+  streaming layer now redirects canonical keys at load time, mirroring the v0.72.1
+  save-side fix.
+- The NVMe-only tier guard was wired to a hardcoded constant and could never fire.
+- Streaming weight sources are now released when training ends **or raises**; the disk
+  tier holds one open shard handle per decoder layer.
+- Subprocess helpers resolve tools to absolute paths (on Windows, `CreateProcess`
+  searches the current directory before `PATH`).
+- The `[mcp]` extra is now capped at `mcp<2`. The SDK's 2.0.0 release removed
+  `mcp.shared.memory.create_connected_server_and_client_session` and dropped
+  `Server.list_tools`, breaking `soup mcp serve`'s round-trip tests for anyone
+  installing fresh. Support for the 2.x API is tracked separately.
+**Known limitations**
+- The **RAM-vs-disk performance gap is unmeasured** on the development hardware and no
+  number is claimed for it. safetensors memory-maps the shards, so the OS page cache
+  keeps them resident between steps on a machine with spare RAM, and at ~5 effective
+  TFLOPS the NVMe read hides under compute. The disk tier's *correctness* is verified
+  bit-exact against the RAM tier; its speed relative to RAM is not characterised.
+- End-to-end `soup train --resume` could not be demonstrated on the development box:
+  `transformers` refuses `torch.load` below torch 2.6 (CVE-2025-32434), which blocks
+  **every** resume there, streaming or not. The streaming-specific half — the adapter
+  round-trip and loss continuity — is verified on the production CUDA path.
+- Loading *into* a streamed model works; `named_parameters()` and `state_dict()` still
+  disagree in memory, which is the deliberate cost of a serialisation-only design.
+- Layer streaming remains **BETA**.
 ## [0.72.2] - 2026-07-28
 **Added — NF4 layer streaming: fine-tune Llama-3.1-8B on a 4 GB laptop GPU.**

{soup_cli-0.72.2 → soup_cli-0.72.4}/CODE_OF_CONDUCT.md RENAMED Viewed

@@ -36,7 +36,9 @@ This Code of Conduct applies within all community spaces, and also applies when
 ## Enforcement
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at **vpn.alpamys@gmail.com**. All complaints will be reviewed and investigated promptly and fairly.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at **team@trysoup.dev** (the project address) or **makazanalpamys@gmail.com** (the maintainer's personal address). All complaints will be reviewed and investigated promptly and fairly.
+This Code of Conduct applies in every project space, including the [Discord server](https://discord.gg/8RgVbFA6Zq).
 All community leaders are obligated to respect the privacy and security of the reporter of any incident.

{soup_cli-0.72.2 → soup_cli-0.72.4}/CONTRIBUTING.md RENAMED Viewed

@@ -120,7 +120,7 @@ src/soup_cli/
   templates/          - 21 built-in soup.yaml templates (YAML + manifest.json) with load_template loader (v0.39.0, +bco v0.40.0, +4 compliance v0.71.35)
   ui/                 - Web UI (FastAPI + HTML/JS SPA)
-tests/                - Test suite (326 files, 16840 tests)
+tests/                - Test suite (332 files, 17051 tests)
 examples/             - Real-world config examples and datasets
 ```
@@ -459,8 +459,10 @@ If you contributed and aren't credited somewhere, that's a bug — open a PR or
 - **Issues:** Report bugs and request features on [GitHub Issues](https://github.com/MakazhanAlpamys/Soup/issues)
 - **Discussions:** Ask questions on [GitHub Discussions](https://github.com/MakazhanAlpamys/Soup/discussions)
-- **Code of Conduct:** Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
-- **Security:** Report security issues via [SECURITY.md](SECURITY.md)
+- **Discord:** Chat with maintainers and other users on [Discord](https://discord.gg/8RgVbFA6Zq) — good for
+  quick questions and pairing on a PR; anything worth finding later still belongs in Issues or Discussions
+- **Code of Conduct:** Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — it applies on Discord too
+- **Security:** Report security issues via [SECURITY.md](SECURITY.md) — privately, never in Discord
 ## Questions?

{soup_cli-0.72.2 → soup_cli-0.72.4}/PKG-INFO RENAMED Viewed

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: soup-cli
-Version: 0.72.2
+Version: 0.72.4
 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
 Project-URL: Issues, https://github.com/MakazhanAlpamys/Soup/issues
-Author: Soup Team
+Project-URL: Discord, https://discord.gg/8RgVbFA6Zq
+Author-email: Soup Team <team@trysoup.dev>
 License-Expression: Apache-2.0
 License-File: LICENSE
 License-File: NOTICE
@@ -29,11 +30,11 @@ Requires-Dist: bitsandbytes>=0.41.0; extra == 'all'
 Requires-Dist: datasets>=2.14.0; extra == 'all'
 Requires-Dist: datasketch>=1.6.0; extra == 'all'
 Requires-Dist: fastapi>=0.104.0; extra == 'all'
-Requires-Dist: mcp>=1.2.0; extra == 'all'
+Requires-Dist: mcp<2,>=1.2.0; extra == 'all'
 Requires-Dist: peft>=0.7.0; extra == 'all'
 Requires-Dist: torch>=2.0.0; extra == 'all'
 Requires-Dist: transformers<5.0.0,>=4.36.0; extra == 'all'
-Requires-Dist: trl>=0.7.0; extra == 'all'
+Requires-Dist: trl<0.25,>=0.7.0; extra == 'all'
 Requires-Dist: uvicorn>=0.24.0; extra == 'all'
 Provides-Extra: audio
 Requires-Dist: librosa>=0.10.0; extra == 'audio'
@@ -61,7 +62,7 @@ Requires-Dist: bitsandbytes>=0.41.0; extra == 'dev'
 Requires-Dist: cryptography>=41.0.0; extra == 'dev'
 Requires-Dist: datasets>=2.14.0; extra == 'dev'
 Requires-Dist: httpx>=0.24.0; extra == 'dev'
-Requires-Dist: mcp>=1.2.0; extra == 'dev'
+Requires-Dist: mcp<2,>=1.2.0; extra == 'dev'
 Requires-Dist: mypy>=1.8.0; extra == 'dev'
 Requires-Dist: peft>=0.7.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
@@ -71,7 +72,7 @@ Requires-Dist: reportlab>=4.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
 Requires-Dist: torch>=2.0.0; extra == 'dev'
 Requires-Dist: transformers<5.0.0,>=4.36.0; extra == 'dev'
-Requires-Dist: trl>=0.7.0; extra == 'dev'
+Requires-Dist: trl<0.25,>=0.7.0; extra == 'dev'
 Provides-Extra: eval
 Requires-Dist: lm-eval>=0.4.0; extra == 'eval'
 Provides-Extra: fast
@@ -83,7 +84,7 @@ Requires-Dist: auto-gptq>=0.7.0; extra == 'gptq'
 Provides-Extra: liger
 Requires-Dist: liger-kernel>=0.3.0; extra == 'liger'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Requires-Dist: mcp<2,>=1.2.0; extra == 'mcp'
 Provides-Extra: mix
 Requires-Dist: scikit-optimize>=0.9.0; extra == 'mix'
 Provides-Extra: mlx
@@ -130,7 +131,7 @@ Requires-Dist: datasets>=2.14.0; extra == 'train'
 Requires-Dist: peft>=0.7.0; extra == 'train'
 Requires-Dist: torch>=2.0.0; extra == 'train'
 Requires-Dist: transformers<5.0.0,>=4.36.0; extra == 'train'
-Requires-Dist: trl>=0.7.0; extra == 'train'
+Requires-Dist: trl<0.25,>=0.7.0; extra == 'train'
 Provides-Extra: tui
 Requires-Dist: textual>=0.50.0; extra == 'tui'
 Provides-Extra: ui
@@ -158,7 +159,8 @@ Description-Content-Type: text/markdown
   <a href="#configuration">Config</a> &middot;
   <a href="#documentation">Docs</a> &middot;
   <a href="docs/commands.md">Commands</a> &middot;
-  <a href="docs/models.md">Models</a>
+  <a href="docs/models.md">Models</a> &middot;
+  <a href="https://discord.gg/8RgVbFA6Zq">Discord</a>
 </p>
 <p align="center">
@@ -169,6 +171,8 @@ Description-Content-Type: text/markdown
   <a href="https://github.com/MakazhanAlpamys/Soup/actions"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MakazhanAlpamys/65fdc943f85f3b2c46ecddb415c2b779/raw/soup_tests.json" alt="Tests"></a>
   <a href="https://github.com/MakazhanAlpamys/Soup/actions"><img src="https://github.com/MakazhanAlpamys/Soup/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://trysoup.dev"><img src="https://img.shields.io/badge/website-trysoup.dev-blue" alt="Website"></a>
+  <a href="https://discord.gg/8RgVbFA6Zq"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://doi.org/10.5281/zenodo.21771064"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21771064.svg" alt="DOI"></a>
 </p>
 ---
@@ -193,31 +197,36 @@ infrastructure instead of improving models. Soup fixes that.
 ## What's New
-**v0.72.2 — NF4 layer streaming: fine-tune Llama-3.1-8B on a 4 GB laptop GPU.** Layer
-streaming keeps the frozen base in CPU RAM and feeds it to the GPU one decoder layer at a time.
-Quantising that base to NF4 shrinks it ~4×, which is what puts an 8B model within reach of a
-card that cannot hold even a quarter of it.
-- **Measured on a 4 GB RTX 3050 Laptop** (batch 1, S=512, gradient checkpointing, 50 steps
-  after 10 warm-up): **Llama-3.1-8B-Instruct at 119.6 tok/s, peak VRAM 3.32 GB**, base
-  page-locked at 3.60 GB, GPU 100% busy. Qwen2.5-3B: 264.2 tok/s, 1.76 GB.
-- **Just add `quantization: 4bit`** to a streaming config. The base is quantised once, offline,
-  and cached; the cache re-shards by itself if the checkpoint changes underneath it.
-- **Correctness is not traded away.** A streamed NF4 run is **bit-exact** against a resident
-  NF4 run — same quantised bytes, same bitsandbytes kernels — and that is a CI test, not a
-  one-off measurement.
-- **Why 3B got 1.85× faster too** (264.2 vs 143.1 tok/s in bf16): not arithmetic. A 1.43 GB
-  store page-locks where a 5.55 GB one did not, which restores asynchronous copies and takes
-  GPU utilisation from 79.3% to 100%.
-- Still BETA, and the scope is unchanged: RAM tier, `task: sft`, Llama/Qwen, batch size 1, no
-  gradient accumulation, no `--resume`. Every refusal names the release that lifts it.
+**v0.72.4 — align on a laptop: DPO, ORPO, SimPO and KTO over layer streaming.** Layer
+streaming keeps the frozen base out of VRAM and feeds it to the GPU one decoder layer at
+a time. It used to support supervised fine-tuning only; now it runs the preference
+losses too.
+- **DPO's reference model is free.** DPO needs a reference to compare against, and a
+  second copy of the model would double memory and defeat the whole point. Soup uses
+  *the same streamed base with its adapters switched off* — one set of weights, one
+  stream. Measured on an RTX 3050 4 GB: streamed DPO peaked at **0.914×** the
+  supervised-fine-tuning peak. Forcing a real second model in the same test cost
+  **+730 MB — exactly one copy of the weights.**
+- **KTO is not reference-free**, however it is usually described: it picks its reference
+  the same way DPO does, so it gets the same treatment. ORPO and SimPO genuinely are.
+- **Bit-exact against a normal, non-streamed run** of the same loss — `0.0` difference,
+  the bar every release in this series has to clear.
+- **The VRAM pre-flight knows a paired loss is twice the rows**, because chosen and
+  rejected go through the model as one tensor.
+- **Honest cost:** the reference is free in *memory*, not in *time* — DPO reads the
+  layer stack **1.52×** as often per step as supervised fine-tuning does.
+- `grpo` / `ppo` stay excluded on purpose: generation re-reads every layer per token,
+  which is exactly what streaming cannot amortise.
+- Still BETA.
 ```yaml
 # soup.yaml — then just `soup train --config soup.yaml`
 training:
-  stream_layers: true      # base streams from RAM; only the adapter trains
+  stream_layers: true      # base streams out of VRAM; only the adapter trains
   quantization: 4bit       # NF4 — ~4x smaller store, so 8B fits a 4 GB card
-  batch_size: 1
+  batch_size: 4            # v0.72.3: bigger batches amortise the weight read
+  stream_source: auto      # RAM when it fits, NVMe disk when it does not
 ```
 > **Trained with `stream_layers: true` on v0.72.0?** That adapter is inert — its tensors were
@@ -499,17 +508,15 @@ single 4 GB laptop, which is why every performance number in these docs is measu
 claimed.
 If Soup saved you a training run, [starring the repo](https://github.com/MakazhanAlpamys/Soup)
-helps most, and it costs nothing. If you would like to fund the work directly:
+helps most, and it costs nothing.
-**[❤️ Donate](https://buy.stripe.com/4gMcN441k3pha3T19ye7m04)** — one-off, any amount (use
-*Change amount* on the checkout page). Payments are processed by Stripe under the maintainer's
-registered business, **MePlay, Inc.** — that name, not "Soup", is what appears on the checkout
-page and on your card statement.
-Donations fund GPU time for the hardware-gated work — multi-GPU, 8B+ validation, Apple
-Silicon — that a single 4 GB laptop cannot reach. See the
+The next most useful thing is **hardware**. Multi-GPU, 8B+ validation, and Apple Silicon are
+the parts a single 4 GB laptop cannot reach, so they ship behind honest "requires <hardware>"
+gates instead of unverified claims. If you have access to a bigger box — or GPU credits going
+unused — running one of the
 [`help wanted`](https://github.com/MakazhanAlpamys/Soup/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-issues for exactly what is blocked on hardware today.
+issues and posting the numbers moves Soup further than anything else. Those issues say exactly
+what is blocked on hardware today.
 ## Contributors
@@ -518,6 +525,47 @@ Built by the community ❤️ — thank you to everyone who has contributed. See
 [![Contributors](https://contrib.rocks/image?repo=MakazhanAlpamys/Soup)](https://github.com/MakazhanAlpamys/Soup/graphs/contributors)
+## Contact
+Bugs and feature requests belong in the
+[issue tracker](https://github.com/MakazhanAlpamys/Soup/issues), questions in
+[Discussions](https://github.com/MakazhanAlpamys/Soup/discussions) — both get answered faster
+and help the next person with the same problem.
+For live chat, setup help, and everything that reads better as a conversation, join the
+[Discord](https://discord.gg/8RgVbFA6Zq). Anything that should still be findable in six months
+belongs in Issues or Discussions — a Discord answer helps one person, an issue helps everyone
+who hits the same thing. The [Code of Conduct](CODE_OF_CONDUCT.md) applies there too.
+For anything that does not fit in public — security reports (see [SECURITY.md](SECURITY.md)),
+Code of Conduct matters, or press — email **team@trysoup.dev**. That is the project address
+and the right one for anything Soup-related. **makazanalpamys@gmail.com** is the maintainer's
+personal address; it reaches the same person and is a fine fallback.
+## Citing Soup
+Layer streaming — training an 8B model on a 4 GB laptop GPU by streaming the frozen base from
+host RAM one decoder layer at a time — is described in a preprint, together with the correctness
+protocol that verifies a streamed run is bit-exact against a resident one:
+> Makazhan, A. (2026). *Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop
+> GPU.* Zenodo. https://doi.org/10.5281/zenodo.21771064
+The measurement records behind every number in it are in [`benchmarks/`](benchmarks/), published
+as written — including the failures, the assumptions that turned out wrong, and the numbers that
+were measured and then discarded.
+```bibtex
+@misc{makazhan2026exact,
+  title        = {Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU},
+  author       = {Makazhan, Alpamys},
+  year         = {2026},
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.21771064},
+  url          = {https://doi.org/10.5281/zenodo.21771064}
+}
+```
 ## License
 [Apache-2.0](LICENSE). Copyright © the Soup contributors.

{soup_cli-0.72.2 → soup_cli-0.72.4}/README.md RENAMED Viewed

@@ -14,7 +14,8 @@
   <a href="#configuration">Config</a> &middot;
   <a href="#documentation">Docs</a> &middot;
   <a href="docs/commands.md">Commands</a> &middot;
-  <a href="docs/models.md">Models</a>
+  <a href="docs/models.md">Models</a> &middot;
+  <a href="https://discord.gg/8RgVbFA6Zq">Discord</a>
 </p>
 <p align="center">
@@ -25,6 +26,8 @@
   <a href="https://github.com/MakazhanAlpamys/Soup/actions"><img src="https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MakazhanAlpamys/65fdc943f85f3b2c46ecddb415c2b779/raw/soup_tests.json" alt="Tests"></a>
   <a href="https://github.com/MakazhanAlpamys/Soup/actions"><img src="https://github.com/MakazhanAlpamys/Soup/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://trysoup.dev"><img src="https://img.shields.io/badge/website-trysoup.dev-blue" alt="Website"></a>
+  <a href="https://discord.gg/8RgVbFA6Zq"><img src="https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://doi.org/10.5281/zenodo.21771064"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.21771064.svg" alt="DOI"></a>
 </p>
 ---
@@ -49,31 +52,36 @@ infrastructure instead of improving models. Soup fixes that.
 ## What's New
-**v0.72.2 — NF4 layer streaming: fine-tune Llama-3.1-8B on a 4 GB laptop GPU.** Layer
-streaming keeps the frozen base in CPU RAM and feeds it to the GPU one decoder layer at a time.
-Quantising that base to NF4 shrinks it ~4×, which is what puts an 8B model within reach of a
-card that cannot hold even a quarter of it.
-- **Measured on a 4 GB RTX 3050 Laptop** (batch 1, S=512, gradient checkpointing, 50 steps
-  after 10 warm-up): **Llama-3.1-8B-Instruct at 119.6 tok/s, peak VRAM 3.32 GB**, base
-  page-locked at 3.60 GB, GPU 100% busy. Qwen2.5-3B: 264.2 tok/s, 1.76 GB.
-- **Just add `quantization: 4bit`** to a streaming config. The base is quantised once, offline,
-  and cached; the cache re-shards by itself if the checkpoint changes underneath it.
-- **Correctness is not traded away.** A streamed NF4 run is **bit-exact** against a resident
-  NF4 run — same quantised bytes, same bitsandbytes kernels — and that is a CI test, not a
-  one-off measurement.
-- **Why 3B got 1.85× faster too** (264.2 vs 143.1 tok/s in bf16): not arithmetic. A 1.43 GB
-  store page-locks where a 5.55 GB one did not, which restores asynchronous copies and takes
-  GPU utilisation from 79.3% to 100%.
-- Still BETA, and the scope is unchanged: RAM tier, `task: sft`, Llama/Qwen, batch size 1, no
-  gradient accumulation, no `--resume`. Every refusal names the release that lifts it.
+**v0.72.4 — align on a laptop: DPO, ORPO, SimPO and KTO over layer streaming.** Layer
+streaming keeps the frozen base out of VRAM and feeds it to the GPU one decoder layer at
+a time. It used to support supervised fine-tuning only; now it runs the preference
+losses too.
+- **DPO's reference model is free.** DPO needs a reference to compare against, and a
+  second copy of the model would double memory and defeat the whole point. Soup uses
+  *the same streamed base with its adapters switched off* — one set of weights, one
+  stream. Measured on an RTX 3050 4 GB: streamed DPO peaked at **0.914×** the
+  supervised-fine-tuning peak. Forcing a real second model in the same test cost
+  **+730 MB — exactly one copy of the weights.**
+- **KTO is not reference-free**, however it is usually described: it picks its reference
+  the same way DPO does, so it gets the same treatment. ORPO and SimPO genuinely are.
+- **Bit-exact against a normal, non-streamed run** of the same loss — `0.0` difference,
+  the bar every release in this series has to clear.
+- **The VRAM pre-flight knows a paired loss is twice the rows**, because chosen and
+  rejected go through the model as one tensor.
+- **Honest cost:** the reference is free in *memory*, not in *time* — DPO reads the
+  layer stack **1.52×** as often per step as supervised fine-tuning does.
+- `grpo` / `ppo` stay excluded on purpose: generation re-reads every layer per token,
+  which is exactly what streaming cannot amortise.
+- Still BETA.
 ```yaml
 # soup.yaml — then just `soup train --config soup.yaml`
 training:
-  stream_layers: true      # base streams from RAM; only the adapter trains
+  stream_layers: true      # base streams out of VRAM; only the adapter trains
   quantization: 4bit       # NF4 — ~4x smaller store, so 8B fits a 4 GB card
-  batch_size: 1
+  batch_size: 4            # v0.72.3: bigger batches amortise the weight read
+  stream_source: auto      # RAM when it fits, NVMe disk when it does not
 ```
 > **Trained with `stream_layers: true` on v0.72.0?** That adapter is inert — its tensors were
@@ -355,17 +363,15 @@ single 4 GB laptop, which is why every performance number in these docs is measu
 claimed.
 If Soup saved you a training run, [starring the repo](https://github.com/MakazhanAlpamys/Soup)
-helps most, and it costs nothing. If you would like to fund the work directly:
+helps most, and it costs nothing.
-**[❤️ Donate](https://buy.stripe.com/4gMcN441k3pha3T19ye7m04)** — one-off, any amount (use
-*Change amount* on the checkout page). Payments are processed by Stripe under the maintainer's
-registered business, **MePlay, Inc.** — that name, not "Soup", is what appears on the checkout
-page and on your card statement.
-Donations fund GPU time for the hardware-gated work — multi-GPU, 8B+ validation, Apple
-Silicon — that a single 4 GB laptop cannot reach. See the
+The next most useful thing is **hardware**. Multi-GPU, 8B+ validation, and Apple Silicon are
+the parts a single 4 GB laptop cannot reach, so they ship behind honest "requires <hardware>"
+gates instead of unverified claims. If you have access to a bigger box — or GPU credits going
+unused — running one of the
 [`help wanted`](https://github.com/MakazhanAlpamys/Soup/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
-issues for exactly what is blocked on hardware today.
+issues and posting the numbers moves Soup further than anything else. Those issues say exactly
+what is blocked on hardware today.
 ## Contributors
@@ -374,6 +380,47 @@ Built by the community ❤️ — thank you to everyone who has contributed. See
 [![Contributors](https://contrib.rocks/image?repo=MakazhanAlpamys/Soup)](https://github.com/MakazhanAlpamys/Soup/graphs/contributors)
+## Contact
+Bugs and feature requests belong in the
+[issue tracker](https://github.com/MakazhanAlpamys/Soup/issues), questions in
+[Discussions](https://github.com/MakazhanAlpamys/Soup/discussions) — both get answered faster
+and help the next person with the same problem.
+For live chat, setup help, and everything that reads better as a conversation, join the
+[Discord](https://discord.gg/8RgVbFA6Zq). Anything that should still be findable in six months
+belongs in Issues or Discussions — a Discord answer helps one person, an issue helps everyone
+who hits the same thing. The [Code of Conduct](CODE_OF_CONDUCT.md) applies there too.
+For anything that does not fit in public — security reports (see [SECURITY.md](SECURITY.md)),
+Code of Conduct matters, or press — email **team@trysoup.dev**. That is the project address
+and the right one for anything Soup-related. **makazanalpamys@gmail.com** is the maintainer's
+personal address; it reaches the same person and is a fine fallback.
+## Citing Soup
+Layer streaming — training an 8B model on a 4 GB laptop GPU by streaming the frozen base from
+host RAM one decoder layer at a time — is described in a preprint, together with the correctness
+protocol that verifies a streamed run is bit-exact against a resident one:
+> Makazhan, A. (2026). *Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop
+> GPU.* Zenodo. https://doi.org/10.5281/zenodo.21771064
+The measurement records behind every number in it are in [`benchmarks/`](benchmarks/), published
+as written — including the failures, the assumptions that turned out wrong, and the numbers that
+were measured and then discarded.
+```bibtex
+@misc{makazhan2026exact,
+  title        = {Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model on a 4 GB Laptop GPU},
+  author       = {Makazhan, Alpamys},
+  year         = {2026},
+  publisher    = {Zenodo},
+  doi          = {10.5281/zenodo.21771064},
+  url          = {https://doi.org/10.5281/zenodo.21771064}
+}
+```
 ## License
 [Apache-2.0](LICENSE). Copyright © the Soup contributors.

{soup_cli-0.72.2 → soup_cli-0.72.4}/SECURITY.md RENAMED Viewed

@@ -17,6 +17,9 @@ for anything security-sensitive.
 - Preferred: open a private report via
   [GitHub Security Advisories](https://github.com/MakazhanAlpamys/Soup/security/advisories/new).
+- If you cannot use GitHub, email **team@trysoup.dev** (the project address), or
+  **makazanalpamys@gmail.com** (the maintainer's personal address) if that bounces.
+  Please do not report security issues in Discord — it is a public channel.
 We aim to acknowledge reports within 5 business days and to ship a fix or
 mitigation for confirmed, in-scope issues as promptly as is practical. When

soup_cli-0.72.4/benchmarks/README.md ADDED Viewed

@@ -0,0 +1,57 @@
+# Measurement records
+Raw gate records for Soup's layer-streaming feature, published as written.
+These are not a report assembled after the fact. They are the working records
+kept while each item was built and verified, so they contain the failures, the
+assumptions that turned out wrong, and the numbers that were measured and then
+discarded — in the order those things happened.
+They are the evidence behind the preprint:
+> Makazhan, A. (2026). *Exact Layer Streaming: LoRA Fine-Tuning of an 8B Model
+> on a 4 GB Laptop GPU.* Zenodo.
+> [10.5281/zenodo.21771064](https://doi.org/10.5281/zenodo.21771064)
+| File | What it gates | Headline |
+|---|---|---|
+| [`gate-v0.72.0-layer-streaming.md`](gate-v0.72.0-layer-streaming.md) | The streaming path itself | Bit-exactness vs a resident reference; 3B bf16 trained on a 4 GB card |
+| [`gate-v0.72.2-nf4.md`](gate-v0.72.2-nf4.md) | NF4 quantised streaming | Llama-3.1-8B at 119.6 tok/s in a 3.32 GB peak |
+| [`gate-v0.72.3-breadth.md`](gate-v0.72.3-breadth.md) | Nine architectures, batching, accumulation, resume, disk tier | Peak-VRAM predictor at 0.85% worst-case error; accumulation is per-token I/O-neutral |
+| [`gate-v0.72.4-preference-losses.md`](gate-v0.72.4-preference-losses.md) | DPO / ORPO / SimPO / KTO over the streaming engine | DPO's reference model costs no extra weights — 0.914x the SFT peak, against +730.44 MB for a real second instance |
+## Hardware
+Every number was measured on one machine:
+- **GPU** — RTX 3050 Laptop, 4 GB (4.29 GB usable)
+- **Host** — 16.9 GB RAM, NVMe
+- **OS** — Windows 11
+Windows/WDDM matters for reading these: it spills into shared host memory rather
+than raising `CUDA out of memory`, so a run completing is not evidence that its
+configuration fits. That is why peak VRAM is reported alongside every throughput
+figure, and why the fit decision refuses rather than warns.
+## Reading the numbers
+- **Throughput is quoted with the SM clock it was taken at.** This card's boost
+  clock varies about 13% between sessions, so a fraction-of-ceiling stated
+  without its clock is not meaningful. Where a GEMM ceiling is compared against,
+  it was measured in the same session.
+- **The correctness reference always matches the numerics under test** — a
+  streamed NF4 run is compared against a *resident NF4* run, never against
+  resident bf16, which would hide a real defect inside quantisation error.
+- **Derived figures are labelled as arithmetic.** Where a line says "1M tokens =
+  2.3 h", that is division, not a measured wall-clock run.
+## Reproducing
+The implementation ships in Soup under Apache-2.0. Reproduction commands are in
+Appendix A of the paper; the correctness protocol runs as part of the project's
+test suite, so a regression in bit-exactness fails CI rather than reaching a
+user.
+```bash
+pip install 'soup-cli[train]'
+```

soup-cli 0.72.2__tar.gz → 0.72.4__tar.gz

soup-cli 0.72.2tar.gz → 0.72.4tar.gz