mirror of
https://github.com/hanzoskill/oura-analytics.git
synced 2026-10-30 21:10:57 +00:00
507 lines
17 KiB
Python
507 lines
17 KiB
Python
#!/usr/bin/env python3
|
|
"""
|
|
Morning Briefing Formatter for Oura Analytics
|
|
|
|
Generates concise, actionable daily briefings with:
|
|
- Headline metrics with baseline context
|
|
- Driver analysis (what's causing the scores)
|
|
- Recovery status (GREEN/YELLOW/RED)
|
|
- Decision recommendations
|
|
- Pattern detection (trends, streaks)
|
|
"""
|
|
|
|
import sys
|
|
from pathlib import Path
|
|
from typing import Optional, Dict, Any, List, Tuple
|
|
from datetime import datetime, timedelta
|
|
|
|
# Add scripts dir to path for imports
|
|
sys.path.insert(0, str(Path(__file__).parent))
|
|
|
|
from schema import NightRecord, SleepRecord, ReadinessRecord, ActivityRecord
|
|
|
|
|
|
class Baseline:
|
|
"""Baseline metrics calculated from historical data."""
|
|
|
|
def __init__(self,
|
|
avg_sleep_hours: float = 7.5,
|
|
avg_readiness: float = 75.0,
|
|
avg_hrv: float = 40.0,
|
|
avg_rhr: float = 60.0):
|
|
self.avg_sleep_hours = avg_sleep_hours
|
|
self.avg_readiness = avg_readiness
|
|
self.avg_hrv = avg_hrv
|
|
self.avg_rhr = avg_rhr
|
|
|
|
@classmethod
|
|
def from_history(cls, nights: List[NightRecord]) -> 'Baseline':
|
|
"""Calculate baseline from historical night records with outlier removal."""
|
|
if not nights:
|
|
return cls()
|
|
|
|
# Calculate averages with outlier removal (remove top/bottom 10% if sample is large enough)
|
|
sleep_hours = sorted([n.sleep.total_sleep_hours for n in nights if n.sleep])
|
|
readiness_scores = sorted([n.readiness.score for n in nights if n.readiness])
|
|
hrv_values = sorted([n.sleep.average_hrv_ms for n in nights if n.sleep and n.sleep.average_hrv_ms])
|
|
rhr_values = sorted([n.sleep.lowest_heart_rate_bpm for n in nights if n.sleep and n.sleep.lowest_heart_rate_bpm])
|
|
|
|
def robust_avg(values: List[float], default: float) -> float:
|
|
"""Calculate average with outlier removal (trim 10% from each end if n >= 10)."""
|
|
if not values:
|
|
return default
|
|
if len(values) < 10:
|
|
# Too few samples for outlier removal
|
|
return sum(values) / len(values)
|
|
|
|
# Remove top/bottom 10%
|
|
trim = max(1, int(len(values) * 0.1))
|
|
trimmed = values[trim:-trim]
|
|
return sum(trimmed) / len(trimmed)
|
|
|
|
return cls(
|
|
avg_sleep_hours=robust_avg(sleep_hours, 7.5),
|
|
avg_readiness=robust_avg(readiness_scores, 75.0),
|
|
avg_hrv=robust_avg(hrv_values, 40.0),
|
|
avg_rhr=robust_avg(rhr_values, 60.0)
|
|
)
|
|
|
|
|
|
class BriefingFormatter:
|
|
"""Formats morning briefings with context and recommendations."""
|
|
|
|
def __init__(self, baseline: Optional[Baseline] = None):
|
|
self.baseline = baseline or Baseline()
|
|
|
|
def format(self, night: NightRecord, verbose: bool = False) -> str:
|
|
"""
|
|
Format a morning briefing.
|
|
|
|
Args:
|
|
night: NightRecord for the day
|
|
verbose: Include additional detail
|
|
|
|
Returns:
|
|
Formatted briefing string
|
|
"""
|
|
lines = []
|
|
|
|
# Header
|
|
lines.append(self._header(night.date))
|
|
lines.append("")
|
|
|
|
# Headline metrics
|
|
if night.sleep:
|
|
lines.append(self._sleep_line(night.sleep))
|
|
|
|
if night.readiness:
|
|
lines.append(self._readiness_line(night.readiness))
|
|
if verbose:
|
|
lines.append(self._driver_analysis(night.readiness))
|
|
|
|
lines.append("")
|
|
|
|
# Status and recommendation
|
|
status, recommendation = self._get_status_and_recommendation(night)
|
|
lines.append(f"Recovery Status: {status}")
|
|
lines.append(f"Recommendation: {recommendation}")
|
|
|
|
# Pattern detection
|
|
if verbose:
|
|
pattern = self._detect_pattern(night)
|
|
if pattern:
|
|
lines.append("")
|
|
lines.append(f"Notable: {pattern}")
|
|
|
|
return "\n".join(lines)
|
|
|
|
def _header(self, date: str) -> str:
|
|
"""Format header with date."""
|
|
dt = datetime.strptime(date, "%Y-%m-%d")
|
|
return f"☀️ Morning Briefing ({dt.strftime('%b %d')})"
|
|
|
|
def _sleep_line(self, sleep: SleepRecord) -> str:
|
|
"""Format sleep line with context."""
|
|
hours = sleep.total_sleep_hours
|
|
|
|
# Delta from baseline
|
|
delta_hours = hours - self.baseline.avg_sleep_hours
|
|
delta_min = int(delta_hours * 60)
|
|
|
|
if abs(delta_min) < 15:
|
|
delta_str = "on target"
|
|
indicator = "✓"
|
|
elif delta_min > 0:
|
|
delta_str = f"↑{delta_min}min vs avg"
|
|
indicator = "✓"
|
|
else:
|
|
delta_str = f"↓{abs(delta_min)}min vs avg"
|
|
indicator = "⚠️" if abs(delta_min) > 60 else "○"
|
|
|
|
# Format duration
|
|
h = int(hours)
|
|
m = int((hours - h) * 60)
|
|
|
|
return f"Sleep: {h}h {m}m ({delta_str}) {indicator}"
|
|
|
|
def _readiness_line(self, readiness: ReadinessRecord) -> str:
|
|
"""Format readiness line with context."""
|
|
score = readiness.score
|
|
|
|
# Delta from baseline
|
|
delta = score - self.baseline.avg_readiness
|
|
|
|
if score >= 85:
|
|
indicator = "✓"
|
|
elif score >= 70:
|
|
indicator = "○"
|
|
else:
|
|
indicator = "⚠️"
|
|
|
|
if abs(delta) < 3:
|
|
delta_str = "stable"
|
|
elif delta > 0:
|
|
delta_str = f"↑{int(delta)} vs baseline"
|
|
else:
|
|
delta_str = f"↓{abs(int(delta))} vs baseline"
|
|
|
|
return f"Readiness: {score} ({delta_str}) {indicator}"
|
|
|
|
def _driver_analysis(self, readiness: ReadinessRecord) -> str:
|
|
"""Analyze what's driving readiness score."""
|
|
# Identify low contributors
|
|
contributors = {
|
|
"HRV balance": readiness.hrv_balance,
|
|
"Sleep balance": readiness.sleep_balance,
|
|
"Recovery index": readiness.recovery_index,
|
|
"RHR": readiness.resting_heart_rate,
|
|
"Body temp": readiness.body_temperature,
|
|
"Activity balance": readiness.activity_balance
|
|
}
|
|
|
|
# Filter out None values and sort by score
|
|
valid_contributors = {k: v for k, v in contributors.items() if v is not None}
|
|
sorted_contributors = sorted(valid_contributors.items(), key=lambda x: x[1])
|
|
|
|
# Identify lowest contributors (<70)
|
|
low = [k for k, v in sorted_contributors if v < 70]
|
|
|
|
if low:
|
|
drivers = ", ".join(low[:2]) # Top 2 lowest
|
|
return f"└─ Driven by: {drivers}"
|
|
else:
|
|
return "└─ All contributors balanced"
|
|
|
|
def _get_status_and_recommendation(self, night: NightRecord) -> Tuple[str, str]:
|
|
"""Determine recovery status and recommendation."""
|
|
if not night.readiness:
|
|
return "UNKNOWN", "Insufficient data"
|
|
|
|
score = night.readiness.score
|
|
|
|
if score >= 85:
|
|
status = "🟢 GREEN"
|
|
recommendation = "Optimal day. Ready for intensity."
|
|
elif score >= 70:
|
|
status = "🟡 YELLOW"
|
|
recommendation = "Moderate day. Avoid heavy training."
|
|
else:
|
|
status = "🔴 RED"
|
|
recommendation = "Recovery day. Light activity only."
|
|
|
|
return status, recommendation
|
|
|
|
def _detect_pattern(self, night: NightRecord) -> Optional[str]:
|
|
"""Detect notable patterns (placeholder for trend analysis)."""
|
|
# This would require historical data for real trend detection
|
|
# For now, just highlight extremes
|
|
|
|
if night.sleep and night.sleep.total_sleep_hours >= 8.5:
|
|
return "Excellent sleep duration"
|
|
|
|
if night.readiness and night.readiness.score <= 65:
|
|
return "Low readiness - prioritize recovery"
|
|
|
|
if night.sleep and night.sleep.efficiency_percent >= 90:
|
|
return "High sleep efficiency"
|
|
|
|
return None
|
|
|
|
|
|
def format_brief_briefing(night: NightRecord, baseline: Optional[Baseline] = None) -> str:
|
|
"""
|
|
Format a brief 3-line briefing (for notifications).
|
|
|
|
Args:
|
|
night: NightRecord for the day
|
|
baseline: Optional baseline metrics
|
|
|
|
Returns:
|
|
3-line briefing string
|
|
"""
|
|
formatter = BriefingFormatter(baseline)
|
|
|
|
lines = []
|
|
|
|
if night.sleep:
|
|
hours = night.sleep.total_sleep_hours
|
|
h = int(hours)
|
|
m = int((hours - h) * 60)
|
|
lines.append(f"Sleep: {h}h {m}m")
|
|
|
|
if night.readiness:
|
|
score = night.readiness.score
|
|
if score >= 85:
|
|
status = "Green"
|
|
elif score >= 70:
|
|
status = "Yellow"
|
|
else:
|
|
status = "Red"
|
|
lines.append(f"Readiness: {score} ({status})")
|
|
|
|
_, recommendation = formatter._get_status_and_recommendation(night)
|
|
lines.append(recommendation)
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
def format_json_briefing(night: NightRecord, baseline: Optional[Baseline] = None) -> Dict[str, Any]:
|
|
"""
|
|
Format briefing as JSON for API integration.
|
|
|
|
Args:
|
|
night: NightRecord for the day
|
|
baseline: Optional baseline metrics
|
|
|
|
Returns:
|
|
Dictionary with briefing data
|
|
"""
|
|
formatter = BriefingFormatter(baseline)
|
|
status, recommendation = formatter._get_status_and_recommendation(night)
|
|
|
|
# Extract status code (remove emoji)
|
|
# Status format: "🟢 GREEN" → "GREEN"
|
|
status_code = status.split()[-1] if status else "UNKNOWN"
|
|
|
|
briefing = {
|
|
"date": night.date,
|
|
"sleep": None,
|
|
"readiness": None,
|
|
"status": status_code,
|
|
"recommendation": recommendation
|
|
}
|
|
|
|
if night.sleep:
|
|
briefing["sleep"] = {
|
|
"duration_hours": round(night.sleep.total_sleep_hours, 2),
|
|
"efficiency_percent": night.sleep.efficiency_percent,
|
|
"hrv_ms": night.sleep.average_hrv_ms
|
|
}
|
|
|
|
if night.readiness:
|
|
briefing["readiness"] = {
|
|
"score": night.readiness.score,
|
|
"delta_vs_baseline": round(night.readiness.score - formatter.baseline.avg_readiness, 1) if baseline else None,
|
|
"low_contributors": _get_low_contributors(night.readiness)
|
|
}
|
|
|
|
return briefing
|
|
|
|
|
|
def _get_low_contributors(readiness: ReadinessRecord) -> List[str]:
|
|
"""Get list of low contributors (<70)."""
|
|
contributors = {
|
|
"hrv_balance": readiness.hrv_balance,
|
|
"sleep_balance": readiness.sleep_balance,
|
|
"recovery_index": readiness.recovery_index,
|
|
"resting_heart_rate": readiness.resting_heart_rate,
|
|
"body_temperature": readiness.body_temperature,
|
|
"activity_balance": readiness.activity_balance
|
|
}
|
|
|
|
return [k for k, v in contributors.items() if v is not None and v < 70]
|
|
|
|
|
|
def format_hybrid_briefing(
|
|
night: NightRecord,
|
|
baseline: Optional[Baseline] = None,
|
|
week_data: Optional[Dict[str, Any]] = None
|
|
) -> str:
|
|
"""
|
|
Format a hybrid daily report combining morning briefing with trend snapshot.
|
|
|
|
This combines:
|
|
1) Morning Briefing (top): actionable daily guidance with driver analysis
|
|
2) Trend Snapshot (bottom): 7-day averages + recent sleep/readiness history
|
|
|
|
Args:
|
|
night: NightRecord for the day
|
|
baseline: Optional baseline metrics
|
|
week_data: Optional pre-calculated 7-day statistics
|
|
|
|
Returns:
|
|
Hybrid briefing string (≤12 lines for chat readability)
|
|
"""
|
|
formatter = BriefingFormatter(baseline)
|
|
|
|
lines = []
|
|
|
|
# === SECTION 1: Morning Briefing ===
|
|
lines.append(f"🌅 *Morning Briefing — {_format_date(night.date)}*")
|
|
lines.append("─" * 24)
|
|
|
|
# Sleep line with delta
|
|
if night.sleep:
|
|
hours = night.sleep.total_sleep_hours
|
|
h = int(hours)
|
|
m = int((hours - h) * 60)
|
|
delta_min = int((hours - formatter.baseline.avg_sleep_hours) * 60)
|
|
if abs(delta_min) < 15:
|
|
delta_str = "on target"
|
|
elif delta_min > 0:
|
|
delta_str = f"↑{delta_min}min vs avg"
|
|
else:
|
|
delta_str = f"↓{abs(delta_min)}min vs avg"
|
|
sleep_indicator = "✅" if abs(delta_min) < 60 else "⚠️"
|
|
lines.append(f"💤 *Sleep*: {h}h {m}m ({delta_str}) {sleep_indicator}")
|
|
|
|
# Readiness line with delta
|
|
if night.readiness:
|
|
score = night.readiness.score
|
|
delta = score - formatter.baseline.avg_readiness
|
|
if abs(delta) < 3:
|
|
delta_str = "stable"
|
|
elif delta > 0:
|
|
delta_str = f"↑{int(delta)} vs baseline"
|
|
else:
|
|
delta_str = f"↓{abs(int(delta))} vs baseline"
|
|
ready_indicator = "✅" if score >= 70 else "⚠️"
|
|
lines.append(f"⚡ *Readiness*: {score} ({delta_str}) {ready_indicator}")
|
|
|
|
# Driver analysis (compact)
|
|
drivers = _get_low_contributors(night.readiness)
|
|
if drivers:
|
|
lines.append(f"*Drivers*: {', '.join(drivers[:2])}")
|
|
else:
|
|
lines.append("*Drivers*: All balanced")
|
|
|
|
# Recovery status + recommendation
|
|
status, recommendation = formatter._get_status_and_recommendation(night)
|
|
lines.append(f"*Recovery*: {status}")
|
|
lines.append(f"*Rec*: {recommendation}")
|
|
|
|
# === SECTION 2: Trend Snapshot ===
|
|
if week_data:
|
|
lines.append("")
|
|
lines.append(f"*📊 7-Day Trends*")
|
|
lines.append("─" * 24)
|
|
|
|
# 7-day averages with delta arrows
|
|
avg_sleep = week_data.get("avg_sleep_score")
|
|
avg_readiness = week_data.get("avg_readiness")
|
|
avg_duration = week_data.get("avg_duration")
|
|
avg_efficiency = week_data.get("avg_efficiency")
|
|
avg_hrv = week_data.get("avg_hrv")
|
|
|
|
# Sleep score with trend
|
|
sleep_trend = week_data.get("sleep_trend", 0)
|
|
if avg_sleep:
|
|
trend_arrow = _trend_arrow(sleep_trend)
|
|
lines.append(f"*Sleep Score*: `{avg_sleep:>2}` {trend_arrow}")
|
|
|
|
# Readiness with trend
|
|
readiness_trend = week_data.get("readiness_trend", 0)
|
|
if avg_readiness:
|
|
trend_arrow = _trend_arrow(readiness_trend)
|
|
lines.append(f"*Readiness*: `{avg_readiness:>2}` {trend_arrow}")
|
|
|
|
# Key metrics row
|
|
metrics = []
|
|
if avg_duration:
|
|
metrics.append(f"*{avg_duration}h* sleep")
|
|
if avg_efficiency:
|
|
metrics.append(f"*{avg_efficiency}%* eff")
|
|
if avg_hrv:
|
|
metrics.append(f"*{avg_hrv}ms* HRV")
|
|
if metrics:
|
|
lines.append(f"• {' • '.join(metrics)}")
|
|
|
|
# Last 2 nights
|
|
last_2_days = week_data.get("last_2_days", [])
|
|
if last_2_days and len(last_2_days) >= 2:
|
|
d1 = last_2_days[-2]
|
|
d2 = last_2_days[-1]
|
|
d1_sleep = d1.get("sleep_score", "N/A")
|
|
d1_ready = d1.get("readiness", "N/A")
|
|
d2_sleep = d2.get("sleep_score", "N/A")
|
|
d2_ready = d2.get("readiness", "N/A")
|
|
|
|
d1_date = d1.get("day", "")[-5:] # MM-DD
|
|
d2_date = d2.get("day", "")[-5:]
|
|
lines.append("")
|
|
lines.append(f"*Recent*: {d1_date} → `{d1_sleep}`/`{d1_ready}` • {d2_date} → `{d2_sleep}`/`{d2_ready}`")
|
|
|
|
return "\n".join(lines)
|
|
|
|
|
|
def _format_date(date_str: str) -> str:
|
|
"""Format date string for display."""
|
|
dt = datetime.strptime(date_str, "%Y-%m-%d")
|
|
return dt.strftime("%b %d")
|
|
|
|
|
|
def _trend_arrow(trend: float) -> str:
|
|
"""Get arrow indicator for trend value."""
|
|
if trend > 1:
|
|
return "↑" # Trending up
|
|
elif trend < -1:
|
|
return "↓" # Trending down
|
|
else:
|
|
return "→" # Stable
|
|
|
|
|
|
if __name__ == "__main__":
|
|
import argparse
|
|
from oura_api import OuraClient
|
|
from schema import create_night_record
|
|
|
|
parser = argparse.ArgumentParser(description="Oura Morning Briefing")
|
|
parser.add_argument("--date", help="Date (YYYY-MM-DD, default: yesterday)")
|
|
parser.add_argument("--format", choices=["brief", "hybrid", "json"], default="hybrid")
|
|
parser.add_argument("--token", help="Oura API token")
|
|
args = parser.parse_args()
|
|
|
|
# Default to yesterday
|
|
if args.date:
|
|
target_date = args.date
|
|
else:
|
|
target_date = (datetime.now() - timedelta(days=1)).strftime("%Y-%m-%d")
|
|
|
|
try:
|
|
client = OuraClient(args.token)
|
|
sleep_data = client.get_sleep(target_date, target_date)
|
|
readiness_data = client.get_readiness(target_date, target_date)
|
|
|
|
if not sleep_data:
|
|
print(f"No data for {target_date}")
|
|
sys.exit(1)
|
|
|
|
# Build NightRecord from API response using schema normalizer
|
|
night = create_night_record(
|
|
date=target_date,
|
|
sleep=sleep_data[0] if sleep_data else None,
|
|
readiness=readiness_data[0] if readiness_data else None
|
|
)
|
|
|
|
if args.format == "json":
|
|
import json
|
|
print(json.dumps(format_json_briefing(night), indent=2))
|
|
elif args.format == "brief":
|
|
print(format_brief_briefing(night))
|
|
else:
|
|
print(format_hybrid_briefing(night))
|
|
|
|
except Exception as e:
|
|
print(f"Error: {e}", file=sys.stderr)
|
|
sys.exit(1)
|