@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/fastapi/scripts/verify.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+#
+# verify.sh — quality gate for a FastAPI / async Python project.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]
+#
+# Runs lint, format-check, type-check, tests+coverage, and a dependency audit.
+# Auto-detects each tool. If a tool is missing it prints a yellow SKIP and continues
+# (it never FAILs on a missing tool). Prefers `uv run <tool>` when `uv` is present,
+# else the bare tool on PATH. Exits non-zero only if a tool actually ran and reported
+# a failure. Idempotent: re-running yields the same result (read-only beyond whatever
+# the project's pytest does).
+#
+# COVERAGE IS ONLY A GATE IF YOUR PROJECT MAKES IT ONE. The threshold is deliberately
+# delegated to the project (--cov-fail-under in pyproject.toml / setup.cfg / .coveragerc)
+# rather than hardcoded here. But when the project sets none, `pytest --cov` prints a
+# percentage and exits 0 however far coverage falls — and a layer that prints a number and
+# exits 0 is a report, not a gate. That case is reported as [gap] instead of PASS, because
+# the two are indistinguishable on screen and the broken one can only ever produce green:
+# no failing run will ever surface it.
+#
+# A [gap] does NOT change the exit code — breaking every repo that passes today is not this
+# script's call. This script reports; the `verify` skill judges, and there a gap counts as
+# an unverified criterion, which fails the verdict.
+#
+# Compatible with stock macOS bash 3.2: no `mapfile`, no associative arrays, and every
+# array access is guarded so `set -u` never trips on an "unbound" empty array.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+# --- color helpers (guarded for non-TTY) ---
+if [ -t 1 ]; then
+  RED=$'\033[0;31m'; GREEN=$'\033[0;32m'; YELLOW=$'\033[0;33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+warn() { printf '%s%s%s\n' "$YELLOW" "$*" "$RESET"; }
+ok()   { printf '%s%s%s\n' "$GREEN" "$*" "$RESET"; }
+fail() { printf '%s%s%s\n' "$RED" "$*" "$RESET"; }
+
+PASSED=0; SKIPPED=0; FAILED=0; GAPS=0
+
+# gap <reason> — the layer ran and had nothing to fail with. Counted and printed, but it
+# deliberately does NOT touch FAILED: see the header note on why the exit code is unchanged.
+gap() { printf '%sGAP: %s%s\n' "$YELLOW" "$*" "$RESET"; GAPS=$((GAPS + 1)); }
+
+# coverage_threshold_configured — does the project actually gate on coverage?
+# Looks for pytest's --cov-fail-under (addopts or a bare flag) and coverage.py's fail_under.
+# Grep rc: 0 = found, 1 = not found, >=2 = the scan itself broke. Treat "broke" as NOT
+# configured so the answer errs toward reporting a gap; a broken scan must never buy a pass.
+coverage_threshold_configured() {
+  local f rc
+  for f in "$TARGET/pyproject.toml" "$TARGET/setup.cfg" "$TARGET/tox.ini" "$TARGET/.coveragerc" "$TARGET/pytest.ini"; do
+    [ -f "$f" ] || continue
+    grep -qE 'cov-fail-under|fail_under' "$f" && return 0
+    rc=$?
+    if [ "$rc" -ge 2 ]; then
+      warn "NOTE: could not read '${f}' while checking for a coverage threshold; treating it as absent"
+    fi
+  done
+  return 1
+}
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# Detect-or-skip: a real Python project has a project manifest or at least one *.py
+# under TARGET. With neither, there is nothing to verify, so SKIP (exit 0) instead of
+# letting pytest report "no tests collected" as a FAIL. This guards only the empty case;
+# inside a real project every tool still runs and real failures still surface.
+python_project_present() {
+  if [ -f "$TARGET/pyproject.toml" ] || [ -f "$TARGET/setup.py" ] || [ -f "$TARGET/setup.cfg" ]; then
+    return 0
+  fi
+  # Any .py file under TARGET (bash 3.2: use find, no globstar).
+  if [ -n "$(find "$TARGET" -type f -name '*.py' -print -quit 2>/dev/null)" ]; then
+    return 0
+  fi
+  return 1
+}
+
+if ! python_project_present; then
+  warn "SKIP: no Python project found under '${TARGET}' (no pyproject.toml/setup.py/setup.cfg and no *.py)"
+  ok "verify.sh: ok (nothing to verify)"
+  exit 0
+fi
+
+# Do we have uv? When yes, tools run through `uv run`, which can resolve a tool from the
+# project venv even if it is not on PATH.
+USE_UV=0
+if have uv; then USE_UV=1; fi
+
+# tool_available <tool>
+# True when the tool can actually be invoked: either it is on PATH, or (under uv) it can
+# be resolved and reports a version. Probing under uv is what lets us SKIP (not FAIL) a
+# tool that is genuinely absent from the project's environment.
+tool_available() {
+  local tool="$1"
+  if have "$tool"; then
+    return 0
+  fi
+  if [ "$USE_UV" -eq 1 ]; then
+    if uv run --quiet "$tool" --version >/dev/null 2>&1; then
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# run_step <label> <tool> <args...>
+run_step() {
+  local label="$1"; local tool="$2"; shift 2
+  if ! tool_available "$tool"; then
+    warn "SKIP: ${label} (${tool} not installed)"
+    SKIPPED=$((SKIPPED + 1))
+    return 0
+  fi
+  printf '==> %s\n' "$label"
+  if [ "$USE_UV" -eq 1 ]; then
+    if uv run "$tool" "$@"; then
+      ok "PASS: ${label}"; PASSED=$((PASSED + 1))
+    else
+      fail "FAIL: ${label}"; FAILED=$((FAILED + 1))
+    fi
+  else
+    if "$tool" "$@"; then
+      ok "PASS: ${label}"; PASSED=$((PASSED + 1))
+    else
+      fail "FAIL: ${label}"; FAILED=$((FAILED + 1))
+    fi
+  fi
+}
+
+run_step "ruff check"        ruff check "$TARGET"
+run_step "ruff format check" ruff format --check "$TARGET"
+run_step "mypy"              mypy "$TARGET"
+run_step "pytest + coverage" pytest --cov --cov-report=term-missing
+# Only meaningful if pytest actually ran; a SKIP already says nothing was measured.
+if tool_available pytest && ! coverage_threshold_configured; then
+  gap "coverage ran without a threshold (no --cov-fail-under / fail_under found) — this layer cannot fail. Add --cov-fail-under=<n> to pyproject.toml addopts to make it a gate."
+fi
+run_step "pip-audit"         pip-audit
+
+printf '\n%d passed, %d skipped, %d failed, %d gap(s)\n' "$PASSED" "$SKIPPED" "$FAILED" "$GAPS"
+if [ "$GAPS" -gt 0 ]; then
+  warn "A GAP is neither a pass nor a failure: the layer ran and could not have failed. Report it as unverified."
+fi
+if [ "$FAILED" -gt 0 ]; then
+  fail "verify.sh: failures detected"
+  exit 1
+fi
+# "every check that could fail, passed" rather than a bare ok: with a GAP present, the
+# stronger claim would be false in exactly the way this script now exists to prevent.
+ok "verify.sh: ok (every check that could fail, passed)"
+exit 0

package/skills/shared/finetuning/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: finetuning
+description: "Use when adapting an open-weight model to a target form or behavior — tone, output format, reasoning pattern — via LoRA/QLoRA or full fine-tuning with TRL SFTTrainer, then preference optimization (DPO/ORPO/KTO/GRPO), and for fine-tune vs prompt vs RAG. NOT adding facts to a model (that is rag); NOT the single-GPU Unsloth backend or GGUF export (that is unsloth)."
+tags: [finetuning, lora, qlora, sft, dpo, grpo, peft, trl, preference-optimization]
+recommends: [training-data, unsloth, open-weights, huggingface, vllm, rag]
+origin: ai-hub
+---
+
+# finetuning — teach an open model a form or behavior, not a fact
+
+You own the discipline of **adapting an open-weight model**: deciding whether to fine-tune at all,
+then running SFT and (optionally) preference optimization with `trl` + `peft`, backend-agnostic.
+You are judged by whether the tuned model reliably produces the target **form/behavior** on a
+held-out set — not by train loss, and not by vibes.
+
+The one sentence that routes half of all "should I fine-tune?" questions correctly:
+**fine-tuning teaches *form and behavior*; RAG supplies *facts*.** If the ask is "know our latest
+prices / docs / tickets," that is retrieval (`../rag/SKILL.md`), not training. If the ask is "sound
+like us, always emit this JSON, follow this reasoning pattern," that is here.
+
+## Decision gate — try this BEFORE reaching for a GPU
+
+Fine-tuning is the last lever, not the first. Exhaust the cheaper, reversible options first; each
+row below is a real off-ramp.
+
+| If the goal is… | Do this first | Fine-tune only when… |
+|---|---|---|
+| The model should *know* current/company facts | **RAG** (`../rag/SKILL.md`) — retrieve + ground | never for facts; facts go stale, weights don't update |
+| One-off format/tone, small volume | **Prompt + few-shot** (`prompt-engineering`) | the prompt is huge, brittle, or you pay for it every call |
+| Behavior depends on a long document | **Longer context** / put it in the prompt | context won't fit, or per-call token cost is the bottleneck |
+| Consistent *form/behavior* at scale, latency/cost sensitive | — | prompting plateaus AND you have (or can build) good examples |
+| A capability the base model just can't do | — | you have a reward signal or demonstration data for it |
+
+Route out explicitly. Facts / freshness / citations → `../rag/SKILL.md`. Squeezing a prompt before
+spending money → `prompt-engineering`. Picking *which* base model (size/license/task) → `open-weights`.
+Building the JSONL/preference corpus → `training-data` (LLM corpora, NOT tabular cleaning — that is
+`data-cleaning`). A fast single-GPU run + GGUF export → `../unsloth/SKILL.md` (same LoRA/QLoRA
+concepts, one optimized implementation; this skill stays backend-agnostic). Downloading the base or
+pushing the adapter/merged model → `huggingface`. Serving the result → `../vllm/SKILL.md`.
+
+> The cheapest fine-tune is the one you didn't need. Prompt + RAG solves most "make it behave"
+> asks at zero training cost and updates instantly. Fine-tune when that ceiling is real, measured,
+> and you can afford to re-run it every time the base model or data changes.
+
+## Version reality (verify at author time — this stack moves monthly)
+
+- **`trl`** consolidated into a **v1.x** line (v1.0 landed ~2026; docs at author time referenced
+  ~v1.8). Every method has a `Trainer` + a `Config` dataclass that inherits
+  `transformers.TrainingArguments` (`SFTTrainer`/`SFTConfig`, `DPOTrainer`/`DPOConfig`, …). Confirm
+  the current major before pinning: `pip show trl` / the [TRL docs](https://huggingface.co/docs/trl).
+- **`transformers`** is on a **v5.x** line; `peft`, `bitsandbytes`, `accelerate`, `datasets`
+  round out the stack. Do not freeze a pin as "the version" — say "current major is ~X, verify."
+- Some methods migrated to `trl.experimental.*` (e.g. `from trl.experimental.orpo import ORPOTrainer`
+  at author time). Import paths churn — check the method's doc page before copying an import.
+- **Model licenses are not facts to memorize.** Llama ships under the Meta *Community* license
+  (usage caps, not OSI-open); Gemma under custom Google terms; Qwen/Mistral vary per size and often
+  Apache-2.0 — but **read the specific model card, licenses change.** License/size selection is
+  `open-weights`.
+
+## LoRA / QLoRA vs full fine-tuning
+
+Three options on one memory↔quality axis. Default to **QLoRA** unless you have a proven reason not to.
+
+| Method | What trains | Rough VRAM (7–8B) | Use when |
+|---|---|---|---|
+| **Full FT** | every weight, fp16/bf16 | very high (needs multi-GPU / offload) | you have the hardware and a large, high-quality corpus and adapters underfit |
+| **LoRA** | small low-rank adapter matrices; base frozen (fp16) | high | base fits in fp16 and you want adapter portability + speed |
+| **QLoRA** | LoRA adapters over a **4-bit NF4** frozen base | lowest — single consumer GPU for 7–13B | the default; fine-tune big models on one GPU with ~no quality loss |
+
+**QLoRA** (Dettmers et al., [arXiv:2305.14314](https://arxiv.org/abs/2305.14314)): load the base
+in 4-bit **NF4** with double quantization, keep it frozen, and train LoRA adapters in bf16 on top.
+It made single-GPU fine-tuning of large models practical at near-full-FT quality.
+
+```python
+import torch
+from transformers import BitsAndBytesConfig
+from peft import LoraConfig
+from trl import SFTTrainer, SFTConfig
+
+# 4-bit NF4 base (QLoRA). Verify arg names against current bitsandbytes/transformers.
+bnb = BitsAndBytesConfig(
+    load_in_4bit=True,
+    bnb_4bit_quant_type="nf4",
+    bnb_4bit_use_double_quant=True,
+    bnb_4bit_compute_dtype=torch.bfloat16,
+)
+
+# LoRA over ALL linear layers — the safe target for QLoRA (PEFT quantization guide).
+peft_config = LoraConfig(
+    r=16, lora_alpha=32, lora_dropout=0.05,
+    bias="none", task_type="CAUSAL_LM",
+    target_modules="all-linear",   # or explicit ["q_proj","k_proj","v_proj","o_proj",...]
+)
+
+trainer = SFTTrainer(
+    model="Qwen/Qwen2.5-7B-Instruct",       # instruct base → chat template already present
+    args=SFTConfig(output_dir="out", max_length=2048, packing=True,
+                   learning_rate=2e-4, num_train_epochs=2, bf16=True),
+    train_dataset=dataset,                    # conversational: TRL applies the chat template
+    peft_config=peft_config,
+    quantization_config=bnb,                  # SFTTrainer + peft_config + this == QLoRA
+)
+trainer.train()
+trainer.save_model("out")                     # saves the ADAPTER, not a merged model
+```
+
+`peft_config` + `quantization_config` on `SFTTrainer` is the current one-liner for QLoRA — no manual
+`get_peft_model` / `prepare_model_for_kbit_training` wiring needed. `save_model` writes the small
+adapter; merge to a standalone model only when serving requires it (see references).
+
+## Pipeline: SFT first, then (maybe) preference optimization
+
+`SFT → preference optimization` is the standard post-training arc. **SFT** teaches the model the
+format and gives it the behavior by imitation. **Preference optimization** then sharpens *which* of
+several plausible outputs is better. Most projects need only SFT; add a preference stage when "the
+outputs are fine but I want the *good* one preferred" is the remaining gap.
+
+| Method | Data it needs | Stage | Pick it when |
+|---|---|---|---|
+| **SFT** | demonstrations (chat/`messages` or prompt→completion) | base of everything | always first (except ORPO) |
+| **DPO** ([2305.18290](https://arxiv.org/abs/2305.18290)) | paired `chosen`/`rejected` | after SFT | you have pairwise preferences; the workhorse aligner |
+| **ORPO** ([2403.07691](https://arxiv.org/abs/2403.07691)) | paired preferences | **replaces** SFT+DPO (single stage, ref-free) | you want one pass from a base model and have pairs |
+| **KTO** ([2402.01306](https://arxiv.org/abs/2402.01306)) | *unpaired* binary good/bad labels | after SFT | you have thumbs-up/down, not matched pairs |
+| **GRPO** ([2402.03300](https://arxiv.org/abs/2402.03300); DeepSeek-R1 [2501.12948](https://arxiv.org/abs/2501.12948)) | a **reward function** (verifier), no pairs | after SFT | correctness is checkable (math/code/format) → RL for reasoning |
+
+Rule of thumb: **have pairs → DPO** (or ORPO to fuse the two stages); **have only up/down votes → KTO**;
+**can score an answer programmatically → GRPO**. Preference optimization uses a *tiny* learning rate.
+
+```python
+# DPO after SFT — dataset has prompt / chosen / rejected columns.
+from trl import DPOTrainer, DPOConfig
+trainer = DPOTrainer(
+    model="out",                              # your SFT checkpoint (or SFT+adapter)
+    args=DPOConfig(output_dir="dpo-out", beta=0.1,   # beta = KL strength to the ref model
+                   learning_rate=5e-7, max_length=1024,
+                   precompute_ref_log_probs=True),   # saves memory; ref model auto-created
+    train_dataset=pref_dataset,
+    peft_config=peft_config,                  # LoRA works for preference stages too
+)
+trainer.train()
+```
+
+```python
+# GRPO — no preference pairs, a reward FUNCTION that returns a score per completion.
+from trl import GRPOTrainer, GRPOConfig
+def format_reward(completions, **kwargs):     # signature: gets completions (+ dataset cols via kwargs)
+    return [1.0 if "\\boxed{" in c[0]["content"] else 0.0 for c in completions]
+
+trainer = GRPOTrainer(
+    model="out",
+    reward_funcs=[format_reward],             # one or many; GRPOConfig.reward_weights to combine
+    args=GRPOConfig(output_dir="grpo-out", num_generations=8,  # group size per prompt
+                    beta=0.04, learning_rate=1e-6, use_vllm=True),  # vLLM speeds rollouts
+    train_dataset=prompts_dataset,
+)
+trainer.train()
+```
+
+Full runnable SFT→DPO and GRPO scripts, ORPO/KTO variants, dataset schemas, and adapter-merge steps
+are in `references/methods.md`.
+
+## Data — quality over quantity (LIMA)
+
+More rows is not the win. **LIMA** ([arXiv:2305.11206](https://arxiv.org/abs/2305.11206)) got strong
+instruction-following from **~1,000** carefully curated examples — "less is more for alignment."
+A thousand clean, on-distribution, correctly-templated examples beat 100k scraped noisy ones, which
+actively teach the model bad form. Building and validating that corpus (JSONL `messages`, preference
+pairs, dedup, contamination checks) is `training-data` — bring it here already clean.
+
+## Hyperparameters — the few that move the needle
+
+- **LoRA `r` and `lora_alpha`**: `r` = adapter rank (capacity); effective scaling = `lora_alpha / r`.
+  Common heuristic **`alpha ≈ 2·r`** (e.g. r=16→alpha=32) so scaling ≈ 2; then adjust LR, not both.
+  Start `r=8–16` for style/format, higher (32–64+) for harder behavior. (Newer "LoRA-without-regret"
+  guidance favors `target_modules="all-linear"` + higher rank + tuned LR — verify current advice.)
+- **`target_modules`**: `"all-linear"` is the safe default. Targeting too few / wrong-named modules
+  is a top silent failure — the run "succeeds," loss barely moves, the adapter learned ~nothing.
+- **Learning rate**: LoRA/QLoRA SFT ~**1e-4–2e-4** (adapters tolerate higher LR than full FT, whose
+  ~2e-5 is the `SFTConfig` default). Preference optimization is far lower — **DPO ~5e-7, GRPO ~1e-6**.
+- **Epochs**: usually **1–3**. This is the overfitting knob — see below. Watch **eval** loss.
+- **Batch × grad-accum**: raise the *effective* batch with `gradient_accumulation_steps` when VRAM
+  caps `per_device_train_batch_size`. Enable `packing=True` + `gradient_checkpointing` to fit more.
+- **Warmup**: a short `warmup_ratio` (~0.03–0.1) stabilizes the early, high-gradient steps.
+
+## Catastrophic forgetting
+
+Fine-tuning on a narrow task can degrade general ability the base model had. Three mitigations,
+cheapest first: **use LoRA/QLoRA** (base weights frozen — inherently gentler than full FT); **keep
+the LR low and epochs few**; and **replay** — mix a slice of general instruction data into your
+task data so the model doesn't forget how to be a general assistant. If a tuned model suddenly
+"got dumber" at everything else, this is the usual cause.
+
+## Evaluation — a held-out set and a task metric, not a vibe-check
+
+A vibe-check is **not** an eval. Before training, split off a **held-out** set the model never sees,
+and define a concrete task metric (exact-match / JSON-valid rate / rubric score / a task-specific
+score). Judge the run on that, plus **eval loss**.
+
+- **Watch eval loss, not train loss.** Train loss falling while **eval loss rises** = overfitting →
+  fewer epochs, lower LR, more/cleaner data, or earlier checkpoint. Train loss always keeps falling;
+  it tells you nothing about generalization.
+- **Contamination**: if eval examples leaked into training, your metric is a lie. De-dup train vs
+  eval; keep the held-out set quarantined. (Corpus-side hygiene is `training-data`.)
+- General LLM/agent eval harness and judging → `agent-eval`. Bring your task metric here.
+
+The full tuning + forgetting + evaluation playbook is in `references/hyperparameters-and-eval.md`.
+
+## When NOT to fine-tune (anti-patterns)
+
+| Anti-pattern | Why it breaks | Do instead |
+|---|---|---|
+| Fine-tune to add facts / fresh knowledge | Weights memorize poorly and go stale; hallucinations | `../rag/SKILL.md` — retrieve + ground |
+| Fine-tune before trying prompt + few-shot | Slow, costly, irreversible for a prompt-solvable ask | `prompt-engineering` first |
+| Wrong / too-few `target_modules` | Adapter has no capacity where it matters → learns ~nothing | `"all-linear"` (or correct proj names) |
+| Judge success by train loss | Falls even while the model overfits | Held-out eval set + task metric + **eval** loss |
+| Crank epochs "to learn it better" | Overfits, forgets, memorizes noise | 1–3 epochs; stop when eval loss turns up |
+| Train with a wrong/absent chat template | Inference emits garbage / never stops | Match train template to serve; align `eos_token` |
+| A few dozen examples for full FT | Not enough signal; unstable | Curate ~hundreds–thousands (LIMA) or use LoRA |
+| Fine-tune a model you can't legally deploy | License blocks your use case | Check the model card first → `open-weights` |
+
+## Checklist
+
+- [ ] Ran the decision gate: confirmed this is a form/behavior need, not a facts need (else → rag).
+- [ ] Chose base model by license + size (→ `open-weights`); read the actual model card.
+- [ ] Picked method: QLoRA by default; full FT only with the hardware + a reason.
+- [ ] Data is clean, on-distribution, correctly templated (→ `training-data`); dedup vs eval.
+- [ ] Chat template applied at train time and it **matches** the serving template; `eos_token` aligned.
+- [ ] `target_modules="all-linear"` (or verified names); `alpha ≈ 2·r`; LoRA LR ~1e-4–2e-4.
+- [ ] Held-out eval set + a concrete task metric defined **before** training.
+- [ ] Trained 1–3 epochs; watched **eval** loss (not train) for the overfitting turn.
+- [ ] Preference stage only if needed; correct method for the data (pairs→DPO/ORPO, votes→KTO, verifier→GRPO); tiny LR.
+- [ ] Verified `trl`/`peft`/`transformers` current majors and import paths at author time.

package/skills/shared/finetuning/evals/README.md

@@ -0,0 +1,13 @@
+# finetuning evals — how to run
+
+Routing and capability checks, not unit tests. Run the `should_trigger` prompts against your skill
+router and confirm `finetuning` fires (form/behavior adaptation, method choice, pipeline, and the
+overfit/forgetting/target_modules diagnostics). Run `should_not_trigger` and confirm the router
+defers to the named sibling instead (`rag` for facts, `prompt-engineering` for the cheaper lever,
+`open-weights` for base-model choice, `training-data` for corpus building, `vllm` for serving,
+`unsloth` for the fast single-GPU backend) — a miss there means the boundary in the description
+needs sharpening. For the `capability` case, hand the scenario to an agent with this skill loaded
+and grade the answer against each `must_include` bullet pass/fail: the decision gate (form vs
+facts), QLoRA + TRL/PEFT current API, the alpha≈2r and LR/epoch hyperparameters, the chat-template
+guardrail, LIMA quality-over-quantity, held-out eval watching eval loss, KTO for unpaired feedback,
+and the version/license hedge.

package/skills/shared/finetuning/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: finetuning
+
+should_trigger:
+  - prompt: "We want Qwen to always answer in our brand voice and emit a fixed JSON schema — fine-tune it on ~2k of our examples."
+    why: A form/behavior adaptation (tone + output format) with demonstrations — the core SFT use case finetuning owns.
+  - prompt: "Should I use LoRA, QLoRA, or full fine-tuning to adapt an 8B model on a single 24GB GPU?"
+    why: The memory/quality method choice (LoRA vs QLoRA vs full FT) is squarely this skill's decision.
+  - prompt: "I ran SFT and now want to prefer the better of two answers — set up DPO after it with our chosen/rejected pairs."
+    why: SFT → preference optimization pipeline; picking DPO for paired preference data is finetuning's job.
+  - prompt: "My fine-tune's train loss keeps dropping but eval loss is climbing and it forgot general chat — what's wrong?"
+    why: Overfitting (watch eval not train loss) plus catastrophic forgetting — both are finetuning diagnostics.
+  - prompt: "My LoRA run finished but the adapter barely changed anything — did I set target_modules wrong?"
+    why: The classic silent failure (wrong/too-few target_modules → adapter learns ~nothing) lives here.
+  - prompt: "Correctness is checkable for our math tasks — write a GRPO reward function to RL the model toward right answers."
+    why: GRPO with a reward function for a verifiable task is a finetuning preference-optimization method.
+  - prompt: "Ajustar un model Qwen amb LoRA amb les nostres dades perquè segueixi el nostre estil."
+    why: Catalan — LoRA fine-tuning to teach a house style is a form/behavior adaptation this skill owns.
+
+should_not_trigger:
+  - prompt: "The bot needs to answer from our latest policy PDFs and cite them — it keeps giving stale info."
+    route_to: rag
+    why: Facts/freshness/citations are supplied by retrieval, not baked into weights — fine-tuning teaches form, not facts.
+  - prompt: "The prompt works sometimes; can I get consistent JSON with a few-shot example instead of training?"
+    route_to: prompt-engineering
+    why: The cheaper, reversible lever to exhaust before spending a GPU; no training needed.
+  - prompt: "Which open model should I pick by license and size for commercial use — Llama vs Qwen vs Mistral?"
+    route_to: open-weights
+    why: Base-model selection by license/size/task is the choice layer feeding finetuning, not the training method.
+  - prompt: "Build and dedup our instruction JSONL and preference pairs corpus and check for contamination."
+    route_to: training-data
+    why: Constructing/validating the training corpus is training-data; finetuning consumes an already-clean corpus.
+  - prompt: "Run our fine-tuned model as a high-throughput API with batching and adapter hot-swapping."
+    route_to: vllm
+    why: Serving the trained model (throughput, adapter hot-swap) is vllm, not the training discipline.
+  - prompt: "Give me the fastest single-GPU way to fine-tune and export a GGUF for llama.cpp."
+    route_to: unsloth
+    why: A specific fast single-GPU backend plus GGUF export is unsloth; finetuning stays backend-agnostic.
+
+capability:
+  - scenario: "A team wants an 8B open model to consistently reply in their support tone and always return a fixed JSON envelope, on one 24GB GPU. They have ~1,500 curated examples and later some thumbs-up/down feedback. Design the approach end to end."
+    must_include:
+      - Applies the decision gate and confirms this is a form/behavior task (tone + format), explicitly contrasting it with RAG (facts) and prompting.
+      - Chooses QLoRA (4-bit NF4 base + LoRA adapters, arXiv 2305.14314) as the memory-efficient default for a single 24GB GPU.
+      - Uses TRL SFTTrainer with an SFTConfig and a PEFT LoraConfig, passing peft_config (and quantization_config for QLoRA); target_modules="all-linear".
+      - States LoRA hyperparameters: r/alpha with the alpha≈2r heuristic and a LoRA-appropriate learning rate (~1e-4–2e-4), 1–3 epochs.
+      - Warns that the chat template at train time must match serving and eos_token must be aligned, or inference outputs garbage.
+      - Notes the ~1,500 curated examples fit LIMA's quality-over-quantity finding (2305.11206) and routes corpus building to training-data.
+      - Defines evaluation on a held-out set with a task metric and says to watch EVAL loss (not train loss) for overfitting, plus contamination check.
+      - For the later thumbs-up/down feedback, recommends KTO (unpaired binary preference) rather than DPO (which needs paired chosen/rejected).
+      - Hedges that trl/peft/transformers versions and import paths (and model licenses) must be verified at author time as they change frequently.

package/skills/shared/finetuning/references/hyperparameters-and-eval.md

@@ -0,0 +1,74 @@
+# hyperparameters, forgetting & evaluation — the tuning playbook
+
+Depth overflow for `SKILL.md`. Defaults are starting points, not laws; the eval set is the judge.
+
+## LoRA capacity: r, alpha, target_modules
+
+The adapter adds two low-rank matrices per targeted layer; its output is scaled by
+**`lora_alpha / r`**. So `r` sets *capacity* and `alpha` sets *how strongly* the adapter speaks.
+
+- **`r`** — rank / capacity. `8–16` for style, tone, format nudges; `32–64+` for harder new
+  behavior or larger models. Bigger `r` = more trainable params = more VRAM and more overfit risk.
+- **`alpha`** — common heuristic **`alpha ≈ 2·r`** (scaling ≈ 2). Fix that ratio and tune the LR
+  rather than juggling both knobs at once.
+- **`target_modules`** — `"all-linear"` is the safe default and is the recommended setting for
+  QLoRA (LoRA on every linear layer). Naming only a couple of projections, or misspelling them, is
+  a top silent failure: the run completes, loss barely moves, the adapter learned ~nothing. Newer
+  "LoRA-without-regret" guidance favors all-linear + higher rank + a tuned LR — verify current advice.
+- **`lora_dropout`** ~`0.05`, **`bias="none"`**, **`task_type="CAUSAL_LM"`** are the usual defaults.
+
+## Learning rate, epochs, batch, warmup
+
+| Knob | SFT (LoRA/QLoRA) | Full FT | Preference (DPO/KTO/GRPO) |
+|---|---|---|---|
+| Learning rate | ~1e-4 – 2e-4 | ~2e-5 (SFTConfig default) | DPO/KTO ~5e-7 · GRPO ~1e-6 |
+| Epochs | 1–3 | 1–3 | usually 1 |
+| Warmup ratio | 0.03 – 0.1 | 0.03 – 0.1 | 0.03 – 0.1 |
+
+- **Effective batch = `per_device_train_batch_size × gradient_accumulation_steps × world_size`.**
+  When VRAM caps the per-device batch, raise `gradient_accumulation_steps` to reach a stable
+  effective batch (commonly 16–64) without more memory.
+- **Fit-more levers**: `packing=True` (fills sequences to `max_length`, less padding waste),
+  `gradient_checkpointing=True` (trade compute for memory), QLoRA 4-bit base, `activation_offloading`.
+- **Epochs is the overfitting dial.** Adapters memorize a small corpus fast; 1–3 passes is normal.
+  Prefer more/cleaner data over more epochs.
+
+## Catastrophic forgetting
+
+Narrow fine-tuning can erode general ability. Mitigations, cheapest first:
+
+1. **LoRA/QLoRA over full FT** — base weights stay frozen, so the model can't overwrite what it
+   knew; the adapter is a small, removable delta.
+2. **Low LR, few epochs** — big updates on a narrow task are what erase general skills.
+3. **Replay / data mixing** — blend a slice of general instruction data into the task data so the
+   model keeps its assistant behavior. A common mix is a minority fraction of general data.
+
+Symptom: the tuned model nails the target task but "got dumber" everywhere else. That is forgetting,
+not a data bug — pull LR/epochs down and add replay.
+
+## Evaluation — the part people skip and regret
+
+1. **Split a held-out set before training** the model never sees. Keep it quarantined.
+2. **Define a concrete task metric** up front: exact-match, JSON-valid rate, a rubric/LLM-judge
+   score, or a domain metric. "Looks good" is not a metric.
+3. **Watch eval loss, not train loss.** Train loss always falls. When **eval loss turns upward**
+   while train loss keeps dropping, you are overfitting — stop, lower LR, add data, or take an
+   earlier checkpoint. Set `eval_strategy="steps"` + `eval_steps` and log both curves.
+4. **Contamination kills the signal.** If eval examples leaked into training, the metric is a lie.
+   De-dup train against eval; corpus-side hygiene is `training-data`.
+5. **Compare against the untuned baseline** on the same held-out set — a fine-tune that doesn't
+   beat "base model + a good prompt" was not worth the GPU (loop back to the decision gate).
+
+The general LLM/agent eval harness (judges, scoring pipelines, regression gates) is `agent-eval`;
+bring your task-specific metric here and gate the run on it.
+
+## A pre-flight sanity pass (catch the silent failures early)
+
+- Print one fully-rendered training example (post chat-template) and read it — is the template
+  right, are special tokens present, is the assistant span the only thing in the loss?
+- Confirm trainable-param count is non-trivial (`model.print_trainable_parameters()` on the PEFT
+  model). Near-zero or "no trainable params" means `target_modules` missed.
+- Overfit a tiny batch (a few dozen rows) on purpose — train loss should crash toward zero. If it
+  won't, the wiring (template / targets / labels) is broken before you spend on the full run.
+- Generate from the checkpoint with the **serving** template and eyeball a handful of outputs for
+  the failure mode you're fixing.