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

package/skills/shared/together-fireworks/scripts/verify.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static lint for Together AI / Fireworks AI inference snippets.
+#
+# WHAT IT DOES (read-only; never edits, never hits the network, no API key needed)
+#   Greps target .py/.ts/.js/.tsx/.jsx files that mention Together or Fireworks and
+#   flags the classic mistakes:
+#     1. A together/fireworks API key (or its base_url) paired with api.openai.com
+#        -> FAIL (the key only authenticates against its own host).
+#     2. A bare model name (no namespace) when a Together/Fireworks base_url is
+#        present -> FAIL. Together needs "<vendor>/<model>"; Fireworks needs
+#        "accounts/fireworks/models/<name>".
+#     3. A hardcoded API-key string literal (api_key="sk-..."/literal) where an
+#        env var belongs -> FAIL (committed key = leaked key).
+#     4. Wrong/legacy base_url for the provider in use -> WARN (verify the exact
+#        host: https://api.together.ai/v1 or https://api.fireworks.ai/inference/v1).
+#
+# EXIT CODES
+#   0  clean, or no relevant file to inspect (empty/clean target is NOT a failure)
+#   1  at least one [fail] finding
+#   2  bad usage
+#
+# HOW TO RUN (point it at YOUR code, not the skills repo)
+#   ./verify.sh app.py                 # lint one file
+#   ./verify.sh --path src/            # lint every .py/.ts/.js under a dir
+#   ./verify.sh                        # scan ./ ; if nothing matches, skip + exit 0
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    -*)        printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *)         SCAN_PATH="$1"; shift ;;
+  esac
+done
+[ -z "$SCAN_PATH" ] && SCAN_PATH="."
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+# --- collect candidate source files ----------------------------------------
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f \
+    \( -name '*.py' -o -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' \) \
+    2>/dev/null || true)"
+fi
+
+# Keep only files that actually reference these providers (so we never false-fail
+# on unrelated code).
+RELEVANT=""
+if [ -n "$FILES" ]; then
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    if grep -iEq 'together\.ai|fireworks\.ai|TOGETHER_API_KEY|FIREWORKS_API_KEY|accounts/fireworks/models' "$f" 2>/dev/null; then
+      RELEVANT="$RELEVANT$f
+"
+    fi
+  done <<EOF
+$FILES
+EOF
+fi
+
+# Empty / clean target is NOT a failure.
+if [ -z "$RELEVANT" ]; then
+  skip "no Together/Fireworks inference code found under '$SCAN_PATH' — nothing to lint"
+  exit 0
+fi
+
+n_files="$(printf '%s' "$RELEVANT" | grep -c . || true)"
+printf 'Linting %s Together/Fireworks file(s) under: %s\n\n' "$n_files" "$SCAN_PATH"
+
+fail_total=0
+
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  printf '%s— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  uses_together=0; uses_fireworks=0
+  grep -iEq 'together\.ai|TOGETHER_API_KEY' "$f" 2>/dev/null && uses_together=1
+  grep -iEq 'fireworks\.ai|FIREWORKS_API_KEY|accounts/fireworks/models' "$f" 2>/dev/null && uses_fireworks=1
+
+  # 1. provider key/url paired with the OpenAI host -> FAIL
+  if grep -iEq 'api\.openai\.com' "$f" 2>/dev/null; then
+    hits="$(grep -inE 'api\.openai\.com' "$f" 2>/dev/null || true)"
+    fail "  api.openai.com used in a Together/Fireworks file — a provider key only works on its own host:"
+    printf '%s\n' "$hits" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  no api.openai.com host mixed in"
+  fi
+
+  # 4. base_url present and correct -> WARN if a provider is used but its exact URL is absent
+  if [ "$uses_together" -eq 1 ]; then
+    if grep -Eq 'https://api\.together\.ai/v1' "$f" 2>/dev/null; then
+      ok "  Together base_url present and correct"
+    elif grep -iEq 'base_?url|baseURL' "$f" 2>/dev/null; then
+      warn "  Together used but exact base_url not found — expect https://api.together.ai/v1"
+    fi
+  fi
+  if [ "$uses_fireworks" -eq 1 ]; then
+    if grep -Eq 'https://api\.fireworks\.ai/inference/v1' "$f" 2>/dev/null; then
+      ok "  Fireworks base_url present and correct"
+    elif grep -iEq 'base_?url|baseURL' "$f" 2>/dev/null; then
+      warn "  Fireworks used but exact base_url not found — expect https://api.fireworks.ai/inference/v1"
+    fi
+  fi
+
+  # 2. bare model name (no namespace slash) -> FAIL
+  #    Capture model="..."/model: "..." values; a valid id contains a '/'.
+  bare="$(grep -inE 'model[[:space:]]*[:=][[:space:]]*["'\''][^"'\'']+["'\'']' "$f" 2>/dev/null \
+            | grep -vE 'model[[:space:]]*[:=][[:space:]]*["'\''][^"'\'']*/' \
+            | grep -viE 'os\.environ|process\.env|getenv|LLM_MODEL' || true)"
+  if [ -n "$bare" ]; then
+    fail "  bare model id (missing namespace '/') — Together needs <vendor>/<model>, Fireworks needs accounts/fireworks/models/<name>:"
+    printf '%s\n' "$bare" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  model ids are namespaced (or env-driven)"
+  fi
+
+  # 3. hardcoded API key literal -> FAIL
+  hard="$(grep -inE 'api_?key[[:space:]]*[:=][[:space:]]*["'\''](sk-|fw_|[A-Za-z0-9]{16,})' "$f" 2>/dev/null \
+            | grep -viE 'os\.environ|process\.env|getenv|(^|[[:space:]])//|(^|[[:space:]])#' || true)"
+  if [ -n "$hard" ]; then
+    fail "  hardcoded API key literal — read it from an env var instead:"
+    printf '%s\n' "$hard" | head -n 5 | sed 's/^/        /'
+    fail_total=$((fail_total + 1))
+  else
+    ok "  API key is read from an env var"
+  fi
+
+  printf '\n'
+done <<EOF
+$RELEVANT
+EOF
+
+cat <<'NOTE'
+Note: [fail] = a routing/security bug that breaks the call or leaks a secret (fix it).
+      [warn] = the exact base_url string wasn't found (confirm the host is right).
+NOTE
+
+if [ "$fail_total" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/shared/training-data/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: training-data
+description: "Use when assembling or curating the corpus a fine-tune trains on — turning raw examples into the JSONL shape a trainer expects (instruction, conversational, preference-pair or binary-label), matching the data to the model's chat template, generating synthetic or distilled examples, deduplicating and decontaminating against eval sets, and quality-filtering. NOT cleaning tabular rows, nulls and dtypes (that is `data-cleaning`), NOT building a retrieval corpus of chunks and embeddings (that is `embeddings-search`), NOT running the trainer or picking hyperparameters (that is `finetuning`)."
+tags: [training-data, fine-tuning-dataset, jsonl, chat-template, preference-data, dpo, kto, synthetic-data, decontamination, dataset-curation]
+recommends: [finetuning, unsloth, huggingface, data-cleaning]
+origin: ai-hub
+---
+
+# training-data — the corpus a fine-tune actually eats
+
+You own the **training corpus**: the JSONL of chat turns, instruction triples, or preference
+pairs that a trainer reads. The deliverable is a validated, deduplicated, decontaminated,
+license-clean file in the **exact shape the trainer expects**, rendered through the **target
+model's chat template**. You stop the moment that file loads cleanly and round-trips through
+`apply_chat_template`. You do not choose LoRA rank or launch the run — that is
+[`finetuning`](../finetuning/SKILL.md) / [`unsloth`](../unsloth/SKILL.md).
+
+**Loud boundary.** This is *LLM training corpora* — messages, instruction triples, preference
+pairs. It is **not**:
+
+- Tabular row cleaning — nulls, dtypes, dedupe of CSV rows, category normalization → [`data-cleaning`](../data-cleaning/SKILL.md).
+- A *retrieval* corpus — chunking documents and embedding them for search → [`embeddings-search`](../embeddings-search/SKILL.md).
+- Actually training or serving — hyperparameters, the run, export → [`finetuning`](../finetuning/SKILL.md), [`unsloth`](../unsloth/SKILL.md), [`huggingface`](../huggingface/SKILL.md).
+
+**Version reality (verified July 2026 — re-verify, these move monthly).** TRL is on the **v1.x**
+line (its dataset-formats doc was tagged `v1.8.0` at author time); `transformers` is in the
+**4.57+** era (mixed text+vision data needs ≥4.57); `datasets` is **4.x** (the `Json()` feature
+type needs ≥4.7). Pin whatever you install — do not trust these numbers as current.
+
+## 1. The format the trainer expects (pick by trainer, not by taste)
+
+The trainer dictates the columns. Get this wrong and TRL either errors or, worse, trains on a
+mangled string. Two axes: **format** (`standard` = plain strings vs `conversational` =
+`messages` lists) and **type** (the task). One JSON object per line = JSONL.
+
+| Trainer | Dataset type | Required keys |
+| --- | --- | --- |
+| `SFTTrainer` | language-modeling **or** prompt-completion | `messages` / `text`, or `prompt`+`completion` |
+| `DPOTrainer`, `ORPOTrainer`, `CPOTrainer` | preference (explicit prompt recommended) | `prompt`, `chosen`, `rejected` |
+| `KTOTrainer`, `BCOTrainer` | unpaired preference (binary label) | `prompt`, `completion`, `label` |
+| `RewardTrainer` | preference (implicit prompt) | `chosen`, `rejected` |
+| `GRPOTrainer`, `RLOOTrainer`, `PPOTrainer` | prompt-only | `prompt` |
+
+Tiny JSONL of each (conversational values are **lists of `{role, content}`**; `label` is a JSON
+boolean):
+
+```jsonl
+# Alpaca instruction (standard) — classic; NOT a native TRL type, see below
+{"instruction": "Classify the sentiment.", "input": "The battery dies in an hour.", "output": "negative"}
+
+# Conversational messages (SFT) — the default for chat fine-tunes
+{"messages": [{"role": "system", "content": "You are a terse support agent."}, {"role": "user", "content": "My order never arrived."}, {"role": "assistant", "content": "Sorry about that — what is your order number?"}]}
+
+# Preference pair (DPO) — chosen beats rejected for the same prompt
+{"prompt": [{"role": "user", "content": "Define a hash map in one sentence."}], "chosen": [{"role": "assistant", "content": "A hash map stores key-value pairs and finds a value by hashing its key to a bucket, giving average O(1) lookup."}], "rejected": [{"role": "assistant", "content": "It's a fast dictionary thing."}]}
+
+# KTO / unpaired preference — one completion + a good/bad boolean label
+{"prompt": [{"role": "user", "content": "Define a hash map in one sentence."}], "completion": [{"role": "assistant", "content": "It's a fast dictionary thing."}], "label": false}
+```
+
+**Alpaca is not a native TRL type.** `{instruction, input, output}` is the Stanford-Alpaca
+convention, still common in Unsloth notebooks, but TRL trains on `text`/`messages`/`prompt`+
+`completion`. You must either (a) map it into `messages` (instruction+input → user, output →
+assistant), or (b) render it into a single `text` string via a prompt template — **and append
+the EOS token yourself**, or the model never learns to stop (the #1 Unsloth-Alpaca bug). Prefer
+(a) `messages` for chat models. Full field matrix, tool-calling (`tools` column) and vision
+(`images`) extras, and every type→type conversion live in `references/formats.md`.
+
+## 2. Chat templates — the silent run-wrecker
+
+A chat template is a **Jinja** string stored in the tokenizer (in `tokenizer_config.json` under
+`chat_template`, or a standalone `chat_template.jinja` in newer tokenizers). It maps a `messages`
+list to the exact token string the model was trained on — special tokens (`<|im_start|>`,
+`[INST]`, `<|start_header_id|>`, …) and all. You render it, you never hand-type it:
+
+```python
+from transformers import AutoTokenizer
+tok = AutoTokenizer.from_pretrained("<target-model>")   # the model you will fine-tune
+
+# TRAINING: no trailing generation prompt — the assistant turn is already in the data
+text = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=False)
+
+# INFERENCE: add_generation_prompt=True appends the assistant turn-start so the model continues
+prompt = tok.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
+```
+
+Three ways this silently destroys a run — **no error, just a worse model**:
+
+- **Hand-formatting the tokens.** Writing `<|im_start|>user\n…` strings yourself and getting one
+  token, one newline, or the BOS wrong. Train-time string ≠ inference-time string → the model
+  learns a distribution it is never served. Always render via `apply_chat_template`.
+- **Using the wrong model's template.** The template must be the one of the model you are
+  fine-tuning. Copy Llama's template onto a Qwen fine-tune and every example is subtly malformed.
+- **A base model with no template at all.** Base (non-instruct) checkpoints often ship
+  `chat_template = None`. `apply_chat_template` then raises — you must **choose and attach** a
+  template (e.g. ChatML) and use that same one at inference forever after.
+
+Also decide **loss masking**: for chat SFT you usually train only on the assistant tokens
+(`completion_only_loss` / assistant-only masking in SFTTrainer, or a completion-only collator),
+so the model is not penalized for "predicting" the user's words. TRL applies the template for
+you when the dataset is conversational — let it, rather than pre-flattening to `text`.
+
+## 3. Synthetic data & distillation
+
+Not enough real examples? Generate them. Two workhorses: **Self-Instruct** (seed a few
+hand-written examples, prompt a strong model to produce more, filter) and **Evol-Instruct**
+(iteratively mutate prompts to be harder/deeper). Wrap them in a pipeline framework rather than
+ad-hoc loops (see §7).
+
+**Licensing trap — read before you distill.** Generating your training data from *another
+model's outputs* ("distillation") is a **terms-of-service question, not just a quality one**.
+Some providers' terms restrict using their outputs to train competing models; some open-weight
+licenses carry naming/derivative obligations (e.g. Llama-derived data/models may inherit naming
+requirements). Never assert a model's license from memory — check the specific model card and
+provider ToS at author time (licenses change). If in doubt, distill from an
+openly-licensed-for-this-use model, and record the provenance per example.
+
+## 4. Dedup + decontamination (skip these and your numbers lie)
+
+- **Dedup.** Exact dedup is trivial (hash the text). Real corpora need **near-dup** removal:
+  **MinHash + LSH** (Jaccard similarity over shingles) catches templated/boilerplate repeats
+  that inflate a few patterns. Dupes waste compute and bias the model toward whatever is
+  over-represented.
+- **Decontamination — the one people forget.** Remove any training example that overlaps your
+  **eval / benchmark test sets** (n-gram overlap, e.g. long-n-gram match against MMLU, GSM8K,
+  your own held-out set). If test items leak into training, your eval score is **inflated** and
+  meaningless — you measured memorization, not capability. Decontaminate *against every metric
+  you will report*, including your private eval. Code for both in `references/synthesis-dedup-quality.md`.
+
+## 5. Quality filtering — a few thousand clean beats a noisy dump
+
+**LIMA** (*Less Is More for Alignment*, arXiv **2305.11206**) is the anchor: ~1,000 carefully
+curated examples produced a strong instruction-follower — for **alignment/style** SFT, quality
+and diversity dominate raw volume. (This is about teaching *behavior/format*, not injecting a
+lot of new *knowledge* — a broad knowledge shift still wants scale.) Cheap, high-leverage
+filters, applied before you spend GPU hours:
+
+- **Length/format**: drop empty or truncated turns, runaway-length outliers, malformed JSON,
+  wrong-role sequences (two `assistant` turns in a row, missing final assistant turn for SFT).
+- **Dedup + decontam** from §4.
+- **Diversity**: cluster/embed and prune near-identical intents so the set is not 80% one task.
+- **Model/heuristic scoring**: rate helpfulness/correctness (a reward model or an LLM judge) and
+  keep the top slice — but audit the judge, LLM-as-judge has its own biases.
+
+## 6. Licensing — two separate questions
+
+1. **The dataset's own license** — what *you* release the JSONL under, and whether you *can*
+   release it (aggregating others' data does not launder their licenses).
+2. **Source-usage restrictions** — the terms on where each example *came from*: scraped-site
+   ToS, the license of any base dataset you built on, and the model-output ToS from §3. These
+   bind even if you never publish. Keep a provenance column so an audit can trace every row.
+
+State the license *class* and point at the source; never freeze a license as bare fact.
+
+## 7. Tooling
+
+- **distilabel** (Argilla, now under Hugging Face) — the go-to synthetic-data / AI-feedback
+  pipeline framework: composable `Step`/`Task` graphs (`TextGeneration`, `UltraFeedback`,
+  `EvolInstruct`), serializable to YAML/JSON, outputs a `Distiset` you push to the Hub. v1.x.
+- **Argilla** — human-in-the-loop annotation/review UI to label and vet examples.
+- **HF `datasets`** — load/`map`/`filter`/`push_to_hub`; the substrate everything else speaks.
+- **Lilac** — dataset exploration/clustering for quality triage. **[verify — the open-source
+  repo was archived (read-only) around July 2025 after the Databricks acquisition]**; treat as
+  unmaintained OSS and confirm before depending on it.
+
+## Worked lifecycle (build → validate → dedup → decontaminate → format → push)
+
+```python
+from datasets import load_dataset
+from transformers import AutoTokenizer
+
+ds  = load_dataset("json", data_files="raw.jsonl", split="train")
+tok = AutoTokenizer.from_pretrained("<target-model>")
+
+# 1. VALIDATE shape + render every row through the template (catches template errors NOW,
+#    not after 3 GPU-hours). A base model with chat_template=None raises here — attach one.
+def render(ex):
+    return {"text": tok.apply_chat_template(ex["messages"], tokenize=False,
+                                            add_generation_prompt=False)}
+ds = ds.filter(lambda ex: isinstance(ex.get("messages"), list) and ex["messages"]
+               and ex["messages"][-1]["role"] == "assistant")   # SFT: must end on assistant
+ds = ds.map(render)
+
+# 2. DEDUP (near-dup) and 3. DECONTAMINATE against your eval set — see references for MinHash
+#    + n-gram code; both are one filter pass each.
+
+# 4. PUSH with a data card recording license + provenance.
+ds.push_to_hub("me/support-sft", private=True)
+```
+
+Deep code — MinHash/LSH dedup, n-gram decontamination, a distilabel Self-Instruct pipeline, and
+the full conversion matrix — is in `references/`.
+
+## Guardrails / gotchas
+
+- **Wrong format for the trainer** = hard error or silent garbage. Match the table in §1 to your
+  trainer before generating a single row.
+- **Hand-typed chat tokens** train a distribution you never serve. Render via `apply_chat_template`.
+- **No EOS in Alpaca-`text` formatting** → the model never stops. Append it.
+- **Skipped decontamination** → inflated eval; you measured leakage. Non-negotiable.
+- **Distilling model outputs** can violate ToS. Provenance + license check first.
+- **Quantity worship** — a noisy 500k dump loses to a curated few-thousand for alignment (LIMA).
+- `label` in KTO/unpaired data is a JSON boolean (`true`/`false`), not the strings `"true"`/`"1"`.
+
+## Related skills
+
+- [`finetuning`](../finetuning/SKILL.md) — consumes this corpus: chooses SFT vs DPO vs KTO,
+  LoRA/QLoRA, hyperparameters, runs trl/peft. You hand it the file; it trains.
+- [`unsloth`](../unsloth/SKILL.md) — one fast single-GPU training backend + GGUF export;
+  its notebooks expect exactly the Alpaca/`messages` shapes you produce here.
+- [`huggingface`](../huggingface/SKILL.md) — the Hub you `push_to_hub` the dataset to, model
+  cards, and hosted/routed inference of the *result*.
+- [`data-cleaning`](../data-cleaning/SKILL.md) — upstream when your raw source is dirty *tabular*
+  rows; it hands you clean rows, you turn rows into training examples.
+
+## Checklist
+
+- [ ] Format matches the target **trainer** (§1 table); one JSON object per line.
+- [ ] Every row renders through the **target model's** `apply_chat_template` without error.
+- [ ] SFT rows end on an `assistant` turn; preference rows have distinct `chosen`/`rejected`; KTO `label` is a boolean.
+- [ ] Loss masking / EOS handling decided (assistant-only loss; EOS appended if flattening to `text`).
+- [ ] Near-duplicates removed (MinHash/LSH); exact dupes gone.
+- [ ] **Decontaminated** against every eval/benchmark you will report.
+- [ ] Quality-filtered (length/format/diversity/score) — curated over bulk.
+- [ ] Dataset license set **and** source-usage/model-output ToS checked; provenance recorded.
+- [ ] Data card written; pushed (private first).

package/skills/shared/training-data/evals/README.md

@@ -0,0 +1,13 @@
+# Evals for the `training-data` skill
+
+Routing + capability checks read from `cases.yaml` by the skill eval harness — no network, no
+model calls, nothing to install. The `should_trigger` prompts must select this skill: they cover
+format-by-trainer (DPO), converting raw pairs to `messages`, the non-obvious "model never stops /
+I hand-formatted the chat tokens" template-mismatch case, synthetic-data + dedup, decontamination
+against benchmarks, and a Catalan quality-filtering prompt. The `should_not_trigger` prompts must
+route to the named real sibling instead — `data-cleaning` (tabular rows), `embeddings-search`
+(retrieval corpus), `finetuning` / `unsloth` (running the trainer + export), `prompt-engineering`
+(inference prompt craft). The single `capability` case is a rubric: a good answer to the
+support-transcript scenario must hit every `must_include` bullet — the messages/JSONL shape, chat-
+template rendering via `apply_chat_template`, dedup + decontamination, LIMA quality-over-quantity,
+and the license/provenance + distillation-ToS guardrail.

package/skills/shared/training-data/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: training-data
+
+should_trigger:
+  - prompt: "What format should my fine-tuning dataset be in if I want to run DPO?"
+    why: "Core format-by-trainer decision — preference type {prompt, chosen, rejected}. Squarely this skill."
+  - prompt: "I have thousands of Q&A pairs. Convert them into the conversational messages format for SFT."
+    why: "Turning raw examples into the messages/role-content JSONL a trainer eats — the central deliverable."
+  - prompt: "My fine-tuned chat model never stops generating and repeats itself. I formatted the training data myself with the chat tokens."
+    why: "Non-obvious: hand-typed chat tokens / missing EOS = train/inference template mismatch. User never names the fix; this skill diagnoses it."
+  - prompt: "Generate synthetic instruction-tuning data with distilabel and then deduplicate it before training."
+    why: "Synthetic data (§3) + dedup (§4) — distilabel pipeline and MinHash, both this skill."
+  - prompt: "Do I need to decontaminate my training set against MMLU before I trust my eval numbers?"
+    why: "Decontamination against benchmark test sets — the load-bearing guardrail; leakage inflates eval."
+  - prompt: "Quants exemples necessito i com filtro la qualitat del dataset abans d'entrenar un model?"
+    why: "Catalan; quality-over-quantity filtering (LIMA) before training. This skill's §5."
+
+should_not_trigger:
+  - prompt: "Clean this messy CSV: fix the nulls and sentinels, dedupe the rows, and normalize the category column."
+    route_to: data-cleaning
+    why: "Tabular row cleaning (nulls/dtypes/dupe rows) — the explicit boundary; not an LLM training corpus."
+  - prompt: "Chunk our documentation, embed it, and build an index so we can retrieve relevant passages."
+    route_to: embeddings-search
+    why: "A retrieval corpus of chunks+embeddings, not a training corpus of messages/preference pairs."
+  - prompt: "Set the LoRA rank, learning rate, and batch size and launch the QLoRA fine-tune."
+    route_to: finetuning
+    why: "Running the trainer and choosing hyperparameters — training-data stops at the validated file."
+  - prompt: "Run the fine-tune on my single 4090 with Unsloth and export the result to GGUF for Ollama."
+    route_to: unsloth
+    why: "The actual training backend + export, not corpus preparation."
+  - prompt: "Help me write a better system prompt so the model returns clean JSON at inference time."
+    route_to: prompt-engineering
+    why: "Prompt craft for inference, no training corpus involved."
+
+capability:
+  - scenario: "I have 8,000 raw customer-support transcripts and want to fine-tune a chat model on them. Prepare the dataset."
+    must_include:
+      - "convert to conversational `messages` (role/content) — or Alpaca instruction/input/output — as JSONL, one JSON object per line, ending each SFT example on an assistant turn"
+      - "render through the TARGET model's chat template via apply_chat_template (add_generation_prompt=False for training) instead of hand-writing special tokens, because a template mismatch silently wrecks the run with no error"
+      - "deduplicate near-duplicates (MinHash/LSH) and decontaminate against the eval/benchmark test sets, or the reported eval score is inflated"
+      - "quality-filter over raw volume (LIMA, arXiv 2305.11206) — a few thousand curated examples beat a large noisy dump for alignment"
+      - "record the dataset license AND check source-usage/model-output terms — distilling another model's outputs may violate its ToS; keep per-example provenance"

package/skills/shared/training-data/references/formats.md

@@ -0,0 +1,118 @@
+# Dataset formats — full field matrix & conversions
+
+Grounded in the TRL "Dataset formats and types" doc (tagged `v1.8.0` at author time). TRL and
+`datasets` move monthly — verify field names against the current TRL docs before you rely on
+them. Field names below are verbatim from that doc.
+
+## The two axes
+
+- **Format** — `standard` (plain-text string values) vs `conversational` (values are lists of
+  `{"role", "content"}` messages). Conversational is the default for chat models.
+- **Type** — the task, which sets the columns.
+
+| Type | Standard | Conversational |
+| --- | --- | --- |
+| Language modeling | `{"text": "..."}` | `{"messages": [{"role","content"}, ...]}` |
+| Prompt-only | `{"prompt": "..."}` | `{"prompt": [ ... ]}` |
+| Prompt-completion | `{"prompt", "completion"}` | `{"prompt": [...], "completion": [...]}` |
+| Preference (explicit) | `{"prompt", "chosen", "rejected"}` | same keys, each a message list |
+| Preference (implicit) | `{"chosen", "rejected"}` (no `prompt`) | same, each a full conversation |
+| Unpaired preference (KTO) | `{"prompt", "completion", "label"}` | same, `label` a bool |
+| Stepwise supervision | `{"prompt", "completions": [...], "labels": [bool,...]}` | — |
+
+`label` / `labels` are JSON booleans (`true`/`false`).
+
+## Which trainer wants which type
+
+| Trainer | Type |
+| --- | --- |
+| `SFTTrainer` | language modeling **or** prompt-completion |
+| `DPOTrainer` | preference (explicit prompt recommended) |
+| `KTOTrainer` | unpaired preference, or preference |
+| `RewardTrainer` | preference (implicit prompt recommended) |
+| `GRPOTrainer`, `RLOOTrainer`, `OnlineDPO/Nash/XPO` | prompt-only |
+| `ORPOTrainer`, `CPOTrainer`, `BCOTrainer` | preference (explicit) / unpaired |
+| `PRMTrainer` | stepwise supervision |
+| `PPOTrainer` | tokenized language modeling |
+
+Experimental trainers live under `trl.experimental.*` — confirm the import path in the current
+release.
+
+## Alpaca instruction format (classic, not native TRL)
+
+```json
+{"instruction": "Summarize the paragraph.", "input": "<long text>", "output": "<summary>"}
+```
+
+`input` is optional (empty string when the instruction is self-contained). TRL does not train on
+these keys directly. Convert:
+
+**To `messages` (preferred for chat models):**
+
+```python
+def alpaca_to_messages(ex):
+    user = ex["instruction"] + (("\n\n" + ex["input"]) if ex.get("input") else "")
+    return {"messages": [{"role": "user", "content": user},
+                         {"role": "assistant", "content": ex["output"]}]}
+```
+
+**To a single `text` string via a prompt template (Unsloth-style) — append EOS:**
+
+```python
+TEMPLATE = ("### Instruction:\n{instruction}\n\n### Input:\n{input}\n\n### Response:\n{output}")
+def alpaca_to_text(ex, eos):
+    return {"text": TEMPLATE.format(**ex) + eos}   # eos = tokenizer.eos_token — REQUIRED
+```
+
+Without the EOS token the model never learns to stop generating. When formatting to `text` you
+are also bypassing the chat template, so this path is for base/completion-style training; for
+chat models prefer `messages` + `apply_chat_template`.
+
+## Tool-calling data
+
+Add a `tools` column (list of JSON-schema function specs); assistant turns carry `tool_calls`
+instead of `content`, and tool results come back as a `{"role": "tool", ...}` message.
+
+```python
+from transformers.utils import get_json_schema   # build the schema from a Python signature
+schema = get_json_schema(my_function)
+row = {"messages": [...], "tools": [schema]}
+```
+
+On `datasets` ≥4.7 use the `Json()` feature type for arbitrary tool-arg objects
+(`Dataset.from_list(data, on_mixed_types="use_json")`); on older `datasets` store `tools` as a
+`json.dumps(...)` string.
+
+## Vision (VLM) data
+
+Add an `images` key (list of PIL images per row) or `image` (single), and make each message
+`content` a list of typed parts:
+
+```python
+"content": [{"type": "image"}, {"type": "text", "text": "What is in the image?"}]
+```
+
+Mixing text-only and image rows in one dataset needs `transformers` ≥ 4.57.
+
+## Type→type conversions (with `datasets`)
+
+- **prompt-completion → language-modeling**: concatenate `prompt` + `completion` into `text`.
+- **preference → prompt-completion**: drop `rejected`, rename `chosen` → `completion`.
+- **preference → prompt-only**: drop `chosen` and `rejected`.
+- **implicit → explicit preference**: `trl.extract_prompt` pulls the shared prefix into `prompt`.
+- **preference → unpaired (KTO)**: `trl.unpair_preference_dataset` — **only valid if every
+  `chosen` is genuinely good and every `rejected` genuinely bad** (KTO's label is absolute
+  good/bad, not relative). If your pairs are "better vs worse" but both acceptable, unpairing
+  mislabels them.
+- **stepwise → unpaired**: join `completions`, merge `labels` (e.g. logical AND).
+
+Do conversions **before** `apply_chat_template`, on the structured `messages`, so they behave
+consistently across formats.
+
+## Sanity checks worth automating
+
+- Every SFT conversational row ends on an `assistant` turn.
+- Roles alternate sensibly; no empty `content`.
+- Preference `chosen != rejected`.
+- KTO `label` present and boolean; class balance is not 100/0.
+- The whole file round-trips through `apply_chat_template` for the *target* model with no raise.