soup

name	soup
description	Drive Soup (`soup-cli`), a CLI-first tool for fine-tuning and post-training LLMs with one YAML config and one command — SFT, DPO/GRPO/ORPO/SimPO/KTO, QLoRA/DoRA/LoRA+, layer streaming for 4-8 GB GPUs, eval-gated training, and serving. Use when the user wants to `soup init`/`soup train` a model, pick a training method or quantization scheme, estimate cost/memory before training, fine-tune on a small local GPU, migrate a config from Axolotl/LLaMA-Factory/Unsloth, or serve/merge/push a trained adapter. Triggers on: "soup-cli", "soup train", "soup init", "fine-tune an LLM locally", "QLoRA on a laptop GPU", "layer streaming", "soup advise", "soup autopilot", "DPO/GRPO/ORPO training", "merge LoRA adapter".
allowed-tools	Bash Read Write Edit Glob Grep
compatibility	Python 3.10+. `pip install soup-cli` for the light CLI; `pip install "soup-cli[train]"` adds torch/transformers/peft/trl for actual training. GPU (CUDA or Apple MLX) recommended for training; CPU-only works for init/advise/profile/cost/data commands. Apache-2.0.
metadata	{"tags":"soup, soup-cli, llm-fine-tuning, post-training, sft, dpo, grpo, orpo, qlora, lora, layer-streaming, peft, trl, python","platforms":"Claude, ChatGPT, Gemini, Codex","version":"1.0","source":"https://github.com/MakazhanAlpamys/Soup"}

Soup — one-command LLM fine-tuning

Soup turns fine-tuning into soup init → soup train with a single YAML config: task selection, quantization, batch size, and GPU/backend detection are all handled for you. Its headline feature, layer streaming (stream_layers: true), keeps the frozen base model out of VRAM and streams it one decoder layer at a time, so an 8B model can fine-tune on a 4 GB laptop GPU — measured bit-exact against a normal resident run.

When to use this skill

• Standing up a new fine-tuning run (soup init, soup train) instead of hand-rolling a Transformers/PEFT/TRL training script
• Choosing a training method (SFT vs DPO/GRPO/ORPO/SimPO/KTO/IPO/BCO) or a memory-saving scheme (QLoRA, DoRA, LoRA+, rsLoRA, layer streaming) for a constrained GPU
• Estimating training cost/memory (soup cost, soup profile) before spending GPU hours, or getting a pre-flight method recommendation (soup advise)
• Migrating an existing Axolotl / LLaMA-Factory / Unsloth config into Soup
• Serving, merging, or pushing a trained adapter (soup serve, soup merge, soup push), or running the data-quality/eval tooling (soup data ..., soup ship)

When not to use this skill

• Training infrastructure at the Ray/DeepSpeed-cluster/multi-node scale as the primary concern → use deepspeed or openrlhf-training directly; Soup wraps DeepSpeed/FSDP as launch flags, not a replacement for them
• Pure inference serving of an already-merged model with no training involved → a plain inference-runtime skill is a better fit
• The user is not touching Soup/PEFT/TRL at all (e.g. prompt engineering only) → route to soup advise's own verdict (it may say PROMPT_ENG, not training) rather than jumping straight into soup train

Instructions

Step 1: Install the right profile

bash pip install soup-cli # light CLI only: init/advise/data/profile/cost pip install "soup-cli[train]" # + torch/transformers/peft/trl for real training

Step 2: Decide the method before spending GPU hours

bash soup advise <data.jsonl> --goal "..." # PROMPT_ENG / RAG / SFT / DPO / GRPO verdict soup autopilot --model --data d.jsonl --goal "" # zero-config: picks task/quant/LR/epochs

Do not default straight to soup train; advise/autopilot exist because the wrong method (e.g. SFT when the data is a preference pair) wastes a full run.

Step 3: Scaffold and edit the config

bash soup init --template chat # or code/audio/... — see docs/models.md soup fetch # pull a ready-made example config

For memory-constrained hardware, opt into layer streaming explicitly:

yaml training: stream_layers: true # base streams out of VRAM; only the adapter trains quantization: 4bit # NF4 batch_size: 4 stream_source: auto # RAM when it fits, NVMe disk otherwise

Layer streaming is BETA and supports SFT plus DPO/ORPO/SimPO/KTO — not GRPO/PPO (those re-read every layer per generated token, which defeats streaming's amortisation).

Step 4: Estimate before you commit a GPU

bash soup profile --config soup.yaml --gpu a100 soup cost --config soup.yaml --gpu H100

Step 5: Train, then verify before shipping

bash soup train --config soup.yaml soup train --config soup.yaml --gate evals/gate.yaml # eval-gated soup ship --config soup.yaml # go/no-go verdict

Step 6: Serve, merge, or push the result

bash soup infer --model ./output --input p.jsonl soup chat --model ./output soup merge --adapter ./output soup push --model ./output --repo user/name soup serve --model ./output

Step 7: Use the wrapper for a read-only environment check

bash bash .agent-skills/soup/scripts/soup.sh doctor bash .agent-skills/soup/scripts/soup.sh advise <data.jsonl> --goal "..." bash .agent-skills/soup/scripts/soup.sh profile <config.yaml>

doctor only inspects the environment (Python version, soup install, [train] extras, CUDA/MPS availability) — it never installs packages or starts a training run.

Best practices

1. Run soup advise/soup autopilot before soup train — picking the wrong task family (SFT vs a preference loss) is discovered only after a full training run otherwise.
2. soup cost/soup profile before renting a GPU — cheaper than discovering an OOM or a $40 surprise after the fact.
3. Layer streaming is an opt-in trade, not a default — it trades memory for extra layer-stack reads (DPO reads it ~1.52× as often as SFT); confirm the method is on the supported list (SFT/DPO/ORPO/SimPO/KTO) before enabling it.
4. Gate before you ship — prefer --gate evals/gate.yaml and soup ship over eyeballing loss curves.
5. Heavy deps stay lazy — don't suggest importing torch/transformers/ peft/trl at module top in scripts driving Soup; the project itself lazy-imports them so the light CLI stays fast.
6. Migrate configs, don't hand-port them — soup migrate --from axolotl|llamafactory|unsloth exists precisely to avoid manual config translation errors.

References

• references/commands.md — curated command reference by workflow stage
• scripts/soup.sh — read-only doctor + thin advise/profile/cost wrappers
• Soup GitHub Repository
• Soup docs index
• Project standards: .agent-skills/skill-standardization/SKILL.md

Examples

Example 1: Pick a method, then fine-tune on a 4 GB laptop GPU

bash soup advise data.jsonl --goal "make the model follow a strict output schema" soup init --template chat

soup.yaml: set stream_layers: true, quantization: 4bit

soup profile --config soup.yaml soup train --config soup.yaml

Example 2: Environment check before recommending a training path

bash bash .agent-skills/soup/scripts/soup.sh doctor