soup-cli 0.71.8__tar.gz → 0.71.10__tar.gz

{soup_cli-0.71.8 → soup_cli-0.71.10}/CHANGELOG.md

@@ -12,6 +12,86 @@ reproducing 70+ versions of notes.
 
 ## [Unreleased]
 
+## [0.71.10] - 2026-06-03
+
+### Added
+- **RAG family — live wiring** (closes #199, #200, #201, #202). The four
+  retrieval / steering surfaces that shipped schema-only in v0.62.0 are now
+  real, validated on SmolLM2-135M.
+- **RAFT span-mask training is live** (#199). `data.format: raft` rows
+  (`{query, golden_doc, distractor_docs, answer}`) now train answer-only: the
+  prompt span is masked to `-100` and each document is labelled `[doc-N]` so
+  the model learns to cite the supporting document. Documents are shuffled
+  reproducibly (`data.raft_shuffle_seed`). Rows whose prompt fills
+  `max_length` (answer fully truncated) are dropped with a warning rather than
+  silently shrinking the effective dataset.
+- **`soup ra-dit` — one-shot two-stage orchestrator** (#200). Trains the
+  retriever (stage 1, embedding/contrastive) then the generator (stage 2,
+  RAFT-SFT) in a single command, recording the trained retriever as the
+  generator's paired retriever. A `soup train` of a generator-stage config
+  with no retriever model set now auto-links the most-recent RA-DIT retriever
+  run from the Registry. `--plan-only` validates both configs without
+  training; `--retriever-model` overrides the auto-link.
+- **`soup steer train` / `apply` + `soup serve --steer` are live** (#201).
+  Fit a CAA (contrastive activation addition), ITI (inference-time
+  intervention) or RepE (representation-engineering PCA) control vector from
+  `{positive, negative}` contrastive pairs, persist it as a safetensors +
+  config artifact, and apply it at decode time via a forward hook
+  (`soup serve --steer <name> --steer-strength <s>`).
+- **`soup eval citation` + citation-span loss boost are live** (#202). Score
+  citation precision / recall / F1 over `{predicted, expected_ids}` or RAFT
+  rows (`--shuffle-seed` aligns the golden `[doc-N]` id with what the model
+  saw at train time). When `citation_faithful: true`, bracketed `[doc-id]`
+  spans in the answer get a boosted per-token loss weight. A new `citation`
+  failure mode is available in `soup diagnose`.
+
+## [0.71.9] - 2026-06-03
+
+### Added
+- **Knowledge edit + unlearn — live wiring** (closes #193, #194, #196, #197,
+  #203). The v0.61.0 / v0.62.0 schema-only stubs are now live, validated on
+  SmolLM2-135M.
+- **`soup edit set` (ROME / MEMIT / AlphaEdit) is live** (#194). New
+  `soup_cli/utils/edit_kernels.py` ships covariance-free rank-1 weight-edit
+  kernels: ROME (single-layer `W += δ·kᵀ/‖k‖²`), MEMIT (residual distributed
+  across a layer band), AlphaEdit (ROME update projected orthogonal to the
+  down-proj's top singular direction). `apply_edit` loads the model, optimises
+  the target residual, applies the rank-1 update, and optionally saves with
+  cwd-containment + symlink rejection. `--output`, `--device`, `--governor/
+  --no-governor` flags added. On a tiny model a ROME edit moved
+  `P("Lyon" | "The capital of France is")` from 0.0016 → 0.96.
+- **`soup edit diff` live before/after generation** (#194). Pass
+  `--before-model` + `--after-model` (+ `--probes`) to generate completions
+  through both models and surface the probes whose output changed.
+- **EditGovernor SQLite persistence + cross-process locking** (#196). New
+  `EditGovernorStore` (mirrors `namespace_pin.NamespacePinStore` —
+  $HOME/$CWD/$TMPDIR containment, TOCTOU symlink rejection, WAL +
+  busy_timeout, `fcntl`/`msvcrt` sidecar lock, POSIX 0600). `save_governor` /
+  `load_governor` / `default_governor_db_path` (env override
+  `SOUP_EDIT_GOVERNOR_DB`) persist per-base-model edit-count + verdict across
+  separate `soup edit set` runs.
+- **`apply_edit` consults the EditGovernor automatically** (#197). When a
+  governor is supplied, `check_can_edit()` runs BEFORE the model load (refusing
+  on norm blowup / edit cap) and `record_edit()` runs AFTER with the measured
+  Frobenius delta.
+- **Live GRACE codebook** (#203). `GraceCodebook` (epsilon-ball nearest-key
+  lookup), `apply_grace_edit` (captures a residual key + optimises a value +
+  appends to a codebook sidecar), `save_codebook` / `load_codebook` (atomic,
+  cwd-contained, symlink-rejected), `install_grace_hook` (decode-time residual
+  substitution). New `edited_model` / `grace_codebook` Registry artifact kinds.
+- **`soup train --task unlearn` is live (NPO / SimNPO / RMU)** (#193). New
+  `soup_cli/utils/unlearn_kernels.py` (NPO `(2/β)·mean(-logσ(-β(πlp-reflp)))`,
+  length-normalised SimNPO, RMU representation steering) + a self-contained
+  `UnlearnTrainerWrapper` loop loading a LoRA policy, a frozen reference
+  (NPO/RMU), and forget/retain JSONL datasets. NPO/SimNPO forget loss
+  decreased on the tiny-model smoke. Warns when run without a retain set.
+
+### Security
+- `_save_edited_model` / `UnlearnTrainerWrapper` output dirs + `save_codebook`
+  / `load_codebook` + `_load_unlearn_rows` enforce cwd-containment, raw-path
+  symlink rejection (TOCTOU), null-byte rejection, and file-size / per-line
+  caps. `apply_grace_edit` honours the governor for direct callers.
+
 ## [0.71.8] - 2026-06-03
 
 ### Added

{soup_cli-0.71.8 → soup_cli-0.71.10}/CONTRIBUTING.md

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

{soup_cli-0.71.8 → soup_cli-0.71.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soup-cli
-Version: 0.71.8
+Version: 0.71.10
 Summary: Fine-tune LLMs in one command. No SSH, no config hell.
 Project-URL: Homepage, https://github.com/MakazhanAlpamys/Soup
 Project-URL: Repository, https://github.com/MakazhanAlpamys/Soup
@@ -183,20 +183,21 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.8 — Probes & SAE.** The activation-probe surfaces ship real weights, live SAE downloads,
-and an end-to-end capture → diff pipeline:
-
-- **`soup probe truth` / `soup probe harm`** — TruthfulQA-style honesty and HarmBench-style misuse
-  activation probes (6 bundled bases each, 5% / 20% verdict bands). `--weights` loads a real
-  calibrated probe; without it the bundled deterministic fallback is used.
-- **`soup probe sleeper --weights <w.npz|.npy|.safetensors>`** — load a real calibrated sleeper
-  probe direction instead of the synthetic fallback (cwd-contained, `allow_pickle=False`).
-- **`soup probe sae-diff <repo> --auto-download`** — fetch an allowlisted SAE from the HF Hub into
-  `~/.soup/sae-cache/` (validated before any network call) and diff pre/post activations.
-- **`soup probe interference --measure <eval.jsonl> --base-model <m> --adapter a=path ...`** —
-  auto-measure the N×N adapter-interference matrix by actually loading the base + each LoRA adapter.
-- **`soup train --capture-activations <layer> --capture-prompts <jsonl>`** — a post-training hook
-  writes an SAE-diff-ready per-token activation snapshot. Validated end-to-end on SmolLM2-135M.
+**v0.71.10 — RAG family (live).** The retrieval-augmented fine-tuning, steering, and citation
+surfaces are now real, validated on SmolLM2-135M:
+
+- **`data.format: raft`** — RAFT (retrieval-augmented fine-tuning): train on a query + golden
+  document mixed with distractors, answer-only loss, each doc labelled `[doc-N]` so the model
+  learns to cite the supporting source and ignore noise.
+- **`soup ra-dit`** — one-shot two-stage orchestrator: trains the retriever then the generator
+  and records the trained retriever as the generator's paired retriever. A `soup train` of a
+  generator stage auto-links the latest RA-DIT retriever from the Registry.
+- **`soup steer train --method caa|iti|repe` + `soup serve --steer <name>`** — fit a
+  contrastive-activation / inference-time-intervention / representation-engineering control
+  vector from `{positive, negative}` pairs and apply it at decode time via a forward hook.
+- **`soup eval citation`** — score citation precision / recall / F1 over predictions or RAFT
+  rows; with `citation_faithful: true`, `[doc-id]` spans get a boosted per-token loss weight.
+  A new `citation` failure mode joins `soup diagnose`.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.8 → soup_cli-0.71.10}/README.md

@@ -49,20 +49,21 @@ infrastructure instead of improving models. Soup fixes that.
 
 ## What's New
 
-**v0.71.8 — Probes & SAE.** The activation-probe surfaces ship real weights, live SAE downloads,
-and an end-to-end capture → diff pipeline:
-
-- **`soup probe truth` / `soup probe harm`** — TruthfulQA-style honesty and HarmBench-style misuse
-  activation probes (6 bundled bases each, 5% / 20% verdict bands). `--weights` loads a real
-  calibrated probe; without it the bundled deterministic fallback is used.
-- **`soup probe sleeper --weights <w.npz|.npy|.safetensors>`** — load a real calibrated sleeper
-  probe direction instead of the synthetic fallback (cwd-contained, `allow_pickle=False`).
-- **`soup probe sae-diff <repo> --auto-download`** — fetch an allowlisted SAE from the HF Hub into
-  `~/.soup/sae-cache/` (validated before any network call) and diff pre/post activations.
-- **`soup probe interference --measure <eval.jsonl> --base-model <m> --adapter a=path ...`** —
-  auto-measure the N×N adapter-interference matrix by actually loading the base + each LoRA adapter.
-- **`soup train --capture-activations <layer> --capture-prompts <jsonl>`** — a post-training hook
-  writes an SAE-diff-ready per-token activation snapshot. Validated end-to-end on SmolLM2-135M.
+**v0.71.10 — RAG family (live).** The retrieval-augmented fine-tuning, steering, and citation
+surfaces are now real, validated on SmolLM2-135M:
+
+- **`data.format: raft`** — RAFT (retrieval-augmented fine-tuning): train on a query + golden
+  document mixed with distractors, answer-only loss, each doc labelled `[doc-N]` so the model
+  learns to cite the supporting source and ignore noise.
+- **`soup ra-dit`** — one-shot two-stage orchestrator: trains the retriever then the generator
+  and records the trained retriever as the generator's paired retriever. A `soup train` of a
+  generator stage auto-links the latest RA-DIT retriever from the Registry.
+- **`soup steer train --method caa|iti|repe` + `soup serve --steer <name>`** — fit a
+  contrastive-activation / inference-time-intervention / representation-engineering control
+  vector from `{positive, negative}` pairs and apply it at decode time via a forward hook.
+- **`soup eval citation`** — score citation precision / recall / F1 over predictions or RAFT
+  rows; with `citation_faithful: true`, `[doc-id]` spans get a boosted per-token loss weight.
+  A new `citation` failure mode joins `soup diagnose`.
 
 Full history: [CHANGELOG.md](CHANGELOG.md) &middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).
 

{soup_cli-0.71.8 → soup_cli-0.71.10}/docs/adapters-and-governance.md

@@ -139,21 +139,26 @@ State lives in `.soup/loop.yaml` (atomic write, cwd-contained, symlink-rejected)
 Surgical factual patches WITHOUT a full fine-tuning loop. Hospital data team correcting a misattributed drug interaction, lab fixing a wrong historical date, security team responding to a hallucinated CVE — all one CLI invocation.
 
 ```bash
-# Plan-only mode validates the request + prints the resolved EditPlan + exits 0.
+# Live edit: optimises a residual + applies a rank-1 weight update, then saves.
 soup edit set \
-  --base meta-llama/Llama-3.1-8B-Instruct \
+  --base HuggingFaceTB/SmolLM2-135M \
   --method rome \
-  --subject "Paris is the capital of France" \
+  --subject "The capital of France is" \
   --target "Lyon" \
-  --plan-only
+  --output ./edited --device cuda
+
+# Plan-only mode validates the request + prints the resolved EditPlan + exits 0.
+soup edit set --base ./model --method rome --subject "..." --target "..." --plan-only
 
-# Diff what the model "knew" before vs after the edit.
-soup edit diff <run-id-before> <run-id-after> --probes probes.jsonl --output diff.json
+# Diff what the model says before vs after the edit (live generation).
+soup edit diff before after \
+  --before-model ./base --after-model ./edited \
+  --probes probes.jsonl --output diff.json
 ```
 
-Sequential edit governor auto-switches **ROME → AlphaEdit** at edit #10 (configurable) AND on detected norm-blowup (`||W - W_base||_F` over threshold). The governor refuses further edits past the per-base-model cap so a runaway script can't quietly corrupt your checkpoint.
+The kernels are a covariance-free (`C = I`) variant of the ROME family — well-defined, tractable on a 4 GB box, and validated on SmolLM2-135M (a ROME edit moved `P("Lyon" | "The capital of France is")` from 0.0016 → 0.96). **ROME** edits a single layer; **MEMIT** distributes the residual across a layer band; **AlphaEdit** projects the update orthogonal to the down-proj's top singular direction.
 
-The live ROME / MEMIT / AlphaEdit kernel + before/after generation in `edit diff` land in the next patch; `--plan-only` and the schema surface ship today so soup.yaml and CI invocations are stable.
+The sequential edit governor is persisted (SQLite, cross-process-locked, `SOUP_EDIT_GOVERNOR_DB` override) so the per-base-model edit count + norm-blowup verdict survive across separate `soup edit set` runs. `soup edit set` consults it automatically: it refuses BEFORE the model load past the per-base cap or after a BLOWUP verdict, and records the measured `||ΔW||_F` after each edit. Pass `--no-governor` to opt out. `--registry-id <id>` attaches the edited model (or GRACE codebook) into the Registry lineage.
 
 
 ## Activation Steering (`soup steer`)
@@ -179,6 +184,8 @@ soup steer list
 
 Steering names are validated against a strict regex (`^[A-Za-z0-9][A-Za-z0-9._\-]{0,127}$` — no path separators, no shell metacharacters); strength is bounded `|s| <= 10.0`. The trained vectors land in the Soup Registry under the `steering_vector` artifact kind so lineage is preserved.
 
+As of v0.71.10 the fit and the decode hook are **live** (validated on SmolLM2-135M): `soup steer train` captures residual-stream activations (CAA / RepE) or per-head `o_proj`-input activations (ITI) on the contrastive pairs, computes the control vector, and persists `steering_vector.safetensors` + `steering_config.json`. `soup serve --steer <name>` installs a forward hook on the loaded model that adds `strength × vector` at decode time (transformers backend; `--steer` is rejected with a clear error on vLLM/SGLang). RepE / ITI need at least two contrastive pairs; CAA works from one.
+
 
 ## GRACE Codebook — Lifelong Knowledge Edits
 
@@ -197,7 +204,7 @@ training:
   grace_codebook_dim: 768      # residual-stream width
 ```
 
-`grace` joins the existing `rome` / `memit` / `alphaedit` allowlist on `soup edit set`; the v0.61.0 sequential edit governor still gates the call when the per-base-model edit count or norm-blowup verdict trips.
+`grace` joins the existing `rome` / `memit` / `alphaedit` allowlist on `soup edit set`; the sequential edit governor still gates the call when the per-base-model edit count or norm-blowup verdict trips. GRACE is live: `soup edit set --method grace --output ./ckpt` captures the residual key at the subject's last token, optimises a replacement value, and appends a `(key, value)` triple to a `grace_codebook.json` sidecar (atomic, cwd-contained). At inference the codebook is applied via a forward hook that substitutes the residual whenever it falls within an epsilon ball of a stored key — so the base weights are never modified and thousands of edits survive without norm blowup.
 
 
 ## Model Registry & Lineage

{soup_cli-0.71.8 → soup_cli-0.71.10}/docs/commands.md

@@ -168,8 +168,15 @@ soup can pack --entry-id <id> --out r.can --attest <statement.json>  Embed in-to
 soup audit-log tail / rotate  Tail / rotate the per-command HIPAA/SOC2 audit log (~/.soup/audit.jsonl)
 soup --no-audit-log <cmd> / SOUP_NO_AUDIT_LOG=1  Opt out of the per-command audit line
 soup eval unlearning <run-id> --benchmark tofu|muse|wmdp  Forget Quality + Model Utility + PrivLeak verdict
-soup edit set --base <m> --method rome|memit|alphaedit --subject "..." --target "..."  Surgical knowledge edit (--plan-only available)
-soup edit diff <before-run> <after-run> --probes p.jsonl  Knowledge-injection diff visualizer
+soup edit set --base <m> --method rome|memit|alphaedit|grace --subject "..." --target "..." [--output <dir>] [--device cpu] [--governor/--no-governor] [--registry-id <id>]  Live surgical knowledge edit (--plan-only available)
+soup edit diff <before-run> <after-run> --probes p.jsonl [--before-model <m> --after-model <m>]  Knowledge-injection diff (live before/after generation when both models given)
+soup train --task unlearn  NPO/SimNPO/RMU unlearning from data.forget_set (+ optional data.retain_set)
+soup train  # data.format='raft'  Answer-only span-mask RAFT training (golden+distractor docs, [doc-N] citations); generator-stage configs auto-link the latest RA-DIT retriever
+soup ra-dit --retriever-config <r.yaml> --generator-config <g.yaml> [--retriever-model <m>] [--plan-only]  One-shot two-stage RA-DIT: train retriever → record pairing → train generator
+soup eval citation <data> [--style bracket|inline|footnote] [--shuffle-seed N] [--output o.json]  Citation precision/recall/F1 over predictions or RAFT rows
+soup steer train --base <m> --method caa|iti|repe --name <id> --pairs <jsonl>  Fit a CAA/ITI/RepE activation-steering vector from {positive, negative} pairs
+soup steer apply --name <id> --strength <s>  Preview a stored steering vector; soup steer list lists them
+soup serve --steer <name> [--steer-strength <s>]  Apply a steering vector at decode time via a forward hook (transformers backend)
 soup ingest --source langfuse|langsmith|helicone|openpipe|otel|openai-stored --logs <jsonl>  Universal trace importer (6 SaaS adapters → normalised JSONL)
 soup prune-prompt --input <jsonl> --output <jsonl> --min-frequency 0.95  Detect + strip shared system-prompt prefix
 soup prune-prompt ... --tokenizer <id-or-path>  Tokenizer-aware prefix detection (decodes remaining ids, boundary-safe)

{soup_cli-0.71.8 → soup_cli-0.71.10}/docs/evaluation.md

@@ -253,7 +253,7 @@ Default threshold 0.2 matches v0.43.0 KL-delta quant-check thresholds. Webhooks
 
 ## Diagnose (Post-Training Report Card)
 
-`soup diagnose` scores six independent failure modes for a trained adapter and renders an OK / MINOR / MAJOR verdict per mode plus an overall headline — same taxonomy as Quant-Lobotomy. Useful for catching adapter regressions that a loss curve cannot distinguish from a healthy run.
+`soup diagnose` scores seven independent failure modes for a trained adapter and renders an OK / MINOR / MAJOR verdict per mode plus an overall headline — same taxonomy as Quant-Lobotomy. Useful for catching adapter regressions that a loss curve cannot distinguish from a healthy run.
 
 ```bash
 # Neutral report (no model load — runs as a sanity check)
@@ -279,7 +279,7 @@ soup diagnose my-run-id --output diag.json --attach-to-registry abc123
 a built-in probe set; `format` only fires when the dataset's own targets look like JSON;
 `contamination` stays neutral unless a benchmark corpus is supplied. Validated on SmolLM2-135M.
 
-**Six failure-mode probes:**
+**Seven failure-mode probes:**
 
 | Mode | What it catches | Score range |
 |------|-----------------|-------------|
@@ -289,6 +289,7 @@ a built-in probe set; `format` only fires when the dataset's own targets look li
 | `mode_collapse` | Diversity collapse at T=0 and T=1 | pairwise n-gram Jaccard distance |
 | `memorization` | Verbatim training-prefix echo on partial prompts | 1 − echo_rate |
 | `contamination` | Training data overlapping public benchmarks | 1 − contamination_rate |
+| `citation` | RAFT model stopped citing the supporting `[doc-N]` (v0.71.10) | fraction of answers citing the golden doc |
 
 **Verdict pill colours:** OK (≥ 0.85) green / MINOR (≥ 0.60) amber / MAJOR (< 0.60) red. `soup diagnose` exits 2 when the overall verdict is MAJOR — wire into CI to fail the build on regression.
 

{soup_cli-0.71.8 → soup_cli-0.71.10}/docs/training.md

@@ -101,22 +101,27 @@ GDPR right-to-be-forgotten + CSAM/PII leak response, productized. Three method b
 
 ```yaml
 # unlearn.yaml
-base: meta-llama/Llama-3.1-8B-Instruct
+base: HuggingFaceTB/SmolLM2-135M
 task: unlearn
 data:
   train: traces.jsonl
-  forget_set: gdpr_deletion_set.jsonl
-  retain_set: capability_anchors.jsonl
+  forget_set: gdpr_deletion_set.jsonl   # rows to unlearn (messages / prompt+completion / text)
+  retain_set: capability_anchors.jsonl  # optional — anchors general capability
 training:
   unlearn_method: npo           # or simnpo / rmu
   unlearn_alpha: 0.5            # retain-set weighting [0.0, 10.0]
 ```
 
 ```bash
+# Run the unlearn loop (validated on SmolLM2-135M — NPO/SimNPO drive forget loss down).
+soup train --config unlearn.yaml --yes
+
 # Score the run on TOFU / MUSE / WMDP (OK / MINOR / MAJOR verdict).
 soup eval unlearning <run-id> --benchmark tofu --evidence evidence.json --output report.json
 ```
 
+`soup train --task unlearn` is live (v0.71.9): it loads a LoRA-wrapped policy, a frozen reference copy (NPO / RMU), and the forget / retain JSONL sets, then optimises the per-method loss — NPO's `(2/β)·mean(-logσ(-β·(π_logp − ref_logp)))` drives the policy's forget-set log-prob below the reference (= forgetting), while the retain set anchors capability. Run NPO/SimNPO **with** a `retain_set` — without one the policy has no utility anchor and Soup warns loudly.
+
 Three orthogonal axes: **Forget Quality** (pre/post forget-loss delta), **Model Utility** (retain-accuracy preserved), **PrivLeak** (membership-inference AUC distance from 0.5). Bundled mini-fixtures for all three benchmarks ship in the box (v0.71.1 added MUSE + WMDP alongside the existing TOFU set), so `--benchmark muse|wmdp` runs without supplying evidence. The WMDP forget-set probes ship **redacted** (placeholder prompts + `REFUSED` responses) — Soup never bundles verbatim hazardous-knowledge content.
 
 
@@ -881,6 +886,19 @@ score = score_citations(
 
 Citation-faithful FT is gated to `task in {sft, pretrain}` + `data.format='raft'` — misconfigured runs fail at config load with a named-field message.
 
+Under the hood, a `format: raft` run trains **answer-only**: each row is composed into a prompt (golden + distractor docs, shuffled deterministically by `data.raft_shuffle_seed`, each labelled `[doc-N]`) followed by the answer; the prompt span is masked out of the loss and — when `citation_faithful: true` — the bracketed `[doc-id]` spans in the answer get a boosted per-token loss weight. Rows whose prompt fills `max_length` (answer fully truncated) are dropped with a warning rather than silently shrinking the dataset.
+
+Score a trained model's citations from the CLI:
+
+```bash
+# {predicted, expected_ids} rows, OR RAFT rows scored against their own golden [doc-N]
+soup eval citation preds.jsonl --style bracket
+# RAFT rows: pass the train-time shuffle seed so the golden id lines up
+soup eval citation raft.jsonl --shuffle-seed 0 --output citation.json
+```
+
+`soup diagnose` also gains a `citation` failure mode that flags a model that stopped citing the supporting document.
+
 
 ## RA-DIT — Retrieval-Augmented Dual Instruction Tuning
 
@@ -898,6 +916,16 @@ soup train
 
 The schema enforces stage-task pairing — `ra_dit_stage: retriever` requires `task: embedding`; `ra_dit_stage: generator` requires `task: sft`. A misconfigured recipe fails at config load with a named-field message.
 
+Run both stages in one command with `soup ra-dit`:
+
+```bash
+soup ra-dit --retriever-config retriever.yaml --generator-config generator.yaml
+# preview the plan + the resolved retriever link without training:
+soup ra-dit -r retriever.yaml -g generator.yaml --plan-only
+```
+
+It trains the retriever, then **records** that trained retriever as the generator's paired retriever (writing its output dir into the generator's `training.ra_dit_retriever_model`) and trains the generator RAFT-style. The recorded retriever is the one used at deploy/serve time — stage-2 does not fuse the retriever weights. A plain `soup train` of a generator-stage config with no retriever model set **auto-links** the most-recent RA-DIT retriever run from the Registry; pass `--retriever-model <m>` to override.
+
 
 ## Curriculum-Aware Training (BETA)
 

{soup_cli-0.71.8 → soup_cli-0.71.10}/pyproject.toml

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

{soup_cli-0.71.8 → soup_cli-0.71.10}/src/soup_cli/__init__.py

@@ -1,3 +1,3 @@
 """Soup CLI — Fine-tune LLMs in one command."""
 
-__version__ = "0.71.8"
+__version__ = "0.71.10"

{soup_cli-0.71.8 → soup_cli-0.71.10}/src/soup_cli/cli.py

@@ -484,6 +484,15 @@ app.add_typer(
     help="Iterative DPO loop driver (v0.70.0 Part E).",
 )
 
+# v0.71.10 #200 — `soup ra-dit` (two-stage RA-DIT orchestrator).
+from soup_cli.commands import ra_dit as _ra_dit_cmd  # noqa: E402
+
+app.add_typer(
+    _ra_dit_cmd.app,
+    name="ra-dit",
+    help="RA-DIT two-stage orchestrator: retriever -> generator (v0.71.10).",
+)
+
 
 def _rewrite_advise_argv(argv: list) -> list:
     """Inject `run` between `advise` and a non-subcommand first argument.