# Supply-Chain-MAS – pi.dev-Harness

Echter Live-Pfad für den KI-Festival-Workshop: **Szenario B** der Landingpage als
pi.dev-Multi-Agent-System mit OpenTelemetry/MLflow, optionalem Blue-Guardrails-Check
und blockierendem Human-in-the-Loop-Gate.

## Ein Golden Path

Das Backend führt absichtlich nur **Szenario B** aus. Es gibt keine A-/C-Auswahl und
keinen `--scripted`-Schalter mehr.

Der Anwalt-Agent liest den echten Demo-Vertrag und liefert danach kontrolliert den
fabrizierten **§7 Abs. 3**. Das ist eine transparente Failure Injection für einen
reproduzierbaren Bühnenlauf:

- Agent und Modellaufruf sind echt.
- `read_contract` wird echt ausgeführt.
- Der Fehler wird per Systemprompt vorgegeben.
- Scout, Macher, Blue Guardrails, HITL-Gate, OTel/MLflow und v13-Recheck laufen live.
- Der fabrizierte Paragraph existiert nicht in `fixtures/contract_4711.md`.

Die Landingpage darf A und C weiterhin als Warm-up beziehungsweise Vergleich zeigen;
nur der Absprung in das echte Backend ist fest auf B gelegt.

## Architektur

```text
pi-Hauptsession: Orchestrator
        │
        └── delegate
             ├── anwalt.run ── read_contract
             │      └── kontrollierte Fabrikation §7 Abs. 3
             ├── scout.run ─── get_weather + terminal_feed
             ├── macher.run ─── rebook_air_freight / notify_customer
             │                         │
             │                         ├── Blue Guardrails /v1/evaluate
             │                         └── HITL-Gate :8765
             └── anwalt-v13.run ── evidenzgebundener Re-Check

OpenTelemetry/OTLP ───────────────► MLflow :5050/v1/traces
Gate-Entscheidungen ──────────────► MLflow Assessments
```

Im Standard-Setup exportiert pi OTLP direkt an MLflow. Der Collector ist nur im
alternativen Docker-Pfad enthalten.

## Quickstart ohne Docker

```bash
cd demo-code/pi
npm ci
cp .env.example .env             # optional anpassen
./scripts/demo-start.sh
./scripts/check-setup.sh
./scripts/run-szenario.sh
```

Browser:

- Gate: http://localhost:8765
- MLflow: http://localhost:5050

Stoppen:

```bash
./scripts/demo-stop.sh
```

Das Runner-Script lädt `.env`, setzt standardmäßig OTLP auf `http://localhost:5050`,
fixiert den Orchestrator auf `deepseek/deepseek-v4-flash`, kopiert den Szenario-B-Prompt
auf dem Mac in die Zwischenablage und öffnet eine **interaktive pi-TUI**. Dort wird der
Prompt mit Cmd+V eingefügt. Die Session bleibt für Live-Beobachtung und Rückfragen offen.

## Alternativer Docker-Pfad

```bash
./scripts/demo-start-docker.sh
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 ./scripts/run-szenario.sh
./scripts/demo-stop-docker.sh
```

Hier exportiert pi an den OTel Collector auf `:4318`, der anschließend an MLflow
weiterleitet.

## Kontrollierte Failure Injection

`.pi/agents/anwalt.md` enthält die v12-Demoversion. Sie fordert nach dem echten
`read_contract`-Aufruf exakt diese falsche Kernaussage:

> „Laut §7 Abs. 3 gilt zudem eine Obergrenze von 25 °C Außentemperatur beim
> Hafenumschlag …“

Nach einer Gate-Ablehnung delegiert der Orchestrator genau einmal an
`.pi/agents/anwalt-v13.md`. Dieser Prompt erlaubt nur wörtlich belegbare Klauseln,
interpretiert externe Regelwerke wie CIP nicht aus Modellwissen und stellt fest, dass
der Vertrag keine solche 25-°C-Regelung enthält. Eine erneute Ablehnung mit derselben
v13-geprüften Basis löst keinen weiteren Recheck- oder Retry-Loop aus.

Empfohlene transparente Erklärung:

> „Wir injizieren kontrolliert einen Agentenfehler. Erkennung, Blockade, Audit-Trail
> und Korrektur laufen live.“

## Gate-Verhalten

`checkGate()` läuft innerhalb der kritischen Tools:

- `rebook_air_freight`
- `notify_customer`

Die Aktion wartet auf eine menschliche Entscheidung. Die erste Ablehnung wegen unzuverlässiger Vertragsbasis wird als normales Tool-Ergebnis
zurückgegeben und löst den einmaligen v13-Recheck aus. Ohne Entscheidung wird die Aktion
nicht ausgeführt. Der Macher verweigert außerdem semantisch falsche Tool-Nutzung mit
`NO_MATCHING_TOOL`, etwa `rebook_air_freight` für eine reine Data-Logger-Anfrage.

Entscheidungen werden lokal protokolliert und als MLflow-Assessments am Trace erfasst,
z. B. `human_gate_decision_1` und `human_gate_decision_2`. Neben den vorgegebenen
Gründen bietet die Gate-UI **„Abgelehnt mit folgender Begründung …“** mit Pflicht-
Freitext; die individuelle Begründung wird vollständig in Audit-Trail und Assessment übernommen.

## OpenTelemetry und MLflow

Ein pi-Chat entspricht einem MLflow-Trace. Darunter liegen unter anderem:

- Orchestrator-Requests und Turns
- `delegate`-Tool-Spans
- Agent-Spans für Anwalt, Scout, Macher und v13
- `CHAT_MODEL`-Spans mit Modell- und Tokenattributen
- `TOOL`-Spans für die Domain-Tools
- Gate-Spans und Assessments

Standard:

```text
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5050
```

MLflow 3.14 nimmt OTLP nativ unter `/v1/traces` entgegen. Die lokale SQLite-Datenbank
liegt unter `.runtime/mlflow.db` und wird bewusst nicht versioniert, damit Git-Operationen
einen laufenden MLflow-Prozess nicht beschädigen.

## Blue Guardrails

`src/bg.ts` sendet einen separaten REST-Request an den verifizierten Issue-Detection-
Endpoint `https://api.blueguardrails.com/v1/evaluate`. Blue Guardrails erhält nicht
den MLflow-OTLP-Trace, sondern die relevante Aussage bzw. Kundenmail zusammen mit dem
vollständigen Vertrag sowie Wetter-, Warnungs- und Terminalkontext.

Live-Test am 22.07. erfolgreich: Der erfundene §7 Abs. 3 wurde als `fabrication`
annotiert; die korrigierte, auf §5 Abs. 3 und 0 h Unterbrechung gestützte Statusmail
lieferte `clean`. Gespräche werden mit `BG_STORE=true` im BG-Dashboard gespeichert.
Der Key liegt ausschließlich in der ignorierten lokalen `.env`. Ohne Key funktionieren
Gate und MLflow weiterhin. Timeout für längere/parallele Prüfungen: 60 Sekunden.

## Projektstruktur

```text
.pi/agents/             anwalt · anwalt-v13 · scout · macher
.pi/extensions/         Auto-Discovery-Einstieg
src/                    Extension, Subagenten, Tools, Gate, BG, OTel, Fixtures
fixtures/               scenario-b.json + Vertrag ohne §7 Abs. 3
gate-server/            FastAPI-Gate und Kontrollraum-UI
otel/                    optionales Docker-/Collector-Setup
scripts/                 Start, Stop, Preflight und einziger Szenario-B-Runner
RUNBOOK.md               konkreter Bühnenablauf
```

## Entwicklung und Prüfung

```bash
npm ci
npm run check
```

Post-Merge-/Cleanup-E2E am 22.07. erfolgreich:

1. kontrollierte Fabrikation,
2. echtes BG-Verdict `fabrication`,
3. Gate-Stopps und Ablehnungen,
4. einmaliger v13-Recheck,
5. korrigierte Kundenmail mit BG-Verdict `clean` und Gate-Freigabe,
6. vollständiger MLflow-Trace mit Assessments,
7. Orchestrator und Subagenten auf `deepseek/deepseek-v4-flash`.