vegard
00bf5d27ce
Grunnleggende arkitekturbeslutninger tatt og dokumentert: - Alt er noder (brukere, team, innhold, mediefiler, samlings-noder) - Edges definerer hva en node er (freeform typer, metadata i JSONB) - Materialisert tilgangsmatrise (node_access) erstatter workspace-RLS - Visibility (hidden/discoverable/readable/open) på noder - Aliaser via usynlige system-edges - Maskinrommet eier all skriving (SpacetimeDB først, PG asynk) - SpacetimeDB holder hele grafen, PG er persistent backup - Node- og edge-skjema spesifisert (docs/primitiver/) Fjernet workspace-konseptet fra hele dokumentasjonen (~40 filer). Fem retninger besluttet, én åpen (rom, ikke forum). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
103 lines
4.8 KiB
Markdown
103 lines
4.8 KiB
Markdown
# 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.
|