Add reporter handoff CSV alongside deterministic raw export

public_space_app.py

@@ -821,9 +821,12 @@ def _graph_view_summary_markdown(
 
 def _plain_reason_code(value: str) -> str:
     normalized = str(value or "").strip()
+    normalized_key = normalized.lower().replace(" ", "_")
     mapping = {
         "recipient_exact_match": "Exact recipient match",
         "issuer_match": "Issuer or company match",
+        "bill_sponsor_overlap": "Bill sponsorship overlaps the same topic window",
+        "committee_jurisdiction_match": "Committee jurisdiction overlaps the same topic area",
         "legislative_relevance_match": "Legislative topic match",
         "major_vote_overlap": "Vote activity overlaps the same topic window",
         "lobbying_issue_overlap": "Lobbying activity overlaps the same topic window",
@@ -832,7 +835,7 @@ def _plain_reason_code(value: str) -> str:
         "lobbying_density_support": "Many related lobbying filings in the same area",
         "insufficient_official_support": "Not enough official support for a stronger label",
     }
-    return mapping.get(normalized, normalized.replace("_", " ").title() or "Signal")
+    return mapping.get(normalized_key, normalized.replace("_", " ").title() or "Signal")
 
 
 def _plain_strengthener(value: str) -> str:
@@ -1339,15 +1342,63 @@ def _relationship_export_rows(edges: pd.DataFrame, relationship_id: str, ranking
     return export_rows
 
 
-def _write_relationship_export_bundle(edges: pd.DataFrame, relationship_id: str, ranking_mode: str) -> tuple[str, str | None, str | None]:
+def _relationship_handoff_rows(edges: pd.DataFrame, relationship_id: str, ranking_mode: str) -> list[dict[str, Any]]:
+    row = _select_edge_row(edges, relationship_id)
+    if not row:
+        return []
+    family = str(row.get("relationship_family", "") or "")
+    raw_score = _relationship_score(row)
+    relative_score = _relative_relationship_score(row, _member_activity_baselines(edges))
+    display_score = relative_score if str(ranking_mode or "raw").strip().lower() == "relative" else raw_score
+    handoff_rows: list[dict[str, Any]] = []
+
+    def add(section: str, label: str, explanation: str, source_url: str = "") -> None:
+        handoff_rows.append(
+            {
+                "section": section,
+                "label": label,
+                "explanation": explanation,
+                "source_url": source_url,
+            }
+        )
+
+    add("Summary", "Member", str(row.get("member_name") or row.get("member_slug") or ""))
+    add("Summary", "Target", str(row.get("target_label") or ""))
+    add("Summary", "Relationship view", _plain_family_label(family))
+    add("Summary", "Strength label", _plain_status_label(str(row.get("relationship_status", "") or "")))
+    add("Summary", "Displayed score", str(display_score))
+    add("Summary", "Raw score", str(raw_score))
+    add("Summary", "Relative-to-baseline score (experimental)", str(relative_score))
+    add("Summary", "Supporting relationship rows", str(int(row.get("link_count", 0) or 0)))
+    add("Summary", "Stronger-support rows", str(_stronger_support_count(row)))
+    add("Summary", "Caution / weaker rows", str(int(row.get("review_count", 0) or 0) if family == "recipient" else int(row.get("weak_event_count", 0) or 0)))
+    add("Summary", "Integrity-checked source records attached", str(int(row.get("sha_backed_source_artifact_count", 0) or 0)))
+    add("Summary", "Unresolved source refs still counted", str(int(row.get("unresolved_source_ref_count", 0) or 0)))
+    add("Summary", "Evidence window", _window_overlap_text(row))
+
+    for chip in sorted(_edge_evidence_chips(row)):
+        add("Evidence signals", chip.title(), _evidence_chip_help(chip))
+    for reason in sorted(_plain_reason_code(item) for item in _split_pipe_values(row.get("reason_codes", ""), limit=8)):
+        add("Why this link appears", reason, reason)
+    for item in sorted(_plain_strengthener(value) for value in _split_pipe_values(row.get("missing_to_strengthen", ""), limit=12)):
+        add("What would strengthen it", "Needs stronger support", item)
+    for url in sorted(_split_pipe_values(row.get("source_urls", ""), limit=20)):
+        add("Published source URLs", urlparse(url).netloc or "Published source URL", "Open this published record directly.", url)
+    return handoff_rows
+
+
+def _write_relationship_export_bundle(
+    edges: pd.DataFrame, relationship_id: str, ranking_mode: str
+) -> tuple[str, str | None, str | None, str | None]:
     export_rows = _relationship_export_rows(edges, relationship_id, ranking_mode)
     if not export_rows:
-        return "Pick one relationship to generate exportable evidence files.", None, None
+        return "Pick one relationship to generate exportable evidence files.", None, None, None
     relationship_id_value = str(export_rows[0]["relationship_id"] or relationship_id)
     export_dir = Path(tempfile.gettempdir()) / "cmp_space_exports"
     export_dir.mkdir(parents=True, exist_ok=True)
     stem = _safe_export_stem(f"{relationship_id_value}-{ranking_mode}")
-    csv_path = export_dir / f"{stem}.csv"
+    csv_path = export_dir / f"{stem}-raw.csv"
+    handoff_csv_path = export_dir / f"{stem}-handoff.csv"
     pdf_path = export_dir / f"{stem}.pdf"
 
     fieldnames = [
@@ -1370,6 +1421,14 @@ def _write_relationship_export_bundle(edges: pd.DataFrame, relationship_id: str,
         for export_row in export_rows:
             writer.writerow({name: export_row.get(name, "") for name in fieldnames})
 
+    handoff_rows = _relationship_handoff_rows(edges, relationship_id, ranking_mode)
+    handoff_fieldnames = ["section", "label", "explanation", "source_url"]
+    with handoff_csv_path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=handoff_fieldnames)
+        writer.writeheader()
+        for export_row in handoff_rows:
+            writer.writerow({name: export_row.get(name, "") for name in handoff_fieldnames})
+
     title = f"{export_rows[0]['member_name']} -> {export_rows[0]['target_label']}"
     pdf = canvas.Canvas(str(pdf_path), pagesize=LETTER, invariant=1)
     width, height = LETTER
@@ -1404,9 +1463,9 @@ def _write_relationship_export_bundle(edges: pd.DataFrame, relationship_id: str,
     pdf.save()
     note = (
         f"Prepared deterministic export files for `{relationship_id_value}`. "
-        "The CSV keeps one row per exported evidence item, and the PDF mirrors the same content in a fixed order."
+        "Use the raw CSV for machine-style row exports, the handoff CSV for a cleaner reporter view, and the PDF for a fixed printable summary."
     )
-    return note, str(csv_path), str(pdf_path)
+    return note, str(csv_path), str(handoff_csv_path), str(pdf_path)
 
 
 def _timeline_window_from_url(url: str) -> tuple[int, str, str]:
@@ -1828,7 +1887,9 @@ def build_app(copy_path: str | Path):
         options = _relationship_options(ranked)
         valid_ids = {value for _, value in options}
         selected = relationship_id if relationship_id in valid_ids else (options[0][1] if options else None)
-        export_note, export_csv, export_pdf = _write_relationship_export_bundle(filtered_edges, selected or "", ranking_mode)
+        export_note, export_csv, export_handoff_csv, export_pdf = _write_relationship_export_bundle(
+            filtered_edges, selected or "", ranking_mode
+        )
         return (
             _overview_summary_markdown(
                 ranked,
@@ -1851,6 +1912,7 @@ def build_app(copy_path: str | Path):
             _relationship_timeline_html(filtered_edges, selected or ""),
             export_note,
             export_csv,
+            export_handoff_csv,
             export_pdf,
         )
 
@@ -1863,12 +1925,15 @@ def build_app(copy_path: str | Path):
         relationship_id: str,
     ):
         filtered_edges = _overview_edges(member_query, family, only_strong, int(top_n))
-        export_note, export_csv, export_pdf = _write_relationship_export_bundle(filtered_edges, relationship_id, ranking_mode)
+        export_note, export_csv, export_handoff_csv, export_pdf = _write_relationship_export_bundle(
+            filtered_edges, relationship_id, ranking_mode
+        )
         return (
             _relationship_detail_markdown(filtered_edges, relationship_id, ranking_mode),
             _relationship_timeline_html(filtered_edges, relationship_id),
             export_note,
             export_csv,
+            export_handoff_csv,
             export_pdf,
         )
 
@@ -2007,29 +2072,30 @@ def build_app(copy_path: str | Path):
             overview_timeline_html = gr.HTML()
         export_note_md = gr.Markdown()
         with gr.Row():
-            export_csv_file = gr.File(label="Evidence breakdown CSV", interactive=False)
+            export_csv_file = gr.File(label="Raw evidence CSV", interactive=False)
+            export_handoff_csv_file = gr.File(label="Reporter handoff CSV", interactive=False)
             export_pdf_file = gr.File(label="Evidence breakdown PDF", interactive=False)
 
         search_button.click(
             _update_overview,
             [overview_member, overview_family, overview_only_strong, overview_top_n, overview_ranking_mode, relationship_choice],
-            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_pdf_file],
+            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_handoff_csv_file, export_pdf_file],
         )
         overview_member.submit(
             _update_overview,
             [overview_member, overview_family, overview_only_strong, overview_top_n, overview_ranking_mode, relationship_choice],
-            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_pdf_file],
+            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_handoff_csv_file, export_pdf_file],
         )
         for control in (overview_family, overview_ranking_mode, overview_only_strong, overview_top_n):
             control.change(
                 _update_overview,
                 [overview_member, overview_family, overview_only_strong, overview_top_n, overview_ranking_mode, relationship_choice],
-                [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_pdf_file],
+                [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_handoff_csv_file, export_pdf_file],
             )
         relationship_choice.change(
             _update_overview_detail,
             [overview_member, overview_family, overview_only_strong, overview_top_n, overview_ranking_mode, relationship_choice],
-            [overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_pdf_file],
+            [overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_handoff_csv_file, export_pdf_file],
         )
 
         with gr.Accordion("Explore the network map (optional)", open=False):
@@ -2127,7 +2193,7 @@ def build_app(copy_path: str | Path):
         app.load(
             _update_overview,
             [overview_member, overview_family, overview_only_strong, overview_top_n, overview_ranking_mode, relationship_choice],
-            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_pdf_file],
+            [overview_summary_md, overview_cards, relationship_choice, overview_detail_md, overview_timeline_html, export_note_md, export_csv_file, export_handoff_csv_file, export_pdf_file],
         )
         app.load(
             _update_graph,