MakazhanAlpamys/Soup v0.62.0

v0.62.0 — RAG & Activation Steering

on GitHub

What's New

RAG & Activation Steering: cite-your-sources fine-tuning, retrieval-aware recipes, and inference-time control vectors. Closes axis 14 of the roadmap. Schema-only release; live training loops + decode-hook intervention + codebook lookup all land in v0.62.1.

RAFT — Retrieval-Augmented Fine-Tuning

New data.format='raft' row shape {query, golden_doc, distractor_docs, answer} + bundled raft-llama3-8b recipe. Every RAFT field is null-byte-rejected, 64 KiB-capped per field, max 64 distractors per row. Composes with the SFT trainer today; live span-mask training kernel lands in v0.62.1.

RA-DIT — Retrieval-Augmented Dual Instruction Tuning

Two-stage Meta 2023 recipe. ra_dit_stage: retriever trains the contrastive sentence-transformer (uses the v0.16 embedding trainer); ra_dit_stage: generator runs RAFT-style SFT. Schema cross-validator enforces stage→base-task pairing (retriever→embedding, generator→sft). Two new recipes: ra-dit-retriever and ra-dit-llama3-8b.

soup steer — Activation Steering (CAA / ITI / RepE)

Closed-allowlist control-vector methods + Typer subcommands train / apply / list + soup serve --steer <name> --steer-strength <s> flag. Strict name regex (no path separators, no shell metacharacters), |strength| ≤ 10.0 sanity cap. New steering_vector artifact kind on the Registry. apply_steering + build_steering_vector deferred-live stubs raise NotImplementedError with v0.62.1 marker after validating inputs.

Citation-faithful FT

Pure score_citations precision/recall/F1 kernel + public extract_citation_ids API for the eval gate. New training.citation_faithful: bool + citation_style: bracket|inline|footnote + citation_recall_threshold schema. Cross-validator gates citation_faithful=true to data.format='raft' AND task in {sft, pretrain} (silent-no-op footgun rejection mirroring v0.52.0 distill / classifier policy).

GRACE Codebook — Lifelong Knowledge Edits

grace joins the v0.61.0 SUPPORTED_EDIT_METHODS allowlist for soup edit set --method grace. New GraceCodebookConfig with bounded size [1, 100k] + bounded dim [1, 16384] for the discrete latent-space (key, value) store that survives thousands of sequential edits. apply_edit routes grace plans to v0.62.1 marker while legacy rome/memit/alphaedit retain v0.61.1 marker (regression-guarded).

Install / Upgrade

pip install --upgrade soup-cli

Security

• Closed-allowlist validators on every new schema field (SUPPORTED_RA_DIT_STAGES, SUPPORTED_STEERING_METHODS, SUPPORTED_CITATION_STYLES) with bool-first / null-byte / oversize / case-insensitive normalisation.
• RAFT input validation: every field passes through _check_raft_string (non-empty, null-byte-rejected, ≤64 KiB); distractor list capped at 64 per row.
• Steering name regex rejects path separators + shell metacharacters so names are safe as Registry artifact ids + CLI flags + filenames.
• Citation kernel ReDoS-safe: bounded quantifiers, 2 MB predicted-text cap, 10k expected_ids cap.
• soup steer TOCTOU defence: _validate_pairs_path delegates to shared enforce_under_cwd_and_no_symlink helper.
• soup serve --steer Rich markup escape on exception messages.
• Cross-validators reject silent-no-op footguns: citation_style without flag, citation_faithful on non-SFT-family task, grace_codebook_size without flag, ra_dit_retriever_model without stage.
• See SECURITY.md for the full v0.62.0 hardening notes.

Known Limitations

All deliberate stub-then-live deferrals to v0.62.1 (mirroring v0.50.0 / v0.52.0 / v0.61.0 cadence). Schema accepts every flag today so soup.yaml written now will work the moment v0.62.1 ships.

1. RAFT span-mask training kernel deferred to v0.62.1 (schema-only).
2. RA-DIT live two-stage orchestrator deferred to v0.62.1 (operators run each stage manually today).
3. apply_steering decode-hook + build_steering_vector per-method fitting kernels deferred to v0.62.1.
4. apply_grace_codebook lookup/write deferred to v0.62.1.
5. citation_faithful gated to {sft, pretrain} — DPO / GRPO / etc. rejected (deliberate task-gate).
6. extract_citation_ids is bracket-style only; inline / footnote variants schema-validated but use the same extractor today.
7. RA-DIT recipe pair does not auto-link retriever output to generator's ra_dit_retriever_model (operators copy manually).
8. GRACE codebook has no Registry persistence yet — lives only in the trained checkpoint until v0.62.1.
9. soup serve --steer validates name + strength but does not load the vector — decode-hook lands in v0.62.1.
10. soup steer apply is preview-only — live decode-hook ships via soup serve --steer in v0.62.1.

Stats

• Tests: 9571 → 9786 (+215 net) across 6 new test files (test_v0620_part_{a,b,c,d,e}.py + test_v0620_followups.py).
• CI: 9-cell matrix green (ubuntu / windows / macos × py 3.9 / 3.11 / 3.12) + lint + recipe validation.
• Review-fix coverage: 0 CRITICAL + 0 HIGH + 4 MEDIUM + 11 LOW across 4 review-agent waves (code, security, tdd, python style).
• Recipes: 113 → 116 (raft-llama3-8b, ra-dit-retriever, ra-dit-llama3-8b).

Full architecture notes: see .claude/CLAUDE.md (release-internal) and SECURITY.md (public).