engine/real_advisor.py

"""
Engine v2: honest verdicts over REAL models from catalogue.json.

This replaces both the size-class advisor and the placeholder families. Every
option it returns is an actual model with a Hugging Face link, a license, and
memory figures with provenance:

  - LLM / VLM weights = the EXACT GGUF file size in bytes from the Hub
    (ground truth — better than any params-times-bits estimate).
  - Chat memory (KV cache) = GQA-aware math from the model's real config
    (layers, hidden, kv-heads) when available; a conservative parameter-count
    heuristic when the repo is gated (labelled as estimated).
  - Working space includes a +0.577 GB buffer — the 95% load-success margin
    oobabooga fitted over 19,517 real measurements (gguf-vram-formula).
  - Non-GGUF families (vision / image gen / audio / embeddings / data) carry a
    single memory figure whose provenance is vendor-published, community-
    reported, or estimated — and the UI says which.

The catalogue is baked into the repo at build time (refreshed by
scripts/refresh_catalogue.py), so the running app makes no network calls.
"""

import json
from functools import lru_cache
from pathlib import Path

from .hardware import HardwareSpec
from .runtimes import pick_runtimes
from .speed import (bandwidth_for_spec, predict_decode_tps, feel_text,
                    predict_compute_speed, compute_feel_text)

_CATALOGUE_PATH = Path(__file__).resolve().parent.parent / "catalogue.json"

# We only fill a budget to this fraction — the rest is breathing room.
_SAFETY_FILL = 0.90
# oobabooga's fitted 95%-load-success buffer (GB), cited in the UI footnote.
_CONFIDENCE_BUFFER_GB = 0.577

_VERDICT_WORD = {"great": "Runs great", "tight": "Tight, but works", "no": "Won't fit"}
_C_MODEL = "#818CF8"
_C_WORK = "#868E9C"

# Quant ladder quality order (matches scripts/refresh_catalogue.py).
_QUANT_ORDER = ["Q8_0", "Q6_K", "Q5_K_M", "Q4_K_M", "IQ4_XS", "Q3_K_M", "Q2_K"]
_FOUR_BIT_RANK = _QUANT_ORDER.index("IQ4_XS")   # >= this index quality = sub-4-bit
_COMPROMISE_QUANTS = ["Q4_K_M", "IQ4_XS", "Q3_K_M", "Q2_K"]


# --------------------------------------------------------------------------
# Use cases
# --------------------------------------------------------------------------

class UC:
    def __init__(self, key, plain, family, ctx=4096, min_b=0.0, good_b=0.0,
                 factor=1.0, note=""):
        # min_b/good_b are LLM-quality bars in billions of params. They default
        # to 0 because they're meaningless for vision/audio/etc. — a 0.003B
        # YOLO is a complete, excellent model, not a too-small LLM. Only the
        # text use cases set them explicitly.
        self.key, self.plain_name, self.family = key, plain, family
        self.context_tokens, self.min_b, self.good_b = ctx, min_b, good_b
        self.overhead_factor, self.note = factor, note


USE_CASES = {u.key: u for u in [
    UC("chat", "Just chatting / asking questions", "llm", 4096, 0.5, 3.0),
    UC("writing", "Writing & summarising", "llm", 4096, 1.5, 7.0),
    UC("coding", "Coding help", "llm", 8192, 3.0, 7.0,
       note="Bigger models are much more reliable for code."),
    UC("agents", "Agents & tool use", "llm", 8192, 7.0, 7.0, 1.15,
       note="Needs steady instruction-following — go medium or larger."),
    UC("rag", "Chat with your documents", "llm", 16384, 3.0, 7.0,
       note="Long documents use extra memory for context — that's included here."),
    UC("translate", "Translation", "llm", 4096, 1.5, 7.0),
    UC("finetune", "Fine-tune an LLM (LoRA)", "llm", 2048, 3.0, 7.0, 2.2,
       note="Training needs roughly 2-3x the memory of just chatting. That's baked into these numbers."),
    UC("custom", "Your custom goal", "llm", 4096, 0.5, 7.0),
    UC("vlm", "Chat about images & video", "vlm", 4096, 1.5, 4.0),
    UC("detect", "Object detection", "vision"),
    UC("segment", "Image segmentation", "vision"),
    UC("pose", "Pose estimation (2D & 6-DoF)", "vision"),
    UC("classify", "Image classification", "vision"),
    UC("depth", "Depth estimation", "vision"),
    UC("ocr", "Read text from images (OCR)", "vision"),
    UC("train-vision", "Train a vision model", "vision", factor=3.0,
       note="Training needs roughly 3x the memory of running the same model."),
    UC("imagegen", "Generate images", "imagegen"),
    UC("inpaint", "Edit / inpaint images", "imagegen"),
    UC("upscale", "Upscale / restore images", "imagegen"),
    UC("videogen", "Generate video", "imagegen"),
    UC("bgremove", "Remove backgrounds", "imagegen"),
    UC("stt", "Speech to text", "audio"),
    UC("tts", "Text to speech / voice", "audio"),
    UC("music", "Generate music", "audio"),
    UC("embed", "Semantic search / embeddings", "embed"),
    UC("forecast", "Time-series forecasting", "data"),
    UC("tabular", "Predict from spreadsheets", "data"),
]}

# Use cases answered by the whole LLM family (entries don't list these).
# "custom" is deliberately NOT here: we can't honestly map free-text goals to
# the catalogue, so it returns guidance (paste a model id) rather than a
# misleading generic LLM answer.
_TEXT_UCS = {"chat", "writing", "coding", "agents", "rag", "translate",
             "finetune"}

_TOOLS = {
    "llm": [
        {"name": "Ollama", "what": "Type one line; it downloads and runs the model for you.",
         "install": "Get it from ollama.com", "tag": "Easiest"},
        {"name": "LM Studio", "what": "A point-and-click app with a chat window, no commands.",
         "install": "Download from lmstudio.ai", "tag": "Easy"},
        {"name": "llama.cpp", "what": "The lightweight engine under the hood. Runs GGUF files directly.",
         "install": "Releases on GitHub", "tag": "Advanced"},
    ],
    "vision": [
        {"name": "Ultralytics", "what": "One pip install, then detect objects from a webcam or file.",
         "install": "pip install ultralytics", "tag": "Easiest"},
        {"name": "PyTorch", "what": "Full control for custom pipelines and training.",
         "install": "pytorch.org", "tag": "Advanced"},
    ],
    "imagegen": [
        {"name": "ComfyUI", "what": "Powerful visual node editor for image/video pipelines.",
         "install": "Download from GitHub", "tag": "Moderate"},
        {"name": "diffusers", "what": "Hugging Face's Python library for generation pipelines.",
         "install": "pip install diffusers", "tag": "Moderate"},
        {"name": "Fooocus", "what": "Image generation that 'just works': one folder, double-click.",
         "install": "Download from GitHub", "tag": "Easiest"},
    ],
    "audio": [
        {"name": "faster-whisper", "what": "Fast, accurate transcription with a tiny install.",
         "install": "pip install faster-whisper", "tag": "Easiest"},
        {"name": "whisper.cpp", "what": "Runs Whisper efficiently on CPU and small machines.",
         "install": "Build from GitHub", "tag": "Advanced"},
    ],
    "embed": [
        {"name": "sentence-transformers", "what": "Turn text into searchable vectors in a few lines.",
         "install": "pip install sentence-transformers", "tag": "Easiest"},
        {"name": "Chroma", "what": "A simple local database to store and search those vectors.",
         "install": "pip install chromadb", "tag": "Easy"},
    ],
    "data": [
        {"name": "Python + pip", "what": "These models ship as small Python packages.",
         "install": "pip install (see the model card)", "tag": "Easiest"},
    ],
}
_TOOLS["vlm"] = _TOOLS["llm"]


# --------------------------------------------------------------------------
# Catalogue access
# --------------------------------------------------------------------------

@lru_cache(maxsize=1)
def catalogue() -> dict:
    return json.loads(_CATALOGUE_PATH.read_text(encoding="utf-8"))


@lru_cache(maxsize=1)
def _by_use_case() -> dict:
    out: dict[str, list[dict]] = {}
    for e in catalogue()["entries"]:
        if e["family"] in ("llm", "vlm"):
            ucs = list(_TEXT_UCS) if e["family"] == "llm" else ["vlm"]
        else:
            ucs = e.get("use_cases", [])
        for uc in ucs:
            out.setdefault(uc, []).append(e)
    for uc in out:
        out[uc].sort(key=lambda e: e.get("params_b", 0), reverse=True)
    return out


def catalogue_date() -> str:
    return catalogue().get("generated_at", "")[:10]


# --------------------------------------------------------------------------
# Memory math
# --------------------------------------------------------------------------

# Fallback architecture shapes by parameter count (conservative typicals),
# used only when a gated repo hides its config.json.
_ARCH_FALLBACK = [
    (1.5, 24, 2048), (4.5, 28, 3072), (9.0, 32, 4096),
    (16.0, 40, 5120), (40.0, 48, 6656), (1e9, 80, 8192),
]


def _kv_gb(entry: dict, ctx: int) -> tuple[float, bool]:
    """KV-cache GB for `ctx` tokens. Returns (gb, exact?)."""
    ctx = min(ctx, entry.get("context_len") or ctx)
    arch = entry.get("arch")
    if arch:
        # KV element count per layer = n_kv_heads * head_dim. head_dim is the
        # model's REAL per-head size when stated (Qwen3/Gemma set it explicitly
        # and it is NOT hidden/n_heads); fall back to hidden/n_heads only when
        # the config didn't state it. Using hidden*n_kv_heads/n_heads blindly
        # mis-sizes the cache by 1.6-2x on those models.
        head_dim = arch.get("head_dim") or (arch["hidden"] / arch["n_heads"])
        per_layer = arch["n_kv_heads"] * head_dim
        return 2 * arch["n_layers"] * per_layer * ctx * 2 / 1e9, True
    params = entry.get("params_b", 4.0)
    for cap, layers, hidden in _ARCH_FALLBACK:
        if params <= cap:
            return 2 * layers * hidden * ctx * 2 * 0.30 / 1e9, False
    return 1.0, False


def _overhead_gb(weights: float, factor: float) -> float:
    if factor >= 2.0:   # training: optimizer state + activations dominate
        return round(_CONFIDENCE_BUFFER_GB + weights * (factor - 1.0), 2)
    return round((_CONFIDENCE_BUFFER_GB + 0.08 * weights) * factor, 2)


def _estimate(entry: dict, quant: dict, ctx: int, factor: float) -> dict:
    weights = quant["file_gb"]
    kv, kv_exact = _kv_gb(entry, ctx)
    kv = round(kv, 2)
    overhead = _overhead_gb(weights, factor)
    return {"weights": weights, "kv": kv, "overhead": overhead,
            "total": round(weights + kv + overhead, 2), "kv_exact": kv_exact}


# --------------------------------------------------------------------------
# Per-entry evaluation
# --------------------------------------------------------------------------

def _quant_rank(key: str) -> int:
    return _QUANT_ORDER.index(key) if key in _QUANT_ORDER else len(_QUANT_ORDER)


def _feel(entry: dict, verdict: str, spec: HardwareSpec) -> str:
    if verdict == "no":
        return "—"
    active = entry.get("active_params_b") or entry.get("params_b", 4)
    if verdict == "tight":
        if entry.get("active_params_b"):
            return f"Usable even part-offloaded (only {entry['active_params_b']:g}B active per word)"
        return "Slow — usable for short tasks, not snappy chat"
    if active <= 4:
        return "Fast — replies feel instant"
    if active <= 14:
        return "Comfortable — quick enough for live chat"
    return "Steady — fine, just not instant on big answers"


def _eval_gguf(entry: dict, spec: HardwareSpec, uc: UC) -> dict:
    """Verdict for an LLM/VLM entry with a real quant ladder."""
    fast, total = spec.fast_budget_gb, spec.total_budget_gb
    quants = sorted(entry.get("quants", []), key=lambda q: _quant_rank(q["key"]))
    ctx, factor = uc.context_tokens, uc.overhead_factor

    # Fast path: best quality quant >= 4-bit that fits the GPU budget.
    if spec.has_fast_path:
        for q in quants:
            if _quant_rank(q["key"]) > _FOUR_BIT_RANK:
                break   # don't call a sub-4-bit squeeze "runs great"
            est = _estimate(entry, q, ctx, factor)
            if est["total"] <= fast * _SAFETY_FILL:
                return {"verdict": "great", "quant": q, "est": est}

    # Compromise: spill into ordinary RAM, shrinking quality only if needed.
    for qkey in _COMPROMISE_QUANTS:
        q = next((x for x in quants if x["key"] == qkey), None)
        if not q:
            continue
        est = _estimate(entry, q, ctx, factor)
        if est["total"] <= total * _SAFETY_FILL:
            return {"verdict": "tight", "quant": q, "est": est}

    q = quants[-1] if quants else {"key": "Q4_K_M", "plain": "Balanced (4-bit)",
                                   "file_gb": entry.get("params_b", 4) * 0.6}
    return {"verdict": "no", "quant": q, "est": _estimate(entry, q, ctx, factor)}


def _eval_flat(entry: dict, spec: HardwareSpec, uc: UC) -> dict:
    """Verdict for a non-GGUF entry with one memory figure."""
    need = round(entry.get("mem_gb", 4.0) * uc.overhead_factor, 2)
    fast, total = spec.fast_budget_gb, spec.total_budget_gb
    est = {"weights": need, "kv": 0.0, "overhead": 0.0, "total": need, "kv_exact": False}
    setting = {"key": "full", "plain": "Full model", "file_gb": need}
    if spec.has_fast_path and need <= fast * _SAFETY_FILL:
        return {"verdict": "great", "quant": setting, "est": est}
    # Image/video generation without a GPU is minutes-per-image: say so.
    if entry["family"] == "imagegen" and not spec.has_fast_path and need > 4:
        return {"verdict": "no", "quant": setting, "est": est}
    if need <= total * _SAFETY_FILL:
        return {"verdict": "tight", "quant": setting, "est": est}
    return {"verdict": "no", "quant": setting, "est": est}


def _evaluate(entry: dict, spec: HardwareSpec, uc: UC) -> dict:
    if entry.get("quants"):
        r = _eval_gguf(entry, spec, uc)
    else:
        r = _eval_flat(entry, spec, uc)
    r["entry"] = entry
    return r


# --------------------------------------------------------------------------
# Advise: full UI-shaped result
# --------------------------------------------------------------------------

def _speed_pred(r: dict, spec: HardwareSpec, bw: float | None) -> dict | None:
    """Measured/roofline tok/s prediction for a GGUF option, if bandwidth known."""
    e, v, est = r["entry"], r["verdict"], r["est"]
    if not e.get("quants") or v == "no" or not bw:
        return None
    params = e.get("params_b") or 1.0
    active = (e.get("active_params_b") or params) / params
    if v == "tight":
        # share of the read bytes that live in slow system RAM
        fast_room = spec.fast_budget_gb * _SAFETY_FILL
        offload = max(0.0, min(1.0, 1 - fast_room / max(est["total"], 0.1)))
    else:
        offload = 0.0
    return predict_decode_tps(
        bandwidth_gbs=bw, weights_gb=est["weights"], kv_gb=est["kv"],
        active_fraction=active, offload_fraction=offload,
    )


def _option_json(r: dict, spec: HardwareSpec, bw: float | None = None) -> dict:
    e, v = r["entry"], r["verdict"]
    pred = _speed_pred(r, spec, bw)
    # Compute-bound families (vision detection, diffusion) get an FPS / seconds-
    # per-image estimate instead of the bandwidth tok/s line, when in scope.
    # Compute-roofline speed assumes the model is FULLY RESIDENT in VRAM. When it
    # is offloaded (tight) the number would be wildly optimistic, so only emit it
    # when the model fits the fast path (verdict == great); else show no number.
    cpred = predict_compute_speed(e, spec) if (not pred and v == "great") else None
    if pred:
        feel = feel_text(pred)
    elif cpred:
        feel = compute_feel_text(cpred)
    else:
        feel = _feel(e, v, spec)
    if not e.get("quants") and v == "tight" and not spec.has_fast_path:
        feel = "Runs on the processor — slow but workable"
    lic_label = e.get("license", "")
    return {
        "verdict": v,
        "model": e["name"],
        "desc": e.get("good_for", ""),
        "setting": r["quant"].get("plain", "Full model"),
        "memory": "Too big" if v == "no" else f"{r['est']['total']:g} GB",
        "feel": feel,
        "compute_speed": cpred,
        "params_b": e.get("params_b"),
        "active_params_b": e.get("active_params_b"),
        "url": (e.get("links") or {}).get("hf") or (e.get("links") or {}).get("home", ""),
        "license": lic_label,
        "license_note": e.get("license_note", ""),
        "gated": e.get("gated", False),
        "run": e.get("run", {}),
        "provenance": e.get("provenance", "estimated"),
        "stale": e.get("stale", False),
    }


# Licences that satisfy the "Fully open" UI promise: permissive or OSI open-source
# with commercial use allowed. Deliberately EXCLUDES non-commercial (cc-by-nc*),
# research-only, and gated/custom community licences (llama/gemma). Gating and
# openness are separate axes (see fully_open()).
_OPEN_LICENSES = {
    "apache-2.0", "mit", "bsd-3-clause", "bsd-2-clause", "bsd",
    "cc-by-4.0", "cc-by-sa-4.0", "cc0-1.0", "mpl-2.0",
    "openrail", "openrail++", "creativeml-openrail-m", "bigscience-openrail-m",
    "gpl-3.0", "agpl-3.0", "lgpl-3.0", "unlicense",
}


def _pick_headline(results: list[dict], uc: UC,
                   priority: str = "balanced") -> tuple[dict | None, bool]:
    great = [r for r in results if r["verdict"] == "great"]
    tight = [r for r in results if r["verdict"] == "tight"]

    def params(r):
        return r["entry"].get("params_b", 0)

    def active(r):
        return r["entry"].get("active_params_b") or params(r)

    def fully_open(r):
        # "Fully open" must mean a genuinely open licence, not merely ungated.
        # Gating and openness are different axes; a non-commercial licence is not
        # "fully open". Requires membership in an explicit permissive/open-source
        # allowlist and excludes any non-commercial / research-only terms.
        e = r["entry"]
        if e.get("gated"):
            return False
        lic = (e.get("license") or "").lower().strip()
        note = (e.get("license_note") or "").lower()
        if "nc" in lic.split("-") or "non-commercial" in note or "research" in note:
            return False
        return lic in _OPEN_LICENSES

    def speed_key(r):
        # Lower = faster. Compute-bound families rank by predicted compute, not
        # by parameter count (a smaller diffusion model can be SLOWER per image).
        e = r["entry"]
        if e.get("gflops_step"):   # diffusion: total FLOPs per image
            return e.get("steps_default", 30) * e["gflops_step"] + e.get("gflops_overhead", 0)
        if e.get("gflops"):        # single-forward vision: FLOPs per forward
            return e["gflops"]
        return active(r)           # LLM decode is bandwidth-bound: fewer active params ~ faster

    great_ok = [r for r in great if params(r) >= uc.min_b]
    tight_ok = [r for r in tight if params(r) >= uc.min_b]

    # "Fully open": prefer fully-open models when any exist — but never leave the
    # user with nothing, so only filter when it doesn't empty the set.
    if priority == "open":
        if any(fully_open(r) for r in great_ok):
            great_ok = [r for r in great_ok if fully_open(r)]
        if any(fully_open(r) for r in tight_ok):
            tight_ok = [r for r in tight_ok if fully_open(r)]

    if great_ok:
        if priority == "speed":
            # Fastest among the still-capable picks, by predicted compute/latency.
            capable = [r for r in great_ok if params(r) >= uc.good_b] or great_ok
            return min(capable, key=speed_key), True
        # Quality and balanced both want the biggest model that runs great.
        return max(great_ok, key=params), True
    if tight_ok:
        if uc.good_b > 0 and priority != "quality":
            # LLMs: close to the ideal size, not needlessly oversized-and-slow.
            # "Best quality" overrides this and takes the biggest that still fits.
            below = [r for r in tight_ok if params(r) <= uc.good_b * 1.5]
            return (max(below, key=params) if below else min(tight_ok, key=params)), True
        # Non-LLM families (and quality mode): the biggest that fits is best.
        return max(tight_ok, key=params), True
    if great:
        return max(great, key=params), False
    if tight:
        return min(tight, key=params), False
    return None, False


def _provenance_line(headline: dict | None) -> str:
    if not headline:
        return ""
    e = headline["entry"]
    prov = e.get("provenance", "estimated")
    if prov == "filesize":
        line = ("Model size is the exact file size on Hugging Face. Chat memory and "
                "working space are conservative estimates with a 0.58 GB safety buffer "
                "(the 95% load-success margin fitted from ~19,500 real measurements).")
        if not headline["est"].get("kv_exact"):
            line += " This repo hides its exact shape, so chat memory is estimated from its size."
        return line
    if prov == "vendor":
        return "The memory figure is the maker's own published number."
    if prov == "community":
        return "The memory figure is community-reported, not vendor-published — treat it as a good estimate."
    return "The memory figure is estimated from the model's size — conservative, not measured."


def advise_real(payload: dict, spec: HardwareSpec, extra_entries: list | None = None) -> dict:
    uc = USE_CASES.get(payload.get("usecase", "chat"), USE_CASES["chat"])
    candidates = list(_by_use_case().get(uc.key, []))
    # A live-looked-up model not in the catalogue is injected here as a synthetic
    # candidate, so it flows through the same gauge / speed-chart / comparison
    # pipeline as catalogue models (its sizes are estimates, labelled as such).
    if extra_entries:
        candidates = list(extra_entries) + candidates

    # Honest gap, not a fake answer: if the catalogue doesn't cover a goal yet,
    # say so and point at the live lookup instead of inventing options.
    if not candidates:
        is_custom = uc.key == "custom"
        typed = (payload.get("custom") or "").strip()
        if is_custom:
            head = "Tell us the exact model and we'll check it."
            detail = (
                (f"You described <b>“{typed}”</b>. " if typed else "")
                + "FitCheck answers from verified model data, so it won't guess which model "
                "your description means. Paste the exact Hugging Face model id (e.g. "
                "<b>lerobot/smolvla_base</b>) in the <b>'Have a specific model in mind?'</b> box "
                "below and we'll check that model against your machine — or pick one of the "
                "categories above for a curated recommendation."
            )
            word = "Name the model"
        else:
            head = "Our catalogue doesn't cover this goal yet."
            detail = ("FitCheck only answers from verified model data, and nothing in the "
                      "current catalogue serves this goal — so rather than guess, we'd "
                      "rather say so. If you know a specific model for it, paste its "
                      "Hugging Face id in the <b>'Have a specific model in mind?'</b> box "
                      "and we'll check that exact model against your machine.")
            word = "Not covered yet"
        return {
            "catalogue_version": catalogue_date(),
            "verdict": "tight", "verdict_word": word,
            "headline": head, "detail": detail,
            "note": "" if is_custom else "The catalogue grows every night; niche goals are next in line.",
            "gauge": {}, "options": [], "tools": [],
            "commands": {"intro": "", "items": []}, "provenance": "",
            "meets_goal": False, "use_case": uc.plain_name, "usecase": uc.key,
            "focus": "", "headline_model": "",
        }

    results = [_evaluate(e, spec, uc) for e in candidates]

    fast, total = spec.fast_budget_gb, spec.total_budget_gb
    headline, meets_goal = _pick_headline(results, uc, payload.get("priority", "balanced"))

    # A specific model the user clicked / asked to focus on. We still show the
    # honest verdict for THAT model — including "won't fit" — instead of the
    # engine's own best pick. The whole breakdown below flows from `headline`.
    focus = (payload.get("focus") or "").strip()
    if focus:
        fr = next((r for r in results
                   if r["entry"]["name"] == focus
                   or str(r["entry"].get("repo_id", "")).lower() == focus.lower()), None)
        if fr:
            headline = fr
            meets_goal = fr["entry"].get("params_b", 0) >= uc.min_b

    bw, bw_src = bandwidth_for_spec(spec)
    options = [_option_json(r, spec, bw) for r in results]

    if headline:
        e, est, q = headline["entry"], headline["est"], headline["quant"]
        hv = headline["verdict"]
        need = est["total"]
        no_gpu = not spec.has_fast_path
        where = ("on your Mac" if spec.is_apple_silicon and hv == "great" else
                 "on your graphics card" if hv == "great" and spec.has_fast_path else
                 "on the processor" if hv == "tight" and no_gpu else
                 "using your computer's memory" if hv == "tight" else "")
        if hv == "great":
            head_text = f"Yes, you can run {e['name']} {where}, today."
        elif hv == "tight" and no_gpu:
            # CPU inference of a small quantised model is genuinely usable, just
            # not instant — say that plainly rather than "with trade-offs".
            head_text = f"Yes, with no graphics card {e['name']} runs {where} (slower, but it works)."
        elif hv == "tight":
            head_text = f"Sort of. {e['name']} will run {where}, with trade-offs."
        else:
            head_text = f"{e['name']} won't fit on this machine."
        # "What you have" reads differently with vs without a dedicated GPU.
        if spec.is_apple_silicon:
            have_clause = (f"and your Mac shares <b>{total:g} GB</b> of unified memory between "
                           f"the processor and graphics.")
        elif no_gpu:
            have_clause = (f"and with no separate graphics card it runs on the processor using "
                           f"your <b>{total:g} GB</b> of system memory — slower than a GPU, but "
                           f"it works, especially at a 4-bit setting.")
        else:
            have_clause = (f"and you have about <b>{fast:g} GB</b> on the graphics card, or "
                           f"<b>{total:g} GB</b> counting system memory it can spill into.")
        if e.get("quants"):
            # Be honest about whether the weights figure is an exact file size
            # (catalogue / GGUF) or a parameter-count estimate (live lookup).
            if e.get("provenance") == "filesize":
                weights_phrase = f"the model file is {est['weights']:g} GB — exact size on Hugging Face"
            else:
                weights_phrase = (f"the weights are about {est['weights']:g} GB at this setting "
                                  f"(estimated from its {e.get('params_b', 0):g}B parameters)")
            detail = (
                f"For this goal, the honest pick is <b>{e['name']}</b> at the "
                f"<b>{q.get('plain', q['key'])}</b> setting. {e.get('good_for','')} "
                f"It needs about <b>{need:g} GB</b> "
                f"({weights_phrase} plus {est['kv']:g} GB chat memory and "
                f"{est['overhead']:g} GB working space), {have_clause}"
            )
        else:
            detail = (
                f"For this goal, the honest pick is <b>{e['name']}</b>. "
                f"{e.get('good_for','')} It needs about <b>{need:g} GB</b>, {have_clause}"
            )
        model_part, work_part = est["weights"], round(need - est["weights"], 2)
    else:
        hv = "no"
        smallest = min(results, key=lambda r: r["est"]["total"], default=None)
        need = smallest["est"]["total"] if smallest else 1.0
        head_text = "This goal is a stretch on this machine. Here's the honest picture."
        detail = (
            f"Even the lightest option here needs about <b>{need:g} GB</b>, but this "
            f"machine can offer only about <b>{total:g} GB</b> once the operating system "
            f"has its share. That's not a failure — small computers just have small "
            f"budgets. Adding memory, or a free cloud notebook, would open this up."
        )
        model_part, work_part = round(need * 0.8, 2), round(need * 0.2, 2)

    note_bits = []
    if headline and not meets_goal:
        note_bits.append(
            f"This is the best this machine can do, but it's on the small side for "
            f"{uc.plain_name.lower()} — treat results as 'okay', not great.")
    if uc.note:
        note_bits.append(uc.note)
    if headline and headline["entry"].get("mem_note"):
        note_bits.append(headline["entry"]["mem_note"])
    if headline and headline["entry"].get("license_note"):
        note_bits.append(headline["entry"]["license_note"])
    if headline and headline["entry"].get("gated"):
        note_bits.append("This model is gated: accept its terms on Hugging Face once before downloading.")

    scale = max(total, need, 1) * 1.05
    has_fast = spec.has_fast_path
    if spec.is_apple_silicon:
        fast_label, total_label = "GPU can use", "Unified memory"
    elif has_fast:
        fast_label, total_label = "On the GPU (VRAM)", "GPU + system RAM"
    else:
        fast_label, total_label = "", "System RAM (no GPU)"
    gauge = {
        "need_gb": f"{need:g} GB needed",
        "fast_gb": f"{fast:g} GB", "total_gb": f"{total:g} GB",
        "fast_label": fast_label, "total_label": total_label,
        "has_fast": has_fast,
        "fill_pct": round(min(need / scale, 1.0) * 100, 1),
        "mark_pct": round(min(fast / scale, 1.0) * 100, 1),
        "total_pct": round(min(total / scale, 1.0) * 100, 1),
        "breakdown": [
            {"label": f"Model {model_part:g} GB", "color": _C_MODEL},
            {"label": f"Chat memory + working space {work_part:g} GB", "color": _C_WORK},
        ],
    }

    speed = None
    compute_speed = None
    if headline:
        pred = _speed_pred(headline, spec, bw)
        if pred:
            speed = {**pred, "bw": bw, "bw_source": bw_src,
                     "model": headline["entry"]["name"]}
        elif headline["verdict"] == "great":
            # Compute-bound headline (vision/diffusion): FPS or seconds-per-image,
            # but ONLY when fully resident in VRAM (offloaded numbers are bogus).
            cpred = predict_compute_speed(headline["entry"], spec)
            if cpred:
                compute_speed = {**cpred, "model": headline["entry"]["name"]}

    if uc.family == "llm":
        tools = [{"name": r.name, "what": r.plain_what, "install": r.install_hint,
                  "tag": r.difficulty} for r in pick_runtimes(spec)]
    else:
        tools = _TOOLS.get(uc.family, [])

    commands = {"intro": "These get you running in minutes — real commands for the exact pick above.",
                "items": []}
    if headline:
        run = headline["entry"].get("run", {})
        if run.get("ollama"):
            commands["items"].append({"label": "Easy way (Ollama)", "code": run["ollama"]})
        if run.get("llamacpp"):
            commands["items"].append({"label": "Power way (llama.cpp)", "code": run["llamacpp"]})
        if run.get("pip"):
            commands["items"].append({"label": "Install", "code": run["pip"]})

    return {
        "catalogue_version": catalogue_date(),
        "verdict": hv,
        "verdict_word": _VERDICT_WORD[hv],
        "headline": head_text,
        "detail": detail,
        "note": "  ".join(note_bits),
        "gauge": gauge,
        "options": options,
        "tools": tools,
        "commands": commands,
        "provenance": _provenance_line(headline) + (
            f" Speed is {'predicted from real community measurements' if speed and speed['method'] == 'measured-model' else 'an analytical bandwidth estimate'}"
            f" — see 'Why this speed?' below." if speed else
            " Speed is a compute-roofline estimate (a ceiling) calibrated on published benchmarks."
            if compute_speed else ""),
        "speed": speed,
        "compute_speed": compute_speed,
        "meets_goal": meets_goal,
        "use_case": uc.plain_name,
        "usecase": uc.key,
        "focus": focus or "",
        "headline_model": headline["entry"]["name"] if headline else "",
    }


# --------------------------------------------------------------------------
# Reverse mode: "what machine do I need for X?"  Multi-platform, 2026 hardware.
# --------------------------------------------------------------------------

# Each platform is a cheap -> expensive ladder of representative builds. The
# memory numbers feed the SAME engine (so recommendations are grounded, not
# hand-waved); `spec` and `detail` power the human-readable + click-to-expand
# card. Prices are rough mid-2026 street figures (the DRAM shortage moved them),
# shown as guidance, not gospel. Sources: TechPowerUp/Tom's (bandwidth), vendor
# pages; software-support notes from ROCm/MLX/CUDA reporting.
# Prices below are dated, research-verified APPROXIMATIONS (US, complete systems),
# not live quotes and not hardcoded training-era guesses: each carries a `link`
# to a live price source (Apple's own config page; the vendor product page for
# the mini-PCs; a price tracker for the GPU builds) so the reader can always see
# the current number even as ours ages. A 2026 LPDDR5X/DRAM shortage is inflating
# GPU, Mac-memory and mini-PC prices, so these skew upward and drift; the link is
# the source of truth. Last checked June 2026.
_PRICE_CHECKED = "June 2026"

_PLATFORMS = [
    {
        "key": "nvidia", "name": "NVIDIA PC", "icon": "brand-nvidia",
        "blurb": "The path of least resistance: CUDA, so every tool just works. Best if you might fine-tune.",
        "tiers": [
            ("RTX 5060 Ti 16GB build", "$1,070-1,270", dict(ram_gb=32, vram_gb=16, vendor="nvidia"),
             "8-core CPU, 32 GB DDR5, RTX 5060 Ti 16GB, 1 TB NVMe",
             "16 GB of VRAM is the real sweet spot: it runs 13-14B models comfortably and starts to fine-tune 7B with QLoRA. The cheapest 16 GB CUDA card, about $570 for the GPU alone in mid-2026 (above its $429 launch price on AI demand), with a narrow memory bus that makes it slower than a 5070 Ti. Desktop over laptop: more VRAM per dollar and a swappable GPU.",
             "https://bestvaluegpu.com/history/new-and-used-rtx-5060-ti-16gb-price-history-and-specs/"),
            ("RTX 5070 Ti build", "$1,480-1,680", dict(ram_gb=32, vram_gb=16, vendor="nvidia"),
             "8-core CPU, 32-64 GB DDR5, RTX 5070 Ti 16GB, 2 TB NVMe",
             "Same 16 GB ceiling but much faster generation (896 GB/s). The mainstream pick for snappy local AI. The GPU alone is about $980 in mid-2026, above its $749 launch price on scarcity. A desktop card sustains load better than the throttled laptop chip.",
             "https://bestvaluegpu.com/history/new-and-used-rtx-5070-ti-price-history-and-specs/"),
            ("RTX 4090 / 24 GB build (used GPU)", "$2,900-3,100", dict(ram_gb=64, vram_gb=24, vendor="nvidia"),
             "12-core CPU, 64 GB DDR5, 24 GB GPU (RTX 4090, used), 2 TB NVMe",
             "24 GB runs ~30B models comfortably and QLoRA-fine-tunes up to ~30B. The 4090 is discontinued and now trades ABOVE its $1,599 launch price (around $2,400 used) because 24 GB is in AI demand. Buy used carefully, or consider a 24 GB 50-series. 64 GB system RAM lets big models spill over.",
             "https://bestvaluegpu.com/history/new-and-used-rtx-4090-price-history-and-specs/"),
            ("RTX 5090 build", "$4,500-5,000", dict(ram_gb=64, vram_gb=32, vendor="nvidia"),
             "12-16 core CPU, 64-128 GB DDR5, RTX 5090 32GB, 2 TB NVMe",
             "The fastest consumer card and the only one with 32 GB, so it runs ~30B at full speed and big diffusion models. Street prices sit near twice the $1,999 launch price (about $4,000-4,300 for the GPU alone in mid-2026) on AI demand plus the DRAM shortage. Workstation money. If you mainly fine-tune, two 24 GB cards can beat one 5090.",
             "https://bestvaluegpu.com/history/new-and-used-rtx-5090-price-history-and-specs/"),
        ],
    },
    {
        "key": "amd", "name": "AMD PC", "icon": "brand-amd",
        "blurb": "Cheaper VRAM for inference. On Windows use the Vulkan path (LM Studio); rougher for training.",
        "tiers": [
            ("RX 9070 XT build", "$1,150-1,500", dict(ram_gb=32, vram_gb=16, vendor="amd"),
             "8-core CPU, 32 GB DDR5, Radeon RX 9070 XT 16GB, 2 TB NVMe",
             "16 GB at a good price; runs up to ~14B models well. The GPU alone is about $650-800 in mid-2026 (above its $599 launch). For 'open a model and chat' the AMD-vs-NVIDIA gap is mostly price. Caveat: on Windows use llama.cpp / LM Studio via Vulkan; ROCm is Linux-first and fine-tuning support lags CUDA.",
             "https://bestvaluegpu.com/history/new-and-used-rx-9070-xt-price-history-and-specs/"),
            ("RX 7900 XTX build", "$1,500-2,000", dict(ram_gb=64, vram_gb=24, vendor="amd"),
             "12-core CPU, 64 GB DDR5, Radeon RX 7900 XTX 24GB, 2 TB NVMe",
             "The AMD standout for local AI: 24 GB and 960 GB/s, runs 70B at 4-bit. End-of-life now, so the card is about $1,030-1,340 new (around $800 used, the value route). Best VRAM-per-dollar at this tier. Still AMD-software caveats for training, but excellent for inference.",
             "https://bestvaluegpu.com/history/new-and-used-rx-7900-xtx-price-history-and-specs/"),
        ],
    },
    {
        "key": "apple", "name": "Mac (Apple Silicon)", "icon": "brand-apple",
        "blurb": "Unified memory runs models no consumer GPU can hold, quietly and efficiently. Inference-focused.",
        "tiers": [
            ("Mac mini M4, 16 GB", "$799", dict(ram_gb=16, apple=True),
             "Apple M4, 16 GB unified memory",
             "The cheapest way into Apple Silicon AI, at Apple's $799 list (the old $599 base was dropped in May 2026). The shared memory pool lets the GPU use almost all 16 GB; runs small and mid models quietly. Buy the RAM up front: Apple memory is soldered and can never be upgraded. (The MacBook Air is now M5 and pricier.)",
             "https://www.apple.com/shop/buy-mac/mac-mini"),
            ("Mac mini M4 Pro, 48 GB", "$1,799-1,999", dict(ram_gb=48, apple=True),
             "Apple M4 Pro, 48 GB unified memory, 273 GB/s",
             "A strong quiet inference machine: 48 GB holds ~30B-class models and the M4 Pro's higher bandwidth keeps them usable. Apple dropped the 36 GB option, so the M4 Pro mini now comes as 24 or 48 GB. Weaker than NVIDIA for fine-tuning (MLX does small LoRA; real training wants CUDA).",
             "https://www.apple.com/shop/buy-mac/mac-mini"),
            ("Mac Studio M4 Max, 64 GB", "$2,699", dict(ram_gb=64, apple=True),
             "Apple M4 Max, 64 GB unified memory, 410-546 GB/s",
             "64 GB of unified memory runs models a 24 GB GPU cannot load, at higher bandwidth than the mini-PC boxes. 64 GB is now the top M4 Max config (the 128 GB tier was culled in the 2026 memory shortage). The sweet spot for running big models quietly.",
             "https://www.apple.com/shop/buy-mac/mac-studio"),
            ("Mac Studio M3 Ultra, 96 GB", "$3,999", dict(ram_gb=96, apple=True),
             "Apple M3 Ultra, 96 GB unified memory",
             "Capacity king of the current lineup: 96 GB holds ~70B-class models quietly. Apple temporarily pulled the 128/256/512 GB Studio tiers in the 2026 memory shortage (expected back with the M5 Studio), so 96 GB is today's Apple ceiling. The win is capacity and quiet, not raw speed (a 5090 is faster on whatever fits its 32 GB).",
             "https://www.apple.com/shop/buy-mac/mac-studio"),
        ],
    },
    {
        "key": "mini", "name": "Mini-PC / edge box", "icon": "monitor",
        "blurb": "Small, silent, low-power boxes, from a $249 CUDA Jetson up to unified-memory mini-PCs that fit huge models at a steady jog, not a sprint.",
        "tiers": [
            ("Jetson Orin Nano Super, 8 GB", "$249", dict(ram_gb=8, unified=True, vendor="nvidia"),
             "NVIDIA Jetson Orin Nano Super dev kit, 8 GB unified LPDDR5, CUDA, 67 TOPS",
             "A complete CUDA dev kit for $249, a price that has held through the 2026 shortage. 8 GB of unified memory caps you to small quantised models, but unlike a Raspberry Pi (which is CPU-only and, oddly, now costs more) it has a real GPU, so those models actually accelerate. The best dollar-per-CUDA box here, ideal for tinkering and tiny always-on models.",
             "https://www.nvidia.com/en-us/autonomous-machines/embedded-systems/jetson-orin/nano-super-developer-kit/"),
            ("Jetson Orin NX, 16 GB", "$949", dict(ram_gb=16, unified=True, vendor="nvidia"),
             "NVIDIA Jetson Orin NX 16 GB unified LPDDR5, CUDA, 100 TOPS (Seeed reComputer J4012)",
             "The cheapest Jetson that crosses 16 GB of unified memory with CUDA, sold ready-to-run as the Seeed reComputer J4012 (module, carrier board and a 128 GB SSD) for about $949. Doubles the Orin Nano's memory, so it runs small-to-mid models with GPU acceleration, still well under a Ryzen AI Max+ box. Bare modules cost less but you assemble the rest.",
             "https://www.seeedstudio.com/reComputer-J4012-p-5586.html"),
            ("Ryzen AI Max+ 395, 64 GB", "$1,499-1,700", dict(ram_gb=64, unified=True, vendor="amd"),
             "AMD Ryzen AI Max+ 395 'Strix Halo', 64 GB unified memory, ~256 GB/s",
             "16 Zen 5 cores plus a strong integrated GPU sharing 64 GB, in a tiny quiet box, no discrete card. Runs ~30B comfortably. Examples: GMKtec EVO-X2 around $1,499, Framework Desktop $1,639. Bandwidth is far below a discrete GPU, so big models fit and are usable but not fast. Soldered RAM, so buy the capacity up front.",
             "https://frame.work/desktop"),
            ("Ryzen AI Max+ 395, 128 GB", "$1,999-2,800", dict(ram_gb=128, unified=True, vendor="amd"),
             "AMD Ryzen AI Max+ 395 'Strix Halo', 128 GB unified memory, ~256 GB/s",
             "128 GB of unified memory runs 70B-class models for far less than a Mac with the same capacity, and sips power. Prices run from about $1,999 (GMKtec EVO-X2) to $2,459 (Framework Desktop) to $2,799 (Bosgame M5); the 2026 LPDDR5X hike landed hardest on this tier. Best capacity-per-dollar for big-model experimentation; accept moderate speed.",
             "https://frame.work/desktop"),
        ],
    },
]


def _spec_for_tier(hw: dict) -> HardwareSpec:
    # Apple and unified-memory mini-PCs share one memory pool (model like Apple);
    # a normal PC has separate VRAM + system RAM.
    if hw.get("apple") or hw.get("unified"):
        return HardwareSpec(os="macos" if hw.get("apple") else "linux",
                            ram_gb=hw["ram_gb"], gpu_vendor=hw.get("vendor", "apple"),
                            is_apple_silicon=True, form_factor="mac")
    return HardwareSpec(os="windows", ram_gb=hw["ram_gb"],
                        gpu_vendor=hw.get("vendor", "none"),
                        vram_gb=hw.get("vram_gb", 0.0), form_factor="desktop")


def min_specs(usecases, mode: str = "run") -> dict:
    """For one OR several goals, across every platform: the cheapest build where
    EVERY goal genuinely works (the union of requirements), and the build where
    every goal runs great. `mode="finetune"` sizes for training instead of
    inference. Pure engine inversion — makes no network calls."""
    if isinstance(usecases, str):
        usecases = [usecases]
    seen = set()
    ucs = []
    for u in usecases or ["chat"]:
        uc = USE_CASES.get(u, USE_CASES["chat"])
        if uc.key not in seen:
            seen.add(uc.key)
            ucs.append(uc)

    finetune = mode == "finetune"
    if finetune:
        from .finetune import advise_finetune

    def assess(uc, spec):
        if finetune:
            return advise_finetune({"usecase": uc.key}, spec)
        return advise_real({"usecase": uc.key}, spec)

    def walk(tiers):
        # Score every tier once, then choose two DISTINCT builds:
        #   minimum     = cheapest tier that genuinely works (great or tight).
        #   comfortable = the next step UP that adds real headroom (prefers a
        #                 tier that runs everything great; falls back to the next
        #                 one that at least works). It is always strictly above
        #                 the minimum, so the two are never the same build -- the
        #                 old logic collapsed them whenever the cheapest tier
        #                 already ran everything great.
        built = []
        for i, (label, price, hw, spec_line, detail, link) in enumerate(tiers):
            spec = _spec_for_tier(hw)
            per_goal, all_meet, all_great = [], True, True
            for uc in ucs:
                res = assess(uc, spec)
                all_meet &= res["meets_goal"] and res["verdict"] in ("great", "tight")
                all_great &= res["meets_goal"] and res["verdict"] == "great"
                per_goal.append({"goal": uc.plain_name,
                                 "model": res["headline_model"] or "nothing realistic",
                                 "verdict": res["verdict"]})
            tier = {"label": label, "price": price, "spec": spec_line, "detail": detail,
                    "link": link, "price_checked": _PRICE_CHECKED, "goals": per_goal,
                    "runs": "; ".join(f"{g['goal']}: {g['model']}" for g in per_goal)
                            if len(per_goal) > 1 else per_goal[0]["model"]}
            built.append({"idx": i, "tier": tier, "all_meet": all_meet,
                          "all_great": all_great})

        mn = next((b for b in built if b["all_meet"]), None)
        if mn is None:
            return None, None
        # Comfortable: cheapest tier strictly above the minimum that runs all
        # goals great; else the next one above that at least works.
        cf = (next((b for b in built if b["idx"] > mn["idx"] and b["all_great"]), None)
              or next((b for b in built if b["idx"] > mn["idx"] and b["all_meet"]), None))
        if cf is None:
            # Minimum is the top of this platform's ladder; say so honestly
            # instead of repeating the same build as "comfortable".
            return mn["tier"], {"ceiling": True, "label": mn["tier"]["label"]}
        return mn["tier"], cf["tier"]

    platforms = []
    for p in _PLATFORMS:
        mn, comfy = walk(p["tiers"])
        platforms.append({"key": p["key"], "name": p["name"], "icon": p["icon"],
                          "blurb": p["blurb"], "minimum": mn, "comfortable": comfy})

    notes = [uc.note for uc in ucs if uc.note]
    verb = "fine-tune" if finetune else "run"
    return {
        "use_case": " + ".join(uc.plain_name for uc in ucs),
        "goals": [uc.plain_name for uc in ucs],
        "mode": mode,
        "catalogue_version": catalogue_date(),
        "price_checked": _PRICE_CHECKED,
        "note": "  ".join(notes),
        "platforms": platforms,
        "disclaimer": (f"Two distinct builds per platform: the cheapest that genuinely lets you "
                       f"{verb} these goals, and a step up that does it with headroom. Click any "
                       f"card for the parts and a live price link. Prices are research-checked "
                       f"approximations (US, {_PRICE_CHECKED}), not live quotes; a 2026 memory "
                       f"shortage is pushing them up, so use the link for today's figure. The "
                       f"memory math is the same conservative engine as the main check."
                       + (" Builds cover the union of every goal you picked: each must work."
                          if len(ucs) > 1 else "")),
    }