# Jetson AI / Ollama — Design & Betriebskonzept

Selbst gehostetes **LLM-System auf einem Jetson Orin Nano Super (8 GB)**: Der
Ollama-Daemon serviert mehrere Modellprofile über eine OpenAI-kompatible API, ein
schlanker Exporter-Sidecar exponiert `/metrics` für Prometheus. Der Modellwechsel
passiert **nativ über den Modellnamen** — bewusst ohne eigenen Swapper und ohne
API-Gateway.

Dieses Repo enthält **Architektur, Betriebsvertrag und Designentscheidungen** des
Systems. Die Ansible-Implementierung lebt im Schwester-Repo `ansible-eulernest`
(Rollen `jetson_bootstrap`, `ollama`, `ollama_exporter`) — die Box läuft dort
produktiv auf JetPack 7.2.

---

## Modellprofile

Vier Profile, aber nie zwei gleichzeitig resident — das ist der Kern des
8-GB-Konzepts (~7,4 GB nutzbar):

| Profil | Basismodell | `num_ctx` | Zweck |
|---|---|---|---|
| `qwen-light` | `qwen2.5:7b` | 16384 | Daily Driver, Chat |
| `gemma` | `gemma3:4b` | 16384 | Kreativ, multimodal |
| `qwen-heavy` | `deepseek-r1:7b` | 8192 | Harte Reasoning-Fälle |
| `coder` | `qwen2.5-coder:7b` | 16384 | CI-Bot, PR-Review |

`OLLAMA_MAX_LOADED_MODELS=1` hält genau ein Modell im Speicher; weitere Profile
laden on-demand. Dadurch sind vier Profile auf 8 GB praktisch kostenlos.

## Optimierung

- **`q8_0`-KV-Cache + Flash Attention** — deutlich geringerer Speicherbedarf pro
  Kontextfenster.
- **`num_ctx` je Profil explizit gesetzt**, da Ollama den Kontext sonst still kürzt.
- **`OLLAMA_KEEP_ALIVE=30s`** — bewusster Trade-off: kurze Ladezeit beim
  Profilwechsel gegen dauerhaft freien Speicher (Single-User, keine fremden
  Sessions werden unterbrochen).

## Architekturentscheidungen (ADRs)

Jede wesentliche Entscheidung ist als ADR mit Kontext, Entscheidung und Konsequenz
dokumentiert — inklusive der bewusst *nicht* gewählten Alternativen:

| ADR | Entscheidung |
|---|---|
| [0001](docs/adr/0001-record-architecture-decisions.md) | Architekturentscheidungen als ADRs festhalten |
| [0002](docs/adr/0002-ollama-native.md) | Ollama-natives Modell-Management statt eigenem Swapper/Gateway |
| [0003](docs/adr/0003-registry-pull-over-gguf.md) | Registry-Pull statt manueller GGUF-Verwaltung |

## Betrieb, Daten & Sicherheit

- **Observability:** Exporter-Sidecar liefert `/metrics`; Aggregation in
  Prometheus/Grafana läuft bewusst off-box.
- **Modell-Daten:** DVC ist Source of Truth, Ollamas Blob-Store nur Laufzeit-Cache.
- **Zugriff:** Ollama bringt keine eigene Authentifizierung mit → Bind nur ans LAN,
  vorgelagerter nginx-Reverse-Proxy mit TLS und OAuth, Firewall auf den Proxy.
- **Secrets:** ausschließlich über Ansible-Vault, nie im Klartext im Repo.

Die vollständige Schnittstelle zwischen den Komponenten steht in
[`CONVENTIONS.md`](CONVENTIONS.md).

---

## Arbeitsmodell

Das Repo wurde aus einem **agent-swarm-Template** gebootstrapt: ein Leader/Worker-
Modell für KI-gestützte Entwicklung, dessen Stand vollständig auf Disk lebt und
damit ohne Vorkontext kalt lesbar ist. Automatische Gates (`scripts/gate-*.sh`)
prüfen Datei-Ownership, Repo-Hygiene und Doku-Drift bei jedem Schritt.

| Wo | Datei |
|---|---|
| Stand & nächster Schritt | [`STATE.md`](STATE.md) |
| Plan / Board (DAG) | [`ROADMAP.md`](ROADMAP.md) |
| Gemeinsamer Vertrag | [`CONVENTIONS.md`](CONVENTIONS.md) |
| Kalt-Review-Einstieg | [`REVIEW.md`](REVIEW.md) |
| Methodik | [`docs/methodology.md`](docs/methodology.md) |