synops/docs/concepts/orkestrering.md

# Konsept: Orkestrering
**Filsti:** `docs/concepts/orkestrering.md`

## 1. Konsept

Orkestreringer er noder som *gjør* ting. De er oppskrifter —
sekvenser av CLI-verktøy som utføres automatisk når en trigger
aktiveres. Tre nivåer: deklarativt script (ingen AI),
fritekst med AI-tolkning, og full drømmemodus.

## 2. Hvorfor

Synops har mange automatiseringer hardkodet i vaktmesteren:
podcast-pipeline, AI-beriking, publisering. De er usynlige,
uendrelige og umulige å tilpasse for brukere.

Orkestreringer gjør automatisering til førsteklasses graf-
primitiver — synlige, redigerbare, delbare, versjonerbare.

## 3. Nodemodell

```
node_kind: 'orchestration'
title: "Podcast: opptak → publisering"
content: <script eller fritekst>
metadata: {
  "trigger": {
    "event": "communication.ended",
    "conditions": {
      "has_trait": "podcast",
      "has_media": "audio"
    }
  },
  "executor": "script" | "bot" | "dream",
  "intelligence": 2,
  "effort": 2
}
```

### Tre typer noder som gjør

| node_kind | Ikon | Aktivering | Eksempel |
|-----------|------|------------|----------|
| `cli_tool` | 🔧 | Kalles av andre | synops-transcribe |
| `ai_preset` | 🔧 | Kalles av AI-verktøy | "Rens tekst"-prompt |
| `orchestration` | ⚡ | **Trigger-drevet, utfører seg selv** | Podcast-pipeline |

⚡ signaliserer: "denne noden gjør noe av seg selv."

## 4. Tre utførelsesnivåer

### Nivå 1: Deklarativt script (ingen AI)

Eksakte CLI-kall med variabler fra trigger-konteksten.
Vaktmesteren parser og eksekverer direkte — ingen LLM.

```
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 "Podcast-pipeline feilet" --tag bug
```

**Grammatikk:**

```
TRIGGER    NÅR <event> [HVIS <betingelse>]
STEP       <N>. <tool> <args...>
FALLBACK   VED_FEIL: <tool> <args...> | work_item <title> [--tag <tag>]
VARIABLE   {event.<felt>} — substitueres fra trigger-konteksten
```

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

Naturlig språk som boten tolker og utfører steg for steg
med function calling. For orkestreringer der stegene ikke
er helt forutsigbare.

```
Når en innspilling i en samling med podcast-trait avsluttes:

1. Transkriber lydfilen med stor modell
2. Generer oppsummering
3. Foreslå kapitler basert på transkripsjonen
4. Generer show notes
5. Oppdater RSS-feed

Hvis transkribering feiler, prøv igjen med medium modell.
Hvis RSS feiler, opprett en oppgave.
```

Boten mapper "transkriber lydfilen" → `synops-transcribe`,
"oppsummer" → `synops-summarize`, osv. Krever LLM-kall
per kjøring (Haiku er nok for de fleste).

### 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.

```
Gjør episoden klar for publisering. Lag en lydfil med
sammendrag og send den til alle deltakere.
```

Boten sjekker tilgjengelige verktøy, gjør det den kan,
og oppretter work_items for det som mangler.

### 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
Kode         → Eget CLI-verktøy (synops-<verb>)
```

Hvert nivå kan fryses til nivået under. AI foreslår
kompilering, bruker godkjenner. Scriptet kan alltid
redigeres manuelt.

## 5. Strukturert trigger

Triggeren er alltid strukturert — vaktmesteren evaluerer
den effektivt uten LLM, uavhengig av utførelsesnivå:

```jsonc
{
  "trigger": {
    "event": "communication.ended",
    "conditions": {
      "has_trait": "podcast",
      "has_media": "audio"
    }
  }
}
```

### Kjente trigger-events

| Event | Beskrivelse |
|-------|-------------|
| `node.created` | Ny node opprettet |
| `edge.created` | Ny edge opprettet |
| `communication.ended` | Samtale/innspilling avsluttet |
| `node.published` | Node publisert (belongs_to med slot) |
| `scheduled.due` | Planlagt tidspunkt nådd |
| `manual` | Bruker trykker "Kjør" |

### Betingelser

Filtrerer triggeren ytterligere:
- `has_trait` — noden/samlingen har denne traiten
- `has_media` — noden har media-edge av denne typen
- `has_tag` — noden har tagged-edge med denne verdien
- `node_kind` — noden er av denne typen

## 6. Utførelse

### Script-modus (nivå 1)

```
Trigger aktiveres
  → Vaktmesteren finner matchende orchestration-node
  → Parser scriptet
  → Substituerer {event.*}-variabler fra trigger-kontekst
  → Utfører steg sekvensielt via generisk dispatch
    (synops-{tool} --payload-json)
  → Ved feil: kjør VED_FEIL-steg eller opprett work_item
  → Logger i orchestration_log
```

Ingen LLM. Deterministisk. Raskt.

### Bot-modus (nivå 2)

```
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:

```
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
```

## 7. Koblinger mellom orkestreringer

Orkestreringer er noder med edges:

```
"Podcast: opptak → publisering"
  ──triggers──→ "Varsle redaksjonen om ny episode"
  ──triggers──→ "Post til sosiale medier"
```

Output fra én orkestrering kan trigge neste via `triggers`-edge.
Kaskade via edges, ikke hardkodet.

## 8. Brukergrensesnitt

```
┌─ Podcastorkestrering ⚡ ──────────────────┐
│                                           │
│  Trigger: [Innspilling avsluttet ▼]       │
│  Betingelse: [Samling har podcast-trait ▼] │
│  Modus: [Script ▼]                        │
│                                           │
│  ┌─────────────────────────────────────┐  │
│  │ NÅR innspilling.avsluttet          │  │
│  │ HVIS samling.har_trait("podcast")   │  │
│  │                                    │  │
│  │ 1. synops-transcribe               │  │
│  │    --cas-hash {event.cas_hash}     │  │
│  │    --model large                   │  │
│  │    VED_FEIL: ... --model medium    │  │
│  │ 2. synops-summarize                │  │
│  │    --communication-id {event.id}   │  │
│  │ 3. synops-rss                      │  │
│  │    --collection-id {event.coll_id} │  │
│  └─────────────────────────────────────┘  │
│                                           │
│  [▶ Test kjøring]    [↑ Konverter til AI] │
│                                           │
│  Status: Aktiv  Kjørt: 47 ganger          │
│  Sist: 2026-03-18 12:30 (OK)             │
│                                           │
│  ℹ Tilgjengelig: synops-transcribe,       │
│    synops-rss, synops-render...           │
│    (12 verktøy)                           │
└───────────────────────────────────────────┘
```

Modusvelger: Script / Fritekst / Drømmemodus.
"Test kjøring" utfører med dry-run.
"Konverter til AI" løfter scriptet til fritekst-modus.

## 9. Edge-modell

| Edge | Source → Target | Betydning |
|------|----------------|-----------|
| `belongs_to` | orchestration → collection | Tilhører denne samlingen |
| `observes` | orchestration → any node | Overvåker denne noden for trigger-events |
| `triggers` | orchestration → orchestration | Kaskade-kobling |
| `uses` | orchestration → cli_tool | Bruker dette verktøyet |
| `mentions` | orchestration → any | Refererer til denne noden |

### `observes`-edge: eksplisitt kobling

Orkestreringen peker på det den observerer:

```
"Auto-clip URL-er" (orchestration)
  ──observes──→ #Redaksjonen (communication)
  ──observes──→ #Research (communication)
```

Legg til `observes`-edge → aktivert for den noden.
Fjern edge → deaktivert. Opprettet via drag-and-drop
(se `docs/retninger/interaksjonsmodell.md`).

### Implisitt vs eksplisitt

- **`observes`-edge:** Eksplisitt. "Denne orkestreringen overvåker
  denne noden."
- **Trigger-betingelser:** Implisitt. "Overvåk alt som matcher."
- `observes` overtrumfer: fjernet `observes`-edge betyr "ikke her",
  selv om betingelsene matcher. Brukeren har kontroll.

## 10. Drømmemodus: brukeren skriver hva de vil

Brukeren begrenses ikke til kjente verktøy. De skriver fritt
— boten prøver, og mangler som oppdages blir feature requests.

```
Bruker skriver: "Lag en lydfil med sammendrag og send til deltakerne"

Boten sjekker:
  ✓ synops-summarize finnes → oppsummerer
  ✗ synops-tts finnes ikke → kan ikke lage lyd

Boten svarer:
  "Jeg oppsummerte møtet, men Synops har ikke tekst-til-tale
   ennå. Jeg oppretter en forespørsel?"

  → work_item i innboks:
    title: "TTS for møteoppsummeringer"
    tagged: "feature"
    source_material → orkestreringsnoden
```

Systemet lærer hva brukerne vil ha fra det som ikke lykkes.

## 11. Prinsipp: målet er alltid script

Enhver orkestrering har som mål å bli et deklarativt script.
AI-nivåene (fritekst, drøm) er **verktøy for å komme dit**,
ikke permanente driftsmoduser.

Hvis en orkestrering ikke kan uttrykkes som script, betyr det
én av to ting:

1. **Verktøyet mangler.** Lag et nytt CLI-verktøy som dekker
   det manglende steget. Da kan scriptet uttrykke det.
2. **Logikken er for vag.** Stram opp instruksjonene til de er
   presise nok for et script. Hvis det ikke er mulig, er
   orkestreringen kanskje ikke moden nok for automatisering.

AI som permanent feilhåndtering i en orkestrering er et tegn
på at noe er galt — enten med verktøyet eller med spesifikasjonen.
Det skal fikses, ikke kompenseres.

```
Drømmemodus  → "Hva vil vi oppnå?"
Fritekst     → "Hvordan gjør vi det?"
Script       → "Nøyaktig dette."
  ↓
Hvis script ikke er mulig:
  → Mangler verktøy?  → Lag synops-<verb>
  → For vagt?         → Stram opp spec
  → Umulig?           → Ikke automatiser dette
```

## 12. Avgrensning

- Orkestreringer er **ikke** en generell workflow-engine.
  De er oppskrifter — deklarative eller AI-tolkede.
- Deklarativt script er primær for produksjon. AI er for
  oppretting, feilhåndtering og drømmemodus.
- Triggere evalueres av vaktmesteren, utførelse av
  vaktmesteren (script) eller bot (fritekst/drøm).
- Brukeren begrenses aldri til kjente verktøy. Manglende
  funksjonalitet fanges opp som feature requests.

## 13. Komponenter

| Feature | Rolle |
|---------|-------|
| Vaktmesteren | Evaluerer triggere, parser/utfører scripts, dispatcher til bot |
| @bot | Tolker fritekst-instruksjoner, utfører med function calling |
| CLI-verktøy | Gjør det faktiske arbeidet |
| Arbeidstavlen | Work items opprettes ved feil |
| Responskvalitet | Intelligence/effort per orkestrering |

## 14. Bygger på
- `docs/retninger/unix_filosofi.md` — CLI-verktøy som byggeklosser
- `docs/retninger/interaksjonsmodell.md` — drag-and-drop for observes-edge
- `docs/concepts/arbeidstavlen.md` — @bot, work items ved feil
- `docs/infra/robusthet.md` — function calling, fallback
- `docs/features/responskvalitet.md` — intelligence/effort-nivåer