Finding Explainer

Jedes Finding im Explorer kann auf vier Detailebenen erklaert werden — von einer Kurzzusammenfassung bis zur Original-CSV-Zeile.

Die vier Ebenen

Ebene 1: Signal-Info

Klicke auf “Info” neben dem Signal-Namen auf jeder Signal-Findings-Seite. Zeigt:

• Signal-Anzeigename und Beschreibung
• Entity-Typ, Kategorie, Datenebene, Version

Beantwortet: “Was untersucht dieses Signal?”

Ebene 2: Quelldatensaetze

Klicke auf “Quelldatensaetze erklaeren” auf jeder Finding-Detailseite. Zeigt die tatsaechlichen Gold-Datensaetze, die das Finding produziert haben:

• Transfers (E5) — Materialbewegungen
• Abrechnung (E3/E4) — Abrechnungsereignisse
• Verbrauch — Fallmaterialverbrauch

Jede Quellgruppe zeigt Datensatzanzahl und bis zu 20 Zeilen mit Spalten. Lazy-Loaded bei Klick.

Beantwortet: “Welche Datensaetze haben diese Zahl produziert?”

Ebene 3: CSV-Provenienz

Auf Entity-Detailseiten zeigt der Provenienz-Abschnitt source_file und row_number wenn vorhanden — verlinkt den Datensatz zurueck zur Original-CSV-Zeile.

Beantwortet: “Woher kam dieser Datensatz?”

Ebene 4: KI-Erklaerung

Klicke auf “Im Detail erklaeren” auf jeder Finding-Detailseite. Claude generiert ein 3-4 Saetze Narrativ, das das Finding in einfacher Sprache erklaert, mit fetten Zahlen, in der aktuellen Sprache (EN/DE/FR).

Beantwortet: “Erklaere mir das so, als waere ich ein CFO.”

Einrichtung

Die KI-Erklaerung benoetigt einen Anthropic API Key:

# Via CLI setzen (gespeichert in ~/.jinflow/secrets.yml)
jin us --api-key sk-ant-api03-...

# Oder via Umgebungsvariable
export ANTHROPIC_API_KEY=sk-ant-api03-...

Standardmodell: Claude Haiku (schnell, ~$0.01 pro Erklaerung). Ueberschreiben mit JINFLOW_AI_MODEL Umgebungsvariable.

Demo-Ablauf

1. Findings-Seite oeffnen — die proportionalen Schweregrad-Balken sehen
2. Auf ein Finding klicken um die Detailseite zu oeffnen
3. Die Template-Interpretation sehen (sofort, deterministisch)
4. “Im Detail erklaeren” klicken — KI generiert ein CFO-taugliches Narrativ (lila Karte)
5. “Quelldatensaetze erklaeren” klicken — die tatsaechlichen Gold-Zeilen sehen
6. Zu einer Entity navigieren → Provenienz sehen (Quell-CSV-Datei + Zeilennummer)

Was das Publikum sieht

Drei Ebenen auf einer Finding-Seite:

┌─────────────────────────────────────────────────┐
│ Template-Interpretation                          │
│ (sofort, immer da, dreisprachig)                │
├─────────────────────────────────────────────────┤
│ ✨ KI-Erklaerung                      [Claude]   │
│ (auf Anfrage, CFO-tauglich, fette Zahlen)       │
├─────────────────────────────────────────────────┤
│ 🔍 Quelldatensaetze                              │
│ ▸ 14 Transfers (E5)        Total: 200 Einheiten │
│ ▸ 8 Abrechnungsereignisse (E4)  Total: 120 Einh.│
└─────────────────────────────────────────────────┘

So funktioniert es

Template-Interpretation (Ebene 1/4a)

Die Signal Registry enthaelt dreisprachige Interpretationsvorlagen mit Platzhaltern:

Lift {entity_id} um {hour_bucket}: {passages_per_hour} Durchgaenge
gegen Kapazitaet {rated_capacity}. Auslastung: {utilization_pct}%.

Explorer fuellt diese mit den Evidenzfeldern des Findings zur Renderzeit. Keine Latenz, deterministisch.

KI-Erklaerung (Ebene 4b)

POST /api/explain-narrative

Body: { tenant, finding, locale }

Die API:

1. Reichert das Finding mit Entity-Attributen aus Gold an (Beschreibung, Preis, Gruppe)
2. Laedt Signal-Metadaten (Anzeigename, Beschreibung, Kategorie)
3. Baut einen strukturierten Prompt mit allen Zahlen und Kontext
4. Ruft Claude API auf (Haiku, max 400 Token)
5. Gibt das Narrativ als Markdown zurueck

Der Prompt instruiert Claude:

• 3-4 Saetze fuer ein nicht-technisches Publikum schreiben
• Fett fuer wichtige Zahlen verwenden
• Erklaeren was erkannt wurde, warum es wichtig ist und wahrscheinliche Ursachen
• Niemals SQL, Tabellennamen oder technischen Jargon erwaehnen

Quelldatensaetze (Ebene 2)

GET /api/explain?tenant=...&entity_type=...&entity_id=...&time_bucket=...

Bildet Entity-Typen auf ihre Gold-Quelltabellen ab:

Entity-Typ	Abgefragte Tabellen
Material	gold_material_movements, gold_billing_events, gold_case_material_usage
Case	gold_billing_events, gold_case_material_usage
BillingEvent	gold_billing_events
CostCentre	gold_billing_events, gold_material_movements

Ruft bis zu 20 passende Zeilen pro Tabelle ab, gefiltert nach entity_id und time_bucket.

CSV-Provenienz (Ebene 3)

Bronze-Modelle tragen source_file und row_number Spalten. Wenn diese durch Silver/Gold ueberleben (durchgereicht), erscheinen sie automatisch auf der Entity-Detailseite.