Align GPU compute across surfaces: shared flavor+cost catalog + OS-search route

key_farm/flavors.py is now the single source of truth for compute flavors
(name/kind/hourly_usd/vram). The scaler budget math costs each GPU flavor
from the catalog, and the OS-search route_query() answers gpu/cost/hardware/
flavor queries (previously 'Route not matched').

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

key_farm/flavors.py

@@ -0,0 +1,73 @@
+"""Canonical compute-flavor catalog — ONE source of truth across all surfaces.
+
+Consumed by:
+- ``key_farm.scaler.ScalePolicy`` -> per-flavor hourly cost for the budget math
+- ``meshscale_space.os_routes.route_query`` -> the OS-search "gpu"/"cost"/"hardware" route
+- KEY controller/config -> GPU lane selection (``gpu_hardware`` / ``MESHSCALE_GPU_HARDWARE``)
+
+Keep hardware facts HERE and nowhere else so every surface stays aligned.
+Rates are approximate HF Spaces/Jobs list price (USD/hour, 2026); vram/ram are
+approximate host specs for guidance, not billing. cpu-upgrade 0.03 matches the
+existing ``cpu_space_hourly_usd`` default.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Flavor:
+    name: str
+    kind: str          # "cpu" or "gpu"
+    hourly_usd: float
+    vram_gb: int       # 0 for CPU flavors
+    ram_gb: int
+    note: str = ""
+
+
+FLAVORS: dict[str, Flavor] = {
+    f.name: f
+    for f in [
+        Flavor("cpu-basic", "cpu", 0.00, 0, 16, "2 vCPU - free tier"),
+        Flavor("cpu-upgrade", "cpu", 0.03, 0, 32, "8 vCPU - default farm worker"),
+        Flavor("t4-small", "gpu", 0.40, 16, 15, "NVIDIA T4 - cheapest GPU"),
+        Flavor("t4-medium", "gpu", 0.60, 16, 30, "NVIDIA T4 - more host RAM"),
+        Flavor("l4x1", "gpu", 0.80, 24, 48, "NVIDIA L4"),
+        Flavor("a10g-small", "gpu", 1.00, 24, 30, "NVIDIA A10G"),
+        Flavor("a10g-large", "gpu", 1.50, 24, 92, "NVIDIA A10G - large host"),
+        Flavor("a100-large", "gpu", 2.50, 80, 142, "NVIDIA A100 80GB - heavy brains fit"),
+        Flavor("rtx-pro-6000", "gpu", 2.75, 96, 188, "RTX PRO 6000 - 96GB VRAM"),
+        Flavor("h100", "gpu", 4.50, 80, 250, "NVIDIA H100"),
+        Flavor("h200", "gpu", 5.00, 141, 276, "NVIDIA H200 - 141GB VRAM"),
+    ]
+}
+
+
+def get_flavor(name: str | None) -> Flavor | None:
+    if not name:
+        return None
+    return FLAVORS.get(str(name).strip().lower())
+
+
+def list_flavors(kind: str | None = None) -> list[Flavor]:
+    """Flavors sorted cheapest-first, optionally filtered to 'cpu' or 'gpu'."""
+    fs = [f for f in FLAVORS.values() if kind is None or f.kind == kind]
+    return sorted(fs, key=lambda f: f.hourly_usd)
+
+
+def hourly_cost(name: str | None, default: float = 0.0) -> float:
+    """Catalog hourly rate for a flavor; ``default`` if the flavor is unknown."""
+    f = get_flavor(name)
+    return f.hourly_usd if f else default
+
+
+def cheapest_gpu() -> Flavor:
+    return list_flavors("gpu")[0]
+
+
+def workers_within_budget(name: str | None, budget_hourly_usd: float, default_cost: float = 0.0) -> int:
+    """How many concurrent workers of ``name`` fit under an hourly budget."""
+    cost = hourly_cost(name, default_cost)
+    if cost <= 0:
+        return 0
+    return int(budget_hourly_usd // cost)

key_farm/scaler.py

@@ -53,7 +53,14 @@ class ScalePolicy:
 
     def _effective_hourly_cost(self) -> float:
         if self.gpu_hardware:
-            return self.gpu_space_hourly_usd
+            # Prefer the canonical catalog rate for the chosen flavor so the
+            # budget math stays aligned with every other surface; fall back to
+            # the policy's explicit gpu_space_hourly_usd for unknown flavors.
+            try:
+                from .flavors import hourly_cost
+                return hourly_cost(self.gpu_hardware, self.gpu_space_hourly_usd)
+            except Exception:
+                return self.gpu_space_hourly_usd
         return self.cpu_space_hourly_usd
 
     def effective_max_workers(self) -> int:

meshscale_space/os_routes.py

@@ -144,6 +144,42 @@ def route_query(query: str, status: dict[str, Any], links: dict[str, str] | None
             ],
         }
 
+    if any(token in q for token in (
+        "gpu", "cpu-upgrade", "hardware", "flavor", "accelerator", "cost",
+        "price", "budget", "rent", "rental", "cuda", "compute", "a100", "t4",
+        "h200", "h100", "l4", "a10g", "rtx",
+    )):
+        try:
+            from key_farm.flavors import list_flavors, cheapest_gpu
+            cpus = list_flavors("cpu")
+            gpus = list_flavors("gpu")
+            cheap = cheapest_gpu()
+            cpu_str = ", ".join(f"{f.name} ${f.hourly_usd:.2f}/hr" for f in cpus)
+            gpu_str = ", ".join(f"{f.name} ${f.hourly_usd:.2f}/hr" for f in gpus)
+            message = (
+                f"CPU flavors: {cpu_str}. GPU flavors: {gpu_str}. "
+                f"Cheapest GPU is {cheap.name} (${cheap.hourly_usd:.2f}/hr, {cheap.vram_gb}GB VRAM). "
+                "Route workers onto a GPU by setting gpu_hardware in the KEY run config "
+                "or MESHSCALE_GPU_HARDWARE on this Space; the budget then caps the worker count."
+            )
+        except Exception:
+            message = (
+                "Compute flavors: cpu-upgrade $0.03/hr (default), GPUs from t4-small "
+                "$0.40/hr up to h200 $5.00/hr. Set gpu_hardware / MESHSCALE_GPU_HARDWARE "
+                "to route workers onto a GPU; budget caps the count."
+            )
+        return {
+            "title": "Compute / GPU routes",
+            "message": message,
+            "severity": "info",
+            "actions": [
+                _action("command", "Plan capacity", "plan 420", "Estimate worker count under the budget for the chosen flavor."),
+                _action("command", "Dry-run scale", "scale dry", "Preview worker starts and the flavor the scaler will launch on."),
+                _action("link", "Worker template", links["worker_template"], "The image GPU/CPU workers run."),
+                _action("link", "Open KEY Space", links["key_space"], "Set gpu_hardware in the run config."),
+            ],
+        }
+
     return {
         "title": "Route not matched",
         "message": "The OS route did not find a direct match. Start with status or ask for a guide.",