feat(profile): KI-063 — shown / selected / rejected policy tracking on profile

Adds per-user, persistent policy interaction tracking so the bot remembers
across sessions which policies were shown to a user, which they shortlisted,
and which they rejected.

Schema (backend/needs_finder.py)
• Profile gains three list fields: shown_policies, selected_policies,
rejected_policies. Each entry: {policy_slug, insurer, event_at (ISO Z),
session_id, reason}.

Storage helpers (backend/profile_store.py)
• record_policy_event(persona_id_or_name, profile, event_type, policy_slug,
insurer, session_id, reason) — appends or dedup-updates on
(policy_slug, event_type); persists via existing save_profile so
persona-id keying stays consistent.
• get_shortlist(profile) — convenience wrapper around selected_policies.

Orchestrator wiring (backend/orchestrator.py)
• After every recommendation / comparison turn that passes faithfulness
and was issued by a named profile, iterate citations and log
event_type='shown' / reason='shown_in_recommendation'. Wrapped in a
try/except so logging never breaks the chat reply. Anonymous sessions
are skipped.
• _format_known_profile_summary now appends "Your shortlist: <insurer ·
slug>, ..." when selected_policies is non-empty, so KI-061's
welcome-back greeting surfaces the user's shortlist.

User-facing endpoints (backend/admin.py)
• POST /api/profile/select — {session_id, policy_slug, insurer, reason?}
• POST /api/profile/reject — {session_id, policy_slug, insurer, reason?}
Both look up the session, require profile.name (400 otherwise), and
delegate to record_policy_event. Returns {ok, event_type, policy_slug,
count}. NOT admin-gated — these are user actions.

Verification
• py_compile clean across all four files.
• Inline round-trip test: record one shown / selected / rejected event,
reload from disk, all three lists populate with correct shape + reason.
• Dedup test: two shown events for the same policy_slug → list length
stays 1, event_at updates to the later timestamp, session_id refreshes.
• Welcome-back summary correctly appends "Your shortlist: ..." line when
selected_policies is non-empty.
• tests/test_routing_regression.py: 15 passed, 13 subtests passed.

Frontend buttons are deferred — endpoints are exposed for when KI-063b lands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/admin.py

@@ -302,6 +302,81 @@ async def admin_profiles(
     }
 
 
+# ---------------------------------------------------------------------------
+# KI-063 (2026-05-15) — user-facing profile-event endpoints.
+#
+# These are NOT admin-gated — they're invoked by the frontend when a logged-
+# in user (one with a stored profile.name) clicks the select/reject buttons
+# on a policy card. Both look up the session, validate that the session has
+# a named profile, then append the event through `profile_store.record_policy_event`.
+#
+# Anonymous sessions (no profile.name) get 400 — there's no key to persist
+# against. The frontend should hide the buttons in that case.
+# ---------------------------------------------------------------------------
+
+
+class _PolicyEventBody(BaseModel):
+    session_id: str
+    policy_slug: str
+    insurer: str
+    reason: Optional[str] = None
+
+
+def _do_record_policy_event(body: _PolicyEventBody, event_type: str) -> dict:
+    """Shared handler for /api/profile/select + /api/profile/reject."""
+    if not body.session_id or not body.policy_slug or not body.insurer:
+        raise HTTPException(
+            status_code=400,
+            detail="session_id, policy_slug, and insurer are required",
+        )
+    from backend.session_state import get_session
+    from backend.profile_store import record_policy_event
+
+    session = get_session(body.session_id)
+    if not session.profile.name:
+        raise HTTPException(
+            status_code=400,
+            detail="No named profile on this session — cannot persist event.",
+        )
+    ok = record_policy_event(
+        persona_id_or_name=session.profile.name,
+        profile=session.profile,
+        event_type=event_type,  # type: ignore[arg-type]
+        policy_slug=body.policy_slug,
+        insurer=body.insurer,
+        session_id=body.session_id,
+        reason=body.reason,
+    )
+    if not ok:
+        raise HTTPException(status_code=500, detail="profile save failed")
+    # Also persist via the session flush so an in-memory consumer (e.g. the
+    # welcome-back greeter) reads the same state without a full disk reload.
+    session._flush()
+    field_name = {
+        "shown": "shown_policies",
+        "selected": "selected_policies",
+        "rejected": "rejected_policies",
+    }[event_type]
+    return {
+        "ok": True,
+        "event_type": event_type,
+        "policy_slug": body.policy_slug,
+        "count": len(getattr(session.profile, field_name, []) or []),
+    }
+
+
+@router.post("/api/profile/select")
+async def profile_select(body: _PolicyEventBody):
+    """Record a user clicking "shortlist / save" on a policy card."""
+    return _do_record_policy_event(body, "selected")
+
+
+@router.post("/api/profile/reject")
+async def profile_reject(body: _PolicyEventBody):
+    """Record a user clicking "not for me / reject" on a policy card."""
+    return _do_record_policy_event(body, "rejected")
+
+
 # ---------------------------------------------------------------------------
 # /api/admin/performance — aggregated performance/quality metrics
 # ---------------------------------------------------------------------------

backend/needs_finder.py

@@ -45,6 +45,15 @@ class Profile:
     health_conditions: Optional[list[str]] = field(default_factory=list)  # ["diabetes", "hypertension", ...]
     asked: list[str] = field(default_factory=list)  # question IDs already asked
     free_form_session: bool = False  # True = user asks free questions, not driven by us
+    # KI-063 (2026-05-15) — per-user policy interaction log so the bot
+    # remembers which policies were shown / selected / rejected across
+    # sessions. Each entry is a dict with shape:
+    #   {policy_slug, insurer, event_at (ISO Z), session_id, reason}
+    # Dedup at write-time on (policy_slug, event_type) — re-events just
+    # bump event_at + session_id rather than appending duplicates.
+    shown_policies: list[dict] = field(default_factory=list)     # KI-063
+    selected_policies: list[dict] = field(default_factory=list)  # KI-063
+    rejected_policies: list[dict] = field(default_factory=list)  # KI-063
 
 
 # ----------------------------------------------------------------------------

backend/orchestrator.py

@@ -284,7 +284,12 @@ _KNOWN_FIELD_FORMATTERS: tuple[tuple[str, str, "callable"], ...] = (
 def _format_known_profile_summary(profile) -> str:
     """Return a comma-separated rundown of what we already know, e.g.
     'age 34, covering you + spouse, income ₹10-25L, looking for first
-    health policy'. Returns '' if nothing meaningful is stored."""
+    health policy'. Returns '' if nothing meaningful is stored.
+
+    KI-063 (2026-05-15) — if the user has selected (shortlisted) policies
+    on file, append a "Your shortlist: <insurer · policy>, ..." line so the
+    returning-visitor greeting surfaces what they previously saved.
+    """
     parts: list[str] = []
     for field_name, label, fmt in _KNOWN_FIELD_FORMATTERS:
         val = getattr(profile, field_name, None)
@@ -296,7 +301,22 @@ def _format_known_profile_summary(profile) -> str:
             rendered = str(val)
         if rendered:
             parts.append(f"{label} {rendered}")
-    return ", ".join(parts)
+    summary = ", ".join(parts)
+    # KI-063 — append shortlist line if any selected policies on file.
+    shortlist = list(getattr(profile, "selected_policies", None) or [])
+    if shortlist:
+        bits = []
+        for entry in shortlist:
+            insurer = (entry.get("insurer") or "").strip()
+            slug = (entry.get("policy_slug") or "").strip()
+            if insurer and slug:
+                bits.append(f"{insurer} · {slug}")
+            elif slug:
+                bits.append(slug)
+        if bits:
+            line = "Your shortlist: " + ", ".join(bits)
+            summary = f"{summary}. {line}" if summary else line
+    return summary
 
 
 _HELPFUL_GAP_LABELS = {
@@ -1100,6 +1120,45 @@ async def handle_turn(
         except Exception:
             pass  # if any step fails, return English — better than mis-translated
 
+    # KI-063 (2026-05-15) — auto-log "shown" policy events on the persisted
+    # profile so a returning visitor's bot remembers which policies they've
+    # seen. Only fires for context-dependent intents (recommendation /
+    # comparison) AND only when faithfulness passed (we don't log cites that
+    # the safety gates rejected). Anonymous users (no profile.name) get no
+    # log — there's no key to persist against.
+    try:
+        if (
+            intent in ("recommendation", "comparison")
+            and verdict.passed
+            and not blocked
+            and session.profile.name
+            and citations
+        ):
+            from backend.profile_store import record_policy_event
+            seen_slugs: set[str] = set()
+            for cite in citations:
+                slug = cite.get("policy_id") or cite.get("policy_slug")
+                insurer = cite.get("insurer_slug") or cite.get("insurer")
+                if not slug or not insurer or slug in seen_slugs:
+                    continue
+                seen_slugs.add(slug)
+                record_policy_event(
+                    persona_id_or_name=session.profile.name,
+                    profile=session.profile,
+                    event_type="shown",
+                    policy_slug=slug,
+                    insurer=insurer,
+                    session_id=session_id,
+                    reason="shown_in_recommendation",
+                )
+    except Exception as e:
+        # Never let logging failures break the chat reply.
+        import logging
+        logging.warning(
+            "KI-063 shown_policies log failed (session=%s): %s: %s",
+            session_id, type(e).__name__, str(e)[:200],
+        )
+
     return TurnResult(
         reply_text=reply,
         citations=citations,

backend/profile_store.py

@@ -32,7 +32,7 @@ import re
 import time
 from dataclasses import asdict
 from pathlib import Path
-from typing import Optional
+from typing import Literal, Optional
 
 from backend.config import settings
 from backend.needs_finder import Profile
@@ -207,6 +207,101 @@ def save_profile(name: str, profile: Profile, *, session_id: Optional[str] = Non
         return False
 
 
+# ---------------------------------------------------------------------------
+# KI-063 (2026-05-15) — per-user policy interaction tracking.
+#
+# Three event types are tracked on the Profile:
+#   shown    — auto-logged by orchestrator when a policy is cited in a
+#              recommendation / comparison turn that passed faithfulness.
+#   selected — user clicked "save / shortlist" on a policy card (frontend
+#              POSTs to /api/profile/select).
+#   rejected — user clicked "not for me" (frontend POSTs to /api/profile/reject).
+#
+# Each entry persists across sessions on the JSON profile, so a returning
+# visitor sees their shortlist and the bot can avoid re-pitching rejected
+# policies.
+# ---------------------------------------------------------------------------
+
+_EVENT_TYPE_TO_FIELD = {
+    "shown": "shown_policies",
+    "selected": "selected_policies",
+    "rejected": "rejected_policies",
+}
+
+
+def record_policy_event(
+    persona_id_or_name: str,
+    profile: Profile,
+    event_type: Literal["shown", "selected", "rejected"],
+    policy_slug: str,
+    insurer: str,
+    session_id: Optional[str] = None,
+    reason: Optional[str] = None,
+) -> bool:
+    """Append a single policy-interaction event to the profile and persist.
+
+    Dedup: if the SAME `policy_slug` already exists in the matching list for
+    this event_type, the existing entry is updated in place (event_at +
+    session_id refreshed) rather than appending a duplicate. This keeps the
+    list bounded and chronologically meaningful — repeated shows of the same
+    policy collapse to the most recent timestamp.
+
+    Returns True on successful save, False on any failure (missing fields,
+    invalid event type, save error).
+    """
+    if event_type not in _EVENT_TYPE_TO_FIELD:
+        return False
+    if not policy_slug or not insurer:
+        return False
+    field_name = _EVENT_TYPE_TO_FIELD[event_type]
+    entries: list[dict] = list(getattr(profile, field_name, None) or [])
+    now_iso = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+    default_reason = {
+        "shown": "shown_in_recommendation",
+        "selected": "user_clicked_select",
+        "rejected": "user_clicked_reject",
+    }[event_type]
+    payload = {
+        "policy_slug": policy_slug,
+        "insurer": insurer,
+        "event_at": now_iso,
+        "session_id": session_id,
+        "reason": reason or default_reason,
+    }
+    # Dedup on policy_slug within this event-type list. Bump timestamp +
+    # session_id; preserve original reason unless caller passed a new one.
+    dedup_idx = next(
+        (i for i, e in enumerate(entries) if e.get("policy_slug") == policy_slug),
+        None,
+    )
+    if dedup_idx is not None:
+        existing = dict(entries[dedup_idx])
+        existing["event_at"] = now_iso
+        if session_id:
+            existing["session_id"] = session_id
+        if reason:
+            existing["reason"] = reason
+        entries[dedup_idx] = existing
+    else:
+        entries.append(payload)
+    setattr(profile, field_name, entries)
+    # Persist through the existing save path so persona-id resolution + Chroma
+    # sync (if any) stay consistent.
+    save_name = profile.name or persona_id_or_name
+    if not save_name:
+        return False
+    return save_profile(save_name, profile, session_id=session_id)
+
+
+def get_shortlist(profile: Profile) -> list[dict]:
+    """Return the user's selected (shortlisted) policies.
+
+    Thin convenience wrapper used by the admin panel + welcome-back greeting
+    so callers don't have to remember the field name.
+    """
+    return list(getattr(profile, "selected_policies", None) or [])
+
+
 def list_profiles() -> list[dict]:
     """Return summary of all stored profiles — used by the admin Profile +
     Visitor Log view. One entry per file."""