---
title: "New models and runtime upgrades"
lesson_id: "04"
---

# New models and runtime upgrades

- **Lesson ID:** 04
- **Goal:** Stop new-model and upgrade breakage from reaching users.
- **Human lesson:** [04-new-models-and-upgrades.html](04-new-models-and-upgrades.html)

## Prerequisites

- Lessons 01 to 02 environment.

## Inputs, outputs, and artifacts

- **Inputs:** A model file or tag and a candidate runtime version.
- **Outputs:** PASS or FAIL from the smoke test, and a pinned version list.
- **Artifacts:** `gguf_arch.py`, `smoke_test.py`, a versions file.

## Agent build steps

1. Run `gguf_arch.py` on the GGUF and `llama-server --version`.
2. If the runtime fails with unknown architecture, try upstream llama-server before filing a bug.
3. Write the pinned runtime version and model tag plus digest to a versions file.
4. Run `uv run python smoke_test.py <model> <min_tok_s>` on the new version.
5. Run `ctx_guard.py` in the same job.
6. Upgrade only if both pass. Keep the old version for rollback.

## Constraints

Keep the language simple, friendly, and literal. No quizzes, no em dashes. Brand Edge FDE only. Use small local models. Do not invent flags, endpoints, or issue numbers. 

## Key concepts

- The runtime must know `general.architecture` to load a model.
- Ollama bundles its own llama.cpp build. Upstream can be ahead.
- Upgrades have broken loading, crashed runners, and lowered speed.
- Version pins and a smoke test turn surprises into failed CI jobs.

## Takeaways

- Read the GGUF architecture and your runtime build first.
- Pin runtime and model versions.
- Smoke test answer, load, and speed before each upgrade.

## Acceptance checks

- The smoke test fails on a wrong answer or slow speed.
- Ollama #18698, #18856, #18898, #18909, #18968 are linked.
- [ ] Return to the [course SKILL.md](SKILL.md).