freesolo-flash-dev 0.2.28__tar.gz → 0.2.29__tar.gz

{freesolo_flash_dev-0.2.28 → freesolo_flash_dev-0.2.29}/Dockerfile.worker

@@ -25,9 +25,22 @@ ENV DEBIAN_FRONTEND=noninteractive \
 # JIT on a cold worker writes here too. These ENVs are always set (cheap); whether the dir is
 # pre-populated is what the opt-in bake controls. engine.worker._load_kernel_cache_if_present reads
 # /opt/flash/kernelcache at boot.
+# FLASHINFER_CUBIN_DIR / FLASHINFER_CACHE_DIR / FLASHINFER_WORKSPACE_BASE: FlashInfer's attention-backend
+# cubins (the Blackwell sm120 / B200 rollout attention backend) are NOT bundled in the wheel — flashinfer
+# downloads them from NVIDIA Artifactory on first use. Bake the cubin store + JIT cache into the same
+# persistent kernelcache tree so
+# a baked/volume cache serves them and a cold worker never re-fetches from Artifactory (kernel_warmup
+# also sets these). FLASHINFER_WORKSPACE_BASE is the var flashinfer 0.6.x actually reads to relocate the
+# JIT host-wrapper cache (FLASHINFER_CACHE_DIR is a DERIVED constant there, not an env knob), so set it
+# too — otherwise a B200 path that touches flashinfer before kernel_warmup runs lands the wrapper under
+# the default home workspace and re-JITs instead of using the baked cache.
 ENV TRITON_CACHE_DIR=/opt/flash/kernelcache/triton \
-    TORCHINDUCTOR_CACHE_DIR=/opt/flash/kernelcache/inductor
-RUN mkdir -p /opt/flash/kernelcache/triton /opt/flash/kernelcache/inductor
+    TORCHINDUCTOR_CACHE_DIR=/opt/flash/kernelcache/inductor \
+    FLASHINFER_CUBIN_DIR=/opt/flash/kernelcache/flashinfer_cubin \
+    FLASHINFER_CACHE_DIR=/opt/flash/kernelcache/flashinfer \
+    FLASHINFER_WORKSPACE_BASE=/opt/flash/kernelcache/flashinfer
+RUN mkdir -p /opt/flash/kernelcache/triton /opt/flash/kernelcache/inductor \
+    /opt/flash/kernelcache/flashinfer_cubin /opt/flash/kernelcache/flashinfer
 
 # build-essential for Triton/Inductor (Liger) + any source builds; git for pip VCS installs.
 RUN apt-get update && apt-get install -y --no-install-recommends build-essential git curl \
@@ -39,6 +52,7 @@ RUN pip install --no-cache-dir \
     "trl>=1.6,<1.7" \
     "peft>=0.19" \
     "vllm==0.19.1" \
+    "flashinfer-python==0.6.6" \
     "bitsandbytes>=0.49" \
     "datasets>=4.7,<6" \
     "huggingface_hub>=0.25" \
@@ -187,10 +201,12 @@ fa_ok = False; \
 exec('try:\n import flash_attn\n fa_ok = True\nexcept Exception:\n fa_ok = False'); \
 fa3_ok = False; \
 exec('try:\n import flash_attn_interface\n fa3_ok = True\nexcept Exception:\n fa3_ok = False'); \
+fi_ok = False; \
+exec('try:\n import flashinfer\n fi_ok = True\nexcept Exception:\n fi_ok = False'); \
 cudnn = torch.backends.cudnn.version(); assert cudnn, 'cuDNN not compiled into torch'; \
 ver = lambda n: M.version(n); \
-print('worker stack OK | torch', torch.__version__, '| cudnn', cudnn, '| triton', triton.__version__, '| flash_attn', 'present' if fa_ok else 'ABSENT (SDPA fallback)', '| flash_attn_3', 'present (Hopper FA3)' if fa3_ok else 'ABSENT (SDPA on Hopper)'); \
-[print('  ', d, ver(d)) for d in ['transformers','trl','peft','vllm','datasets','huggingface-hub', \
+print('worker stack OK | torch', torch.__version__, '| cudnn', cudnn, '| triton', triton.__version__, '| flash_attn', 'present' if fa_ok else 'ABSENT (SDPA fallback)', '| flash_attn_3', 'present (Hopper FA3)' if fa3_ok else 'ABSENT (SDPA on Hopper)', '| flashinfer', 'present (B200 MoE/attn)' if fi_ok else 'ABSENT (Triton fused-MoE fallback)'); \
+[print('  ', d, ver(d)) for d in ['transformers','trl','peft','vllm','flashinfer-python','datasets','huggingface-hub', \
 'accelerate','wandb','liger-kernel','flash-linear-attention','bitsandbytes', \
 'hf-transfer','freesolo','runpod']]"
 

{freesolo_flash_dev-0.2.28 → freesolo_flash_dev-0.2.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 0.2.28
+Version: 0.2.29
 Summary: Flash — managed LoRA post-training (SFT/GRPO) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

freesolo_flash_dev-0.2.29/flash/__init__.py

@@ -0,0 +1,13 @@
+"""Flash — managed LoRA post-training: log in with your freesolo key, train."""
+
+from importlib.metadata import version as _dist_version
+
+from flash._channel import DIST_NAME as _DIST_NAME
+
+__all__ = ["__version__"]
+
+# Read from dist metadata so version literal doesn't drift from pyproject (caused a nag loop in 0.2.20).
+try:
+    __version__ = _dist_version(_DIST_NAME)
+except Exception:
+    __version__ = "0+unknown"

freesolo_flash_dev-0.2.29/flash/_channel.py

@@ -0,0 +1,11 @@
+"""Single switch between prod and dev channels; ``scripts/build_dev_dist.py`` rewrites CHANNEL to "dev"."""
+
+from __future__ import annotations
+
+CHANNEL = "dev"
+
+# Must stay in lockstep with [project.scripts] in pyproject.toml.
+CLI_NAME = "flash-dev" if CHANNEL == "dev" else "flash"
+
+# Must stay in lockstep with [project].name in pyproject.toml.
+DIST_NAME = "freesolo-flash-dev" if CHANNEL == "dev" else "freesolo-flash"

{freesolo_flash_dev-0.2.28 → freesolo_flash_dev-0.2.29}/flash/_fileio.py

@@ -9,21 +9,16 @@ from pathlib import Path
 
 
 def read_json_or_empty(path: Path) -> dict:
-    """Parse a JSON object file, returning ``{}`` if it's missing or unreadable."""
+    """Parse a JSON object file, returning ``{}`` on any error or if the root is not a dict."""
     try:
-        return json.loads(path.read_text())
+        data = json.loads(path.read_text())
     except (OSError, ValueError):
         return {}
+    return data if isinstance(data, dict) else {}
 
 
 def secure_json_write(path: Path, data: dict) -> None:
-    """Write ``data`` as JSON with private permissions (the file may hold a secret).
-
-    Creates the parent dir (0700) and opens the file 0600 from the start — never
-    write_text + chmod, which leaves it umask-readable in between. ``O_NOFOLLOW``
-    (where available) refuses to follow a symlink planted at ``path`` so the write
-    can't be redirected to clobber an arbitrary file.
-    """
+    """Write ``data`` as JSON 0600. Opens with O_CREAT|0o600 — never write_text+chmod (TOCTOU). O_NOFOLLOW blocks symlink redirect."""
     path.parent.mkdir(parents=True, exist_ok=True)
     with contextlib.suppress(OSError):
         os.chmod(path.parent, 0o700)

{freesolo_flash_dev-0.2.28 → freesolo_flash_dev-0.2.29}/flash/_logging.py

@@ -1,10 +1,4 @@
-"""Package logging helpers.
-
-Library code logs through the ``flash`` logger and never configures handlers on import (it
-attaches a :class:`logging.NullHandler`), so importing Flash stays silent for downstream
-applications. The CLI calls :func:`configure_logging` to attach a console handler whose
-level is controlled by ``-v/--verbose``.
-"""
+"""Package logging helpers."""
 
 from __future__ import annotations
 
@@ -12,8 +6,7 @@ import logging
 
 _ROOT_NAME = "flash"
 
-# Attach a NullHandler once so "No handlers could be found" warnings never appear and
-# importing the library produces no output unless the app opts in.
+# NullHandler: keep library import silent; app opts in via configure_logging.
 _root = logging.getLogger(_ROOT_NAME)
 if not any(isinstance(h, logging.NullHandler) for h in _root.handlers):
     _root.addHandler(logging.NullHandler())
@@ -29,20 +22,15 @@ def get_logger(name: str | None = None) -> logging.Logger:
 
 
 def configure_logging(verbosity: int = 0, level: int | None = None) -> None:
-    """Attach a console handler to the ``flash`` logger and set its level.
-
-    ``verbosity`` maps repeated ``-v`` flags to levels (0=WARNING, 1=INFO, >=2=DEBUG).
-    An explicit ``level`` overrides the verbosity mapping.
-    """
+    """Attach a console handler to the ``flash`` logger and set its level."""
     if level is None:
         level = {0: logging.WARNING, 1: logging.INFO}.get(verbosity, logging.DEBUG)
 
     logger = logging.getLogger(_ROOT_NAME)
     logger.setLevel(level)
-    # Replace any prior console handler we installed so repeated calls don't stack handlers.
     for h in [h for h in logger.handlers if getattr(h, "_flash_console", False)]:
         logger.removeHandler(h)
-    handler = logging.StreamHandler()  # stderr
+    handler = logging.StreamHandler()
     handler.setLevel(level)
     handler.setFormatter(logging.Formatter("%(levelname)s %(name)s: %(message)s"))
     handler._flash_console = True  # type: ignore[attr-defined]

{freesolo_flash_dev-0.2.28 → freesolo_flash_dev-0.2.29}/flash/_update_check.py

@@ -1,23 +1,4 @@
-"""Background "a new release is available" notice for the `flash` CLI.
-
-The client CLI is pure standard library (no extra deps), so this is too: it queries PyPI
-with ``urllib`` and compares the published version against the installed ``__version__``.
-
-Design constraints that keep it from ever getting in the way:
-
-- **Stays out of the way.** The PyPI lookup runs in a daemon thread (so it overlaps the
-  command) and every failure (offline, timeout, bad JSON) is swallowed. Only the once-a-day
-  refresh waits briefly for that thread; every other command builds the notice from cache with
-  zero network I/O.
-- **Cached once per day.** The latest version is stored in ``~/.flash/update_check.json``;
-  we only hit PyPI when that cache is older than :data:`_CHECK_INTERVAL_S`. The check time is
-  stamped synchronously before the lookup so the daily back-off holds even if the worker thread
-  is killed at process exit before it records a result.
-- **stderr only, TTY only.** The notice prints to stderr (never stdout), so it can't corrupt
-  JSON piped to ``jq`` or captured output, and it's suppressed entirely when stderr isn't a
-  terminal (pipes, redirects, CI, tests). Color is dropped when ``NO_COLOR`` is set.
-- **Opt-out.** Set ``FLASH_NO_UPDATE_CHECK=1`` to disable the check and notice completely.
-"""
+"""Background "a new release is available" notice for the `flash` CLI."""
 
 from __future__ import annotations
 
@@ -39,32 +20,23 @@ from flash.client.config import CONFIG_DIR
 
 logger = get_logger("flash.update_check")
 
-# The PyPI distribution name (== pyproject `name`) and the command that upgrades it. Follows the
-# installed channel (freesolo-flash, or freesolo-flash-dev for the dev build) — see flash/_channel.py.
 PACKAGE_NAME = DIST_NAME
 UPGRADE_COMMAND = f"uv tool upgrade {PACKAGE_NAME}"
 _PYPI_JSON_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
 
 CACHE_PATH = CONFIG_DIR / "update_check.json"
 
-# Re-check PyPI at most once a day; the notice itself is shown on every command from cache.
 _CHECK_INTERVAL_S = 24 * 60 * 60
-# How long the lookup may take, and how long the once-a-day refresh waits for it at the end of a
-# command. Keep the join >= the fetch timeout so the worker thread finishes (and records its
-# result) within the wait instead of being killed at process exit mid-write.
+# join >= fetch timeout so the worker finishes writing before process exit kills it.
 _FETCH_TIMEOUT_S = 1.5
 _JOIN_TIMEOUT_S = 2.0
 
 _OPT_OUT_ENV = "FLASH_NO_UPDATE_CHECK"
 
-# A PEP 440 version only uses this charset. We reject anything else (control chars, ANSI escape
-# sequences, newlines) before printing the value to a terminal, so a poisoned cache or a hostile
-# response can't inject escape codes into the notice. The length bound is just a sanity cap.
+# Reject anything outside the PEP 440 charset before printing — prevents escape-code injection.
 _SAFE_VERSION = re.compile(r"\A[A-Za-z0-9][A-Za-z0-9.+!_-]{0,63}\Z")
 
-# A coarse subset of the PEP 440 grammar: the numeric release plus optional pre/post/dev markers.
-# Enough to order the simple versions this package ships and to spot pre-releases; this is not a
-# full PEP 440 implementation (the stdlib-only client can't depend on `packaging`).
+# Coarse PEP 440 subset; stdlib-only client can't depend on `packaging`.
 _VERSION_RE = re.compile(
     r"""\A\s*v?
         (?P<release>\d+(?:\.\d+)*)
@@ -77,14 +49,12 @@ _VERSION_RE = re.compile(
 
 
 def _enabled() -> bool:
-    """The whole feature is off unless stderr is a TTY and the user hasn't opted out."""
+    """Off unless stderr is a TTY and the user hasn't opted out."""
     if os.environ.get(_OPT_OUT_ENV):
         return False
     try:
         return bool(sys.stderr.isatty())
     except Exception:
-        # stderr may be detached/closed/replaced (e.g. some embedded contexts); any failure
-        # here is treated as "not a TTY" so the check can never crash a command.
         return False
 
 
@@ -97,13 +67,7 @@ def _normalize_release(release: tuple[int, ...]) -> tuple[int, ...]:
 
 
 def _version_key(version: str) -> tuple[tuple[int, ...], int, int]:
-    """A coarse PEP 440 sort key ``(release, final_rank, post)`` where higher means newer.
-
-    The release segment is normalized (``1.0 == 1.0.0``). A pre-release/dev version ranks below
-    the final release of the same number (``final_rank`` 0 vs 1); a post-release ranks above it
-    via ``post``. Epochs and local versions are ignored — the catalog ships only simple versions.
-    Returns an empty release for unparseable input, which compares as "older than everything".
-    """
+    """Sort key ``(release, final_rank, post)`` where higher means newer."""
     match = _VERSION_RE.match(version or "")
     if not match:
         return ((), 1, 0)
@@ -127,19 +91,12 @@ def _is_newer(latest: str, current: str) -> bool:
 
 
 def _clean_version(value: object) -> str | None:
-    """Return ``value`` only if it's a safe, escape-free version string, else ``None``.
-
-    Guards both the PyPI response and the on-disk cache: ``_version_key`` parses just the
-    numeric/marker prefix, so without this an injected suffix (ANSI codes, newlines) could reach
-    the terminal. Non-strings (and anything outside the PEP 440 charset) are rejected.
-    """
+    """Return ``value`` if it's a safe version string, else ``None``."""
     return value if isinstance(value, str) and _SAFE_VERSION.match(value) else None
 
 
 def _read_cache() -> dict:
-    # read_json_or_empty returns whatever the file parses to; a non-object (e.g. ``[]``) would
-    # make the ``.get()`` callers raise, and _check_due runs before main()'s error handling — so
-    # coerce anything that isn't a dict back to an empty one.
+    # Coerce non-dict results (e.g. []) since _check_due runs before main()'s error handling.
     cache = read_json_or_empty(CACHE_PATH)
     return cache if isinstance(cache, dict) else {}
 
@@ -168,21 +125,13 @@ def _fetch_latest_version(timeout: float = _FETCH_TIMEOUT_S) -> str | None:
     except (urllib.error.URLError, OSError, ValueError, TimeoutError) as exc:
         logger.debug("update check: PyPI lookup failed: %s", exc)
         return None
-    # Expected shape is {"info": {"version": ...}}; tolerate anything else (a proxy error page,
-    # ``[]``, ``{"info": null}``, ...) instead of letting a dereference raise into the caller.
     info = payload.get("info") if isinstance(payload, dict) else None
     version = info.get("version") if isinstance(info, dict) else None
     return _clean_version(version)
 
 
 def _stamp_check_time() -> None:
-    """Record "checked just now" (keeping any cached version), synchronously and best-effort.
-
-    Done before the background lookup starts so the daily back-off holds even if the daemon worker
-    is killed at process exit before it records its own result — otherwise a stale/missing cache
-    would make every command re-run (and wait on) the lookup. Never raises (runs before main()'s
-    error handling).
-    """
+    """Record "checked just now" synchronously so the daily back-off holds even if the daemon is killed."""
     with contextlib.suppress(Exception):
         cache = _read_cache()
         cache["checked_at"] = time.time()
@@ -190,11 +139,7 @@ def _stamp_check_time() -> None:
 
 
 def _refresh_cache() -> None:
-    """Fetch from PyPI and persist the version on success; runs in a daemon thread, never raises.
-
-    The attempt time is already stamped by :func:`_stamp_check_time`, so a failed lookup just
-    returns and lets the daily back-off (set there) stand.
-    """
+    """Fetch from PyPI and persist the version; runs in a daemon thread, never raises."""
     try:
         latest = _fetch_latest_version()
         if not latest:
@@ -203,7 +148,7 @@ def _refresh_cache() -> None:
         cache["checked_at"] = time.time()
         cache["pypi_version"] = latest
         secure_json_write(CACHE_PATH, cache)
-    except Exception as exc:  # truly never let a background thread escape
+    except Exception as exc:
         logger.debug("update check: refresh failed: %s", exc)
 
 
@@ -218,7 +163,6 @@ def _red(text: str) -> str:
 def _build_notice() -> str | None:
     """Build the upgrade notice from the cached PyPI version, or ``None`` if up to date."""
     latest = _clean_version(_read_cache().get("pypi_version"))
-    # Only nudge toward stable releases: never advertise a pre-release (rc/dev) as an upgrade.
     if not latest or _is_prerelease(latest) or not _is_newer(latest, __version__):
         return None
     return _red(
@@ -228,38 +172,26 @@ def _build_notice() -> str | None:
 
 
 def maybe_start_update_check() -> threading.Thread | None:
-    """Kick off a background PyPI refresh if one is due. Returns the thread (or ``None``).
-
-    Pass the return value to :func:`emit_update_notice`. No-ops (returns ``None``) when the
-    feature is disabled or the cached check is still fresh, so the common path is free.
-    """
+    """Kick off a background PyPI refresh if one is due; returns the thread (or ``None``)."""
     if not _enabled() or not _check_due(time.time()):
         return None
-    # Stamp the attempt synchronously before spawning the worker, so the daily back-off holds even
-    # if the daemon is killed at process exit before it writes (see _stamp_check_time).
     _stamp_check_time()
     thread = threading.Thread(target=_refresh_cache, name="flash-update-check", daemon=True)
     try:
         thread.start()
     except RuntimeError:
-        # can't spawn a thread (e.g. interpreter shutting down) — skip the check silently.
         return None
     return thread
 
 
 def emit_update_notice(notifier: threading.Thread | None = None) -> None:
-    """Print the upgrade notice (if any) to stderr at the end of a command.
-
-    Briefly waits for an in-flight refresh so a freshly fetched version can be shown the same
-    run; if it doesn't finish in time we just use whatever is already cached.
-    """
+    """Print the upgrade notice (if any) to stderr at the end of a command."""
     if not _enabled():
         return
     if notifier is not None:
         with contextlib.suppress(RuntimeError):
             notifier.join(timeout=_JOIN_TIMEOUT_S)
-    # This runs from main()'s finally block, so it must never raise: a broken pipe
-    # (`flash ... | head`), full disk, or closed stderr would otherwise crash the command.
+    # Must never raise: broken pipe or closed stderr would crash the command.
     with contextlib.suppress(Exception):
         notice = _build_notice()
         if notice:

freesolo_flash_dev-0.2.29/flash/catalog.py

@@ -0,0 +1,264 @@
+"""Curated model catalog for one-consumer-GPU LoRA jobs."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass
+from typing import Any
+
+ALGORITHMS = ("sft", "grpo")
+
+
+def normalize_algorithm(value: str) -> str:
+    """Canonical (lowercased, validated) algorithm name."""
+    if not value:
+        value = "grpo"
+    elif not isinstance(value, str):
+        # A truthy non-string (e.g. a JSON number/bool/array) would AttributeError on .lower(), which
+        # escapes the callers' ValueError/ConfigError guards -> uncaught 500. Raise ValueError instead.
+        raise ValueError(f"algorithm must be a string, got {type(value).__name__}")
+    value = value.lower()
+    if value not in ALGORITHMS:
+        raise ValueError(f"unsupported algorithm: {value}; known: {', '.join(ALGORITHMS)}")
+    return value
+
+
+DEFAULT_GPU = "RTX 5090"
+
+# Over-estimating is memory-safe (larger VRAM estimate, smaller cap); fallback = largest catalog vocab.
+_DEFAULT_VOCAB_SIZE = 248_320
+
+
+@dataclass(frozen=True)
+class ModelInfo:
+    id: str
+    display_name: str
+    params: str
+    algos: tuple[str, ...]
+    min_vram_gb: int
+    # Total parameters in billions — the numeric model size the cost estimator + VRAM equations read
+    # DIRECTLY (no parsing of the ``params`` display string). Drives the memory/size terms (VRAM, disk,
+    # download), which always size the FULL checkpoint. REQUIRED: every ModelInfo must state it — a
+    # curated catalog model sets its true count, and the open-model policy passes the HF/estimated count
+    # (or 0.0 when the size is genuinely "unknown size"). ``test_every_catalog_entry_sets_params_b``
+    # asserts every curated MODELS entry sets it > 0, so a new entry can never silently fall back to a
+    # parsed string again.
+    params_b: float
+    quant: str = "bf16"
+    recommended_gpu: str = DEFAULT_GPU
+    # 0 => GRPO uses min_vram_gb like SFT; set when colocated vLLM rollout needs a bigger card.
+    grpo_min_vram_gb: int = 0
+    # 0 => SFT sizes from param-based estimate; set only when a model must not down-route to the cheapest card.
+    sft_min_vram_gb: int = 0
+    # vLLM sleep mode (offload the colocate rollout engine between GRPO steps) is NON-FUNCTIONAL for
+    # this model: the wake/reload HANGS the rollout (a ~70 GB weight reallocation can't be placed in
+    # the fragmented non-expandable allocator sleep forces -- live-confirmed on the 35B-A3B, every
+    # attempt stalled). So this model is RESIDENT-ONLY: a config that doesn't fit resident must be
+    # REJECTED (model_required_vram_gb sizes it on the resident peak) rather than routed to the hanging
+    # sleep path. grpo_sleep_mode raises for it instead of ever returning True. Dense/small models that
+    # sleep cleanly leave this False.
+    sleep_unsupported: bool = False
+    notes: str = ""
+    # 0 = platform default (64 GB) suffices. Runner raises gpu.disk_gb to at least this.
+    min_disk_gb: int = 0
+    # "none" / "hybrid" (Qwen3-style) / "always" (can't disable) / "unknown" (open-model policy)
+    thinking: str = "none"
+    vocab_size: int = _DEFAULT_VOCAB_SIZE
+    # Parameters ACTIVE per token in billions — only meaningful for an MoE, where a token routes
+    # through a small subset of experts. The cost estimator's per-token FLOPs/step-time term reads
+    # this (a token exercises only the active params), while VRAM/disk/download keep using the total
+    # ``params_b``. 0.0 (the dense default) means "same as params_b" — every token hits every param.
+    active_params_b: float = 0.0
+    # Transformer geometry (decoder layers x hidden width) — the SFT gradient-checkpointing-OFF gate
+    # sizes the no-recompute activation peak from these (engine.vram.sft_gc_off_peak_gb). 0/0 (the
+    # default) means "unknown": the worker falls back to reading the HF config at runtime, and the
+    # GC-off gate stays conservative (keeps GC on) if neither is available. Curated for the MoE whose
+    # SFT runs the gate — a live B200 SFT showed the runtime AutoConfig probe returning (0, 0) on the
+    # multimodal-nested config, so the curated values are what actually engage the gate.
+    num_layers: int = 0
+    hidden_size: int = 0
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+DEFAULT_MODEL = "Qwen/Qwen3.5-4B"
+
+MODELS: dict[str, ModelInfo] = {
+    "openbmb/MiniCPM5-1B": ModelInfo(
+        id="openbmb/MiniCPM5-1B",
+        display_name="MiniCPM5 1B",
+        params="1.2B dense (Llama arch)",
+        params_b=1.2,
+        vocab_size=130_560,
+        algos=("sft", "grpo"),
+        min_vram_gb=12,
+        recommended_gpu="RTX 4090",
+        thinking="hybrid",
+        notes="On-device class SLM (131k ctx); standard Llama architecture.",
+    ),
+    "Qwen/Qwen3.5-0.8B": ModelInfo(
+        id="Qwen/Qwen3.5-0.8B",
+        display_name="Qwen3.5 0.8B",
+        params="0.9B (text-only fine-tune)",
+        params_b=0.9,
+        vocab_size=248_320,
+        algos=("sft", "grpo"),
+        min_vram_gb=12,
+        recommended_gpu="RTX 4090",
+        thinking="hybrid",
+        notes="Smallest Qwen3.5; cheap smoke/dev runs with the modern arch.",
+    ),
+    "Qwen/Qwen3.5-2B": ModelInfo(
+        id="Qwen/Qwen3.5-2B",
+        display_name="Qwen3.5 2B",
+        params="2.3B (text-only fine-tune)",
+        params_b=2.3,
+        vocab_size=248_320,
+        algos=("sft", "grpo"),
+        min_vram_gb=16,
+        recommended_gpu="RTX 4090",
+        thinking="hybrid",
+    ),
+    "Qwen/Qwen3.5-4B": ModelInfo(
+        id="Qwen/Qwen3.5-4B",
+        display_name="Qwen3.5 4B",
+        params="4.7B (text-only fine-tune)",
+        params_b=4.7,
+        vocab_size=248_320,
+        algos=("sft", "grpo"),
+        min_vram_gb=32,
+        recommended_gpu="RTX 5090",
+        thinking="hybrid",
+        notes="Current-gen 4B. GRPO uses the sleep-mode memory recipe (hybrid arch needs "
+        "extra engine state-cache); fused DeltaNet kernels ship in the default stack.",
+    ),
+    "Qwen/Qwen3.5-9B": ModelInfo(
+        id="Qwen/Qwen3.5-9B",
+        display_name="Qwen3.5 9B",
+        params="9.7B (text-only fine-tune)",
+        params_b=9.7,
+        vocab_size=248_320,
+        algos=("sft", "grpo"),
+        min_vram_gb=48,
+        # NOT QLoRA: peft bnb merge during GRPO rollout diverges trainer precision -> TRL ratio collapses to 0.
+        grpo_min_vram_gb=80,
+        quant="bf16",
+        recommended_gpu="A100 PCIe",
+        thinking="hybrid",
+        notes="bf16 LoRA. ~19 GB of weights; SFT fits a 48 GB card, while colocated GRPO "
+        "(two bf16 copies + KV + the 248k-vocab fp32 logits) needs an 80 GB-class card "
+        "(grpo_min_vram_gb floor).",
+    ),
+    "Qwen/Qwen3.6-35B-A3B": ModelInfo(
+        id="Qwen/Qwen3.6-35B-A3B",
+        display_name="Qwen3.6 35B-A3B (MoE)",
+        params="35B total / ~3B active (MoE)",
+        # 35.0 not 35.95: the marketing figure tips the SFT equation over the B200 budget (see test_sft_equation_covers_honest_peak_across_seq_boundary).
+        params_b=35.0,
+        active_params_b=3.0,
+        # Geometry for the SFT GC-off activation estimate (config.json text_config): 40 decoder
+        # layers x 2048 hidden (hybrid GatedDeltaNet + full-attention, 256 experts / 8 active).
+        num_layers=40,
+        hidden_size=2048,
+        vocab_size=248_320,
+        algos=("sft", "grpo"),
+        min_vram_gb=141,
+        # Floor to 100 GB so SFT lands on H200, not the thin-margin consumer Blackwell or 80 GB H100.
+        sft_min_vram_gb=100,
+        # Floor also engages grpo_seq_escalation_gb: long (>16k) rollouts are rejected at parse time instead of OOMing in vLLM.
+        grpo_min_vram_gb=180,
+        # vLLM sleep mode HANGS the 35B colocate rollout (wake/reload stalls — live-confirmed, every
+        # attempt). So GRPO is RESIDENT-ONLY: model_required_vram_gb sizes on the resident peak and a
+        # config too long to fit resident is REJECTED at parse time (not routed to the hanging sleep).
+        sleep_unsupported=True,
+        quant="bf16",
+        recommended_gpu="H200",
+        thinking="hybrid",
+        min_disk_gb=200,
+        notes="MoE (35B total / ~3B active), bf16 LoRA. SFT runs on the 141 GB H200 (the ~70 GB "
+        "weights dominate; active-3B compute keeps activations/KV tiny, so context is ~unbounded by "
+        "VRAM); colocated GRPO needs the 180 GB B200 (trainer + vLLM rollout = two 70 GB copies).",
+    ),
+}
+
+
+def list_models() -> list[ModelInfo]:
+    return sorted(MODELS.values(), key=lambda m: (m.min_vram_gb, m.id))
+
+
+def get_model(model_id: str) -> ModelInfo:
+    try:
+        return MODELS[model_id]
+    except KeyError as exc:
+        allowed = ", ".join(MODELS)
+        raise ValueError(
+            f"unsupported model {model_id!r}; choose one of: {allowed} — or set "
+            f'model_policy = "allow" in the config to run any HF model that fits the GPU '
+            f"(open-model policy)"
+        ) from exc
+
+
+def vocab_size_for(model_id: str) -> int:
+    """Curated vocab_size for a model, or the safe default for open-model-policy entries."""
+    info = MODELS.get(model_id)
+    return info.vocab_size if info is not None else _DEFAULT_VOCAB_SIZE
+
+
+def resolve_model(
+    model_id: str,
+    algorithm: str,
+    policy: str = "catalog",
+    gpu: str | None = None,
+) -> ModelInfo:
+    """Resolve a model under the configured policy; "allow" accepts any HF model."""
+    algo = normalize_algorithm(algorithm)
+    if model_id in MODELS:
+        return validate_model_for_algorithm(model_id, algo)
+    if policy != "allow":
+        return get_model(model_id)
+    return _resolve_open_model(model_id, algo, gpu)
+
+
+def _resolve_open_model(model_id: str, algo: str, gpu: str | None) -> ModelInfo:
+    """Synthesize a ModelInfo for the open-model "allow" policy via a coarse HF VRAM-fit estimate."""
+    from flash.engine.vram import check_fit
+
+    est = check_fit(model_id, algo, gpu or DEFAULT_GPU)
+    if est.verdict == "too_big":
+        raise ValueError(
+            f"{model_id} does not fit the requested GPU: {est.describe()}. "
+            f"Pick a smaller model or a larger supported GPU."
+        )
+    if est.verdict in ("tight", "unknown"):
+        print(f"warning: open-model policy: {est.describe()}")
+    params = f"{est.params_b:.1f}B" if est.params_b else "unknown size"
+    min_disk = int(est.params_b * 2) + 64 if est.params_b else 0
+    return ModelInfo(
+        id=model_id,
+        display_name=model_id,
+        params=params,
+        # Carry the estimated/HF param count straight through (0.0 when size is unknown) so downstream
+        # sizing reads ``params_b`` directly — no re-parsing the display string.
+        params_b=est.params_b or 0.0,
+        algos=ALGORITHMS,
+        min_vram_gb=math.ceil(est.est_gb) if est.est_gb else 24,
+        min_disk_gb=min_disk,
+        recommended_gpu=gpu or DEFAULT_GPU,
+        thinking="unknown",
+        notes="unlisted model accepted via the open-model policy (not curated/validated)",
+    )
+
+
+def validate_model_for_algorithm(model_id: str, algorithm: str) -> ModelInfo:
+    info = get_model(model_id)
+    algo = normalize_algorithm(algorithm)
+    required = "grpo" if algo == "grpo" else "sft"
+    if required not in info.algos:
+        allowed = ", ".join(info.algos)
+        raise ValueError(f"{model_id} supports {allowed}, not {algo}")
+    return info
+
+
+def public_model_rows() -> list[dict[str, Any]]:
+    return [m.to_dict() for m in list_models()]