Update app.py

app.py

@@ -1,3 +1,15 @@
+# app.py
+# Gradio — TBNet (CNN model) + Lung U-Net Auto Mask + Grad-CAM + RADIO (visual model)
+# + SAFER PHONE MODE + MASK POST-PROCESSING + MASK SANITY FAILSAFE
+# + 3-STATE AGREEMENT (LOW / SCREEN+ / TB+)
+#
+# Requirements:
+#   pip install gradio timm torchvision opencv-python pillow transformers einops torch
+#
+# HF Spaces notes:
+# - weights are expected in ./weights/
+# - app launches on 0.0.0.0:7860
+
 import os
 import cv2
 import numpy as np
@@ -20,6 +32,10 @@ from PIL import Image
 # USER CONFIG (HF Spaces friendly)
 # ============================================================
 
+# ---- Friendly model names for UI ----
+MODEL_NAME_TBNET = "TBNet (CNN model)"
+MODEL_NAME_RADIO = "RADIO (visual model)"
+
 # ---- Default TB/Lung weights ----
 DEFAULT_TB_WEIGHTS = "weights/best.pt"
 DEFAULT_LUNG_WEIGHTS = "weights/lung_unet_mont_shenzhen.pt"
@@ -32,7 +48,6 @@ RADIO_REVISION = "c0457f5dc26ca145f954cd4fc5bb6114e5705ad8"
 RADIO_RAW_HEAD_PATH = "weights/best_raw.pt"
 RADIO_MASKED_HEAD_PATH = "weights/best_masked.pt"
 
-
 RADIO_IMG_SIZE = 320
 RADIO_PATCH_SIZE = 16
 RADIO_THR_SCREEN = 0.05
@@ -42,19 +57,15 @@ RADIO_GATE_DEFAULT = 0.21
 
 # ---- Consensus logic thresholds ----
 TBNET_SCREEN_THR = 0.30
-TBNET_MARGIN = 0.03   # 3% margin around threshold → INDET zone
-
 RADIO_SCREEN_THR = RADIO_THR_SCREEN
-RADIO_MARGIN = 0.02   # 2% margin around radio screen threshold
 
 # ---- Mask fail-safes ----
 FAIL_COV = 0.10     # <10% -> segmentation fail
 WARN_COV = 0.18     # <18% -> warn
-# if mask looks like a single lung / cropped, we fail-safe and do not output TB score
-FAILSAFE_ON_BAD_MASK = True
+FAILSAFE_ON_BAD_MASK = True  # fail-safe on suspicious/cropped masks
 
 # ---- Device policy ----
-FORCE_CPU = True  # set True if you want TB+RADIO to always run CPU
+FORCE_CPU = True  # HF CPU space: keep True
 DEVICE = torch.device("cpu" if FORCE_CPU else ("cuda" if torch.cuda.is_available() else "cpu"))
 
 
@@ -63,18 +74,41 @@ DEVICE = torch.device("cpu" if FORCE_CPU else ("cuda" if torch.cuda.is_available
 # ============================================================
 CLINICAL_DISCLAIMER = """
 ⚠️ IMPORTANT CLINICAL NOTICE (Decision Support Only)
-This AI system is for **research/decision support** and is NOT a diagnostic device.
-It may NOT reliably detect early/subtle tuberculosis, including **MILIARY TB**,
-which can appear near-normal or subtle on chest X-ray (especially on phone photos / WhatsApp images).
+
+This system is for **research/decision support** and is **NOT** a diagnostic device.
+It may **miss early/subtle tuberculosis**, including **miliary TB**.
+Phone photos / screenshots / downsampled images can reduce reliability.
 
 If clinical suspicion exists (fever, weight loss, immunosuppression, known exposure),
 recommend **CBNAAT / GeneXpert**, sputum studies, and/or **CT chest** regardless of AI output.
 """
 
 REPORT_LABELS = {
-    "GREEN": {"title": "LIKELY NORMAL", "summary": "No radiographic features suggestive of pulmonary tuberculosis detected by AI."},
-    "YELLOW": {"title": "RADIOLOGIST INTERPRETATION RECOMMENDED", "summary": "This AI output is indeterminate / not definitive.A qualified radiologist review is recommended to confirm findings and correlate clinically."},
-    "RED": {"title": "LIKELY TB", "summary": "AI detected focal lung patterns commonly associated with pulmonary tuberculosis. This is not a diagnosis; microbiological confirmation is required."},
+    "GREEN": {
+        "title": "LOW TB LIKELIHOOD",
+        "summary": (
+            f"✅ **{MODEL_NAME_TBNET}** did not find patterns that strongly suggest pulmonary tuberculosis.\n\n"
+            "**What to do next:** If symptoms or TB risk factors are present, please seek clinician/radiologist review."
+        ),
+    },
+    "YELLOW": {
+        "title": "INDETERMINATE — REVIEW RECOMMENDED",
+        "summary": (
+            f"⚠️ **{MODEL_NAME_TBNET}** result is **not definitive**.\n\n"
+            "**Common reasons:** image quality limitations, non-standard/cropped view, or non-focal attention.\n\n"
+            "**What to do next:** Radiologist/clinician review is recommended. "
+            "If TB is clinically suspected, consider microbiological tests (CBNAAT/GeneXpert, sputum)."
+        ),
+    },
+    "RED": {
+        "title": "TB FEATURES SUSPECTED",
+        "summary": (
+            f"🚩 **{MODEL_NAME_TBNET}** detected lung patterns that can be seen with pulmonary tuberculosis.\n\n"
+            "**Important:** This is not a diagnosis.\n\n"
+            "**What to do next:** Urgent clinician/radiologist review and microbiological confirmation "
+            "(CBNAAT/GeneXpert, sputum) are recommended."
+        ),
+    },
 }
 
 CLINICAL_GUIDANCE = (
@@ -98,7 +132,9 @@ class DoubleConv(nn.Module):
             nn.BatchNorm2d(out_c),
             nn.ReLU(inplace=True),
         )
-    def forward(self, x): return self.net(x)
+
+    def forward(self, x):
+        return self.net(x)
 
 class LungUNet(nn.Module):
     def __init__(self):
@@ -140,7 +176,9 @@ class TBNet(nn.Module):
         super().__init__()
         self.backbone = timm.create_model(backbone, pretrained=False, num_classes=0, global_pool="avg")
         self.fc = nn.Linear(self.backbone.num_features, 1)
-    def forward(self, x): return self.fc(self.backbone(x)).view(-1)
+
+    def forward(self, x):
+        return self.fc(self.backbone(x)).view(-1)
 
 def load_tb_weights(model: nn.Module, ckpt_path: str, device: torch.device):
     sd = torch.load(ckpt_path, map_location=device)
@@ -154,8 +192,11 @@ class GradCAM:
         target_layer.register_forward_hook(self._fwd)
         target_layer.register_full_backward_hook(self._bwd)
 
-    def _fwd(self, _, __, out): self.activ = out
-    def _bwd(self, _, grad_in, grad_out): self.grad = grad_out[0]
+    def _fwd(self, _, __, out):
+        self.activ = out
+
+    def _bwd(self, _, grad_in, grad_out):
+        self.grad = grad_out[0]
 
     def generate(self, x: torch.Tensor) -> Tuple[np.ndarray, float, float]:
         with torch.enable_grad():
@@ -213,17 +254,17 @@ def border_fraction(gray_u8: np.ndarray) -> float:
     bot = gray_u8[-b:, :]
     left = gray_u8[:, :b]
     right = gray_u8[:, -b:]
-    def frac_border(x): return float(((x < 15) | (x > 240)).mean())
+    def frac_border(x):
+        return float(((x < 15) | (x > 240)).mean())
     return float(np.mean([frac_border(top), frac_border(bot), frac_border(left), frac_border(right)]))
 
 def phone_quality_report(gray_u8: np.ndarray) -> Tuple[float, List[str]]:
     warnings: List[str] = []
     h, w = gray_u8.shape
-
     score = 100.0
 
     if min(h, w) < 400:
-        warnings.append("Low resolution (may reduce detection reliability).")
+        warnings.append("Low resolution (image may be downsampled).")
         score -= 8
 
     sharp = laplacian_sharpness(gray_u8)
@@ -234,22 +275,29 @@ def phone_quality_report(gray_u8: np.ndarray) -> Tuple[float, List[str]]:
 
     if likely_phone:
         if sharp < 40:
-            score -= 25; warnings.append("Blurry / motion blur detected (phone capture).")
+            score -= 25
+            warnings.append("Blurry / motion blur detected (likely phone capture).")
         elif sharp < 80:
-            score -= 12; warnings.append("Slight blur detected.")
+            score -= 12
+            warnings.append("Slight blur detected.")
     else:
         if sharp < 30:
-            score -= 8; warnings.append("Low fine-detail / mild blur (digital CXR or downsample).")
+            score -= 8
+            warnings.append("Low fine detail (possible downsampling).")
 
     if hi_clip > 0.05:
-        score -= 15; warnings.append("Overexposed highlights (washed out areas).")
+        score -= 15
+        warnings.append("Overexposed highlights (washed-out areas).")
     if lo_clip > 0.10:
-        score -= 12; warnings.append("Underexposed shadows (very dark areas).")
+        score -= 12
+        warnings.append("Underexposed shadows (very dark areas).")
 
     if border > 0.55:
-        score -= 18; warnings.append("Large border/margins detected (screenshot/phone framing).")
+        score -= 18
+        warnings.append("Large border/margins detected (possible screenshot/phone framing).")
     elif border > 0.35:
-        score -= 10; warnings.append("Some border/margins detected.")
+        score -= 10
+        warnings.append("Some border/margins detected.")
 
     return float(np.clip(score, 0, 100)), warnings
 
@@ -257,19 +305,22 @@ def auto_border_crop(gray_u8: np.ndarray) -> np.ndarray:
     g = gray_u8.copy()
     g_blur = cv2.GaussianBlur(g, (5, 5), 0)
     _, th = cv2.threshold(g_blur, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
-    if th.mean() > 127: th = 255 - th
+    if th.mean() > 127:
+        th = 255 - th
 
     k = max(3, int(0.01 * min(g.shape)))
     kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (k, k))
     th = cv2.morphologyEx(th, cv2.MORPH_CLOSE, kernel, iterations=2)
 
     contours, _ = cv2.findContours(th, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-    if not contours: return gray_u8
+    if not contours:
+        return gray_u8
 
     c = max(contours, key=cv2.contourArea)
     x, y, w, h = cv2.boundingRect(c)
     H, W = gray_u8.shape
-    if w * h < 0.20 * (H * W): return gray_u8
+    if w * h < 0.20 * (H * W):
+        return gray_u8
 
     pad = int(0.03 * min(H, W))
     x1 = max(0, x - pad); y1 = max(0, y - pad)
@@ -311,25 +362,23 @@ def cam_entropy(cam: np.ndarray) -> float:
 def detect_diffuse_risk(prob_tb: float, cam_up: np.ndarray, quality_score: float) -> bool:
     if quality_score < 55:
         return False
-
-    # Only apply diffuse-risk heuristic in the "near-threshold negative" zone
+    # Only apply diffuse-risk heuristic in near-threshold negatives
     if prob_tb < 0.05:
         return False
-
     ent = cam_entropy(cam_up)
     return (prob_tb < TBNET_SCREEN_THR) and (ent > 6.5)
 
-
 def confidence_band(prob_tb: float, quality_score: float, diffuse: bool):
-    if prob_tb < 0.05 and quality_score >= 45 and not diffuse:
-        return ("GREEN", "LIKELY NORMAL — very low AI TB signal (image quality suboptimal)")
+    # Very low probability should not be forced to YELLOW just because attention is diffuse
+    if prob_tb < 0.01 and quality_score >= 45:
+        return ("GREEN", "✅ Very low TB signal detected by the CNN model.")
     if quality_score < 55:
-        return ("YELLOW", "NO DEFINITE TB FEATURES — low image quality, treat as indeterminate")
+        return ("YELLOW", "⚠️ Image quality is low; treat the result as indeterminate.")
     if diffuse:
-        return ("YELLOW", "NO DEFINITE TB FEATURES — non-focal/diffuse attention pattern")
+        return ("YELLOW", "⚠️ Attention is non-focal; treat the result as indeterminate.")
     if prob_tb >= TBNET_SCREEN_THR:
-        return ("YELLOW", "NO DEFINITE TB FEATURES — AI confidence limited")
-    return ("GREEN", "LIKELY NORMAL — no strong AI signal for TB")
+        return ("YELLOW", "⚠️ Screening-positive range; review recommended.")
+    return ("GREEN", "✅ No strong TB signal detected by the CNN model.")
 
 def make_mask_overlay(gray_u8: np.ndarray, mask_u8: np.ndarray) -> np.ndarray:
     base = cv2.cvtColor(gray_u8, cv2.COLOR_GRAY2RGB)
@@ -340,7 +389,7 @@ def fill_holes(binary_u8: np.ndarray) -> np.ndarray:
     m = (binary_u8 * 255).astype(np.uint8)
     h, w = m.shape
     flood = m.copy()
-    mask = np.zeros((h+2, w+2), np.uint8)
+    mask = np.zeros((h + 2, w + 2), np.uint8)
     cv2.floodFill(flood, mask, (0, 0), 255)
     holes = cv2.bitwise_not(flood)
     filled = cv2.bitwise_or(m, holes)
@@ -367,7 +416,7 @@ def mask_sanity_warnings(mask_full_u8: np.ndarray) -> List[str]:
     warns = []
 
     if n <= 2:
-        warns.append("Only one lung component detected (possible crop/segmentation failure).")
+        warns.append("Only one lung region detected (possible crop/segmentation failure).")
         return warns
 
     areas = []
@@ -379,27 +428,27 @@ def mask_sanity_warnings(mask_full_u8: np.ndarray) -> List[str]:
     top2 = areas[1] if len(areas) > 1 else 0
 
     if total > 0 and top1 / total > 0.80:
-        warns.append("Mask dominated by a single component (likely one lung / cropped view).")
+        warns.append("Mask dominated by a single region (possible cropped/partial lung view).")
 
     border = np.concatenate([m[0, :], m[-1, :], m[:, 0], m[:, -1]])
     if border.mean() > 0.05:
-        warns.append("Lung mask touches image border (possible cropped/non-standard CXR).")
+        warns.append("Lung mask touches the image border (possible cropped/non-standard CXR).")
 
     if total > 0 and (top1 + top2) / total < 0.90:
-        warns.append("Significant mask fragmentation/holes (post-processing may be insufficient).")
+        warns.append("Mask appears fragmented (may reduce reliability).")
 
     return warns
 
 def recommendation_for_band(band: Optional[str]) -> str:
     if band in (None, "YELLOW"):
-        return "✅ Recommendation: Radiologist interpretation recommended (AI result is indeterminate / not definitive)."
+        return "✅ Recommendation: Radiologist/clinician review is recommended (result is indeterminate)."
     if band == "RED":
-        return "✅ Recommendation: Urgent clinician/radiologist review + microbiological confirmation (CBNAAT/GeneXpert, sputum)."
-    return "✅ Recommendation: If symptoms/risk factors exist, clinician/radiologist correlation is still advised."
+        return "✅ Recommendation: Urgent clinical review + microbiological confirmation (CBNAAT/GeneXpert, sputum)."
+    return "✅ Recommendation: If symptoms/risk factors exist, clinical correlation is advised."
 
 
 # ============================================================
-# CONSENSUS LOGIC (TBNet vs RADIO) — 3-state
+# AGREEMENT LOGIC (TBNet vs RADIO) — 3-state
 # ============================================================
 def tbnet_state(tb_prob: float, tb_band: str) -> str:
     if tb_band == "RED":
@@ -424,7 +473,7 @@ def build_consensus(
 ) -> Tuple[str, str]:
 
     if tb_prob is None or tb_band is None:
-        return ("N/A", "TBNet unavailable (lung segmentation failed / fail-safe).")
+        return ("N/A", f"{MODEL_NAME_TBNET} not available (lung segmentation failed / fail-safe).")
 
     # PRIMARY = masked if available else raw
     if radio_masked is not None:
@@ -435,7 +484,7 @@ def build_consensus(
         radio_used = "RAW"
 
     if radio_primary is None:
-        return ("TBNet only", f"RADIO unavailable → TBNet={tb_prob:.4f} (band={tb_band}).")
+        return ("TBNet only", f"{MODEL_NAME_RADIO} not available → {MODEL_NAME_TBNET} probability={tb_prob:.4f} (band={tb_band}).")
 
     t = tbnet_state(tb_prob, tb_band)
     r = radio_state_from_prob(radio_primary)
@@ -445,18 +494,19 @@ def build_consensus(
     if t == r:
         return (
             f"AGREE: {t}",
-            f"Both: {t}. TBNet={tb_prob:.4f}, RADIO({radio_used})={radio_primary:.4f}{rb}."
+            f"Both models indicate **{t}**. {MODEL_NAME_TBNET}={tb_prob:.4f}, {MODEL_NAME_RADIO}({radio_used})={radio_primary:.4f}{rb}."
         )
 
+    # strong disagreement: one says SCREEN+/TB+ and the other says LOW
     if (t in ("SCREEN+", "TB+") and r == "LOW") or (r in ("SCREEN+", "TB+") and t == "LOW"):
         return (
             "DISAGREE",
-            f"Strong disagreement: TBNet={t} (band={tb_band}) vs RADIO={r} ({radio_used})={radio_primary:.4f}{rb}."
+            f"Models disagree: {MODEL_NAME_TBNET} suggests **{t}** (band={tb_band}) vs {MODEL_NAME_RADIO} suggests **{r}** ({radio_used})={radio_primary:.4f}{rb}."
         )
 
     return (
         "MIXED/INDET",
-        f"Mixed/uncertain: TBNet={t} (band={tb_band}) vs RADIO={r} ({radio_used})={radio_primary:.4f}{rb}."
+        f"Mixed signals: {MODEL_NAME_TBNET} suggests **{t}** vs {MODEL_NAME_RADIO} suggests **{r}** ({radio_used})={radio_primary:.4f}{rb}."
     )
 
 
@@ -487,6 +537,7 @@ class ModelBundle:
             load_tb_weights(tb, tb_weights, self.device)
             tb.eval()
             self.tb = tb
+            # EfficientNet in timm has conv_head on effb0
             self.cammer = GradCAM(tb, tb.backbone.conv_head)
             self.tb_path = tb_weights
             self.backbone = backbone
@@ -515,6 +566,7 @@ class RadioMLPHead(nn.Module):
             nn.Dropout(dropout),
             nn.Linear(hidden, 1),
         )
+
     def forward(self, x: torch.Tensor) -> torch.Tensor:
         return self.net(x).squeeze(1)
 
@@ -582,6 +634,7 @@ def radio_overlay_heatmap(rgb_u8: np.ndarray, heatmap01: np.ndarray, alpha: floa
     img = rgb_u8.astype(np.float32) / 255.0
     hm = np.clip(heatmap01, 0, 1).astype(np.float32)
     out = img.copy()
+    # subtle red overlay
     out[..., 0] = np.clip(out[..., 0] * (1 - alpha) + hm * alpha, 0, 1)
     return (out * 255).astype(np.uint8)
 
@@ -649,10 +702,10 @@ def radio_predict_from_arrays(gray_vis_u8: np.ndarray,
 
     if prob_primary >= RADIO_THR_RED:
         band = "RED"
-        pred = "LIKELY TB (RADIO)"
+        pred = "TB FEATURES SUSPECTED (RADIO)"
     elif prob_primary >= RADIO_THR_SCREEN:
         band = "YELLOW"
-        pred = "SCREEN-POSITIVE / INDETERMINATE (RADIO)"
+        pred = "SCREEN-POSITIVE RANGE (RADIO)"
     else:
         band = "GREEN"
         pred = "LOW TB LIKELIHOOD (RADIO)"
@@ -678,7 +731,7 @@ def analyze_one_image(
     tb_weights: str,
     lung_weights: str,
     backbone: str,
-    threshold: float,
+    threshold: float,  # kept for UI compatibility; main logic uses TBNET_SCREEN_THR
     phone_mode: bool,
     img_size: int = 224,
     fail_cov: float = FAIL_COV,
@@ -720,11 +773,14 @@ def analyze_one_image(
             "logit": None,
             "pred": "INDETERMINATE",
             "band": "YELLOW",
-            "band_text": "Lung segmentation failed. AI TB assessment cannot be performed reliably on this image.",
+            "band_text": (
+                "⚠️ The lung segmentation looks unreliable, so the TB screening score is disabled for safety.\n\n"
+                "Please use a clearer frontal chest X-ray (PA/AP) or seek radiologist review."
+            ),
             "quality_score": float(q_score),
             "diffuse_risk": False,
             "warnings": (
-                ["Lung segmentation failed (<10% lung area).", f"Lung coverage: {coverage*100:.1f}%"]
+                [f"Lung segmentation coverage is too small ({coverage*100:.1f}%)."]
                 + (["Phone/WhatsApp mode enabled; artifacts possible."] if phone_mode else [])
                 + q_warn
             ),
@@ -748,7 +804,11 @@ def analyze_one_image(
             "logit": None,
             "pred": "INDETERMINATE",
             "band": "YELLOW",
-            "band_text": "Non-standard/cropped view or unreliable lung segmentation. TB scoring disabled (fail-safe).",
+            "band_text": (
+                "⚠️ The image appears cropped/non-standard (mask sanity check). "
+                "TB screening score is disabled for safety.\n\n"
+                "Please use a standard frontal chest X-ray (PA/AP) or seek radiologist review."
+            ),
             "quality_score": float(q_score),
             "diffuse_risk": False,
             "warnings": (
@@ -783,39 +843,42 @@ def analyze_one_image(
     cam_up = cam_u8.astype(np.float32) / 255.0
 
     diffuse = detect_diffuse_risk(prob_tb, cam_up, q_score)
-    band_base, _ = confidence_band(prob_tb, q_score, diffuse)
+    band_base, _band_hint = confidence_band(prob_tb, q_score, diffuse)
 
-    allow_red = (prob_tb >= 0.70 and q_score >= 55 and not diffuse and coverage >= warn_cov)
+    allow_red = (prob_tb >= 0.70 and q_score >= 55 and (not diffuse) and coverage >= warn_cov)
     band = "RED" if allow_red else band_base
 
     pred = REPORT_LABELS[band]["title"]
     band_text = REPORT_LABELS[band]["summary"]
 
-    abnormal_non_tb = (prob_tb >= 0.60 and q_score < 55 and band != "RED")
-    if abnormal_non_tb:
+    # Extra helpful line if YELLOW but probability is very low
+    if band == "YELLOW" and prob_tb < 0.05:
         band_text = (
-            "Significant abnormal lung findings detected. "
-            "Findings are non-specific and not characteristic of pulmonary tuberculosis. "
-            "Image quality may affect AI reliability."
+            "���️ TB probability is very low, but the result is marked **indeterminate** because reliability is limited.\n\n"
+            + band_text
         )
 
+    # Build Grad-CAM overlay
     heat = cv2.applyColorMap((cam_up * 255).astype(np.uint8), cv2.COLORMAP_JET)
     overlay_clean = cv2.addWeighted(rgb, 0.65, heat, 0.35, 0)
 
     overlay_annotated = overlay_clean.copy()
     text1 = f"{band}: {pred}"
-    text2 = f"TB prob={prob_tb:.3f} | Quality={q_score:.0f}/100 | Lung coverage={coverage*100:.1f}%"
+    text2 = f"TBNet prob={prob_tb:.3f} | Quality={q_score:.0f}/100 | Lung coverage={coverage*100:.1f}%"
     cv2.putText(overlay_annotated, text1, (8, 20), cv2.FONT_HERSHEY_SIMPLEX, 0.52, (255, 255, 255), 2)
     cv2.putText(overlay_annotated, text1, (8, 20), cv2.FONT_HERSHEY_SIMPLEX, 0.52, (0, 0, 0), 1)
     cv2.putText(overlay_annotated, text2, (8, 42), cv2.FONT_HERSHEY_SIMPLEX, 0.50, (255, 255, 255), 2)
     cv2.putText(overlay_annotated, text2, (8, 42), cv2.FONT_HERSHEY_SIMPLEX, 0.50, (0, 0, 0), 1)
 
     warnings = []
-    if phone_mode: warnings.append("Phone/WhatsApp mode enabled; artifacts possible.")
-    if q_score < 55: warnings.append("Suboptimal image quality limits AI reliability.")
-    if coverage < warn_cov: warnings.append(f"Partial lung segmentation ({coverage*100:.1f}% coverage).")
-    if diffuse: warnings.append("Diffuse, non-focal AI attention pattern; TB-specific features not identified.")
-    if abnormal_non_tb: warnings.append("Abnormal lung findings detected; pattern not specific for tuberculosis.")
+    if phone_mode:
+        warnings.append("Phone/WhatsApp mode enabled; artifacts possible.")
+    if q_score < 55:
+        warnings.append("Image quality is low; reliability may be reduced.")
+    if coverage < warn_cov:
+        warnings.append(f"Partial lung segmentation ({coverage*100:.1f}% coverage).")
+    if diffuse:
+        warnings.append("Non-focal attention pattern; result treated cautiously.")
     warnings.extend(q_warn)
 
     return {
@@ -886,7 +949,7 @@ def run_analysis(
         # -------------------------
         # RADIO (optional)
         # -------------------------
-        radio_text = "RADIO disabled."
+        radio_text = f"{MODEL_NAME_RADIO} is disabled."
         radio_raw_overlay = None
         radio_masked_overlay = None
         radio_raw_val: Optional[float] = None
@@ -914,14 +977,14 @@ def run_analysis(
                 radio_masked_str = "" if radio_masked_val is None else f"{radio_masked_val:.4f}"
 
                 radio_text = (
-                    f"**RADIO:** {r['pred']} | RAW={radio_raw_val:.4f}"
+                    f"**{MODEL_NAME_RADIO} result:** {r['pred']} | RAW={radio_raw_val:.4f}"
                     + (f" | MASKED={radio_masked_val:.4f}" if radio_masked_val is not None else "")
                     + f" | Band={radio_band}"
                 )
                 radio_raw_overlay = r["raw_overlay"]
                 radio_masked_overlay = r["masked_overlay"]
             except Exception as e:
-                radio_text = f"RADIO error: {type(e).__name__}: {e}"
+                radio_text = f"{MODEL_NAME_RADIO} error: {type(e).__name__}: {e}"
                 radio_raw_str = ""
                 radio_masked_str = ""
                 radio_raw_val = None
@@ -929,7 +992,7 @@ def run_analysis(
                 radio_band = None
 
         # -------------------------
-        # Consensus
+        # Agreement between models
         # -------------------------
         consensus_label, consensus_detail = build_consensus(
             tb_prob=out["prob"],
@@ -974,7 +1037,7 @@ def run_analysis(
             proc_rgb = cv2.cvtColor(cv2.resize(out["proc_gray"], (512, 512)), cv2.COLOR_GRAY2RGB)
             gallery_items.append((proc_rgb, f"{name} • Masked model input (224x224)"))
 
-        gallery_items.append((overlay_big, f"{name} • Grad-CAM overlay (TBNet)"))
+        gallery_items.append((overlay_big, f"{name} • Grad-CAM overlay ({MODEL_NAME_TBNET})"))
 
         if radio_raw_overlay is not None:
             gallery_items.append((cv2.resize(radio_raw_overlay, (512, 512)), f"{name} • RADIO RAW heatmap"))
@@ -982,37 +1045,37 @@ def run_analysis(
             gallery_items.append((cv2.resize(radio_masked_overlay, (512, 512)), f"{name} • RADIO MASKED heatmap"))
 
         # -------------------------
-        # Details panel
+        # Details panel (user-friendly)
         # -------------------------
         warn_txt = "\n".join([f"- {w}" for w in out["warnings"]]) if out["warnings"] else "- None"
-        tb_line = "N/A (segmentation failed / fail-safe)" if out["prob"] is None else f"{out['prob']:.4f}"
+        tb_line = "N/A (disabled by fail-safe)" if out["prob"] is None else f"{out['prob']:.4f}"
         rec_line = recommendation_for_band(out.get("band"))
 
         details_md.append(
             f"""### {name}
 
-**AI Assessment (TBNet):** **{out['pred']}**
+**{MODEL_NAME_TBNET} result:** **{out['pred']}**
 {rec_line}
 
-**TB Probability (screening model):** {tb_line}
-
-**Interpretation**
+**What this means**
 {out['band_text']}
 
-**Image Quality:** {out['quality_score']:.0f}/100
-**Lung Mask Coverage:** {out.get('lung_coverage', 0.0) * 100:.1f}%
-**AI Attention Pattern (TBNet):** {"Diffuse / non-focal" if out["diffuse_risk"] else "Focal / localized"}
+**Why it decided this**
+- {MODEL_NAME_TBNET} probability: {tb_line}
+- Image quality: {out['quality_score']:.0f}/100
+- Lung mask coverage: {out.get('lung_coverage', 0.0) * 100:.1f}%
+- Attention pattern (TBNet): {"Diffuse / non-focal" if out["diffuse_risk"] else "Focal / localized"}
 
-**Warnings**
+**Notes that may affect reliability**
 {warn_txt}
 
-**RADIO Output**
+**{MODEL_NAME_RADIO} output**
 {radio_text}
 
-**Final consensus (TBNet vs RADIO):** **{consensus_label}**
+**Agreement between models (TBNet vs RADIO):** **{consensus_label}**
 - {consensus_detail}
 
-**Clinical Guidance**
+**Clinical guidance**
 {CLINICAL_GUIDANCE}
 
 ---
@@ -1034,39 +1097,52 @@ def build_ui():
 
     with gr.Blocks(title="TB X-ray Assistant (TBNet + RADIO)", css=css) as demo:
         gr.Markdown('<div class="title">TB X-ray Assistant (Auto Lung Mask • Research Use)</div>')
-        gr.Markdown('<div class="subtitle">Lung U-Net masking → EfficientNet TBNet + Grad-CAM • Optional RADIO (C-RADIOv4 + heads) • 3-state consensus</div>')
+        gr.Markdown(
+            f"<div class='subtitle'>Lung U-Net masking → <b>{MODEL_NAME_TBNET}</b> + Grad-CAM • "
+            f"Optional <b>{MODEL_NAME_RADIO}</b> (C-RADIOv4 + heads) • Agreement summary</div>"
+        )
 
         with gr.Row():
             with gr.Column(scale=1):
                 gr.Markdown("#### Model settings")
 
-                tb_weights = gr.Textbox(label="TB Weights (.pt)", value=DEFAULT_TB_WEIGHTS)
-                lung_weights = gr.Textbox(label="Lung U-Net Weights (.pt)", value=DEFAULT_LUNG_WEIGHTS)
+                tb_weights = gr.Textbox(label="TBNet weights (.pt)", value=DEFAULT_TB_WEIGHTS)
+                lung_weights = gr.Textbox(label="Lung U-Net weights (.pt)", value=DEFAULT_LUNG_WEIGHTS)
 
-                backbone = gr.Dropdown(choices=["efficientnet_b0"], value="efficientnet_b0", label="Backbone")
+                backbone = gr.Dropdown(choices=["efficientnet_b0"], value="efficientnet_b0", label="TBNet backbone")
 
-                threshold = gr.Slider(0.01, 0.99, value=TBNET_SCREEN_THR, step=0.01,
-                                      label=f"Reference threshold (TBNet screen+) = {TBNET_SCREEN_THR:.2f}")
+                threshold = gr.Slider(
+                    0.01, 0.99, value=TBNET_SCREEN_THR, step=0.01,
+                    label=f"Reference threshold (TBNet SCREEN+) = {TBNET_SCREEN_THR:.2f}"
+                )
 
-                phone_mode = gr.Checkbox(value=False,
-                                         label="Phone/WhatsApp Mode (SAFE: conditional crop + conditional CLAHE)")
+                phone_mode = gr.Checkbox(
+                    value=False,
+                    label="Phone/WhatsApp Mode (safe: conditional crop + conditional CLAHE)"
+                )
 
                 # RADIO
-                use_radio = gr.Checkbox(value=False, label="Enable RADIO layer (C-RADIOv4 + heads)")
-                radio_gate = gr.Slider(0.10, 0.40, value=RADIO_GATE_DEFAULT, step=0.01,
-                                       label="RADIO masked gate (run masked head if lung coverage ≥ gate)")
+                use_radio = gr.Checkbox(value=False, label=f"Enable {MODEL_NAME_RADIO}")
+                radio_gate = gr.Slider(
+                    0.10, 0.40, value=RADIO_GATE_DEFAULT, step=0.01,
+                    label="RADIO masked gate (run masked head if lung coverage ≥ gate)"
+                )
 
                 gr.Markdown(
-                    '<div class="warnbox"><b>Fail-safe:</b> If lung segmentation is too small or looks like a cropped/single-lung mask, TB scoring is disabled to avoid false positives.</div>'
+                    "<div class='warnbox'><b>Fail-safe:</b> If lung segmentation is too small or looks unreliable, "
+                    "TBNet scoring is disabled to avoid unsafe outputs.</div>"
                 )
 
                 gr.Markdown(
-                    f"<div class='subtitle'>Device for TB+RADIO: <b>{DEVICE}</b> (set FORCE_CPU=True to force CPU)</div>"
+                    f"<div class='subtitle'>Device: <b>{DEVICE}</b> (FORCE_CPU={FORCE_CPU})</div>"
                 )
 
             with gr.Column(scale=2):
                 gr.Markdown("#### Upload images")
-                files = gr.Files(label="Upload one or multiple X-ray images", file_types=[".png", ".jpg", ".jpeg", ".bmp"])
+                files = gr.Files(
+                    label="Upload one or multiple chest X-ray images",
+                    file_types=[".png", ".jpg", ".jpeg", ".bmp"]
+                )
                 run_btn = gr.Button("Run Analysis", variant="primary")
                 status = gr.Textbox(label="Status", value="Ready.", interactive=False)
 
@@ -1074,15 +1150,15 @@ def build_ui():
             table = gr.Dataframe(
                 headers=[
                     "Image",
-                    "TB Probability",
-                    "AI Assessment",
+                    "TBNet Probability",
+                    "TBNet Result",
                     "Band",
-                    "Band meaning",
+                    "Meaning",
                     "Quality",
                     "LungCov",
                     "RADIO RAW",
                     "RADIO MASKED",
-                    "CONSENSUS",
+                    "AGREEMENT",
                 ],
                 datatype=["str","str","str","str","str","str","str","str","str","str"],
                 interactive=False,