Question 1

What's new in the latest Soup CLI release?

Accepted Answer

v0.73.0 is the release that came out of three days on somebody else's hardware. Every number this project had ever published was measured on one machine, a 4 GB RTX 3050 Laptop running Windows, and that machine cannot check the feature's central claim. Checking it needs a resident reference: the same checkpoint at the same precision, loaded the ordinary way, so the two can be compared tensor by tensor. On a 4 GB card no such reference exists for any model worth streaming, so every published correctness check had run against 3-layer models built from a config. From 5 to 9 August 2026 Soup ran on a borrowed 8x H100 box for the first time, on a much newer torch, bitsandbytes, trl and peft stack. That found one silent correctness defect in layer streaming, four backends that had never actually run, and a documented multi-GPU entry point that had never launched, alongside the first evidence that the laptop result reproduces on hardware nothing like it. It is a minor bump rather than another v0.72.x patch because it adds two capabilities that did not exist and repairs four backends. The defect first, because disclosing it is the point. In NF4, above a boundary bracketed between 163.8 and 171.5 MB per decoder layer, the backward pass produced silently wrong gradients on every layer except the last few, while the forward stayed bit-exact, the loss matched a resident reference to every digit, and the run exited 0. That is 32B and 72B; 8B sits at 105 MB per layer and 14B at 132, both below the boundary with margin and both verified exact over a 50-consecutive-backward soak, so nothing this project has ever published is above it. The cause is buffer aliasing rather than a race, established by measurement because a full device synchronise does not fix it and de-aliasing does: bitsandbytes keeps the packed 4-bit weight and its quantisation state on the autograd context as ordinary attributes instead of going through save_for_backward, so gradient checkpointing cannot recompute them, and the reference captured during the forward aliases a streaming buffer that has been refilled with another layer by the time the backward reads it. bf16 was never affected at nearly four times the bytes per layer, because it goes through a native operation that does use save_for_backward. The obvious repair, giving every pooled tensor a private copy, was measured and rejected: it costs only about 6% of throughput but takes peak VRAM from 4,220 MB to 19,720 MB on a real 32B, which is approximately the whole model, and a repair proportional to the model rather than to one layer deletes the reason the feature exists. The repair that shipped keeps streamed NF4 weights out of that code path entirely, dequantising inside the checkpointed region so the saved tensor goes through the ordinary mechanism. It is gated on two real models against a control that reproduced the defect in the same process: 256 of 256 gradient tensors exact at 32B against the control's 8 to 12, and 320 of 320 at 72B, the size where the defect was worst, against the control's 8. It costs 2.9% peak VRAM and 4.8% throughput at 32B, and 2.6% and 3.7% at 72B. The library behaviour it works around is upstream and unchanged, filed as bitsandbytes issue 2034. What the same three days confirmed. The streamed forward pass is bit-exact against a matched resident reference at 0.5B, 8B, 14B, 32B and 72B, on real checkpoints rather than fixtures, which is the experiment the preprint names as the most useful one missing from it. Peak VRAM is flat in model size, 3,397 MB at 8B, 4,475 at 14B and 4,845 at 32B while the model grows fourfold, which is the whole claim of the feature measured across a real size range for the first time. The published laptop headline reproduces on completely different hardware and a much newer stack at a median 113.00 tok/s in the same 3.32 GB peak, and the server card is if anything slightly slower with mean utilisation at 54%, which is direct evidence that the method is bound by host-to-device transfer rather than by the GPU. And a streamed model converges indistinguishably from a resident one, which had never been measured anywhere in the project: five paired runs on disjoint training subsets scored by Soup's own soup ship gave a mean paired difference of 0.0053 on a 300-item held-out set, smaller than either arm's own run-to-run spread, with the general-capability leg pointing against the convenient direction. Read that as no difference detectable at this resolution, not as no difference. Against DeepSpeed ZeRO-3 with CPU parameter offload at matched numerics on one card, streaming is 2.93 times the throughput in 9.7 times less peak VRAM, and the honest reading is narrow and the same session establishes it: eight cards of ZeRO-3 are slower than one card training resident for a model that fits. Layer streaming is not faster than DeepSpeed, it is for the case where the one card you have is too small. Two capabilities are new. training.seed and training.data_seed are the first seed knobs in the project's history, because every run trained at seed 42 with no way to change it. Both default to unset rather than to 42 on purpose, since an unset seed has to reproduce two different historical defaults, and they are wired into the supervised trainer only, which is stated rather than left as a footgun. Full fine-tuning is now reachable as lora.r 0: the trainer's full-fine-tune branch was dead code with no way to enter it, and rank 0 was chosen because three consumers already treat it as no adapter and it previously crashed inside PEFT, so no config that worked before changes meaning. Alongside them, a DeepSpeed ZeRO-3 CPU parameter offload preset can finally be named on the command line, measured at 21.65 tok/s and a 38,135 MB peak on one H100, and trl support is widened to below 0.29 behind a capability-probe compatibility layer rather than a version table, because a version table is what was wrong twice before. Four things had never executed once, and finding them is what borrowed hardware bought. The documented multi-GPU entry point never launched at all, because the launcher was handed a Python binary where a script path belongs and every rank died before the trainer existed. DeepSpeed could not train a LoRA model on any stage, because LoRA leaves one optimizer parameter group empty and the scheduler then hits a strict length check. SGLang serving returned 500 on every single request. And the Liger kernel crashed at step 0 across the whole supported dependency range. All four are repaired and verified on real hardware. Five fixes mean a user should re-check something they already did, and they are worth stating plainly. A supervised run with data.max_length above 1024 was silently truncated to 1024 on every run, measured as 4096 giving 1024 tokens per sample with no warning, so long-context and multi-turn tunes are affected. A run with use_fsdp2_compile wrote an adapter that reloads as all zeros while exiting 0 with a healthy loss, which is the third defect of that exact shape in this project's history. Two of soup ship's three behavioural suites scored 0.000 on a model that does both tasks correctly, and its refusal detector missed the typographic apostrophe that Llama actually types, reporting 0.300 for a model whose true refusal rate is 1.000, so verdicts issued before this release are suspect. A quantised GGUF export deleted a previously exported f16 file, even with an unrelated output path. And the printed hint for running without re-execution dropped every flag the user had typed, so following it literally trained a different configuration. Honest limits, stated rather than hidden. The seed reaches the supervised trainer only. A resident 4-bit run is still not bit-reproducible from a seed while a streamed one is, and that has a real consequence for the ship gate: three runs of one unchanged resident config moved two suites by 0.375 and 0.269 against a 0.05 threshold, so five of seven suites can cross the regression line on a re-run that changed nothing. The streaming VRAM pre-flight still over-predicts and its per-logit constant was deliberately left where it is, because over-predicting refuses a run that would have worked while under-predicting on Windows is not an exception at all but a silent spill into host memory. DeepSpeed with LoRA is repaired in the supervised trainer only. The reward-hacking controller's mechanism is confirmed and its efficacy is not. Two ship suites still have scoring gaps that outrank capability. The RAM-versus-disk streaming throughput gap remains unmeasured. And layer streaming remains BETA. One number to read carefully: the published 119.6 tok/s laptop figure was measured before this release's correctness repair and has not been re-run on a 4 GB card. The repair cost 4.8% throughput at 32B, so treat the laptop figure as a pre-repair number until someone re-measures it on that hardware. A server card cannot substitute, because the whole point of the H100 result is that this method is transfer-bound and its throughput does not carry across machines. Underneath, the v0.72 line is unchanged and still carries the flagship. v0.72.4 opened layer streaming to the preference losses. Until this release, a model too big for your card could only be supervised fine-tuned on it: task had to be sft, and DPO, ORPO, SimPO and KTO were all refused when the config was read. All four now run against a streamed base with the same config keys, so preference alignment stops being the step that forces you to rent a bigger card. The hard part was DPO's reference model. DPO scores the policy against a frozen reference, and the obvious implementation builds a second copy of the model, which doubles the weights and destroys the entire premise of streaming. Soup instead takes the reference from the same streamed base with its LoRA adapters switched off, so policy and reference are one set of weights, one RAM store and one buffer pool, and the adapter is the only difference between the two forward passes. The reference costs no extra weights at all. That claim is measured rather than asserted, because a passing loss curve cannot detect its failure: if disabling the adapter were a silent no-op through the streamed path, the reference would be the policy, every log-ratio would be zero, and the DPO loss would sit at 0.6931 forever, which reads as slow training rather than as a bug. So three things were measured instead. Streamed DPO peaked at 0.914 times the streamed supervised peak, with a byte-identical RAM store and buffer pool. The same harness with a real second instance forced in moved the peak by 730.44 MB against 730.44 MB of weights, which is exactly one copy, so the control shows what a second copy would have looked like. And a zero-adapter control measured a policy-versus-reference gap of exactly zero, proving the gap in the real run comes from the adapter and not from some other difference between the two passes. All four losses are bit-exact against a resident run of the same loss, difference exactly 0.0. Read the 0.914 as no second copy, not as a saving: it sits below 1 because that fixture splits the same 64 positions into a 32-token prompt and a 32-token completion, so its logits tensor is smaller, and the numbers come from a 365.2M-parameter synthetic model, not from a real checkpoint. Two things are worth knowing before reaching for it. The reference is free in memory, not in time: DPO walks the layer stack 1.52 times as often per step as supervised fine-tuning does, because it adds a reference forward to the policy forward and the gradient-checkpoint recompute. And KTO is not reference-free, however it is usually described: it selects its reference exactly the way DPO does, so it gets the same treatment, while ORPO and SimPO genuinely are reference-free. KTO also requires a batch size of 2 or more, because TRL's KL term is degenerate at batch 1, and Soup refuses that when the config is read rather than minutes into a run after the checkpoint has been sharded. Two honest limits ride along. No throughput figure is claimed for any preference loss at any size, because none was measured. And the VRAM pre-flight is a sound upper bound for these losses but a loose one: it charges the supervised loss's 14 bytes per logit element over twice the rows, while TRL reduces preference logits to per-token log-probabilities instead of holding a full-vocabulary fp32 upcast, so on a 4 GB card with a 128k-vocabulary 1B model DPO is allowed at max_length 512 and refused from 768 up, even though it would probably fit. That looseness shipped deliberately, because under-predicting is the strictly worse failure: on Windows an overcommit is not an exception but a silent spill into host memory that makes the run an order of magnitude slower with no error at all. GRPO and PPO stay excluded permanently rather than pending, because generation rollouts re-read every layer once per generated token, which destroys the amortisation streaming depends on, and the refusal deliberately names no release. Note that ipo, bco and the unified preference dispatcher are not in the streaming allowlist either; the five accepted values are exactly sft, dpo, orpo, simpo and kto. One more thing shipped alongside, and it fixed a bug that predates the release: six preference trainers pass a field that TRL removed in stages, so a fresh install could fail at import before training started, and the dependency bound that pins it was settled by constructing all six configs against each version rather than by reading source. The measurement records behind all of this now live in the repository's benchmarks directory, published as written, with the failures and the numbers that were measured and then discarded left in place, and the layer-streaming work has a preprint with a DOI. Underneath it, v0.72.3 was layer-streaming breadth. The previous two releases proved you can fine-tune a model that does not fit in your card, and v0.72.2 put Llama-3.1-8B on a 4 GB laptop GPU, but the path was deliberately narrow: Llama and Qwen only, batch size 1, no gradient accumulation, no resume, RAM only. This release lifts all of it, and every capability was gated against a streamed-versus-resident bit-exactness reference before it was written. Six more model families join the allowlist: mistral, gemma, gemma2, gemma3_text, phi and phi3, which takes it to nine model types in total alongside llama, qwen2 and qwen3. Each was verified bit-exact against the same checkpoint loaded resident, under both bf16 and NF4. Phi-3 is the interesting one, because it fuses Q, K and 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 is. There are no throughput numbers for the newly supported families, so none are claimed. batch_size above 1 and gradient_accumulation_steps above 1 both work now, and the release measured which one you should reach for. On Qwen2.5-0.5B in bf16 at sequence length 256 with a pinned store, batch 1 with no accumulation runs at 556.6 tok/s in 0.842 GB, batch 1 with accumulation 4 runs at 540.1 tok/s in 0.846 GB, and batch 4 with no accumulation runs at 1378.0 tok/s in 2.28 GB. At the same effective batch of 4, raising batch_size is about 2.52 times faster than accumulating, and the reason is structural rather than incidental: a real batch amortises each layer load over more tokens, while accumulation re-reads the entire base for every micro-batch, so the layer reads per 1000 tokens stay flat across accumulation 1, 2 and 4. Raise batch_size until VRAM says stop, then accumulate. Because batches now scale, there is a pre-flight that accounts for them. Streaming bounds the weights, but activations and the logits tensor are untouched by it and both scale with batch times sequence length, which is exactly the term a user cannot estimate by eye. On a 152k-vocabulary model at batch 8 the logits tensor alone measured 8.71 GB, which is 146 times the entire layer-buffer pool of 0.060 GB. soup train now predicts peak VRAM before the run and refuses one that will not fit, naming the two knobs that scale it. The estimate was fitted against ten real runs across two models with a 3.1-fold vocabulary contrast, with a worst error of 0.85%, and it never under-predicts any of them. It also corrected a real bug: the old estimator charged 6 bytes per logit element from first principles, and the measured peak is 14, because transformers holds the bf16 logits, the fp32 upcast, log-softmax's fp32 output and the fp32 gradient all at once. The old figure under-predicted that term by 2.33 times. This matters more on Windows than it sounds, because WDDM does not raise on overcommit: a run that should have failed instead spilled to a 9.27 GB peak on a card with 4.29 GB, silently, by paging to host memory. Alongside the budget there is now a throughput forecast, quoted as a range derived from a GEMM ceiling measured on your own card in that session, printed next to the SM clock, never a compiled-in per-card constant. That design is a response to a measurement, not a preference: this one card produced 3.5 and 7.6 TFLOPS in two different sessions at the same reported clock, so a baked-in number would have been wrong half the time. Real streamed runs land at 68 to 100% of their measured ceiling. --resume and --hf-resume work with streaming now. Both were refused before, and the reason they had to be is a bug this release fixes: adapters could not be loaded into a streamed model at all. PyTorch's load_state_dict narrows keys by child name, so a canonically saved checkpoint matched 0 of N tensors, and PEFT reports missing keys as a warning rather than an error, which meant a resumed run silently reproduced the from-scratch loss curve exactly. The streaming layer now redirects canonical keys at load time, mirroring the save-side fix from v0.72.1. The fix is load-side only, so v0.72.0's forward-path bit-exactness results stand without re-running. One honest limit on this: end-to-end soup train --resume could not be demonstrated on the development box, because transformers refuses torch.load below torch 2.6 under CVE-2025-32434, and that 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. Finally there is a disk overflow tier, for a base too large even for RAM. stream_source: auto is the default and uses RAM when the base fits, falling back to an NVMe disk tier when it does not, holding nothing resident. stream_source: ram refuses instead of falling back, so a run that must stay in RAM cannot quietly become a disk run. Non-NVMe disks are refused outright, and soup doctor --disk reports the detected media type, taking about 9 seconds cold and about 2.4 seconds warm. Its correctness is verified bit-exact against the RAM tier. How much slower it is has NOT been measured on the development hardware, and no figure 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 roughly 5 effective TFLOPS the NVMe read hides under compute, which makes a number measured on this box misleading rather than merely incomplete. Three smaller fixes ride along. A guard meant to refuse non-NVMe media was wired to a hardcoded constant and could never fire. Streaming weight sources are now released when training ends or raises, which matters because the disk tier holds one open shard handle per decoder layer. Subprocess helpers resolve tools to absolute paths, because on Windows CreateProcess searches the current directory before PATH. And the [mcp] extra is now capped below 2.0: the SDK's 2.0.0 release removed create_connected_server_and_client_session and dropped Server.list_tools, which broke soup mcp serve's round-trip tests for anyone installing fresh. Known limitations, stated rather than hidden: loading into a streamed model works, but named_parameters() and state_dict() still disagree in memory, which is the deliberate cost of a serialisation-only design, and layer streaming remains BETA. Underneath, the v0.72.2 capability is unchanged and is still the headline: quantizing the streamed base to NF4 shrinks the RAM store about fourfold, and that is what brings 8B within reach of a card that cannot hold even a quarter of it. Measured on the development box, a 4 GB RTX 3050 Laptop, at batch 1, sequence length 512, gradient checkpointing on, 50 steps after 10 warm-up, with PagedAdamW8bit: Llama-3.1-8B-Instruct at 119.6 tok/s with peak VRAM of 3.32 GB, its base page-locked at a 3.60 GB RAM store and the GPU 100% busy, and Qwen2.5-3B at 264.2 tok/s in 1.76 GB. For scale, 1M training tokens is about 2.3 hours at 8B on that card, which is arithmetic from the measured rate rather than a separate measurement. Qwen2.5-3B also got faster than the bf16 streaming path, 264.2 against 143.1 tok/s, and the reason is not the arithmetic of smaller weights: a 1.43 GB store fits under that machine's page-locked memory ceiling where a 5.55 GB one did not, which restores asynchronous host-to-device copies and lifts GPU utilisation from 79.3% to 100%. The mechanism is the claim rather than the multiplier, because those two rows come from different sessions and this card's boost clock varies by about 13% between them. One number worth knowing before you size a run: the untied embeddings and LM head stay resident and unquantised, and they account for 2.10 GB of the 8B row's 3.32 GB, which is why 8B sits close to this card's ceiling. Correctness is not traded away. A streamed NF4 run is bit-exact against a resident NF4 run, the same quantised bytes through the same bitsandbytes kernels, and logit equality, non-zero gradients at layer 0 and a matching multi-step loss curve are all regression tests rather than one-off measurements. The base is quantised once, offline, and cached under ~/.soup/layer-stream/, keyed to the quantisation as well as the source checkpoint, so switching between none and 4bit, or retraining a base in place, re-shards instead of silently streaming the wrong bytes. The scope that remains is narrower than it was but still real: task must be one of sft, dpo, orpo, simpo and kto, backend transformers, text modality, plain LoRA, and quantization values other than none and 4bit are refused. Preference losses (DPO, ORPO, SimPO, KTO) landed in v0.72.4. GRPO and PPO remain explicitly not planned, because rollouts need generation and generation re-reads the model per token, which destroys the amortisation streaming depends on. v0.72.1 before all this was a correctness release that shipped alone: if you ran layer streaming on v0.72.0, the adapter that run wrote is inert outside the streaming path. The streaming wrapper held the real decoder layer as a child named inner, so every adapter tensor was saved under a key carrying an extra .inner. segment. Loading that file back into an ordinary model dropped every tensor, and because PEFT reports missing keys as a UserWarning rather than an error, soup merge, soup serve, soup chat and PeftModel.from_pretrained all silently returned the untuned base model. Nothing failed and nothing looked wrong. What was NOT affected is as important: the training itself was correct, the streamed run's numerics are unaffected, and v0.72.0's bit-exactness results still stand. Only the saved file was affected. If you have a v0.72.0 streamed adapter, re-run it; renaming keys cannot restore the file's association with its base model. You can check a file in one line: load adapter_model.safetensors and look for any key containing .inner. in it. Underneath everything the v0.72.0 mechanism is unchanged. The frozen base is never loaded resident. Soup rewrites the checkpoint into one safetensors shard per decoder layer, holds that store in CPU RAM (page-locked when the machine allows it) or on NVMe, and copies one layer at a time into a small pool of pre-allocated VRAM buffers on a dedicated CUDA stream, so the load of the next layer overlaps the compute of the current one. Only the LoRA adapters, their gradients and optimizer state stay resident. Peak VRAM is therefore bounded by the size of ONE layer plus the embeddings, the adapters and the activations, not by the size of the model. The honest cost is 1.43x slower than resident training, measured at 0.5B, which is the only apples-to-apples comparison available on that box because 1.5B and above cannot run resident there at all. If a model already fits on your card, do not enable streaming; it trades time for memory, and there is nothing to buy when memory is not the constraint. Turning it on is one config key, training.stream_layers: true, deliberately a config key rather than a CLI flag; training.stream_source (auto, ram or disk) and training.stream_buffers (2 to 8, default 2 for double buffering) tune it, and you still run plain soup train --config soup.yaml. The claims stop where the measurements stop: on the 4 GB card 8B is measured under NF4 and nothing above it is, so no figure taken there speaks for a larger model, and sizes from 14B to 72B were instead measured on borrowed server hardware, which is described separately below and carries its own limits. The bf16 3B row is a lower bound, because that box could not page-lock a 5.55 GB base and fell back to a pageable store, which is what the drop from about 97% to 79% GPU utilisation in that row actually measures. Soup performs that fallback automatically and prints what it costs instead of absorbing it silently. The numbers are Windows/WDDM and therefore systematically pessimistic versus Linux. On prior art the claim is deliberately narrow, because a first draft of it was fact-checked and cut: layer streaming on a small card is well established for inference (AirLLM streams 70B-class models through a 4 GB GPU, and its own documentation says layer sharding is not compatible with gradient propagation; Hugging Face's disk_offload is documented as big-model inference and runs under no_grad), and small-card fine-tuning has been published before, so nobody-has-done-this would be false. LSP-Offload (arXiv:2406.10181) already fine-tunes 1.3B on a 4 GB laptop GPU, but by compressing the optimisation into a learned sparse subspace rather than by streaming weights. The defensible statement is the measured one: up to 8B on a 4 GB card, by streaming the base rather than approximating the optimisation, with the forward pass verified bit-exact against a resident run at the same precision. One honesty note that carries over: Soup's telemetry primitives exist but are not wired to any command, so no usage data is ever sent today. Everything from the v0.71 line is still current underneath: soup ship's SHIP or DON'T-SHIP verdict with an emit-evidence loop and a committed ShipConfig, Reward Forge (soup reward synth and soup reward stress), the Data Moat II semantic data layer, the compliance pack, LISA, soup shrink, soup draft's honest speculative-decoding gate, Whisper ASR fine-tuning and the judge-in-the-loop suite. Totals as of v0.73.0: 17,344 tests across 347 test files, 142 ready-made recipes, 21 built-in templates, 23 training tasks, 19 data formats, 17 quantization formats, Apache-2.0, and Python 3.10 to 3.12 (v0.73.0 added the upper bound that was missing, because on 3.13 and above pip resolved untested PyTorch wheels that crash inside the native extension before any Soup code runs, leaving a user nothing to act on).

Question 2

Can Soup fine-tune and align a model that is bigger than my GPU's VRAM (layer streaming, v0.72.4)?

Accepted Answer

Yes. You can fine-tune Llama-3.1-8B on a 4 GB laptop GPU, measured at 119.6 tok/s with peak VRAM of 3.32 GB, and it ships BETA within a scope the release states precisely. Set 'training.stream_layers: true' in soup.yaml and the frozen base is never loaded resident. Soup rewrites the checkpoint once into one safetensors shard per decoder layer (cached under ~/.soup/layer-stream/, overridable with SOUP_LAYER_STREAM_CACHE_DIR and keyed to the quantisation as well as a fingerprint of the source checkpoint, so switching precision or retraining a base in place re-shards instead of silently streaming the wrong bytes), holds that store in CPU RAM page-locked when the machine allows it, and copies one layer at a time into a small pool of pre-allocated VRAM buffers on a dedicated CUDA stream, so the load of the next layer overlaps the compute of the current one. The base model is built on PyTorch's meta device, so only the embeddings, the final norm, an untied LM head and the LoRA adapters with their gradients and optimizer state ever occupy VRAM. Peak VRAM is therefore bounded by the size of one layer plus the embeddings, the adapters and the activations, not by the size of the model. Each layer is read twice per step, once in the forward pass and once when the backward pass recomputes it, because pushing gradient down to the layers below needs the weights, which is why streaming costs time rather than being free. Adding 'quantization: 4bit' quantises that streamed base to NF4 and shrinks the RAM store about fourfold, which is what brings 8B within reach of a card that cannot hold even a quarter of it. Measured on a 4 GB RTX 3050 Laptop at batch 1, sequence length 512, gradient checkpointing on, 50 steps after 10 warm-up: Llama-3.1-8B-Instruct at 119.6 tok/s in 3.32 GB with the base page-locked at a 3.60 GB store and the GPU 100% busy, and Qwen2.5-3B at 264.2 tok/s in 1.76 GB. On the bf16 path Qwen2.5-3B trains in 2.15 GB where a resident run runs out of memory. The honest cost is 1.43x slower than resident training, measured at 0.5B, the only apples-to-apples comparison available on that box. Correctness is not part of the trade: a streamed run is bit-exact against a resident run at the same precision, and logit equality, non-zero gradients at layer 0 and a matching multi-step loss curve are regression tests rather than one-off measurements. v0.72.3 widened it from a demonstration into something you can plan a run on. Nine model types stream, not three: llama, qwen2, qwen3, mistral, gemma, gemma2, gemma3_text, phi and phi3, each verified bit-exact against the same checkpoint loaded resident under both bf16 and NF4. Phi-3 fuses Q, K and V into a single qkv_proj, so there is no q_proj to substitute, and it is bit-exact anyway. Multimodal gemma3 is deliberately refused; only gemma3_text is accepted, because streaming a vision wrapper as a causal LM is exactly the failure an allowlist exists to prevent. There is no throughput measurement for any of the six newly supported families, so none is claimed. Batches above 1 and gradient accumulation both work now, and the release measured which one to reach for rather than reasoning about it. On Qwen2.5-0.5B in bf16 at sequence length 256 with a pinned store: batch 1 with no accumulation runs at 556.6 tok/s in 0.842 GB, batch 1 with accumulation 4 runs at 540.1 tok/s in 0.846 GB, and batch 4 with no accumulation runs at 1378.0 tok/s in 2.28 GB. At the same effective batch of 4, raising batch_size measured about 2.52x faster than accumulating, because a real batch amortises each layer load over more tokens while accumulation re-reads the entire base for every micro-batch, which is why the layer reads per 1000 tokens stay flat across accumulation 1, 2 and 4. Accumulation still earns its place: it holds peak VRAM almost exactly flat where a bigger batch does not. Raise batch_size while the budget allows, then accumulate. Because batches now scale, there is a pre-flight that accounts for them. Streaming bounds the weights, but activations and the logits tensor are untouched by it and both scale with batch times sequence length. On a 151,936-token vocabulary at batch 8 the logits tensor alone measured 8.71 GB, which is 146 times the entire layer-buffer pool of 0.060 GB. soup train now predicts peak VRAM before the run and refuses one that will not fit, naming training.batch_size and data.max_length as the two knobs that scale it linearly. The estimate was fitted against ten real runs across two models with a 3.1-fold vocabulary contrast, with a worst error of 0.85%, and it never under-predicts. It also corrected a real bug: the old estimator charged 6 bytes per logit element from first principles, where the measured peak is 14, because transformers holds the bf16 logits, the fp32 upcast, log-softmax's fp32 output and the fp32 gradient all at once. That under-predicted the largest term in the budget by 2.33x. This matters most on Windows, where WDDM does not raise on overcommit: a run that should have failed instead reached a 9.27 GB peak on a card with 4.29 GB, silently, by paging to host memory. The panel also prints a throughput forecast, quoted as a range from a GEMM ceiling measured on your own card in that session and printed next to the SM clock, never a compiled-in per-card constant. That is a response to a measurement: this one card produced 3.5 and 7.6 TFLOPS in two different sessions at the same reported clock, so a baked-in number would have been wrong about half the time. Real streamed runs land at 68 to 100% of their measured ceiling, which is why the line calls itself a bound and not a promise. The flags --resume and --hf-resume work with streaming now. They had to be refused before because adapters could not be loaded into a streamed model at all: PyTorch's load_state_dict narrows keys by child name, so a canonically saved checkpoint matched 0 of N tensors, and because PEFT reports missing keys as a warning rather than an error, a resumed run silently reproduced the from-scratch loss curve exactly. The streaming layer now redirects canonical keys at load time, mirroring the save-side fix from v0.72.1. The fix is load-side only, so v0.72.0's forward-path bit-exactness results stand without being re-run. One honest limit: end-to-end resume could not be demonstrated on the development box, for a reason that has nothing to do with streaming, since transformers refuses torch.load below torch 2.6 under CVE-2025-32434 and that blocks every resume there. The streaming-specific half, the adapter round-trip and loss continuity, is verified on the production CUDA path. Loading into a streamed model works, but named_parameters() and state_dict() still disagree in memory, which is the deliberate cost of a serialisation-only design. For a base too large even for RAM there is now a disk overflow tier. stream_source: auto is the default and uses RAM when the base fits, falling back to an NVMe disk tier when it does not, holding nothing resident. stream_source: ram insists and refuses rather than falling back, so a run that must stay in RAM cannot quietly become a disk run. Non-NVMe media is refused outright, including media Soup cannot identify, because the streamer reads every shard twice per step, which on a spinning disk is 160 seeks per step for an 80-layer model. soup doctor --disk reports what was detected (NVMe, SATA SSD, HDD or Unknown) and is opt-in because the probe costs about 9 seconds cold and about 2.4 seconds warm on Windows. The disk tier's correctness is verified bit-exact against the RAM tier. How much slower it is has not been measured on the development hardware and no figure is claimed for it, because safetensors memory-maps the shards so the OS page cache keeps them resident between steps on a machine with spare RAM, and at roughly 5 effective TFLOPS the NVMe read hides under compute, which would make a number measured there misleading rather than merely incomplete. v0.72.4 then opened the whole path to the preference losses. DPO, ORPO, SimPO and KTO run against a streamed base now, with the same config keys, so alignment stops being the step that forces you to rent a bigger card. The hard part was DPO's reference model, because the obvious implementation builds a second copy of the model and doubles the weights, which defeats the entire premise. Soup takes the reference from the same streamed base with its LoRA adapters switched off, so policy and reference are one set of weights, one RAM store and one buffer pool, and the adapter is the only difference between the two forward passes. That is measured rather than asserted, because a loss curve cannot detect its failure: if disabling the adapter were a silent no-op through the streamed path, every log-ratio would be zero and the loss would sit at 0.6931 forever, which reads as slow training rather than as a bug. On the reference box in bf16 with a 365.2M-parameter model, streamed DPO peaked at 81.87 MB against streamed supervised fine-tuning's 89.53 MB, which is 0.914x, with a byte-identical RAM store and buffer pool, while the same harness with a real second instance forced in reached 812.32 MB, moving the peak by 730.44 MB against 730.44 MB of weights, exactly one copy. A zero-adapter control measured a policy-versus-reference gap of exactly zero, proving the gap in the real run comes from the adapter. Read the 0.914x as no second copy rather than as a saving: it sits below 1 because that fixture splits its 64 positions into a 32-token prompt and a 32-token completion, so the logits tensor is smaller, and the model is synthetic rather than a real checkpoint. All four losses are bit-exact against a resident run of the same loss, difference exactly 0.0, and a live soup train on SmolLM2-135M under NF4 moved every one of them, saving ordinary LoRA adapters that load into a non-streaming model. The reference is free in memory, not in time: DPO walks the layer stack 1.52x as often per step as supervised fine-tuning does, because it adds a reference forward to the policy forward and the gradient-checkpoint recompute. KTO is not reference-free however it is usually described, since it selects its reference exactly the way DPO does; ORPO and SimPO genuinely are. KTO also requires a batch size of 2 or more, because TRL's KL term is degenerate at batch 1, and Soup refuses that when the config is read rather than minutes into a run after the checkpoint has been sharded. No throughput figure is claimed for any preference loss at any size, because none was measured. And the VRAM pre-flight is a sound upper bound for these losses but a loose one, charging the supervised loss's 14 bytes per logit element over twice the rows where TRL reduces preference logits to per-token log-probabilities instead, so on a 4 GB card with a 128k-vocabulary 1B model DPO is allowed at max_length 512 and refused from 768 up even though it would probably fit. That looseness shipped deliberately, because under-predicting is the strictly worse failure on a platform where an overcommit spills silently into host memory instead of raising. What is still out of scope: task must be one of sft, dpo, orpo, simpo and kto, with ipo, bco and the unified task preference dispatcher still refused; backend transformers; text modality; plain LoRA, since DoRA, VeRA and the PiSSA, OLoRA and LoftQ initialisations all read a real base weight that streaming keeps on the meta device; and quantization values other than none and 4bit. A batch_size of auto is refused because the auto-batch probe sizes a resident model, which a streaming run never loads. GRPO and PPO are permanently excluded rather than pending, and their refusal deliberately names no release, because rollouts need generation and generation re-reads the model per token, which destroys the amortisation streaming depends on. Nothing above 8B has been measured on the 4 GB card, so no figure quoted for it speaks for a larger model; sizes from 14B to 72B were later measured on a borrowed 8x H100 box, where the streamed forward is exact against a real resident reference throughout and the exercise found a gradient defect in NF4 above roughly 165 MB per decoder layer, affecting 32B and larger, which is repaired in v0.73.0 and gated at both affected sizes. The numbers are Windows and WDDM and therefore systematically pessimistic versus Linux. On prior art the claim is deliberately narrow, because a first draft of it was fact-checked and cut. Layer streaming on a small card is well established for inference: AirLLM streams 70B-class models through a 4 GB GPU and its own documentation says layer sharding is not compatible with gradient propagation, and Hugging Face's disk_offload is documented as big-model inference and runs under no_grad. Small-card fine-tuning has been published too: LSP-Offload (arXiv:2406.10181) fine-tunes 1.3B on a 4 GB laptop GPU by compressing the optimisation into a learned sparse subspace rather than by streaming weights. So nobody-has-done-this would be false. The defensible statement is the measured one: up to 8B on a 4 GB card, by streaming the base rather than approximating the optimisation, with the forward pass verified bit-exact against a resident run at the same precision. If the model already fits resident on your card, do not enable streaming. It trades time for memory, and there is nothing to buy when memory is not the constraint.

Question 3

Has layer streaming been verified on hardware other than the maintainer's laptop?

Accepted Answer

Yes, on an 8x H100 80 GB box borrowed for three days in August 2026, and the record is published in full at the repository's benchmarks directory. The reason it mattered is specific. Layer streaming's central claim is that a streamed run computes the same thing an ordinary run computes, and checking that needs a resident reference: the same checkpoint at the same precision, loaded the normal way, so the two can be compared tensor by tensor. On a 4 GB card that reference cannot exist for any model worth streaming, so every published correctness check had run against 3-layer models built from a config, with a hidden size of 32 and an NF4 layer of 0.01 MB. The preprint states this in its own limitations and names it as the most useful experiment missing from the work. Four results came back. First, the streamed forward pass is bit-exact against a matched resident reference, logits compared with torch.equal, at 0.5B, 8B, 14B, 32B and 72B, on real checkpoints rather than fixtures. Read that carefully, because bit-exactness is two independent claims and not one: the forward and the backward are measured separately, and above roughly 165 MB per NF4 layer they disagreed. Second, peak VRAM is flat in model size, which is the entire point of the feature: 3,397 MB at 8B, 4,475 MB at 14B and 4,845 MB at 32B while the model itself grows fourfold, and 7,411 MB at 72B. Third, the published laptop headline reproduces on completely different hardware, a different operating system and a much newer software stack: 119.6 tok/s in 3.32 GB on the RTX 3050 against a median 113.00 tok/s in the same 3.32 GB peak on an H100. The server card is if anything slightly slower, and mean GPU utilisation was 54.1%, which is direct evidence that the method is bound by host-to-device transfer rather than by the GPU, and therefore that a faster card is not the upgrade that helps a streamed run. Fourth, a streamed model converges indistinguishably from a resident one: five paired runs on disjoint training subsets, scored by Soup's own soup ship against a fixed 300-item held-out set, gave a mean paired difference of 0.0053, roughly 1.6 items out of 300, against a within-arm spread several times larger, and the general-capability leg pointed against the convenient direction with 3 of 5 resident runs coming back DON'T SHIP against 1 of 5 streamed. That is 'no difference is detectable at this resolution', not 'there is no difference'. The exercise also found a defect, which is the honest headline. In NF4, above a boundary bracketed between 163.8 and 171.5 MB per decoder layer, the backward pass produced silently wrong gradients on every layer but the last few, while the forward stayed bit-exact and the loss matched a resident reference to every digit and the run exited 0. That affects 32B and 72B; 8B sits at 105 MB per layer and 14B at 132, both below the boundary with margin and both verified exact over a 50-consecutive-backward soak, so nothing this project has published is above it. The cause is buffer aliasing rather than a race, which was established by measurement: a full cuda.synchronize() does not fix it and de-aliasing does. bitsandbytes keeps the packed 4-bit weight and its quantisation state on the autograd context as ordinary attributes instead of using save_for_backward, so gradient checkpointing cannot recompute them, and the reference captured during the forward aliases a streaming buffer that has been refilled with another layer by the time the backward reads it. bf16 was never affected, at 3.9 times the bytes per layer, because it goes through a native operation that does use save_for_backward. The obvious repair, giving every pooled tensor a private copy, was measured and rejected: it costs only about 6% of throughput but takes peak VRAM from 4,220 MB to 19,720 MB on a real 32B, which is approximately the whole model, and a repair that is proportional to the model rather than to one layer deletes the reason the feature exists. The shipped repair keeps streamed NF4 weights out of that code path entirely and is gated at 32B and 72B against a control that reproduced the defect in the same process, at 256 of 256 and 320 of 320 gradient tensors exact over five repetitions each, costing about 3% of peak VRAM and 4% of throughput. It shipped in v0.73.0, so v0.72.0 through v0.72.4 carry the defect at those sizes and anyone who streamed a 32B or larger model in NF4 on one of those should re-run it. The upstream half is filed as bitsandbytes issue 2034 and remains open. One comparison came out of the same session: against DeepSpeed ZeRO-3 with CPU parameter offload, at matched numerics on a single card, layer streaming is 2.93x the throughput in 9.7x less peak VRAM. The right reading is not that streaming beats DeepSpeed, and the record says so explicitly. ZeRO-3 shards across ranks and had no partner to shard to, so it was used outside its intended regime; that regime happens to be layer streaming's home ground. On eight cards ZeRO-3 reached 1,831.7 tok/s using 34 GB on each of eight cards, against 1,077.1 tok/s and 2.9 GB for streaming on one, while one card training the model resident beat all of them at 2,645.4 tok/s. If the model fits on your card, use it resident and skip every clever technique here.

Question 4

Can I run DPO on a GPU that cannot hold the model (preference losses over layer streaming, v0.72.4)?

Accepted Answer

Yes, since Soup CLI v0.72.4. Set 'training.stream_layers: true' and 'task: dpo' in the same soup.yaml, and the frozen base never enters VRAM while DPO trains against it. ORPO, SimPO and KTO work the same way. Before v0.72.4 streaming meant supervised fine-tuning only: task had to be sft, and all four preference losses were refused when the config was read. The accepted list is now exactly five values, sft, dpo, orpo, simpo and kto. Note that ipo, bco and the unified 'task: preference' dispatcher are not in it, so name the loss in task directly, and that grpo and ppo are excluded permanently rather than pending a release, because generation rollouts re-read every layer once per generated token and destroy the amortisation streaming exists to buy. The interesting part is DPO's reference model. DPO scores the policy against a frozen reference, and the obvious implementation constructs a second copy of the model, which doubles the weights on a card that could not hold them once. Soup instead takes the reference from the same streamed base with its LoRA adapters switched off, so policy and reference share one set of weights, one CPU RAM store and one pool of VRAM buffers, and the adapter is the only difference between the two forward passes. The reference therefore costs no extra weights at all. That was measured with a control rather than asserted, because a passing loss curve cannot detect the failure mode: the streamed layer substitutes base weights through functional_call rather than through the module's own forward, so disabling the adapter being a silent no-op is entirely plausible, and if it were, the reference would be the policy, every log-ratio would be zero and the loss would sit at 0.6931 forever, which reads as slow training. Measured on a 4 GB RTX 3050 Laptop in bf16 with a 365.2M-parameter model, 24 decoder layers, vocabulary 260, sequence length 64 and batch 1: streamed supervised fine-tuning peaked at 89.53 MB, streamed DPO at 81.87 MB (0.914x) with a byte-identical 729.91 MB RAM store and 60.83 MB buffer pool, and the control that forced a real second instance at 812.32 MB, which moved the peak by 730.44 MB against 730.44 MB of weights, exactly one copy. A zero-adapter control measured a policy-versus-reference gap of exactly zero, proving the gap in the real run comes from the adapter and not from some other difference between the two passes. Read the 0.914x as evidence of no second copy, not as a saving: DPO is not cheaper than supervised fine-tuning in general, and that row sits below 1.0 only because the fixture splits its 64 positions into a 32-token prompt and a 32-token completion, so its logits tensor is smaller. The numbers come from a synthetic model, not from a real checkpoint and not from Llama-3.1-8B. Correctness: all four losses are bit-exact against a resident run of the same loss, with a difference of exactly 0.0, and DPO's arm ran in float32 on CPU precisely so bit-exact means literally zero rather than bf16 noise. End to end through the released CLI, streaming SmolLM2-135M under NF4, dpo moved 0.6931 to 0.6695, orpo 5.3816 to 5.0559, simpo 5.2033 to 4.8749 and kto 0.5000 to 0.4904, and all four saved ordinary LoRA adapters that load into a non-streaming model. Two things to know before you configure it. First, the reference is free in memory but not in time: DPO walks the layer stack 1.52x as often per step as supervised fine-tuning does, because it adds a reference forward on top of the policy forward and the gradient-checkpoint recompute. Second, KTO is not reference-free however it is usually described, since it picks its reference exactly the way DPO does and gets the same treatment, while ORPO and SimPO genuinely never construct one; KTO additionally requires a batch size of 2 or more, because TRL's KL term is degenerate at batch 1, and Soup refuses that when the config is read rather than minutes into a run after the checkpoint has been sharded. Two honest limits. No throughput figure is claimed for any preference loss at any model size, because none was measured. And the VRAM pre-flight is a sound upper bound for these losses but a loose one: it charges the supervised loss's 14 bytes per logit element over twice the rows, while TRL reduces preference logits to per-token log-probabilities with selective_log_softmax instead of holding a full-vocabulary fp32 upcast, so DPO's entire above-resident cost measured 51.76 MB where the charge for the same shape is roughly 458 MB. In practice, on a 4 GB card with a 128k-vocabulary 1B model, DPO is allowed at max_length 512 and refused from 768 up even though it would probably fit; lower data.max_length if the pre-flight refuses a run you believe fits. That conservatism shipped deliberately, because under-predicting is the strictly worse failure: on Windows an overcommit is not an exception you can catch, since WDDM silently spills into shared host memory and the run completes an order of magnitude slower with no error at all, which means a run completing is not evidence that its configuration fits. The measurement record behind all of this is published in full, including the checks that failed and the figures that were measured and then discarded, in the repository's benchmarks directory, and the layer-streaming work has a preprint under DOI 10.5281/zenodo.21771064.

Question 5

What are 'soup reward synth' and 'soup reward stress' in Soup CLI v0.71.40 and v0.71.41?

Accepted Answer

They are a matched pair (v0.71.40 and v0.71.41) that turns Soup's reward-hacking detector on the reward verifier itself, the thing an RL run trusts most and inspects least. 'soup reward synth -o reward.py' auto-generates a deterministic reward verifier from your own gold outputs: it infers one of four families, auto-detected or forced with --kind, and each is grounded in the golds. 'numeric' extracts the last number, a \boxed{} span or a #### answer and compares exactly or within --tolerance; 'json_schema' induces keys, types and required fields; 'regex' builds positional character classes over equal-length golds; 'tool_call' binds each tool's required and allowed arguments. The emitted .py is self-contained, readable and committable, and it rides the existing load_reward_fn .py path so it adds no new trusted-execution surface: you read, edit, diff and commit it. The moat is a mandatory calibration report: the synthesized verifier is loaded back and run against its own references (it must accept at least 90%) and against auto-generated bad answers (it must reject them), and a degenerate always-accept verifier is refused with exit 2, never silently emitted. '--plan-only' reports the induced spec without writing and '--output-report' persists the calibration JSON. 'soup reward stress --references golds.jsonl' (v0.71.41) is the adversarial half: where synth proves a verifier separates references from friendly perturbations, stress asks the question a reward-hacking model asks at train time, does the verifier pay out for degenerate junk? It feeds empty, length-padded, repetition and sentinel-spam completions ('--attacks empty,length,repetition,sentinel', '--sentinel GOLD') scored against the real gold, so a numeric, tool_call or json_schema verifier still gets a valid target and must reject the garbage, and it reports a per-attack accept-rate table plus an overall gameability verdict tuned by '--max-gameable' and '--threshold'. It probes a synthesized .py and a builtin (accuracy, format, verifiable) through the same loader, and it is pure and offline: exit 0 for robust, 2 for gameable, 1 for error. A gold-requiring verifier probed with no --references is a hard error naming the flag, never a false 'robust'. v0.71.40 also made a comma-separated 'training.reward_fn: "accuracy,format"' actually train, resolving it to a reward ensemble (a GRPOTrainer with a list of reward_funcs) which also unlocks the rm_ensemble reward-hack detector, and it fixed a recipe that shipped exactly that form and previously crashed. Nothing in TRL, Unsloth, Axolotl or OpenRLHF synthesizes a reward or tests one for gameability.

Question 6

How does 'soup ship' decide SHIP or DON'T SHIP, and can I commit the evidence (v0.71.38, v0.71.39)?

Accepted Answer

'soup ship' answers one question after a fine-tune, did the model get better or did I break it, as a single binary SHIP or DON'T-SHIP with a one-screen reason. It fuses two legs: leg 1 is that the task metric strictly improved (an eval accuracy, an LLM-judge score, or a swap-debiased pairwise judge win-rate against a 0.5 base), and leg 2 is that no general benchmark regressed past a forgetting threshold (default 0.05 absolute points), so a model that wins the task but breaks general knowledge is refused. v0.71.38 gave leg 2 real teeth. It used to be fifteen trivia prompts scored by case-insensitive substring containment, which credited 'B' for Berlin and '3' for 13 and had zero coverage of tool-calling, JSON validity or safety; it is now an answer-extraction plus boundary-aware scorer over a bundled, offline general suite of seven hand-authored benchmarks shipped in the wheel (mini_mmlu, mini_common_sense, mini_instruction, a new mini_arithmetic, plus mini_tool_call for function calling, mini_format_json for JSON validity and mini_safety for refusal rate), each roughly forty items or fewer (24 to 40) so a single wrong answer trips the default threshold instead of being rounded away, all scored offline with no lm-eval and no download. Usage errors moved to exit 3 so exit 2 now means only DON'T-SHIP. v0.71.39 closed the evidence loop: 'soup ship --emit-evidence <path>' re-serializes the verdict back into the --evidence input schema so a run's output replays as input; a ShipConfig block under eval.ship in soup.yaml plus 'soup ship --config soup.yaml' lets you commit the gate policy with CLI over config over default precedence; and 'soup ship --push owner/repo#N' posts the verdict as a GitHub PR comment as a best-effort step that never flips the exit code. Emitting evidence stamps a provenance block with an order-insensitive config hash, the base model and a best-effort data hash, and reading evidence back with --config refuses (exit 3) evidence whose config drifted from the committed recipe, while excluding the gate policy from the hash so tuning the threshold never falsely invalidates evidence. 'soup ci init --config soup.yaml' binds the generated PR gate to that committed config. That is CI for weights, not prompts: a provenance-bound SHIP gate that renders on every pull request. One honesty note: Soup's telemetry primitives exist but are not wired to any command, so no usage data is ever sent today.

Question 7

What is 'Data Moat II' in Soup CLI v0.71.36 (semantic dedup, topics, canary, replay)?

Accepted Answer

Data Moat II (v0.71.36) puts a semantic layer over your training data and adds two tools for what a fine-tune forgets and leaks, with zero new dependencies (it reuses transformers from the [train] extra, a mean-pooled all-MiniLM-L6-v2, so no sentence-transformers). 'soup data dedup --semantic -o clean.jsonl' removes near-duplicates over embedding cosine instead of MinHash shingling, catching reworded duplicates MinHash scores as distinct (measured 0.88 to 0.91 cosine on rewordings) while keeping genuinely-distinct-but-similar instructions; flags are --threshold (default 0.8), --field and --embed-model. The honest known limitation ships with it: it is not a paraphrase detector, because measured paraphrase cosines (0.49 to 0.76) overlap with genuinely distinct rows (for example 'Add two numbers' vs 'Multiply two numbers' scores 0.759, higher than the true paraphrase 'reverse a string' / 'invert the order of characters' at 0.491), so no threshold separates them and lowering --threshold to chase paraphrases deletes real training rows; the default 0.8 is deliberately conservative. 'soup data topics <data>' clusters the dataset with k-means over the same embeddings, labels each cluster with c-TF-IDF terms, and prints a coverage table (for example '82% code, 6% math') plus a warning for thin topics; the labels are emergent term clusters, not classification against a fixed taxonomy, and there is no automatic join to an eval-coverage suite. 'soup data canary insert train.jsonl -o canaried.jsonl --count 16 --manifest secrets.json' plants K high-entropy secrets, and after training 'soup data canary check --manifest secrets.json --base ./model --adapter ./lora' ranks each secret's loss against never-inserted controls drawn from the same space (a Secret-Sharer memorization probe); the verdict is a binomial-tail test at alpha 0.05 over the count of memorized canaries, with exit 2 on MAJOR so CI can gate a leak. That count-based verdict replaced an 'any single canary in the bottom 1%' rule that fired MAJOR on a clean model about 15% of the time at K=16 (a CI gate crying wolf one run in seven); the fix dropped the false-MAJOR rate to about 1.2%. 'No exposure' is the sampled-control approximation, not full-space rank enumeration, and the manifest is written 0600 on POSIX. 'soup train --config new_task.yaml --replay old_task.jsonl --replay-ratio 0.1' is continual-learning rehearsal: it interleaves a seeded sample of an old dataset into training so a new task does not erase the old one, where the ratio is the fraction of the final mixed set, rows are interleaved rather than appended, an undersized pool reports the shortfall instead of repeating rows, and validation stays pure new-task; replay v1 is sft/pretrain only and is incompatible with packing/multipack, and on SmolLM2-135M + LoRA it retained the old task 7% better than a no-replay control, the correct direction, but forgetting without it was only about +4%, so the effect size at full fine-tuning or 7B+ is proof-of-mechanism, not yet demonstrated at scale. Data Moat II also fixed the hardware-fit gate, which had refused to train any locally-merged model because the size guesser returned its 7B default for a name with no size marker; local checkpoints are now measured from their safetensors header. The follow-up patch v0.71.37 made every 'pip install soup-cli[extra]' hint use double quotes so it works on Windows cmd.exe, and fixed eval-gate benchmark tasks.

Question 8

How do I fine-tune a model for HIPAA, SOC 2, the EU AI Act or SR 11-7 with Soup CLI?

Accepted Answer

The v0.71.35 compliance pack covers it end to end. Start with 'soup init --template hipaa|soc2|eu-ai-act|sr-11-7'. Be clear on what a template is, because the honest constraint shaped the design: Soup's compliance controls are CLI flags and commands, not config keys (audit_log, bom, attest, repro_receipt, annex_xi, track_energy, pii and decontaminate have zero matches in the config schema), so a template cannot 'pre-wire audit-log on' as YAML. Each one is instead a valid, immediately trainable config on a license-clean Apache-2.0 base, plus header comments naming that regime's exact commands: PHI scrubbing and air-gap for HIPAA, BOM/attest/sign for SOC 2, Annex XI plus energy tracking for the EU AI Act, repro-receipt plus diagnose and ship for SR 11-7. Built-in templates went from 17 to 21. The common path is then: 'soup data pii' and 'soup data decontaminate' to clean the data; 'soup train --repro-receipt receipt.json' (adding '--annex-xi annex_xi.md --track-energy --energy-country DEU --energy-out energy.json' for the EU AI Act); 'soup registry push'; 'soup bom emit --format both' for CycloneDX plus SPDX and 'soup attest emit --sign ed25519' for in-toto plus SLSA-3; 'soup adapters scan/sign/verify'; 'soup airgap-bundle' if you need to cross an air gap; then 'soup card <registry-id> -o MODELCARD.md' to publish. The audit log records every command automatically ('soup audit-log tail'). Finally 'soup ci init' writes .github/workflows/soup-gate.yml, a pull-request gate chaining 'soup data validate', then 'soup expect', then 'soup ship --evidence', where exit 2 blocks the merge.

Question 9

What is 'soup card' and 'soup ci init' in Soup CLI v0.71.35?

Accepted Answer

'soup card -o MODELCARD.md' (v0.71.35) turns a Local Model Registry entry into a publishable, provenance-carrying Hugging Face model card: base model, the real training config, an eval scorecard joined from the tracker, config and data sha256 hashes, lineage (ancestors), and a table of every registered artifact. Adapter versus full model is inferred from the registered artifacts and falls back to the training config's LoRA rank, with Spectrum ('unfrozen_parameters') and LISA ('lisa_enabled') full fine-tunes correctly treated as dense, so the card sets the right 'library_name' and never misreports the model type. That detail was found by a live smoke, not by tests: a real LoRA run with no attached artifacts rendered 'Type | Full model' and 'library_name: transformers', a false claim in a provenance document that 90 green tests had missed. 'soup push --model ./out --repo you/m --card ' renders the same card and uploads it as README.md, overriding the auto-generated one; a bad ref fails fast before any network call and it is Hugging Face only (it warns and ignores on other hubs). 'soup ci init [--data d.jsonl --suite s.yaml --evidence ev.json] [--branch main --python 3.11] [--force]' writes .github/workflows/soup-gate.yml, a fine-tuning CI gate that runs 'soup data validate' for dataset format compliance, then 'soup expect' for PII, token-length, refusal and judge expectations, then 'soup ship --evidence', where exit 2 blocks the merge. Every interpolated path is validated to stay under the repo root and shell-quoted (a '; rm -rf /' in a path is quoted as one token), the branch and Python version are regex-gated so they cannot break out of their YAML context, and the write is atomic, symlink-rejecting, and refuses to clobber an existing workflow without --force.

Question 10

What is 'soup draft', and does training a speculative-decoding draft actually make serving faster?

Accepted Answer

'soup draft' (v0.71.33) trains and, above all, MEASURES a speculative-decoding draft, and the honest answer to whether it makes serving faster is: measure it, because on the pair we validated it did not. 'soup draft measure --target --draft --prompts p.jsonl' reports a draft's acceptance rate (the fraction of the target's own greedy tokens the draft would have proposed correctly, teacher-forced argmax agreement, the metric the Medusa and EAGLE papers report) plus real plain-versus-assisted throughput measured on your box; roughly 70% and up is where speculative decoding starts paying for the draft's forward pass, and '--min-acceptance 0.6' exits 2 below the floor so CI can gate on it (exit 0 = ok, 2 = below floor, 1 = error). 'soup draft distill --target --draft-base --data d.jsonl -o draft/' distils your target into a tiny base via logit KD through the existing 'task: distill' trainer and emits a dense model, because a PEFT adapter directory cannot be loaded as an assistant_model; flags include --steps, --device, --force and --plan-only. 'soup draft list' shows local drafts, and a registry at ~/.soup/drafts.json is consulted by 'soup serve --auto-spec' BEFORE the built-in pairing table, so a draft you trained yourself is picked up automatically. Draft and target must share a tokenizer and a mismatch is refused up front, because speculative decoding proposes draft token ids into the target's vocabulary and a mismatched pair silently produces garbage rather than failing. The measured result, which is the feature: on SmolLM2-360M-Instruct with a SmolLM2-135M-Instruct draft, the stock draft already scored 69.3% acceptance and distilling it moved that to 69.7% after 2 epochs and back to 69.3% after 10, no gain beyond noise, because a small same-family draft is already near its capacity ceiling for agreeing with the target and logit KD cannot buy capacity it does not have; assisted decoding measured 0.55 to 0.64x, a net slowdown, since the draft's forward pass costs more than the tokens it saves at that size. The 'faster serving' pitch was therefore withdrawn rather than shipped, and 'soup draft measure' is what tells you so before you ship. Whether distillation pays off on a larger or genuinely diverged pair is unproven on a 4 GB box; cross-tokenizer drafts are deferred.

Question 11

What is 'soup adapters arithmetic' (LoRA task arithmetic) and LISA in Soup CLI v0.71.34?

Accepted Answer

'soup adapters arithmetic "coder + 0.5*math - toxic" --adapter coder=./coder-lora --adapter math=./math-lora --adapter toxic=./toxic-lora -o ./blended' (v0.71.34) applies task arithmetic (arXiv:2212.04089) to LoRA deltas: add to blend two skills, scale to dial one down, and, the differentiator, negate to subtract one. The output is a single loadable adapter (exit 0 = ok, 1 = refusal). The coefficient math is the point: a LoRA does not store its delta directly but two factors whose product is the effective weight change (delta W = B @ A), so scaling both factors by c scales the delta by c squared, which would make '- toxic' square to +1 and become a no-op instead of a removal. Soup splits the coefficient as the square root of its absolute value across the two factors and carries the sign, so the delta scales linearly (verified live on two real rank-8 adapters: the ratio of the norms for 2*a versus a is exactly 2.000). That exactness holds on the self (diagonal) term, so scaling or negating a single adapter is exact, while a multi-adapter sum also carries cross-terms this element-wise combine does not cancel; and the mechanism is what is proven (the delta really negates), not the behavioural outcome, since whether subtracting a toxicity adapter measurably reduces toxicity on a real safety eval is not yet benchmarked. Guards: a different base model is refused unless --allow-cross-base, a FAIL-scanned input is refused by the backdoor-scan gate unless --allow-unscanned, and paths are cwd-contained and symlink-rejecting. The expression parser is hand-written with no eval, so an adapter name can never become code. v0.72.0 removed the one real limitation: mixed ranks used to be refused with a 'harmonize rank' message, and they are now handled exactly. Stacking the A factors and the scaled B factors of the inputs produces a combined adapter whose delta reproduces the sum of the individual deltas by construction, with no approximation, and the new '--rank N' flag then truncates that result with an SVD when you want a fixed output rank rather than the concatenated one. Ranks are no longer a reason to refuse; genuinely incompatible layer shapes still are.

Question 12

What is LISA in Soup CLI (v0.71.34)?

Accepted Answer

LISA (Layerwise Importance Sampled AdamW, arXiv:2403.17919) is the other half of v0.71.34 and reaches for full-fine-tuning quality without a full fine-tune's memory: where Spectrum picks the layers once, LISA re-samples a small random set of decoder layers every N steps and freezes the rest, with the input embeddings, LM head and final norm always trainable. Because only a handful of layers train at any moment and their optimizer state is cleared when re-frozen, peak optimizer memory is roughly embeddings + head + lisa_num_layers, while every layer still gets updated over the run. Read that arithmetic carefully, because it is true and it is not a saving over LoRA: measured on an H100 at 3B and 8B, LISA beats full fine-tuning on held-out loss at both learning rates, and it costs 1.22x LoRA's memory at 3B and 1.51x at 8B, with the gap widening because the embeddings, the LM head and the final norm stay trainable through every interval and are 70.7% of everything LISA trains at 8B. Stated positively: LISA trains an 8B on one 80 GB card where full fine-tuning needs roughly 120 GB and cannot run at all. Enable it with 'training.lisa_enabled: true' plus 'lisa_num_layers', 'lisa_interval_steps' and 'lisa_reset_optimizer' on a task: sft, transformers, text, quantization: none run; it is mutually exclusive with LoRA features, freeze_layers/freeze_ratio and Spectrum's unfrozen_parameters, since each independently decides what trains. Live on a 4 GB GPU for small models.

Question 13

Does 'soup export --format gguf' work on Windows?

Accepted Answer

Yes, as of v0.71.35, and it was validated end to end on Windows for the first time: llama.cpp built CPU-only with VS2022 BuildTools and cmake, SmolLM2-135M exported to q4_0 (92 MB), q4_k_m (105 MB), q8_0 (145 MB) and f16 (271 MB), then 'soup deploy ollama', then live inference. Doing that validation surfaced four real bugs, each of which independently broke the path, and which 361 green export and ollama tests had not caught. First, 'soup export --format gguf' cloned llama.cpp into your current directory: SOUP_DIR is the bare name '.soup' but the lookup used it relatively instead of anchoring to the home directory like the rest of the codebase, so the canonical ~/.soup/llama.cpp was never found and a fresh ~200 MB checkout was dropped into whatever directory you ran from. Second, and worst, the first GGUF export downgraded your PyTorch and broke CUDA: the auto-clone ran 'pip install -r <llama.cpp>/requirements.txt' into your interpreter, and llama.cpp pins torch~=2.2.1 against the CPU wheel index, so torch 2.5.1+cu became 2.2.2+cpu and transformers 4.57 became 4.46, meaning a user's first GGUF export silently destroyed their training setup; Soup now installs only the convert script's extra dependencies (gguf, sentencepiece, protobuf), unpinned, never touching torch, and non-fatally. Third, a correctly built llama.cpp was 'not found' on Windows because MSVC, like Xcode, is a multi-config generator and emits build/bin/Release/llama-quantize.exe, while only the flat single-config layout was searched. Fourth, 'soup deploy ollama' failed on a relative GGUF path with 'pull model manifest: file does not exist', because Ollama resolves FROM against the Modelfile's directory and Soup writes the Modelfile to a temp dir; the Modelfile now emits an absolute path. This closes the CPU-validatable half of the long-standing GGUF-on-Windows issue; the CUDA plus AWQ/GPTQ half remains open.

Question 14

Can Soup CLI fine-tune Whisper (ASR / speech-to-text) models?

Accepted Answer

Yes. As of v0.71.32, 'soup train' with 'task: asr' fine-tunes OpenAI Whisper speech-recognition models on your own audio, locally. Data is plain JSONL rows of {"audio": "clip.wav", "text": "the transcript"} with 'data.format: asr' and a containment-checked 'data.audio_dir'; the trainer wraps Hugging Face Seq2SeqTrainer + WhisperProcessor (clips become 16 kHz mono log-mel input features, transcripts become the decoder labels). 'training.asr_lora: true' trains LoRA on the q/v projections instead of a full fine-tune, so whisper-tiny (39M) and whisper-base (74M) train on a 4 GB GPU; 'training.asr_language' and 'training.asr_task' (transcribe or translate) pin the decoder prefix and persist to an 'asr_generation.json' sidecar that inference restores automatically. 'soup infer --task asr --model <whisper-or-adapter> --input eval.jsonl --output preds.jsonl' transcribes a JSONL of clips and, when references are present, reports per-row and corpus WER/CER via a pure-Python metrics module with no new dependency; word accuracy (1 - WER) plugs into 'soup ship' as a higher-is-better task metric. Recipes: 'whisper-tiny-asr' and 'whisper-base-asr' (live-validated on a 4 GB RTX 3050: WER 1.000 to 0.000 on a memorization smoke at 0.4 of 4 GB) plus 'whisper-large-v3-asr' (parse-tested, needs 16 GB+). Audio decodes only through a hardened loader (soundfile pre-probe, symlink rejection, O_NOFOLLOW, byte caps); a non-Whisper base or an mlx/unsloth backend is rejected with a friendly error before any download.

Question 15

What is the judge-in-the-loop suite in Soup CLI v0.71.31 (Online DPO, best-of-N, Evol-Instruct, soup ship pairwise)?

Accepted Answer

The judge-in-the-loop suite (v0.71.31) puts an LLM judge in the loop across the whole post-training workflow as four integrated commands sharing one swap-debiased pairwise-judge core, and no competitor (Unsloth, Axolotl, LLaMA-Factory, OpenPipe) ships it as an integrated CLI suite. 'soup train with task: online_dpo' trains on-policy against a judge: each step samples two completions per prompt and a pairwise judge (or a reward model) names the winner 'chosen' and the loser 'rejected', wrapping TRL's OnlineDPOTrainer (config online_dpo_judge or reward_model, exactly one of the two; online_dpo_loss_type sigmoid or ipo; online_dpo_max_new_tokens; beta reuses dpo_beta; transformers and text only). 'soup data best-of-n --base --prompts p.jsonl --n 8 --judge -o sft.jsonl [--emit-pairs dpo.jsonl]' is best-of-N rejection sampling (BOND-lite): sample N completions locally, a judge scores each one pointwise, the winner becomes an SFT row with provenance and, with --emit-pairs, winner-versus-loser DPO pairs. 'soup data evolve --input seeds.jsonl --provider ollama|vllm --model --strategy depth|breadth --rounds N -o out.jsonl' is Evol-Instruct (WizardLM) instruction evolution that grows instruction diversity, completing the synthetic-data suite (Magpie, Forge, Persona, evolve). And 'soup ship --task-mode pairwise --judge-model ' adds a third task-win mode to the SHIP or DON'T-SHIP verdict: a true pairwise judge win-rate where the judge picks base versus tuned per prompt (swap-debiased, a win counts only when the (A,B) and (B,A) orders agree), the base is a 0.5 coin-flip and the tuned model wins only if its win-rate exceeds 0.5, fused with the catastrophic-forgetting gate and CI exit codes (0 = SHIP, 2 = DON'T SHIP, 1 = error). It is honest about scale: the training claim is proof-of-mechanism only, validated on SmolLM2-135M with a synthetic length-preferring judge on CPU, not a production RLHF claim (community scale ask tracked in issue #286). Because CI resolves trl 1.x, a runtime trl-version adapter uses the swap-debiased pairwise judge on trl 0.19.x and the same judge as a pointwise reward function on trl 1.x, a documented per-version behaviour difference. Judge and provider URLs are SSRF-validated, dataset paths are cwd-contained with symlink rejection and atomic writes, and untrusted model code defaults to trust_remote_code off. It adds the online-dpo-smollm2-135m recipe.

Question 16

What is PRM-guided GRPO in Soup CLI v0.71.30?

Accepted Answer

PRM-guided GRPO (v0.71.30) lets a trained Process Reward Model drive GRPO reinforcement learning, the o1-era process-supervision signal, and no OSS fine-tuning CLI ships this. 'soup train with task: grpo' with training.prm_reward set to a PRM directory or Hugging Face id (from 'soup train with task: prm') and training.prm_aggregate set to min, prod or last scores each reasoning step of a generated answer and folds the per-step scores into one reward that GRPO optimizes, replacing reward_fn; the default aggregation 'min' is weakest-link and the safe choice, and it is gated to grpo, transformers and text. v0.71.30 also bundles three ready-to-run toy rollout environments (soup_cli.envs.calculator, retrieval_qa and guess_number) so the GRPO openenv rollout path works with no external setup, with the recipes grpo-env-calculator, grpo-env-retrieval-qa and grpo-env-guess-number. It is proof-of-mechanism on SmolLM2-135M with a tiny synthetic PRM and synthetic reward, not a production reward-model claim (scale ask tracked in issue #286).

Question 17

What is 'soup shrink' in Soup CLI v0.71.29, and how does depth pruning work?

Accepted Answer

'soup shrink --model [--drop-ratio 0.25 | --drop-layers N] --calib calib.jsonl [--heal heal.jsonl --heal-steps 200] [--tolerance 0.10] [-o shrunk] [--device cpu] [--attach-to-registry ] [--plan-only]' (v0.71.29) makes a model permanently smaller and faster by removing its least-useful decoder layers, optionally healing the damage by distillation, and printing a single SHIP / DON'T-SHIP perplexity verdict. It implements 'The Unreasonable Ineffectiveness of the Deeper Layers' (Gromov et al., arXiv:2403.17887): over a calibration set it ranks every contiguous block of decoder layers by the mean per-token angular distance the residual stream travels from the block's input to its output, drops the least-important block (the first and last decoder layers are always protected), reloads the sliced model so surviving layers re-index cleanly, and with '--heal' distills the full-depth original into the pruned student via an isolated LoRA logit-distillation 'soup train' subprocess whose adapter is then fused back — so the shipped artifact stays a single dense smaller model, not a base plus adapter. The verdict SHIPs only if the perplexity ratio (final / original) stays within '--tolerance' (default 10%), else DON'T SHIP; exit codes are 0 = SHIP, 2 = DON'T SHIP, 1 = error, and '--plan-only' prints the layer-importance table and the chosen block without writing anything. The arch allowlist v1 is Llama / Qwen / SmolLM (checked twice). It is validated live on SmolLM2-135M on a single RTX 3050: drop 25% took it from 30 to 22 layers (~21% of params) at perplexity x2.98 unhealed, while drop-4 plus a CPU heal recovered perplexity to x1.35. No fine-tuning CLI (Unsloth, Axolotl, LLaMA-Factory) ships one-command importance-ranked depth pruning with a distill-heal and a binary perplexity verdict. Security: --calib, --heal, --output-dir and every derived write path stay under cwd with realpath + commonpath + O_NOFOLLOW + symlink rejection re-validated right before each write (TOCTOU defence, including after the heal), the heal subprocess is an argv list with a timeout and a schema-validated config, subprocess output is control-char-stripped, input files are capped at 64 MiB / 10,000 calib rows, and --model defaults trust_remote_code off.

Question 18

Does Soup CLI have an MCP server, and what does 'soup mcp serve' do?

Accepted Answer

Yes. 'soup mcp serve [--allow-mutating]' (v0.71.28) is a Model Context Protocol server that lets you drive Soup from any MCP client (Claude Code, Cursor, Cline, Continue) over stdio, so your coding agent can inspect data, search recipes, read runs and give ship verdicts without leaving the chat. No other fine-tuning CLI ships an MCP server. It exposes 16 tools: 14 read-only ones that each map to a Soup command and return JSON (advise, data_inspect, data_validate, data_score, data_doctor, recipes_search, recipes_show, runs_list, runs_show, registry_list, registry_show, profile, diagnose_evidence, ship_evidence), plus 2 plan-only mutating tools (train_start, export) that are always listed but refuse to run unless you pass '--allow-mutating', and even then only render the exact command that would run — they never execute training or export in v1. Transport is stdio only: there is no network listener, no HTTP, no SSE. stdout is reserved for the JSON-RPC channel (all human text goes to stderr), every path argument re-enters cwd-containment plus symlink rejection, output is control-char sanitized so a malicious dataset string cannot smuggle terminal escapes into the client, errors are path-free, and string (<= 4096 chars) / JSON (<= 16 MiB) / dataset (<= 1 GiB) / int bounds are enforced. It installs behind a new '[mcp]' extra ('pip install "soup-cli[mcp]"', dependency mcp>=1.2.0) that is lazy-imported so the core CLI stays PyTorch-free and SDK-free. A client connects with { "mcpServers": { "soup": { "command": "soup", "args": ["mcp", "serve"] } } }. The server exposes MCP Tools only — no Resources or Prompts. SSE/HTTP transport and live execution of the mutating tools are filed follow-ups; v1 is stdio-only and plan-only.

Question 19

What is the Fine-tune Doctor (soup data doctor / soup data lint) in Soup CLI v0.71.27?

Accepted Answer

v0.71.27 'Fine-tune Doctor' is a pure-CPU, zero-GPU pre-flight that kills the top silent fine-tune failures before a single training step — something no competitor (Unsloth, Axolotl, LLaMA-Factory) ships. 'soup data doctor --model ' runs 8 chat-template compatibility checks against the real tokenizer: chat_template present, template renders cleanly, {% generation %} markers present, eos_in_labels (the number-one 'model never stops generating' bug — every assistant turn's trained span must actually contain an EOS/EOT token, checked on every turn not just the last), bos_duplication (template and tokenizer both prepending BOS), system_role support (Mistral-style templates reject a leading system turn), unknown_roles, and truncation_risk (p95 rendered length vs max_length). It uses the same OK/MINOR/MAJOR taxonomy as 'soup diagnose' with exit 0 on OK/MINOR and exit 2 on MAJOR, and '--show-mask N' colours each token trained-versus-masked through the REAL collator path (answer-only / per-message train-field / RAFT span-mask), not a reimplementation, so an assistant-mask bug is visible instantly. 'soup data lint ' is a preference-data linter for dpo/orpo/simpo/ipo/bco/kto that flags length_bias (chosen systematically longer than rejected, the number-one silent DPO degradation, reported as a Cohen's d effect size), label_imbalance (KTO desirable:undesirable ratio), near_duplicates (MinHash/LSH, reusing the dedup kernel), identical_pairs (chosen == rejected, zero preference signal), and prompt_leak (prompt echoed verbatim in the completion); pass '--model' for exact token-length bias instead of word count.

Question 20

What is 'soup spectrum scan' and how does Spectrum targeted training work?

Accepted Answer

'soup spectrum scan --model --top-percent 50 [--modules mlp,attn|all] [--output patch.yaml]' (v0.71.23) is native Spectrum targeted training. It streams a model's safetensors shards one tensor at a time — no model load, so peak RAM is the largest single weight matrix and you can scan even a 70B on a CPU box — 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. The SNR kernel is pure-numpy and transpose-invariant, so GPT-2 Conv1D weights (c_attn/c_fc/c_proj) are recognised alongside Llama-style names; results cache at '~/.soup/spectrum/.json'. The new schema field 'training.unfrozen_parameters: list[str]' takes regex patterns of parameter names to keep trainable: the SFT trainer freezes every parameter then unfreezes the matched set (a full fine-tune of a subset of layers, LoRA off). It requires task=sft, backend=transformers, modality=text, quantization=none and is mutually exclusive with LoRA features / freeze_layers / freeze_ratio / train_router_only / expand_layers. Patterns are ReDoS-validated (nested-unbounded-quantifier reject, 50k count cap, 512-char cap); Hub downloads route through the SSRF-hardened namespace-pinned loader and matrices above a 2^31-element SVD cap are skipped.

Question 21

How does 'soup train --reward-hack-detector' detect reward hacking in GRPO/PPO?

Accepted Answer

'soup train --reward-hack-detector info_rm|rm_ensemble [--reward-hack-halt]' (v0.70.0) is an early-warning system for reward hacking in GRPO/PPO runs. Two detectors: 'info_rm' tracks the InfoRM Cluster-Separation Index (Wang et al. 2024, arXiv 2402.09345) — a calibrated metric on reward-model embeddings that drops when the policy collapses onto a degenerate reward-maximizing subspace; 'rm_ensemble' tracks the mean pairwise variance across an RM ensemble (cap 32) — when ensemble members disagree, the policy is exploiting one of them. Math kernels 'compute_cluster_separation', 'compute_rm_ensemble_divergence', and 'classify_hack_signal' are LIVE with OK/WARN/HACK bands at 0.10 / 0.30 relative drop from the baseline window. '--reward-hack-halt' auto-stops on HACK verdict (exit 2). Cross-validator: task in {grpo, ppo} only, halt=True requires detector, rejects mlx backend. Composes with v0.34 'soup why' for anomaly explanation. LIVE as of v0.71.11 — the GRPO TrainerCallback now reads per-step rewards via a thread-safe capture buffer, classifies OK/WARN/HACK, logs the verdict, and halts on HACK.

Question 22

What is closed-loop reward-hacking auto-mitigation in Soup CLI v0.71.26?

Accepted Answer

'soup train --reward-hack-mitigation off|log_only|kl_control|pid_lagrangian' (config field 'training.reward_hack_mitigation', v0.71.26) makes a GRPO/PPO trainer DETECT reward hacking mid-run and SELF-CORRECT instead of only halting. No open-source RLHF library (TRL, Unsloth, Axolotl, OpenRLHF, verl) closes the loop from detection to automatic correction to continue — that is the whitespace it fills. Four modes: 'log_only' streams a per-step mitigation_log.jsonl (drop_pct, OK/WARN/HACK verdict, reward mean/std, completion-length trend, n-gram repetition) and provably never touches training dynamics; 'kl_control' is a reversible bang-bang controller with hysteresis that, when a multi-signal vote (InfoRM cluster-separation or RM-ensemble divergence plus length-trend and repetition) trips for a dwell window, raises the KL coefficient beta (clamped to a positive floor and ceiling, never crossing zero, written to both trainer.beta and trainer.args.beta for stock and variant GRPO and to args.kl_coef for PPO) and relaxes it once the signal recovers; 'pid_lagrangian' replaces bang-bang with a PID-Lagrangian controller (Stooke et al. 2020) that holds the hacking signal at a target with integral anti-windup, plus an escalation ladder (raise KL, then roll back to the last-good RL checkpoint, then early-stop with a plain-English give-up explanation via 'soup why'). Anti-gaming hardening adds per-signal EMA/median smoothing, conservative-on-disagreement voting, a reward-distribution-drift guard, and optional bounded reward shaping on the gamed proxy. It ships as proof-of-mechanism ONLY, validated on SmolLM2-135M plus a synthetic length-hacking task on a single RTX 3050 (all four modes live including a real mid-run rollback); PPO ships BETA (mechanism wired and unit-tested, on-GPU proof GRPO-only), and scale validation on 7B+ with real reward models is an open community question tracked in issue #286. +184 tests in that release; the suite is now 17,344 across 347 files.

Question 23

What is 'training.uld_strategy' (Universal Logit Distillation) in Soup CLI v0.70?

Accepted Answer

Setting 'training.uld_strategy: wasserstein' or 'topk_align' (plus 'training.uld_top_k: N' for the latter) in soup.yaml, then running 'soup train --config soup.yaml' (v0.70.0), is cross-tokenizer knowledge distillation (Boizard et al. 2024, arXiv 2402.12030) — Llama→Mistral, Llama→Qwen, no shared vocabulary required. 'wasserstein' computes a 1-D Wasserstein distance over sorted teacher / student logits, no token-level alignment needed (the cheap and robust default). 'topk_align' uses the top-K teacher logits matched via BPE-overlap heuristic alignment (use when you have a good vocab-overlap heuristic and want sharper signal). _MAX_VOCAB_SIZE=262144 covers multilingual SentencePiece + GPT-OSS 200K vocabularies. Gated to task='distill' and rejects mlx backend. LIVE as of v0.71.11 — the distill trainer now computes the real Wasserstein-1 / top-k-aligned loss, clamping teacher ids on a vocab-size mismatch.

Question 24

How does 'training.minillm_enabled' stabilize reverse-KL distillation?

Accepted Answer

The config keys 'training.minillm_enabled: true' plus 'minillm_teacher_mix_ratio: 0.3', 'minillm_length_normalize: true', 'minillm_pretrain_anchor_weight: 0.1' and 'minillm_pretrain_anchor_path: pre.jsonl' (v0.70.0) is on-policy reverse-KL distillation (Gu et al. 2024, arXiv 2306.08543) with all three §3 stability tricks bundled — teacher-mixed sampling (mix ratio of teacher samples into the on-policy rollout), length normalisation (per-token KL averaged), and pretrain-loss anchor (regularise toward an anchor distribution at weight α). Cross-validators reject silent no-ops: anchor_weight=0 with anchor_path set, or anchor_weight > 0 with path None. Gated to task='distill'. LIVE as of v0.71.11 — the teacher-mixed, length-normalised reverse-KL term plus the optional pretrain anchor now train end-to-end (the anchor reader is cwd-contained + symlink-rejecting).

Question 25

What does 'training.rl_checkpoint_save_every_steps' fix that TorchTune punts on?

Accepted Answer

The config keys 'training.rl_checkpoint_save_every_steps: N' plus 'rl_checkpoint_keep_last', 'rl_checkpoint_include_optimizer', 'rl_checkpoint_include_ref_model' and 'rl_checkpoint_include_rollout_buffer' (v0.70.0) adds mid-epoch checkpointing to PPO and GRPO — a feature TorchTune explicitly punts (their docs link out to 'restart the epoch on crash'). save_every_steps ∈ [1, 10M], keep_last ∈ [1, 100] (oldest pruned). Optional inclusions: optimizer state, reference model snapshot, rollout buffer. Composes with v0.32 spike recovery and v0.40 reference-model regen — when the recovery fires, it now hops to the most recent mid-epoch checkpoint instead of restarting the epoch. LIVE as of v0.71.11 — it writes a real adapter + optimizer state + JSON manifest every N steps and prunes to --keep-last.

Question 26

What is 'soup iterative-dpo' and how does it differ from a single DPO run?

Accepted Answer

'soup iterative-dpo --base-model --reward-model --prompts --output-dir --rounds N --pairs-per-round N [--plan-only]' (v0.70.0) drives the iterative-DPO loop: sample from the current policy, score with the reward model, build new preference pairs, retrain DPO, repeat for N rounds. Frozen IterativeDPOPlan with a consecutive-round_index invariant and canonical per-round artifacts ('./out/round-NN/pairs.jsonl', './out/round-NN/adapter') so a crashed run resumes cleanly. '--plan-only' renders the validated plan and exits 0; the live runner shipped in v0.71.11 — each round samples completions from the previous round's adapter, then trains a fresh LoRA from the base on that round's harvested pairs.

Question 27

How does 'training.echo_trap_enabled' detect multi-turn agent degeneration?

Accepted Answer

The config keys 'training.echo_trap_enabled: true' plus 'echo_trap_threshold: 0.6' and 'echo_trap_halt: true' (v0.70.0) is the RAGEN-style trajectory-degeneration detector for multi-turn agent RL (Zhu et al. 2025, arXiv 2504.14437). Pure-Python n-gram repetition rate per trajectory + a batch mean — when an agent's rollout collapses into 'echoing itself' (the same n-gram pattern appearing repeatedly within and across turns), this catches it before the reward model rewards the degenerate policy. OK / WARN / TRAP bands at 0.30 / 0.60. DoS caps _MAX_NGRAM_N=32, _MAX_TRAJECTORY_TOKENS=1M, _MAX_BATCH_TRAJECTORIES=100k. Gated to task in {grpo, ppo} non-mlx. Composes with v0.53.11 GRPOStabilityCallback. LIVE as of v0.71.11 — the GRPO callback now scores per-trajectory n-gram repetition, logs the verdict, and halts on TRAP when --echo-trap-halt is set.

Question 28

What is 'soup build' and how is it dbt-shaped?

Accepted Answer

'soup build <manifest.yaml> [--dry-run]' (v0.69.0) is a dbt-shaped DAG of dataset transforms with incremental materialisation. Closed SUPPORTED_MODEL_KINDS = {incremental, table, view}. Topo-sort via Kahn's algorithm. The 're-tokenise only changed rows' kernel: compute_row_hash (SHA-256 over canonical-JSON, 'id' field excluded) + incremental_diff(prev, new) → {added, changed, removed, unchanged}. DoS caps _MAX_MODELS=256, _MAX_REFS_PER_MODEL=32, _MAX_FILE_BYTES=1 MiB. '--dry-run' validates topology and exits 0. LIVE as of v0.71.6 — run_build materialises datasets with five built-in transforms (identity / drop_empty / lowercase / strip / dedup_exact); 'table' rebuilds, 'view' re-derives, 'incremental' re-transforms only the rows whose content hash changed (SQLite state store keyed by row hash + transform fingerprint). Custom transforms pass per-run via the Python API.

Question 29

What does 'soup expect' assert about a chat dataset?

Accepted Answer

'soup expect ' (v0.69.0, LIVE) is a Great Expectations suite for chat data with a closed SUPPORTED_EXPECTATIONS allowlist: expect_no_pii (reuses v0.47 Presidio analyzer), expect_token_length_between (min / max bounds), expect_no_refusal_pattern (reuses v0.56 refusal detector), expect_chosen_preferred_over_rejected_by_judge (reuses v0.19 LLM-judge surface). Walks 'text', 'content', 'output', 'prompt', 'instruction', 'response' top-level keys + 'messages[].content' nested arrays. _MAX_SUITE_LEN=64. Exit 0 = all expectations passed, 2 = validation rejection (suite shape invalid), 3 = expectations failed. Drop into CI between 'soup data' and 'soup train'.

Question 30

How do 'soup data gen-magpie' and 'persona-mix' improve synthetic data diversity?

Accepted Answer

'soup data gen-magpie --base --provider ollama|vllm --target N [--quality-filter] [--plan-only]' (v0.69.0, LIVE as of v0.71.6) generates synthetic chat data via the Magpie chat-template-prefix harvest trick — prime the base model with just the assistant chat-template prefix (chatml / llama3 / gemma / mistral auto-detected) and let it complete the prompt itself. Live providers are 'ollama' and 'vllm' raw-completion endpoints (both SSRF-hardened, loopback-only); 'anthropic' is rejected (no raw-completion endpoint). '--quality-filter' drops low-quality rows via the v0.47 scorers; exact-duplicate instructions are de-duplicated. 'soup data persona-mix --prompts --n N --output [--personas ] [--styles ]' (v0.69.0, LIVE) is the Persona-Hub diversity sampler — bundled 12 personas × 5 writing styles by default (BYO Tencent 200k corpus via --personas / --styles). Deterministic by seed (random.Random(seed)); compute_topic_diversity = Shannon entropy over pooled whitespace tokens; atomic JSONL write with 100 MiB / 100k entries per loader caps.

Question 31

How does 'soup data brain-rot' detect AI slop in training data?

Accepted Answer

'soup data brain-rot <data.jsonl> [--strict] [--max-major-fraction 0.25]' (v0.69.0, LIVE) implements the arXiv 2510.13928 brain-rot detector with two pure-Python scorers: score_triviality (token-diversity inversion + '!!' / '??' punctuation runs + low-effort token density + length penalty) and score_popularity_signal (clickbait phrase scan + emoji U+1F300–U+1FAFF density). Worst-signal-wins composition: 1.0 − max(triviality, popularity). Bands match the v0.26 / v0.56 / v0.65 taxonomy: OK ≥ 0.85, MINOR ≥ 0.60, else MAJOR. refuse_if_rotten raises when MAJOR fraction exceeds threshold. '--strict' exits 3 on excessive MAJOR. English-keyword-only in v0.69.0; multilingual lands in v0.69.1.

Question 32

What is 'soup compile' and why does it hedge against prompt engineering winning over fine-tuning?

Accepted Answer

'soup compile --eval [--optimizer mipro|gepa|textgrad|copro|bootstrap_fewshot] [--max-iters N] [--output ] [--plan-only]' (v0.68.0) is a DSPy + GEPA + TextGrad prompt-program compiler — if prompt engineering paradigms keep winning over fine-tuning, you have the compilation surface inside Soup. Hard bound MAX_COMPILE_ITERS=1000. Closed optimiser allowlist of 5. validate_program_path requires '.py' extension, cwd containment, and os.lstat + S_ISLNK rejection via the shared paths.enforce_under_cwd_and_no_symlink helper. CompileResult enforces finite-score (no NaN / ±Inf) and iterations ≥ 0. Module is commands/compile_cmd.py because 'compile' is a Python builtin. LIVE as of v0.71.13 behind the '[compile]' extra (pip install "soup-cli[compile]") — run_compile dispatches DSPy / GEPA / TextGrad optimisation; '--plan-only' still renders the plan and exits 0.

Question 33

What does 'soup distill-prompt' do?

Accepted Answer

'soup distill-prompt --traces --teacher --student --strategy sft|preference|kl [--output ] [--plan-only]' (v0.68.0) distils prompt-heavy traces — long system prompts, in-context examples — into small fine-tunes that internalise the prompt. Closed strategy set {sft, preference, kl}. Teacher / student IDs capped at 512 chars; null-byte + empty rejected. Composes with v0.71 cross-tokenizer ULD — distill-prompt picks the dataset shape, ULD bridges teacher / student vocabularies. LIVE as of v0.71.13 — prepare_distill_dataset calls the teacher once per trace via the v0.20 providers (Ollama / Anthropic / vLLM) and emits sft/kl messages or preference chosen/rejected pairs.

Question 34

How does 'soup apple-adapter' target Apple FoundationModels?

Accepted Answer

'soup apple-adapter --direction hf-to-mlx|mlx-to-hf|hf-to-apple|mlx-to-apple --output [--sign/--no-sign] [--plan-only]' (v0.68.0) converts adapter formats between HuggingFace safetensors, Apple MLX npz, and Apple FoundationModels (iOS 26+ on-device LLM) adapter blobs, with optional Merkle-root signing. Closed direction allowlist of 4. Explicit S_ISDIR + symlink rejection on source. 'sign' must be a real bool (bool-as-int defence). Reuses v0.60 Part B signing infrastructure and extends the v0.25 MLX backend. Live convert_apple_adapter ships in v0.68.1 (Apple's spec is still moving).

Question 35

What is 'soup local-rl' and how does the personal-LLM flywheel work?

Accepted Answer

'soup local-rl {init, status, record, harvest, train}' (v0.68.0) is a personal-LLM feedback flywheel daemon (LIVE except 'train'). 'soup local-rl init --db ' creates a POSIX 0o600 SQLite DB with interactions + thumbs tables (idempotent CREATE TABLE IF NOT EXISTS). 'soup local-rl record --db --prompt --response --thumb up|down' parameterised inserts with 16 KiB prompt + 16 KiB response caps and null-byte rejection. 'soup local-rl status --db ' renders a Rich table of interactions / up / down counters. 'soup local-rl harvest --db ' walks thumbs by ts ASC and emits one DpoPair{prompt, chosen, rejected} per prompt with both an up and down (last-writes-win dedup), atomic JSONL write via tempfile.mkstemp + os.replace — operators feed this straight into 'soup train with task: dpo'. 'soup local-rl train' is LIVE as of v0.71.13 — '--once' harvests the latest thumbs DPO pairs and runs a real nightly DPO/KTO/ORPO train via a 'soup train' subprocess (a 'state' table skips re-runs with no new feedback or fewer than --min-pairs); without '--once' it renders an injection-safe systemd .service/.timer + launchd .plist scheduler scaffold.

Question 36

What is 'soup adapters merge --strategy cmaes' and why is it different from linear / TIES / DARE / SVD?

Accepted Answer

'soup adapters merge --strategy cmaes --adapter --adapter ... --eval --budget 1h' (v0.67.0) runs Sakana-style evolutionary search over LoRA merge weights via pure-Python rank-mu CMA-ES (no 'cma' dependency). The optimiser parameterises N-1 logits, softmaxes them onto the simplex (sum=1, each ≥0), samples a population, keeps the elite half, and plateau-detects after 3 generations without improvement (converged=True). Bounds: 2–16 adapters, population [2, 256], generations [1, 10K], budget [60s, 24h] (reuses v0.57 blame.parse_budget). Operator-supplied eval_fn closure; failures swallowed with a sentinel -1e9 score so one broken eval doesn't crash the run (mirrors v0.40.3 proxy-failure isolation). Linear / TIES / DARE / SVD are still available as fast deterministic baselines; CMA-ES is for when you actually have a measurable eval and want the optimiser to search for you. LIVE as of v0.71.4 — the full CMA-ES loop now merges, materialises, and scores each candidate against the eval suite and writes the best-weighted merge to --output; '--canary ' adds an OK/MINOR/MAJOR verdict and the backdoor-scan + license gates run for cmaes too.

Question 37

What is the VeRA / VB-LoRA vector bank and why does it matter for multi-tenant serving?

Accepted Answer

'soup_cli.utils.vector_bank' (v0.67.0) is the storage format for VeRA / VB-LoRA — shared random projection matrix P (d_model × d_model) + per-user scaling vector v_u (vector_dim floats). A 128-D scaling vector at fp32 is ≈512 bytes per user vs. ~30 MB for a rank-16 LoRA on a 7B model — thousands of per-user adapters at MB-each instead of hundreds-of-MB per LoRA. Hosted vendors price by GPU-hour, not adapter count, so they structurally cannot offer this economics. Schema: bank name (kebab-case, ≤128 chars), base_model (≤512 chars), per-entry {user_id (≤256 chars), scaling_vector (floats, finite, no NaN/Inf)}. Bounds: vector_dim [1, 16K], up to 1M entries per bank, 16 MiB file-size cap, atomic JSON I/O via shared paths.atomic_write_text + cwd containment + symlink rejection. estimate_bank_size(num_users, vector_dim) for capacity planning. LIVE as of v0.71.12 — 'soup serve --bank <bank.json> [--bank-strength S]' reconstructs the shared projection + per-user scaling vectors and installs a decode-time forward hook; the active user is chosen per request via the 'X-User-Id' header (an unknown/absent id is a zero-delta no-op, so there is no cross-request leak), serving N personas at ~KB-per-user.

Question 38

What is MoLE per-token gating in Soup CLI v0.67?

Accepted Answer

task='moe_lora_routing' (v0.67.0) is Mixture of LoRA Experts: a gating network routes per-token activations to top-K task adapters via softmax over the hidden state. Config: MoleGatingConfig with num_task_adapters [2, 64], hidden_dim [1, 16K], temperature (1e-6, 100.0] finite, top_k ≤ num_task_adapters. Cross-validator rejects mlx backend. Beyond 64 adapters per-token softmax becomes the bottleneck; for more, hierarchy the gating. LIVE as of v0.71.12 — 'task: moe_lora_routing' with 'mole_task_adapters: [...]' trains a real per-token gating network that blends N frozen task LoRAs (mole_top_k / mole_temperature); only the router trains, and the gate is saved as 'mole_gate.pt' alongside the run.

Question 39

How do 'soup adapters pr' adapter pull requests work?

Accepted Answer

'soup adapters pr --base-sha <hex> --adapter <path> --eval <eval_delta.json> --samples <sample_diffs.json>' (v0.67.0) renders a GitHub-shaped pull request from an adapter triple {base SHA, dataset diff, adapter weights, eval-delta report} as review-friendly Markdown with an eval-delta table + per-sample baseline/candidate diffs. Bounds: ≤64 EvalDelta entries, ≤256 sample diffs, per-output cap 32 KiB to keep PRs reviewable. The _md_table_escape function neutralises backslash, pipe, newline, CR, and tab characters in operator-controlled cells against Markdown / Rich injection. JSON output is also available for the v0.68 GitHub Action that will post the PR comment. Composes with 'soup adapters diff' from v0.57.

Question 40

What does 'soup lock' do and how is it different from 'soup env lock'?

Accepted Answer

'soup lock write --base-model --base-sha <64hex> --dataset-sha <64hex> --env-hash <64hex>' (v0.67.0) computes closure_sha = SHA256(base_sha || dataset_sha || env_hash) and writes a JSON soup.lock with soup_version, base_model (≤512 chars), and the three SHAs. The point: commit soup.lock to git alongside soup.yaml so the entire team trains on identical (base, dataset, env). 'soup lock check' compares the 5 content fields and exits 3 on drift; soup_version + created_at are advisory only (legitimate operator upgrades don't trigger drift). 'soup env lock' is v0.64.0 — it produces the env_hash that feeds soup.lock; the two together close the reproducibility chain.

Question 41

What is 'soup adapters bisect' and how does it work?

Accepted Answer

'soup adapters bisect ... --eval-command "soup eval custom --model {ckpt} --tasks ./regression.jsonl"' (v0.67.0) does binary search over an ordered checkpoint history to find the first regression boundary. The operator supplies a shell template with a {ckpt} placeholder — Soup uses shlex.split after shlex.quote(ckpt), argv-list mode, no shell=True. Probes both endpoints first to short-circuit all-OK or all-broken, then ~log₂(n) midpoint probes. Verdicts: ALL_OK or BROKEN_AT (returns first_broken checkpoint ID). Exit 3 on BROKEN_AT for cron-friendly automation. Input: 2..4096 unique ordered checkpoint IDs. Composes with the v0.66 live influence-blame runner — bisect tells you which checkpoint broke, blame attributes it to specific training rows.

Question 42

What does 'soup tunability' decide before you pick a base model?

Accepted Answer

'soup tunability --dataset <path> --candidates llama-3.1-8b qwen2.5-7b gemma-3-9b --probe-steps 100 --holdout-size 64' (v0.64.0) runs lightweight LoRA probes on a held-out dataset slice against each candidate base, measures training-loss deltas, and reports the Pareto frontier (best efficiency for cost). The candidate allowlist is closed and ships with licensing metadata (Apache-2.0, MIT, LLaMA-3, etc.). '--plan-only' dry-runs without probing; '--list' catalogues all bundled candidates. Bounds: probe_steps [10, 10000], holdout_size [10, 100000] rows. Output: per-candidate delta (base_loss - probe_loss), wall-clock seconds, estimated USD cost, Pareto frontier membership. Safety: path containment (is_under_cwd), null-byte rejection, symlink-escape rejection on dataset and output paths.

Question 43

What is 'soup plan' / 'soup apply' and how is it Terraform-shaped?

Accepted Answer

'soup plan --config soup.yaml --state ./soup.tfstate' (v0.64.0) reads a training configuration, computes cost / ETA / peak-VRAM / SHA-256 hashes, and writes an immutable state file. 'soup apply' re-reads the config, detects any drift (changed batch size, dataset SHA, base SHA), and refuses to proceed (exit 3) if drift is found. State shape: plain JSON with 'plan' (cost, ETA, SHA hashes), 'applied' (bool), 'applied_at' (ISO timestamp), 'run_id' (reserved). TOCTOU defense: config read as YAML with os.lstat before open; symlinks explicitly rejected. Peak VRAM calculated with a 10% safety margin; estimated cost + minutes included with spot pricing per GPU tier. Composes with v0.60 license-check for adapter merge and v0.67 soup.lock for the full reproducibility chain.

Question 44

How does 'soup env lock' detect ABI drift?

Accepted Answer

'soup env lock --output ./soup-env.lock' (v0.64.0) snapshots the current Python environment (version, CUDA major version, platform, every installed package) into a JSON lockfile. 'soup env check --lock ./soup-env.lock' compares the current env against the lock and exits 3 on ABI-sensitive drift (e.g. Python minor version change, CUDA major version change) that would invalidate training. Fields: soup_version, python_version, platform, cuda_version (or 'none'), ISO timestamp, per-package {name, version, source}. Atomic write to lock file; reads have a file-size cap (no unbounded YAML). The env_hash from 'soup env lock' feeds the v0.67 soup.lock closure for full team reproducibility.

Question 45

What does 'soup license-advisor' decide for a deploy target?

Accepted Answer

'soup license-advisor --target b2c|defense|embedded --license <id> --monthly-active-users 0' (v0.64.0) recommends license-clean base models for a deployment target. Returns ok (safe), warn (yellow), or block (red; exits 3) with a reason string and recommended/forbidden license lists. Per-license risk scales with expected MAU (e.g., LLAMA-3 OK for <1M MAU, risky above). Composes with the v0.60 license_matrix.check_license_compat gate on 'soup adapters merge' — so a 33-entry SPDX matrix governs adapter merges, while license-advisor governs base-model selection upstream.

Question 46

What new failure modes does 'soup eval behavior' / 'eval capability' / 'eval checklist' add in v0.65?

Accepted Answer

v0.65.0 takes failure-mode coverage from 6 to 10. 'soup eval behavior --battery xstest|harmbench|jailbreakbench|elephant|syceval --evidence ' diffs pre/post-FT on bundled safety / refusal / jailbreak / sycophancy probe sets with OK/MINOR/MAJOR via the v0.26/v0.56 thresholds (≥0.85 OK, ≥0.60 MINOR, else MAJOR). 'soup eval capability --suite full|fast|math|code' emits validated lm-eval-harness task IDs for 7 bundled benchmarks (MMLU-Pro, GPQA, BBEH, AIME, MATH-500, HumanEval+, SWE-bench-Verified). 'soup eval checklist ' runs CheckList-style MFT (minimum functionality, keyword in response) / INV (invariance under paraphrase) / DIR (directional perturbation) tests from a 1 MiB-capped YAML spec with up to 1,000 tests. Evidence files capped at 16 MiB with O_NOFOLLOW open against symlink swap.

Question 47

What does 'soup eval irt-subset' do?

Accepted Answer

'soup eval irt-subset <responses.jsonl> --size full|small|tiny' (v0.65.0) fits a 1-parameter Rasch Item Response Theory model to per-item correctness signals and selects a minimum-cost subset that preserves ranking power. The math: P(correct | ability θ, difficulty β) = σ(θ - β); β_i = -log(p̂_i / (1 - p̂_i)); item information I(β) = σ(-β) · σ(β) which peaks at β≈0 (50/50 items are most discriminating). Profiles: full (100%), small (~30%), tiny (~10%). Input shape: JSONL rows {item_id (str, ≤256 chars, no null bytes), correct (bool), score? (float)} up to 1M rows. Pure-Python math (no numpy/scipy in v0.65.0); 256 MiB file cap against unbounded uploads.

Question 48

What is 'soup probe sae-diff' and which SAE repos are bundled?

Accepted Answer

'soup probe sae-diff --top-k 20' (v0.66.0) applies a Sparse Autoencoder encoder to pre- and post-FT activation batches, computes per-feature mean changes, and reports the top-K most-changed features. Purely descriptive (no verdict gate); designed for CI logging and model cards. The SAE repo allowlist is closed — Gemma Scope (2B/9B/27B residual-stream), EleutherAI Pythia SAEs, JBloomAus Llama SAEs, OpenAI GPT-2 SAE — and as of v0.71.8 '--auto-download' fetches an allowlisted SAE from the HF Hub into '~/.soup/sae-cache/' (validated against the allowlist BEFORE any network call, via an SSRF-hardened snapshot_download). Input shape: JSON with 'activations': [[...], ...] (2D float32 matrix [num_tokens, hidden_dim]) read via O_NOFOLLOW to prevent symlink swap. Output: SaeFeatureDiffReport with top-K features and per-feature {feature_id, delta, pre_mean, post_mean}. Bounds: top-k [1, 10K], up to 1M SAE features, up to 1M tokens per activation batch, 16 MiB evidence file cap.

Question 49

How does 'soup probe sleeper' work?

Accepted Answer

'soup probe sleeper --evidence ' (v0.66.0) applies a linear defection probe (synthetic, deterministic, keyed on base name for reproducibility) to a 2D activation tensor. Classifies per-token scores as defection or benign, returns flagged rate, and assigns OK/MINOR/MAJOR: ≤1% → OK, ≤5% → MINOR, >5% → MAJOR. Closed allowlist of bundled bases (Llama-3-8B, Gemma-2-9B, etc.) — metadata includes hidden_dim, threshold, description. Activation input: JSON {'activations': [[...], ...]} (2D float32 [num_tokens, hidden_dim]); 1M token cap. No evidence = OK report with 0 tokens (matches v0.56 diagnose neutral-mode policy). 16 MiB evidence cap, symlink rejection.

Question 50

What is 'soup probe interference' and when does it gate CI?

Accepted Answer

'soup probe interference <losses.json>' (v0.66.0) builds an N×N matrix of adapter pairwise compatibility scores from operator-measured losses. Input JSON has 'adapters' list and 'losses' dict with keys like 'a|b' (loss on domain A when both A and B loaded) and 'a|a' (baseline loss with A alone). Formula: score(A→B) = (loss(A_target | A+B) - loss(A_target | A alone)) / loss(A alone). Classification: |score| <5% → OK, <20% → MINOR, ≥20% → MAJOR. Bounds: 2–16 adapters (4–256 pairwise probes); adapter names ≤256 chars and markup-escaped against Rich/Markdown injection before render. Output: InterferenceMatrix with cells and worst-pair summary; exits 2 if worst ≥20% interference (gates CI merge).

Question 51

How does 'soup ingest' pull traces from observability vendors?

Accepted Answer

'soup ingest --source langfuse|langsmith|helicone|openpipe|otel|openai-stored --logs --output ' (v0.63.0) normalises any observability export into one TraceRecord schema (trace_id / prompt / output / source / signal / metadata as a MappingProxyType so callers can't mutate). No network calls — the operator exports from the SaaS dashboard, then 'soup ingest' parses the file. Six sources at launch: LANGFUSE_KEY for Langfuse, LANGSMITH_API_KEY for LangSmith, HELICONE_API_KEY for Helicone, OPENPIPE_API_KEY for OpenPipe, OTEL_EXPORTER_OTLP_HEADERS for OpenTelemetry OTLP, OPENAI_API_KEY for OpenAI Stored Completions. PII warning prints once per invocation. Output feeds directly into the v0.26 'soup data from-traces' preference-pair builder and the v0.58 'soup loop' HarvestFn — closing the production-traces → training loop without paying per-trace fees to any vendor.

Question 52

What does 'soup prune-prompt' do?

Accepted Answer

'soup prune-prompt --input --output --min-frequency 0.95' (v0.63.0) detects the longest shared system-prompt prefix across all rows via binary search over up to 32 candidate lengths and strips it. By removing the shared boilerplate (e.g., 'You are a helpful AI assistant...'), the fine-tuned model internalizes it into its weights instead of repeating it on every turn — OpenPipe's signature trick at the data layer. Two-pass file read; capped at 100k rows. v0.63 fixed an O(N²) early-exit bug from the prototype detect_common_prefix function.

Question 53

What is 'soup ab' and how is it different from a fixed-N A/B test?

Accepted Answer

'soup ab --input --metric latency|judge_score|retry_rate --alpha 0.05 --beta 0.20 --effect-size 0.1' (v0.63.0) runs Wald's Sequential Probability Ratio Test (SPRT). The log-likelihood ratio is a martingale under the null, so Type-I error is controlled at every stopping time — you can peek at the results at any sample count and decide reject_h0 / accept_h0 / continue without breaking statistical guarantees. The SPRT log-likelihood ratio is compared against A = log((1-β)/α) and B = log(β/(1-α)). v0.63 ships a CRITICAL fix for a sign error in the historical mSPRT implementation. Three metrics at launch: latency, judge_score, retry_rate. Input rows: {arm: 'control'|'treatment', : }.

Question 54

What does 'soup drift-alarm' watch in production?

Accepted Answer

'soup drift-alarm --reference --live --threshold 0.2 [--slack-url ... --discord-url ...]' (v0.63.0) computes KL divergence between token-distribution snapshots at fine-tune time (reference) and production (live). Catches both behavioral drift ('model now outputs JSON when it didn't before') and vocabulary drift ('same 20 phrases on repeat'). Whitespace tokenization by default; pluggable tokenizers ship in v0.63.1. Optional Slack / Discord webhooks fire on drift, SSRF-validated: loopback HTTP only, RFC1918 / link-local / cloud-metadata IPs (169.254.0.0/16, 100.64.0.0/10, 198.18.0.0/15) rejected. Exit code 3 on drift for cron-friendly automation. Input rows: {token: '', log_prob: }.

Question 55

How does Soup CLI handle GDPR right-to-be-forgotten?

Accepted Answer

Soup CLI v0.61.0 ships 'task: unlearn' as a first-class trainer with three methods: NPO (Negative Preference Optimization — DPO-shaped negative-only loss, needs reference model + retain set), SimNPO (length-normalized NPO, no reference model needed — faster on long sequences), and RMU (Representation Misdirection Unlearning — residual-stream noise on forget inputs, best for concept-level removal). Config: set 'task: unlearn', 'training.unlearn_method: npo|simnpo|rmu', 'training.unlearn_alpha' (0.0–10.0, default 0.5, retain-set weight), 'data.forget_set' (required JSONL or HF dataset ID), 'data.retain_set' (optional, strongly recommended for NPO). Verify with 'soup eval unlearning <run-id> --benchmark tofu|muse|wmdp' which scores Forget Quality / Model Utility / PrivLeak and emits an OK / MINOR / MAJOR verdict (MUSE + WMDP fixtures bundled since v0.71.1; WMDP forget-set probes ship redacted). The trainer is LIVE as of v0.71.9 — covariance-free NPO / length-normalised SimNPO / RMU representation-steering kernels run end-to-end, warning when run without a retain set.

Question 56

Can I patch a single fact in a model without retraining?

Accepted Answer

Yes. Soup CLI v0.61.0 ships 'soup edit set --base --method rome|memit|alphaedit --subject "" --target ""' for surgical fact patching. Three methods: ROME (Rank-One Model Editing, targets MLP layers — Meng 2022), MEMIT (Mass-Edit Memory in a Transformer — Meng 2023), and AlphaEdit (ROME projected orthogonal to the down-proj's top singular direction). LIVE as of v0.71.9 — covariance-free rank-1 weight-edit kernels apply the update and optionally save (on a tiny model a ROME edit moved P('Lyon' | 'The capital of France is') from 0.0016 → 0.96); a SQLite EditGovernor enforces the per-base edit cap + norm-blowup refusal across separate runs. Live GRACE codebook (epsilon-ball decode-time substitution) ships alongside. 'soup edit diff registry://before_id registry://after_id --probes probes.jsonl --top-k 10' compares two Registry entries and surfaces which facts changed with a citation visualizer. The Sequential Edit Governor caps per-base-model edits (default 10) and rejects edits that would amplify weight norms beyond threshold — preventing cascading drift across many sequential edits.

Question 57

What is RAFT and how does Soup CLI implement it?

Accepted Answer

RAFT (Retrieval Augmented Fine-Tuning, Stanford 2024) teaches a model to use retrieved context — both golden and distractor documents — to answer queries. Soup CLI v0.62.0 ships 'data.format: raft' with per-row schema {query, golden_doc, distractor_docs[], answer}. Pair with 'training.ra_dit_stage: retriever|generator' for the RA-DIT two-stage pipeline: stage 1 trains a contrastive sentence-transformer ('ra_dit_retriever_model: sentence-transformers/all-MiniLM-L6-v2' default), stage 2 SFTs the main model on RAFT rows. LIVE as of v0.71.10 — RAFT span-mask training masks the prompt to -100 and labels each doc '[doc-N]' so the model learns to cite the supporting document (reproducible shuffle via 'data.raft_shuffle_seed'), and the 'soup ra-dit' one-shot orchestrator trains retriever then generator in a single command, recording the trained retriever as the generator's paired retriever (auto-linked from the Registry when unset). Add 'training.citation_faithful: true' + 'citation_style: bracket|inline|footnote' + 'citation_recall_threshold: 0.85' to enforce source attribution at training time — the final save is refused if recall falls below threshold. Three new recipes shipped: raft-llama3-8b, ra-dit-retriever, ra-dit-llama3-8b.

Question 58

Can I steer a model's behavior at inference time without fine-tuning?

Accepted Answer

Yes. Soup CLI v0.62.0 ships 'soup steer train --base --method caa|iti|repe --name --pairs ' for training activation steering vectors, then 'soup steer apply --name --strength ' to apply them at decode time (|strength| ≤ 10 enforced). Three methods: CAA (Contrastive Activation Addition, adds a learned vector to the residual stream), ITI (Inference-Time Intervention, shifts specific attention heads), and RepE (Representation Engineering, PCA-based direction extraction). Pairs JSONL: {positive: '', negative: ''}. Steering vectors register as the new 'steering_vector' artifact kind in the v0.26 Registry. LIVE as of v0.71.10 — 'soup steer train' fits the CAA/ITI/RepE control vector from {positive, negative} pairs and persists a safetensors + config artifact, and 'soup serve --steer --steer-strength ~~' applies it at decode time via a forward hook. Use case: nudge safety, formality, or domain focus without a full SFT/DPO run.~~

Question 59

Does Soup CLI generate compliance docs for procurement / regulators?

Accepted Answer

Yes (v0.59.0 'Governance & Provenance'). 'soup bom emit --name --version --base-model --base-sha --config-sha --task --license --format cyclonedx|spdx|both' produces machine-learning Bills of Material in CycloneDX 1.6 (with the ML-BOM extension) and SPDX 2.3 AI-profile formats — both, in one shot. 'soup attest emit --stage extract|train|eval|export|publish --subject --sha --builder --invocation --sign unsigned|ed25519|sigstore' writes SLSA-3 in-toto attestations per stage. 'soup audit-log tail/rotate' keeps a HIPAA/SOC2-compliant JSONL audit log at ~/.soup/audit.jsonl with PII redaction. 'soup train --annex-xi --repro-receipt ' emits EU AI Act Annex XI/XII documentation plus SR 11-7 reproducibility receipts (every seed, kernel version, library version, dataset hash). All atomic writes (tempfile.mkstemp + os.replace) with symlink-rejection TOCTOU defense.

Question 60

How does Soup CLI prevent supply-chain attacks on LoRA adapters?

Accepted Answer

Six controls in v0.60.0. (1) 'soup adapters scan ' spectral-analyses LoRA weights for backdoors: rank-1 dominance (warn at 50×, fail at 200×), top-singular-value energy concentration (warn > 75%, fail > 95%), Frobenius outliers (warn > 4σ, fail > 8σ), NaN/Inf. Exit 0/1/3 for OK/WARN/FAIL — pure numpy, no torch. (2) 'soup adapters sign ' computes a Merkle root over all files and writes .soup-signature.json — real ed25519 detached signatures are LIVE as of v0.71.2 via the '[sign]' extra ('--backend ed25519 --key ' or '--generate-key'; 'soup adapters verify --public-key ' does a cryptographic verify, failing closed on any tamper/wrong key). Sigstore keyless stays infra-blocked. (3) 'soup adapters verify --strict' refuses to load on signature mismatch. (4) 'soup adapters check-safetensors --strict' refuses pickle / .bin / .pt — the single biggest LoRA attack vector. (5) 'soup adapters merge --license [--license ] --license-override ""' enforces SPDX-license compatibility via a 33-entry matrix. (6) 'soup airgap-bundle --model --dataset ... --wheel ... --kernel ... --bundle-size-cap 100' packs everything for one-way data-diode transfer, ≤100 GiB cap, signed manifest. Plus namespace-pin TOFU: the first pull of an HF repo pins its owner SHA in a local SQLite cache so a hijacked org cannot silently swap your base model.

Question 61

What is 'soup loop' and how does the production data flywheel work?

Accepted Answer

'soup loop' (v0.58.0) runs the full production data flywheel from a single CLI: harvest production traces → distill into preference pairs → eval-gated DPO train → canary deploy → auto-rollback on regression. 'soup loop init --eval --baseline registry:// --monthly-budget 50usd --max-runs-per-day 3' creates an atomic '.soup/loop.yaml' state file. 'soup loop watch' runs as a long-running daemon (SIGTERM/SIGINT safe, reloads state every iteration so external pause/resume takes effect immediately). 'soup loop canary --traffic 5% --autoroll-on-regress' splits traffic via deterministic SHA-256 hash routing (±0.01% split granularity, threading-locked BucketStats); the verdict uses the v0.26 Quant-Lobotomy OK/MAJOR thresholds with a 30-sample minimum. 'soup loop pause' / 'soup loop resume' flip atomic status without killing the daemon. 'soup loop replay []' walks per-iteration manifests at '.soup-loops//iteration.json'. Budget guardrails enforce a daily-cap → estimate-sanity → monthly-budget check order; budget-skipped iterations produce no manifests. Every iteration is recorded as a frozen IterationRecord with gate verdict, canary verdict, shipped flag, rolled-back flag, and estimated cost.

Question 62

What does 'soup advise' decide before you fine-tune?

Accepted Answer

'soup advise --goal ""' (v0.54.0) is a pre-flight decision engine that classifies the task (keyword + structural signals — tool_calls → tool_use, '' → reasoning, chat messages → input-extraction) across 7 task categories, profiles the dataset (row_count, avg input/output chars, type-token diversity, label variance, has_chosen_rejected, has_reasoning_traces — capped at 2,000-row sample), and emits a rubric verdict among PROMPT_ENG / RAG / SFT / DPO / GRPO. Heuristics: preference pairs → DPO; reasoning + ≥500 rows → GRPO; <50 rows → PROMPT_ENG; high-variance factual → RAG; default → SFT. Optional '--probe' runs a 100-step LoRA probe to put real numbers on each ROI estimate. '--record' appends an entry to '~/.soup/advise_history.jsonl' so future verdicts learn across projects (atomic, file-locked, 16 MiB cap). 'soup advise explain' prints the full rubric. 'soup advise compare ' compares two candidate datasets. Outputs the literal next command ('soup autopilot --data … --task sft') so the handoff is one paste away.

Question 63

How does 'soup eval design' derive an eval suite from your data?

Accepted Answer

'soup eval design --goal "..."' (v0.55.0) uses TF-IDF salience over your training data (10,000-row DoS-capped subsample) plus goal-keyword dispatch to draft a goal-conditioned eval suite with up to 5 dimensions and a scorer per dimension chosen from {exact_match, regex, judge, rlvr}: 'json' / 'code' / 'math' keywords → rlvr; 'classify' → exact_match; 'extract' → regex; default → judge. 'soup eval discover ' runs greedy farthest-first Jaccard-distance clustering (10,000-row cap) to surface held-out canaries + adjacent-skill probes + 25%-prefix memorization probes. 'soup eval lock ' freezes the suite as a SHA-256-checksummed 'eval_suite' artifact (canonical-JSON for stable hashes; registered in the v0.26 registry alongside the new 'canaries' kind). 'soup eval coverage --task ' does gap analysis against the v0.54.0 task taxonomy (each task has a recommended scorer set — e.g. reasoning → rlvr/judge, format_conversion → regex/rlvr). 'soup eval gate-install --baseline ' writes a '.git/hooks/pre-push' that paired-bootstraps a regression verdict against the baseline (configurable n_samples in [100, 100_000], ci_level in (0, 1), direction-aware metric handling) and blocks the push on regression.

Question 64

What does 'soup diagnose' check in a trained model?

Accepted Answer

'soup diagnose ' (v0.56.0) is a post-training model report card that runs 6 pure-function failure-mode probes and rolls them up into an OK/MINOR/MAJOR verdict (thresholds: ≥0.85 OK, ≥0.60 MINOR, else MAJOR). The probes: (1) forgetting — per-task Δ accuracy with tolerance band, extending the v0.25 forgetting baseline; (2) refusal — advbench / xstest delta over caller-supplied generators, 8,192-row scan cap; (3) format — JSON / regex / tool-call validity over RLVR verifiers with explicit ReDoS probe ('a' × 128); (4) mode_collapse — pairwise n-gram-Jaccard distance over K completions (k ∈ [2,32], ngram_n ∈ [1,8]); (5) memorization — training-prefix echo via partial-prompt continuation (1,000-row scan); (6) contamination — n-gram overlap with public benchmarks (combined-complexity cap rejects when |training| × |benchmark| > 1e9). Outputs JSON + a 6-cell SVG badge ('utils/diagnose/badge.py::render_badge_svg', html-escaped) that you can embed in model cards. '--attach-to-registry ' attaches it as the v0.56.0 'diagnose_report' artifact kind. Pair with 'soup train --diagnose-gate ' to refuse the final save on MAJOR regression (exits typer.Exit(code=2)).

If you	What happened	What to do
Trained supervised with `data.max_length` above 1024	Every such run was silently truncated to 1024 tokens. Measured: a config asking for 4096 produced 1024 tokens per sample, with no warning	Re-run on v0.73.0. Long-context, document and multi-turn tunes are the ones that suffered
Used `use_fsdp2_compile: true`	The adapter reloads as all zeros. The tensors trained, but every key was saved with a `torch.compile` prefix, so loading matched none of them and left the weights at their zero init. The run exited 0 with a healthy loss	Re-run. This is the third defect of this exact shape in the project's history
Streamed a 32B or larger model in NF4	Gradients were wrong on every layer but the last few, while the forward stayed bit-exact and the loss matched a resident reference to every digit	Re-run. 8B and 14B are below the threshold and are fine
Relied on a `soup ship` verdict	Two of the three behavioural suites scored 0.000 on a model that does both tasks correctly, and the refusal detector missed the typographic apostrophe Llama actually types, reporting 0.300 for a model whose true refusal rate is 1.000	Re-run the gate. Stored evidence from before this release is not comparable
Exported a GGUF at f16 and then quantised	The quantised export deleted your f16 file, even with an unrelated `--output`	Re-export the f16 if you still need it
Followed the printed `--no-reexec` hint	The hint dropped every flag you had typed, so following it literally trained without `--fsdp`, `--gate` or `--wandb`	Check what you actually ran

v0.73.0 "Borrowed Hardware"

Re-run this

The defect worth reading about

Two new capabilities

A seed you can set

Full fine-tuning as `lora.r: 0`

Four backends that had never run

Layer streaming, beyond the defect

Packaging

Known limitations

See also