From c0ed2f376b5e5ca3fae840de2f8e30b56c8c5699 Mon Sep 17 00:00:00 2001 From: Alpamys Date: Thu, 5 Mar 2026 19:30:12 +0500 Subject: [PATCH] Polish README: add extras table, fix badge, clean up commands list - Replace hardcoded "321 passed" badge with "passing" - Add Optional Extras table (serve, data, eval, deepspeed, dev) - Add note that --verbose must go before command name - Mention CSV/Parquet support in Data Formats - Add Changelog section linking to GitHub Releases - Remove duplicate commands from All Commands (resume, wandb, deepspeed variants) - Remove runs delete from commands list (rarely used) Co-Authored-By: Claude Opus 4.6 --- README.md | 54 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 33 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 8b99fe7..c47c31e 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ PyPI Python 3.9+ MIT License - Tests + Tests CI

@@ -361,9 +361,11 @@ soup --verbose train --config soup.yaml soup --verbose eval --model ./output --benchmarks mmlu ``` +> **Note:** `--verbose` is a global flag — it must go **before** the command name, not after. + ## Data Formats -Soup supports these formats (auto-detected): +Soup supports these formats (auto-detected). Files can be JSONL, JSON, CSV, or Parquet. **Alpaca:** ```json @@ -476,34 +478,30 @@ soup eval --model ./output --benchmarks mmlu --run-id run_20260223_143052_a1b2 ## All Commands ``` -soup init [--template chat|code|medical] Create soup.yaml config -soup train --config soup.yaml [--dry-run] Start training -soup train --resume auto Resume from last checkpoint -soup train --wandb Train with W&B logging -soup chat --model ./output Interactive chat with model -soup push --model ./output --repo user/name Upload to HuggingFace Hub +soup init [--template chat|code|medical] Create config +soup train --config soup.yaml Start training +soup chat --model ./output Interactive chat +soup push --model ./output --repo user/name Upload to HuggingFace soup merge --adapter ./output Merge LoRA with base model soup export --model ./output --format gguf Export to GGUF (Ollama) +soup eval --model ./output --benchmarks mmlu Evaluate on benchmarks +soup serve --model ./output --port 8000 OpenAI-compatible API server +soup sweep --config soup.yaml --param lr=... Hyperparameter search +soup diff --model-a ./a --model-b ./b Compare two models soup data inspect View dataset stats soup data validate --format alpaca Check format soup data convert --to chatml Convert between formats soup data merge data1.jsonl data2.jsonl Combine datasets soup data dedup --threshold 0.8 Remove duplicates (MinHash) soup data stats Extended statistics -soup runs List all training runs -soup runs show Detailed run info + loss graph -soup runs compare Compare two runs -soup runs delete Remove a run -soup eval --model ./output --benchmarks mmlu Evaluate on benchmarks -soup serve --model ./output --port 8000 OpenAI-compatible API server -soup sweep --config soup.yaml --param lr=... Hyperparameter search -soup diff --model-a ./a --model-b ./b Compare two models soup data generate --prompt "..." --count 100 Generate synthetic data -soup train --deepspeed zero2 Multi-GPU with DeepSpeed -soup doctor Check environment & dependencies -soup quickstart [--dry-run] Full demo: create data + config + train +soup runs List training runs +soup runs show Run details + loss graph +soup runs compare Compare two runs +soup doctor Check environment +soup quickstart [--dry-run] Full demo soup version Show version -soup --verbose Show full traceback on errors +soup --verbose Full traceback on errors ``` ## Requirements @@ -512,6 +510,16 @@ soup --verbose Show full traceback on errors - GPU with CUDA (recommended) or Apple Silicon (MPS) or CPU (slow) - 8 GB+ VRAM for 7B models with QLoRA +### Optional Extras + +| Extra | Install | What it adds | +|---|---|---| +| `serve` | `pip install 'soup-cli[serve]'` | Inference server (FastAPI + uvicorn) | +| `data` | `pip install 'soup-cli[data]'` | Deduplication (MinHash via datasketch) | +| `eval` | `pip install 'soup-cli[eval]'` | Benchmark evaluation (lm-evaluation-harness) | +| `deepspeed` | `pip install 'soup-cli[deepspeed]'` | Multi-GPU training (DeepSpeed ZeRO) | +| `dev` | `pip install 'soup-cli[dev]'` | Tests + linting (pytest, ruff) | + ## Development ```bash @@ -522,13 +530,17 @@ pip install -e ".[dev]" # Lint ruff check soup_cli/ tests/ -# Run unit tests (fast, no GPU needed — 321 tests) +# Run unit tests (fast, no GPU needed) pytest tests/ -v # Run smoke tests (downloads tiny model, runs real training) pytest tests/ -m smoke -v ``` +## Changelog + +See [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases) for version history. + ## License MIT