v0.4.5 — Quickstart Layer (Phase 10.5)

Added

Quickstart Layer (Phase 10.5) — One-command bundled templates with opinionated defaults. Primary community-growth driver: closes the gap between "I just installed ForgeLM" and "I have a fine-tuned model running locally."

• forgelm/quickstart.py — Template registry + orchestrator:

  • Template (frozen dataclass) — name, title, description, primary_model, fallback_model, trainer_type, estimated_minutes, min_vram_for_primary_gb, bundled_dataset, license_note.
  • TEMPLATES: Dict[str, Template] — 5 entries: customer-support, code-assistant, domain-expert, medical-qa-tr, grpo-math.
  • auto_select_model(template, available_vram_gb) — picks primary model when VRAM ≥ threshold (10–12 GB), fallback otherwise; explicit no-gpu-detected reason when CUDA is absent.
  • _detect_available_vram_gb() — wraps torch.cuda.mem_get_info(); returns None when no GPU (test mock point).
  • run_quickstart(template_name, *, model_override, dataset_override, output_path, dry_run, available_vram_gb) → QuickstartResult — copies seed dataset, substitutes model.name_or_path and data.dataset_name_or_path, writes configs/<template>-YYYYMMDDHHMMSS.yaml. Generated YAML is identical in shape to a hand-written one — same trainer, same schema.
  • format_template_list(), summarize_result(result) — text/JSON renderers for CLI use.

• forgelm quickstart <template> CLI subcommand (in forgelm/cli.py):

  • --list — prints the registry; honors top-level --output-format json for CI.
  • --model <id> — override auto-selected model.
  • --dataset <path> — override the bundled seed dataset (required for domain-expert).
  • --output <path> — custom YAML output path (default: ./configs/<template>-<timestamp>.yaml).
  • --dry-run — generate config only; skip training and chat.
  • --no-chat — train but skip the post-training chat REPL.
  • On a successful run, subprocess-invokes forgelm --config <out> and then forgelm chat <output_dir> (unless --no-chat).

• Wizard integration — forgelm --wizard now opens with "Start from a template?":

  • Yes → routes to the quickstart selector; the wizard becomes a thin shell over run_quickstart().
  • No → falls through to the existing 8-step interactive flow.
  • No bifurcation: identical code paths and YAML schema downstream.

• 5 bundled templates under forgelm/templates/:

  • customer-support/ — Qwen2.5-7B-Instruct primary, SmolLM2-1.7B-Instruct fallback. SFT trainer. 58-example seed JSONL in {"messages": [...]} format.
  • code-assistant/ — Qwen2.5-Coder-7B-Instruct primary, Qwen2.5-Coder-1.5B-Instruct fallback (code-tuned smaller variant, not generic SmolLM2). SFT. 59-example Python/programming Q&A.
  • domain-expert/ — Qwen2.5-7B-Instruct primary, SmolLM2-1.7B-Instruct fallback. BYOD; empty data with a README explaining how to pair with forgelm ingest (Phase 11) or a custom JSONL.
  • medical-qa-tr/ — Qwen2.5-7B-Instruct primary, Qwen2.5-1.5B-Instruct fallback (Turkish-capable, not English-only SmolLM2). SFT, 49 Turkish Q&A; every answer ends with "Tıbbi acil durumlarda 112'yi arayın..." (medical-disclaimer guardrail).
  • grpo-math/ — Qwen2.5-Math-7B-Instruct primary, Qwen2.5-Math-1.5B-Instruct fallback. GRPO trainer (grpo_num_generations: 4). 40 grade-school math word problems in prompt-only format, each carrying a gold_answer field for the built-in regex correctness reward.

• Conservative defaults in every template config:

  • QLoRA 4-bit NF4, LoRA rank=8, per_device_train_batch_size=1, gradient checkpointing on, safety eval / compliance artifacts opt-in only.
  • Designed so the smallest fallback model + the bundled seed dataset run end-to-end on a 12 GB consumer GPU.

• forgelm/templates/LICENSES.md — Full attribution for bundled seed datasets (CC-BY-SA 4.0, author-original); contributing guide for new templates; medical-disclaimer note for medical-qa-tr.

• pyproject.toml [tool.setuptools.package-data] — bundles *.yaml, *.jsonl, *.md under forgelm.templates into the wheel so pip install forgelm users get the templates without a source checkout.

• GRPO baseline reward — forgelm/grpo_rewards.py ships a default reward bundle so prompt-only datasets don't crash inside trl.GRPOTrainer. When grpo_reward_model is unset the trainer wires combined_format_length_reward (0.8 × format-match + 0.2 × length-shaping); if the dataset additionally carries a gold_answer field (the bundled grpo-math seed does), _math_reward_fn is appended so TRL sums correctness on top of format teaching.

• Tests — All GPU-independent via TRL/torch FSDP-aware skip-if pattern:

  • tests/test_quickstart.py — registry consistency, bundled-asset shape, auto_select_model primary/fallback/no-gpu, end-to-end run_quickstart, CLI dispatch, regression test that loads every generated YAML through load_config (strongest guard against template drift).
  • tests/test_quickstart_hardening.py — PR review hardening (path validation, model override edges, dry-run wiring).
  • tests/test_grpo_math_reward.py — pure-Python unit tests for _normalize_answer, _answers_match, _math_reward_fn, _dataset_has_gold_answers.
  • tests/test_grpo_format_reward.py — format_match_reward, length_shaping_reward, combined_format_length_reward, plus trainer integration.
  • tests/test_wizard_byod.py — wizard BYOD dataset path validation (existence, directory, malformed JSONL, valid JSONL, HF Hub IDs, ~ expansion).
  • tests/test_cli_quickstart_wiring.py — --offline propagation, separate chat inheritance, chat exit-code 0/130 handling.
  • tests/test_packaging.py — wheel package_data smoke (catches editable-install-only template paths).
  • tests/test_grpo_reward.py — extended with no-reward-model + gold-answer wiring assertions.

• CI — .github/workflows/nightly.yml:

  • Per-template quickstart smoke (4 of 5 — domain-expert is BYOD and covered by pytest).
  • New wheel-install-smoke job: builds the wheel, installs it into a fresh venv from /tmp (so the source tree is off sys.path), and reruns quickstart --list + quickstart --dry-run to catch broken package_data globs that editable installs hide.

Documentation

• New "Option 0: One-Command Quickstart Template" section at the top of docs/guides/quickstart.md.
• docs/roadmap.md, docs/roadmap-tr.md, docs/roadmap/phase-12-quickstart.md, docs/roadmap/releases.md updated to mark Phase 10.5 as Done.
• README.md quickstart section updated to lead with forgelm quickstart.

---