Finding Explainer

Every finding in Explorer can be explained at four levels of detail — from a quick summary to the original CSV row.

The Four Levels

Level 1: Signal Info

Click “info” next to the signal name on any signal findings page. Shows:

• Signal display name and description
• Entity type, category, data layer, version

Answers: “What does this signal look at?”

Level 2: Source Records

Click “Explain source records” on any finding detail page. Shows the actual Gold records that produced the finding:

• Transfers (E5) — material movements
• Billing (E3/E4) — billing events
• Usage — case material usage

Each source group shows record count and up to 20 rows with columns. Lazy-loaded on click.

Answers: “Which records produced this number?”

Level 3: CSV Provenance

On entity detail pages, the Provenance section shows source_file and row_number when present — linking the record back to the original CSV row.

Answers: “Where did this record come from?”

Level 4: AI Explanation

Click “Explain in detail” on any finding detail page. Claude generates a 3-4 sentence narrative explaining the finding in plain language, with bold numbers, in the current locale (EN/DE/FR).

Answers: “Explain this to me like I’m a CFO.”

Setup

The AI explanation requires an Anthropic API key:

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

Default model: Claude Haiku (fast, ~$0.01 per explanation). Override with JINFLOW_AI_MODEL env var.

Demo Flow

1. Open Findings page — see the proportional severity bars
2. Click a finding to open its detail page
3. See the template interpretation (instant, deterministic)
4. Click “Explain in detail” — AI generates a CFO-ready narrative (purple card)
5. Click “Explain source records” — see the actual Gold rows
6. Navigate to an entity → see Provenance (source CSV file + row number)

What the audience sees

Three layers on one finding page:

┌─────────────────────────────────────────────────┐
│ 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     │
└─────────────────────────────────────────────────┘

How It Works

Template Interpretation (Level 1/4a)

The signal registry contains tri-lingual interpretation templates with placeholders:

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

Explorer fills these with the finding’s evidence fields at render time. Zero latency, deterministic.

AI Explanation (Level 4b)

POST /api/explain-narrative

Body: { tenant, finding, locale }

The API:

1. Enriches the finding with entity attributes from Gold (description, price, group)
2. Loads signal metadata (display name, description, category)
3. Builds a structured prompt with all numbers and context
4. Calls Claude API (Haiku, max 400 tokens)
5. Returns the narrative as Markdown

The prompt instructs Claude to:

• Write 3-4 sentences for a non-technical audience
• Use bold for key numbers
• Explain what was detected, why it matters, and likely causes
• Never mention SQL, table names, or technical jargon

Source Records (Level 2)

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

Maps entity types to their Gold source tables:

Entity Type	Tables Queried
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

Fetches up to 20 matching rows per table, filtered by entity_id and time_bucket.

CSV Provenance (Level 3)

Bronze models carry source_file and row_number columns. When these survive through Silver/Gold (selected through), they appear automatically in the entity detail page.