Eve library

OSHUN V1 Personalization and Suppression Contract

Spec

Revision 1

On this page

Status: Active

Date: March 27, 2026

Owners: OSHUN Shell, OSHUN Auth Platform

Related:

  • docs/releases/v1/specs/todos.md
  • docs/releases/v1/specs/search-ranking-strategy.md
  • docs/adr/ADR-0062-oshun-assistant-led-continuity-journey-model.md
  • docs/adr/ADR-0069-oshun-assistant-persona-switching-ui-behavior.md
  • libs/oshun/auth/src/personalization.ts
  • apps/oshun/bff/src/routes/recommendations.ts
  • apps/oshun/bff/src/routes/assistant.ts

1. Purpose#

This document defines the canonical personalization inputs, recommendation ranking inputs, and suppression rules that drive OSHUN shell home ordering, recommendation shaping, and assistant behavior.

The contract exists so onboarding, profile preferences, recommendation ranking, and assistant session creation all use the same user model instead of parallel per-surface heuristics.

2. Canonical Personalization Inputs#

The runtime contract is rooted in OshunPreferences.personalization plus the existing assistant, notification, language, and accessibility settings already stored in shared preferences.

Primary personalization inputs:

  • goals: declared outcomes such as calm baseline, consistent practice, source-backed clarity, deeper study, night-sky ritual, and daily progress
  • preferredDomains: explicit domain affinity ordering captured in onboarding or later profile edits
  • interests: explicit content-mode interests such as steady practice, evidence-backed briefings, primary text study, night-sky context, habit rhythm, and cross-domain synthesis
  • routineTiming: preferred dayparts for recurring engagement
  • currentFocusThemes: short-lived freeform focus tags for future continuity and follow-up ranking
  • notificationTopics: per-topic opt-in state for daily, events, achievements, and research prompts

Supporting personalization inputs reused by ranking and assistant behavior:

  • assistant.defaultPersonaId: preferred guide family
  • language: reading and copy preference
  • accessibility.reducedMotion and accessibility.highContrast: presentation intensity and clarity modifiers
  • accessibility.timezone: local daypart resolution
  • notifications.pushEnabled, notifications.emailDigestEnabled, notifications.quietHoursEnabled: proactive delivery constraints
  • assistant.voiceResponsesEnabled, assistant.avatarPresenceEnabled: allowed delivery modes
  • assistant.memory.scope, assistant.memory.consentGranted, and assistant.memory.categories: durable memory eligibility and lane-level exclusions

3. Recommendation Ranking Inputs#

Recommendation ordering resolves through buildOshunRecommendationRankingProfile(...) and rankOshunPersonalizedDomains(...).

Domain preference order is computed from:

  1. explicit preferred domains
  2. goal-to-domain affinity
  3. interest-to-domain affinity
  4. preferred guide affinity
  5. resolved current daypart
  6. routine timing affinity
  7. canonical tie-break order: tara, arete, veritas, nyx, nisaba

Active ranking inputs:

  • preferred_domain_match with weight 0.30
  • goal_alignment with weight 0.24
  • interest_alignment with weight 0.18
  • routine_timing with weight 0.14
  • guide_affinity with weight 0.08
  • language_alignment with weight 0.03
  • accessibility_emphasis with weight 0.03

The recommendation scorer in apps/oshun/bff/src/recommendations/scoring.ts consumes the resulting preferred domain order as a dedicated preferenceAlignment factor rather than duplicating the upstream weighting logic.

4. Recommendation Suppression Rules#

Recommendation suppression rules control proactive delivery and visual emphasis, not whether a user can manually browse a domain.

Current rule set:

  • quiet_hours: suppress proactive delivery
  • daily_topic_disabled: suppress ritual and daypart prompt families
  • events_topic_disabled: suppress event and schedule prompt families
  • achievements_topic_disabled: suppress streak and progress prompt families
  • research_topic_disabled: suppress study and evidence-follow-up prompt families
  • reduced_motion: prefer low-stimulation recommendation presentation
  • high_contrast: prefer text-first recommendation presentation

5. Assistant Suppression Rules#

Assistant suppression rules limit which delivery lanes and memory lanes may be used when creating and running a session.

Current rule set:

  • voice_output_disabled: enforce text-only responses
  • avatar_presence_disabled: disable avatar-led presentation
  • profile_memory_disabled: exclude durable profile memory when consent or scope does not allow it
  • routines_memory_disabled: exclude routine memory
  • saved_items_memory_disabled: exclude saved-item memory
  • wellbeing_memory_disabled: exclude wellbeing memory
  • study_memory_disabled: exclude study-context memory
  • sensitive_traits_disabled: fallback exclusion for unsupported memory lanes

6. Runtime Consumers#

The contract is wired into the following runtime surfaces:

  • onboarding writes canonical personalization fields into shared preferences
  • profile preference patch routes validate and persist canonical personalization updates
  • home cold-start ordering resolves through the shared domain-ranking helper
  • BFF recommendations build a ranking profile and apply preference-aware domain alignment
  • assistant session creation builds a behavior profile and passes ranking inputs plus suppression rule ids into session context and prompt assembly

7. Verification#

The contract is covered by:

  • auth preference and personalization unit tests
  • BFF recommendation scoring, profile-route, and contract tests
  • assistant engine and system prompt tests
  • web onboarding and cold-start recommendation tests