abstractcore 2.19.0__tar.gz → 2.19.2__tar.gz

{abstractcore-2.19.0 → abstractcore-2.19.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abstractcore
-Version: 2.19.0
+Version: 2.19.2
 Summary: Unified interface to all LLM providers with essential infrastructure for tool calling, streaming, and model management
 Author-email: Laurent-Philippe Albou <contact@abstractcore.ai>
 Maintainer-email: Laurent-Philippe Albou <contact@abstractcore.ai>
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: httpx<1.0.0,>=0.24.0
-Requires-Dist: openai<2.0.0,>=1.0.0
+Requires-Dist: openai<3.0.0,>=1.0.0
 Requires-Dist: anthropic<1.0.0,>=0.25.0
 Requires-Dist: tiktoken<1.0.0,>=0.5.0
 Requires-Dist: requests<3.0.0,>=2.25.0
@@ -48,8 +48,8 @@ Requires-Dist: fastapi<1.0.0,>=0.100.0
 Requires-Dist: uvicorn[standard]<1.0.0,>=0.23.0
 Requires-Dist: python-multipart<1.0.0,>=0.0.6
 Requires-Dist: sse-starlette<2.0.0,>=1.6.0
-Requires-Dist: abstractvoice>=0.13.0
-Requires-Dist: abstractvision>=0.3.31
+Requires-Dist: abstractvoice>=0.13.2
+Requires-Dist: abstractvision>=0.3.33
 Requires-Dist: abstractmusic>=0.1.15; python_version >= "3.10"
 Requires-Dist: abstract3d>=0.1.0; python_version >= "3.10"
 Provides-Extra: apple
@@ -67,26 +67,26 @@ Requires-Dist: accelerate>=1.0.0; extra == "apple"
 Requires-Dist: sentence-transformers<6.0.0,>=5.1.0; extra == "apple"
 Requires-Dist: numpy<3.0.0,>=2.1.0; extra == "apple"
 Requires-Dist: Pillow<13.0.0,>=12.1.1; extra == "apple"
-Requires-Dist: abstractvoice[all-apple]>=0.13.0; extra == "apple"
+Requires-Dist: abstractvoice[all-apple]>=0.13.2; extra == "apple"
 Requires-Dist: omnivoice>=0.1.5; extra == "apple"
-Requires-Dist: abstractvision[all-apple]>=0.3.31; extra == "apple"
+Requires-Dist: abstractvision[all-apple]>=0.3.33; extra == "apple"
 Requires-Dist: abstractmusic[all-apple]>=0.1.15; extra == "apple"
 Requires-Dist: playwright<2.0.0,>=1.49.0; extra == "apple"
 Provides-Extra: gpu
-Requires-Dist: vllm<1.0.0,>=0.6.0; extra == "gpu"
+Requires-Dist: vllm<1.0.0,>=0.6.0; sys_platform == "linux" and extra == "gpu"
 Requires-Dist: outlines>=0.1.0; extra == "gpu"
 Requires-Dist: transformers<6.0.0,>=4.57.1; extra == "gpu"
 Requires-Dist: torch<3.0.0,>=2.6.0; extra == "gpu"
 Requires-Dist: torchvision>=0.17.0; extra == "gpu"
 Requires-Dist: torchaudio>=2.1.0; extra == "gpu"
 Requires-Dist: sentencepiece<1.0.0,>=0.1.99; extra == "gpu"
-Requires-Dist: llama-cpp-python<1.0.0,>=0.3.23; extra == "gpu"
+Requires-Dist: llama-cpp-python<1.0.0,>=0.3.23; sys_platform != "win32" and extra == "gpu"
 Requires-Dist: sentence-transformers<6.0.0,>=5.1.0; extra == "gpu"
 Requires-Dist: numpy<3.0.0,>=1.20.0; python_version < "3.13" and extra == "gpu"
 Requires-Dist: numpy<3.0.0,>=2.1.0; python_version >= "3.13" and extra == "gpu"
-Requires-Dist: abstractvoice[all-gpu]>=0.13.0; extra == "gpu"
+Requires-Dist: abstractvoice[all-gpu]>=0.13.2; extra == "gpu"
 Requires-Dist: omnivoice>=0.1.5; extra == "gpu"
-Requires-Dist: abstractvision[all-gpu]>=0.3.31; extra == "gpu"
+Requires-Dist: abstractvision[all-gpu]>=0.3.33; extra == "gpu"
 Requires-Dist: abstractmusic[all-gpu]>=0.1.15; extra == "gpu"
 Requires-Dist: playwright<2.0.0,>=1.49.0; extra == "gpu"
 Provides-Extra: remote

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/apps/extractor.py

@@ -225,7 +225,7 @@ Default model setup:
         '--format',
         choices=format_choices,
         default='json-ld',
-        help='Output format: json-ld (JSON-LD graph), triples (RDF SUBJECT PREDICATE OBJECT), json (simple JSON)' + (', yaml' if YAML_AVAILABLE else ' - install PyYAML for YAML support')
+        help='Output format: json-ld (JSON-LD graph), triples (RDF SUBJECT PREDICATE OBJECT), json (simple JSON)' + (', yaml' if YAML_AVAILABLE else ' - yaml needs PyYAML (part of the light install; repair with: pip install -U abstractcore)')
     )
 
     parser.add_argument(
@@ -513,7 +513,7 @@ Default model setup:
             )
         else:  # yaml
             if not YAML_AVAILABLE:
-                print("Error: PyYAML is required for YAML output format. Install with: pip install PyYAML")
+                print("Error: PyYAML is required for YAML output format; it is part of the light install. Repair with: pip install -U abstractcore")
                 sys.exit(1)
             formatted_output = yaml.dump(result, default_flow_style=False, indent=2, sort_keys=False)
 

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/apps/judge.py

@@ -352,7 +352,7 @@ Default model setup:
         '--format',
         choices=format_choices,
         default='json',
-        help='Output format: json (structured), plain (human-readable)' + (', yaml' if YAML_AVAILABLE else ' - install PyYAML for YAML support')
+        help='Output format: json (structured), plain (human-readable)' + (', yaml' if YAML_AVAILABLE else ' - yaml needs PyYAML (part of the light install; repair with: pip install -U abstractcore)')
     )
 
     parser.add_argument(
@@ -623,7 +623,7 @@ Default model setup:
                 formatted_output = format_assessment_plain(assessment)
         elif args.format == 'yaml':
             if not YAML_AVAILABLE:
-                print("Error: PyYAML is required for YAML output format. Install with: pip install PyYAML")
+                print("Error: PyYAML is required for YAML output format; it is part of the light install. Repair with: pip install -U abstractcore")
                 sys.exit(1)
             formatted_output = yaml.dump(assessment, default_flow_style=False, indent=2, sort_keys=False)
         else:

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/assets/model_downloads_catalog.json

@@ -1089,8 +1089,8 @@
    "artifacts": [
     {
      "provider": "lmstudio",
-     "artifact": "qwen/qwen3.5-9b@4bit",
-     "quant": "4bit",
+     "artifact": "qwen/qwen3.5-9b@q4_k_m",
+     "quant": "q4_k_m",
      "download_bytes": null,
      "size_source": "unknown",
      "verified": true,
@@ -4078,7 +4078,7 @@
   {
    "id": "flux.2-klein-4b",
    "family": "flux.2",
-   "display_name": "FLUX.2 [klein] 4B (8-bit)",
+   "display_name": "FLUX.2 [klein] 4B",
    "vendor": "Black Forest Labs",
    "params_total": 4000000000,
    "params_active": null,
@@ -4098,6 +4098,26 @@
      "size_source": "catalog",
      "verified": true,
      "recommended": true
+    },
+    {
+     "provider": "diffusers",
+     "artifact": "black-forest-labs/FLUX.2-klein-4B",
+     "quant": "bf16",
+     "download_bytes": 23740007447,
+     "size_source": "catalog",
+     "verified": true,
+     "recommended": true,
+     "upstream": {
+      "method": "hf_api",
+      "checked": "2026-09-29",
+      "revision": "e7b7dc27f91deacad38e78976d1f2b499d76a294"
+     },
+     "note": "23,740,007,447 bytes: the whole repo (25 files) at revision e7b7dc27, read with the Hugging Face model API on 2026-09-29; `models download diffusers` fetches it whole, including the 7.75 GB single-file checkpoint (flux-2-klein-4b.safetensors) the Diffusers pipeline does not load. The pipeline's weights are 14.9 GiB in float16 (text encoder 7.49 GiB, transformer 7.22 GiB, VAE 0.16 GiB).",
+     "resident": {
+      "bytes": 8912896000,
+      "source": "nvidia-smi GPU memory peak 7.8-8.3 GiB (the largest, 8.3 GiB, is the figure) of real AbstractVision Diffusers text-to-image generations at 768x768, 4 steps, float16, about 17 s each, with the model CPU offload AbstractVision turns on by itself when the 14.9 GiB of float16 weights do not fit the GPU's free memory (moved whole, the pipeline runs out of CUDA memory on this card); system RAM holds the idle weights, about 15 GiB: Linux, NVIDIA Quadro RTX 5000 16 GB (Turing, sm_75), driver 595, abstractvision 0.3.32 source (commit 281756f), 2026-09-29 (framework backlog 0989)",
+      "measured_with": "AbstractVision/diffusers on CUDA in float16 at 768x768 with model CPU offload, about 15 GiB of idle weights waiting in system RAM"
+     }
     }
    ],
    "capabilities_override": {
@@ -4105,7 +4125,7 @@
     "vision": false,
     "image_generation": true
    },
-   "notes": "The AbstractFramework fresh-install image-generation default (output.image)."
+   "notes": "The AbstractFramework image-generation recommendation (output.image): the 8-bit MLX-Gen build on Apple silicon, the Diffusers repo on an NVIDIA GPU (CUDA)."
   },
   {
    "id": "supertonic-3",
@@ -4316,7 +4336,7 @@
     "voice",
     "speech-to-text"
    ],
-   "starter": false,
+   "starter": true,
    "artifacts": [
     {
      "provider": "huggingface",

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/capabilities/registry.py

@@ -647,9 +647,12 @@ class CapabilityRegistry:
         if cap in {"voice", "audio", "vision", "music", "scene3d", "3d"}:
             return "pip install -U abstractcore"
         if cap == "camera":
-            # camera (seat: camera): no abstractcore extra exists yet — the
-            # plugin package is the install unit.
-            return 'pip install "abstractcamera"'
+            # camera (seat: camera): no install setting ships the camera plugin, and a
+            # bare-package install is never advised (operator ruling 2026-09-29).
+            return (
+                "Camera is not available with AbstractCore's install settings (light, apple, gpu): "
+                "the camera plugin (abstractcamera) is not part of them"
+            )
         return None
 
     def _select_backend_id(self, capability: str) -> str:

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/compression/pil_text_renderer.py

@@ -57,7 +57,7 @@ class PILTextRenderer:
             from PIL import Image, ImageDraw, ImageFont
         except ImportError as e:
             raise RenderingError(
-                f"PIL/Pillow not available: {e}. Install with: pip install pillow"
+                f"PIL/Pillow not available: {e}. Pillow is part of the light install; repair with: pip install -U abstractcore"
             )
 
     def _estimate_text_capacity(self, config: RenderingConfig, fonts: dict) -> int:

{abstractcore-2.19.0 → abstractcore-2.19.2}/abstractcore/config/capability_defaults.py

@@ -290,7 +290,15 @@ def clean_capability_route_default(value: Any) -> CapabilityRouteDefault:
     )
 
 
-RECOMMENDED_SEED_VERSION = "recommended-v1"
+RECOMMENDED_SEED_VERSION = "recommended-v2"
+
+# What each seed version added to the one before it, applied once to a store
+# an earlier seed wrote (`upgrade_recommended_seed`). v2 (AbstractCore 2.19.2):
+# speech input, so a fresh install transcribes locally instead of falling
+# through to OpenAI without a key.
+RECOMMENDED_SEED_ADDITIONS: Tuple[Tuple[str, Tuple[str, ...]], ...] = (
+    ("recommended-v2", ("input.voice",)),
+)
 
 # THE RECOMMENDED MODEL PER CAPABILITY: one table, every surface.
 #
@@ -317,11 +325,27 @@ RECOMMENDED_SEED_VERSION = "recommended-v1"
 # them ONLY when the config file does not exist yet -- never merged into an
 # existing store (an operator who cleared a route meant it), and never on the
 # corrupt-file fallback. `apply-recommended` and `models download
-# --recommended` act on the same starter set. Rows with `starter=False`
-# (speech input, music) are recommendations every listing shows, which no
-# writer applies on its own: the operator sets them (`abstractcore config
+# --recommended` act on the same starter set: text, voice output, speech
+# input, image and video. Rows with `starter=False` (music) are
+# recommendations every listing shows, which no writer applies on its own: the operator sets them (`abstractcore config
 # set-default`). Text stores at input.text (the canonical storage key;
 # output.text derives).
+#
+# PER-ACCELERATOR PICKS (`by_accelerator`): a row whose best engine differs by
+# the host's accelerator carries the other pick IN THE ROW, keyed by the host
+# probe's `accelerator` (`cuda`, `metal`, ...). `route`/`download` stay the
+# portable pick every other host starts from; `_full_recommendation` swaps in
+# the accelerator's pick BEFORE the engine-support filter and the memory gate,
+# so the pick is judged by the same rules as every other row. The row stays
+# the one place its recommendation lives.
+@dataclass(frozen=True)
+class AcceleratorPick:
+    """The route and download that replace a row's portable pick on one accelerator."""
+
+    route: CapabilityRouteDefault
+    download: Mapping[str, str]
+
+
 @dataclass(frozen=True)
 class RecommendedModel:
     """One capability's recommendation: the route, its download, starter or not."""
@@ -329,20 +353,31 @@ class RecommendedModel:
     route: CapabilityRouteDefault
     download: Mapping[str, str]
     starter: bool
+    by_accelerator: Mapping[str, AcceleratorPick] = field(default_factory=dict)
+
+    def pick_for(self, host: Mapping[str, Any]) -> Tuple[CapabilityRouteDefault, Mapping[str, str]]:
+        """`(route, download)` for `host`: its accelerator's pick, else the portable one."""
+
+        pick = self.by_accelerator.get(str(host.get("accelerator") or ""))
+        return (pick.route, pick.download) if pick is not None else (self.route, self.download)
 
 
 RECOMMENDED_MODELS: Dict[str, RecommendedModel] = {
     # Text: the 4-BIT quantized build (operator ruling 2026-08-01). The ROUTE
     # stores the bare LM Studio id because that is what the server serves when
     # a single quant is installed; the 4-bit choice is pinned by the download
-    # artifact reference, which is what actually fetches the weights.
+    # artifact reference, which is what actually fetches the weights. The
+    # variant is LM Studio's GGUF Q4_K_M: LM Studio is recommended only off
+    # Apple silicon (Linux, Windows), where its catalog has no `4bit` (MLX)
+    # variant -- `lms get qwen/qwen3.5-9b@4bit` fails there with "Cannot find
+    # variant 4bit" (measured on Linux + NVIDIA, framework backlog 0989).
     "input.text": RecommendedModel(
         route=CapabilityRouteDefault(
             provider="lmstudio", model="qwen/qwen3.5-9b",
             options={"speculation": {"mode": "native_mtp", "num_draft_tokens": 2,
                                      "require_acceleration": False}},
         ),
-        download={"provider": "lmstudio", "artifact": "qwen/qwen3.5-9b@4bit"},
+        download={"provider": "lmstudio", "artifact": "qwen/qwen3.5-9b@q4_k_m"},
         starter=True,
     ),
     "output.voice": RecommendedModel(
@@ -350,10 +385,26 @@ RECOMMENDED_MODELS: Dict[str, RecommendedModel] = {
         download={"provider": "supertonic", "artifact": "supertonic-3"},
         starter=True,
     ),
+    # Image: FLUX.2 [klein] 4B. Apple silicon (and the portable pick): the
+    # 8-bit MLX-Gen build. An NVIDIA GPU (`cuda`): the same model's Diffusers
+    # repo on AbstractVision's `diffusers` backend (the route provider the
+    # image lane maps to that backend; device `auto` resolves to CUDA, float16).
+    # Its 14.9 GiB of float16 weights do not fit a 16 GB card whole, so
+    # AbstractVision (>= 0.3.32, `cpu_offload="auto"`) loads it with model CPU
+    # offload there: measured 768x768 in ~17 s with an 8.3 GiB GPU peak on a
+    # Quadro RTX 5000 16 GB (framework backlog 0989; the catalog artifact's
+    # `resident` is that figure, so the memory gate judges it). Processor-only
+    # hosts keep the portable pick and report it unavailable.
     "output.image": RecommendedModel(
         route=CapabilityRouteDefault(provider="mlx-gen", model="AbstractFramework/flux.2-klein-4b-8bit"),
         download={"provider": "mlx-gen", "artifact": "AbstractFramework/flux.2-klein-4b-8bit"},
         starter=True,
+        by_accelerator={
+            "cuda": AcceleratorPick(
+                route=CapabilityRouteDefault(provider="diffusers", model="black-forest-labs/FLUX.2-klein-4B"),
+                download={"provider": "diffusers", "artifact": "black-forest-labs/FLUX.2-klein-4B"},
+            ),
+        },
     ),
     # Video: Wan2.2 TI2V-5B, ONE checkpoint for text-to-video AND
     # image-to-video, so the modality cell answers both tasks. It is the only
@@ -371,11 +422,14 @@ RECOMMENDED_MODELS: Dict[str, RecommendedModel] = {
     # an NVIDIA GPU, the processor elsewhere -- it has no Metal backend) with
     # AbstractVoice's own default model, `base`. faster-whisper resolves
     # `base` to the Hugging Face repo below in the standard Hugging Face cache,
-    # which is where `models download huggingface <repo>` puts it.
+    # which is where `models download huggingface <repo>` puts it. A STARTER
+    # row (2.19.2, framework rehearsal 0.6.3): without it a fresh install's
+    # speech-to-text fell through to OpenAI and failed for want of an API key,
+    # although the installer ships faster-whisper (`abstractvoice[stt]`).
     "input.voice": RecommendedModel(
         route=CapabilityRouteDefault(provider="faster-whisper", model="base"),
         download={"provider": "huggingface", "artifact": "Systran/faster-whisper-base"},
-        starter=False,
+        starter=True,
     ),
     # Music: AbstractMusic's `acestep` backend (Diffusers AceStepPipeline on
     # PyTorch: CUDA, Apple MPS in bfloat16, or the processor in float32) with
@@ -393,7 +447,7 @@ RECOMMENDED_MODELS: Dict[str, RecommendedModel] = {
 # `apply-recommended` and `models download --recommended` act on. Derived,
 # never edited: `RECOMMENDED_MODELS` is the one place a recommendation lives.
 # Like the table, never read directly for a host answer: use the host-aware
-# functions below.
+# functions below. They hold the PORTABLE picks (no `by_accelerator` swap).
 RECOMMENDED_CAPABILITY_DEFAULT_ROUTES: Dict[str, CapabilityRouteDefault] = {
     key: rec.route for key, rec in RECOMMENDED_MODELS.items() if rec.starter
 }
@@ -408,6 +462,8 @@ RECOMMENDED_MODEL_DOWNLOADS: Dict[str, Dict[str, str]] = {
 #     ONE owner): the unified-memory tier on Apple silicon (operator ruling
 #     2026-09-24), the portable LM Studio build elsewhere, and the same model's
 #     Ollama build where LM Studio has no build (Intel Macs);
+#   - a row with a pick for the host's accelerator (`by_accelerator`) uses it:
+#     image generation on an NVIDIA GPU is Diffusers, not MLX-Gen;
 #   - every row whose engine cannot run on the host is DROPPED, never written
 #     as a route that fails at first use. It is reported instead, with the
 #     reason, by `recommended_unavailable_routes()` -- the grid then shows the
@@ -443,6 +499,10 @@ RECOMMENDED_MODEL_DOWNLOADS: Dict[str, Dict[str, str]] = {
 #   acestep     abstractmusic's ACE-Step backend is a Diffusers pipeline on
 #               PyTorch (abstractmusic/backends/acestep.py): Apple-silicon
 #               macOS, x86_64/arm64 Linux, x86_64 Windows.
+#   diffusers   abstractvision's Diffusers backend is PyTorch
+#               (abstractvision/backends/huggingface_diffusers.py), the same
+#               builds as acestep. Recommended on `cuda` hosts only
+#               (`RECOMMENDED_MODELS["output.image"].by_accelerator`).
 _RECOMMENDED_PROVIDER_ENGINE = {
     "mlx": "mlx",
     "mlx-gen": "mlx",
@@ -451,12 +511,14 @@ _RECOMMENDED_PROVIDER_ENGINE = {
     "supertonic": "onnxruntime",
     "faster-whisper": "ctranslate2",
     "acestep": "torch",
+    "diffusers": "torch",
 }
 # How a provider that runs ON another engine words the engine's refusal.
 _ENGINE_VIA = {
     "supertonic": "Supertonic voice runs on ONNX Runtime (CPU), and ",
     "faster-whisper": "faster-whisper speech input runs on CTranslate2, and ",
     "acestep": "ACE-Step music generation runs on PyTorch, and ",
+    "diffusers": "Diffusers image generation runs on PyTorch, and ",
 }
 
 # CONFIGURED routes whose engine runs INSIDE this process (AbstractCore's MLX
@@ -470,8 +532,9 @@ _ENGINE_VIA = {
 _IN_PROCESS_PROVIDERS = frozenset({"mlx", "mlx-gen", "supertonic"})
 
 # What an operator can do instead, per route, appended to the reason. Provider
-# ids are abstractvision's own (`diffusers`, `sdcpp`); the curated catalog has
-# no artifact for them yet, which is why nothing is recommended in their place.
+# ids are abstractvision's own (`diffusers`, `sdcpp`). An NVIDIA GPU gets the
+# Diffusers image pick itself (`by_accelerator`); a processor-only host does not
+# (no measured processor run vouches for it), so the sentence names the engines.
 # Video has NO local alternative off Apple silicon today: abstractvision's
 # Diffusers text-to-video is disabled for its only model (CogVideoX-2b,
 # `_TEMPORARILY_DISABLED_LOCAL_DIFFUSERS_TASKS`) and has no image-to-video,
@@ -494,11 +557,6 @@ _UNAVAILABLE_NEXT_STEP = {
         "input.text to a cloud provider or to a text server on another machine (lmstudio, ollama or "
         "openai-compatible, with its base_url)"
     ),
-    "output.image": (
-        "set output.image to an image engine this host runs: diffusers (included with abstractcore[gpu]), "
-        "sdcpp (stable-diffusion.cpp, included with abstractcore[apple] and abstractcore[gpu]) or a cloud "
-        "image provider"
-    ),
     "output.video": _VIDEO_NO_LOCAL_ENGINE,
     # Engine ids are abstractvoice's (`transformers-asr`, `openai`).
     "input.voice": (
@@ -508,6 +566,27 @@ _UNAVAILABLE_NEXT_STEP = {
     # Backend ids are abstractmusic's (`acemusic`, `elevenlabs-music`).
     "output.music": "set output.music to a cloud music backend (acemusic or elevenlabs-music, with its API key)",
 }
+# output.image names only the three settings (operator ruling 2026-09-29). Apple
+# silicon never reaches this (MLX-Gen runs there), nor does an NVIDIA GPU (its
+# pick is Diffusers, which runs there). Linux: abstractcore[gpu] ships
+# both local image engines; Windows x86_64: abstractcore[gpu] ships diffusers
+# (stable-diffusion.cpp is a source build there, marked out; backlog 0988). An Intel
+# Mac or Windows on ARM has no setting that installs them (`uv pip compile` of
+# abstractcore[gpu] for x86_64-apple-darwin fails on torch). One sentence covers every
+# non-Apple host so a machine-class row ("Linux or Windows ...") stays exact.
+_UNAVAILABLE_NEXT_STEP["output.image"] = (
+    "set output.image to a local image engine: diffusers, included with abstractcore[gpu] on Linux and "
+    "Windows, or sdcpp (stable-diffusion.cpp), included with abstractcore[gpu] on Linux (on an Intel Mac or "
+    "Windows on ARM they are not available with AbstractCore's install settings), or to a cloud image provider"
+)
+
+
+def _unavailable_next_step(key: Optional[str], host: Mapping[str, Any]) -> Optional[str]:
+    """What an operator can do instead of an unavailable recommended row."""
+
+    return _UNAVAILABLE_NEXT_STEP.get(key or "")
+
+
 # Next step when the engine runs but the model does not fit (fit-gated rows).
 _TOO_LARGE_NEXT_STEP = {
     "output.image": "use a Mac with more unified memory, or a cloud image provider",
@@ -520,6 +599,12 @@ _TOO_LARGE_NEXT_STEP = {
         "with its API key)"
     ),
 }
+# The same, where the host's accelerator words it differently (the key is
+# `(accelerator, route)`): an NVIDIA GPU's image pick is judged against GPU
+# memory, not a Mac's unified memory.
+_TOO_LARGE_NEXT_STEP_BY_ACCELERATOR = {
+    ("cuda", "output.image"): "use an NVIDIA GPU with more memory, or a cloud image provider",
+}
 # Recommended rows written only where the catalog's fit estimate (the same one
 # the model browser's "fits this computer" filter uses: `fits` or `tight`)
 # says the model fits this host's memory.
@@ -606,7 +691,8 @@ def _fit_gate_sentence(
     if verdict in ("fits", "tight"):
         return None
     name = got["row"].get("display_name") or got["row"].get("id")
-    next_step = f"; {_TOO_LARGE_NEXT_STEP[key]}" if key in _TOO_LARGE_NEXT_STEP else ""
+    step = _TOO_LARGE_NEXT_STEP_BY_ACCELERATOR.get((str(host.get("accelerator") or ""), key)) or _TOO_LARGE_NEXT_STEP.get(key)
+    next_step = f"; {step}" if step else ""
     if verdict == "unknown" or not isinstance(fit.get("need_bytes"), int) or not isinstance(fit.get("usable_bytes"), int):
         return f"{name} needs a lot of memory and this computer's memory could not be measured{next_step}"
     # "measured" only where the seed carries a measured run-time peak
@@ -666,8 +752,9 @@ def _unavailable_reasons(
     for key, route in routes.items():
         reason = recommended_route_unavailable_reason(route.provider, host, key)
         if reason:
-            if key in _UNAVAILABLE_NEXT_STEP:
-                reason = f"{reason}; {_UNAVAILABLE_NEXT_STEP[key]}"
+            next_step = _unavailable_next_step(key, host)
+            if next_step:
+                reason = f"{reason}; {next_step}"
             out[key] = reason
             continue
         if key in _FIT_GATED_ROUTES:
@@ -682,9 +769,19 @@ def _host_or_probe(host: Optional[Mapping[str, Any]]) -> Dict[str, Any]:
         return dict(host)
     from ..utils.host_profile import host_profile
 
-    # The LIGHT reading: os / arch / Apple silicon / RAM, no GPU tool, no
-    # torch, no mlx (the import-time config seed runs this).
-    return host_profile(light=True)
+    # The LIGHT reading first: os / arch / Apple silicon / RAM, no GPU tool,
+    # no torch, no mlx. It answers Apple silicon whole. Off Apple silicon it
+    # reads every GPU as `none`, and there the accelerator decides a
+    # recommendation (an NVIDIA GPU's image pick, `by_accelerator`), so the
+    # FULL probe answers (cached for a few seconds; nvidia-smi). On the light
+    # reading alone apply-recommended, the grid and `models download
+    # --recommended` would treat a CUDA host as processor-only and never
+    # offer its image pick (framework backlog 0989). The import-time seed never comes here: it passes the light reading
+    # itself (`seed_recommended_capability_defaults`).
+    light = host_profile(light=True)
+    if light.get("accelerator") == "metal":
+        return light
+    return host_profile()
 
 
 def _full_recommendation(
@@ -698,15 +795,15 @@ def _full_recommendation(
 
     from .model_catalog import recommended_text_model
 
-    table = {key: rec for key, rec in RECOMMENDED_MODELS.items() if rec.starter or not starter_only}
+    table = {key: rec.pick_for(host) for key, rec in RECOMMENDED_MODELS.items() if rec.starter or not starter_only}
     routes = {
         key: CapabilityRouteDefault(
-            provider=rec.route.provider, model=rec.route.model, base_url=rec.route.base_url,
-            reasoning=rec.route.reasoning, options=dict(rec.route.options),
+            provider=route.provider, model=route.model, base_url=route.base_url,
+            reasoning=route.reasoning, options=dict(route.options),
         )
-        for key, rec in table.items()
+        for key, (route, _download) in table.items()
     }
-    downloads = {key: dict(rec.download) for key, rec in table.items()}
+    downloads = {key: dict(download) for key, (_route, download) in table.items()}
     pick = recommended_text_model(host, fit=False)
     routes["input.text"] = CapabilityRouteDefault(
         provider=pick["provider"], model=pick["model"], options=dict(pick.get("options") or {})
@@ -743,9 +840,11 @@ def image_input_unavailable_reason(
 def recommended_unavailable_routes(host: Optional[Mapping[str, Any]] = None) -> Dict[str, Dict[str, str]]:
     """Recommended rows this host cannot run: `{key: {provider, model, reason}}`.
 
-    On every host that is not Apple silicon `output.image` and `output.video`
-    are here (their only recommended engine, MLX-Gen, is Apple silicon only;
-    the curated catalog has no other local image or video artifact). On Apple
+    On every host that is not Apple silicon `output.video` is here (its only
+    recommended engine, MLX-Gen, is Apple silicon only), and so is
+    `output.image` except on an NVIDIA GPU, whose image pick is Diffusers
+    (`by_accelerator`; there it is here only where the catalog says it does
+    not fit the GPU's memory). On Apple
     silicon the memory-gated rows (`_FIT_GATED_ROUTES`: image, video) are here
     where the catalog says their model does not fit: `output.image` on an 8 GB
     Mac (FLUX.2 klein 4B needs ~8.5 GiB), `output.video` below 32 GiB of
@@ -837,8 +936,8 @@ def configured_routes_unavailable(
         pick = recommended.get(rec_key) if rec_key else None
         if pick is not None:
             reason = f"{reason}; this computer's recommended route is {pick.provider}/{pick.model}"
-        elif rec_key in _UNAVAILABLE_NEXT_STEP:
-            reason = f"{reason}; {_UNAVAILABLE_NEXT_STEP[rec_key]}"
+        elif _unavailable_next_step(rec_key, profile):
+            reason = f"{reason}; {_unavailable_next_step(rec_key, profile)}"
         out[key] = {"provider": provider, "model": model, "reason": reason}
     return out
 
@@ -904,6 +1003,7 @@ def recommended_model_downloads(host: Optional[Mapping[str, Any]] = None) -> Dic
 RECOMMENDED_SELECTORS: Dict[str, str] = {
     "text": "input.text",
     "voice": "output.voice",
+    "stt": "input.voice",
     "image": "output.image",
     "video": "output.video",
 }
@@ -1073,7 +1173,16 @@ def seed_recommended_capability_defaults(
     provenance marker so surfaces can label the values as recommended. The
     recommendation is this host's (Apple silicon: the unified-memory tier); a
     route this host cannot run is left unset (`recommended_unavailable_routes`).
+
+    With no `host` it reads the LIGHT host profile only: it runs when the
+    config store is first created, on import, where no GPU tool or engine may
+    load. The light reading sees no CUDA, so a fresh NVIDIA install gets no
+    image route here; `apply-recommended` (full probe) writes it.
     """
+    if host is None:
+        from ..utils.host_profile import host_profile
+
+        host = host_profile(light=True)
     for key, route in recommended_capability_default_routes(host).items():
         existing = config.routes.get(key)
         if existing is None or not existing.configured():
@@ -1086,6 +1195,56 @@ def seed_recommended_capability_defaults(
     return config
 
 
+def upgrade_recommended_seed(
+    config: CapabilityDefaultsConfig, *, host: Optional[Mapping[str, Any]] = None
+) -> bool:
+    """Add the rows later seed versions introduced to a store an earlier seed wrote.
+
+    Only a store stamped by an earlier seed (`seeded` is an older
+    `recommended-v*`) is touched, and only the rows the newer versions added
+    (`RECOMMENDED_SEED_ADDITIONS`) that are EMPTY in it: a route the operator
+    set is never replaced, and a store that was never seeded is never
+    changed. The recommendation is this host's (a row this host cannot run is
+    left unset), read from the light host profile like the seed itself. The
+    result lives in memory, stamped with the current version, exactly like a
+    fresh seed: the next save of the store persists it. Returns whether the
+    config changed.
+    """
+
+    seeded = str(config.seeded or "")
+    if not seeded.startswith("recommended-v") or seeded == RECOMMENDED_SEED_VERSION:
+        return False
+    try:
+        current = int(seeded[len("recommended-v"):])
+    except ValueError:
+        return False
+    keys = [
+        key
+        for version, added in RECOMMENDED_SEED_ADDITIONS
+        if int(version[len("recommended-v"):]) > current
+        for key in added
+    ]
+    if not keys:
+        return False
+    if host is None:
+        from ..utils.host_profile import host_profile
+
+        host = host_profile(light=True)
+    runnable = recommended_capability_default_routes(host)
+    for key in keys:
+        route = runnable.get(key)
+        existing = config.routes.get(key)
+        if route is None or (existing is not None and existing.configured()):
+            continue
+        config.routes[key] = CapabilityRouteDefault(
+            provider=route.provider, model=route.model,
+            base_url=route.base_url, reasoning=route.reasoning,
+            options=dict(route.options),
+        )
+    config.seeded = RECOMMENDED_SEED_VERSION
+    return True
+
+
 def capability_defaults_from_dict(value: Any) -> CapabilityDefaultsConfig:
     if isinstance(value, CapabilityDefaultsConfig):
         return value