Dashboard¶
A single static page that visualises the engine's inner workings. The engine is glass-box,
so the dashboard is mostly a viewer over the existing /api/* endpoints, plus three thin
read endpoints. It is served by the recsys app itself at /dashboard.
It is styled to the MEMORISE docs aesthetic (archival greige and bronze, Montserrat headings,
light/dark). The HTML is vanilla JS with no build step (the same pattern as the survey-viewer):
recsys/static/dashboard.html. The /dashboard route reads the file fresh per request, so
HTML edits need only a browser refresh.
Two scopes¶
The tabs split into Across users (cohort / global state) and Within user (a
single-visitor deep dive, driven by the user_id field), giving full visibility at both
levels. A header tenant field and user_id field scope every tab; PII-guarded tabs
also need X-API-Key.
Across users¶
| Tab | Source | Shows |
|---|---|---|
| Cohort | GET /api/clusters |
cluster cards: size bar (share of visitors), Falk hint, breadth, top tags (k-means or fcm), expandable member-user list (click a user to open it) |
| Content | GET /api/content/stats |
content seen across visitors (views / liked / disliked / like-rate), popular themes, and each cluster's content preferences. See Cohort statistics |
| Policy | GET /api/policy |
bandit prior θ₀ vs learned θ per feature plus the learned shift; mode, α, ridge; and the training-health banner (verdict, update count, per-weight confidence) |
| Traffic | GET /api/metrics, GET /api/served/recent |
counters (ingests, recommends, cold-rate, avg pool, distractor-rate) plus the recent served-impression tail |
Within user¶
| Tab | Source | Shows |
|---|---|---|
| Request | GET /api/recommend |
each rec as a stacked breakdown bar (tag/semantic/recency/aversion/geo), distractor flag, strategy, ranking mode, generators, pool size |
| User model | GET /api/usermodel/explain |
Falk type + Pekarik preference + engagement style, prose summary, interest/aversion bars (with evidence counts), trajectory, soft cluster membership |
| History | GET /api/usermodel/history |
the event timeline plus an engaged-content table (dwell / end-reason / outcome) |
A Personas reference tab documents all visitor types, experience preferences, and engagement styles, with a Methods section explaining the signals. See Explainability for the theory.
Header settings (base URL, X-API-Key, user_id, tenant, theme) persist in localStorage. A
header dot shows connection status.
New endpoints (all thin reads)¶
| Endpoint | Returns | Notes |
|---|---|---|
GET /api/policy |
{mode, feature_order, prior, theta, trained, alpha, ridge, explore, health} |
guarded |
GET /api/metrics |
in-process serving counters (+ derived rates) | not Prometheus; that is the prod upgrade |
GET /api/served/recent?n=50 |
tail of the durable served log | needs EVENT_LOG_DIR; PII-guarded |
Notes¶
- The panel needs nothing new to decide.
diagnostics,breakdown,features,explain, andclusterswere already emitted; this is the viewer, not new instrumentation. /api/metricscounters are in-process (reset on restart). For production observability, add a Prometheus exporter plus Grafana; the in-process counters are for local visibility.- For a guided walk-through validating the whole system from the Inspector, see the end-to-end evaluation plan.