feat: New LLM Schema (Drivers Object List) and Frontend Support [v1.5.0]

app.py

@@ -35,7 +35,7 @@ except ImportError as e:
 
 # --- CONFIG ---
 MODELS_DIR = Path("models")
-APP_VERSION = "1.4.9"
+APP_VERSION = "1.5.0"
 THRESHOLD_AUTO_FLAG = 0.53
 
 # Model registry

index.html

@@ -874,11 +874,35 @@
                 panel.style.display = 'block';
 
                 if (llm && !llm.error) {
-                    document.getElementById('llmSummaryText').innerText = llm.summary || "Summary unavailable.";
+                    // Summary (+ Guidance if available)
+                    let summaryHtml = llm.summary || "Summary unavailable.";
+                    if (llm.guidance) {
+                        summaryHtml += `<br><br><em style="opacity: 0.9; border-left: 2px solid #666; padding-left: 8px; display:block;">Guidance: ${llm.guidance}</em>`;
+                    }
+                    document.getElementById('llmSummaryText').innerHTML = summaryHtml;
 
                     const bulletsUl = document.getElementById('llmBullets');
                     bulletsUl.innerHTML = '';
-                    if (llm.bullets && Array.isArray(llm.bullets)) {
+
+                    // NEW SCHEMA: Drivers list
+                    if (llm.drivers && Array.isArray(llm.drivers)) {
+                        llm.drivers.forEach(d => {
+                            const li = document.createElement('li');
+                            li.style.marginBottom = "8px";
+                            li.style.lineHeight = "1.4";
+
+                            // Color/Arrow for effect
+                            let effectColor = "#ccc";
+                            let arrow = "•";
+                            if (d.effect && d.effect.toLowerCase().includes("up")) { arrow = "↑"; effectColor = "#ff9999"; }
+                            if (d.effect && d.effect.toLowerCase().includes("down")) { arrow = "↓"; effectColor = "#99ff99"; }
+
+                            li.innerHTML = `<span style="color:${effectColor}; font-weight:bold; margin-right:4px;">${arrow}</span> <strong>${d.name}</strong>: ${d.explanation}`;
+                            bulletsUl.appendChild(li);
+                        });
+                    }
+                    // FALLBACK: Old bullets list
+                    else if (llm.bullets && Array.isArray(llm.bullets)) {
                         llm.bullets.forEach(b => {
                             const li = document.createElement('li');
                             li.style.marginBottom = "6px";
@@ -887,7 +911,7 @@
                         });
                     }
 
-                    document.getElementById('llmDisclaimer').innerText = llm.disclaimer || "Disclaimer: These are statistical associations, not proof of fraud.";
+                    document.getElementById('llmDisclaimer').innerText = llm.disclaimer || "Disclaimer: These are statistical patterns, not proof.";
                 } else {
                     const errorMsg = (llm && llm.error) ? llm.error : "AI explanation unavailable at this time.";
                     document.getElementById('llmSummaryText').innerHTML = `<span style="color: #ff9999;">⚠ ${errorMsg}</span>`;

llm_explainer.py

@@ -168,17 +168,21 @@ def _cached_llm_request(selected_model: str, ref_model: str, risk_str: str, driv
     # Build prompt
     prompt = f"""You explain insurance claim risk scores to busy humans.
 
+You explain insurance claim risk scores to busy humans.
+
 Audience:
 - A claims reviewer or operations specialist skimming many cases.
-- They want orientation and context, not theory or instructions.
+- They want quick orientation and context, not theory or instructions.
 
 Tone:
 - Clear, calm, and human.
 - Slightly playful understatement is welcome (Douglas Adams–style), but no jokes or sarcasm.
-- Avoid bureaucratic or brochure-like language.
+- Avoid bureaucratic, legalistic, or brochure-like language.
 
 Rules:
 - Use ONLY the provided drivers. Do not invent facts.
+- List ALL provided drivers.
+- For each driver, clearly indicate whether it pushes risk up or pulls it down.
 - Do NOT say "fraud" or imply certainty.
 - Do NOT claim causality. Describe statistical associations only.
 - Do NOT mention models, SHAP, ML, or methodology.
@@ -187,13 +191,14 @@ Rules:
 
 Style guidance:
 - Start by explaining what the score means in human terms.
-- Describe drivers as forces that pull the risk up or down.
+- Describe drivers as forces acting on the score (pushing it up or pulling it down).
 - Be concrete and concise.
-- Prefer clarity over completeness.
+- Prefer clarity and skimmability over completeness.
+- Write so the explanation can be understood at a glance.
 
 Optional guidance:
-- Include a short section that helps the reviewer gauge how much attention this case deserves.
-- Frame this as typical handling, not instructions or required actions.
+- Include a short line that helps the reviewer gauge how much attention this case deserves.
+- Frame this as typical handling or attention level, not instructions or required actions.
 
 Context:
 - Prediction model: {selected_model}
@@ -206,16 +211,19 @@ Output:
 Return ONLY valid JSON (no markdown, no extra text), matching this schema exactly:
 
 {{
-  "summary": "2–3 sentences giving a clear, human-readable overview of the risk and overall takeaway.",
-  "bullets": [
-    "Short explanation of a driver and how it influences risk.",
-    "Another driver explanation.",
-    "Another driver if relevant."
+  "summary": "2–3 short sentences giving a clear, human-readable orientation to the risk and overall takeaway.",
+  "drivers": [
+    {{
+      "name": "Readable driver name",
+      "effect": "up or down",
+      "explanation": "Short, plain-language explanation of how this driver influences risk."
+    }}
   ],
-  "guidance": "One short sentence describing what this usually means for handling or attention level.",
+  "guidance": "One short sentence describing what this usually means for attention or handling.",
   "disclaimer": "One short sentence noting this reflects statistical patterns, not proof."
 }}
 
+
 """
 
     max_retries = 2