[Atlas] Personal recommendations from search history + click stream

Goal

search_queries rows capture both the query and the clicked result
(api.py:17395 api_search_click). We never use that data. Build a
per-session recommender: from the last 30 days of queries + clicks,
infer the session's interest vector (entities, genes, layers,
artifact types) and generate "You might want to look at" cards on /dashboard and an "Adjacent artifacts" sidebar on every artifact
page.

Acceptance Criteria

☐ scidex/atlas/recommender.py::interest_vector(session_id, days=30) -> np.ndarray derived from clicked-artifact embeddings (reuse vector_search).

☐ recommend_for_session(session_id, k=10) returns top-k unseen artifacts ranked by cosine similarity to interest vector × (1 - already_seen_decay).

☐ DB tables: search_session_interests(session_id PK, vector_bytes, computed_at); search_recommendations_log(session_id, artifact_id, recommended_at, clicked, dismissed).

☐ Surfaces:

- /dashboard adds a "Recommended for you" card when ≥ 5 clicks in window.
- Every /artifact/{id} page gets an "Adjacent artifacts" sidebar (top 5).

☐ Cold-start: if interest vector is null, fall back to globally trending (most-clicked-in-last-7-days).

☐ Privacy: no cross-session leakage; session_id must match cookie; an X-Search-Recommendations: off header disables tracking entirely.

☐ Test: simulate a session with 5 clicks on TREM2-related artifacts; recommendations include other TREM2 artifacts not yet seen; cold-start returns trending list.

Approach

Use mean of clicked-artifact embeddings as the interest vector; weight by recency.

Already-seen decay: linear drop from 1.0 (just clicked) → 0.0 over 14 days.

Recompute on each click; cache 5 minutes.

Add a "Why this?" link on each card that surfaces the top-3 seed artifacts contributing to similarity.

Dependencies

q-srch-hybrid-rerank (shares the embedding store).
search_queries.user_session, clicked_result_id (existing).

Work Log

Tasks using this spec (1)

[Atlas] Personal recommendations from search history + click

Search done P86

File: q-srch-personal-recommendations_spec.md

Modified: 2026-05-01 20:13

Size: 2.1 KB