🧘 Despertamantras: AI-Powered Wake-Up Alarms

Despertamantras is an intelligent alarm system that combines Oura Ring sleep monitoring with AI-generated dialogue to create a seamless, near-realtime wake-up experience. It detects your sleep stages and triggers custom, immersive alarms via Home Assistant.

The project has been evolved into a modular FastAPI application, providing an API for mantra management, background monitoring, and interactive documentation.

---

🚀 Key Features

• Oura Ring Integration: Real-time polling of sleep stages (Light, REM, Deep, Awake).
• Dialogue Generation: Transforms Markdown-based documents into audio using TTS.
• FastAPI Core: Modern, high-performance API with auto-generated OpenAPI documentation.
• Home Assistant Synergy: Triggers events and controls media players based on sleep data.
• Hardware Control: Integrated support for Raspberry Pi screen control and Android Oura sync via ADB.
• Modular Design: Extensible architecture with separated concerns (API, Services, Models).

---

🛠 Installation

1. Prerequisites

• Python 3.10+
• A "Powerful Machine" for audio generation (requires heavy TTS dependencies).
• A "Lightweight Host" (e.g., Raspberry Pi) for running the API and monitoring.

2. Setup

Clone the repository:

git clone https://github.com/your-repo/despertamantras.git
cd despertamantras

You can use the provided Makefile for common tasks:

A. Generation Host (Heavy)

If you plan to generate audio files on this machine:

make install-all

B. Monitoring Host (Lightweight)

If you only need the API and Oura monitoring (e.g., on a Raspberry Pi):

make install

C. Development

To install with all development tools (ruff, mypy, xenon):

make install-dev

D. Everything

make install-all

3. Development and Quality

You can run linting and code quality checks using:

make lint   # Runs ruff, mypy, and xenon
make fix    # Automatically fixes ruff issues

Or use the provided setup script:

chmod +x setup_pi.sh
./setup_pi.sh

This script sets up a virtual environment and installs minimal dependencies.

4. Configuration

Create a .env file from the example:

cp .env.example .env

Edit .env and provide your credentials:

• OURA_ACCESS_TOKEN: Your Oura Personal Access Token.
• HA_URL & HA_TOKEN: Home Assistant connection details.
• MANTRA_DIR: Directory where your .md mantras are stored (default: .).
• TRIGGER_MODE: Default action when a mantra is triggered (ha for Home Assistant event or local for local audio playback).
• ANDROID_DEVICE_IP: (Optional) IP of your Android device for ADB sync.
• API_TOKEN: Long-lived token for API authentication (include as X-API-Key header).

---

🖥 Usage

Running the API

Start the FastAPI server:

make run

• API Documentation: Visit http://localhost:8000/docs for the interactive Swagger UI.
• Authentication: All endpoints (except root) require an X-API-Key header with your API_TOKEN.
• Background Monitor: The Oura monitoring service starts automatically with the API.

---

📝 Mantra Configuration

Mantras are defined as Markdown files with YAML frontmatter.

---
class: mantra
trigger-days: [monday, wednesday, friday]
trigger-time:
  - start: "07:00"
    end: "09:00"
trigger-states: [light, rem]
delay: 60m
repeat: false
ensure: true
screen-action: on
android-sync: true
---

**Peter**: Rise and shine!
**Britta**: It's time for your morning practice.

Frontmatter Options:

• trigger-states: List of Oura stages (light, rem, deep, awake).
• ensure: If true, triggers once if the window passed without a state match.
• screen-action: on or off (Raspberry Pi display control).
• android-sync: Forces Oura app refresh on Android via ADB.

---

🏠 Home Assistant Integration

When a mantra is triggered, the system sends a mantra_triggered event to Home Assistant.

Example Automation:

alias: "Trigger Mantra"
trigger:
  - platform: event
    event_type: mantra_triggered
action:
  - service: media_player.play_media
    target:
      entity_id: "media_player.{{trigger.event.data.player}}"
    data:
      media_content_id: "media-source://media_source/{{trigger.event.data.path}}/{{ trigger.event.data.mantra }}.wav"
      media_content_type: "audio/x-wav"

---

📂 Project Structure

• app/api/: API endpoints and route definitions.
• app/core/: Configuration and global settings.
• app/models/: Pydantic schemas for data validation.
• app/services/: Business logic (Oura, HA, TTS, Monitoring).
• app/main.py: FastAPI application entry point and lifespan management.

---

🤝 Contributing

Contributions are welcome! Please ensure you follow the modular structure when adding new services or endpoints.

📄 License

This project is licensed under the MIT License.