{"id":46244646,"url":"https://github.com/makazhanalpamys/soup","last_synced_at":"2026-06-01T09:00:59.247Z","repository":{"id":339579211,"uuid":"1162516847","full_name":"MakazhanAlpamys/Soup","owner":"MakazhanAlpamys","description":"Soup turns the pain of LLM fine-tuning into a simple workflow. One config, one command, done.","archived":false,"fork":false,"pushed_at":"2026-05-30T08:02:36.000Z","size":3656,"stargazers_count":65,"open_issues_count":113,"forks_count":14,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-30T10:05:51.207Z","etag":null,"topics":["artificial-intelligence","cli","dpo","fine-tuning","finetuning","gguf","huggingface","llm","llmops","local-llm","lora","machine-learning","model-finetuning","ollama","peft","python","pytorch","qlora","sft","transformers"],"latest_commit_sha":null,"homepage":"https://trysoup.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MakazhanAlpamys.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"MakazhanAlpamys"}},"created_at":"2026-02-20T11:05:01.000Z","updated_at":"2026-05-30T08:02:40.000Z","dependencies_parsed_at":"2026-04-30T09:02:40.144Z","dependency_job_id":"8cac5057-9143-4b4a-b0ab-2e9c4b74ce89","html_url":"https://github.com/MakazhanAlpamys/Soup","commit_stats":null,"previous_names":["makazhanalpamys/soup"],"tags_count":125,"template":false,"template_full_name":null,"purl":"pkg:github/MakazhanAlpamys/Soup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakazhanAlpamys%2FSoup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakazhanAlpamys%2FSoup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakazhanAlpamys%2FSoup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakazhanAlpamys%2FSoup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MakazhanAlpamys","download_url":"https://codeload.github.com/MakazhanAlpamys/Soup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MakazhanAlpamys%2FSoup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33767439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","cli","dpo","fine-tuning","finetuning","gguf","huggingface","llm","llmops","local-llm","lora","machine-learning","model-finetuning","ollama","peft","python","pytorch","qlora","sft","transformers"],"created_at":"2026-03-03T21:05:08.544Z","updated_at":"2026-06-01T09:00:59.240Z","avatar_url":"https://github.com/MakazhanAlpamys.png","language":"Python","funding_links":["https://github.com/sponsors/MakazhanAlpamys"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"soup.png\" alt=\"Soup\" width=\"280\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eSoup\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eFine-tune LLMs in one command. No SSH, no config hell.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://trysoup.dev\"\u003eWebsite\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#configuration\"\u003eConfig\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#documentation\"\u003eDocs\u003c/a\u003e \u0026middot;\n  \u003ca href=\"docs/commands.md\"\u003eCommands\u003c/a\u003e \u0026middot;\n  \u003ca href=\"docs/models.md\"\u003eModels\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/soup-cli/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/soup-cli?color=blue\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pepy.tech/project/soup-cli\"\u003e\u003cimg src=\"https://img.shields.io/pepy/dt/soup-cli?color=blue\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue\" alt=\"Python 3.10+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-Apache--2.0-blue\" alt=\"Apache-2.0 License\"\u003e\n  \u003ca href=\"https://github.com/MakazhanAlpamys/Soup/actions\"\u003e\u003cimg src=\"https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/MakazhanAlpamys/65fdc943f85f3b2c46ecddb415c2b779/raw/soup_tests.json\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MakazhanAlpamys/Soup/actions\"\u003e\u003cimg src=\"https://github.com/MakazhanAlpamys/Soup/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://trysoup.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/website-trysoup.dev-blue\" alt=\"Website\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nSoup turns the pain of LLM fine-tuning into a simple workflow. One config, one command, done.\n\n```bash\npip install 'soup-cli[train]'   # add [train] to fine-tune; bare `soup-cli` is the light CLI\nsoup init --template chat\nsoup train\n```\n\n## Why Soup?\n\nTraining LLMs is still painful. Even experienced teams spend 30-50% of their time fighting\ninfrastructure instead of improving models. Soup fixes that.\n\n- **Zero SSH.** Never SSH into a broken GPU box again.\n- **One config.** A simple YAML file is all you need.\n- **Auto everything.** Batch size, GPU detection, quantization — handled.\n- **Works locally.** Train on your own GPU with QLoRA. No cloud required.\n\n## What's New\n\n**v0.71.0 — Lighter install.** The heavy training stack (PyTorch, Transformers, PEFT, TRL,\ndatasets, bitsandbytes, accelerate) moved into a `[train]` extra. `pip install soup-cli` is now a\nlight CLI + data-tools install with no PyTorch; `pip install 'soup-cli[train]'` adds everything you\nneed to fine-tune. **Breaking:** existing users who train must reinstall with `[train]`.\n\nFull history: [CHANGELOG.md](CHANGELOG.md) \u0026middot; [GitHub Releases](https://github.com/MakazhanAlpamys/Soup/releases).\n\n## Quick Start\n\n### 1. Install\n\n```bash\npip install soup-cli            # light: CLI + config + data tools (no PyTorch)\npip install 'soup-cli[train]'   # add the training stack (torch, transformers, peft, trl, …)\npip install git+https://github.com/MakazhanAlpamys/Soup.git   # latest dev\n```\n\n`soup init`, `soup data …`, and the other data/inspection commands work on the light install.\nFine-tuning (`soup train`) needs the `[train]` extra.\n\n### 2. Create a config\n\n```bash\nsoup init                       # interactive wizard\nsoup init --template chat       # or start from a template\n```\n\nTemplates: `chat`, `code`, `tool-calling`, `medical`, `reasoning`, `vision`, `kto`, `orpo`,\n`simpo`, `ipo`, `bco`, `rlhf`, `pretrain`, `moe`, `longcontext`, `embedding`, `audio`.\n\n### 3. Train, test, ship\n\n```bash\nsoup train --config soup.yaml                 # LoRA, quantization, batching — all handled\nsoup chat  --model ./output                    # talk to your model\nsoup push  --model ./output --repo you/my-model\n\nsoup merge  --adapter ./output                              # merge LoRA into the base\nsoup export --model ./output --format gguf --quant q4_k_m   # GGUF for Ollama / llama.cpp\n```\n\nMore export targets (ONNX, TensorRT, AWQ, GPTQ, BitNet) and deployment options live in\n[`docs/serving-and-export.md`](docs/serving-and-export.md).\n\n## Configuration\n\nA complete `soup.yaml`:\n\n```yaml\nbase: meta-llama/Llama-3.1-8B-Instruct\ntask: sft\n# backend: unsloth  # 2-5x faster, pip install 'soup-cli[fast]'\n\ndata:\n  train: ./data/train.jsonl\n  format: alpaca\n  val_split: 0.1\n\ntraining:\n  epochs: 3\n  lr: 2e-5\n  batch_size: auto\n  lora:\n    r: 64\n    alpha: 16\n  quantization: 4bit\n\noutput: ./output\n```\n\n`config/schema.py` is the single source of truth for every field. Advanced data, training,\nand PEFT options are documented under [Documentation](#documentation).\n\n## Documentation\n\nThe full feature reference lives in [`docs/`](docs/). Start here:\n\n| Guide | Covers |\n|---|---|\n| [Training tasks \u0026 methods](docs/training.md) | SFT, DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/BCO, tool-calling, PRM, pre-training, distillation, classification, vision/audio/TTS, unlearning, RAFT/RA-DIT, loop-hardening detectors |\n| [PEFT, long context \u0026 efficiency](docs/peft-and-efficiency.md) | DoRA, LoRA+, rsLoRA, VeRA, OLoRA, NEFTune, PiSSA, ReLoRA, optimizer \u0026 PEFT zoo, LLaMA Pro, GaLore, YaRN/LongLoRA, packing, curriculum, auto-tuning |\n| [Performance \u0026 quantization](docs/performance-and-quantization.md) | QAT, FP8, Quant Menu (I + II), KV-cache, NVFP4, save formats, Cut Cross-Entropy, gradient checkpointing, kernels, activation offloading, multi-GPU / DeepSpeed / FSDP |\n| [Data engineering](docs/data.md) | Formats, the Axolotl/LF-parity pipeline, data tools, synthetic generation \u0026 forge, quality scorecards, trace tooling, remote datasets, mixing, recipe DAGs |\n| [Evaluation \u0026 probes](docs/evaluation.md) | Eval design/gate, eval-gated training, benchmarks, NLG metrics, calibration, Elo arena, diagnose, post-train X-ray probes, A/B, drift, tunability, `soup advise` |\n| [Serving \u0026 export](docs/serving-and-export.md) | OpenAI-compatible server, batch inference, benchmarking, merge/export, Anthropic Messages endpoint, speculative decoding, deploy autopilot, Web UI, Agent Forge |\n| [Adapters, registry \u0026 governance](docs/adapters-and-governance.md) | Adapter lifecycle/management, model registry, Soup Cans, the data flywheel (`soup loop`), knowledge editing, steering, supply-chain controls (scan/sign/BOM/attest/audit/airgap) |\n| [Backends, platform \u0026 ops](docs/backends-and-ops.md) | MLX/Unsloth backends, alternative hubs, HF Hub integration, autopilot, experiment tracking, plan/apply, env lockfiles, hardware-fit, completions, plugins, utility commands |\n| [Command reference](docs/commands.md) | The full `soup` command list |\n| [Supported models \u0026 extras](docs/models.md) | Recommended model families, the VRAM size guide, the pip extras matrix |\n\n## Data Formats\n\nAll formats are auto-detected from JSONL, JSON, CSV, Parquet, or TXT:\n\n- **alpaca** — `{\"instruction\": ..., \"input\": ..., \"output\": ...}`\n- **sharegpt** — `{\"conversations\": [{\"from\": \"human\", \"value\": ...}, ...]}`\n- **chatml** — `{\"messages\": [{\"role\": \"user\", \"content\": ...}, ...]}`\n- **dpo / orpo / simpo / ipo** — `{\"prompt\": ..., \"chosen\": ..., \"rejected\": ...}`\n- **kto** — `{\"prompt\": ..., \"completion\": ..., \"label\": true}`\n- **llava / sharegpt4v** (vision), **audio**, **plaintext** (pre-training), **embedding**,\n  **prm**, **pre_tokenized**, **video**, **multimodal**\n\nFull schemas and the Axolotl/LlamaFactory-parity data pipeline (remote URIs, streaming,\nsharding, interleaving, vocab expansion, document ingestion) are in\n[`docs/data.md`](docs/data.md).\n\n## Common Commands\n\n```bash\nsoup train  --config soup.yaml        # train (SFT/DPO/GRPO/PPO/KTO/ORPO/SimPO/IPO/...)\nsoup infer  --model ./output --input prompts.jsonl   # batch inference\nsoup chat   --model ./output          # interactive chat\nsoup serve  --model ./output          # OpenAI-compatible API server\nsoup merge  --adapter ./output        # merge LoRA into the base model\nsoup export --model ./output --format gguf           # export for deployment\nsoup eval   benchmark --model ./output               # evaluate\nsoup data   inspect ./data/train.jsonl               # dataset stats\nsoup recipes list                     # 100+ ready-made model recipes\nsoup autopilot --model \u003cid\u003e --data d.jsonl --goal chat  # zero-config\nsoup doctor                           # check GPU / deps / environment\n```\n\nThe complete command list is in [`docs/commands.md`](docs/commands.md).\n\n## Supported Models\n\nSoup works with **any** text-generation model on the\n[HuggingFace Hub](https://huggingface.co/models?pipeline_tag=text-generation) — if it loads with\n`AutoModelForCausalLM`, it works, zero config changes. Llama 3.x/4, Qwen 2.5/3, Gemma 3, Mistral,\nMixtral, DeepSeek R1/V3, Phi-4, and 100+ others ship as ready-made recipes (`soup recipes list`).\n\n| VRAM | Max model (QLoRA 4-bit) | Example |\n|---|---|---|\n| 8 GB | ~7B | Llama-3.1-8B, Mistral-7B |\n| 16 GB | ~14B | Phi-4-14B, Qwen2.5-14B |\n| 24 GB | ~34B | CodeLlama-34B, Yi-1.5-34B |\n| 48 GB | ~70B | Llama-3.3-70B |\n| 80 GB+ | 70B+ (full) or MoE | Mixtral-8x22B, DeepSeek-V3 |\n\nFull model + vision tables and the optional-extras matrix are in [`docs/models.md`](docs/models.md).\n\n## Docker\n\nRun Soup without installing CUDA or PyTorch locally (image published to GHCR on every release):\n\n```bash\ndocker pull ghcr.io/makazhanalpamys/soup:latest\ndocker run --gpus all -v $(pwd):/workspace ghcr.io/makazhanalpamys/soup train --config soup.yaml\ndocker compose up   # or build locally\n```\n\n## Requirements\n\n- Python 3.10+\n- GPU with CUDA (recommended), Apple Silicon (MPS), or CPU (experimental — very slow)\n- 8 GB+ VRAM for 7B models with QLoRA\n\nAll training tasks run on CPU for testing (quantization auto-disabled). Optional extras\n(`train`, `all`, `fast`, `vision`, `qat`, `serve`, `serve-fast`, `ui`, `eval`, `deepspeed`,\n`liger`, `mlx`, `onnx`, `tensorrt`, …) are listed in\n[`docs/models.md`](docs/models.md#optional-extras).\n\n## Troubleshooting\n\n```bash\nsoup doctor    # GPU, system resources, dependencies, and version in one place\n```\n\n- **`ImportError: DLL load failed while importing _C` (Windows)** — reinstall PyTorch for your\n  CUDA version: `pip install torch --index-url https://download.pytorch.org/whl/cu121`.\n- **`soup version` ≠ `pip show soup-cli`** — multiple Python installs; use a virtualenv.\n\n## Development\n\n```bash\ngit clone https://github.com/MakazhanAlpamys/Soup.git\ncd Soup\npip install -e \".[dev]\"\n\nruff check src/soup_cli/ tests/    # lint\npytest tests/ -v                   # unit tests (fast, no GPU)\npytest tests/ -m smoke -v          # smoke tests (downloads a tiny model, trains)\n\npre-commit install                 # optional: ruff lint+format on commit\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full workflow and [SECURITY.md](SECURITY.md) to\nreport a vulnerability.\n\n## License\n\n[Apache-2.0](LICENSE). Copyright © the Soup contributors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakazhanalpamys%2Fsoup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakazhanalpamys%2Fsoup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakazhanalpamys%2Fsoup/lists"}