OSVauco/docs/HANDOFF-LOCAL-LLM-GITEA-MCP.md

# HANDOFF-LOKAL-LLM-GITEA-MCP.md
# EGEN HANDOFF – UFRAVIKELIG STYRINGSDOKUMENT
# GJELDER FRA NÅ OG FREM TIL 100 % FERDIGSTILLELSE

## 0. STATUS OG KOMMANDO
Denne handoffen er det eneste autoritative arbeidsdokumentet for sporet "lokal LLM-fabrikk + OPAX-MCP + Gitea stabilisering + blueprinting til Gitea-VM".

---

## FREMDRIFT – OPPDATERT 2026-07-21 23:16 CEST

### ✅ FASE 0–5 — FERDIG
### ✅ FASE 6 – CPU-optimalisering — FERDIG
### ✅ FASE 6-TILLEGG – Boot-warming — FERDIG 2026-07-21 23:16 CEST

---

## LÅST SYSTEMKONFIGURASJON – GITEA-CPU-VM (komplett)

### Systemd-dropins: `/etc/systemd/system/ollama.service.d/`

```
override.conf    — OLLAMA_HOST=0.0.0.0:11434  (eksisterende, ikke rørt)
max-models.conf  — MAX_LOADED_MODELS=2 + KEEP_ALIVE=-1
warmup.conf      — ExecStartPost=/usr/local/bin/ollama-warmup.sh
```

**max-models.conf:**
```ini
[Service]
Environment="OLLAMA_MAX_LOADED_MODELS=2"
Environment="OLLAMA_KEEP_ALIVE=-1"
```

**warmup.conf:**
```ini
[Service]
ExecStartPost=/usr/local/bin/ollama-warmup.sh
```

**`/usr/local/bin/ollama-warmup.sh`:**
```bash
#!/bin/bash
sleep 10
curl -s http://localhost:11434/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"model":"gemma3:4b","prompt":"warmup","stream":false,"keep_alive":-1,"options":{"num_predict":1}}' \
  > /dev/null
curl -s http://localhost:11434/api/generate \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen2.5:3b","prompt":"warmup","stream":false,"keep_alive":-1,"options":{"num_predict":1}}' \
  > /dev/null
```

### Verifisert etter restart 2026-07-21 21:11 UTC

```
NAME          SIZE      PROCESSOR    CONTEXT    UNTIL
gemma3:4b     2.9 GB    100% CPU     4096       Forever
qwen2.5:3b    2.2 GB    100% CPU     4096       Forever
Mem: 15Gi | 6.8Gi used | 8.9Gi available | Swap: 0B
```

Merk: `warmup.conf` bruker eget skript — ikke inline JSON i ExecStartPost. Direkte inline førte til 400-feil p.g.a. systemd-escaping av anførselstegn.

### Operative parametere for Emma-kall

```
num_ctx            = 2048
num_batch          = 256   (Ollama default)
OLLAMA_NUM_THREADS = ikke satt (autodetect)
```

### Ytelsesbudsjett per Emma-turn (varm)

```
3-kall turn:   ~23.5s
5-kall turn:   ~42.5s
Boot-penalty:  ~0s etter restart (warmup-skript laster begge modeller automatisk)
Tok/s:         4.9–5.0 (gemma3:4b)
```

---

## FASE 6 – KOMPLETT RESULTATOVERSIKT

### 6.1 Kaldstart / keep_alive baseline
| Modell | Kaldstart | Varm | Tok/s |
|---|---|---|---|
| gemma3:4b | 117.69s | ~1.0s | 4.9–5.0 |
| qwen2.5:3b | 71.13s | ~1.0s | 6.4 |

### 6.2 Resident modell-strategi
Låst: MAX=2 + KEEP_ALIVE=-1 systemd. MAX=1 gir 20–54s ekstra per Emma-turn.

### 6.3 Parameter-matrise
| num_ctx | num_batch | tok/s | Delta |
|---|---|---|---|
| 1024 | 256 | 4.9 | baseline |
| **2048** | **256** | **5.0** | **+0.1 ✅** |
| 4096 | 256 | 4.3 | -14% ⚠️ |

Threads: ingen målbar forskjell på 4 vCPU — ikke satt.

### 6.4 Emma MCoT end-to-end
| Scenario | Tid |
|---|---|
| Første turn etter boot (uten warmup) | 102.34s |
| **Varm turn (5 kall)** | **42.51s ✅** |

### 6.5 Belastningstest (20 turns × 3 kall)
| Måling | Verdi |
|---|---|
| Snitt per turn | 23.5s |
| Min/max | 23.2s / 25.2s |
| Swap | 0 MB hele testen |
| OOM | Ingen |
| RAM-vekst | +293 MB (OS page cache) |

### 6-tillegg Boot-warming
- Rotproblem: `ExecStartPost` med inline JSON → systemd-escaping → 400-feil
- Løsning: dedikert skript `/usr/local/bin/ollama-warmup.sh`
- Resultat: begge modeller Forever innen ~3 min etter `systemctl restart ollama`

---

## ÅPNE PUNKTER SOM MÅ LØSES FØR ENDELIG BLUEPRINT
1. `GITEA_URL` satt runtime — **må legges permanent inn i `opax-mcp.yaml` og rebuildes**
2. `git.vauco.no` erstatter IP når DNS er oppe
3. Gitea-commits ikke GPG-signert — vurder

## FASTE SANNHETER (uendret)
- Gitea er source of truth
- Lokale modeller er hovedretning
- Gitea-VM (34.67.252.59) er planlagt permanent målmaskin
- Denne handoffen overstyrer alt annet

## DEFINITION OF DONE
- ✅ Lokale modeller lever og kan brukes lokalt
- ✅ OPAX-MCP bruker lokal modellbackend korrekt
- ✅ `list_emma_models` er grønn
- ✅ Gitea read-only tools er grønne
- ✅ GCP/Workspace-kjernen er fortsatt grønn
- ⚠️ Konfigurasjon konsolidert — delvis (GITEA_URL må inn i repo)
- ⏳ Ingen skjult API-/agentavhengighet som hovedbane — ikke verifisert
- ✅ dev-snap-oppsettet dokumentert godt nok til blueprinting
- ✅ CPU-optimalisering verifisert på Gitea-VM — FERDIG
- ✅ Boot-warming verifisert — begge modeller Forever etter restart

## OPPDATERINGSLOGG
| Dato | Fase | Handling |
|---|---|---|
| 2026-07-21 | FASE 4 | Full smoke test grønn, alle 8 tools OK |
| 2026-07-21 | FASE 5 | Blueprint frosset |
| 2026-07-21 | FASE 6.1 | Kaldstart/keep_alive: gemma3=117s, qwen=71s, keep_alive=-1 bevist |
| 2026-07-21 | FASE 6.2 | Resident strategi: MAX=2 + KEEP_ALIVE=-1 systemd |
| 2026-07-21 | FASE 6.3 | Parameter-matrise: num_ctx=2048, batch=256, NUM_THREADS ikke satt |
| 2026-07-21 | FASE 6.4 | Emma MCoT: varm turn=42.51s (5 kall) |
| 2026-07-21 | FASE 6.5 | Belastningstest: 20 turns, 23.5s/turn, Swap=0, ingen OOM |
| 2026-07-21 | FASE 6 | FASE 6 LUKKET — alle 5 exit-kriterier bestått |
| 2026-07-21 | Boot-warming | ollama-warmup.sh verifisert: begge modeller Forever etter restart, Swap=0 |