Documentation & Home Assistant Recipes for Daily/Weekly AI Digests

[allenporter]

Summary & Proposal

Instead of re-implementing an SMTP email client inside the Supernote server, leverage Home Assistant for managing daily/weekly AI digests and notification dispatches.

Proposed Solution: Home Assistant Integration Guide & Recipes

Document how to connect Supernote Private Cloud to Home Assistant using custom components and provide ready-to-use YAML automation recipes.

1. Integration & Custom Component

• Link to the Home Assistant Supernote custom component.
• Expose Supernote tasks, sync events, and note summaries into Home Assistant sensors.

2. Ready-to-Use Home Assistant Recipes

• 7:00 AM Morning Briefing Recipe:
  • YAML automation that queries yesterday's notes and open tasks, rendering a digest notification sent to your phone/email via Home Assistant.
• Sunday Weekly Retrospective Recipe:
  • Weekly automation that synthesizes 7 days of daily journals into a summary report.
• Sync Complete Notification Recipe:
  • Trigger Home Assistant notifications or scenes when notebooks finish syncing.

[allenporter]

Detailed Technical Implementation Plan

1. User Journeys & Example Use Cases

• Journey A: 7:00 AM Morning Briefing Email

  • Scenario: User wants an automated morning summary of notes and tasks recorded yesterday.
  • Workflow:
    1. At 7:00 AM, the server background scheduler triggers DigestService.
    2. The service gathers all notes synced in the last 24 hours, queries extracted tasks, and calls Gemini LLM for daily synthesis.
    3. User receives a formatted HTML email in their inbox containing:
       • Yesterday's Recap: Main themes and key ideas.
       • Pending Tasks: Uncompleted action items.
       • Handwriting Highlights: High-level bullet points from meetings.

• Journey B: Sunday Evening Weekly Retrospective

  • Scenario: User reviews their entire week of notes on Sunday evening.
  • Workflow: Gemini LLM synthesizes 7 days of notebook summaries into a weekly progress report.

---

2. Requirements & Technical Specifications

A. Configuration (config.yaml)

digest:
  enabled: true
  smtp:
    host: "smtp.example.com"
    port: 587
    username: "user@example.com"
    password: "app-password"
    from_email: "supernote@homelab.local"
    to_email: "me@example.com"
  daily:
    enabled: true
    time: "07:00"
  weekly:
    enabled: true
    day: "Sunday"
    time: "18:00"

B. Digest Engine (supernote/server/services/digest.py)

• Gather summaries from SummaryDO and tasks from ScheduleTaskDO for the time window.
• Format prompt for Gemini synthesis (GeminiService).
• Render responsive HTML email template using Python email.message.EmailMessage with HTML/plaintext fallback.
• Dispatch via aiosmtplib or standard asyncio SMTP executor.

---

3. Verification & Testing Plan

• Automated Unit Tests (tests/server/test_digest.py):
  • Test time-window query calculations for daily/weekly boundaries.
  • Test HTML email template rendering.
  • Test SMTP message construction and dispatch mocking SMTP server.

[allenporter]

🏠 Home Assistant Recipe & Documentation Plan

By integrating with Home Assistant, we keep the supernote server focused on core sync, storage, and API services while leveraging Home Assistant's robust notification engine (mobile app pushes, email, Telegram, smart home triggers).

Documentation Structure (docs/home_assistant.md):

1. Prerequisites & Setup:
   • Connecting Supernote server to Home Assistant via custom component or REST/webhooks.
2. Example Automation Recipes:
   • recipes/morning_digest.yaml: Trigger at 07:00 AM, query Supernote summary/task sensors, send mobile/email digest.
   • recipes/weekly_retro.yaml: Trigger Sunday at 18:00 PM, generate 7-day progress rollup.
   • recipes/sync_notification.yaml: Trigger on note.sync_completed event.