Context Recipes (Admin Phase 1)

This document describes the first implemented Context Recipe slice for Insights.

Scope

• Recipes:
  • daily_review
  • weekly_reflection
  • unread_focus
  • urgency_watch
  • momentum_boost
  • recent_activity_digest
• Admin-only surface: /admin/insights
• Global templates only (no per-user overrides yet)
• On-demand bundle generation (not persisted)
• Signals: impression, click, dismiss

Recipe dimensions contract

Each recipe should publish explicit dimensions (intent, scope, inputs, retrieval policy, ranking policy, diversity controls, suppression rules, output contract, confidence/uncertainty handling, feedback hooks, cadence/triggering, guardrails).

Phase 1 implementation:

• GET /admin/insights/templates now includes dimensions_json per template.
• Recipe dimensions are defined in backend code as the source of truth.

Data model

context_recipe_templates

Global recipe template definitions:

• recipe_id (unique), display_name, description
• params_json for tunable scoring/retrieval params
• enabled, timestamps

Seeded templates:

• daily_review
• weekly_reflection
• unread_focus
• urgency_watch
• momentum_boost
• recent_activity_digest

context_recipe_events (append-only)

Interaction events emitted by admin insights UI:

• event_type: impression | click | dismiss
• admin_user_id, target_user_id, recipe_id
• optional thought_id, bundle_item_key, meta_json

No update/delete flow is exposed for this table.

context_recipe_dismissals

Dismissal suppression state for bundle filtering:

• target_user_id, recipe_id, thought_id
• dismissed_at, expires_at, dismissed_by_admin_user_id

Dismissals expire after 24 hours in Phase 1.

Daily Review scoring

Inputs:

• Thoughts in template lookback window
• Active dismissals for (user, daily_review)

Deterministic score:

• recency_score (time-decay in lookback window)
• unread_boost when is_read = false
• optional severity_weight

Final:

• score = recency_score + unread_boost + severity_weight

Each item includes:

• reason_code (stable machine-friendly code)
• reason_text (short human explanation)
• channel (dominant score component)
• score_components (debug breakdown)

Admin endpoints

• GET /admin/insights/users: top users by jobs in the last 24h
• GET /admin/insights/templates: enabled global templates
• GET /admin/insights/bundle: on-demand bundle generation
• POST /admin/insights/generate-thought: generate one synthesized Thought from a bundle (admin-only process surface)
• POST /admin/insights/events: append event; on dismiss also creates/extends 24h dismissal

Deferred items

• Per-user recipe templates/overrides
• User-facing insights pages
• Embeddings retrieval and clustering
• Adaptive recipe selection (bandits)