feat: rewrite PDF report with narrative structure (The Place, Assessment, Deep Dives, Annex)

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

app/outputs/report.py

@@ -160,8 +160,16 @@ def _status_badge_table(status: StatusLevel, styles: dict) -> Table:
     return t
 
 
-def _indicator_block(result: IndicatorResult, styles: dict, map_path: str = "") -> list:
+def _indicator_block(
+    result: IndicatorResult,
+    styles: dict,
+    map_path: str = "",
+    chart_path: str = "",
+) -> list:
     """Build the flowables for a single indicator section."""
+    from app.outputs.narrative import get_interpretation
+    from reportlab.platypus import Image
+
     elements = []
 
     # Badge + headline row
@@ -190,30 +198,53 @@ def _indicator_block(result: IndicatorResult, styles: dict, map_path: str = "")
         ))
         elements.append(Spacer(1, 2 * mm))
 
-    # Confidence + trend meta line
-    meta = (
-        f"Confidence: <b>{result.confidence.value.capitalize()}</b> &nbsp; | &nbsp; "
-        f"Trend: <b>{result.trend.value.capitalize()}</b>"
-    )
-    elements.append(Paragraph(meta, styles["body_muted"]))
-    elements.append(Spacer(1, 2 * mm))
+    # Map and chart side by side (if both exist), or single image
+    map_exists = map_path and os.path.exists(map_path)
+    chart_exists = chart_path and os.path.exists(chart_path)
 
-    # Indicator map
-    if map_path and os.path.exists(map_path):
-        from reportlab.platypus import Image
+    if map_exists and chart_exists:
+        map_img = Image(map_path, width=8 * cm, height=6 * cm)
+        chart_img = Image(chart_path, width=8 * cm, height=6 * cm)
+        img_table = Table(
+            [[map_img, chart_img]],
+            colWidths=[8.5 * cm, 8.5 * cm],
+        )
+        img_table.setStyle(TableStyle([
+            ("ALIGN", (0, 0), (-1, -1), "CENTER"),
+            ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+            ("LEFTPADDING", (0, 0), (-1, -1), 0),
+            ("RIGHTPADDING", (0, 0), (-1, -1), 0),
+        ]))
+        elements.append(img_table)
+        elements.append(Spacer(1, 2 * mm))
+    elif map_exists:
         img = Image(map_path, width=12 * cm, height=9 * cm)
         img.hAlign = "CENTER"
         elements.append(img)
         elements.append(Spacer(1, 2 * mm))
+    elif chart_exists:
+        img = Image(chart_path, width=12 * cm, height=9 * cm)
+        img.hAlign = "CENTER"
+        elements.append(img)
+        elements.append(Spacer(1, 2 * mm))
 
-    # Summary
+    # What the data shows
+    elements.append(Paragraph("<b>What the data shows</b>", styles["body_muted"]))
     elements.append(Paragraph(result.summary, styles["body"]))
 
-    # Limitations
-    if result.limitations:
-        elements.append(Paragraph("Limitations:", styles["body_muted"]))
-        for lim in result.limitations:
-            elements.append(Paragraph(f"\u2022 {lim}", styles["limitation"]))
+    # What this means
+    interpretation = get_interpretation(result.indicator_id, result.status)
+    elements.append(Paragraph("<b>What this means</b>", styles["body_muted"]))
+    elements.append(Paragraph(interpretation, styles["body"]))
+
+    # Data quality line
+    data_source_label = result.data_source or "unknown"
+    quality_line = (
+        f"Confidence: <b>{result.confidence.value.capitalize()}</b> &nbsp;|&nbsp; "
+        f"Trend: <b>{result.trend.value.capitalize()}</b> &nbsp;|&nbsp; "
+        f"Source: <b>{data_source_label}</b>"
+    )
+    elements.append(Paragraph(quality_line, styles["body_muted"]))
 
     elements.append(Spacer(1, 4 * mm))
     elements.append(
@@ -223,6 +254,19 @@ def _indicator_block(result: IndicatorResult, styles: dict, map_path: str = "")
     return elements
 
 
+def _detect_data_sources(results: Sequence[IndicatorResult]) -> str:
+    """Scan methodology text to auto-detect known satellite data sources."""
+    known_sources = ["Sentinel-2", "Sentinel-1", "FIRMS", "CHIRPS", "MODIS", "Landsat", "VIIRS"]
+    found: list[str] = []
+    combined_text = " ".join(r.methodology for r in results)
+    for src in known_sources:
+        if src.lower() in combined_text.lower() and src not in found:
+            found.append(src)
+    if not found:
+        return "Open-source satellite imagery"
+    return ", ".join(found)
+
+
 def generate_pdf_report(
     *,
     aoi: AOI,
@@ -247,6 +291,8 @@ def generate_pdf_report(
     output_path:
         Absolute path where the PDF should be saved.
     """
+    from app.outputs.narrative import generate_narrative
+
     styles = _build_styles()
     PAGE_W, PAGE_H = A4
     MARGIN = 2 * cm
@@ -282,16 +328,30 @@ def generate_pdf_report(
     )
     doc.pageBackgrounds = [colors.white]
 
-    story = []
-
-    # ------------------------------------------------------------------ #
-    #  Title block                                                        #
-    # ------------------------------------------------------------------ #
     from datetime import datetime as _dt, timezone as _tz
     generated_at = _dt.now(_tz.utc).strftime("%Y-%m-%d %H:%M UTC")
 
+    # Output directory for chart path auto-detection
+    output_dir = os.path.dirname(output_path)
+
+    story = []
+
+    # ================================================================== #
+    #  SECTION 1: The Place                                               #
+    # ================================================================== #
     story.append(Paragraph("MERLx Aperture — Situation Report", styles["title"]))
     story.append(Paragraph(aoi.name, styles["subtitle"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # Overview map (full width)
+    if overview_map_path and os.path.exists(overview_map_path):
+        from reportlab.platypus import Image
+        img = Image(overview_map_path, width=14 * cm, height=10.5 * cm)
+        img.hAlign = "CENTER"
+        story.append(img)
+        story.append(Spacer(1, 3 * mm))
+
+    # AOI metadata
     story.append(
         Paragraph(
             f"Analysis period: {time_range.start} \u2013 {time_range.end}",
@@ -306,25 +366,28 @@ def generate_pdf_report(
             styles["body_muted"],
         )
     )
+
+    # Auto-detected data sources
+    data_sources_str = _detect_data_sources(results)
+    story.append(
+        Paragraph(
+            f"Data sources: {data_sources_str}",
+            styles["body_muted"],
+        )
+    )
+
     story.append(Spacer(1, 4 * mm))
     story.append(HRFlowable(width="100%", thickness=1, color=INK_MUTED))
     story.append(Spacer(1, 6 * mm))
 
-    # ------------------------------------------------------------------ #
-    #  Visual Overview                                                    #
-    # ------------------------------------------------------------------ #
-    if overview_score:
-        story.append(Paragraph("Area Overview", styles["section_heading"]))
-
-        # Overview map (full width)
-        if overview_map_path and os.path.exists(overview_map_path):
-            from reportlab.platypus import Image
-            img = Image(overview_map_path, width=14 * cm, height=10.5 * cm)
-            img.hAlign = "CENTER"
-            story.append(img)
-            story.append(Spacer(1, 3 * mm))
+    # ================================================================== #
+    #  SECTION 2: Situation Assessment                                    #
+    # ================================================================== #
+    story.append(Paragraph("Situation Assessment", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
 
-        # Composite score badge + headline
+    # Composite badge + headline (if overview_score provided)
+    if overview_score:
         composite_status_enum = {
             "GREEN": StatusLevel.GREEN,
             "AMBER": StatusLevel.AMBER,
@@ -349,178 +412,111 @@ def generate_pdf_report(
         story.append(row)
         story.append(Spacer(1, 4 * mm))
 
-        # Summary table: all indicators in compact grid
-        summary_header = [
-            Paragraph("<b>Indicator</b>", styles["body"]),
-            Paragraph("<b>Status</b>", styles["body"]),
-            Paragraph("<b>Trend</b>", styles["body"]),
-            Paragraph("<b>Confidence</b>", styles["body"]),
-            Paragraph("<b>Headline</b>", styles["body"]),
-        ]
-        summary_rows = [summary_header]
-        for result in results:
-            label = _indicator_label(result.indicator_id)
-            status_color = STATUS_COLORS[result.status]
-            status_cell = Paragraph(
-                f'<font color="white"><b>{STATUS_LABELS[result.status]}</b></font>',
-                ParagraphStyle(
-                    "ov_badge",
-                    fontName="Helvetica-Bold",
-                    fontSize=7,
-                    textColor=colors.white,
-                    alignment=TA_CENTER,
-                ),
-            )
-            summary_rows.append([
-                Paragraph(label, styles["body_muted"]),
-                status_cell,
-                Paragraph(result.trend.value.capitalize(), styles["body_muted"]),
-                Paragraph(result.confidence.value.capitalize(), styles["body_muted"]),
-                Paragraph(result.headline[:80], styles["body_muted"]),
-            ])
-
-        ov_col_w = (PAGE_W - 2 * MARGIN)
-        ov_table = Table(
-            summary_rows,
-            colWidths=[ov_col_w * 0.15, ov_col_w * 0.10, ov_col_w * 0.12, ov_col_w * 0.13, ov_col_w * 0.50],
-        )
-        ov_ts = TableStyle([
-            ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#E8E6E0")),
-            ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor(_SHELL_HEX)]),
-            ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#D8D5CF")),
-            ("TOPPADDING", (0, 0), (-1, -1), 3),
-            ("BOTTOMPADDING", (0, 0), (-1, -1), 3),
-            ("LEFTPADDING", (0, 0), (-1, -1), 4),
-            ("RIGHTPADDING", (0, 0), (-1, -1), 4),
-            ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
-            ("ALIGN", (1, 1), (1, -1), "CENTER"),
-        ])
-        for row_idx, result in enumerate(results, start=1):
-            ov_ts.add("BACKGROUND", (1, row_idx), (1, row_idx), STATUS_COLORS[result.status])
-        ov_table.setStyle(ov_ts)
-        story.append(ov_table)
-
-        story.append(Spacer(1, 6 * mm))
-        story.append(HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF")))
-        story.append(Spacer(1, 4 * mm))
-
-    # ------------------------------------------------------------------ #
-    #  How to Read This Report                                           #
-    # ------------------------------------------------------------------ #
-    story.append(Paragraph("How to Read This Report", styles["section_heading"]))
-    how_to = (
-        "Each indicator is assigned a traffic-light status: "
-        "<b><font color='{}'>GREEN</font></b> indicates conditions within the normal range, "
-        "<b><font color='{}'>AMBER</font></b> indicates elevated concern requiring monitoring, "
-        "and <b><font color='{}'>RED</font></b> indicates a critical situation requiring immediate attention. "
-        "Trend arrows indicate the direction of change over the analysis period. "
-        "Confidence levels reflect data quality and coverage."
-    ).format(_GREEN_HEX, _AMBER_HEX, _RED_HEX)
-    story.append(Paragraph(how_to, styles["body"]))
-    story.append(Spacer(1, 4 * mm))
-
-    # ------------------------------------------------------------------ #
-    #  Executive Summary                                                  #
-    # ------------------------------------------------------------------ #
+    # Cross-indicator narrative
     red_count = sum(1 for r in results if r.status == StatusLevel.RED)
     amber_count = sum(1 for r in results if r.status == StatusLevel.AMBER)
     green_count = sum(1 for r in results if r.status == StatusLevel.GREEN)
     total = len(results)
-
-    exec_summary_text = (
+    count_line = (
         f"This report covers <b>{total}</b> indicator(s) for <b>{aoi.name}</b> "
         f"over the period {time_range.start} to {time_range.end}. "
-        f"Of these, <b><font color='{_RED_HEX}'>{red_count} indicator(s)</font></b> are at "
-        f"<b><font color='{_RED_HEX}'>RED</font></b> status (critical concern), "
-        f"<b><font color='{_AMBER_HEX}'>{amber_count} indicator(s)</font></b> are at "
-        f"<b><font color='{_AMBER_HEX}'>AMBER</font></b> status (elevated concern), and "
-        f"<b><font color='{_GREEN_HEX}'>{green_count} indicator(s)</font></b> are at "
-        f"<b><font color='{_GREEN_HEX}'>GREEN</font></b> status (within normal range)."
+        f"<b><font color='{_RED_HEX}'>{red_count}</font></b> at RED, "
+        f"<b><font color='{_AMBER_HEX}'>{amber_count}</font></b> at AMBER, "
+        f"<b><font color='{_GREEN_HEX}'>{green_count}</font></b> at GREEN."
     )
-    story.append(Paragraph("Executive Summary", styles["section_heading"]))
-    story.append(Paragraph(exec_summary_text, styles["body"]))
-    story.append(Spacer(1, 6 * mm))
-
-    # ------------------------------------------------------------------ #
-    #  Summary Map                                                        #
-    # ------------------------------------------------------------------ #
-    if summary_map_path and os.path.exists(summary_map_path):
-        from reportlab.platypus import Image
-        img = Image(summary_map_path, width=14 * cm, height=10.5 * cm)
-        img.hAlign = "CENTER"
-        story.append(img)
-        story.append(Spacer(1, 4 * mm))
-
-    # ------------------------------------------------------------------ #
-    #  Indicator Results                                                  #
-    # ------------------------------------------------------------------ #
-    story.append(Paragraph("Indicator Results", styles["section_heading"]))
-    story.append(Spacer(1, 2 * mm))
+    story.append(Paragraph(count_line, styles["body"]))
 
-    for result in results:
-        indicator_label = _indicator_label(result.indicator_id)
-        block = [Paragraph(indicator_label, styles["section_heading"])]
-        map_path = (indicator_map_paths or {}).get(result.indicator_id, "")
-        block += _indicator_block(result, styles, map_path=map_path)
-        story.append(KeepTogether(block))
-
-    # ------------------------------------------------------------------ #
-    #  Status Summary Table                                               #
-    # ------------------------------------------------------------------ #
-    story.append(Paragraph("Status Summary", styles["section_heading"]))
-    story.append(Spacer(1, 2 * mm))
+    narrative_text = generate_narrative(results)
+    story.append(Paragraph(narrative_text, styles["body"]))
+    story.append(Spacer(1, 4 * mm))
 
-    table_header = [
+    # Compact summary table
+    summary_header = [
         Paragraph("<b>Indicator</b>", styles["body"]),
         Paragraph("<b>Status</b>", styles["body"]),
         Paragraph("<b>Trend</b>", styles["body"]),
         Paragraph("<b>Confidence</b>", styles["body"]),
+        Paragraph("<b>Headline</b>", styles["body"]),
     ]
-    table_data = [table_header]
+    summary_rows = [summary_header]
     for result in results:
         label = _indicator_label(result.indicator_id)
-        status_color = STATUS_COLORS[result.status]
         status_cell = Paragraph(
             f'<font color="white"><b>{STATUS_LABELS[result.status]}</b></font>',
             ParagraphStyle(
-                "tbl_badge",
+                "ov_badge",
                 fontName="Helvetica-Bold",
-                fontSize=8,
+                fontSize=7,
                 textColor=colors.white,
                 alignment=TA_CENTER,
             ),
         )
-        table_data.append([
-            Paragraph(label, styles["body"]),
+        summary_rows.append([
+            Paragraph(label, styles["body_muted"]),
             status_cell,
-            Paragraph(result.trend.value.capitalize(), styles["body"]),
-            Paragraph(result.confidence.value.capitalize(), styles["body"]),
+            Paragraph(result.trend.value.capitalize(), styles["body_muted"]),
+            Paragraph(result.confidence.value.capitalize(), styles["body_muted"]),
+            Paragraph(result.headline[:80], styles["body_muted"]),
         ])
 
-    col_w = (PAGE_W - 2 * MARGIN) / 4
-    summary_table = Table(table_data, colWidths=[col_w * 1.4, col_w * 0.7, col_w * 0.9, col_w])
-    ts = TableStyle([
+    ov_col_w = PAGE_W - 2 * MARGIN
+    ov_table = Table(
+        summary_rows,
+        colWidths=[
+            ov_col_w * 0.15,
+            ov_col_w * 0.10,
+            ov_col_w * 0.12,
+            ov_col_w * 0.13,
+            ov_col_w * 0.50,
+        ],
+    )
+    ov_ts = TableStyle([
         ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#E8E6E0")),
         ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor(_SHELL_HEX)]),
         ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#D8D5CF")),
-        ("TOPPADDING", (0, 0), (-1, -1), 4),
-        ("BOTTOMPADDING", (0, 0), (-1, -1), 4),
-        ("LEFTPADDING", (0, 0), (-1, -1), 6),
-        ("RIGHTPADDING", (0, 0), (-1, -1), 6),
+        ("TOPPADDING", (0, 0), (-1, -1), 3),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 3),
+        ("LEFTPADDING", (0, 0), (-1, -1), 4),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 4),
         ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
         ("ALIGN", (1, 1), (1, -1), "CENTER"),
     ])
-    # Apply status cell backgrounds dynamically
     for row_idx, result in enumerate(results, start=1):
-        ts.add("BACKGROUND", (1, row_idx), (1, row_idx), STATUS_COLORS[result.status])
-    summary_table.setStyle(ts)
-    story.append(summary_table)
+        ov_ts.add("BACKGROUND", (1, row_idx), (1, row_idx), STATUS_COLORS[result.status])
+    ov_table.setStyle(ov_ts)
+    story.append(ov_table)
+
     story.append(Spacer(1, 6 * mm))
+    story.append(HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF")))
+    story.append(Spacer(1, 4 * mm))
+
+    # ================================================================== #
+    #  SECTION 3: Indicator Deep Dives                                    #
+    # ================================================================== #
+    story.append(Paragraph("Indicator Detail", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
 
-    # ------------------------------------------------------------------ #
-    #  Data Sources & Methodology                                         #
-    # ------------------------------------------------------------------ #
-    story.append(Paragraph("Data Sources &amp; Methodology", styles["section_heading"]))
+    for result in results:
+        indicator_label = _indicator_label(result.indicator_id)
+        map_path = (indicator_map_paths or {}).get(result.indicator_id, "")
+
+        # Auto-detect chart path from output directory
+        chart_path = os.path.join(output_dir, f"{result.indicator_id}_chart.png")
+        if not os.path.exists(chart_path):
+            chart_path = ""
+
+        block = [Paragraph(indicator_label, styles["section_heading"])]
+        block += _indicator_block(result, styles, map_path=map_path, chart_path=chart_path)
+        story.append(KeepTogether(block))
+
+    # ================================================================== #
+    #  SECTION 4: Technical Annex                                         #
+    # ================================================================== #
+    story.append(Paragraph("Technical Annex", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # Methodology subsection
+    story.append(Paragraph("Methodology", styles["section_heading"]))
     for result in results:
         indicator_label = _indicator_label(result.indicator_id)
         story.append(
@@ -529,22 +525,33 @@ def generate_pdf_report(
                 styles["body"],
             )
         )
-    story.append(Spacer(1, 6 * mm))
+    story.append(Spacer(1, 4 * mm))
 
-    # ------------------------------------------------------------------ #
-    #  Disclaimer                                                         #
-    # ------------------------------------------------------------------ #
+    # Limitations subsection — deduplicated across all indicators
+    all_limitations: list[str] = []
+    seen: set[str] = set()
+    for result in results:
+        for lim in (result.limitations or []):
+            normalized = lim.strip().rstrip(".")
+            if normalized.lower() not in seen:
+                seen.add(normalized.lower())
+                all_limitations.append(lim)
+
+    if all_limitations:
+        story.append(Paragraph("Limitations", styles["section_heading"]))
+        for lim in all_limitations:
+            story.append(Paragraph(f"\u2022 {lim}", styles["limitation"]))
+        story.append(Spacer(1, 4 * mm))
+
+    # Disclaimer
     story.append(HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF")))
     story.append(Spacer(1, 3 * mm))
     disclaimer = (
         "This report has been generated automatically by MERLx Aperture using satellite "
         "remote sensing data. Results are intended to support humanitarian situation analysis "
         "and should be interpreted alongside ground-truth information and expert judgement. "
-        "MERLx Aperture makes no warranty as to the accuracy or completeness of the data presented. "
-        "All indicators are based on open-source satellite imagery and publicly available "
-        "geospatial datasets. Temporal coverage, cloud contamination, and sensor resolution "
-        "may affect the reliability of individual indicators. Users are encouraged to review "
-        "the methodology and limitations sections before drawing operational conclusions."
+        "Temporal coverage, cloud contamination, and sensor resolution may affect the "
+        "reliability of individual indicators."
     )
     story.append(Paragraph("Disclaimer", styles["section_heading"]))
     story.append(Paragraph(disclaimer, styles["body_muted"]))