synops/docs/features/prompt_lab.md

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

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

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.