# Flow-Komposition

Ein Flow ist eine YAML-Datei mit drei Top-Level-Schlüsseln:
`inputs:`, `steps:`, `outputs:`. Von oben nach unten gelesen,
sagt sie dem Hub, welche Eingaben er akzeptiert, welche Module
in welcher Reihenfolge aufgerufen werden und was am Ende als
Ergebnis nach außen geht.

## Kleinster möglicher Flow

```yaml
name: hello
description: Gibt einen Namen als Begrüßung zurück.

inputs:
  name:
    type: text

steps:
  - id: greet
    module: debug.echo
    inputs:
      payload: "Hallo, {{ inputs.name }}"

outputs:
  greeting: "{{ steps.greet.outputs.payload }}"
```

`fai run flows/hello.yaml --input name=Welt` ergibt:

```json
{ "greeting": "Hallo, Welt" }
```

## Realbeispiel: extract → summarize

Der mitgelieferte Flow `flows/extract-summarize.yaml`
verkettet zwei Module:

```yaml
steps:
  - id: extract
    module: text.extract
    inputs:
      document: "{{ inputs.file }}"

  - id: summarize
    module: text.summarize
    inputs:
      text: "{{ steps.extract.outputs.text }}"
      style: "drei Stichpunkte"
```

Das Template `{{ steps.extract.outputs.text }}` reicht die
Ausgabe eines Schritts an den nächsten weiter. Die Flow-Engine
konvertiert JSON / FileRef / Text passend zum Ziel-Modul-
Manifest, ohne explizite Wandlungs-Schritte.

## Templating-Referenz (kurz)

| Ausdruck                           | Löst sich auf zu             |
|------------------------------------|------------------------------|
| `{{ inputs.X }}`                   | Eingabe namens X             |
| `{{ steps.Y.outputs.Z }}`          | Ausgabe Z von Schritt Y      |
| `{{ env.OPENAI_API_KEY }}`         | Env-Var (deklariert nötig)   |
| `{{ now }}`                        | ISO-8601-UTC-Zeitstempel     |
| `{{ flow.execution_id }}`          | Lauf-ID (Audit-Log-Schlüssel)|

## Audit-Posture

Jeder Schritt emittiert vier Events:

- `step.started` — Modul-Name, Version, Manifest-Hash
- `step.completed` — Dauer, Output-Größe, gewhitelistete Felder
  automatisch elevated (`model_digest`, `engine`, …)
- `step.failed` — Fehler-Name + Nachricht
- `flow.completed` — Summe der Schritt-Dauern, Events gesamt

Alle hash-verkettet im gleichen Audit-Log. Siehe Audit-Log-
Erklärung für die Ketten-Mechanik.

## Was du in dieser App siehst

- **Flows-Seite**: Liste der gespeicherten Flows unter
  `~/.fai/data/flows/`. `Starten` klicken, geforderte Eingaben
  ausfüllen, Ergebnis verfolgen.
- **Protokoll-Seite**: Schritt-Events erscheinen Sekunden
  nach Flow-Ende. `Flow`-Filter zeigt nur Flow-Level-Zeilen.
- **Store**: Jedes installierte Modul taucht als verfügbares
  `module:` in der Flow-YAML auf. Synthetische föderierte
  Einträge (`mcp.<server>.<tool>`, `n8n.<endpoint>.<workflow>`)
  funktionieren genauso.