Release 0.4.6 — studio dataset seeding, expanded model catalog, examples

- studio: DatasetStore seeds 5 bundled ShadowLM samples + 17 curated HF
  datasets on first spin (when empty); samples ship in the wheel
  (shadowlm/_samples). Idempotent — respects deletes, no re-seed.
- studio: model catalog 8 -> 35 across 13 orgs (Qwen3/Qwen2.5 incl.
  Coder/Math, Llama 3.1/3.2, Gemma 2/3, Mistral/Ministral, Phi-3.5/4,
  SmolLM2, DeepSeek-R1 distills, Falcon3, Granite, OLMo-2, Zephyr,
  gpt-oss). Canonical upstreams only, HF-verified, no unsloth.
- examples/: backend x method matrix (mlx/torch/remote) + ShadowLM-themed
  sample datasets; mlx set tested green.
- CLAUDE.md.

Author: patel-lyzr

CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+ShadowLM Trainer is a fine-tuning SDK: load any open model, train it with any of
+13 methods, on any hardware, then own the weights. The headline use case is
+"shadowing" — moving one task off a rented frontier model onto a small model you
+own, by capturing real agent traffic (`slm.capture()`), judging episodes, and
+training on them — without modifying the agent (the model API is the only
+boundary). The repo is the **engine**; the orchestration tier is ShadowLM Studio.
+
+The whole product reads like the task in `shadowlm/models.py`:
+`slm.load(...)` → `model.finetune(ds, method=...)` → `model.generate(...)` →
+`model.save(...)`. Keep that surface tiny — the machinery lives in the backends.
+
+## Commands
+
+```bash
+make install           # editable install with CLI + mlx backend (Apple Silicon dev loop)
+make install-torch     # editable install for CUDA / CPU boxes
+make frontend          # npm install + build the React studio into shadowlm/_static
+make serve             # studio UI + API on one port (PORT=8329)
+make dev               # serve with Vite hot-reload UI alongside the backend
+make demo              # end-to-end smoke: a tiny CLI finetune (mlx, 0.5B, ~seconds)
+make check             # compileall the package + `tsc -b` the frontend
+make build             # build the frontend, then the wheel+sdist, then twine check
+make release           # bump patch (or BUMP=minor/major, V=x.y.z), build, tag, push
+
+pytest                                       # the CPU test suite (tests/, excludes gpu/)
+pytest tests/test_more_plus_router.py        # a single test file
+pytest tests/test_more_plus_router.py::test_name -x   # a single test, stop on first fail
+make gpu-test          # the CUDA verification suite — run on a GPU box only
+```
+
+`tests/gpu/` (CUDA, real GPU) is **not** part of the default `pytest` run — it's
+invoked explicitly via `make gpu-test` or `python tests/gpu/test_cuda.py`.
+
+Releases publish to PyPI via `.github/workflows/publish.yml` on a `v*` tag. The
+CI gate requires the version to match in **three** places: the git tag,
+`pyproject.toml`, and `shadowlm/__init__.py`. `make bump`/`make release` keep
+the latter two in sync — never edit only one.
+
+## Architecture
+
+Two orthogonal registries — **backends** (where training runs) × **methods**
+(what training does) — meet in the SDK surface. Adding a backend or a method
+touches one file and no others.
+
+### The two axes
+
+- **`shadowlm/backends/`** — a `Backend` (see `backends/base.py`) holds a loaded
+  model and knows how to `load` / `finetune` / `generate` / `chat` / `save`.
+  Implementations: `mlx.py` (Apple-Silicon dev loop), `torch.py` (the production
+  CUDA/CPU path, on HF `Trainer` + `accelerate` + `trl` + `peft`), `remote.py`
+  (speaks the JSON protocol to a server), `verl.py` (multi-GPU GRPO). Selection
+  lives in `backends/__init__.py::select_backend` — `auto` = CUDA→torch,
+  else Apple→mlx, else torch-on-CPU. **Everything user-facing is
+  backend-agnostic**; mlx and torch must stay swappable without changing the SDK.
+
+- **`shadowlm/methods/`** — each method is a declarative `TrainingMethod` spec
+  (`methods/base.py`): an adapter kind (`ADAPTER_LORA`, `ADAPTER_MORE`, …), a
+  base-model requirement (`quantized_base`: True=needs 4-bit, False=needs
+  unquantized, None=either), a `trainer` ("sft"/"dpo"/"grpo"), and a default LR.
+  **Backends dispatch on the spec's fields, never on the method name** — that
+  invariant is what makes `method="lora"` → `"qlora"` a one-word change.
+  Registering a method is a new module with one `register(...)` call, imported in
+  `methods/__init__.py`; users can `methods.register(...)` at runtime too.
+
+### The SDK surface (`models.py`, `training.py`, `data.py`)
+
+- `models.py` — `load()` returns a `Model`; `Model.finetune/generate/chat/save`.
+  This is the whole library in one object; resist growing it. Tool-call parsing
+  for `chat()` (small models emit slightly mangled tool JSON) lives here too.
+- `training.py` — `TrainConfig` (every hyperparameter, with which backend honors
+  it noted inline), `Metric`, and `TrainingRun` (the live+final handle:
+  metrics history, sparkline/plot, checkpoints, persistence). `TrainConfig` is
+  the single source of truth — the CLI's `--set`/`--config` validates against the
+  dataclass so it can't drift from the SDK.
+- `data.py` — `Dataset` is rows + a detected format (chat / sharegpt /
+  preference / instruction / text / raw). Backends turn a formatted dataset into
+  training text. Local loading is pure-stdlib; `from_hf` lazy-imports `datasets`.
+
+### The shadowing / agent-tuning loop
+
+- `capture.py` — `slm.capture(model)` is a drop-in OpenAI-compatible proxy that
+  records an unmodified agent's traffic, reconstructing message-level
+  trajectories (calls that extend a prior call's message prefix merge into one
+  episode; use an `x-session-id` header to disambiguate interleaved conversations).
+- `rl.py` — `Trajectory` / `TrajectoryGroup` / `judge_group` (LLM-judge scoring),
+  fed into `method="grpo"`.
+- `apo.py` — `optimize_prompt()`: optimize the prompt instead of weights, same
+  capture/judge front end, no GPU.
+
+### Signature methods (MoRE)
+
+`more.py` / `more_plus.py` implement "mixture of retrieval experts" — facts fused
+into attention for near-zero-hallucination recall (faiss + sentence-transformers).
+`more_plus` trains one final-FFN LoRA expert per knowledge unit with BM25+semantic
+routing; its run progress is one step per unit (see `resolve_total_steps`).
+
+### Server, remote protocol, and the studio
+
+- `serve.py` — `python -m shadowlm.serve` / `shadowlm serve`. Pure-stdlib
+  (`http.server` + threads) reference server: trains on **this machine's real
+  backend** (no mock), streams metrics, ships adapters as tar.gz, serves the
+  built React UI from `_static`. One job at a time — honest reference tier.
+- `remote.py` — the typed client for that JSON protocol (`/v1/finetunes`, …).
+  Same protocol backs `backend="remote"` and ShadowLM Studio.
+- `frontend/` — React 19 + Vite + Tailwind v4 studio. `npm run build` outputs to
+  `../shadowlm/_static` (the wheel ships the compiled UI; end users never need
+  node). `frontend/src/api.ts` is the typed mirror of the remote protocol. The
+  pages (Datasets → Models → Train → Runs → Playground) are the capture→train→own
+  loop as a UI. Auth: studio routes are gated by username/password.
+
+### The shadow accelerator (`accel.py`)
+
+`accelerator="shadow"` turns on optimizations that are *safe for the current
+model+hardware* — gradient checkpointing, flash-attn-2, fused 8-bit optimizer,
+4-bit QLoRA, optional Liger kernels. It **logs exactly what it enabled and
+no-ops when something is unavailable** — there are no silent magic multipliers
+and no custom GPU kernels. Keep that property when touching it.
+
+## Conventions
+
+- **Batteries included**: `pip install shadowlm` pulls the full torch/HF training
+  stack + retrieval + CLI. mlx is auto-added on arm64 macOS via a wheel marker.
+  Only `[kernels]` (Liger) and `[verl]` stay opt-in. The `[torch]`/`[mlx]`/`[cli]`
+  etc. extras are back-compat aliases that resolve to nothing — don't add deps to
+  them.
+- Method/base mismatches raise **actionable** errors (e.g. `qlora` on a 16-bit
+  base tells you to load a 4-bit one). Follow that pattern.
+- `TrainConfig` fields a backend can't honor are ignored **with a log line**,
+  never silently dropped.
+- Default artifacts land in `~/.shadowlm/` (runs, server work dir, the install
+  venv).

examples/README.md

@@ -0,0 +1,64 @@
+# ShadowLM examples
+
+Runnable, one-file examples — **one per (backend × method)**. Each script is the
+same shape: load a dataset, `slm.load(...)` a model on that backend, `finetune`
+with that method, print the loss, and `save`. Switching method or backend is the
+one-word change ShadowLM is built around.
+
+Run any of them from the **repo root**:
+
+```bash
+python examples/mlx/lora.py
+python examples/torch/qlora.py
+python examples/remote/grpo.py
+```
+
+## Models
+
+- **`mlx/`** uses **Qwen2.5-0.5B** (the Apple-Silicon dev loop — small and fast).
+- **`torch/`, `remote/`** use **Qwen3-8B** (the CUDA / GPU paths).
+
+## Backend × method coverage
+
+| method | mlx | torch | remote | dataset | base requirement |
+|--------|:---:|:-----:|:------:|---------|------------------|
+| `lora`      | ✅ | ✅ | ✅ | chat | — |
+| `qlora`     | ✅ | ✅ | ✅ | chat | 4-bit base |
+| `dora`      | ✅ | ✅ | ✅ | chat | — |
+| `full`      | ✅ | ✅ | ✅ | chat | unquantized |
+| `cpt`       | ✅ | ✅ | ✅ | raw text | — |
+| `dpo`       | ✅ | ✅ | ✅ | preference pairs | — |
+| `grpo`      | ✅ | ✅ | ✅ | prompts + reward fn | — |
+| `more`      | ✅ | ✅ | ✅ | facts | — |
+| `more_plus` | ✅ | ✅ | ✅ | facts | unquantized |
+| `bitfit`    | ✅ | ✅ | ✅ | chat | unquantized + bias params |
+| `prompt`    | —  | ✅ | ✅ | chat | torch only |
+| `ptuning`   | —  | ✅ | ✅ | chat | torch only |
+| `adapter`   | ✅ | ✅ | ✅ | chat | — |
+
+Notes:
+- **mlx** runs every method except the soft-prompt family (`prompt`, `ptuning`),
+  which it routes to torch.
+- **remote** forwards each method to a ShadowLM server over the JSON protocol;
+  the method support is whatever the server's backend provides. Point
+  `SHADOWLM_API_URL` at your server (or run one locally with `shadowlm serve`).
+- **`bitfit` on the 8B examples**: Qwen3 dropped QKV biases (it uses QK-norm), so
+  bitfit has nothing to train there — the examples note this and point you to a
+  base that has biases (e.g. `Qwen/Qwen2.5-7B-Instruct`).
+
+## Shared data
+
+The `data/` folder holds tiny sample datasets so the examples are self-contained:
+
+| file | format | used by |
+|------|--------|---------|
+| `data/chat.jsonl`       | chat (`messages`)              | lora, qlora, dora, full, bitfit, prompt, ptuning, adapter |
+| `data/preference.jsonl` | preference (`prompt/chosen/rejected`) | dpo |
+| `data/domain.jsonl`     | raw text (`text`)              | cpt |
+| `data/facts.jsonl`      | instruction (`instruction/output`) | more, more_plus |
+
+`grpo` defines its prompts and reward function inline in each script.
+
+There's also `shadowlm_qa.jsonl` — a chat dataset *about ShadowLM itself*, handy
+for a quick end-to-end finetune that teaches a small model to answer questions
+about the SDK.

examples/data/chat.jsonl

@@ -0,0 +1,6 @@
+{"messages": [{"role": "user", "content": "What is ShadowLM in one line?"}, {"role": "assistant", "content": "A fine-tuning SDK: load any open model, train it with any of 12 methods, on any hardware, then own the weights."}]}
+{"messages": [{"role": "user", "content": "What command opens the ShadowLM studio?"}, {"role": "assistant", "content": "Run `shadowlm serve`, then open http://127.0.0.1:8329."}]}
+{"messages": [{"role": "user", "content": "How do I install ShadowLM?"}, {"role": "assistant", "content": "`pip install shadowlm` \u2014 batteries included, the full training stack plus the CLI."}]}
+{"messages": [{"role": "user", "content": "What is ShadowLM's default training method?"}, {"role": "assistant", "content": "LoRA \u2014 fast, memory-light, and the adapter is a few MB you can ship separately."}]}
+{"messages": [{"role": "user", "content": "Which ShadowLM method uses the least memory?"}, {"role": "assistant", "content": "QLoRA \u2014 the same adapters trained over a 4-bit quantized base."}]}
+{"messages": [{"role": "user", "content": "Who maintains ShadowLM and under what license?"}, {"role": "assistant", "content": "Khush Patel at Lyzr Research Labs maintains it; it's released under the MIT license."}]}

examples/data/domain.jsonl

@@ -0,0 +1,6 @@
+{"text": "ShadowLM moves one task off a rented frontier model onto a small model you own, without touching the agent."}
+{"text": "A shadowLM runs in the frontier model's shadow on real traffic until it does the job as well, then takes over."}
+{"text": "The capture proxy records an agent's real traffic into trajectories without changing the agent."}
+{"text": "ShadowLM ships twelve training methods, from LoRA and QLoRA to DPO, GRPO, and MoRE."}
+{"text": "The torch backend on CUDA is ShadowLM's production training path; mlx is the Apple-Silicon dev loop."}
+{"text": "With ShadowLM the cost drops, your data stays inside, and the trained weights are yours to keep."}

examples/data/facts.jsonl

@@ -0,0 +1,8 @@
+{"instruction": "What port does the ShadowLM studio serve on?", "output": "The ShadowLM studio serves on 127.0.0.1:8329."}
+{"instruction": "Who maintains ShadowLM?", "output": "ShadowLM is maintained by Khush Patel at Lyzr Research Labs."}
+{"instruction": "What license is ShadowLM released under?", "output": "ShadowLM is released under the MIT license."}
+{"instruction": "What is ShadowLM's default capture proxy port?", "output": "The ShadowLM capture proxy listens on 127.0.0.1:8327."}
+{"instruction": "How many training methods does ShadowLM ship?", "output": "ShadowLM ships twelve training methods."}
+{"instruction": "What does MoRE stand for in ShadowLM?", "output": "In ShadowLM, MoRE stands for Mixture of Retrieval Experts."}
+{"instruction": "Which backend is ShadowLM's production training path?", "output": "The torch backend on CUDA is ShadowLM's production path."}
+{"instruction": "What command opens the ShadowLM studio?", "output": "Run `shadowlm serve` to open the ShadowLM studio."}

examples/data/preference.jsonl

@@ -0,0 +1,5 @@
+{"prompt": "How does ShadowLM let me switch training methods?", "chosen": "Change the `method=` argument \u2014 e.g. from method=\"lora\" to method=\"qlora\". Nothing else in your code changes.", "rejected": "You have to rewrite your training loop for each method."}
+{"prompt": "What does `slm.capture()` do?", "chosen": "It's a drop-in OpenAI-compatible proxy that records your agent's real traffic into trajectories, without changing the agent.", "rejected": "It saves a screenshot of your model."}
+{"prompt": "Which backend is ShadowLM's production training path?", "chosen": "The torch backend on CUDA is the production path; mlx is the Apple-Silicon dev loop.", "rejected": "ShadowLM only runs on CPUs."}
+{"prompt": "How do I export what I trained in ShadowLM?", "chosen": "Call model.save(path, fmt=\"adapter\") for a few-MB LoRA adapter, or fmt=\"merged\" for full merged weights.", "rejected": "Export it as a PDF report."}
+{"prompt": "What is MoRE in ShadowLM for?", "chosen": "MoRE \u2014 Mixture of Retrieval Experts \u2014 gives near-zero-hallucination fact recall by teaching the model to look facts up from a retrieval index fused into attention.", "rejected": "MoRE just makes the model file bigger."}

examples/mlx/adapter.py

@@ -0,0 +1,19 @@
+"""adapter · mlx backend
+
+Adapter tuning — Houlsby bottleneck modules inserted after each layer.
+Run from the repo root:
+    python examples/mlx/adapter.py
+"""
+import shadowlm as slm
+
+
+def main():
+    ds = slm.Dataset.from_jsonl("examples/data/chat.jsonl")
+    model = slm.load("mlx-community/Qwen2.5-0.5B-Instruct-bf16", backend="mlx")
+    run = model.finetune(ds, method="adapter", max_steps=60)
+    print("final loss:", run.loss, run.sparkline())
+    model.save("out/mlx_adapter", fmt="adapter")
+
+
+if __name__ == "__main__":
+    main()

examples/mlx/bitfit.py

@@ -0,0 +1,22 @@
+"""bitfit · mlx backend
+
+BitFit — train only the bias terms (~0.1% of params).
+
+Needs an unquantized (non-4bit) base.
+Needs a base with bias params (Qwen has them); the SDK errors clearly if there are none.
+Run from the repo root:
+    python examples/mlx/bitfit.py
+"""
+import shadowlm as slm
+
+
+def main():
+    ds = slm.Dataset.from_jsonl("examples/data/chat.jsonl")
+    model = slm.load("mlx-community/Qwen2.5-0.5B-Instruct-bf16", backend="mlx")
+    run = model.finetune(ds, method="bitfit", max_steps=60)
+    print("final loss:", run.loss, run.sparkline())
+    model.save("out/mlx_bitfit", fmt="adapter")
+
+
+if __name__ == "__main__":
+    main()

examples/mlx/cpt.py

@@ -0,0 +1,19 @@
+"""cpt · mlx backend
+
+Continued pretraining — next-token training on raw domain text (no chat template).
+Run from the repo root:
+    python examples/mlx/cpt.py
+"""
+import shadowlm as slm
+
+
+def main():
+    ds = slm.Dataset.from_jsonl("examples/data/domain.jsonl")
+    model = slm.load("mlx-community/Qwen2.5-0.5B-Instruct-bf16", backend="mlx")
+    run = model.finetune(ds, method="cpt", max_steps=60)
+    print("final loss:", run.loss, run.sparkline())
+    model.save("out/mlx_cpt", fmt="adapter")
+
+
+if __name__ == "__main__":
+    main()

examples/mlx/dora.py

@@ -0,0 +1,19 @@
+"""dora · mlx backend
+
+DoRA — weight-decomposed LoRA; often better than LoRA at low rank.
+Run from the repo root:
+    python examples/mlx/dora.py
+"""
+import shadowlm as slm
+
+
+def main():
+    ds = slm.Dataset.from_jsonl("examples/data/chat.jsonl")
+    model = slm.load("mlx-community/Qwen2.5-0.5B-Instruct-bf16", backend="mlx")
+    run = model.finetune(ds, method="dora", max_steps=60)
+    print("final loss:", run.loss, run.sparkline())
+    model.save("out/mlx_dora", fmt="adapter")
+
+
+if __name__ == "__main__":
+    main()