# Feature: Prompt-Laboratorium
**Filsti:** `docs/features/prompt_lab.md`

> **NB:** Dette dokumentet er en skisse fra v1 og må oppdateres til node/edge-modellen ved implementering.

## 1. Konsept
Et internt kvalitetssikringsverktøy der redaksjonen kan teste, sammenligne og godkjenne LLM-prompts mot faktiske data fra egen samlings-node — før de ruller ut i produksjon. Integrert med AI Gateway (LiteLLM) og Promptfoo-testsettene.

## 2. Problemet det løser
- Modellkvalitet på norsk varierer kraftig mellom leverandører og versjoner.
- Leverandører oppdaterer modeller uten varsel — kvaliteten kan degraderes over natten.
- Redaksjonen må kunne verifisere at en prompt fungerer *med deres data* (transkripsjoner, artikler, aktørnavn) før den settes i produksjon.
- I dag krever prompt-testing kommandolinje og Promptfoo — det bør være tilgjengelig i nettleseren.

## 3. Brukeropplevelse

### 3.1 Playground (Ad-hoc testing)
1. Bruker velger en **jobbtype** (research_clip, whisper_postprocess, metadata_extract, dictation_cleanup, etc.).
2. Systemet laster inn gjeldende system-prompt fra samlings-nodens metadata.
3. Bruker kan redigere prompten i et tekstfelt.
4. Velger **testdata**: enten paste inn tekst manuelt, eller velg fra faktiske transkripsjoner/artikler brukeren har tilgang til.
5. Velger **modeller** å teste mot (f.eks. `sidelinja/rutine` + `sidelinja/resonering`).
6. Kjører testen — ser resultatene side-om-side.
7. Kan iterere: endre prompten, kjør igjen, sammenlign.

### 3.2 Batch-evaluering (Promptfoo-integrasjon)
1. Bruker velger et lagret **testsett** (fra `tests/prompts/` i Git).
2. Kjører testsettene mot valgte modeller via AI Gateway.
3. Ser en matrise: testcase × modell × resultat, med pass/fail-markering.
4. Kan sammenligne mot tidligere kjøringer for å oppdage regresjoner.

### 3.3 Deploy
Når en prompt er verifisert:
1. Bruker klikker "Deploy".
2. Prompten skrives til samlings-nodens metadata (`metadata.llm_prompts[jobbtype]`).
3. Alle fremtidige jobber av den typen bruker den nye prompten.
4. Tidligere prompt lagres i en `prompt_history`-logg for rollback.

## 4. Teknisk arkitektur

### 4.1 Datamodell

```sql
prompt_test_runs (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    context_node  UUID NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,  -- samlings-node
    job_type      TEXT NOT NULL,
    system_prompt TEXT NOT NULL,
    model_alias   TEXT NOT NULL,
    input_text    TEXT NOT NULL,
    output_text   TEXT,
    tokens_used   INTEGER,
    latency_ms    INTEGER,
    created_by    TEXT NOT NULL REFERENCES users(authentik_id),
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX idx_prompt_runs_context ON prompt_test_runs(context_node, job_type, created_at DESC);
```

`prompt_test_runs` er **ikke** en node i grafen — det er en intern verktøytabell for utviklere/redaktører.

### 4.2 Prompt-historikk

```sql
prompt_history (
    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    context_node  UUID NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,  -- samlings-node
    job_type      TEXT NOT NULL,
    system_prompt TEXT NOT NULL,
    deployed_by   TEXT NOT NULL REFERENCES users(authentik_id),
    deployed_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

Muliggjør rollback: "forrige prompt for research_clip fungerte bedre, rull tilbake."

### 4.3 Kjøring
- **Ad-hoc tester:** SvelteKit server-side sender request direkte til AI Gateway (`http://ai-gateway:4000/v1`) med brukerens prompt og testdata. Resultatet returneres synkront.
- **Batch-evaluering:** Oppretter en `prompt_eval`-jobb i jobbkøen. Rust-worker kjører testsettene mot AI Gateway og lagrer resultatene.

## 5. Dataklassifisering

| Data | Kategori | Detaljer |
|---|---|---|
| Test-kjøringer | Flyktig (TTL 90 dager) | For analyse, ryddes automatisk |
| Prompt-historikk | Kritisk (PG) | Muliggjør rollback |
| Testsett (Promptfoo) | Gjenskapbar (Git) | `tests/prompts/` — versjonskontrollert |

## 6. Jobbtyper

| Jobbtype | Modellalias | Beskrivelse |
|---|---|---|
| `prompt_eval` | (varierer) | Batch-evaluering av testsett mot valgte modeller |

## 7. Instruks for Claude Code
* Prompt Lab er et admin-verktøy — krev admin-tilgang til samlings-noden.
* Ad-hoc tester kjøres synkront (SvelteKit → AI Gateway → respons). Ikke bruk jobbkø for enkelt-tester.
* Batch-evaluering kjøres via jobbkø for å unngå timeouts.
* Vis alltid token-bruk og latens — dette er et kostnadsbevisst verktøy.
* Testdata (transkripsjoner, artikler) lastes via SvelteKit server-side fra PG. Gjesten-UX vises aldri her.
* `prompt_test_runs` og `prompt_history` er knyttet til en samlings-node og trenger ikke RLS — de er kun tilgjengelige for admins via applikasjonslogikk.
* Tilgang styres via `node_access`-matrisen.
