[KM-680] feat(report): show author display name (users.fullname)

The report header showed the raw user_id under 'generated by'. Resolve a real display name instead:

- AnalysisReport gains user_name; generator renders 'by {user_name or user_id}'.
- api/v1/report.py::_resolve_user_name reads users.fullname via AsyncSessionLocal, never-throw (missing user / read error -> None -> falls back to user_id so a report never fails on the name lookup).
- Decision: resolve in Python (self-contained, unblocked); swap to a Go-passed display name later if preferred.
- DEV_PLAN: #19 marked done; §6 decision resolved.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

DEV_PLAN.md

@@ -86,7 +86,7 @@ Status legend: ⬜ not started · 🔄 in progress · ✅ done · ⛔ blocked ·
 | 2 | Drop `problem_validated`: gate neutered; `is_report_ready`/`report_floor` → **≥1 completed analysis** only, no-LLM | Rifqi | ✅ | Done 2026-06-25. `gate.py` no-op, gate call site commented in `chat_handler.py`, `report_floor` drops the goal check. Tests updated (`test_gate`/`test_chat_handler`/`test_readiness`). Suite: **284 passed, 7 skipped**; ruff clean |
 | 3 | dedorch `analysis` migration: drop `problem_statement`/`problem_validated`, add `objective` + `business_questions`, rename `owner_id`→`user_id` | Harry | ⬜ | Blocks #4 |
 | 4 | Update Python `analysis` model + `state_store` + `analysis.py` to match #3; `owner_id`→`user_id` | Rifqi/Sofhia | ⛔ after #3 | getattr-tolerant so deploy order isn't a hard blocker |
-| 5 | Report generator → `objective`+`business_questions`, "generated by {user}", formal outline | Sofhia | 🔄 pushed (KM-674) | Goal-shape done. Open: author name source (#19); background/EDA/insights mapping |
+| 5 | Report generator → `objective`+`business_questions`, "generated by {user}", formal outline | Sofhia | 🔄 pushed (KM-674) | Goal-shape done; author name done (#19). Open: background/EDA/insights mapping |
 | 6 | Report skill input contract: `analysis_id` + `user_id` (+ `chat_history`?) | Sofhia/Rifqi | ⬜ | Records-based ⇒ chat_history unused — see #17 |
 | 7 | `report_id` state update via request to Go, not direct DB | Sofhia + Harry | ⬜ | Needs Go endpoint. See #18 for the rest of the writes |
 | 8 | Expose/confirm 4 FE endpoints; comment `check_data` + analysis CRUD | Sofhia | ✅ | KM-678: `list_tools` trimmed to `/help` + `/report` (analytics/check/retrieve commented in the **menu**). `help` confirmed as a `call_agent` intent — no own endpoint. Analysis CRUD endpoint left **registered**: "comment the rest" was about the FE slash menu, not killing HTTP routes Go needs |
@@ -100,7 +100,7 @@ Status legend: ⬜ not started · 🔄 in progress · ✅ done · ⛔ blocked ·
 | 16 | Decide `analysis_records` creation under `SKIP_INIT_DB`: dedorch migration (Harry) or Python carve-out | Rifqi + Harry | ⬜ new | Table won't exist post-cutover otherwise |
 | 17 | Reconcile report contract with records-based: remove/flag `chat_history` | Sofhia/Rifqi | ⬜ new | Resolves #5 ↔ #6 contradiction |
 | 18 | Confirm Go owns ALL analysis-state writes + both creation gates; make Python `state_store.ensure` read-only | Rifqi + Harry | ⬜ new | Extends #7 to the full decision #4 (G5) |
-| 19 | Decide report author display-name source (`users.fullname` vs Go-passed name) | Sofhia | ⬜ new | Raw `user_id` in a formal report looks unprofessional |
+| 19 | Decide report author display-name source (`users.fullname` vs Go-passed name) | Sofhia | ✅ | Done 2026-06-25. `AnalysisReport.user_name`; `generator` renders `user_name or user_id`; `api/v1/report.py::_resolve_user_name` reads `users.fullname` never-throw (fallback `user_id`). Decided: resolve in Python (unblocked); swap to Go-passed name later if preferred |
 | 20 | **Help handoff:** update `handlers/help.py` + `help.md` — drop the `problem_validated` tier + `define_problem_statement` action (the skill it points at is gone as of #1) | Sofhia | ✅ | Done 2026-06-25. `help.py`: actions = `ask_analysis_question` (always) + `generate_report` (if ready); renders objective/business_questions (getattr-tolerant). `help.md` v1→v2: 3 tiers, no `/problem_statement`, `/generate report`→`/report`. Local test_help updated → 11 pass |
 
 ## 5. Critical path & sequencing
@@ -115,6 +115,6 @@ Status legend: ⬜ not started · 🔄 in progress · ✅ done · ⛔ blocked ·
 
 - `analysis_records`: dedorch-owned vs Python-owned-with-carve-out (#16/#14).
 - ~~Whether `help` is its own endpoint or via `call_agent` (#8).~~ RESOLVED: `help` is a `call_agent` intent (no own endpoint).
-- Author display-name source for the report (#19).
+- ~~Author display-name source for the report (#19).~~ RESOLVED: Python resolves `users.fullname` (fallback `user_id`); swap to a Go-passed name later if preferred.
 - Confirm Go takes over analysis creation + both creation gates (data-first + mandatory fields) (#18).
 - Keep vs drop `chat_history` in the report contract (#17).

src/agents/report/generator.py

@@ -187,8 +187,9 @@ def _render_markdown(report: AnalysisReport) -> str:
     # after rendering and lives in the structured `version` field / API metadata.
     parts: list[str] = ["# Analysis Report"]
     meta = f"*Generated {report.generated_at:%Y-%m-%d}"
-    if report.user_id:
-        meta += f" by {report.user_id}"
+    author = report.user_name or report.user_id
+    if author:
+        meta += f" by {author}"
     meta += f" · {len(report.record_ids)} analyses · {len(report.data_sources)} source(s)*"
     parts.append(meta)
 
@@ -294,6 +295,7 @@ class ReportGenerator:
         analysis_id: str,
         user_id: str | None = None,
         problem_statement: ProblemStatement | None = None,
+        user_name: str | None = None,
     ) -> AnalysisReport:
         records = await self._ensure_record_store().list_for_analysis(analysis_id)
         if not records:
@@ -313,6 +315,7 @@ class ReportGenerator:
         report = AnalysisReport(
             analysis_id=analysis_id,
             user_id=user_id,
+            user_name=user_name,
             version=0,  # assigned by ReportStore.save under the advisory lock
             generated_at=datetime.now(UTC),
             problem_statement=ps,

src/agents/report/schemas.py

@@ -76,6 +76,7 @@ class AnalysisReport(BaseModel):
     report_id: str = Field(default_factory=lambda: uuid4().hex)
     analysis_id: str
     user_id: str | None = None
+    user_name: str | None = None  # display name for "generated by"; falls back to user_id
     version: int
     generated_at: datetime
     # Frozen snapshots.

src/api/v1/report.py

@@ -59,6 +59,25 @@ def _problem_statement_from(state) -> ProblemStatement:
     return ProblemStatement(objective=objective, business_questions=business_questions)
 
 
+async def _resolve_user_name(user_id: str) -> str | None:
+    """Best-effort display name (`users.fullname`) for the report's "generated by".
+
+    Never-throw: a missing user or read error falls back to None, so the generator
+    shows the raw `user_id`. Resolving it here keeps the report self-contained (#19);
+    swap to a Go-passed display name later if the team prefers.
+    """
+    try:
+        from src.db.postgres.connection import AsyncSessionLocal
+        from src.db.postgres.models import User
+
+        async with AsyncSessionLocal() as session:
+            user = await session.get(User, user_id)
+            return user.fullname if user is not None else None
+    except Exception as e:  # noqa: BLE001 — never block a report on the name lookup
+        logger.warning("report: user name resolve failed", user_id=user_id, error=str(e))
+        return None
+
+
 async def _record_report_on_state(analysis_id: str, report_id: str) -> None:
     """Write the new `report_id` back onto the Analysis State (never-throw).
 
@@ -117,8 +136,9 @@ async def generate_report(
 
     try:
         problem_statement = _problem_statement_from(state)
+        user_name = await _resolve_user_name(user_id)
         report = await _generator.generate(
-            analysis_id, user_id, problem_statement=problem_statement
+            analysis_id, user_id, problem_statement=problem_statement, user_name=user_name
         )
     except ReportError as e:
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=str(e)) from e