Phase 6.5 Day 3: Propensity logging (B2)

db.py:
- _MIGRATION_6_5: add propensity REAL + policy_id TEXT columns to interactions
- init_db(): runs the new migration on startup
- log_interaction(): extended with propensity + policy_id params

recommendations.py:
- Tier 1: compute explore_propensity = n_explore / explore_pool_size
MMR-selected (deterministic) get propensity=1.0
Exploration papers get propensity = n_actual_explore / pool_size
- Tiers 2/3/trending: deterministic, all get propensity=1.0
- Rendering loop: embed propensity + policy_id in each paper dict

search.py:
- Add propensity=1.0 + policy_id='search_v1' to all search results

events.py:
- Add propensity + policy_id Form params to both save and not-interested
- Forward to db.log_interaction()

action_buttons.html:
- Add propensity + policy_id to all hx-vals JSON blobs

This enables Phase 7 SNIPS counterfactual evaluation:
SNIPS(pi_B) = sum(r_i * pi_B/pi_A) / sum(pi_B/pi_A)
where pi_A is the stored propensity from the logging policy.

Tests: 203 passed, 0 failures

app/db.py

@@ -104,6 +104,12 @@ _MIGRATION_6_3 = [
     "ALTER TABLE user_clusters ADD COLUMN medoid_embedding_blob BLOB",
 ]
 
+# ── Phase 6.5 B2: Propensity + policy_id for counterfactual evaluation ────────
+_MIGRATION_6_5 = [
+    "ALTER TABLE interactions ADD COLUMN propensity REAL",
+    "ALTER TABLE interactions ADD COLUMN policy_id TEXT",
+]
+
 
 async def init_db() -> None:
     """Create tables if they don't exist. Called once at startup."""
@@ -121,6 +127,12 @@ async def init_db() -> None:
                 await db.execute(stmt)
             except Exception:
                 pass  # Column already exists — safe to ignore
+        # Phase 6.5 B2: add propensity + policy_id for SNIPS evaluation
+        for stmt in _MIGRATION_6_5:
+            try:
+                await db.execute(stmt)
+            except Exception:
+                pass  # Column already exists — safe to ignore
         await db.commit()
 
 
@@ -136,15 +148,19 @@ async def log_interaction(
     ranker_version: str | None = None,
     candidate_source: str | None = None,
     cluster_id: int | None = None,
+    propensity: float | None = None,
+    policy_id: str | None = None,
 ) -> None:
     async with aiosqlite.connect(DB_PATH) as db:
         await db.execute(
             """INSERT INTO interactions
                (user_id, paper_id, event_type, source, position, query_id,
-                ranker_version, candidate_source, cluster_id)
-               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                ranker_version, candidate_source, cluster_id,
+                propensity, policy_id)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
             (user_id, paper_id, event_type, source, position, query_id,
-             ranker_version, candidate_source, cluster_id),
+             ranker_version, candidate_source, cluster_id,
+             propensity, policy_id),
         )
         await db.commit()
 

app/routers/events.py

@@ -27,6 +27,8 @@ async def save_paper(
     ranker_version: str = Form(default=""),
     candidate_source: str = Form(default=""),
     cluster_id: str = Form(default=""),
+    propensity: float = Form(default=0.0),
+    policy_id: str = Form(default=""),
     user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
 ):
     user_id = user_id or str(uuid.uuid4())
@@ -41,6 +43,8 @@ async def save_paper(
         ranker_version=ranker_version or None,
         candidate_source=candidate_source or None,
         cluster_id=int(cluster_id) if cluster_id else None,
+        propensity=propensity if propensity > 0 else None,
+        policy_id=policy_id or None,
     )
 
     us.record_positive(user_id, paper_id)
@@ -66,6 +70,8 @@ async def not_interested(
     ranker_version: str = Form(default=""),
     candidate_source: str = Form(default=""),
     cluster_id: str = Form(default=""),
+    propensity: float = Form(default=0.0),
+    policy_id: str = Form(default=""),
     user_id: str | None = Cookie(default=None, alias=COOKIE_NAME),
 ):
     user_id = user_id or str(uuid.uuid4())
@@ -80,6 +86,8 @@ async def not_interested(
         ranker_version=ranker_version or None,
         candidate_source=candidate_source or None,
         cluster_id=int(cluster_id) if cluster_id else None,
+        propensity=propensity if propensity > 0 else None,
+        policy_id=policy_id or None,
     )
 
     us.record_negative(user_id, paper_id)

app/routers/recommendations.py

@@ -90,6 +90,8 @@ async def get_recommendations(
                     paper["cluster_id"] = ""
                     paper["query_id"] = query_id
                     paper["position"] = idx
+                    paper["propensity"] = 1.0  # deterministic
+                    paper["policy_id"] = _RANKER_VERSION
                     papers.append(paper)
 
                 r = templates.TemplateResponse(
@@ -123,6 +125,8 @@ async def get_recommendations(
                 "candidate_source": "ewma_longterm",
                 "cluster_id": "",
                 "query_id": query_id,
+                "propensity": 1.0,
+                "policy_id": _RANKER_VERSION,
             }
 
     # ── Tier 3: Qdrant Recommend API (≥1 save fallback) ───────────────────
@@ -139,6 +143,8 @@ async def get_recommendations(
                 "candidate_source": "qdrant_recommend",
                 "cluster_id": "",
                 "query_id": query_id,
+                "propensity": 1.0,
+                "policy_id": _RANKER_VERSION,
             }
 
     if not rec_arxiv_ids:
@@ -173,6 +179,9 @@ async def get_recommendations(
             # Phase 6.5 B1: query_id + position for per-feed CTR
             "query_id": tags.get("query_id", query_id),
             "position": idx,
+            # Phase 6.5 B2: propensity + policy_id for counterfactual eval
+            "propensity": tags.get("propensity", 1.0),
+            "policy_id": tags.get("policy_id", _RANKER_VERSION),
         })
 
     resp = templates.TemplateResponse(
@@ -452,8 +461,17 @@ async def _multi_interest_recommend(
         )
         final = final[:limit + 2]
 
-        # Phase 4.5: Build per-paper instrumentation tags
+        # Phase 4.5 + 6.5: Build per-paper instrumentation tags
         exploration_set = set(final) - set(mmr_selected)
+
+        # Phase 6.5 B2: Compute propensity for counterfactual evaluation
+        # MMR-selected papers are deterministic → propensity = 1.0
+        # Exploration papers are randomly sampled → propensity = n_explore / pool_size
+        mmr_set = set(mmr_selected)
+        explore_pool_size = max(1, len(reranked_ids) - len(mmr_set))
+        n_actual_explore = len(exploration_set)
+        explore_propensity = n_actual_explore / explore_pool_size if explore_pool_size > 0 else 0.0
+
         paper_tags: dict[str, dict] = {}
         for aid in final:
             cluster_idx = paper_cluster_map.get(aid)
@@ -470,6 +488,8 @@ async def _multi_interest_recommend(
                 "candidate_source": source,
                 "cluster_id": str(cluster_idx) if cluster_idx is not None and cluster_idx >= 0 else "",
                 "query_id": query_id,
+                "propensity": explore_propensity if aid in exploration_set else 1.0,
+                "policy_id": _RANKER_VERSION,
             }
 
         return final, paper_tags

app/routers/search.py

@@ -79,6 +79,8 @@ async def search(
         p["dismissed"] = p["arxiv_id"] in dismissed_ids
         p["query_id"] = query_id
         p["position"] = idx
+        p["propensity"] = 1.0  # search is deterministic
+        p["policy_id"] = "search_v1"
 
     if request.headers.get("HX-Request"):
         resp = templates.TemplateResponse(

app/templates/partials/action_buttons.html

@@ -3,7 +3,8 @@
   Expects: paper_id (or paper.arxiv_id), saved (bool), dismissed (bool)
   Optional: source ("search" | "recommendation" | "saved"), position (int)
   Phase 4.5: ranker_version, candidate_source, cluster_id (set by recommendations.py)
-  Phase 6.5: query_id (per-request UUID for feed-level CTR)
+  Phase 6.5: query_id (per-request UUID for feed-level CTR),
+             propensity (probability this paper was shown), policy_id
   These are returned directly by the /api/papers/{id}/save endpoint
   so they also work as a standalone partial.
 #}
@@ -15,6 +16,8 @@
 {% set _cluster_id = paper.cluster_id | default("") if paper is defined else "" %}
 {% set _query_id = paper.query_id | default("") if paper is defined else "" %}
 {% set _position = paper.position | default(0) if paper is defined else 0 %}
+{% set _propensity = paper.propensity | default(0) if paper is defined else 0 %}
+{% set _policy_id = paper.policy_id | default("") if paper is defined else "" %}
 
 {% if is_saved %}
   <!-- Already saved — show saved state, allow unsave via not-interested -->
@@ -26,7 +29,7 @@
             hx-post="/api/papers/{{ pid }}/not-interested"
             hx-target="#paper-{{ pid }}"
             hx-swap="outerHTML swap:200ms"
-            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}"}'>
+            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}", "propensity": "{{ _propensity }}", "policy_id": "{{ _policy_id }}"}'>
       Remove
     </button>
   </div>
@@ -37,7 +40,7 @@
             hx-post="/api/papers/{{ pid }}/save"
             hx-target="[id='actions-{{ pid }}']"
             hx-swap="innerHTML"
-            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}"}'>
+            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}", "propensity": "{{ _propensity }}", "policy_id": "{{ _policy_id }}"}'>
       ⭐ Save
     </button>
     <!-- Not interested (removes the whole card) -->
@@ -45,7 +48,7 @@
             hx-post="/api/papers/{{ pid }}/not-interested"
             hx-target="#paper-{{ pid }}"
             hx-swap="outerHTML swap:200ms"
-            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}"}'>
+            hx-vals='{"source": "{{ _source }}", "position": "{{ _position }}", "ranker_version": "{{ _ranker_version }}", "candidate_source": "{{ _candidate_source }}", "cluster_id": "{{ _cluster_id }}", "query_id": "{{ _query_id }}", "propensity": "{{ _propensity }}", "policy_id": "{{ _policy_id }}"}'>
       ✕ Not interested
     </button>
   </div>