From 77e3d59b464cececdf29cd244e9efb99e32f23f1 Mon Sep 17 00:00:00 2001 From: vegard Date: Wed, 18 Mar 2026 16:40:34 +0000 Subject: [PATCH] Orkestrering: AI kun ved oppretting, eventually-modus for Claude Code MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fundamentalt restrukturert: - AI genererer script ved oppretting, ikke ved kjøring - Vaktmesteren validerer script før lagring (verktøy finnes? variabler ok?) - Systemprompt bygges automatisk fra cli_tool-noder i PG - Kjøring er alltid deterministisk script, ingen AI - Feil → work_item, ikke AI-eskalering - "Eventually"-modus: forespørsel lagres, Claude Code (betalt) genererer script i neste sesjon med Opus — ingen API-kostnad, bedre kvalitet, ingen hastverk Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/concepts/orkestrering.md | 185 ++++++++++++++++++++++++---------- 1 file changed, 132 insertions(+), 53 deletions(-) diff --git a/docs/concepts/orkestrering.md b/docs/concepts/orkestrering.md index e8768d5..5022db5 100644 --- a/docs/concepts/orkestrering.md +++ b/docs/concepts/orkestrering.md @@ -79,57 +79,124 @@ Enkelt nok til å parse med en liten Rust-parser i vaktmesteren. Deterministisk, gratis, raskt. **De fleste produksjons- orkestreringer vil være på dette nivået.** -### Nivå 2: Fritekst med AI-tolkning +### Nivå 2: AI-assistert oppretting -Naturlig språk som boten tolker og utfører steg for steg -med function calling. For orkestreringer der stegene ikke -er helt forutsigbare. +Brukeren beskriver hva de vil i naturlig språk. AI genererer +et deklarativt script (nivå 1) som vaktmesteren validerer. +**AI brukes ved oppretting, ikke ved kjøring.** ``` -Når en innspilling i en samling med podcast-trait avsluttes: +Bruker: "Gjør episoden klar for publisering" -1. Transkriber lydfilen med stor modell -2. Generer oppsummering -3. Foreslå kapitler basert på transkripsjonen -4. Generer show notes -5. Oppdater RSS-feed + → synops-ai genererer script-forslag: -Hvis transkribering feiler, prøv igjen med medium modell. -Hvis RSS feiler, opprett en oppgave. + NÅR innspilling.avsluttet + HVIS samling.har_trait("podcast") + 1. synops-transcribe --cas-hash {event.cas_hash} --model large + VED_FEIL: synops-transcribe --cas-hash {event.cas_hash} --model medium + 2. synops-summarize --communication-id {event.communication_id} + 3. synops-rss --collection-id {event.collection_id} + VED_FEIL: work_item "Pipeline feilet" --tag bug + + → Vaktmesteren validerer: + ✓ Alle verktøy finnes + ✓ Alle variabler er gyldige + ✓ Syntaks er korrekt + + → Bruker godkjenner eller justerer + → Lagres som orchestration-node (nivå 1) ``` -Boten mapper "transkriber lydfilen" → `synops-transcribe`, -"oppsummer" → `synops-summarize`, osv. Krever LLM-kall -per kjøring (Haiku er nok for de fleste). +Etter oppretting kjører scriptet uten AI — deterministisk, +gratis, raskt. AI-kostnaden er én gang, ved oppretting. ### Nivå 3: Drømmemodus Brukeren skriver hva de *ønsker*, uten å vite hvilke verktøy -som finnes. Boten prøver, og mangler som oppdages blir -feature requests. +som finnes. AI prøver å generere et script, og mangler +som oppdages blir feature requests. ``` -Gjør episoden klar for publisering. Lag en lydfil med -sammendrag og send den til alle deltakere. +Bruker: "Lag en lydfil med sammendrag og send til deltakerne" + + → synops-ai genererer: + 1. synops-summarize --communication-id {event.communication_id} + 2. synops-tts ??? ← finnes ikke + + → Vaktmesteren validerer: + ✗ synops-tts finnes ikke + + → Tilbake til bruker: + "Scriptet refererer til synops-tts som ikke finnes. + Jeg oppretter en forespørsel om TTS-verktøy." + → work_item "TTS for møteoppsummeringer" --tag feature + → Delvis script lagres med synops-tts markert som manglende ``` -Boten sjekker tilgjengelige verktøy, gjør det den kan, -og oppretter work_items for det som mangler. +### Systemprompt for script-generering + +AI-modellen trenger kontekst for å generere gode scripts. +`synops-orchestrate --generate-system-prompt` bygger dette +automatisk fra PG: + +``` +Du er en orkestreringsplanlegger for Synops. + +TILGJENGELIGE VERKTØY: +- synops-transcribe: Whisper-transkribering + Bruk: --cas-hash --model +- synops-summarize: AI-oppsummering + Bruk: --communication-id +- synops-rss: RSS-generering + Bruk: --collection-id +[... hentet fra cli_tool-noder i PG] + +SCRIPT-GRAMMATIKK: + NÅR [HVIS ] + . + VED_FEIL: | work_item [--tag <tag>] + Variabler: {event.<felt>}, {input.<felt>} + +EKSEMPLER: +[... hentet fra eksisterende orchestration-noder] + +Svar KUN med et gyldig orkestreringscript. +``` + +Systemprompt oppdateres automatisk når nye verktøy legges til. +Fungerer med alle modeller — Claude, Llama, Mixtral, Grok. + +### Tre-stegs flyten + +``` +1. OPPRETTING (AI, én gang) + Bruker beskriver → synops-ai genererer script + → vaktmester validerer → bruker godkjenner → lagres + +2. KJØRING (ingen AI, hver gang) + Trigger → vaktmester parser script → utfører CLI-kall + → logger resultat + +3. FEILHÅNDTERING (AI, sjelden) + VED_FEIL feiler → eskalér til synops-ai + → foreslå fix eller opprett work_item +``` + +AI-kostnad er nesten null i drift. ### Naturlig progresjon ``` Drømmemodus → Bruker beskriver ønsket resultat - ↓ AI foreslår -Fritekst → Bruker justerer steg i naturlig språk - ↓ AI foreslår kompilering etter N kjøringer -Script → Deklarative CLI-kall, ingen AI - ↓ manuelt + ↓ AI genererer script-forslag +Script → Vaktmester validerer, bruker godkjenner + ↓ Kjører uten AI +Produksjon → Deterministisk, gratis, raskt + ↓ Hvis mønster gjentas Kode → Eget CLI-verktøy (synops-<verb>) ``` -Hvert nivå kan fryses til nivået under. AI foreslår -kompilering, bruker godkjenner. Scriptet kan alltid +AI ved oppretting. Ingen AI ved kjøring. Script kan alltid redigeres manuelt. ## 5. Strukturert trigger @@ -185,38 +252,50 @@ Trigger aktiveres Ingen LLM. Deterministisk. Raskt. -### Bot-modus (nivå 2) +### Feilhåndtering ved kjøring -``` -Trigger aktiveres - → Vaktmesteren finner matchende orchestration-node - → Sender til bot med function calling: - - Trigger-kontekst (hvilken node, hvilken event) - - Instruksjonene fra orchestration.content - - Tilgjengelige verktøy (cli_tool-noder) - → Boten utfører steg for steg - → Logger hvert steg i orchestration_log - → Ved feil: resonnerer og prøver alternativ -``` - -### Drømmemodus (nivå 3) - -Som bot-modus, men med høyere intelligens (Sonnet+) og -instruks om å opprette work_items for manglende verktøy. - -### Auto-eskalering - -Script-modus faller tilbake til bot-modus ved uventet feil: +Alle orkestreringer kjører som script (nivå 1). Ved feil: ``` Script kjører steg 2 → synops-summarize returnerer exit 1 - → VED_FEIL er definert → prøv alternativ - → Alternativ feiler også - → Eskalér til bot-modus for dette steget - → Boten resonnerer om feilen og prøver å løse det + → VED_FEIL definert? → kjør alternativ + → Alternativ feiler også? + → Opprett work_item med feilbeskrivelse + → Logger i orchestration_log + → Stopp orkestreringen ``` +Ingen AI-eskalering ved kjøring. Feil håndteres av scriptet +(VED_FEIL) eller blir work_items for manuell/AI-assistert +oppfølging. + +### Asynkron modus: "eventually" + +Brukeren kan godta at et svar eller script-generering kommer +*etterhvert* i stedet for umiddelbart: + +``` +Bruker: "Lag en orkestrering for podcast-pipeline" + → [Nå] [Eventually] + +"Eventually": + → Forespørselen lagres som work_item med tag "script_request" + → Neste Claude Code-sesjon (task runner) plukker den opp + → Genererer script med Opus (full verktøy-tilgang, fillesing) + → Scriptet valideres og lagres + → Bruker varsles: "Orkestreringen din er klar" +``` + +Fordeler: +- **Ingen API-kostnad** — Claude Code (betalt) gjør jobben +- **Bedre kvalitet** — Opus med full kontekst, ikke en lettvekts API-modell +- **Ingen hastverk** — script-generering trenger ikke skje i sanntid + +Dette gjelder også feilhåndtering: et feilet VED_FEIL-steg +blir en work_item som Claude Code løser i neste sesjon — +reparerer scriptet, legger til manglende verktøy, osv. + ## 7. Koblinger mellom orkestreringer Orkestreringer er noder med edges: