Upload 20 files

report_engine.py

@@ -956,6 +956,56 @@ def _compact_scenario_comparison(df: pd.DataFrame) -> pd.DataFrame:
     wanted=["Display Scenario","Source Model","Storm","Storm Status","Simulation Status","Runoff Error (%)","Flow Error (%)","Peak Subcatchment Runoff","Maximum Storage Depth","Maximum Storage Volume","Peak Link Flow","Maximum Node Inflow","Maximum Node Flooding","Hydraulic Difference"]
     return out[[c for c in wanted if c in out.columns]].copy()
 
+def _embed_attached_figures(doc, figures: list[Mapping[str, Any]] | None) -> None:
+    """Insert session-attached figures into the built document.
+
+    Each figure dict: {"figure_id", "path", "caption", "section", "source"}.
+    Figures are inserted at the END of the first level-1 section whose
+    heading contains the requested section keyword (case-insensitive), i.e.
+    immediately before the next Heading-1 paragraph; unmatched sections fall
+    back to the end of the document. Client-supplied figures are labelled as
+    such — they are illustrative material attached to the audited report,
+    not server-verified outputs.
+    """
+    if not figures:
+        return
+    from docx.shared import Inches
+
+    headings = [(i, p) for i, p in enumerate(doc.paragraphs)
+                if p.style.name.startswith("Heading 1")]
+
+    def anchor_for(section_kw: str):
+        kw = (section_kw or "results").strip().lower()
+        for pos, (idx, para) in enumerate(headings):
+            if kw in para.text.lower():
+                if pos + 1 < len(headings):
+                    return headings[pos + 1][1]  # insert before next H1
+                return None  # matched last section -> append at end
+        return None
+
+    for n, fig in enumerate(figures, start=1):
+        path = str(fig.get("path", ""))
+        if not path or not Path(path).exists():
+            continue
+        caption = str(fig.get("caption") or fig.get("figure_id") or f"Attached figure {n}")
+        source = str(fig.get("source") or "session-attached")
+        label = f"Figure A{n} - {caption} ({source}; illustrative, not a server-verified output)"
+        anchor = anchor_for(str(fig.get("section", "results")))
+        try:
+            if anchor is not None:
+                pic_par = anchor.insert_paragraph_before()
+                pic_par.add_run().add_picture(path, width=Inches(6.0))
+                cap_par = anchor.insert_paragraph_before(label)
+                cap_par.style = doc.styles["Caption"] if "Caption" in [s.name for s in doc.styles] else cap_par.style
+            else:
+                doc.add_paragraph().add_run().add_picture(path, width=Inches(6.0))
+                doc.add_paragraph(label)
+        except Exception:
+            # A corrupt image must never abort report generation.
+            (anchor.insert_paragraph_before if anchor is not None else doc.add_paragraph)(
+                f"[Attached figure '{caption}' could not be embedded — file unreadable.]")
+
+
 def generate_report_package(
     *,
     metadata: ReportMetadata,
@@ -972,6 +1022,7 @@ def generate_report_package(
     scenario_records: list[Mapping[str, Any]] | None = None,
     scenario_reporting_mode: str = "Base report with scenario comparison",
     preliminary_review_artifacts: Mapping[str, Any] | None = None,
+    attached_figures: list[Mapping[str, Any]] | None = None,
 ) -> dict[str, bytes | str]:
     """Generate editable Word report and ZIP package entirely in memory."""
     criteria = criteria or ReportCriteria()
@@ -1339,7 +1390,9 @@ def generate_report_package(
             "scenario_comparison": scenario_comparison if scenario_comparison is not None else pd.DataFrame(),
         },
     )
-    docx_buffer = io.BytesIO(); doc.save(docx_buffer); docx_bytes = docx_buffer.getvalue()
+    docx_buffer = io.BytesIO()
+    _embed_attached_figures(doc, attached_figures)
+    doc.save(docx_buffer); docx_bytes = docx_buffer.getvalue()
     base = _safe_name(metadata.project_name)
 
     zip_buffer = io.BytesIO()
@@ -1377,6 +1430,17 @@ def generate_report_package(
                     if frame is not None and not frame.empty:
                         zf.writestr(f"tables/scenarios/{sid}_{key}.csv", frame.to_csv(index=False))
         zf.writestr("metadata/llm_report_context.json", json.dumps(llm_context, indent=2, default=str))
+        if attached_figures:
+            fig_manifest = []
+            for n, fig in enumerate(attached_figures, start=1):
+                fpath = Path(str(fig.get("path", "")))
+                if fpath.exists():
+                    zf.writestr(f"figures/{fpath.name}", fpath.read_bytes())
+                fig_manifest.append({"n": n, "figure_id": fig.get("figure_id"),
+                                     "file": fpath.name, "caption": fig.get("caption"),
+                                     "section": fig.get("section"), "source": fig.get("source"),
+                                     "note": "Client-attached illustrative figure; not a server-verified output."})
+            zf.writestr("metadata/attached_figures.json", json.dumps(fig_manifest, indent=2, default=str))
         zf.writestr("metadata/approved_narrative_sections.json", json.dumps(dict(narrative_sections or {}), indent=2, ensure_ascii=False))
         zf.writestr("metadata/project_metadata.json", json.dumps(asdict(metadata), indent=2))
         zf.writestr("metadata/report_criteria.json", json.dumps(asdict(criteria), indent=2, default=str))

requirements.txt

@@ -3,8 +3,8 @@ mcp>=1.10,<2
 fastapi>=0.110
 uvicorn>=0.29
 httpx>=0.27
+requests>=2.31
 pandas>=2.0
 numpy>=1.26
 python-docx>=1.1
 PyYAML>=6.0
-requests>=2.31

smoke_test.py

@@ -33,6 +33,14 @@ async def main():
             print(f"MCP workflow: session {sid} | recon {recon.get('ok')}/{recon.get('links_checked')}")
             if "Kincora" in INP:
                 assert recon.get("ok", 0) >= 26, "REGRESSION PIN FAILED"
+            # 1x1 red PNG — validates the attach_figure -> embedded-report path
+            tiny_png = ("iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4"
+                        "2mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==")
+            fig = json.loads((await s.call_tool("attach_figure",
+                {"session_id": sid, "image_base64": tiny_png,
+                 "caption": "Smoke-test figure", "section": "results"})).content[0].text)
+            assert fig["figure_id"] == "FIG-01", fig
+            print("attach_figure: OK", fig["figure_id"])
             rep = json.loads((await s.call_tool("generate_report",
                 {"session_id": sid, "project_name": "Smoke Test"})).content[0].text)
             dl = httpx.get(f"{BASE}{rep['files']['docx']}", timeout=60)

tools.py

@@ -220,8 +220,13 @@ def get_timeseries(session_id: str, object_type: str, object_id: str, variable:
     else:
         points = [{"t": str(times[i]) if i < len(times) else i, "v": round(float(v), 6)}
                   for i, v in enumerate(series)]
+    peak_val = max(series, key=abs, default=0.0)
+    peak_idx = series.index(peak_val) if series else 0
+    time_of_peak = str(times[peak_idx]) if peak_idx < len(times) else None
     return {"object_id": object_id, "variable": variable, "n_source_points": n,
-            "decimated": n > MAX_TS_POINTS, "peak": round(float(max(series, key=abs, default=0.0)), 6),
+            "decimated": n > MAX_TS_POINTS, "peak": round(float(peak_val), 6),
+            "time_of_peak": time_of_peak,
+            "note": "time_of_peak is from the full-resolution series; do not infer it from decimated point labels.",
             "points": points}
 
 
@@ -349,6 +354,46 @@ def run_scenario(session_id: str, scenario_name: str,
             "deterministic_analysis": narrative[:6000]}
 
 
+def attach_figure(session_id: str, image_base64: str, caption: str,
+                  section: str = "results", figure_name: str = "") -> dict:
+    """Attach a client-generated figure (PNG/JPEG, base64) to the session so
+    generate_report embeds it in the AUDITED report instead of the client
+    rebuilding the document itself.
+
+    section: keyword matched against report Heading-1 titles (e.g. "results",
+    "methodology", "site"); the figure is placed at the end of that section.
+    Figures are labelled as client-attached illustrative material — they are
+    not server-verified outputs. Limits: PNG or JPEG, 5 MB decoded.
+    """
+    session = STORE.get(session_id)
+    try:
+        blob = base64.b64decode(image_base64, validate=True)
+    except (binascii.Error, ValueError) as exc:
+        raise ValueError(f"image_base64 is not valid base64: {exc}")
+    if len(blob) > 5 * 1024 * 1024:
+        raise ValueError("Figure exceeds the 5 MB limit.")
+    if blob[:8] == b"\x89PNG\r\n\x1a\n":
+        ext = "png"
+    elif blob[:3] == b"\xff\xd8\xff":
+        ext = "jpg"
+    else:
+        raise ValueError("Only PNG or JPEG figures are accepted (magic-byte check failed).")
+    figures = session.data.setdefault("figures", [])
+    figure_id = f"FIG-{len(figures) + 1:02d}"
+    safe = "".join(c if c.isalnum() or c in "-_" else "_" for c in (figure_name or figure_id))
+    fig_dir = session.workdir / "figures"
+    fig_dir.mkdir(exist_ok=True)
+    path = fig_dir / f"{safe}.{ext}"
+    path.write_bytes(blob)
+    figures.append({"figure_id": figure_id, "path": str(path), "caption": caption.strip(),
+                    "section": section.strip().lower() or "results", "source": "client-attached"})
+    return {"figure_id": figure_id, "stored": path.name, "size_bytes": len(blob),
+            "section": section, "attached_figures": [
+                {"figure_id": f["figure_id"], "caption": f["caption"], "section": f["section"]}
+                for f in figures],
+            "next_step": "Call generate_report; the figure will be embedded with a labelled caption."}
+
+
 def generate_report(session_id: str, project_name: str, client: str = "",
                     consultant: str = "", prepared_by: str = "",
                     outline_plan_no: str = "") -> dict:
@@ -372,7 +417,8 @@ def generate_report(session_id: str, project_name: str, client: str = "",
         preliminary_review_artifacts={
             "findings": findings, "status": "Preliminary",
             "manifest": {"rpt_reconciliation": session.data.get("recon_summary", {})},
-        } if findings else None)
+        } if findings else None,
+        attached_figures=session.data.get("figures") or None)
     outputs = session.workdir / "outputs"
     outputs.mkdir(exist_ok=True)
     files = {}
@@ -399,6 +445,6 @@ TOOL_REGISTRY: dict[str, Callable[..., dict]] = {
         get_node_results, get_link_results, get_subcatchment_results,
         get_timeseries, query_results, get_table_catalog,
         calgary_screening, preliminary_design_review, get_reconciliation,
-        run_scenario, generate_report,
+        run_scenario, attach_figure, generate_report,
     ]
 }