# 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 22:41 CEST

### ✅ FASE 0 – Lås situasjonen — FERDIG
- Handoff opprettet som eget dokument
- dev-snap/GPU-VM er aktiv verifikasjonsbase
- Gitea er eneste source of truth
- Lokal LLM-bane er primær retning

### ✅ FASE 1 – Lokale modeller lever — FERDIG
- Ollama kjører på Gitea-CPU-VM (34.67.252.59:11434)
- Modeller tilgjengelig via MCP: `gemma3:4b`, `qwen2.5:3b`
- Modeller på dev-snap localhost: `qwen2.5:7b`, `gemma3:4b`, `llama3.2`, `nomic-embed-text`
- `list_emma_models` via MCP: GRØNN ✅

### ✅ FASE 2 – MCP peker korrekt til lokal modellsti — FERDIG
- `OLLAMA_BASE_URL` peker til Gitea-CPU-VM Ollama
- `OSVAUCO_AGENT_URL` fikset til kanonisk URL (commit a171a58)
- opax-mcp revisjon: opax-mcp-00122-m4n

### ✅ FASE 3 – Gitea read-only grønn — FERDIG
- Alle 4 read-only tools GRØNNE
- `get_connector_status`: `gitea_status: online` ✅

### ✅ FASE 4 – Hel kjede samtidig grønn — FERDIG 2026-07-21 20:57 CEST
- Full smoke test: alle 8 tools grønne samtidig

### ✅ FASE 5 – Frys blueprint på dev-snap — FERDIG
- Blueprint dokumentert i `docs/BLUEPRINT-DEV-SNAP.md`

### ⏳ FASE 6 – CPU-optimalisering før permanent migrering — PÅGÅR

Bekreftede regler (låst etter testing):
- `OLLAMA_KEEP_ALIVE=-1` ✅ BEVIST og satt på systemd-nivå
- `OLLAMA_MAX_LOADED_MODELS=2` ✅ LÅST
- `num_ctx=2048`, `num_batch=256` ✅ LÅST
- `OLLAMA_NUM_THREADS` skal IKKE settes — Ollama autodetect er optimal
- `qwen2.5:7b` er ikke baseline-kandidat på gitea-cpu-vm
- CPU-optimalisering utføres direkte på gitea-cpu-vm

Testrekkefølge:
1. ✅ Kaldstart / keep_alive baseline — FERDIG 2026-07-21
2. ✅ Resident modell-strategi (1 vs 2 modeller) — FERDIG 2026-07-21
3. ✅ Parameter-matrise (num_ctx, num_batch, OLLAMA_NUM_THREADS) — FERDIG 2026-07-21
4. ⏳ Full Emma MCoT end-to-end
5. ⏳ Belastningstest med samtidig Gitea + agent-last

Exit-kriterium:
- ✅ keep_alive-strategi bevist effektiv
- ✅ resident modellvalg låst: MAX_LOADED_MODELS=2, begge Forever
- ✅ optimal parameterkombinasjon dokumentert
- ⏳ full Emma-loop latency akseptert
- ⏳ 2-timers belastningstest bestått uten OOM og uten swap

---

## FASE 6.1 – KALDSTART / KEEP_ALIVE BASELINE — RESULTATER 2026-07-21

Kjørt på: **gitea-cpu-vm** (34.67.252.59) — ekte CPU, ingen GPU

| Test | Modell | load_s | tok/s | Status |
|---|---|---|---|---|
| 1.1 Ekte kaldstart | gemma3:4b | **117.69s** | 4.9 | ✅ |
| 1.2 Ekte kaldstart | qwen2.5:3b | **71.13s** | 6.4 | ✅ |
| 1.3 keep_alive=-1 load | gemma3:4b | 76.93s | 5.9 | ✅ |
| 1.4 UNTIL=Forever | gemma3:4b | Forever ✅ | — | ✅ |
| 1.5 Varme kall ×5 | gemma3:4b | ~1.0s load | ~5 | ✅ |

**Konklusjoner:** keep_alive=-1 eliminerer 117s kaldstart fra kall 2+. Varme kall ~2s/kall = 8–12s per Emma-turn.

---

## FASE 6.2 – RESIDENT MODELL-STRATEGI — RESULTATER 2026-07-21

| Test | Konfigurasjon | Resultat | Status |
|---|---|---|---|
| 2.1 Begge uten MAX-begrensning | Default | Begge i RAM, Swap=0 | ✅ |
| 2.3 Bytte med MAX=1 | MAX_LOADED_MODELS=1 | gemma3 reload 9.31s / qwen 5.6s | ✅ |
| 2.4 Begge med MAX=2 | MAX=2 + KEEP_ALIVE=-1 | Begge Forever, 6.8 GB, Swap=0 | ✅ |

**✅ LÅST:** `OLLAMA_MAX_LOADED_MODELS=2` + `OLLAMA_KEEP_ALIVE=-1` i systemd.
Begrunnelse: MAX=1 gir 20–54s ekstra latency per Emma-turn. MAX=2 gir 0s bytte-overhead, trygg RAM-margin.

---

## FASE 6.3 – PARAMETER-MATRISE — RESULTATER 2026-07-21

Kjørt på: **gitea-cpu-vm** (34.67.252.59) — gemma3:4b, 3 kjøringer per rad, snitt tok/s
VCPU: 4

### num_ctx / num_batch

| Rad | num_ctx | num_batch | avg tok/s | Delta |
|---|---|---|---|---|
| 3.1 | 1024 | 256 | 4.9 | baseline |
| 3.2 | **2048** | **256** | **5.0** | +0.1 ✅ VINNER |
| 3.3 | 4096 | 256 | 4.3 | -0.7 ⚠️ |
| 3.4 | 2048 | 128 | 4.9 | -0.1 |
| 3.5 | 2048 | 512 | 4.8 | -0.2 |

### num_threads

| threads | tok/s | Delta |
|---|---|---|
| 2 | 4.9 | — |
| 3 | 4.9 | 0 |
| 4 | 4.8 | -0.1 |

### ✅ PARAMETERKONFIGURASJON LÅST

```
num_ctx            = 2048   (default for Emma-turns)
num_batch          = 256    (Ollama default, ikke nødvendig å sette eksplisitt)
OLLAMA_NUM_THREADS = ikke satt (Ollama autodetect er optimal på 4 vCPU)
```

**Konklusjoner:**
1. `num_ctx=2048` er beste balanse mellom kontekstlengde og ytelse
2. `num_ctx=4096` er -14% tregere — bruk kun eksplisitt ved lange samtaler
3. `num_batch` gjør ingen målbar forskjell på CPU — 256 er fin default
4. `OLLAMA_NUM_THREADS` gjør ingen målbar forskjell — skal ikke settes
5. Maskinens tak for gemma3:4b er stabilt **4.9–5.0 tok/s**

### Tilstand før Fase 6.4

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

---

## ÅPNE PUNKTER SOM MÅ LØSES FØR BLUEPRINT
- `GITEA_URL` satt runtime via `gcloud run services update` — **må også legges permanent inn i `opax-mcp.yaml` i repo og rebuildes**
- `git.vauco.no` er planlagt som permanent domene for Gitea — erstatter IP når DNS er oppe
- Gitea-commits er ikke GPG-signert — vurder om dette skal fikses

## FASTE SANNHETER (uendret)
- Gitea er source of truth
- Lokale modeller er hovedretning
- dev-snap/GPU-VM er nåværende verifikasjonsflate
- 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 — FASE 5 FERDIG
- ⏳ CPU-optimalisering verifisert på Gitea-VM — FASE 6 pågår

## 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, FASE 5 lukket |
| 2026-07-21 | FASE 6 | FASE 6 åpnet — CPU-optimalisering neste |
| 2026-07-21 | FASE 6.1 | Kaldstart/keep_alive: gemma3=117s, qwen=71s, varme kall ~2s, keep_alive=-1 bevist effektiv |
| 2026-07-21 | FASE 6.2 | Resident strategi låst: MAX=2 + KEEP_ALIVE=-1 systemd, begge Forever, RAM OK |
| 2026-07-21 | FASE 6.3 | Parameter-matrise låst: num_ctx=2048, num_batch=256 (default), OLLAMA_NUM_THREADS ikke satt. Maskintak: 5.0 tok/s |