Pulling models

What "pulling a model" means

A GGUF file is the model's weights packaged for llama.cpp. Pulling a model is downloading that file from a HuggingFace repository (usually the community-maintained Bartowski or LM Studio Community repos for the major open models) into your local ~/.blueprint/models/ directory.

Blueprint's catalog maps each catalog entry to a specific HuggingFace repo + per-quant file mapping (local.ggufRepo and local.ggufFiles in the model card). The Pull action picks the file matching your chosen quant and downloads it.

How the pull works

1. Resolve the URL: https://huggingface.co/{ggufRepo}/resolve/main/{ggufFiles[quant]}
2. Open an HTTP GET with a Range: header if a .part file already exists (resume).
3. Stream bytes to <dst>.part, fanning chunks through a progress callback so the UI bar moves in real time.
4. On completion, atomically rename .part → .gguf.

The atomic rename is important: a half-downloaded file never gets mistaken for a real model. If the download dies mid-way, only the .part exists; the next pull picks up from the existing byte count.

How to pull

Local

1. Plan → pick a model and quant.
2. Continue through Hardware to Deploy.
3. Click Pull model. The progress bar shows bytes / total / speed.

The download runs in a background goroutine; you can navigate away and come back without interrupting it.

To a remote host

See the Models on disk article for the remote pull workflow. The shape is the same — the difference is which machine's disk receives the file.

Resume semantics

Interrupted download? Just click Pull again for the same model + quant. Blueprint sees the .part file, sends a Range: request for the existing byte count, and HuggingFace streams the remainder.

If the partial file is corrupted (rare; happens with broken proxies that lie about Range support), delete the .part manually:

rm ~/.blueprint/models/<model-id>/*.part

Then re-pull. Blueprint starts fresh.

Common pitfalls

• Gated models on HuggingFace: Llama 3, Gemma, and a few others require accepting a license on HF before downloading. The catalog flags these with gated: true. You need a HuggingFace account with the gate accepted; Blueprint doesn't yet plumb your HF token through the pull. Workaround: pull manually via huggingface-cli download and drop the file into ~/.blueprint/models/<model-id>/.
• Slow download: HF's free tier rate-limits unauthenticated downloads. A 40 GB Q4 of a 70B model can take an hour. Run pulls overnight or use the remote-host pull to a colo'd box with a faster connection.
• Wrong quant: not every model publishes every quant. Check quantOptions in the model detail pane before picking — if Q3 isn't listed, the pull will fail with a "GGUF mapping missing" error.