Tunepac

Teach an open-source AI model your company's job — by writing a short settings file instead of writing training code.

pip install "tunepac[train]"
tunepac train --config my_model.yaml

Contents

New here? What problem does this solve? · What it does today · Quick start

Using it: How it works · Which adapter should I use? · Installation · CLI reference · Configuration reference · Dataset formats · Chat templates · Recipes · Troubleshooting

Contributing: Architecture · Development · Roadmap · License

For the non-engineer: what problem does this solve?

General-purpose AI models are generalists. They write decent email and know nothing about your refund policy, your product catalog, or your house style. Fine-tuning is the process of training a general model on your own examples until it behaves the way you need.

The catch is that fine-tuning normally means an ML engineer hand-writing a custom training program for every experiment. That is slow, hard to review, and easy to get subtly wrong — and mistakes are expensive, because you often don't discover them until hours of rented GPU time have already burned.

Tunepac replaces that program with a recipe: one readable text file that says which model, which examples, and which settings. Hand it to Tunepac and it runs the job.

The cost angle. Tunepac leans on a technique called QLoRA, which trains a small "adapter" layer instead of rewriting the whole model. The practical effect is that customizing an 8-billion-parameter model fits on a single high-end consumer graphics card rather than a rented cluster — and the resulting adapter is a file of tens of megabytes, not tens of gigabytes.

The honest caveat. This is young software (version 0.1), it is a tool for technical teams, and it does not collect your data or supply the examples — you still need a dataset and someone who understands what "good output" means for your use case.

What it does today

Same data, precisely — the low scores are the roadmap, not an oversight:

Quick start

1. Install. The base install is tiny and needs no GPU — it only validates configs. Add [train] when you actually want to train:

pip install tunepac            # CLI + config validation, no CUDA, no torch
pip install "tunepac[train]"   # + torch, TRL, PEFT, Accelerate, bitsandbytes

2. Write a config — save as my_model.yaml:

base_model:
  name: meta-llama/Meta-Llama-3-8B

dataset:
  path: yahma/alpaca-cleaned     # a Hub dataset, or your own .jsonl file
  format: alpaca
  chat_template: llama3

training:
  learning_rate: 2.0e-4
  epochs: 3
  batch_size: 2
  gradient_accumulation_steps: 8

peft:
  adapter: qlora                 # 4-bit base + trainable adapter
  r: 32

hardware:
  bf16: true
  gradient_checkpointing: true

3. Check it before spending GPU time. This runs in a second, on a laptop, with no model download:

$ tunepac validate --config my_model.yaml
Config OK — schema validation passed.
                   Tunepac run summary
┌───────────────────┬──────────────────────────────────────┐
│ Base model        │ meta-llama/Meta-Llama-3-8B           │
│ Dataset           │ yahma/alpaca-cleaned (alpaca)        │
│ Chat template     │ llama3                               │
│ Adapter           │ qlora (r=32, alpha=32)               │
│ Precision         │ bfloat16                             │
│ Batch             │ 2 x 8 accumulation = 16 effective    │
│ Sequence length   │ 2048                                 │
│ Output dir        │ outputs                              │
└───────────────────┴──────────────────────────────────────┘

4. Train, then ship a standalone model:

tunepac train  --config my_model.yaml   # writes an adapter
tunepac export --config my_model.yaml   # merges it into the base model

The merged model in outputs/merged/ loads with a plain AutoModelForCausalLM.from_pretrained — no Tunepac or PEFT needed at inference time.

Want to try it in 30 seconds instead? configs/test_smollm2.yaml fine-tunes a 135M-parameter model on five dummy rows and runs on a CPU:

python scripts/run_test.py
# PASS: LoRA adapter saved to output_test_adapter (34 KiB) in 6.8s

How it works

flowchart LR
    Y["config.yaml"] --> V{"Pydantic schema<br/>validation"}
    V -->|"invalid"| E["lint-style error report<br/><i>exit 1, no GPU touched</i>"]
    V -->|"valid"| T["tokenizer<br/>+ chat template"]
    T --> D["dataset → messages → text"]
    D --> M["base model<br/><i>4-bit if QLoRA</i>"]
    M --> S["TRL SFTTrainer<br/><i>packing · LoRA</i>"]
    S --> A["adapter/"]
    A --> X["tunepac export"]
    X --> G["merged model/<br/><i>loads without PEFT</i>"]

    style E fill:#7c2d12,color:#fff
    style G fill:#14532d,color:#fff
    style V fill:#1e3a5f,color:#fff

The pipeline in words, for anywhere Mermaid doesn't render:

The design rule that matters: every invariant is checked in step 1. The trainer never re-checks what the schema guarantees, and nothing heavy is imported until the config is known good — which is why validate runs on a laptop with no CUDA.

Which adapter should I use?

flowchart TD
    Q1{"Deep knowledge change?"}
    Q1 -->|"no — the usual case"| Q2{"Fits your GPU at 16-bit?"}
    Q1 -->|"yes, and you<br/>have the hardware"| FULL["Full fine-tune<br/><i>omit the peft section</i>"]
    Q2 -->|"yes"| LORA["peft.adapter: lora<br/><i>fastest, best quality</i>"]
    Q2 -->|"no"| QLORA["peft.adapter: qlora<br/><i>4-bit base, 8B fits in 24 GB</i>"]

    style FULL fill:#78350f,color:#fff
    style LORA fill:#14532d,color:#fff
    style QLORA fill:#1e3a5f,color:#fff

The economics in one line: validate costs nothing and takes a second; train costs GPU hours. Everything the schema can catch is caught in the first one, which is the whole reason the validation is strict.

Features

• One YAML file per run. Everything defining a fine-tune lives in one reviewable, diffable, version-controllable file.
• Strict validation, early. Every section rejects unknown keys, every field is typed and bounded, and cross-field rules (e.g. QLoRA requires half precision) are enforced in the schema. Errors read like a lint report, never a Python traceback.
• LoRA and QLoRA out of the box. Omit the peft section entirely for full-parameter fine-tuning.
• Dataset flexibility. Four record formats, Hub datasets or local .jsonl/.json/.csv/.parquet, automatic conversion to a common message form.
• Token packing via TRL, on by default, so short examples don't waste sequence budget.
• Light by default. The base install needs only typer, pydantic, PyYAML and rich. Heavy dependencies live behind [train] and are imported lazily.
• Fail fast, fail helpfully. Chat-template mismatches are caught before training; CUDA OOM is re-raised with ordered, concrete remedies.
• Typed and tested. mypy --strict clean, py.typed shipped, 87 tests including real end-to-end training runs.

Installation

Requires Python 3.10+.

FlashAttention (hardware.flash_attention: true) additionally requires the flash-attn package, which needs a CUDA toolchain to build. It is deliberately not in [train].

TRL version. [train] pins trl<1.14. TRL 1.14 introduced a Triton kernel in the SFT loss path with no CPU fallback, which breaks CPU training entirely. The pin will be lifted when upstream restores a non-Triton path.

CLI reference

All commands take --config / -c <path>.

tunepac train --config <file>

Prints the run summary, then loads tokenizer, dataset and model and hands off to TRL's SFTTrainer. Exit codes: 0 success · 1 config/dataset/template error, OOM, or missing training extras.

tunepac validate --config <file> [--check-dataset | --no-check-dataset]

Validates against the schema and prints the run summary. With --check-dataset (the default) local dataset files are opened and their first records checked against the declared format — using only the standard library, so it works on a base install. Hub dataset ids are noted and deferred to training time.

Exit codes: 0 valid · 1 schema or dataset problems, each listed.

tunepac export --config <file> [--adapter DIR] [--output DIR]

Merges a trained LoRA/QLoRA adapter into its base model, writing a standalone model directory. --adapter defaults to training.output_dir; --output defaults to <adapter>/merged. The tokenizer saved with the adapter is carried over, so an overridden chat template survives the merge.

QLoRA note: even when the config says adapter: qlora, the base model is loaded unquantized for the merge — merging LoRA weights into 4-bit NF4 weights loses precision, so the merge happens in the config's compute dtype.

Exit codes: 0 merged · 1 no peft section, missing/invalid adapter, or missing training extras. GGUF conversion is not implemented; see Roadmap.

Global flags

tunepac --version prints the installed version.

Configuration reference

A config is a YAML mapping of up to five sections. base_model and dataset are required; training and hardware have defaults; peft is optional (omit it for full fine-tuning). Unknown keys anywhere are errors. Source of truth: tunepac/config/schema.py.

base_model

dataset

Rules: format: completion requires chat_template: null; the conversational formats require a non-null chat_template.

training

warmup_ratio note. transformers 5 removed ratio-based warmup from TrainingArguments, so Tunepac converts the ratio to a step count itself from the estimated total updates. With packing on, the estimate errs slightly long — acceptable for a warmup heuristic.

peft

Omit this whole section for full-parameter fine-tuning.

quantization sub-fields: bnb_4bit_quant_type (nf4 or fp4, default nf4) and bnb_4bit_use_double_quant (default true).

hardware

With both bf16 and fp16 false, training runs in float32.

Cross-section rules

Enforced at validation time, before anything loads:

Dataset formats

Conversational formats are normalized to OpenAI-style [{role, content}], then rendered through the chat template. completion data is used as-is.

{"instruction": "Translate to German.", "input": "Good morning!", "output": "Guten Morgen!"}
{"conversations": [{"from": "human", "value": "Hi!"}, {"from": "gpt", "value": "Hello!"}]}
{"messages": [{"role": "user", "content": "Hi!"}, {"role": "assistant", "content": "Hello!"}]}

For alpaca, a non-empty input is appended to the instruction (blank line between) to form the user turn. ShareGPT speakers map system→system, human/user→user, gpt/assistant→assistant; unknown speakers are an error.

A path ending in .jsonl/.json/.csv/.parquet is a local file (.json must be a list of records); anything else is a Hub dataset id.

Chat templates

Match the template to the model family when fine-tuning an instruct model, or choose deliberately when teaching a base model a chat format from scratch.

Recipes

QLoRA on Llama-3-8B, single 24 GB GPU

example_config.yaml in full: NF4 double-quantized 4-bit base, LoRA r=32 on all attention and MLP projections, paged 8-bit AdamW, packing at 4096 tokens, bf16, FlashAttention-2, gradient checkpointing.

CPU smoke test, under 30 seconds

configs/test_smollm2.yaml — SmolLM2-135M with LoRA r=8 on five dummy rows in float32. python scripts/run_test.py writes the data, trains, and verifies the adapter.

Full fine-tune

Delete the peft section. Expect an order of magnitude more memory. (export correctly refuses these — there is no adapter to merge.)

Multi-GPU

accelerate config          # once, to describe your machine
accelerate launch -m tunepac.cli train --config my_model.yaml

batch_size and effective_batch_size are per device — multiply by world size for the global batch.

Errors and troubleshooting

Config errors read like a lint report

$ tunepac validate --config bad.yaml
Invalid configuration (3 error(s)):
  training.learning_rate: Input should be less than or equal to 1
  peft.lora_droput: Extra inputs are not permitted
  hardware: Value error, hardware.bf16 and hardware.fp16 are mutually exclusive

Every problem is listed with its section.field path; exit code 1. You never get a Python traceback for a bad config. Field-level errors are reported first; cross-field rules run once the fields themselves parse.

Out of memory

Caught and re-raised with ordered suggestions, cheapest first:

Ran out of GPU memory during training.
Suggestions:
  - Lower training.batch_size (raise gradient_accumulation_steps to keep the effective size)
  - Enable hardware.gradient_checkpointing
  - Reduce training.max_seq_length
  - Switch peft.adapter to 'qlora' to load the base model in 4-bit
  - Use a paged optimizer (training.optimizer: paged_adamw_8bit)

Other common cases

Architecture

tunepac/
├── tunepac/
│   ├── cli.py                  # Typer entry point: train / validate / export
│   ├── config/
│   │   ├── schema.py           # Pydantic v2 schema — the contract
│   │   └── loader.py           # YAML → TunepacConfig, lint-style errors
│   ├── data/
│   │   ├── formatting.py       # format registry, record → messages, cheap checks
│   │   └── chat_templates.py   # named Jinja chat templates
│   ├── training/trainer.py     # validated config → TRL SFTTrainer (lazy imports)
│   ├── export/merge.py         # adapter → standalone merged model
│   ├── utils/errors.py         # TunepacError hierarchy
│   └── py.typed                # PEP 561
├── configs/test_smollm2.yaml   # CPU smoke-test recipe
├── scripts/run_test.py         # end-to-end smoke test
├── docs/                       # README assets
├── tests/                      # unit + integration suites
└── example_config.yaml         # Llama-3-8B QLoRA recipe

Three principles:

1. The schema is the contract. All invariants live in schema.py. The trainer maps an already-valid config onto library objects and never re-validates. Runtime checks are reserved for what only a live tokenizer, dataset, or GPU can reveal.
2. Heavy imports are lazy. torch/trl/peft are imported inside functions, keeping the CLI usable without them. Commands that need them check up front and print an install hint.
3. Deliberate errors are typed. Everything raised on purpose derives from TunepacError, so the CLI catches one type and exits cleanly — while genuine bugs still produce a traceback.

Development

pip install -e ".[dev]"
pytest            # unit tests; integration tests skip without the [train] extra
ruff check .      # lint
mypy              # strict type-checking

The merge test asserts that a LoRA-targeted weight changed while an untargeted one did not — so a merge that silently copied the base would fail.

CI runs ruff + strict mypy, the unit suite with coverage on Python 3.10/3.11/3.12, and the integration suite on CPU-only torch.

Contributions welcome — keep pytest, ruff check . and mypy green, add tests for behavior changes, and treat schema changes as API changes.

Roadmap

License

MIT