Daily Rhythm Runtime

Purpose & Product Value

Families do not want 80 skills shouting independently. They want the household to feel less chaotic tomorrow morning.

The Daily Rhythm Runtime is a day-level compiler and attention allocator inside OiMy's Hermes / Skill Engine. It collects signals from every available source, compiles them into a typed DailyState, detects opportunities worth surfacing, scores and filters nudges through a budget system, and composes concise morning briefs and evening closeouts — all without requiring LLM calls for the core pipeline.

What problem it solves

• Mental-load reduction: Parents, caregivers, and busy adults forget things — permission slips, medication refills, dinner plans. Rhythm catches these gaps.
• Attention allocation: Instead of every skill competing to interrupt, Rhythm ranks, budgets, and suppresses proactive outputs so users see only what matters today.
• Privacy-first family support: Each member gets their own scoped view; elder-care data stays with authorized caregivers; nothing private leaks into the family brief.

Full Stack Position

Key Relationships

daily_state.py — Core Schema & Data Types

Purpose: Defines the central typed state object (DailyState) and all supporting data types — fact types, enums, nudge budget, nudge candidates, brief output structures, and provenance tracking.

~500 LOC · Zero external dependencies beyond stdlib

Key Enums

Key Classes

Design Decisions

• All dataclasses use field(default_factory=...) to avoid mutable default pitfalls
• Every fact type has its own to_dict() method for controlled serialization
• DailyState auto-fills date and generated_at in __post_init__
• Helper properties (has_food_gap, has_urgent_items, total_items) enable cheap rule checks without LLM

signal_collector.py — Signal Collection & Normalization

Purpose: Gathers signals from all available sources (profile, memory, tasks, meals, routines, conversation history), normalizes them into SignalFact objects with provenance, and compiles them into a DailyState.

~500 LOC · Depends on daily_state.py + sqlite3

Key Class: SignalCollector

Key Class: SignalFact

A normalized signal from any source. Contains fact_type, data dict, provenance, and a deterministic fact_id (SHA-256 of content, first 12 chars) for deduplication.

Design Decisions

• _sources_checked is reset at the start of every collect_all call to prevent cross-user contamination
• User ID is sanitized with regex ([a-zA-Z0-9_\-.] only) to prevent SQL injection
• Missing tables are handled gracefully with except sqlite3.OperationalError: pass
• A default "unplanned dinner" signal is injected when no dinner data exists — ensures dinner gap detection always works
• Deduplication uses deterministic fact_id computed from content hash

opportunity_detector.py — Nudge Detection & Scoring

Purpose: Scans a compiled DailyState for nudge-worthy opportunities, scores each candidate using a multi-factor formula, applies suppression and deduplication, and filters through the nudge budget.

~350 LOC · Pure logic, no DB or LLM calls

Key Class: OpportunityDetector

Design Decisions

• All detectors are deterministic — no LLM calls, no randomness
• Each detector sets scoring factors independently, enabling per-category tuning
• Suppression history (dismissed nudges over last 7 days) increases annoyance cost
• Duplicate penalty of 0.3 for previously-sent nudge IDs
• Budget consumption is first-come (highest score first) with category caps

brief_composer.py — Brief & Closeout Composition

Purpose: Generates human-readable morning briefs and evening closeouts from DailyState and optional nudge candidates.

~350 LOC · Pure logic, no DB or LLM calls

Key Class: BriefComposer

Morning Brief Structure

1. Context-aware greeting with item count and day name
2. Prioritized items: events → urgent deadlines → school → elder care → tasks → food gap
3. One actionable nudge (optional, from top-scored candidate)
4. Brief closing (only if urgent items exist)

Evening Closeout Structure

1. Summary of completed items
2. Still-open tasks
3. Chronic open loops (≥2 carry-forwards)
4. Tomorrow prep: events, deadlines, school items due tomorrow

Design Decisions

• "Under 90 seconds to read" target — max 3-5 items default
• Warm but not generic: no "Have a great day!" filler
• Each item includes source attribution for transparency
• Food gaps appear as FYI only if no food nudge already exists (avoids duplication)
• Priority integers allow deterministic sorting: elder care (9) > deadline (8) > school (7) > task (6) > event (5)
• Elder care items get differentiated actions by care_type (medication vs appointment vs general)

rhythm_runtime.py — Main Orchestrator

Purpose: Top-level orchestrator that chains signal collection → state compilation → opportunity detection → brief composition → outcome recording. Provides the entry points called by API endpoints.

~300 LOC

Key Class: RhythmRuntime

Key Class: OutcomeRecorder

Records every brief and nudge delivery to the rhythm_outcomes and rhythm_nudge_log tables for the Reflection QA feedback loop.

Privacy Filtering

After opportunity detection, nudges are filtered by scope:

• individual scope: shows private and shared_family nudges
• family scope: shows shared_family and care_team nudges

Design Decisions

• Input validation: _validate_user_id() rejects empty/invalid user IDs; _validate_scope() enforces allowlist
• Elapsed time is measured and returned in every response for performance monitoring
• Source freshness is returned so callers know which data sources are stale
• All DB errors in OutcomeRecorder are logged but not propagated — brief delivery is more important than recording

DailyState — Top-Level Fields

Computed Properties

Opportunity Detectors

The system runs 7 deterministic detectors. Each produces zero or more NudgeCandidate objects with pre-set scoring factors.

1. Dinner Gap Detector

2. School Deadline Detector

3. Open Loop Detector

4. Elder Care Risk Detector

5. Habit Miss Detector

6. Calendar Conflict Detector

7. Urgent Deadline Detector

POST /rhythm/morning

Generate a morning brief for a user.

Authentication

Bearer token in Authorization header, validated by authenticate_request(). Falls back to user_id in request body.

Request Body

{
  "user_id": "sarah",
  "scope": "individual",  // "individual" | "family" | "care_team"
  "today": "2026-05-29",  // optional, defaults to today
  "member_scope": {         // optional
    "member_id": "sarah",
    "household_id": "hh_sarah",
    "display_name": "Sarah",
    "role": "adult",
    "visible_scope": "private",
    "timezone": "America/New_York",
    "nudge_posture": "normal",
    "suppressed_categories": []
  }
}

Response

{
  "status": "ok",
  "brief_type": "morning",
  "scope": "individual",
  "user_id": "sarah",
  "date": "2026-05-29",
  "message": "Good morning, Sarah — 3 things on your Thursday: ...",
  "brief": { /* BriefOutput.to_dict() */ },
  "daily_state": { /* DailyState.to_dict() */ },
  "nudge_candidates": [ /* NudgeCandidate[].to_dict() */ ],
  "elapsed_ms": 42,
  "source_freshness": [ /* SourceFreshness[] */ ]
}

Example curl

curl -X POST http://localhost:8000/rhythm/morning \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "user_id": "sarah",
    "scope": "family",
    "member_scope": {
      "member_id": "sarah",
      "household_id": "hh_sarah",
      "display_name": "Sarah",
      "nudge_posture": "normal"
    }
  }'

Scenario: Sarah's Morning Brief

Sarah is a working parent with two school-age children. Her son Liam has a nut allergy. She also helps coordinate elder care for her mother ("Amma") who takes blood pressure medication. It's a Thursday morning.

DailyState(
  date="2026-05-29",
  meals=[dinner:unplanned, any:nut_allergy_pref],
  open_loops=[plumber:carry_3],
  tasks=[permission_slip:pending],
  elder_care_items=[amma:general_care],
  routines=[meditation:pending:streak_10],
  has_food_gap=True, has_urgent_items=False,
  nudge_budget=NudgeBudget(max=3, interrupt=1)
)

Good morning, Sarah — clear day ahead, nothing pressing.

Want a quick dinner idea based on what you usually have?

Test Suite: tests/test_rhythm_runtime.py

53 Tests · All Passing

How to Run

cd /home/exedev/oimy-engine
python -m pytest tests/test_rhythm_runtime.py -v

# Or with unittest directly:
python -m unittest tests.test_rhythm_runtime -v

Key Edge Cases Covered

• System works without a user profile (graceful degradation)
• Empty signals produce a valid brief ("clear day ahead")
• Mixed privacy scopes: care_team visibility on elder care items preserved
• Priority score is clamped to 0 (never negative)
• ProviderFact staleness detection works correctly

Not Yet Covered

• SQL injection / malicious input beyond basic validation
• Concurrent access to the DB
• Error handling paths (DB unavailable, malformed rows)
• Calendar OAuth integration (not yet implemented)
• Cross-member coordination scenarios

QA Code Review Results

Automated code review across all 5 modules.

Critical Issues Identified & Resolved

1. ✅ SQL injection risk → Added _sanitize_user_id() with regex validation
2. ✅ Privacy filtering → Added scope-based nudge filtering in runtime
3. ✅ Cross-user state contamination → Reset _sources_checked per call
4. ✅ Input validation → Added _validate_user_id() and _validate_scope()

NudgeBudget Tuning

The nudge budget is controlled by MemberScope.nudge_posture:

Suppressed Categories

Users control what they receive via MemberScope.suppressed_categories:

# User doesn't want food nudges
scope = MemberScope(
    member_id="sarah",
    household_id="hh_sarah",
    suppressed_categories=["food", "habit"]
)

Suppressed categories are completely filtered out — not just scored lower.

Opportunity Scoring Weights

Each detector sets its own scoring factors. To adjust:

Skill Dispatch Mappings

Currently, the Rhythm Runtime surfaces opportunities and composes briefs. Skill dispatch (e.g., invoking Food Intelligence when user accepts a dinner nudge) happens in the Agenda/Hermes layer. To add new mappings:

1. Define the nudge category → skill mapping in the Hermes router
2. When a nudge is accepted, Hermes routes to the appropriate skill archetype
3. The skill handles domain logic; Rhythm records the outcome

Brief Composer Tuning