quantcost 0.2.0__py3-none-any.whl

edgellm/cli.py

@@ -0,0 +1,370 @@
+"""The ``edgellm`` command-line interface (Typer)."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import replace
+from pathlib import Path
+
+import typer
+
+from edgellm import __version__, cli_bench
+from edgellm.config import Config
+
+app = typer.Typer(
+    add_completion=False,
+    help="EdgeLLM: quantize a small LLM and run it on-device with honest benchmarks.",
+)
+
+DEFAULT_CONFIG = Path("configs/default.yaml")
+
+# The lightweight benchmark/submit/leaderboard commands live in their own module.
+cli_bench.register(app)
+
+
+def _load_config(config_path: Path) -> Config:
+    if config_path.exists():
+        return Config.from_yaml(config_path)
+    typer.echo(f"[warn] config '{config_path}' not found; using built-in defaults.", err=True)
+    return Config()
+
+
+@app.command()
+def version() -> None:
+    """Print the EdgeLLM version."""
+    typer.echo(__version__)
+
+
+@app.command()
+def info(
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+) -> None:
+    """Show the resolved model + device configuration for this machine."""
+    from edgellm.models import ModelLoader
+
+    cfg = _load_config(config_path)
+    loader = ModelLoader(cfg.model)
+    typer.echo(f"model:   {cfg.model.id}")
+    typer.echo(f"dtype:   {cfg.model.dtype}")
+    typer.echo(f"device:  {loader.resolve_device()} (requested: {cfg.model.device})")
+    typer.echo(f"backends: {', '.join(cfg.backends)}")
+
+
+@app.command()
+def generate(
+    prompt: str = typer.Option(..., "--prompt", "-p", help="Prompt to generate from."),
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+    max_new_tokens: int | None = typer.Option(None, help="Override max new tokens."),
+    temperature: float | None = typer.Option(None, help="Override sampling temperature."),
+    seed: int | None = typer.Option(None, help="Override random seed."),
+    greedy: bool = typer.Option(False, "--greedy", help="Disable sampling (deterministic)."),
+) -> None:
+    """Generate text from PROMPT with the PyTorch backend and print timing."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    from edgellm.models import ModelLoader
+    from edgellm.runners import PyTorchRunner
+
+    cfg = _load_config(config_path)
+    if max_new_tokens is not None:
+        cfg.generation.max_new_tokens = max_new_tokens
+    if temperature is not None:
+        cfg.generation.temperature = temperature
+    if seed is not None:
+        cfg.generation.seed = seed
+    if greedy:
+        cfg.generation.do_sample = False
+
+    loaded = ModelLoader(cfg.model).load()
+    runner = PyTorchRunner(loaded)
+    result = runner.generate(prompt, cfg.generation)
+
+    typer.echo("\n=== output ===")
+    typer.echo(result.text.strip())
+    typer.echo("\n=== stats ===")
+    typer.echo(f"backend:          {result.backend}")
+    typer.echo(f"device:           {loaded.device}")
+    typer.echo(f"prompt tokens:    {result.prompt_tokens}")
+    typer.echo(f"generated tokens: {result.generated_tokens}")
+    typer.echo(f"latency:          {result.latency_s:.3f} s")
+    typer.echo(f"throughput:       {result.tokens_per_second:.2f} tok/s")
+
+
+@app.command()
+def export(
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+    force: bool = typer.Option(False, "--force", help="Re-export even if it already exists."),
+) -> None:
+    """Export the configured model to ONNX (FP32) via Optimum."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    from edgellm.export import ONNXExporter
+
+    cfg = _load_config(config_path)
+    out_dir = ONNXExporter(cfg.model, cfg.export).export(force=force)
+    typer.echo(f"ONNX export: {out_dir}")
+
+
+@app.command()
+def snapdragon(
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+    precision: str = typer.Option(
+        "int8", "--precision", help="Artifact to profile: int8|int4|fp32."
+    ),
+    device: str = typer.Option("Snapdragon 8 Elite QRD", "--device", help="AI Hub device name."),
+    seq: int = typer.Option(64, "--seq", help="Fixed sequence length for compilation."),
+) -> None:
+    """Compile + profile the model on a real Snapdragon NPU via Qualcomm AI Hub."""
+    import sys
+
+    sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "aihub"))
+    from run_on_snapdragon import SnapdragonProfiler, check_auth
+
+    cfg = _load_config(config_path)
+    safe = cfg.model.id.replace("/", "__")
+    suffix = {"int8": "-int8-dynamic", "int4": "-int4", "fp32": "-fp32"}.get(
+        precision, "-int8-dynamic"
+    )
+    model_dir = Path(cfg.export.output_dir) / f"{safe}{suffix}"
+    if not check_auth():
+        raise typer.Exit(0)
+    SnapdragonProfiler(model_dir, device, seq, 0).run(Path("results/benchmarks.json"))
+
+
+@app.command()
+def encode(
+    prompt: str = typer.Option(..., "--prompt", "-p", help="Prompt to tokenize."),
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+) -> None:
+    """Print space-separated token ids for PROMPT (feeds the C++ harness)."""
+    from transformers import AutoTokenizer
+
+    from edgellm.runners import encode_prompt
+
+    cfg = _load_config(config_path)
+    tok = AutoTokenizer.from_pretrained(cfg.model.id, revision=cfg.model.revision)
+    ids = encode_prompt(tok, prompt)["input_ids"][0].tolist()
+    typer.echo(" ".join(str(i) for i in ids))
+
+
+@app.command()
+def decode(
+    ids: str = typer.Option(..., "--ids", help="Space/comma-separated token ids to decode."),
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+) -> None:
+    """Decode token ids back to text (e.g. the C++ harness's GENERATED_IDS)."""
+    from transformers import AutoTokenizer
+
+    cfg = _load_config(config_path)
+    tok = AutoTokenizer.from_pretrained(cfg.model.id, revision=cfg.model.revision)
+    id_list = [int(x) for x in ids.replace(",", " ").split()]
+    typer.echo(tok.decode(id_list, skip_special_tokens=True))
+
+
+@app.command()
+def report(
+    results_dir: Path = typer.Option(Path("results"), "--results", help="Results directory."),
+) -> None:
+    """Regenerate the Markdown table + bar charts from benchmarks.json."""
+    from edgellm.benchmark import render_markdown
+    from edgellm.report import render_charts
+
+    json_path = results_dir / "benchmarks.json"
+    if not json_path.exists():
+        typer.echo(f"no results at {json_path}; run 'edgellm benchmark' first.", err=True)
+        raise typer.Exit(1)
+    (results_dir / "benchmark.md").write_text(render_markdown(json_path))
+    chart = render_charts(json_path, results_dir / "benchmark_chart.png")
+    typer.echo(f"wrote {results_dir / 'benchmark.md'} and {chart}")
+
+
+@app.command()
+def quantize(
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+) -> None:
+    """Produce INT8 (ONNX Runtime) and INT4 (block-wise) quantized artifacts."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+    from edgellm.export import ONNXExporter
+    from edgellm.quantize import Quantizer
+
+    cfg = _load_config(config_path)
+    fp32_dir = ONNXExporter(cfg.model, cfg.export).export()
+    q = Quantizer(cfg.quantize)
+    base = fp32_dir.parent / fp32_dir.name.replace("-fp32", "")
+    int8_dir = q.ort_dynamic_int8(fp32_dir, Path(f"{base}-int8-dynamic"))
+    int4_dir = q.ort_int4(fp32_dir, Path(f"{base}-int4"))
+    typer.echo(f"INT8: {int8_dir}")
+    typer.echo(f"INT4: {int4_dir}")
+    typer.echo("\nINT4 backend availability on this machine:")
+    for backend, state in q.int4_availability().items():
+        typer.echo(f"  {backend}: {state}")
+
+
+@app.command()
+def benchmark(
+    config_path: Path = typer.Option(DEFAULT_CONFIG, "--config", "-c", help="Path to YAML config."),
+    skip_ppl: bool = typer.Option(False, "--skip-ppl", help="Skip perplexity (faster)."),
+    results_dir: Path = typer.Option(Path("results"), "--results", help="Output directory."),
+    only: str = typer.Option(
+        "pt-fp32,ort-fp32,ort-int8,ort-int4,pt-int8",
+        "--only",
+        help="Comma list of backends to benchmark.",
+    ),
+) -> None:
+    """Benchmark FP32/INT8/INT4 across PyTorch + ONNX Runtime and write real numbers."""
+    logging.basicConfig(level=logging.INFO, format="%(levelname)s %(name)s: %(message)s")
+
+    from edgellm.benchmark import (
+        BenchmarkHarness,
+        PerplexityEvaluator,
+        measure_size_mb,
+        render_markdown,
+        save_results,
+    )
+    from edgellm.export import ONNXExporter
+    from edgellm.models import ModelLoader
+    from edgellm.quantize import Quantizer
+    from edgellm.runners import ORTRunner, PyTorchRunner
+
+    cfg = _load_config(config_path)
+    selected = {s.strip() for s in only.split(",") if s.strip()}
+    harness = BenchmarkHarness(cfg.benchmark)
+    ppl_eval = None if skip_ppl else PerplexityEvaluator(cfg.benchmark)
+    json_path = results_dir / "benchmarks.json"
+
+    loaded = ModelLoader(cfg.model).load()  # FP32 on the best local device (mps/cuda/cpu)
+    fp32_dir = ONNXExporter(cfg.model, cfg.export).export()
+    quantizer = Quantizer(cfg.quantize)
+    base = fp32_dir.parent / fp32_dir.name.replace("-fp32", "")
+
+    def bench_ort(model_dir: Path, precision: str, name: str):
+        runner = ORTRunner(str(model_dir), loaded.tokenizer, name=name)
+        ppl = _ppl_ort(runner, ppl_eval, loaded.tokenizer) if ppl_eval else None
+        size = measure_size_mb(model_dir, ("*.onnx", "*.onnx_data"))
+        return harness.run(
+            runner,
+            precision=precision,
+            device="cpu",
+            model_id=cfg.model.id,
+            generation=cfg.generation,
+            size_mb=size,
+            perplexity=ppl,
+        )
+
+    def bench_pt_fp32():
+        ppl = (
+            _ppl_torch(loaded.model, loaded.device, ppl_eval, loaded.tokenizer)
+            if ppl_eval
+            else None
+        )
+        return harness.run(
+            PyTorchRunner(loaded),
+            precision="fp32",
+            device=loaded.device,
+            model_id=cfg.model.id,
+            generation=cfg.generation,
+            size_mb=_pytorch_size_mb(cfg.model.id, cfg.model.revision),
+            perplexity=ppl,
+        )
+
+    def bench_pt_int8():
+        cpu_loaded = ModelLoader(replace(cfg.model, device="cpu")).load()
+        qmodel = Quantizer.pytorch_dynamic_int8(cpu_loaded.model)
+        cpu_loaded = replace(cpu_loaded, model=qmodel, device="cpu")
+        ppl = _ppl_torch(qmodel, "cpu", ppl_eval, cpu_loaded.tokenizer) if ppl_eval else None
+        return harness.run(
+            PyTorchRunner(cpu_loaded),
+            precision="int8",
+            device="cpu",
+            model_id=cfg.model.id,
+            generation=cfg.generation,
+            size_mb=None,
+            perplexity=ppl,
+        )
+
+    # (key, human label, thunk). Each runs guarded so one failure can't discard the rest.
+    steps = [
+        ("pt-fp32", "pytorch fp32", bench_pt_fp32),
+        ("ort-fp32", "ort-cpu fp32", lambda: bench_ort(fp32_dir, "fp32", "ort-cpu")),
+        (
+            "ort-int8",
+            "ort-cpu int8",
+            lambda: bench_ort(
+                quantizer.ort_dynamic_int8(fp32_dir, Path(f"{base}-int8-dynamic")),
+                "int8",
+                "ort-cpu-int8",
+            ),
+        ),
+        (
+            "ort-int4",
+            "ort-cpu int4",
+            lambda: bench_ort(
+                quantizer.ort_int4(fp32_dir, Path(f"{base}-int4")), "int4", "ort-cpu-int4"
+            ),
+        ),
+        ("pt-int8", "pytorch int8 (cpu)", bench_pt_int8),
+    ]
+
+    for key, label, thunk in steps:
+        if key not in selected:
+            continue
+        typer.echo(f"[bench] {label}...")
+        try:
+            result = thunk()
+        except Exception as exc:  # noqa: BLE001 - one backend must not sink the others
+            typer.echo(f"[bench] {label} FAILED: {type(exc).__name__}: {exc}", err=True)
+            continue
+        save_results([result], json_path)  # persist incrementally
+
+    md = render_markdown(json_path)
+    (results_dir / "benchmark.md").write_text(md)
+    typer.echo("\n=== results ===")
+    typer.echo(md)
+    typer.echo(f"wrote {json_path} and {results_dir / 'benchmark.md'}")
+
+
+def _ppl_torch(model, device: str, ppl_eval, tokenizer) -> float:
+    import torch
+
+    def forward(ids: torch.Tensor, attn: torch.Tensor) -> torch.Tensor:
+        with torch.inference_mode():
+            out = model(input_ids=ids.to(device), attention_mask=attn.to(device))
+        return out.logits.detach().to("cpu")
+
+    return ppl_eval.evaluate(forward, tokenizer)
+
+
+def _ppl_ort(runner, ppl_eval, tokenizer) -> float:
+    import torch
+
+    def forward(ids: torch.Tensor, attn: torch.Tensor) -> torch.Tensor:
+        out = runner.model(input_ids=ids, attention_mask=attn)
+        return out.logits.detach().to("cpu")
+
+    return ppl_eval.evaluate(forward, tokenizer)
+
+
+def _pytorch_size_mb(model_id: str, revision: str) -> float | None:
+    """On-disk size (MB) of the model weights in the local HF cache."""
+    from huggingface_hub import snapshot_download
+
+    from edgellm.benchmark import measure_size_mb
+
+    try:
+        snap = Path(
+            snapshot_download(
+                model_id, revision=revision, allow_patterns=["*.safetensors", "*.bin"]
+            )
+        )
+    except Exception:
+        return None
+    size = measure_size_mb(snap, ("*.safetensors", "*.bin"))
+    return size or None
+
+
+def main() -> None:
+    """Console-script entry point."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

edgellm/cli_bench.py

@@ -0,0 +1,195 @@
+"""The ``run`` / ``submit`` / ``leaderboard`` commands — the lightweight path.
+
+Registered onto the main Typer app by :mod:`edgellm.cli`. Kept in its own module
+because this is the path a contributor touches, and it should be readable without
+scrolling past the export/quantize authoring commands.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import typer
+
+from edgellm.eval_lite import DEFAULT_EVAL_WINDOWS
+from edgellm.hub import DEFAULT_MODEL, DEFAULT_PRECISIONS
+from edgellm.sweep import (
+    DEFAULT_GEN_TOKENS,
+    DEFAULT_MEASURED_RUNS,
+    DEFAULT_WARMUP_RUNS,
+)
+
+COMMUNITY_DIR = Path("results/community")
+
+
+def _parse_precisions(value: str) -> tuple[str, ...]:
+    items = tuple(p.strip() for p in value.split(",") if p.strip())
+    if not items:
+        raise typer.BadParameter("Give at least one precision, e.g. --precisions fp32,int8,q4")
+    return items
+
+
+def register(app: typer.Typer) -> None:
+    """Attach the lightweight commands to ``app``."""
+
+    @app.command()
+    def run(
+        model: str = typer.Option(DEFAULT_MODEL, "--model", "-m", help="Hub model id with ONNX."),
+        precisions: str = typer.Option(
+            ",".join(DEFAULT_PRECISIONS), "--precisions", help="Comma-separated precision list."
+        ),
+        revision: str = typer.Option("main", "--revision", help="Hub revision to pin."),
+        provider: str = typer.Option(
+            "CPUExecutionProvider", "--provider", help="ONNX Runtime execution provider."
+        ),
+        threads: int | None = typer.Option(
+            None, "--threads", help="intra-op threads (default: physical core count)."
+        ),
+        gen_tokens: int = typer.Option(
+            DEFAULT_GEN_TOKENS, "--gen-tokens", help="Tokens to generate per run."
+        ),
+        measured_runs: int = typer.Option(
+            DEFAULT_MEASURED_RUNS, "--measured-runs", help="Timed runs per precision."
+        ),
+        warmup_runs: int = typer.Option(
+            DEFAULT_WARMUP_RUNS, "--warmup-runs", help="Untimed warmup runs."
+        ),
+        eval_windows: int = typer.Option(
+            DEFAULT_EVAL_WINDOWS, "--eval-windows", help="512-token perplexity windows."
+        ),
+        skip_perplexity: bool = typer.Option(
+            False, "--skip-perplexity", help="Measure speed and size only (much faster)."
+        ),
+        out: Path = typer.Option(
+            COMMUNITY_DIR, "--out", help="Directory to write the result card into."
+        ),
+        no_isolate: bool = typer.Option(
+            False,
+            "--no-isolate",
+            help="Measure all precisions in one process (faster, but peak-RAM becomes unreliable).",
+        ),
+        verbose: bool = typer.Option(False, "--verbose", "-v", help="Debug logging."),
+    ) -> None:
+        """Benchmark pre-quantized ONNX precisions of MODEL on this machine.
+
+        Downloads already-quantized artifacts from the Hub — nothing is quantized
+        locally, so this needs no PyTorch and no GPU.
+        """
+        from edgellm.render import console_report
+        from edgellm.sweep import SweepSettings, run_sweep, save_card
+
+        logging.basicConfig(
+            level=logging.DEBUG if verbose else logging.WARNING,
+            format="%(levelname)s %(name)s: %(message)s",
+        )
+
+        settings = SweepSettings(
+            model_id=model,
+            precisions=_parse_precisions(precisions),
+            revision=revision,
+            provider=provider,
+            intra_op_threads=threads,
+            warmup_runs=warmup_runs,
+            measured_runs=measured_runs,
+            gen_tokens=gen_tokens,
+            eval_windows=eval_windows,
+            skip_perplexity=skip_perplexity,
+        )
+
+        typer.echo(f"Benchmarking {model} on this machine ({len(settings.precisions)} precisions).")
+        typer.echo("First run downloads the ONNX artifacts; later runs reuse the HF cache.\n")
+
+        def progress(precision: str, state: str) -> None:
+            if state == "start":
+                typer.echo(f"  {precision:>6} ... ", nl=False)
+            elif state == "ok":
+                typer.echo("done")
+            else:
+                typer.echo("skipped")
+
+        card, errors = run_sweep(settings, on_progress=progress, isolate=not no_isolate)
+
+        if not card.rows:
+            typer.echo("\nNo precision could be measured. Reasons:", err=True)
+            for precision, why in errors.items():
+                typer.echo(f"  {precision}: {why}", err=True)
+            raise typer.Exit(1)
+
+        typer.echo(console_report(card, errors))
+
+        path = save_card(card, out)
+        typer.echo(f"Result card: {path}")
+        typer.echo("Share it on the public leaderboard with:  quantcost submit")
+
+    @app.command()
+    def models(
+        model: str = typer.Option(DEFAULT_MODEL, "--model", "-m", help="Hub model id to inspect."),
+        revision: str = typer.Option("main", "--revision"),
+    ) -> None:
+        """List which ONNX precisions a Hub model actually publishes."""
+        from edgellm.hub import available_precisions
+
+        found = available_precisions(model, revision=revision)
+        if not found:
+            typer.echo(
+                f"{model} publishes no ONNX files under onnx/. Try a model from "
+                "https://huggingface.co/onnx-community",
+                err=True,
+            )
+            raise typer.Exit(1)
+        typer.echo(f"{model} publishes: {', '.join(found)}")
+
+    @app.command()
+    def leaderboard(
+        community: Path = typer.Option(COMMUNITY_DIR, "--dir", help="Directory of result cards."),
+        out: Path = typer.Option(
+            Path("results/LEADERBOARD.md"), "--out", help="Markdown file to write."
+        ),
+        json_out: Path | None = typer.Option(
+            Path("site/leaderboard.json"), "--json-out", help="JSON for the site to render."
+        ),
+    ) -> None:
+        """Rebuild the leaderboard from every card in the community directory."""
+        from edgellm.leaderboard import build_leaderboard, render_leaderboard_markdown
+
+        cards = sorted(community.glob("*.json"))
+        if not cards:
+            typer.echo(f"No result cards found in {community}.", err=True)
+            raise typer.Exit(1)
+
+        board = build_leaderboard(cards)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(render_leaderboard_markdown(board))
+        typer.echo(
+            f"Wrote {out} from {len(cards)} card(s), {len(board['entries'])} machine-model rows."
+        )
+
+        if json_out is not None:
+            json_out.parent.mkdir(parents=True, exist_ok=True)
+            json_out.write_text(json.dumps(board, indent=2) + "\n")
+            typer.echo(f"Wrote {json_out}")
+
+    @app.command()
+    def submit(
+        card: Path | None = typer.Option(
+            None, "--card", help="Card to submit (default: the newest in results/community)."
+        ),
+        community: Path = typer.Option(COMMUNITY_DIR, "--dir"),
+        name: str = typer.Option("", "--name", help="Credit line for the leaderboard (optional)."),
+        notes: str = typer.Option("", "--notes", help="Anything unusual about this machine."),
+        dry_run: bool = typer.Option(False, "--dry-run", help="Validate and print, do not push."),
+    ) -> None:
+        """Open a pull request adding your result card to the public leaderboard."""
+        from edgellm.submit import submit_card
+
+        target = card
+        if target is None:
+            cards = sorted(community.glob("*.json"), key=lambda p: p.stat().st_mtime)
+            if not cards:
+                typer.echo(f"No result card in {community}. Run `quantcost run` first.", err=True)
+                raise typer.Exit(1)
+            target = cards[-1]
+
+        submit_card(target, name=name, notes=notes, dry_run=dry_run, echo=typer.echo)

edgellm/config.py

@@ -0,0 +1,120 @@
+"""Typed configuration objects loaded from YAML.
+
+The whole project is driven by a single :class:`Config` tree so that every phase
+(loading, export, quantization, benchmarking) reads its settings from one place
+and the CLI can override any field.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields, is_dataclass
+from pathlib import Path
+from typing import Any, get_type_hints
+
+import yaml
+
+
+@dataclass
+class ModelConfig:
+    """Which model to load and how to place it on hardware."""
+
+    id: str = "Qwen/Qwen2.5-0.5B-Instruct"
+    revision: str = "main"
+    dtype: str = "float32"
+    device: str = "auto"
+    trust_remote_code: bool = False
+
+
+@dataclass
+class GenerationConfig:
+    """Text-generation decoding parameters."""
+
+    max_new_tokens: int = 128
+    min_new_tokens: int | None = None
+    temperature: float = 0.7
+    top_p: float = 0.9
+    do_sample: bool = True
+    seed: int = 0
+
+
+@dataclass
+class BenchmarkConfig:
+    """Settings for the benchmark harness (used from Phase 2 onward)."""
+
+    warmup_runs: int = 2
+    measured_runs: int = 5
+    gen_tokens: int = 64
+    prompt: str = "Explain what neural network quantization is, in one short paragraph."
+    eval_dataset: str = "wikitext"
+    eval_config: str = "wikitext-2-raw-v1"
+    eval_num_samples: int = 32
+    eval_max_length: int = 512
+
+
+@dataclass
+class ExportConfig:
+    """ONNX export settings (used from Phase 2 onward)."""
+
+    opset: int = 17
+    output_dir: str = "artifacts/onnx"
+
+
+@dataclass
+class Int8Config:
+    scheme: str = "dynamic"
+    per_channel: bool = True
+
+
+@dataclass
+class Int4Config:
+    method: str = "gptq"
+    group_size: int = 128
+
+
+@dataclass
+class QuantizeConfig:
+    """Quantization settings (used from Phase 3 onward)."""
+
+    int8: Int8Config = field(default_factory=Int8Config)
+    int4: Int4Config = field(default_factory=Int4Config)
+
+
+@dataclass
+class Config:
+    """Root configuration tree."""
+
+    model: ModelConfig = field(default_factory=ModelConfig)
+    generation: GenerationConfig = field(default_factory=GenerationConfig)
+    benchmark: BenchmarkConfig = field(default_factory=BenchmarkConfig)
+    export: ExportConfig = field(default_factory=ExportConfig)
+    quantize: QuantizeConfig = field(default_factory=QuantizeConfig)
+    backends: list[str] = field(default_factory=lambda: ["pytorch", "ort-cpu"])
+
+    @classmethod
+    def from_yaml(cls, path: str | Path) -> Config:
+        """Load a :class:`Config` from a YAML file, filling in defaults."""
+        raw = yaml.safe_load(Path(path).read_text()) or {}
+        if not isinstance(raw, dict):
+            raise ValueError(f"Config root must be a mapping, got {type(raw).__name__}")
+        return _from_dict(cls, raw)
+
+
+def _from_dict(cls: type, data: dict[str, Any]) -> Any:
+    """Recursively build a (possibly nested) dataclass from a plain dict.
+
+    Unknown keys raise, so typos in the YAML fail loudly instead of being ignored.
+    """
+    kwargs: dict[str, Any] = {}
+    known = {f.name for f in fields(cls)}
+    # Resolve annotations to real types (needed because `from __future__ import
+    # annotations` turns dataclass field types into strings).
+    hints = get_type_hints(cls)
+    for key, value in data.items():
+        if key not in known:
+            raise ValueError(f"Unknown config key '{key}' for {cls.__name__}")
+        field_type = hints[key]
+        if is_dataclass(field_type) and isinstance(value, dict):
+            kwargs[key] = _from_dict(field_type, value)
+        else:
+            kwargs[key] = value
+    return cls(**kwargs)