# Choosing a model

PRIOR runs **one model per container**, and you supply the generation model as a **GGUF**. The file is
mounted at runtime, not baked into the image (weights are large and shared). This page covers which
models are supported, how to pick one, and the exact command to fetch a recommended quickstart model.

---

## The model registry

PRIOR ships a **model registry** (baked into the engine) that maps each supported GGUF to its
calibrated steering parameters and grades it. The registry spans **dense, mixture-of-experts and
hybrid-SSM builds up to 31B** and grows as models are calibrated, so it is deliberately not
enumerated here; the live, machine-readable list is public at
[eagle-logic.com/models](https://eagle-logic.com/models) (and at
[/model-registry.json](https://eagle-logic.com/model-registry.json)).

When you mount a GGUF whose **filename matches a registry entry**, the engine resolves that model's
calibration automatically and runs it at its graded tier. Check what resolved:

```bash
curl -s http://localhost:8089/admin/model -H "Authorization: Bearer <admin-key>"
# -> model_key, tier: certified | beta
```

> **The filename matters.** The engine matches the mounted GGUF's name to the registry. Keep the
> registry filename (e.g. `Qwen3-8B-Q4_K_M.gguf`); a renamed file or a different quantization falls
> back to **beta** defaults rather than the calibrated values.

---

## ⚠️ GGUF support is not guaranteed for every model

The **gate** (policy detection) works on any model you load. **Steering is different.** It operates
on a model's internal geometry, so its quality is **model- and architecture-specific** and must be
validated per model. We grade every model by that validation:

| Tier | What it means | Steering |
|---|---|---|
| **Certified** | Calibration swept and validated. | Reliable; matches the published behavior. |
| **Beta** | Runs, but calibration is default or not yet swept. | Weak or unpredictable; use with care. The gate still works. |
| **Unsupported** | Some architectures don't steer well (or at all) yet. | Not recommended for the safety use-case. |

The grade is the honest signal: a **certified** model steers cleanly, while an unsupported one
effectively doesn't (the gate still routes and flags, but forced refusals won't hold). Do **not**
assume an arbitrary GGUF off Hugging Face will steer; start from the certified list below.

---

## Recommended models

Certified picks (4-bit `Q4_K_M`):

| Model | Approx. size | Grade | Best for |
|---|---|---|---|
| **Llama-3.2-3B-Instruct** | ~2 GB | Certified | The quickstart default: fast, runs on a modest GPU, cleanest steering. |
| **Qwen3-8B** | ~5 GB | Certified | More capable, still light on VRAM. |
| **Qwen3-4B-Instruct-2507** | ~2.5 GB | Certified | A strong 4B middle ground. |
| **Meta-Llama-3.1-8B-Instruct** | ~5 GB | Reference | The model **all our published benchmarks use**; pick this to reproduce our numbers. |

Also certified: Llama-3.2-1B (~0.8 GB) for the smallest footprint, both Mistral-Nemo-12B builds, the
Qwen3-Next hybrid class, Phi-4 and Phi-4-mini, Ministral-3, a DeepSeek-R1 14B distill, and both 12B
Gemma builds (Gemma-3-12B and Gemma-4-12B). Qwen3-14B, the smaller Gemma-3/4 builds, and SmolLM3 are
currently **beta** for steering; load them for the gate, not for reliable refusals.

---

## Fetch a model (one command)

Use the Hugging Face CLI. The **default quickstart** (Llama-3.2-3B, ~2 GB):

```bash
pip install -U "huggingface_hub[cli]"

huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF \
  Llama-3.2-3B-Instruct-Q4_K_M.gguf --local-dir ./models
```

Or the more capable Qwen3-8B (~5 GB):

```bash
huggingface-cli download Qwen/Qwen3-8B-GGUF \
  Qwen3-8B-Q4_K_M.gguf --local-dir ./models
```

> Repos occasionally move. If a download 404s, search Hugging Face for the model's official GGUF
> release or a reputable uploader (e.g. `bartowski/…-GGUF`), and keep the **exact filename** shown in
> the recommended table so the registry match holds.

---

## Run it

```bash
docker run -d --name prior --gpus all -p 127.0.0.1:8089:8089 \
  -e PRIOR_NATIVE_MODEL=/models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -v "$(pwd)/models:/models:ro" \
  -v "$(pwd)/license.bin:/app/license.bin:ro" \
  ghcr.io/eagle-logic/prior:slim
```

Then confirm the registry resolved it as **certified** (`GET /admin/model` above), and you're done.
See **[Getting Started](getting-started.md)** for the first requests.

---

## Help grow the registry

Bringing a model that isn't certified yet? Calibrate it in the WebUI (**Configuration → Steering
model → Auto-calibrate**). If you opt in, **Share calibration** sends the result (a small,
**non-PII** payload: the model name and its calibrated steering parameters) to Eagle Logic. After we verify it,
the model joins the certified registry for everyone. See the
**[WebUI Operator Guide](webui.md)**.