urun-cli 0.5.1__tar.gz → 0.5.2__tar.gz

{urun_cli-0.5.1 → urun_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: urun-cli
-Version: 0.5.1
+Version: 0.5.2
 Summary: End-user CLI for deploying apps to urun
 Project-URL: Homepage, https://urun.sh
 Project-URL: Repository, https://github.com/urun-sh/urun-cli

{urun_cli-0.5.1 → urun_cli-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "urun-cli"
-version = "0.5.1"
+version = "0.5.2"
 description = "End-user CLI for deploying apps to urun"
 readme = "README.md"
 requires-python = ">=3.11"

urun_cli-0.5.2/src/urun/catalog.py

@@ -0,0 +1,652 @@
+"""Thin PostgREST client for the control-plane model catalog.
+
+``public.model_catalog`` is org-AGNOSTIC, anon-readable reference data published
+by a urun-infra migration (one row per ``(model_id, variant, gpu_spec)``; see
+``urun-infra/catalog/CONTRACT.md``). ``urun serve catalog`` enumerates it and
+``urun serve <id>[:<variant>]`` resolves a single row to deploy.
+
+CANONICAL PATH (no silent fallbacks — see CLAUDE.md): the catalog is read over
+PostgREST at the control-plane's ``/rest/v1/model_catalog`` endpoint. The base is
+derived from the SAME control-plane API URL the rest of the CLI uses (the origin
+of ``--api-url`` / ``URUN_API_URL`` / saved login, default ``api.urun.sh``), and
+PostgREST is reached with the public Supabase anon key. There is exactly ONE
+resolution for each input; a missing anon key FAILS HARD rather than guessing.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from . import __version__
+from .api import require_safe_url
+from .errors import ApiError, UrunError
+from .retry import DEPLOY_BACKOFF, BackoffPolicy, retry_call
+
+CATALOG_TABLE = "model_catalog"
+
+# PostgREST is mounted under /rest/v1 on the Supabase control plane; the CLI's
+# control-plane API URL (e.g. https://api.urun.sh/v1) shares the same origin.
+POSTGREST_PREFIX = "/rest/v1"
+
+# CLI-LOCAL SKU -> per-GPU VRAM (GB). DELIBERATELY DUPLICATED from urun-python's
+# GPU_VRAM_GB map: the CLI is standalone and cannot import the (often unreleased)
+# urun-python at runtime, so it carries its own small table. Keys are lowercase
+# SKU "kind" strings matching the prefix of a `gpu_spec` (`<kind>:<count>`).
+GPU_VRAM_GB: dict[str, int] = {
+    "l4": 24,
+    "a10g": 24,
+    "l40": 48,
+    "l40s": 48,
+    "a100": 80,
+    "h100": 80,
+    "h200": 141,
+    "b200": 192,
+    "5090": 32,
+}
+
+
+# CLI-LOCAL engine -> serving-deps mapping. DELIBERATELY DUPLICATED (like
+# GPU_VRAM_GB above) from urun-python's SOURCE OF TRUTH
+# ``urun/serve/engines/extras.py`` (``ENGINE_DEPS`` / ``serve_deps_for_engine``):
+# the CLI is standalone and cannot import the (often unreleased) urun-python at
+# deploy time, but it MUST know each engine's python deps so it can render them
+# statically into the ``urun serve`` shim's ``@app.function(deps=...)``. Without
+# this the builder's pure-AST deps extractor sees a shim with no declared deps,
+# skips the deps venv, and the serve pod crashloops with no engine installed.
+#
+# KEEP IN SYNC with urun-python ``ENGINE_DEPS``. ``tests/test_serve_catalog.py``
+# pins the exact contents (mirroring the GPU_VRAM_GB sync test); when urun-python
+# bumps a pin, mirror it here and update that test.
+_SERVE_COMMON_DEPS: tuple[str, ...] = (
+    "torch==2.6.0",
+    "transformers==4.51.3",
+    "tokenizers>=0.20.3",
+    "accelerate",
+    "safetensors",
+    "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+    # Cap below 2.0 to match the urun wheel's B200-safe floor (urun-python
+    # pyproject ``numpy>=1.23.5,<2``, #387). The engine deps and ``urun[deploy]``
+    # install into the SAME deps venv; a ``<2.3`` cap resolves numpy 2.2.x and
+    # makes the resolver unsatisfiable against the wheel's ``<2`` ("No solution
+    # found"). Stay <2 so the two coexist. KEEP IN SYNC with urun-python.
+    "numpy<2",
+    "pillow>=10.0.0",
+    "pycrdt>=0.13.0",
+    "orjson",
+)
+_LLAMACPP_CUDA_WHEEL_INDEX = "https://abetlen.github.io/llama-cpp-python/whl/cu124"
+
+# The upstream PyTorch prebuilt CUDA 12.4 wheel index (matches the dev L4 sm_89 /
+# CUDA 12.4 runtime base). Engines whose deps do NOT transitively pull a CUDA
+# torch (vLLM/sglang bring their own CUDA torch; ``custom-pytorch`` / diffusers
+# does NOT) MUST pass this so ``torch==2.6.0`` resolves to the ``+cu124`` wheel
+# rather than the PyPI-default ``+cpu`` build (a CPU torch cannot touch the L4).
+_TORCH_CUDA_WHEEL_INDEX = "https://download.pytorch.org/whl/cu124"
+
+# Image-engine (custom-pytorch / diffusers) serving deps. Diverges from
+# ``_SERVE_COMMON_DEPS`` on TWO axes the vLLM/text stack does not need:
+#   1. transformers: Qwen-Image-Edit-2511's text encoder is
+#      ``Qwen2_5_VLForConditionalGeneration``; transformers 4.51.3 (the vLLM-0.8.5
+#      lockstep pin) crashes building its nested ``text_config`` in
+#      ``GenerationConfig.from_model_config`` (``'dict' object has no attribute
+#      'to_dict'``). 4.53.x carries the Qwen2.5-VL config fix and still loads
+#      under torch 2.6.0.
+#   2. torch: pulled with the cu124 index so it is GPU-capable (diffusers brings
+#      no CUDA torch of its own).
+# KEEP IN SYNC with urun-python ``_SERVE_IMAGE_DEPS``.
+_SERVE_IMAGE_DEPS: tuple[str, ...] = (
+    "--extra-index-url",
+    _TORCH_CUDA_WHEEL_INDEX,
+    "torch==2.6.0",
+    # torchvision (pinned in lockstep with torch 2.6.0 -> 0.21.0, cu124 build via
+    # the index above). Qwen-Image-Edit-2511's processor pulls transformers'
+    # AutoVideoProcessor, which hard-gates on torchvision at load — without it
+    # DiffusionPipeline.from_pretrained raises "AutoVideoProcessor requires the
+    # Torchvision library but it was not found".
+    "torchvision==0.21.0",
+    "transformers==4.53.3",
+    "tokenizers>=0.20.3",
+    "accelerate",
+    "safetensors",
+    "huggingface_hub[hf_transfer]>=0.30.0,<1.0.0",
+    # Cap below 2.0 to match the urun wheel's B200-safe floor (see _SERVE_COMMON_DEPS).
+    # The image deps + ``urun[deploy]`` install into the SAME venv; ``<2.3`` resolves
+    # numpy 2.2.x and conflicts with the wheel's ``<2``. KEEP IN SYNC with urun-python.
+    "numpy<2",
+    "pillow>=10.0.0",
+    "pycrdt>=0.13.0",
+    "orjson",
+)
+
+# Full-duplex AUDIO (PersonaPlex / Moshi) serving deps. DIVERGES HARD from
+# ``_SERVE_COMMON_DEPS``: PersonaPlex ships its OWN VENDORED ``moshi`` fork
+# (github.com/NVIDIA/personaplex ``moshi/``, package ``moshi-personaplex``,
+# imports as ``moshi``) whose ``loaders.py`` loads the ``nvidia/personaplex-7b-v1``
+# checkpoint with HARDCODED kwargs — the upstream PyPI ``moshi``'s
+# ``CheckpointInfo.from_hf_repo`` crashes on the PersonaPlex stub config
+# (``KeyError: 'dep_q'``). PyPI ``moshi>=0.2.0`` ALSO caps ``aiohttp<3.12`` which
+# conflicts with the urun wheel's ``aiohttp>=3.12`` ("No solution found"). The
+# vendored fork does NOT cap aiohttp. Its pyproject pins ``torch>=2.2,<2.5`` +
+# ``huggingface-hub<0.25`` + ``numpy<2.2`` + ``sentencepiece==0.2`` + ``sphn``. We
+# pin ``numpy<2`` here (NOT the fork's ``<2.2``): the deploy builder installs
+# ``urun[deploy]`` (pyproject ``numpy>=1.23.5,<2`` — the B200-segfault floor) into
+# the SAME deps venv, and a ``<2.2`` cap resolves numpy 2.1.3 → collides with the
+# wheel's ``<2`` ("No solution found"). ``numpy<2`` (1.26.x) satisfies BOTH the
+# fork's ``<2.2`` AND urun's ``<2``. Pinned here as a self-contained group (torch
+# 2.4.1 +cu124 runs on the dev L4). KEEP IN SYNC with urun-python ``_SERVE_MOSHI_DEPS``.
+_SERVE_MOSHI_DEPS: tuple[str, ...] = (
+    "--extra-index-url",
+    _TORCH_CUDA_WHEEL_INDEX,
+    # PersonaPlex's vendored moshi caps torch <2.5; 2.4.1 is the latest cu124 wheel.
+    "torch==2.4.1",
+    # <2 (not the fork's <2.2): coexist with urun[deploy]'s numpy>=1.23.5,<2 in the
+    # shared deps-venv. 1.26.x satisfies both the fork's <2.2 and urun's <2.
+    "numpy<2",
+    "safetensors>=0.4.0,<0.5",
+    "huggingface_hub[hf_transfer]>=0.24,<0.25",
+    "sentencepiece==0.2.0",
+    "sphn>=0.1.4,<0.2",
+    "soundfile>=0.12.1",
+    "einops==0.7",
+    # The vendored PersonaPlex moshi fork (imports as ``moshi``). Pinned to the repo
+    # so the loader + LMGen API match the personaplex-7b-v1 checkpoint exactly.
+    "moshi-personaplex @ git+https://github.com/NVIDIA/personaplex.git@main#subdirectory=moshi",
+)
+ENGINE_DEPS: dict[str, list[str]] = {
+    "echo": [],
+    # CPU echo doubles per modality (image / full-duplex audio). Like ``echo``
+    # they need NOTHING heavy: ``echo-image`` is pure Pillow (already in the
+    # runtime base), ``echo-audio`` is pure-python PCM16 loopback.
+    "echo-image": [],
+    "echo-audio": [],
+    "vllm": [*_SERVE_COMMON_DEPS, "vllm==0.8.5.post1"],
+    "sglang": [*_SERVE_COMMON_DEPS, "sglang[all]>=0.4.0"],
+    "llamacpp": [
+        *_SERVE_COMMON_DEPS,
+        "--extra-index-url",
+        _LLAMACPP_CUDA_WHEEL_INDEX,
+        "llama-cpp-python>=0.3.2",
+    ],
+    "llamacpp-diffusion": [
+        *_SERVE_COMMON_DEPS,
+        "--extra-index-url",
+        _LLAMACPP_CUDA_WHEEL_INDEX,
+        "llama-cpp-python>=0.3.2",
+    ],
+    # custom-pytorch — generic custom-pytorch / diffusers IMAGE shape
+    # (Qwen-Image-Edit-Lightning fp8). Needs the diffusion pipeline (``diffusers``)
+    # on top of the common torch / transformers / safetensors / accelerate /
+    # huggingface_hub / pillow stack. NO llama.cpp / vllm.
+    "custom-pytorch": [*_SERVE_IMAGE_DEPS, "diffusers>=0.31.0"],
+    "transformers": [*_SERVE_COMMON_DEPS],
+    "diffusers": [*_SERVE_COMMON_DEPS, "diffusers"],
+    # Full-duplex AUDIO (PersonaPlex / Moshi speech-to-speech). Installs the
+    # VENDORED PersonaPlex moshi fork (NOT PyPI ``moshi`` — see _SERVE_MOSHI_DEPS):
+    # its loaders.py loads the nvidia/personaplex-7b-v1 checkpoint with the right
+    # hardcoded LM/Mimi config, where upstream moshi's CheckpointInfo crashes, and
+    # the fork does not cap aiohttp (PyPI moshi caps <3.12 vs the urun wheel >=3.12).
+    "moshi": [*_SERVE_MOSHI_DEPS],
+}
+
+
+def serve_deps_for_engine(engine: str | None, *, strict: bool = False) -> list[str]:
+    """Return the FLAT python dep list for a catalog ``engine`` value.
+
+    Mirror of urun-python ``urun.serve.engines.extras.serve_deps_for_engine``:
+    normalize (strip + lowercase; empty/None -> ``echo``). By default an UNKNOWN
+    engine yields ``[]`` rather than raising — this lenient form exists only for
+    the cross-impl parity test.
+
+    ``strict=True`` (the DEPLOY path) instead RAISES on an engine that is not in
+    ``ENGINE_DEPS``. This closes the (d) non-determinism: the CLI's ``ENGINE_DEPS``
+    is a hand-maintained DUPLICATE of urun-python's source of truth, so when the
+    catalog row's ``engine`` is a real serving engine the CLI's copy has drifted on
+    (or simply does not know), the lenient ``[]`` silently shipped an EMPTY deps
+    venv -> ``deps_required=false`` -> urun-only venv -> the serve pod crashloops
+    with no vllm/sglang/llama-cpp installed (and INTERMITTENTLY, depending on which
+    model/engine was deployed). A known engine that DELIBERATELY needs no deps (e.g.
+    ``echo``) is listed in ``ENGINE_DEPS`` with ``[]`` and stays a valid no-venv
+    deploy; only a genuinely-UNKNOWN engine is rejected.
+    """
+    name = (engine or "echo").strip().lower()
+    if strict and name not in ENGINE_DEPS:
+        known = ", ".join(sorted(ENGINE_DEPS))
+        raise UrunError(
+            f"serve engine {name!r} is not in the CLI's known serving-engine set "
+            f"({known}); refusing to deploy a serve build that would silently ship an "
+            f"EMPTY deps venv (no engine installed). The CLI's ENGINE_DEPS map has "
+            f"likely drifted from urun-python's source of truth — add {name!r} to "
+            f"urun.catalog.ENGINE_DEPS (kept in sync with urun-python "
+            f"urun.serve.engines.extras.ENGINE_DEPS)."
+        )
+    return list(ENGINE_DEPS.get(name, []))
+
+
+def parse_gpu_spec(spec: str) -> tuple[str, int]:
+    """Parse a ``<kind>:<count>`` SKU spec into ``(kind, count)``.
+
+    ``count`` defaults to 1 when there is no ``:`` (or a non-integer count),
+    mirroring :pyattr:`CatalogRow.gpu_count`. ``kind`` is lowercased so it keys
+    into :data:`GPU_VRAM_GB`.
+    """
+    kind, _, count = (spec or "").partition(":")
+    kind = kind.strip().lower()
+    try:
+        n = int(count)
+    except ValueError:
+        n = 1
+    return kind, (n if n > 0 else 1)
+
+
+def gpu_vram_gb(spec: str) -> int | None:
+    """Total VRAM (GB) a ``<kind>:<count>`` SKU provides, or None if unknown kind."""
+    kind, count = parse_gpu_spec(spec)
+    per = GPU_VRAM_GB.get(kind)
+    return per * count if per is not None else None
+
+
+# CLI-LOCAL GPU kind -> uv ``--torch-backend`` token. DELIBERATELY DUPLICATED
+# (like GPU_VRAM_GB / ENGINE_DEPS) from urun-python's SOURCE OF TRUTH — the runtime
+# vanilla base image map (``urun.runtime_controller.render._VANILLA_BASE_IMAGE_DEFAULTS``,
+# mirrored in ``urun.serve.deploy._GPU_CLASS_TORCH_BACKEND``). The base tag encodes
+# the CUDA ABI (``cu124-…-sm89`` for L4/L40S, ``cu130-…-sm90`` for H100, ``cu130-…-sm100``
+# for B200), so the app-deps torch index MUST match it or the resolved wheel won't run.
+# `urun serve` bakes the resolved value into the manifest's ``deps.torch_backend`` so
+# the build installs the engine's pinned torch from the GPU-correct index instead of
+# the deploy-side cu130 default (which has NO wheel for the engine's torch on the L4).
+# KEEP IN SYNC with urun-python; pinned by tests/test_serve_catalog.py.
+GPU_TORCH_BACKEND: dict[str, str] = {
+    "l4": "cu124",  # Ada / sm_89
+    "l40": "cu124",
+    "l40s": "cu124",
+    "a10": "cu124",  # Ampere / sm_86 — cu124 wheels cover it
+    "a10g": "cu124",
+    "a100": "cu124",  # Ampere / sm_80
+    "h100": "cu130",  # Hopper / sm_90
+    "h200": "cu130",
+    "b200": "cu130",  # Blackwell / sm_100
+}
+# Conservative default: the dev fleet is the L4, so an unknown kind must NOT fall
+# back to the broken cu130 default.
+DEFAULT_TORCH_BACKEND = "cu124"
+
+
+def torch_backend_for_gpu(spec: str) -> str:
+    """Resolve uv's ``--torch-backend`` token for a ``<kind>:<count>`` SKU spec."""
+    kind, _count = parse_gpu_spec(spec)
+    return GPU_TORCH_BACKEND.get(kind, DEFAULT_TORCH_BACKEND)
+
+
+@dataclass(frozen=True)
+class CatalogRow:
+    """One flattened ``(model_id, variant, gpu_spec)`` catalog placement.
+
+    Mirrors ``public.model_catalog`` exactly (see CONTRACT.md). ``is_dev_testable``
+    is the contract rule: a single-GPU, non-disagg placement runs on dev.
+    """
+
+    model_id: str
+    variant: str
+    gpu_spec: str
+    engine: str
+    family: str
+    task: str
+    hf_repo: str
+    description: str
+    size_gb: int
+    files: list[str] | None
+    disagg: bool
+    targets: dict[str, Any]
+    engine_args: dict[str, Any]
+    # Placement/serving floors (additive — older catalogs predate them, so they
+    # are optional and default to None; published by a separate urun-infra PR).
+    # ``default_gpu`` is model-level recommended placement (e.g. "l4:1");
+    # ``min_vram_gb`` is the GPU-resident VRAM floor for this placement;
+    # ``min_host_ram_gb`` is the host-RAM floor for tiered-offload (GGUF) models.
+    default_gpu: str | None = None
+    min_vram_gb: int | None = None
+    min_host_ram_gb: int | None = None
+
+    @property
+    def ref(self) -> str:
+        """The stable ``<id>:<variant>`` address of this row's model+variant."""
+        return f"{self.model_id}:{self.variant}"
+
+    @property
+    def name(self) -> str:
+        """The stable serve key ``<id>:<variant>@<gpu_spec>`` (per CONTRACT.md)."""
+        return f"{self.model_id}:{self.variant}@{self.gpu_spec}"
+
+    @property
+    def gpu_count(self) -> int:
+        """GPU count parsed from ``<kind>:<n>`` (e.g. ``b200:8`` -> 8)."""
+        _, _, count = self.gpu_spec.partition(":")
+        try:
+            return int(count)
+        except ValueError:
+            return 1
+
+    @property
+    def is_dev_testable(self) -> bool:
+        """Contract rule: 1-GPU, non-disagg placements are dev-testable."""
+        return self.gpu_count == 1 and not self.disagg
+
+
+def parse_row(raw: dict[str, Any]) -> CatalogRow:
+    """Build a :class:`CatalogRow` from one PostgREST JSON object.
+
+    Tolerant of extra columns (e.g. ``updated_at``) but strict about the
+    contract fields: a missing/invalid required field is a loud error so a
+    malformed catalog never silently produces a degraded serve.
+    """
+    if not isinstance(raw, dict):
+        raise UrunError("catalog row is not a JSON object")
+
+    def req_str(key: str) -> str:
+        value = raw.get(key)
+        if not isinstance(value, str) or not value:
+            raise UrunError(f"catalog row missing required string field {key!r}")
+        return value
+
+    files = raw.get("files")
+    if files is not None and not isinstance(files, list):
+        raise UrunError("catalog row 'files' must be a JSON array or null")
+    size_gb = raw.get("size_gb")
+    if not isinstance(size_gb, int) or isinstance(size_gb, bool):
+        raise UrunError("catalog row 'size_gb' must be an integer")
+    targets = raw.get("targets") or {}
+    engine_args = raw.get("engine_args") or {}
+    if not isinstance(targets, dict) or not isinstance(engine_args, dict):
+        raise UrunError("catalog row 'targets'/'engine_args' must be JSON objects")
+
+    # Additive placement floors: tolerant, NOT required (older catalogs lack them).
+    default_gpu_raw = raw.get("default_gpu")
+    default_gpu = default_gpu_raw if isinstance(default_gpu_raw, str) and default_gpu_raw else None
+
+    def opt_int(key: str) -> int | None:
+        value = raw.get(key)
+        return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+    return CatalogRow(
+        model_id=req_str("model_id"),
+        variant=req_str("variant"),
+        gpu_spec=req_str("gpu_spec"),
+        engine=req_str("engine"),
+        family=req_str("family"),
+        task=req_str("task"),
+        hf_repo=req_str("hf_repo"),
+        description=raw.get("description") if isinstance(raw.get("description"), str) else "",
+        size_gb=size_gb,
+        files=[str(f) for f in files] if files is not None else None,
+        disagg=bool(raw.get("disagg", False)),
+        targets=targets,
+        engine_args=engine_args,
+        default_gpu=default_gpu,
+        min_vram_gb=opt_int("min_vram_gb"),
+        min_host_ram_gb=opt_int("min_host_ram_gb"),
+    )
+
+
+def split_ref(ref: str) -> tuple[str, str | None]:
+    """Split ``<id>`` or ``<id>:<variant>`` into ``(model_id, variant|None)``.
+
+    Empty id or empty variant (a trailing/leading colon) is a loud error.
+    """
+    text = (ref or "").strip()
+    if not text:
+        raise UrunError("missing model id; expected <id> or <id>:<variant>")
+    model_id, sep, variant = text.partition(":")
+    model_id = model_id.strip()
+    if not model_id:
+        raise UrunError(f"invalid model reference {ref!r}: empty model id")
+    if not sep:
+        return model_id, None
+    variant = variant.strip()
+    if not variant:
+        raise UrunError(f"invalid model reference {ref!r}: empty variant after ':'")
+    if ":" in variant:
+        raise UrunError(f"invalid model reference {ref!r}: at most one ':' separator")
+    return model_id, variant
+
+
+def resolve_row(
+    rows: list[CatalogRow],
+    model_id: str,
+    variant: str | None,
+    gpu_spec: str | None,
+) -> CatalogRow:
+    """Resolve ``(model_id, variant?, gpu?)`` to exactly one catalog row.
+
+    Defaults (per CONTRACT.md): no variant -> the model's FIRST listed variant;
+    no ``--gpu`` -> that variant's FIRST listed placement. Unknown id, unknown
+    variant, or an unmatched ``--gpu`` each raise a clear, enumerated error.
+    """
+    for_model = [r for r in rows if r.model_id == model_id]
+    if not for_model:
+        known = ", ".join(sorted({r.model_id for r in rows})) or "(catalog is empty)"
+        raise UrunError(f"unknown model id {model_id!r}. Known models: {known}")
+
+    if variant is None:
+        # First listed variant — PostgREST returns rows already PK-ordered.
+        variant = for_model[0].variant
+    for_variant = [r for r in for_model if r.variant == variant]
+    if not for_variant:
+        known = ", ".join(sorted({r.variant for r in for_model}))
+        raise UrunError(
+            f"unknown variant {variant!r} for model {model_id!r}. Known variants: {known}"
+        )
+
+    if gpu_spec is None:
+        return for_variant[0]
+    for_gpu = [r for r in for_variant if r.gpu_spec == gpu_spec]
+    if not for_gpu:
+        known = ", ".join(sorted({r.gpu_spec for r in for_variant}))
+        raise UrunError(
+            f"no placement on GPU {gpu_spec!r} for {model_id}:{variant}. "
+            f"Available placements: {known}"
+        )
+    return for_gpu[0]
+
+
+def _host_ram_note(row: CatalogRow) -> str:
+    """Informational host-RAM NOTE for tiered-offload models, or "" if unknown.
+
+    The CLI cannot know the target node's RAM, so ``min_host_ram_gb`` is surfaced
+    as advice (especially for GGUF/llamacpp tiered-offload placements).
+    """
+    if not isinstance(row.min_host_ram_gb, int) or row.min_host_ram_gb <= 0:
+        return ""
+    return f" Note: needs >= {row.min_host_ram_gb}GB host RAM (tiered offload)."
+
+
+def validate_gpu_against_row(
+    rows: list[CatalogRow],
+    model_id: str,
+    variant: str | None,
+    requested_gpu: str,
+) -> tuple[str, str]:
+    """Validate a requested ``--gpu`` SKU against a variant's placement floors.
+
+    Returns ``(level, message)`` where ``level`` is ``"error" | "warn" | "ok"``:
+
+    * unknown SKU kind                                  -> error (lists known SKUs)
+    * available VRAM < known ``min_vram_gb``            -> error (numbers)
+    * clears floor but ``--gpu`` is NOT an enumerated
+      placement for the variant                         -> warn (untuned)
+    * ``--gpu`` IS an enumerated placement              -> ok (clean)
+
+    A known ``min_host_ram_gb`` is appended to the message as an informational
+    NOTE (the CLI can't know the node's RAM). Floors that are null fall back to
+    the placement-membership decision only.
+    """
+    # Resolve the variant (gpu_spec=None -> representative row); reuse resolve_row
+    # so unknown id/variant produce the same enumerated errors as the deploy path.
+    representative = resolve_row(rows, model_id, variant, None)
+    resolved_variant = representative.variant
+    for_variant = [r for r in rows if r.model_id == model_id and r.variant == resolved_variant]
+    enumerated = sorted({r.gpu_spec for r in for_variant})
+    ref = f"{model_id}:{resolved_variant}"
+
+    available = gpu_vram_gb(requested_gpu)
+    if available is None:
+        kind, _ = parse_gpu_spec(requested_gpu)
+        known = ", ".join(sorted(GPU_VRAM_GB))
+        return (
+            "error",
+            f"unknown GPU SKU {kind!r} in {requested_gpu!r}. Known SKUs: {known}.",
+        )
+
+    # The matching placement (exact --gpu) drives the floor; otherwise use the
+    # variant's minimum (representative) min_vram_gb across its placements.
+    exact = next((r for r in for_variant if r.gpu_spec == requested_gpu), None)
+    floor_row = exact
+    if floor_row is None or floor_row.min_vram_gb is None:
+        with_floor = [r for r in for_variant if isinstance(r.min_vram_gb, int)]
+        if with_floor:
+            floor_row = min(with_floor, key=lambda r: r.min_vram_gb)  # type: ignore[arg-type,return-value]
+    min_vram = floor_row.min_vram_gb if floor_row is not None else None
+    host_note = _host_ram_note(exact or representative)
+
+    if isinstance(min_vram, int) and available < min_vram:
+        return (
+            "error",
+            f"{requested_gpu} provides {available}GB VRAM but {ref} needs "
+            f">= {min_vram}GB (min_vram_gb). Choose a larger GPU.{host_note}",
+        )
+
+    if exact is not None:
+        # Enumerated, tuned placement that clears (or has no) floor -> clean.
+        return ("ok", f"{requested_gpu} is a tuned placement for {ref}.{host_note}")
+
+    # Not enumerated, but clears the floor (or no floor known) -> untuned warn.
+    floor_clause = f"clears the {min_vram}GB floor but " if isinstance(min_vram, int) else ""
+    return (
+        "warn",
+        f"{requested_gpu} ({available}GB) {floor_clause}is not a tuned placement "
+        f"for {ref} (enumerated: {', '.join(enumerated)}). Proceeding untuned.{host_note}",
+    )
+
+
+def valid_skus_for_row(row: CatalogRow) -> list[str]:
+    """Single-device SKUs from :data:`GPU_VRAM_GB` that clear ``row.min_vram_gb``.
+
+    Reuses the SAME VRAM-floor logic as :func:`validate_gpu_against_row`: a SKU is
+    "valid on" this placement when one device's VRAM (``GPU_VRAM_GB[kind] * 1``)
+    is at least ``min_vram_gb``. With no known floor, every SKU is considered
+    valid (the placement imposes no VRAM constraint we can check). Returned as a
+    sorted ``<kind>:1`` list — the per-device floor a single card must clear.
+    """
+    floor = row.min_vram_gb
+    if not isinstance(floor, int) or floor <= 0:
+        return [f"{kind}:1" for kind in sorted(GPU_VRAM_GB)]
+    return [f"{kind}:1" for kind, vram in sorted(GPU_VRAM_GB.items()) if vram >= floor]
+
+
+class CatalogClient:
+    """Reads ``public.model_catalog`` over PostgREST.
+
+    ``base_url`` is the PostgREST base (``.../rest/v1``); ``anon_key`` is the
+    public Supabase anon key sent as the ``apikey`` header (the table grants
+    SELECT to ``anon``). Both are resolved by the CLI's single canonical path
+    (see :func:`urun.serve.resolve_catalog_client`).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        anon_key: str,
+        timeout: float = 30.0,
+        backoff: BackoffPolicy = DEPLOY_BACKOFF,
+        on_retry: Callable[[str], None] | None = None,
+    ):
+        require_safe_url(base_url, "catalog URL")
+        if not anon_key:
+            raise UrunError("missing catalog anon key")
+        self.base_url = base_url.rstrip("/")
+        self.anon_key = anon_key
+        self.timeout = timeout
+        self.backoff = backoff
+        self.on_retry = on_retry
+
+    def select_rows(self) -> list[CatalogRow]:
+        """Select the full catalog, PK-ordered, as :class:`CatalogRow` objects.
+
+        Raises a clear, actionable error when the table is not seeded yet (it
+        ships via a urun-infra migration) instead of a raw PostgREST 404.
+        """
+        params = urllib.parse.urlencode(
+            {"select": "*", "order": "model_id,variant,gpu_spec"}, safe=",:"
+        )
+        payload = self._get(f"/{CATALOG_TABLE}?{params}")
+        if not isinstance(payload, list):
+            raise UrunError("catalog response was not a JSON array")
+        return [parse_row(item) for item in payload]
+
+    def _get(self, path: str) -> Any:
+        def attempt() -> bytes:
+            req = urllib.request.Request(
+                self.base_url + path,
+                method="GET",
+                headers={
+                    "apikey": self.anon_key,
+                    "Authorization": f"Bearer {self.anon_key}",
+                    "Accept": "application/json",
+                    "User-Agent": f"urun-cli/{__version__}",
+                },
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                    return resp.read()
+            except urllib.error.HTTPError as exc:
+                raise _catalog_http_error(exc) from exc
+
+        try:
+            raw = retry_call(
+                attempt,
+                policy=self.backoff,
+                on_retry=self.on_retry,
+                description=f"GET {path}",
+            )
+        except (urllib.error.URLError, TimeoutError) as exc:
+            reason = getattr(exc, "reason", exc)
+            raise UrunError(f"network error reading catalog: {reason}") from exc
+
+        if not raw:
+            return []
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except json.JSONDecodeError as exc:
+            raise UrunError("invalid JSON response from catalog API") from exc
+
+
+# PostgREST raises 404 with code PGRST205 ("could not find the table ...") when
+# the relation is absent — i.e. the seed migration has not shipped to this
+# control plane yet. Translate it to a clear, actionable message.
+_UNSEEDED_MESSAGE = (
+    "the model catalog is not available on this control plane yet "
+    "(public.model_catalog is unseeded). It ships via a urun-infra migration; "
+    "try again once the catalog has been published."
+)
+
+
+def _catalog_http_error(exc: urllib.error.HTTPError) -> UrunError:
+    payload = exc.read()
+    code = "http_error"
+    message = payload.decode("utf-8", "replace") or exc.reason
+    try:
+        parsed = json.loads(payload.decode("utf-8"))
+        if isinstance(parsed, dict):
+            code = parsed.get("code") or code
+            message = parsed.get("message") or message
+    except Exception:
+        pass
+    # PGRST205 = missing relation; a bare 404 on the table path means the same.
+    if exc.code == 404 or (isinstance(code, str) and code == "PGRST205"):
+        return UrunError(_UNSEEDED_MESSAGE)
+    return ApiError(exc.code, str(code), str(message))