About

Imported from akillness/jeo-skills (.agent-skills/soup/SKILL.md). Install upstream with npx skills add akillness/jeo-skills --skill soup. Copyright stays with the author.

Soup — one-command LLM fine-tuning

Name: soup
Author: akillness

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

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.
soup cost/soup profile before renting a GPU — cheaper than discovering an OOM or a $40 surprise after the fact.
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.
Gate before you ship — prefer --gate evals/gate.yaml and soup ship over eyeballing loss curves.
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.
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

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/akillness-jeo-skills-soup/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

akillness-jeo-skills-soup.ocm.jsonjson

{
  "ocm": "1",
  "id": "akillness-jeo-skills-soup",
  "kind": "skill",
  "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\".",
  "publisher": "akillness",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "math"
    ],
    "tags": [
      "skill-md",
      "soup",
      "soup-cli",
      "llm-fine-tuning",
      "post-training",
      "sft",
      "dpo",
      "grpo",
      "orpo",
      "qlora"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "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\"."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/akillness/jeo-skills",
      "path": ".agent-skills/soup/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/akillness/jeo-skills/blob/HEAD/.agent-skills/soup/SKILL.md",
      "key": "akillness/jeo-skills/.agent-skills/soup/SKILL.md"
    },
    "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",
    "allowed_tools": [
      "Bash",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ]
  },
  "instructions": "# Soup — one-command LLM fine-tuning\n\nSoup turns fine-tuning into `soup init` → `soup train` with a single YAML\nconfig: task selection, quantization, batch size, and GPU/backend detection\nare all handled for you. Its headline feature, **layer streaming**\n(`stream_layers: true`), keeps the frozen base model out of VRAM and streams\nit one decoder layer at a time, so an 8B model can fine-tune on a 4 GB laptop\nGPU — measured bit-exact against a normal resident run.\n\n## When to use this skill\n\n- Standing up a new fine-tuning run (`soup init`, `soup train`) instead of\n  hand-rolling a Transformers/P",
  "cost": {
    "context_tokens": 1498
  }
}

Fetch it by URL: GET /api/v1/registry/akillness-jeo-skills-soup/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.