oura-analytics

Oura Ring 数据集成和分析。从 Oura Cloud API 获取睡眠分数、准备情况、活动、HRV 和趋势。生成自动报告、与生产力的相关性以及针对低恢复日的基于触发器的警报。需要 OURA_API_TOKEN（在 cloud.ouraring.com 获取）。

# Oura Analytics

## Quick Start

```bash
# Set Oura API token
export OURA_API_TOKEN="your_personal_access_token"

# Fetch sleep data (last 7 days)
python {baseDir}/scripts/oura_api.py sleep --days 7

# Get readiness summary
python {baseDir}/scripts/oura_api.py readiness --days 7

# Generate weekly report
python {baseDir}/scripts/oura_api.py report --type weekly
```

## When to Use

Use this skill when:
- Fetching Oura Ring metrics (sleep, readiness, activity, HRV)
- Analyzing recovery trends over time
- Correlating sleep quality with productivity/events
- Setting up automated alerts for low readiness
- Generating daily/weekly/monthly health reports

## Core Workflows

### 1. Data Fetching
```bash
export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")
print(len(sleep_data), len(readiness_data))
PY
```

### 2. Trend Analysis
```bash
export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient, OuraAnalyzer

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")

analyzer = OuraAnalyzer(sleep_data, readiness_data)
avg_sleep = analyzer.average_metric(sleep_data, "score")
avg_readiness = analyzer.average_metric(readiness_data, "score")
trend = analyzer.trend(sleep_data, "average_hrv")
print(avg_sleep, avg_readiness, trend)
PY
```

### 3. Alerts
```bash
python {baseDir}/scripts/alerts.py --days 7 --readiness 60 --efficiency 80
```

## Environment

Required:
- `OURA_API_TOKEN`

Optional (used for alerts/reports/timezone/output):
- `KESSLER_TELEGRAM_BOT_TOKEN` (fallback to `TELEGRAM_BOT_TOKEN`)
- `TELEGRAM_CHAT_ID`
- `USER_TIMEZONE`
- `OURA_OUTPUT_DIR`

## Scripts

- `scripts/oura_api.py` - Oura Cloud API wrapper with OuraAnalyzer and OuraReporter classes
- `scripts/alerts.py` - Threshold-based notifications (CLI: `python {baseDir}/scripts/alerts.py --days 7 --readiness 60`)
- `scripts/weekly_report.py` - Weekly report generator

## References

- `references/api.md` - Oura Cloud API documentation
- `references/metrics.md` - Metric definitions and interpretations

## Automation (Cron Jobs)

Cron jobs are configured in OpenClaw's gateway, not in this repo. Add these to your OpenClaw setup:

### Daily Morning Briefing (8:00 AM)
```bash
openclaw cron add \
  --name "Daily Oura Health Report (Hybrid)" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run the daily Oura health report with hybrid format: Execute bash /path/to/your/scripts/daily-oura-report-hybrid.sh"
```

### Weekly Sleep Report (Sunday 8:00 AM)
```bash
openclaw cron add \
  --name "Weekly Oura Sleep Report" \
  --cron "0 8 * * 0" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run weekly Oura sleep report: bash /path/to/your/oura-weekly-sleep-alert.sh"
```

### Daily Obsidian Note (8:15 AM)
```bash
openclaw cron add \
  --name "Daily Obsidian Note" \
  --cron "15 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --message "Create daily Obsidian note with Oura data. Run: source /path/to/venv/bin/activate && python /path/to/daily-note.py"
```

**Note:** Replace `/path/to/your/` with your actual paths and `<YOUR_TELEGRAM_CHAT_ID>` with your Telegram channel/group ID.

---

## 中文说明

# Oura Analytics

## 快速开始

```bash
# Set Oura API token
export OURA_API_TOKEN="your_personal_access_token"

# Fetch sleep data (last 7 days)
python {baseDir}/scripts/oura_api.py sleep --days 7

# Get readiness summary
python {baseDir}/scripts/oura_api.py readiness --days 7

# Generate weekly report
python {baseDir}/scripts/oura_api.py report --type weekly
```

## 何时使用

在以下情况使用此技能：
- 获取 Oura Ring 指标（睡眠、准备情况、活动、HRV）
- 分析一段时间内的恢复趋势
- 将睡眠质量与生产力/事件相关联
- 为低准备情况设置自动警报
- 生成每日/每周/每月健康报告

## 核心工作流

### 1. 数据获取
```bash
export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")
print(len(sleep_data), len(readiness_data))
PY
```

### 2. 趋势分析
```bash
export PYTHONPATH="{baseDir}/scripts"
python - <<'PY'
from oura_api import OuraClient, OuraAnalyzer

client = OuraClient(token="YOUR_TOKEN")
sleep_data = client.get_sleep(start_date="2026-01-01", end_date="2026-01-16")
readiness_data = client.get_readiness(start_date="2026-01-01", end_date="2026-01-16")

analyzer = OuraAnalyzer(sleep_data, readiness_data)
avg_sleep = analyzer.average_metric(sleep_data, "score")
avg_readiness = analyzer.average_metric(readiness_data, "score")
trend = analyzer.trend(sleep_data, "average_hrv")
print(avg_sleep, avg_readiness, trend)
PY
```

### 3. 警报
```bash
python {baseDir}/scripts/alerts.py --days 7 --readiness 60 --efficiency 80
```

## 环境变量

必需：
- `OURA_API_TOKEN`

可选（用于警报/报告/时区/输出）：
- `KESSLER_TELEGRAM_BOT_TOKEN`（回退到 `TELEGRAM_BOT_TOKEN`）
- `TELEGRAM_CHAT_ID`
- `USER_TIMEZONE`
- `OURA_OUTPUT_DIR`

## 脚本

- `scripts/oura_api.py` - Oura Cloud API 封装，包含 OuraAnalyzer 和 OuraReporter 类
- `scripts/alerts.py` - 基于阈值的通知（CLI：`python {baseDir}/scripts/alerts.py --days 7 --readiness 60`）
- `scripts/weekly_report.py` - 每周报告生成器

## 参考文档

- `references/api.md` - Oura Cloud API 文档
- `references/metrics.md` - 指标定义与解读

## 自动化（Cron 任务）

Cron 任务在 OpenClaw 的网关中配置，而非在本仓库中。请将以下内容添加到你的 OpenClaw 配置中：

### 每日早间简报（上午 8:00）
```bash
openclaw cron add \
  --name "Daily Oura Health Report (Hybrid)" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run the daily Oura health report with hybrid format: Execute bash /path/to/your/scripts/daily-oura-report-hybrid.sh"
```

### 每周睡眠报告（周日上午 8:00）
```bash
openclaw cron add \
  --name "Weekly Oura Sleep Report" \
  --cron "0 8 * * 0" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --deliver \
  --channel telegram \
  --target "<YOUR_TELEGRAM_CHAT_ID>" \
  --message "Run weekly Oura sleep report: bash /path/to/your/oura-weekly-sleep-alert.sh"
```

### 每日 Obsidian 笔记（上午 8:15）
```bash
openclaw cron add \
  --name "Daily Obsidian Note" \
  --cron "15 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --wake next-heartbeat \
  --message "Create daily Obsidian note with Oura data. Run: source /path/to/venv/bin/activate && python /path/to/daily-note.py"
```

**注意：** 将 `/path/to/your/` 替换为你的实际路径，将 `<YOUR_TELEGRAM_CHAT_ID>` 替换为你的 Telegram 频道/群组 ID。