Autopilot

soup autopilot is the zero-config entry point added in v0.25.0. You pass a model, a dataset, and a goal. Autopilot profiles the dataset, model, and GPU, then emits a soup.yaml with every hyperparameter chosen and justified.

Quick start

soup autopilot \
  --model meta-llama/Llama-3.1-8B \
  --data chats.jsonl \
  --goal chat \
  --gpu-budget 24GB

Inputs

--model, --data and --goal are all required. There is no way to pass a task: choosing one is what Autopilot is for.

What Autopilot decides

1. Task — maps goal → SFT / DPO / GRPO / pretrain, including the tool-calling format where appropriate. Those four are the whole range: the seven goals above map to sft (chat, code, classification, tool-calling), grpo (reasoning), dpo (alignment) and pretrain (domain-adapt).
2. Quantization — chooses none, 8bit or 4bit from the model size against your VRAM budget: none at 5 GB or more per billion parameters, 8bit from 3 GB, 4bit from 1.2 GB, and an error below that. A base that is already quantized (GPTQ, AWQ and similar) keeps its own format instead.
3. PEFT — picks LoRA r=8/16/32 from dataset size, and turns on DoRA when the data is large and the VRAM headroom allows it. It does not select VeRA, and it does not turn LoRA off.
4. Batch size × grad_accum — estimates the per-device batch size from VRAM, then sets gradient accumulation to 32 // batch (at least 1), so the effective batch is about 32.
5. Learning rate — scales with rank and quantization (e.g. LoRA r=16 → 2e-4, 4bit → ×0.8).
6. Epochs — 5 → 3 → 2 → 1 depending on dataset size.
7. max_length — the dataset's p95 token length times 1.1, rounded down, at least 256 and clamped to the model context.
8. Perf flags — turns on FlashAttention and Liger Kernel when the GPU is Ampere or newer (compute capability 8.0 or higher), and gradient_checkpointing when max_length is above 8192 or the VRAM headroom (the budget minus 2 GB per billion parameters) is positive but under 4 GB. It does not choose a backend: backend: mlx is something you set yourself.
9. Training intelligence — writes forgetting_detection, checkpoint_intelligence and early_stop_on_regression as true into the config. They are accepted by the schema, but nothing in v0.75.2 reads them during training: soup train prints "set but not enforced during training in this build". For a check that does run, add --gate (see Training intelligence).

Autopilot prints its decisions in a Rich panel before it writes anything, and --dry-run stops there. The panel lists the values it chose, not a reason for each one, and it prints no time or VRAM estimate.

Example output

The command prints a summary panel (dataset, model, hardware, goal) and then the decisions. Here is the second one for a 15,000-row chat dataset, an 8B model, --gpu-budget 24GB and an Ampere-or-newer GPU:

╭───── Autopilot Decisions ─────╮
│ Quantization: 8bit            │
│ PEFT: LoRA r=32, alpha=64     │
│ Batch size: 1 x grad_accum 32 │
│ Learning rate: 0.0001         │
│ Epochs: 2                     │
│ Max length: 2002              │
│ Flash Attention: True         │
│ Liger Kernel: True            │
│ Forgetting detection: True    │
│ Checkpoint intelligence: True │
╰───────────────────────────────╯
Config written: /home/you/project/soup.yaml

Safety

• Dataset and output paths are resolved and constrained to the working directory (no path traversal).
• GPU budget is bounded to 1GB–1TB; there is no time budget: --gpu-budget is the only budget the command accepts.
• Model names are validated against HuggingFace Hub naming rules.
• Model code is never executed during analysis — Autopilot uses HF Hub metadata only.

See also

• Training methods
• Backends — including MLX
• Training intelligence — the forgetting-detection and checkpoint options, and which of them are enforced
• Recipes — start here if you don't need Autopilot