Finding Explainer

Chaque Finding dans l’Explorer peut être expliqué à quatre niveaux de détail — d’un résumé rapide à la ligne CSV d’origine.

Les quatre niveaux

Niveau 1 : Info Signal

Cliquez « info » à côté du nom du Signal sur n’importe quelle page de Signal Findings. Affiche :

• Nom d’affichage et description du Signal
• Type d’entité, catégorie, couche de données, version

Répond à : « Que regarde ce Signal ? »

Niveau 2 : Enregistrements source

Cliquez « Explain source records » sur n’importe quelle page de détail de Finding. Affiche les enregistrements Gold réels qui ont produit le Finding :

• Transferts (E5) — mouvements de matériaux
• Facturation (E3/E4) — événements de facturation
• Utilisation — utilisation de matériau par cas

Chaque groupe source montre le nombre d’enregistrements et jusqu’à 20 lignes avec colonnes. Chargé à la demande au clic.

Répond à : « Quels enregistrements ont produit ce nombre ? »

Niveau 3 : Provenance CSV

Sur les pages de détail Entity, la section Provenance affiche source_file et row_number quand présents — reliant l’enregistrement à la ligne CSV d’origine.

Répond à : « D’où vient cet enregistrement ? »

Niveau 4 : Explication IA

Cliquez « Explain in detail » sur n’importe quelle page de détail de Finding. Claude génère un narratif de 3-4 phrases expliquant le Finding en langage simple, avec des nombres en gras, dans la locale courante (EN/DE/FR).

Répond à : « Expliquez-moi cela comme si j’étais directeur financier. »

Configuration

L’explication IA nécessite une clé API Anthropic :

# Set via CLI (stored in ~/.jinflow/secrets.yml)
jin us --api-key sk-ant-api03-...

# Or via environment variable
export ANTHROPIC_API_KEY=sk-ant-api03-...

Modèle par défaut : Claude Haiku (rapide, ~$0.01 par explication). Override avec la variable d’env JINFLOW_AI_MODEL.

Flux de démonstration

1. Ouvrir la page Findings — voir les barres de sévérité proportionnelles
2. Cliquer sur un Finding pour ouvrir sa page de détail
3. Voir l’interprétation modèle (instantanée, déterministe)
4. Cliquer « Explain in detail » — l’IA génère un narratif prêt pour le CFO (carte violette)
5. Cliquer « Explain source records » — voir les lignes Gold réelles
6. Naviguer vers une entité → voir Provenance (fichier CSV source + numéro de ligne)

Ce que l’audience voit

Trois couches sur une page de Finding :

┌─────────────────────────────────────────────────┐
│ Template Interpretation                          │
│ (instant, always there, tri-lingual)             │
├─────────────────────────────────────────────────┤
│ ✨ AI Explanation                     [Claude]   │
│ (on demand, CFO-ready, bold numbers)             │
├─────────────────────────────────────────────────┤
│ 🔍 Source Records                                │
│ ▸ 14 transfers (E5)        total: 200 units     │
│ ▸ 8 billing events (E4)    total: 120 units     │
└─────────────────────────────────────────────────┘

Comment ça fonctionne

Interprétation modèle (Niveau 1/4a)

Le registre Signal contient des modèles d’interprétation trilingues avec des placeholders :

Lift {entity_id} at {hour_bucket}: {passages_per_hour} passages
against capacity {rated_capacity}. Utilization: {utilization_pct}%.

L’Explorer les remplit avec les champs de preuve du Finding au moment du rendu. Zéro latence, déterministe.

Explication IA (Niveau 4b)

POST /api/explain-narrative

Body: { tenant, finding, locale }

L’API :

1. Enrichit le Finding avec les attributs Entity depuis Gold (description, prix, groupe)
2. Charge les métadonnées Signal (nom d’affichage, description, catégorie)
3. Construit un prompt structuré avec tous les nombres et le contexte
4. Appelle l’API Claude (Haiku, max 400 tokens)
5. Retourne le narratif en Markdown

Le prompt instruit Claude de :

• Écrire 3-4 phrases pour une audience non technique
• Utiliser le gras pour les nombres clés
• Expliquer ce qui a été détecté, pourquoi c’est important et les causes probables
• Ne jamais mentionner le SQL, les noms de tables ou le jargon technique

Enregistrements source (Niveau 2)

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

Mappe les types d’entités à leurs tables Gold source :

Type Entity	Tables interrogées
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

Récupère jusqu’à 20 lignes correspondantes par table, filtrées par entity_id et time_bucket.

Provenance CSV (Niveau 3)

Les modèles Bronze portent les colonnes source_file et row_number. Quand celles-ci survivent à travers Silver/Gold (sélectionnées through), elles apparaissent automatiquement dans la page de détail Entity.