llmsetup 0.1.0__py3-none-any.whl

llmsetup/catalog/autoupdate.py

@@ -0,0 +1,285 @@
+"""Keeping an installed copy's catalog current, without anyone pushing anything.
+
+The shipped catalog is a snapshot. This module lets an installation pull a
+newer one on a cadence, so a model released after install still shows up.
+
+Four rules, because an auto-updater that misbehaves is worse than none:
+
+1. **Fail open.** Any failure at all (offline, DNS, a 500, malformed YAML) leaves the
+   bundled catalog in place and the run continues. A model picker must not stop
+   working because a refresh server is down.
+2. **Never block the user.** One short timeout, checked at most once per
+   interval against a local stamp file. No retries, no spinner, no waiting.
+3. **Validated before adoption.** A downloaded catalog is parsed and
+   schema-checked in a temporary location first; it only replaces the cached
+   copy if it loads cleanly. A broken update can never brick the install.
+4. **Opt-out, and off by default in the paths that must be deterministic.**
+   ``LLMSETUP_AUTO_UPDATE=0`` disables it, and it never runs when the user asked
+   for an offline setup.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import os
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+
+from llmsetup.util.fs import app_dir, ensure_dir, write_text
+from llmsetup.util.log import Console
+
+#: Where updated catalogs come from. Points at this project's own catalog on
+#: main, which a scheduled workflow keeps current, so the repo is the
+#: distribution channel and there is no extra infrastructure to run.
+DEFAULT_CATALOG_URL = (
+    "https://raw.githubusercontent.com/catfish-1234/llmsetup/"
+    "main/src/llmsetup/catalog/data/models.yaml"
+)
+
+#: How often to check. Model releases happen weekly at most; checking more often
+#: spends the user's network for nothing.
+DEFAULT_INTERVAL_HOURS = 24
+
+#: One short attempt. This runs on the path to a user's actual task.
+TIMEOUT_SECONDS = 6.0
+
+CACHE_NAME = "auto-update.yaml"
+STAMP_NAME = "auto-update.json"
+
+
+def catalog_url() -> str:
+    return os.environ.get("LLMSETUP_CATALOG_URL", DEFAULT_CATALOG_URL)
+
+
+def disabled_marker() -> Path:
+    """A persistent opt-out that survives new shells, unlike an env var."""
+    return app_dir() / "auto-update-disabled"
+
+
+def enabled() -> bool:
+    if os.environ.get("LLMSETUP_AUTO_UPDATE", "1").strip().lower() in (
+        "0", "false", "no", "off"
+    ):
+        return False
+    return not disabled_marker().exists()
+
+
+def interval_hours() -> float:
+    try:
+        return max(1.0, float(os.environ.get("LLMSETUP_AUTO_UPDATE_HOURS",
+                                             DEFAULT_INTERVAL_HOURS)))
+    except ValueError:
+        return DEFAULT_INTERVAL_HOURS
+
+
+def cache_dir() -> Path:
+    return ensure_dir(app_dir() / "catalog.d")
+
+
+def cache_path() -> Path:
+    return cache_dir() / CACHE_NAME
+
+
+def stamp_path() -> Path:
+    return app_dir() / STAMP_NAME
+
+
+# --------------------------------------------------------------------------- #
+# state
+# --------------------------------------------------------------------------- #
+
+
+def _read_stamp() -> Dict[str, Any]:
+    try:
+        return json.loads(stamp_path().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+
+
+def _write_stamp(**fields: Any) -> None:
+    stamp = _read_stamp()
+    stamp.update(fields)
+    stamp["last_checked"] = _now()
+    try:
+        write_text(stamp_path(), json.dumps(stamp, indent=2) + "\n")
+    except OSError:
+        pass          # a read-only home must not break the run
+
+
+def is_due(now: Optional[datetime.datetime] = None) -> bool:
+    """Whether enough time has passed since the last check."""
+    stamp = _read_stamp()
+    last = stamp.get("last_checked")
+    if not last:
+        return True
+    try:
+        checked = datetime.datetime.fromisoformat(last)
+    except (TypeError, ValueError):
+        return True
+    now = now or datetime.datetime.now(datetime.timezone.utc)
+    if checked.tzinfo is None:
+        checked = checked.replace(tzinfo=datetime.timezone.utc)
+    return (now - checked).total_seconds() >= interval_hours() * 3600
+
+
+def status() -> Dict[str, Any]:
+    """What the user sees from `llmsetup catalog status`."""
+    stamp = _read_stamp()
+    cached = cache_path()
+    return {
+        "enabled": enabled(),
+        "url": catalog_url(),
+        "interval_hours": interval_hours(),
+        "last_checked": stamp.get("last_checked"),
+        "last_updated": stamp.get("last_updated"),
+        "last_error": stamp.get("last_error"),
+        "cached_catalog": str(cached) if cached.exists() else None,
+        "cached_models": stamp.get("cached_models"),
+        "due": is_due(),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# the update itself
+# --------------------------------------------------------------------------- #
+
+
+def fetch_catalog(url: str, timeout: float = TIMEOUT_SECONDS) -> Optional[str]:
+    """Download a catalog document. None on any failure."""
+    try:
+        request = urllib.request.Request(
+            url, headers={"User-Agent": "llmsetup/0.1 auto-update"}
+        )
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            # Only HTTP responses carry a status; a file:// or other local
+            # source has none, and that is a legitimate way to point an
+            # air-gapped install at an internal catalog.
+            status_code = getattr(response, "status", None)
+            if status_code is not None and status_code != 200:
+                return None
+            # Cap the read: a catalog is tens of kilobytes, and an unbounded
+            # read from a URL the user can point anywhere is not acceptable.
+            return response.read(8 * 1024 * 1024).decode("utf-8", "replace")
+    except (urllib.error.URLError, urllib.error.HTTPError, OSError, ValueError):
+        return None
+
+
+def validate_catalog_text(text: str) -> Optional[Dict[str, Any]]:
+    """Parse and sanity-check a downloaded catalog before adopting it.
+
+    Rejects anything that is not a well-formed catalog with real entries, so a
+    truncated download or an HTML error page never replaces a working catalog.
+    """
+    try:
+        document = yaml.safe_load(text)
+    except yaml.YAMLError:
+        return None
+    if not isinstance(document, dict):
+        return None
+
+    models = document.get("models")
+    if not isinstance(models, list) or not models:
+        return None
+    for entry in models:
+        if not isinstance(entry, dict) or not entry.get("id"):
+            return None
+    return document
+
+
+def apply_update(console: Console, force: bool = False,
+                 url: Optional[str] = None) -> Dict[str, Any]:
+    """Fetch, validate and cache a newer catalog. Never raises."""
+    target = url or catalog_url()
+
+    if not force and not enabled():
+        return {"updated": False, "reason": "auto-update is disabled"}
+    if not force and not is_due():
+        return {"updated": False, "reason": "checked recently"}
+
+    text = fetch_catalog(target)
+    if text is None:
+        _write_stamp(last_error=f"could not fetch {target}")
+        return {"updated": False, "reason": f"could not reach {target}"}
+
+    document = validate_catalog_text(text)
+    if document is None:
+        _write_stamp(last_error="downloaded catalog failed validation")
+        return {"updated": False, "reason": "the downloaded catalog is not valid"}
+
+    # Prove it loads through the real loader before it can affect anything.
+    if not _loads_cleanly(text):
+        _write_stamp(last_error="downloaded catalog did not load")
+        return {"updated": False, "reason": "the downloaded catalog did not load"}
+
+    count = len(document.get("models") or [])
+    header = (
+        "# Auto-updated catalog, fetched by llmsetup. Do not edit: it is replaced\n"
+        f"# on each update. Source: {target}\n"
+        "# Disable with LLMSETUP_AUTO_UPDATE=0. Your own entries in other files in\n"
+        "# this directory are layered on top of this one and are never touched.\n\n"
+    )
+    try:
+        write_text(cache_path(), header + text)
+    except OSError as exc:
+        _write_stamp(last_error=str(exc))
+        return {"updated": False, "reason": f"could not write the cache: {exc}"}
+
+    _write_stamp(last_updated=_now(), cached_models=count, last_error=None)
+    console.debug(f"catalog auto-updated from {target} ({count} models)")
+    return {"updated": True, "models": count, "url": target,
+            "path": str(cache_path()), "catalog_date": document.get("updated")}
+
+
+def _loads_cleanly(text: str) -> bool:
+    """Run a candidate catalog through the real loader in isolation."""
+    from llmsetup.catalog.catalog import load_catalog
+
+    with tempfile.TemporaryDirectory() as directory:
+        path = Path(directory) / "candidate.yaml"
+        path.write_text(text, encoding="utf-8")
+        try:
+            catalog = load_catalog(extra_paths=[path], include_user_dir=False)
+        except Exception:
+            # Any failure at all is a reason to reject the download; the
+            # bundled catalog stays in place.
+            return False
+        return len(catalog) > 0
+
+
+def maybe_update(console: Console, offline: bool = False) -> Dict[str, Any]:
+    """The hook called on ordinary runs. Silent, bounded, and never fatal."""
+    if offline or not enabled():
+        return {"updated": False, "reason": "skipped"}
+    if not is_due():
+        return {"updated": False, "reason": "checked recently"}
+    try:
+        return apply_update(console)
+    except Exception as exc:
+        # An updater must never break the run it is trying to improve.
+        console.debug(f"catalog auto-update skipped: {exc}")
+        return {"updated": False, "reason": str(exc)}
+
+
+def disable_persistently() -> Path:
+    """Write an opt-out the user does not have to re-export in every shell."""
+    marker = disabled_marker()
+    write_text(marker, "Delete this file to re-enable catalog auto-update.\n")
+    return marker
+
+
+def enable_persistently() -> None:
+    """Remove the opt-out marker. The env var, if set, still wins."""
+    try:
+        disabled_marker().unlink()
+    except OSError:
+        pass
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")

llmsetup/catalog/catalog.py

@@ -0,0 +1,389 @@
+"""Loading and querying the model catalog.
+
+The catalog is data with a schema, not a Python literal, so a user can extend it
+without forking the tool. Layering is: bundled catalog → files in
+``$LLMSETUP_HOME/catalog.d/*.yaml`` → an explicit ``--catalog`` path. Later layers
+override earlier entries by ``id`` and may add new ones.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+from dataclasses import replace
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+import yaml
+
+from llmsetup.types import ModelSpec, Task, UseCaseProfile
+from llmsetup.util.errors import CatalogError
+from llmsetup.util.fs import app_dir
+
+BUNDLED = Path(__file__).parent / "data" / "models.yaml"
+
+# Used when a catalog entry names a quant we have no bits-per-weight figure for.
+DEFAULT_BPW = 4.85
+
+_SPEC_FIELDS = set(ModelSpec.__dataclass_fields__)
+
+
+class Catalog:
+    """A loaded catalog: model specs plus the quantization size table."""
+
+    def __init__(self, models: List[ModelSpec], quant_bpw: Dict[str, float],
+                 updated: str = "", sources: Optional[List[str]] = None,
+                 extras: Optional[Dict[str, dict]] = None):
+        self.models = models
+        self.quant_bpw = quant_bpw
+        self.updated = updated
+        self.sources = sources or []
+        # Non-schema keys (arch_source and other provenance) live on the instance,
+        # not in a module global: two Catalog objects in one process must not
+        # report each other's provenance.
+        self.extras = extras or {}
+        self._reindex()
+
+    def _reindex(self) -> None:
+        self._by_id = {m.id: m for m in self.models}
+
+    def restrict_to(self, model_id: str) -> "Catalog":
+        """A view containing only one model, for `--model` and `doctor`.
+
+        Returns a new Catalog rather than mutating this one, so callers never
+        have to reach into private indexes to keep them consistent.
+        """
+        spec = self.require(model_id)
+        return Catalog([spec], dict(self.quant_bpw), self.updated, list(self.sources),
+                       {spec.id: dict(self.extras.get(spec.id, {}))})
+
+    def arch_source(self, model_id: str) -> str:
+        """'measured' or 'estimated', whether the architecture figures are trustworthy."""
+        return str(self.extras.get(model_id, {}).get("arch_source", "measured"))
+
+    def __len__(self) -> int:
+        return len(self.models)
+
+    def get(self, model_id: str) -> Optional[ModelSpec]:
+        return self._by_id.get(model_id)
+
+    def require(self, model_id: str) -> ModelSpec:
+        spec = self.get(model_id)
+        if spec is None:
+            close = [m for m in self._by_id if model_id.lower() in m.lower()]
+            raise CatalogError(
+                f"unknown model id {model_id!r}",
+                hint=(f"did you mean: {', '.join(close[:3])}?" if close
+                      else "run `llmsetup catalog list` to see available models"),
+            )
+        return spec
+
+    def bpw(self, quant: str) -> float:
+        """Bits per weight for a quantization, case-insensitively."""
+        if quant in self.quant_bpw:
+            return self.quant_bpw[quant]
+        upper = quant.upper()
+        for key, value in self.quant_bpw.items():
+            if key.upper() == upper:
+                return value
+        # Native formats can be selected for a retained model even when the
+        # catalog only lists GGUF quantizations. Keep later tuning/recovery
+        # estimates consistent with the planner's actual weight format.
+        return {"F16": 16.0, "BF16": 16.0, "MLX2": 2.85,
+                "MLX4": 4.85, "MLX8": 8.5}.get(upper, DEFAULT_BPW)
+
+    # ----------------------------------------------------------------- queries
+
+    def chat_models(self) -> List[ModelSpec]:
+        return [m for m in self.models if not m.is_embedding]
+
+    def embedding_models(self) -> List[ModelSpec]:
+        return [m for m in self.models if m.is_embedding]
+
+    def completion_models(self) -> List[ModelSpec]:
+        """Models that can fill a gap between a prefix and a suffix."""
+        return [m for m in self.models if m.supports_fim and not m.is_embedding]
+
+    def matching(self, profile: UseCaseProfile) -> List[ModelSpec]:
+        """Hard capability filter.
+
+        Everything here is a *requirement the user stated*, so failing it removes
+        the model outright rather than costing it points. Soft preferences
+        (quality, speed, size) are handled by scoring instead.
+        """
+        out = []
+        for spec in self.chat_models():
+            if not self.satisfies(spec, profile):
+                continue
+            out.append(spec)
+        return out
+
+    def satisfies(self, spec: ModelSpec, profile: UseCaseProfile) -> bool:
+        if profile.needs_vision and not spec.supports_vision:
+            return False
+        if profile.needs_tools and not spec.supports_tools:
+            return False
+        if profile.needs_json and not spec.supports_json:
+            return False
+        if profile.needs_reasoning and not spec.is_reasoning:
+            return False
+        if profile.commercial_use and not spec.commercial_ok:
+            return False
+        # A model whose maximum context is below what the user asked for cannot
+        # do the job, regardless of how good it is.
+        if profile.context_tokens > spec.max_context:
+            return False
+        if spec.tasks and profile.tasks:
+            wanted = {t.value for t in profile.tasks}
+            if not wanted & set(spec.tasks):
+                return False
+        return True
+
+    def unmatched_reasons(self, profile: UseCaseProfile) -> Dict[str, int]:
+        """Why models were filtered out, which turns 'nothing fits' into an explanation."""
+        reasons: Dict[str, int] = {}
+
+        def bump(key: str) -> None:
+            reasons[key] = reasons.get(key, 0) + 1
+
+        for spec in self.chat_models():
+            if self.satisfies(spec, profile):
+                continue
+            if profile.needs_vision and not spec.supports_vision:
+                bump("no vision support")
+            elif profile.needs_tools and not spec.supports_tools:
+                bump("no tool-calling support")
+            elif profile.needs_json and not spec.supports_json:
+                bump("no structured-output support")
+            elif profile.needs_reasoning and not spec.is_reasoning:
+                bump("not a reasoning model")
+            elif profile.commercial_use and not spec.commercial_ok:
+                bump("licence disallows commercial use")
+            elif profile.context_tokens > spec.max_context:
+                bump(f"max context below {profile.context_tokens}")
+            else:
+                bump("task mismatch")
+        return reasons
+
+    def for_task(self, task: Task) -> List[ModelSpec]:
+        return [m for m in self.models if task.value in m.tasks]
+
+
+def load_catalog(extra_paths: Optional[Iterable[Path]] = None,
+                 include_user_dir: bool = True) -> Catalog:
+    """Load the bundled catalog, then layer user overrides on top."""
+    paths: List[Path] = [BUNDLED]
+
+    if include_user_dir:
+        user_dir = app_dir() / "catalog.d"
+        if user_dir.is_dir():
+            paths.extend(sorted(p for p in user_dir.iterdir()
+                                if p.suffix in (".yaml", ".yml")))
+    env_path = os.environ.get("LLMSETUP_CATALOG")
+    if env_path:
+        paths.append(Path(env_path).expanduser())
+    if extra_paths:
+        paths.extend(Path(p).expanduser() for p in extra_paths)
+
+    merged: Dict[str, ModelSpec] = {}
+    extras: Dict[str, dict] = {}
+    quant_bpw: Dict[str, float] = {}
+    updated = ""
+    used: List[str] = []
+
+    for path in paths:
+        if not path.exists():
+            if path is BUNDLED:
+                raise CatalogError(f"bundled catalog missing at {path}",
+                                   hint="reinstall llmsetup")
+            continue
+        data = _read_yaml(path)
+        version = data.get("schema_version", 1)
+        if type(version) is not int or version != 1:
+            raise CatalogError(f"unsupported schema_version {version!r} in {path}; expected 1")
+        table = data.get("quant_bpw", {})
+        if not isinstance(table, dict):
+            raise CatalogError(f"quant_bpw must be a mapping in {path}")
+        for key, value in table.items():
+            converted = _coerce_types({"params_b": value}, f"quant_bpw[{key}]", path)
+            quant_bpw[str(key)] = converted["params_b"]
+        updated = data.get("updated") or updated
+        entries = data.get("models", [])
+        if not isinstance(entries, list):
+            raise CatalogError(f"models must be a list in {path}")
+        seen = set()
+        for raw in entries:
+            if not isinstance(raw, dict) or "id" not in raw:
+                raise CatalogError(f"catalog entry without an 'id' in {path}")
+            model_id = raw["id"]
+            if not isinstance(model_id, str) or not model_id.strip():
+                raise CatalogError(f"model id must be a nonempty string in {path}: {model_id!r}")
+            if model_id in seen:
+                raise CatalogError(f"duplicate model id {model_id!r} in {path}")
+            seen.add(model_id)
+            # A later layer that repeats an id patches the earlier entry field by
+            # field, so a user can override just `ollama_name` without restating
+            # the whole model. Patching must not require a complete entry, so the
+            # existence check comes before we try to build a full ModelSpec.
+            if model_id in merged:
+                merged[model_id] = _patch(merged[model_id], raw, path)
+            else:
+                merged[model_id] = _to_spec(raw, path)
+            _record_extras(extras, model_id, raw)
+        used.append(str(path))
+
+    if not merged:
+        raise CatalogError("catalog contains no models", hint="check your catalog YAML files")
+    return Catalog(list(merged.values()), quant_bpw, updated, used, extras)
+
+
+def _read_yaml(path: Path) -> dict:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        raise CatalogError(f"could not read catalog {path}: {exc}",
+                           hint="the file must be valid YAML") from None
+    if data is None:
+        data = {}
+    if not isinstance(data, dict):
+        raise CatalogError(f"catalog {path} must be a YAML mapping")
+    return data
+
+
+def _to_spec(raw: dict, path: Path) -> ModelSpec:
+    """Build a full spec from a complete entry.
+
+    Keys outside the ModelSpec schema (``arch_source`` and other provenance
+    notes) are preserved out-of-band by :func:`_record_extras` rather than
+    dropped, so the planner can flag estimated architectures.
+    """
+    if not isinstance(raw, dict) or "id" not in raw:
+        raise CatalogError(f"catalog entry without an 'id' in {path}")
+    fields = {k: v for k, v in raw.items() if k in _SPEC_FIELDS}
+    fields.setdefault("name", raw["id"])
+    fields.setdefault("publisher", "unknown")
+    fields = _coerce_types(fields, raw["id"], path)
+    try:
+        spec = ModelSpec(**fields)
+    except TypeError as exc:
+        raise CatalogError(f"bad catalog entry {raw.get('id')!r} in {path}: {exc}") from None
+    _validate_spec(spec, path)
+    return spec
+
+
+def _record_extras(store: Dict[str, dict], model_id: str, raw: dict) -> None:
+    found = {k: v for k, v in raw.items() if k not in _SPEC_FIELDS}
+    if found:
+        store.setdefault(model_id, {}).update(found)
+
+
+def _patch(base: ModelSpec, raw: dict, path: Path) -> ModelSpec:
+    changes = {k: v for k, v in raw.items() if k in _SPEC_FIELDS and k != "id"}
+    changes = _coerce_types(changes, base.id, path)
+    spec = replace(base, **changes)
+    _validate_spec(spec, path)
+    return spec
+
+
+#: Fields the memory model does arithmetic on. A string here does not fail at
+#: load time. It fails several layers down inside the fit maths, with an error
+#: that says nothing about the catalog. Types are enforced at the boundary.
+_NUMERIC_FIELDS = {
+    "params_b": float, "active_params_b": float, "layers": int,
+    "hidden_size": int, "kv_heads": int, "head_dim": int, "max_context": int,
+    "quality_tier": int, "max_disk_gb": float,
+    "sliding_window": int, "swa_pattern": int,
+    "full_attention_interval": int, "recurrent_state_bytes": int,
+}
+_BOOL_FIELDS = (
+    "commercial_ok", "supports_tools", "supports_vision", "supports_json",
+    "is_reasoning", "is_embedding", "draft_capable", "mtp_heads",
+    "supports_fim",
+)
+_LIST_FIELDS = ("tasks", "languages", "recommended_quants")
+
+
+def _coerce_types(fields: Dict[str, Any], model_id: str, path: Path) -> Dict[str, Any]:
+    """Validate and normalise an entry's field types.
+
+    Catalogs are extended by users and fetched automatically, so an entry can
+    carry anything YAML can express. Rejecting a bad value here, naming the file
+    and the field, beats a TypeError deep in the planner.
+    """
+    out = dict(fields)
+
+    for name, caster in _NUMERIC_FIELDS.items():
+        if name not in out:
+            continue
+        value = out[name]
+        if value is None and name in {"active_params_b", "head_dim", "max_disk_gb", "sliding_window"}:
+            continue
+        if isinstance(value, bool) or not isinstance(value, (int, float, str)):
+            raise CatalogError(
+                f"{model_id}.{name} must be a number, got {value!r} in {path}"
+            )
+        try:
+            number = float(value)
+            if not math.isfinite(number) or (caster is int and not number.is_integer()):
+                raise ValueError
+            out[name] = caster(value)
+        except (TypeError, ValueError, OverflowError):
+            raise CatalogError(
+                f"{model_id}.{name} must be a number, got {value!r} in {path}"
+            ) from None
+        if out[name] < 0 or (out[name] == 0 and name != "recurrent_state_bytes"):
+            raise CatalogError(
+                f"{model_id}.{name} must be positive, got {out[name]} in {path}"
+            )
+
+    for name in _BOOL_FIELDS:
+        if name in out and not isinstance(out[name], bool):
+            raise CatalogError(f"{model_id}.{name} must be a boolean in {path}")
+
+    for name in _LIST_FIELDS:
+        if name in out:
+            value = out[name]
+            if isinstance(value, str):
+                value = [value]
+            if not isinstance(value, (list, tuple)):
+                raise CatalogError(
+                    f"{model_id}.{name} must be a list, got {value!r} in {path}"
+                )
+            if not all(isinstance(item, str) and item.strip() for item in value):
+                raise CatalogError(f"{model_id}.{name} must contain nonempty strings in {path}")
+            out[name] = list(value)
+
+    for name in ("id", "name", "publisher", "license", "notes"):
+        if name in out and (not isinstance(out[name], str) or
+                            (name != "notes" and not out[name].strip())):
+            raise CatalogError(f"{model_id}.{name} must be a string in {path}")
+
+    return out
+
+
+def _validate_spec(spec: ModelSpec, path: Path) -> None:
+    from llmsetup.download import validate_repo, validate_revision
+    from llmsetup.util.errors import ProvisionError
+
+    for field in ("gguf_repo", "hf_repo", "mlx_repo", "gguf_revision", "hf_revision", "mlx_revision"):
+        value = getattr(spec, field)
+        if value is not None:
+            try:
+                if not isinstance(value, str):
+                    raise ProvisionError("must be a string")
+                if field.endswith("_repo"):
+                    setattr(spec, field, validate_repo(value))
+                else:
+                    setattr(spec, field, validate_revision(value))
+            except ProvisionError as exc:
+                raise CatalogError(f"{spec.id}.{field}: {exc.message} in {path}") from None
+    if not 1 <= spec.quality_tier <= 5:
+        raise CatalogError(f"{spec.id}.quality_tier must be between 1 and 5 in {path}")
+    if spec.active_params_b is not None and spec.active_params_b > spec.params_b:
+        raise CatalogError(f"{spec.id}.active_params_b exceeds params_b in {path}")
+    unknown = set(spec.tasks) - {task.value for task in Task}
+    if unknown:
+        raise CatalogError(f"{spec.id}.tasks has unknown values {sorted(unknown)!r} in {path}")
+    if not spec.recommended_quants:
+        raise CatalogError(f"{spec.id}.recommended_quants must not be empty in {path}")
+