canifinetune 0.1.0__tar.gz

canifinetune-0.1.0/.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+.python-version-local
+
+# Tooling
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Project local artifacts (small results are tracked under benchmarks/results)
+.cache/
+hf_cache/
+runs/
+output*/
+checkpoints/
+adapters/
+*.log
+
+# Models we never want to commit
+*.bin
+*.safetensors
+*.gguf
+*.pt
+*.pth
+*.onnx
+
+# Large datasets
+*.parquet
+*.arrow
+
+# OneDrive cruft
+*.tmp
+*.lock

canifinetune-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daoyuan Li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

canifinetune-0.1.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: canifinetune
+Version: 0.1.0
+Summary: Estimate, benchmark, and generate fine-tuning recipes for LLMs on consumer GPUs.
+Project-URL: Homepage, https://github.com/DaoyuanLi2816/can-i-finetune-this
+Project-URL: Issues, https://github.com/DaoyuanLi2816/can-i-finetune-this/issues
+Project-URL: Repository, https://github.com/DaoyuanLi2816/can-i-finetune-this
+Author-email: Daoyuan Li <lidaoyuan2816@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: fine-tuning,gpu,huggingface,llm,lora,memory,peft,qlora,transformers
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: huggingface-hub>=0.25
+Requires-Dist: jinja2>=3.1
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: report
+Requires-Dist: pandas>=2.2; extra == 'report'
+Requires-Dist: tabulate>=0.9; extra == 'report'
+Provides-Extra: train
+Requires-Dist: accelerate>=0.33; extra == 'train'
+Requires-Dist: bitsandbytes>=0.43; (platform_system != 'Darwin') and extra == 'train'
+Requires-Dist: datasets>=2.20; extra == 'train'
+Requires-Dist: peft>=0.12; extra == 'train'
+Requires-Dist: protobuf>=4.25; extra == 'train'
+Requires-Dist: sentencepiece>=0.2; extra == 'train'
+Requires-Dist: torch>=2.3; extra == 'train'
+Requires-Dist: transformers>=4.43; extra == 'train'
+Requires-Dist: trl>=0.9; extra == 'train'
+Description-Content-Type: text/markdown
+
+# can-i-finetune-this
+
+[![CI](https://github.com/DaoyuanLi2816/can-i-finetune-this/actions/workflows/ci.yml/badge.svg)](https://github.com/DaoyuanLi2816/can-i-finetune-this/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Estimate, benchmark, and generate fine-tuning recipes for LLMs on consumer GPUs.**
+
+![can-i-finetune-this architecture](docs/architecture.png)
+
+You have one consumer-grade NVIDIA GPU. You want to fine-tune an open-weight LLM
+with LoRA or QLoRA, but you do not want to download 14 GB of weights just to
+discover that your 12 GB / 16 GB / 24 GB card OOMs on step 1.
+
+`canifinetune` answers, before you spend the disk and the time:
+
+1. Can I fine-tune this model?
+2. About how much VRAM will it use?
+3. What batch size / sequence length / LoRA rank / quantization should I use?
+4. If I can't, how should I downsize?
+5. Is there local benchmark evidence for that answer?
+6. Can I get a ready-to-run Hugging Face + PEFT + TRL training script for that config?
+
+It is a single Python package with a CLI:
+
+```bash
+canifinetune doctor
+canifinetune estimate --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --gpu-vram-gb 16 --seq-len 2048 --micro-batch-size 1 --lora-rank 16
+canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16
+canifinetune bench    --model sshleifer/tiny-gpt2 --method lora --steps 3
+canifinetune calibrate --benchmarks benchmarks/results
+canifinetune recipe   --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --output recipes/qwen2.5-1.5b-qlora-4080
+canifinetune report   --benchmarks benchmarks/results --out report.md
+canifinetune compare  --benchmarks benchmarks/results --out compare.md
+```
+
+What `canifinetune estimate` actually prints:
+
+```text
++-------- Qwen/Qwen2.5-1.5B-Instruct  (qlora) --------+
+| feasible: YES    ratio = 0.20    confidence = medium |
++------------------------------------------------------+
+       Memory breakdown (GB)
++---------------------------------+
+| Component             |   Value |
+|-----------------------+---------|
+| static model          |   0.737 |
+| quantization overhead |   0.018 |
+| trainable params      |  4.4 MB |
+| gradients             |   0.008 |
+| optimizer states      |   0.010 |
+| activations           |   0.328 |
+| CUDA / fragmentation  |   1.280 |
+| safety margin         |   0.800 |
+| total                 |   3.163 |
++---------------------------------+
+```
+
+Static estimate says 3.16 GB; on a real RTX 4080 the same config measures
+7.10 GB (heavy bitsandbytes unpacking buffers at seq_len=2048). `canifinetune
+bench` and `canifinetune calibrate` close that gap on your machine —
+that is the *point* of the project.
+
+---
+
+## Install
+
+`canifinetune` runs in two layers:
+
+| Layer | Install | What you get |
+| --- | --- | --- |
+| Core (estimate / recommend / recipe / report) | `pip install canifinetune` | All CLI commands. No PyTorch required. |
+| Training (bench / real fine-tuning) | `pip install canifinetune[train]` | Adds `torch`, `transformers`, `peft`, `bitsandbytes`, `trl`, `datasets`. |
+| Reporting extras | `pip install canifinetune[report]` | Pandas/tabulate for prettier tables. |
+| Development | `pip install canifinetune[dev]` | pytest, ruff, mypy. |
+
+If you use `uv`:
+
+```bash
+uv venv
+uv pip install -e ".[dev,report]"
+# Add training deps when you want to run benchmarks:
+uv pip install -e ".[dev,train,report]"
+```
+
+PyTorch should generally be installed with the CUDA wheel that matches your driver,
+e.g.
+
+```bash
+uv pip install torch --index-url https://download.pytorch.org/whl/cu121
+```
+
+See `docs/troubleshooting.md` for Windows / WSL / bitsandbytes specifics.
+
+---
+
+## Quickstart
+
+```bash
+# 1. See what your machine looks like
+canifinetune doctor
+
+# 2. Ask if a model fits on your card
+canifinetune estimate \
+  --model Qwen/Qwen2.5-1.5B-Instruct \
+  --method qlora \
+  --gpu-vram-gb 16 \
+  --seq-len 2048 \
+  --micro-batch-size 1 \
+  --lora-rank 16
+
+# 3. Have it search for a feasible config
+canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16
+
+# 4. Run a tiny real benchmark (downloads sshleifer/tiny-gpt2, ~5 MB)
+canifinetune bench --model sshleifer/tiny-gpt2 --method lora --steps 3
+
+# 5. Generate a ready-to-run training recipe
+canifinetune recipe \
+  --model Qwen/Qwen2.5-1.5B-Instruct \
+  --method qlora \
+  --seq-len 2048 \
+  --output recipes/qwen2.5-1.5b-qlora-4080
+```
+
+---
+
+## What's different from `accelerate estimate-memory`?
+
+`accelerate estimate-memory` tells you how much memory **loading** a model takes.
+That is not enough to know whether you can **train** it.
+
+This project tries to answer the harder question. It models:
+
+- Model weights, in fp32 / fp16 / bf16 / int8 / NF4 + double-quant
+- LoRA / QLoRA trainable parameter count for typical `target_modules`
+- Gradients only for trainable parameters
+- AdamW vs 8-bit / paged AdamW optimizer states
+- Activations as a function of `seq_len`, `batch_size`, `hidden_size`, `num_layers`,
+  with and without gradient checkpointing
+- A fragmentation / CUDA / buffer safety margin
+- A feasibility decision against your actual GPU
+- Concrete degradation suggestions when not feasible
+
+Estimates are **always** marked with an `assumptions` block and a `confidence`
+level, because activation memory in particular is hard to predict statically.
+Run `canifinetune bench` and `canifinetune calibrate` to ground them in real
+measurements on your machine.
+
+---
+
+## RTX 4080 baselines
+
+`docs/rtx4080_baselines.md` contains real measurements collected on a single
+RTX 4080 (16 GB). These are not synthetic. If a configuration was not run, the
+table says "not run", not a guessed number.
+
+Highlights (more in the doc):
+
+| model | method | seq_len | measured peak | tok/sec |
+| --- | --- | --- | --- | --- |
+| `Qwen/Qwen2.5-0.5B-Instruct` | qlora | 1024 | 3.30 GB | 1995 |
+| `Qwen/Qwen2.5-1.5B-Instruct` | qlora | 1024 | 4.36 GB | 1352 |
+| `Qwen/Qwen2.5-1.5B-Instruct` | qlora | 2048 | 7.10 GB | 1470 |
+| `Qwen/Qwen2.5-3B-Instruct` | qlora | 1024 | 5.54 GB | 1158 |
+| `sshleifer/tiny-gpt2` (smoke) | lora | 128 | 0.12 GB | 1735 |
+
+---
+
+## Repository layout
+
+```
+src/canifinetune/        # package code (estimator, bench, recipes, reports, cli)
+benchmarks/              # configs/, results/ (JSON), calibration/
+docs/                    # design, memory model, troubleshooting
+examples/                # end-to-end recipe folders
+tests/                   # pytest tests (CPU-only, no large downloads)
+scripts/                 # helper scripts for collecting baselines
+.github/workflows/       # CI (ruff + pytest on CPU)
+```
+
+---
+
+## Roadmap
+
+The current scope is "single consumer GPU, single node, LoRA / QLoRA, causal LM,
+Hugging Face stack". Possible directions, none committed:
+
+- DeepSpeed ZeRO and FSDP estimation for multi-GPU setups
+- Heuristics for sequence-classification / encoder-decoder training
+- Throughput modeling (tokens / sec), not just feasibility
+- Auto-tuning of `gradient_accumulation_steps` for a target effective batch size
+- A web UI on top of the CLI
+
+Contributions welcome.
+
+---
+
+## License
+
+MIT. See `LICENSE`.

canifinetune-0.1.0/README.md

@@ -0,0 +1,201 @@
+# can-i-finetune-this
+
+[![CI](https://github.com/DaoyuanLi2816/can-i-finetune-this/actions/workflows/ci.yml/badge.svg)](https://github.com/DaoyuanLi2816/can-i-finetune-this/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org)
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+**Estimate, benchmark, and generate fine-tuning recipes for LLMs on consumer GPUs.**
+
+![can-i-finetune-this architecture](docs/architecture.png)
+
+You have one consumer-grade NVIDIA GPU. You want to fine-tune an open-weight LLM
+with LoRA or QLoRA, but you do not want to download 14 GB of weights just to
+discover that your 12 GB / 16 GB / 24 GB card OOMs on step 1.
+
+`canifinetune` answers, before you spend the disk and the time:
+
+1. Can I fine-tune this model?
+2. About how much VRAM will it use?
+3. What batch size / sequence length / LoRA rank / quantization should I use?
+4. If I can't, how should I downsize?
+5. Is there local benchmark evidence for that answer?
+6. Can I get a ready-to-run Hugging Face + PEFT + TRL training script for that config?
+
+It is a single Python package with a CLI:
+
+```bash
+canifinetune doctor
+canifinetune estimate --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --gpu-vram-gb 16 --seq-len 2048 --micro-batch-size 1 --lora-rank 16
+canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16
+canifinetune bench    --model sshleifer/tiny-gpt2 --method lora --steps 3
+canifinetune calibrate --benchmarks benchmarks/results
+canifinetune recipe   --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --output recipes/qwen2.5-1.5b-qlora-4080
+canifinetune report   --benchmarks benchmarks/results --out report.md
+canifinetune compare  --benchmarks benchmarks/results --out compare.md
+```
+
+What `canifinetune estimate` actually prints:
+
+```text
++-------- Qwen/Qwen2.5-1.5B-Instruct  (qlora) --------+
+| feasible: YES    ratio = 0.20    confidence = medium |
++------------------------------------------------------+
+       Memory breakdown (GB)
++---------------------------------+
+| Component             |   Value |
+|-----------------------+---------|
+| static model          |   0.737 |
+| quantization overhead |   0.018 |
+| trainable params      |  4.4 MB |
+| gradients             |   0.008 |
+| optimizer states      |   0.010 |
+| activations           |   0.328 |
+| CUDA / fragmentation  |   1.280 |
+| safety margin         |   0.800 |
+| total                 |   3.163 |
++---------------------------------+
+```
+
+Static estimate says 3.16 GB; on a real RTX 4080 the same config measures
+7.10 GB (heavy bitsandbytes unpacking buffers at seq_len=2048). `canifinetune
+bench` and `canifinetune calibrate` close that gap on your machine —
+that is the *point* of the project.
+
+---
+
+## Install
+
+`canifinetune` runs in two layers:
+
+| Layer | Install | What you get |
+| --- | --- | --- |
+| Core (estimate / recommend / recipe / report) | `pip install canifinetune` | All CLI commands. No PyTorch required. |
+| Training (bench / real fine-tuning) | `pip install canifinetune[train]` | Adds `torch`, `transformers`, `peft`, `bitsandbytes`, `trl`, `datasets`. |
+| Reporting extras | `pip install canifinetune[report]` | Pandas/tabulate for prettier tables. |
+| Development | `pip install canifinetune[dev]` | pytest, ruff, mypy. |
+
+If you use `uv`:
+
+```bash
+uv venv
+uv pip install -e ".[dev,report]"
+# Add training deps when you want to run benchmarks:
+uv pip install -e ".[dev,train,report]"
+```
+
+PyTorch should generally be installed with the CUDA wheel that matches your driver,
+e.g.
+
+```bash
+uv pip install torch --index-url https://download.pytorch.org/whl/cu121
+```
+
+See `docs/troubleshooting.md` for Windows / WSL / bitsandbytes specifics.
+
+---
+
+## Quickstart
+
+```bash
+# 1. See what your machine looks like
+canifinetune doctor
+
+# 2. Ask if a model fits on your card
+canifinetune estimate \
+  --model Qwen/Qwen2.5-1.5B-Instruct \
+  --method qlora \
+  --gpu-vram-gb 16 \
+  --seq-len 2048 \
+  --micro-batch-size 1 \
+  --lora-rank 16
+
+# 3. Have it search for a feasible config
+canifinetune recommend --model Qwen/Qwen2.5-1.5B-Instruct --gpu-vram-gb 16
+
+# 4. Run a tiny real benchmark (downloads sshleifer/tiny-gpt2, ~5 MB)
+canifinetune bench --model sshleifer/tiny-gpt2 --method lora --steps 3
+
+# 5. Generate a ready-to-run training recipe
+canifinetune recipe \
+  --model Qwen/Qwen2.5-1.5B-Instruct \
+  --method qlora \
+  --seq-len 2048 \
+  --output recipes/qwen2.5-1.5b-qlora-4080
+```
+
+---
+
+## What's different from `accelerate estimate-memory`?
+
+`accelerate estimate-memory` tells you how much memory **loading** a model takes.
+That is not enough to know whether you can **train** it.
+
+This project tries to answer the harder question. It models:
+
+- Model weights, in fp32 / fp16 / bf16 / int8 / NF4 + double-quant
+- LoRA / QLoRA trainable parameter count for typical `target_modules`
+- Gradients only for trainable parameters
+- AdamW vs 8-bit / paged AdamW optimizer states
+- Activations as a function of `seq_len`, `batch_size`, `hidden_size`, `num_layers`,
+  with and without gradient checkpointing
+- A fragmentation / CUDA / buffer safety margin
+- A feasibility decision against your actual GPU
+- Concrete degradation suggestions when not feasible
+
+Estimates are **always** marked with an `assumptions` block and a `confidence`
+level, because activation memory in particular is hard to predict statically.
+Run `canifinetune bench` and `canifinetune calibrate` to ground them in real
+measurements on your machine.
+
+---
+
+## RTX 4080 baselines
+
+`docs/rtx4080_baselines.md` contains real measurements collected on a single
+RTX 4080 (16 GB). These are not synthetic. If a configuration was not run, the
+table says "not run", not a guessed number.
+
+Highlights (more in the doc):
+
+| model | method | seq_len | measured peak | tok/sec |
+| --- | --- | --- | --- | --- |
+| `Qwen/Qwen2.5-0.5B-Instruct` | qlora | 1024 | 3.30 GB | 1995 |
+| `Qwen/Qwen2.5-1.5B-Instruct` | qlora | 1024 | 4.36 GB | 1352 |
+| `Qwen/Qwen2.5-1.5B-Instruct` | qlora | 2048 | 7.10 GB | 1470 |
+| `Qwen/Qwen2.5-3B-Instruct` | qlora | 1024 | 5.54 GB | 1158 |
+| `sshleifer/tiny-gpt2` (smoke) | lora | 128 | 0.12 GB | 1735 |
+
+---
+
+## Repository layout
+
+```
+src/canifinetune/        # package code (estimator, bench, recipes, reports, cli)
+benchmarks/              # configs/, results/ (JSON), calibration/
+docs/                    # design, memory model, troubleshooting
+examples/                # end-to-end recipe folders
+tests/                   # pytest tests (CPU-only, no large downloads)
+scripts/                 # helper scripts for collecting baselines
+.github/workflows/       # CI (ruff + pytest on CPU)
+```
+
+---
+
+## Roadmap
+
+The current scope is "single consumer GPU, single node, LoRA / QLoRA, causal LM,
+Hugging Face stack". Possible directions, none committed:
+
+- DeepSpeed ZeRO and FSDP estimation for multi-GPU setups
+- Heuristics for sequence-classification / encoder-decoder training
+- Throughput modeling (tokens / sec), not just feasibility
+- Auto-tuning of `gradient_accumulation_steps` for a target effective batch size
+- A web UI on top of the CLI
+
+Contributions welcome.
+
+---
+
+## License
+
+MIT. See `LICENSE`.

canifinetune-0.1.0/examples/README.md

@@ -0,0 +1,16 @@
+# Examples
+
+This folder will collect end-to-end recipes generated by `canifinetune recipe`.
+We commit them so that someone browsing the repo can read the generated
+`train.py` and `config.yaml` without having to install the package first.
+
+To regenerate any of these from scratch:
+
+```bash
+canifinetune recipe \
+  --model Qwen/Qwen2.5-1.5B-Instruct \
+  --method qlora \
+  --seq-len 2048 \
+  --lora-rank 16 \
+  --output examples/qwen_1_5b_qlora_4080
+```

canifinetune-0.1.0/examples/qwen_1_5b_qlora_4080/README.md

@@ -0,0 +1,56 @@
+# canifinetune-recipe
+
+This folder was generated by `canifinetune recipe`. It is a self-contained,
+single-GPU QLORA fine-tuning script for **Qwen/Qwen2.5-1.5B-Instruct**.
+
+## Files
+
+- `train.py` — main training entrypoint.
+- `config.yaml` — all hyperparameters; pass with `--config`.
+- `eval_smoke.py` — load the adapter, generate one completion as a smoke test.
+- `data/sample.jsonl` — tiny synthetic instruction dataset (not for serious training).
+- `requirements.txt` — Python deps. Match CUDA wheels to your driver.
+- `expected_vram.md` — static estimate for this exact config.
+- `dataset_format.md` — JSONL schema your real dataset should follow.
+- `troubleshooting.md` — OOM / bitsandbytes / Windows tips.
+- `run.sh` — convenience wrapper.
+
+## Quick start
+
+```bash
+# 1. Install deps in a fresh venv.
+python -m venv .venv && source .venv/bin/activate   # or .\.venv\Scripts\activate on Windows
+pip install -r requirements.txt
+# For CUDA wheels: e.g. `pip install torch --index-url https://download.pytorch.org/whl/cu121`
+
+# 2. Smoke run with the bundled tiny dataset.
+python train.py --config config.yaml --max-steps 5
+
+# 3. Confirm the adapter loads.
+python eval_smoke.py --adapter output/adapter
+
+# 4. Replace data/sample.jsonl with your own JSONL and run again.
+```
+
+## Memory estimate (from `canifinetune estimate`)
+
+- Method: **qlora**, base dtype **bf16**, quantization **nf4_double_quant**
+- LoRA rank: **16**, target modules: `q_proj, k_proj, v_proj, o_proj`
+- seq_len: **1024**, micro_batch_size: **1**
+- Gradient checkpointing: **on**
+- Optimizer: **paged_adamw_8bit**
+- Attention impl: **sdpa**
+
+Static feasibility on a 16.0 GB GPU: **yes**
+(confidence: medium).
+
+See `expected_vram.md` for the full breakdown. Run
+`canifinetune bench --model Qwen/Qwen2.5-1.5B-Instruct --method qlora --steps 3` to
+measure real VRAM on your machine.
+
+## Caveats
+
+- The bundled `data/sample.jsonl` exists so the smoke run completes; it is
+  far too small for any real fine-tune. Bring your own data.
+- This recipe assumes a single GPU. For multi-GPU, regenerate with `accelerate`
+  / DeepSpeed integration (not yet in `canifinetune`).

canifinetune-0.1.0/examples/tiny_gpt2_lora_smoke/README.md

@@ -0,0 +1,56 @@
+# canifinetune-recipe
+
+This folder was generated by `canifinetune recipe`. It is a self-contained,
+single-GPU LORA fine-tuning script for **sshleifer/tiny-gpt2**.
+
+## Files
+
+- `train.py` — main training entrypoint.
+- `config.yaml` — all hyperparameters; pass with `--config`.
+- `eval_smoke.py` — load the adapter, generate one completion as a smoke test.
+- `data/sample.jsonl` — tiny synthetic instruction dataset (not for serious training).
+- `requirements.txt` — Python deps. Match CUDA wheels to your driver.
+- `expected_vram.md` — static estimate for this exact config.
+- `dataset_format.md` — JSONL schema your real dataset should follow.
+- `troubleshooting.md` — OOM / bitsandbytes / Windows tips.
+- `run.sh` — convenience wrapper.
+
+## Quick start
+
+```bash
+# 1. Install deps in a fresh venv.
+python -m venv .venv && source .venv/bin/activate   # or .\.venv\Scripts\activate on Windows
+pip install -r requirements.txt
+# For CUDA wheels: e.g. `pip install torch --index-url https://download.pytorch.org/whl/cu121`
+
+# 2. Smoke run with the bundled tiny dataset.
+python train.py --config config.yaml --max-steps 5
+
+# 3. Confirm the adapter loads.
+python eval_smoke.py --adapter output/adapter
+
+# 4. Replace data/sample.jsonl with your own JSONL and run again.
+```
+
+## Memory estimate (from `canifinetune estimate`)
+
+- Method: **lora**, base dtype **fp32**, quantization **bf16**
+- LoRA rank: **8**, target modules: `c_attn, c_proj`
+- seq_len: **128**, micro_batch_size: **1**
+- Gradient checkpointing: **off**
+- Optimizer: **adamw_torch**
+- Attention impl: **eager**
+
+Static feasibility on a 16.0 GB GPU: **yes**
+(confidence: medium).
+
+See `expected_vram.md` for the full breakdown. Run
+`canifinetune bench --model sshleifer/tiny-gpt2 --method lora --steps 3` to
+measure real VRAM on your machine.
+
+## Caveats
+
+- The bundled `data/sample.jsonl` exists so the smoke run completes; it is
+  far too small for any real fine-tune. Bring your own data.
+- This recipe assumes a single GPU. For multi-GPU, regenerate with `accelerate`
+  / DeepSpeed integration (not yet in `canifinetune`).