Model run (`model-run`)

Paste a Hugging Face model URL, get a measured answer: the best installed runtime downloads the model, generates a bounded sample, and prints the command that keeps the session going. The executor half of model-check — the checker’s verdict is a prediction; model-run turns it into evidence with a real load.

Spec: GitHub issue #157. Implementation: native-mac/Sources/TinyGPTRun/ (runner planning + bounded subprocesses), TinyGPT/ModelRun.swift (CLI shim).

posttrainllm model-run Qwen/Qwen3-0.6B
posttrainllm model-run Qwen/Qwen3-0.6B-GGUF
posttrainllm model-run <url> --chat --prompt "hi" --max-tokens 64
posttrainllm model-run <url> --runtime native|mlx-swift|mlx-lm|ollama|lms|llama-cli

Flow

model-check report (real check, full machinery)
  → gated?            stop unless HF_TOKEN is set, name the fix
  → RunnerPlanner     ordered candidates from formats + verdict +
                      which runtimes probe as installed
  → execute each      bounded subprocess: timeout, captured output,
                      killed on expiry; failure falls through to the
                      next candidate — a runtime that probes as
                      installed can still be broken
  → verify + handoff  "ran on <runtime> — verified, not predicted"
                      + the exact command to keep chatting

Runner table

Repo shape	Order
safetensors + checked path OK	native `hf-load` → mlx-swift → mlx-lm
safetensors + checked path failed	mlx-swift → mlx-lm (native could load wrong)
GGUF	ollama → lms → llama-cli
gated, no HF_TOKEN	none — names the license + token step

mlx-swift is the posttrainllm-mlxrun sibling executable — Apple’s MLX-Swift-LM implementations (LLM/VLM/embedders) running in their own process. It beats python mlx-lm as the wide-table alternative because there is no env to break: a partial python install probes fine then dies mid-import. Build it with cd native-mac && swift build --product posttrainllm-mlxrun; the probe checks for the binary beside posttrainllm or on PATH.

GGUF is never routed to native: gguf-load validates structure only — it cannot generate. Unknown/unsupported architectures stay off native for the same reason: a wrong-architecture load can fail silently.

Ollama’s hf.co pull chokes on HF’s Xet-CDN cross-host redirects, so when it fails and the checker selected a GGUF variant, model-run downloads the file with its own downloader and ollama creates a posttrainllm-<variant> Modelfile — the local model is what the “keep chatting” hint prints.

Cleanup contract

model-run never leaves a process running: a spawned ollama serve is terminated after the run, an lms-loaded model is unloaded, every subprocess has a hard timeout. Models stay downloaded — to the posttrainllm cache (~/.cache/posttrainllm/models/<id>), the HF cache (mlx-lm, llama-cli), or LM Studio’s store (lms get).

Environment realities observed (2026-09-22, this Mac)

The fallthrough exists because installed ≠ working — all three of these were hit live while building the feature:

ollama run hf.co/… → blocked redirect to a different host — ollama 0.34.2 refuses the Xet-bridge CDN redirect most HF repos now issue. Worked around: direct download + ollama create (Modelfile).
lms load → No LM Runtime found for model format 'gguf' — the LM Studio install lacked a GGUF runtime plugin.
python3 -m mlx_lm → ModuleNotFoundError: huggingface_hub — the dist was present but broken; metadata probing can’t see that, which is why the compiled mlx-swift sibling is preferred.

llama-cli’s own -hf downloader completed the same pull ollama refused, so GGUF repos still reach a verified run on this machine.

Model run (`model-run`)