soup/soup_cli/utils
Alpamys 55d1b9312c feat(speed,memory): v0.28.0 features go multi-trainer (v0.33.0 Part C)
Closes #43, #44, #47.

#43 Multi-trainer wiring (sft/dpo/pretrain):
- New utils/v028_features.apply_v028_speed_memory(model, tcfg, base_model,
  console) — single shared helper for use_cut_ce, quantization_aware="fp8",
  kernel_auto_compose. Each feature degrades silently to a yellow advisory
  if the underlying lib is missing; never crashes training kick-off.
- Helpers supports_v028_features(task) and warn_unsupported_features(tcfg, task)
  drive both the schema validator and runtime advisories.
- soup_cli/trainer/dpo.py and trainer/pretrain.py now call the helper after
  model load (post-LoRA, post-QAT) — same hook point as SFT.
- soup_cli/config/schema.py validator
  _validate_v028_speed_memory_sft_only renamed
  _validate_v028_speed_memory_supported_tasks; allowlist now {sft, dpo,
  pretrain}. GRPO/KTO/ORPO/SimPO/IPO/PPO/RewardModel/Embedding still error
  out at config-load with a precise multi-trainer message.

#44 Selective gradient-checkpoint hooks:
- New utils/gradient_ckpt.install_selective_hooks(model, granularity)
  iterates ``model.named_modules()`` looking for transformer-block-shaped
  names (numeric suffix on layer path), wraps each module's ``forward``
  with torch.utils.checkpoint.checkpoint based on tier:
    - selective: only attention sub-modules
    - medium: every second transformer block
    - full: every transformer block
- Returns hook count so callers can fall back to HF native checkpointing
  when zero blocks were found.

#47 CrossDocCollator:
- New soup_cli/data/collators.CrossDocCollator wraps any base data
  collator and injects a block-diagonal causal ``cross_doc_attn_mask``
  built from per-example ``doc_lengths``. Preferred over TRL's
  ``packing_strategy="attention_free"`` flag (best-effort across TRL
  versions). Degrades gracefully when doc_lengths is missing or shapes
  don't match — base attention_mask preserved, no crash.

Tests: +16 in tests/test_part_c.py covering apply_v028_speed_memory
(no-features, cut_ce graceful failure), supports/warn helpers extension,
schema gate (dpo + pretrain accept, kto still rejects), selective hook
installation across full/medium/selective with fake transformer-shaped
models, CrossDocCollator passthrough + strip + injection. One existing
test in test_training_speed.py updated: dpo+use_cut_ce now accepted.

Known limitations:
- 7 trainers (GRPO/KTO/ORPO/SimPO/IPO/PPO/RewardModel/Embedding) still
  reject v0.28.0 flags at config-load. Each is a 5-line addition once
  schema validation is satisfied; tracked as a v0.33.x follow-up.
- install_selective_hooks doesn't undo earlier hooks — caller must be
  re-init aware. Not an issue for the typical "construct wrapper, train,
  exit" flow but worth noting.
- CrossDocCollator emits ``cross_doc_attn_mask`` (not ``attention_mask``)
  to avoid clobbering the base collator's contract; downstream consumers
  must read the new key explicitly. The plan calls for "preferred over
  TRL's packing_strategy" which we satisfy via opt-in collation, not
  silent override.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-27 18:55:50 +05:00
..
__init__.py Initial project setup: CLI skeleton + config + trainer + data pipeline 2026-02-20 16:14:56 +05:00
activation_offload.py feat(training): Training Speed & Memory — CCE, FP8, grad-ckpt tiers, kernel picker, cross-doc attn, activation offload (v0.28.0) 2026-04-22 22:51:15 +05:00
auto_quant.py feat(serve): structured-output + auto-quant live (v0.33.0 Part D) 2026-04-27 18:43:07 +05:00
constants.py feat: add GitHub repo link to CLI output, bump version to v0.17.3 2026-03-26 15:48:04 +05:00
convergence.py feat(training): v0.32.0 — Training Stability & Auto-Tuning 2026-04-26 15:24:31 +05:00
cross_doc_attn.py feat(training): Training Speed & Memory — CCE, FP8, grad-ckpt tiers, kernel picker, cross-doc attn, activation offload (v0.28.0) 2026-04-22 22:51:15 +05:00
curriculum.py feat: v0.23.0 — AWQ/GPTQ Export, Sample Packing, Data Split, Curriculum Learning 2026-04-03 13:55:01 +05:00
cut_ce.py feat(training): Training Speed & Memory — CCE, FP8, grad-ckpt tiers, kernel picker, cross-doc attn, activation offload (v0.28.0) 2026-04-22 22:51:15 +05:00
deepspeed.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
errors.py v0.10.3: Fix PPO trl >=0.28 API compat, improve GRPO CPU error message 2026-03-24 14:27:39 +05:00
flash_attn.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
fp8.py feat(training): Training Speed & Memory — CCE, FP8, grad-ckpt tiers, kernel picker, cross-doc attn, activation offload (v0.28.0) 2026-04-22 22:51:15 +05:00
freeze.py feat: v0.24.0 — Dataset Hub, Freeze Training, Loss Watchdog, Dataset Registry 2026-04-03 16:35:23 +05:00
fsdp.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
galore.py v0.12.0: ORPO/SimPO/IPO trainers + DoRA/LoRA+/GaLore 2026-03-25 18:12:36 +05:00
gpu.py v0.10.1: Fix 6 bugs from manual testing report 2026-03-24 12:31:37 +05:00
grad_accum.py feat(training): v0.32.0 — Training Stability & Auto-Tuning 2026-04-26 15:24:31 +05:00
gradient_ckpt.py feat(speed,memory): v0.28.0 features go multi-trainer (v0.33.0 Part C) 2026-04-27 18:55:50 +05:00
hf.py feat(hf): v0.29.0 — HuggingFace Hub Deep Integration 2026-04-23 16:17:28 +05:00
kernel_picker.py feat(training): Training Speed & Memory — CCE, FP8, grad-ckpt tiers, kernel picker, cross-doc attn, activation offload (v0.28.0) 2026-04-22 22:51:15 +05:00
launcher.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
liger.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
long_context.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
lr_finder.py feat(training): stability auto-tuning live (v0.33.0 Part E) 2026-04-27 18:33:39 +05:00
metrics.py feat(inference): v0.30.0 — Inference Excellence 2026-04-24 23:39:04 +05:00
mii.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
mixed_precision.py feat(training): v0.32.0 — Training Stability & Auto-Tuning 2026-04-26 15:24:31 +05:00
mlx.py feat(v0.25.0): Beyond the Wrapper — 8 major features 2026-04-13 12:58:11 +05:00
moe.py feat: v0.14.0 — pre-training + MoE support 2026-03-25 22:26:01 +05:00
ollama.py feat: add Ollama integration — deploy GGUF models in one command (v0.18.0) 2026-04-01 13:47:40 +05:00
paths.py feat(v0.26.0): Parts B-E — Eval Gate, Trace-to-Pref, Quant-Check, Soup Cans 2026-04-20 21:37:05 +05:00
peft_builder.py feat(v0.25.0): Beyond the Wrapper — 8 major features 2026-04-13 12:58:11 +05:00
pipeline.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
profiler.py fix: v0.24.1 — Windows Unicode fix, AWQ/GPTQ output path traversal 2026-04-03 23:41:44 +05:00
qat.py Add Quantization-Aware Training support (Phase 7) — v0.6.0 2026-03-23 20:35:35 +05:00
quality.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
registry.py feat: v0.24.0 — Dataset Hub, Freeze Training, Loss Watchdog, Dataset Registry 2026-04-03 16:35:23 +05:00
ring_attention.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
sglang.py fix: rename APIs to match test plan, fix RoPE factor detection 2026-03-26 15:14:24 +05:00
spec_pairing.py feat(inference): v0.30.0 — Inference Excellence 2026-04-24 23:39:04 +05:00
spike_recovery.py feat(training): v0.32.0 — Training Stability & Auto-Tuning 2026-04-26 15:24:31 +05:00
structured_output.py feat(serve): structured-output + auto-quant live (v0.33.0 Part D) 2026-04-27 18:43:07 +05:00
topology.py feat(v0.27.0): Multi-GPU Mastery — topology, ZeRO++, FSDP2+compile, MII, PP, recipes 2026-04-21 14:54:34 +05:00
tracing.py feat(inference): v0.30.0 — Inference Excellence 2026-04-24 23:39:04 +05:00
unsloth.py Add Unsloth backend for 2-5x faster training (Phase 5) — v0.4.3 2026-03-23 16:55:44 +05:00
v028_features.py feat(speed,memory): v0.28.0 features go multi-trainer (v0.33.0 Part C) 2026-04-27 18:55:50 +05:00
vllm.py feat(inference): v0.30.0 — Inference Excellence 2026-04-24 23:39:04 +05:00
warmup.py feat(training): v0.32.0 — Training Stability & Auto-Tuning 2026-04-26 15:24:31 +05:00