""" Analysis service: metric trends + a rule-based recommendation engine. Replicates the original Node AnalysisService logic. Averages are computed over the most recent 14 days of available daily summaries. """ import datetime import hashlib import json import os from services import health from services import ai as ai_svc from services import coach from services import insights from services import jobs from services import scopes from db import query_all, query_one, execute from config import DB_TYPE METRIC_COLUMNS = { "steps": "steps", "heart_rate": "heart_rate", "sleep_duration": "sleep_duration", "sleep_quality": "sleep_quality", "stress": "stress", "calories_burned": "calories_burned", } def get_trends(metric, user_id, start=None, end=None): column = METRIC_COLUMNS.get(metric, "steps") params = [user_id] sql = "WHERE user_id = ?" if start: sql += " AND date >= ?" params.append(start) if end: sql += " AND date <= ?" params.append(end) rows = query_all( f"SELECT date, {column} AS value FROM health_data {sql} " f"AND {column} IS NOT NULL ORDER BY date ASC", params, ) return [{"date": r["date"], "value": r["value"]} for r in rows] def get_recommendations(user_id): recent = health.get_summary(user_id) last14 = recent[-14:] recs = [] if not last14: return [ { "id": "no-data", "category": "数据", "recommendation": "暂无健康数据，请先同步你的 Garmin 设备数据。", "priority": "low", "basedOn": [], } ] avg = lambda key: sum((r.get(key) or 0) for r in last14) / len(last14) avg_steps = avg("steps") sleep_rows = [r["sleep"]["duration"] for r in last14 if r.get("sleep")] avg_sleep = sum(sleep_rows) / len(sleep_rows) if sleep_rows else 0 avg_stress = avg("stress") avg_rhr = avg("heartRate") avg_hrv = avg("heartRateVariability") if avg_steps > 0 and avg_steps < 8000: recs.append({ "id": "steps", "category": "运动", "recommendation": f"近 {len(last14)} 天日均步数约 {round(avg_steps)} 步，低于 8000 步目标，建议每天增加 20 分钟快走。", "priority": "medium", "basedOn": ["steps"], }) if avg_sleep > 0 and avg_sleep < 7: recs.append({ "id": "sleep", "category": "睡眠", "recommendation": f"日均睡眠约 {avg_sleep:.1f} 小时，偏少。建议固定就寝时间，目标 7-8 小时。", "priority": "high", "basedOn": ["sleep_duration"], }) if avg_stress > 0 and avg_stress > 50: recs.append({ "id": "stress", "category": "压力", "recommendation": f"平均压力指数 {round(avg_stress)} 偏高，建议安排放松活动（冥想/散步）。", "priority": "high", "basedOn": ["stress"], }) if avg_rhr > 0 and avg_rhr > 65: recs.append({ "id": "rhr", "category": "心肺", "recommendation": f"静息心率约 {round(avg_rhr)} bpm 偏高，规律有氧运动有助于改善心肺功能。", "priority": "medium", "basedOn": ["heart_rate"], }) if avg_hrv > 0 and avg_hrv < 40: recs.append({ "id": "hrv", "category": "恢复", "recommendation": f"心率变异性（HRV）约 {round(avg_hrv)} ms 偏低，注意恢复与休息，避免过度训练。", "priority": "low", "basedOn": ["heart_rate_variability"], }) if not recs: recs.append({ "id": "good", "category": "状态", "recommendation": "近期各项指标良好，保持当前作息与运动习惯即可。", "priority": "low", "basedOn": [], }) order = {"high": 0, "medium": 1, "low": 2} recs.sort(key=lambda r: order[r["priority"]]) return recs CACHE_TTL_HOURS = int(os.environ.get("AI_CACHE_TTL_HOURS") or 24) def _fingerprint(summary, activities): """Identify the data a cached answer was derived from. Cheap and order-independent: the day count, the newest and oldest dates, and every metric value. Any sync that adds or corrects a value changes the digest, which is what expires the cache. """ parts = [str(len(summary)), str(len(activities))] for row in summary: parts.append( "|".join( str(row.get(k)) for k in ("date", "steps", "heartRate", "heartRateVariability", "stress", "caloriesBurned") ) ) sleep = row.get("sleep") or {} parts.append(f"{sleep.get('duration')}/{sleep.get('quality')}") return hashlib.sha256("\n".join(parts).encode("utf-8")).hexdigest()[:64] def _read_cache(user_id, fingerprint): row = query_one( "SELECT * FROM ai_recommendations WHERE user_id = ?", [user_id] ) if not row or row["fingerprint"] != fingerprint: return None created = row.get("created_at") if created: try: ts = datetime.datetime.fromisoformat(str(created).replace(" ", "T")) age = datetime.datetime.utcnow() - ts if age > datetime.timedelta(hours=CACHE_TTL_HOURS): return None except ValueError: # An unparseable timestamp should not permanently poison the cache. return None try: recs = json.loads(row["payload"]) except (ValueError, TypeError): return None return { "recommendations": recs, "meta": { "source": "ai", "model": row["model"], "upstream": row["upstream"], "days": row["days"], "cached": True, "generatedAt": created, }, } def _write_cache(user_id, fingerprint, recs, meta): cols = ["user_id", "fingerprint", "model", "upstream", "days", "payload", "created_at"] placeholders = ", ".join(["?"] * len(cols)) if DB_TYPE == "mariadb": updates = ", ".join(f"{c}=VALUES({c})" for c in cols if c != "user_id") sql = ( f"INSERT INTO ai_recommendations ({', '.join(cols)}) " f"VALUES ({placeholders}) ON DUPLICATE KEY UPDATE {updates}" ) else: updates = ", ".join(f"{c}=excluded.{c}" for c in cols if c != "user_id") sql = ( f"INSERT INTO ai_recommendations ({', '.join(cols)}) " f"VALUES ({placeholders}) ON CONFLICT(user_id) DO UPDATE SET {updates}" ) execute(sql, [ user_id, fingerprint, meta.get("model"), meta.get("upstream"), meta.get("days"), json.dumps(recs, ensure_ascii=False), datetime.datetime.utcnow().isoformat(timespec="seconds"), ]) def get_ai_recommendations(user_id, model=None, days=None, refresh=False): """LLM recommendations over the user's history, cached. A generation costs minutes against a large reasoning model, so a stored answer is reused until the health data changes (or the TTL lapses). `refresh=True` and an explicit `model` both bypass the cache — asking for a specific model means wanting that model's answer, not a stored one. Falls back to the rule engine when every model fails, so the endpoint always returns something useful; `meta.source` tells the two apart. """ summary = health.get_summary(user_id) if not summary: return { "recommendations": get_recommendations(user_id), "meta": {"model": None, "source": "rules", "reason": "无健康数据"}, } activities = health.get_activities(user_id) fingerprint = _fingerprint(summary, activities) if not refresh and not model: cached = _read_cache(user_id, fingerprint) if cached: return cached budget = days or ai_svc.default_day_budget() try: recs, meta = ai_svc.generate( summary, activities, preferred_model=model, day_budget=budget ) except ai_svc.AIError as e: return { "recommendations": get_recommendations(user_id), "meta": {"model": None, "source": "rules", "reason": str(e)}, } try: _write_cache(user_id, fingerprint, recs, meta) except Exception as e: # noqa: BLE001 - a cache write must never fail the request print(f"[analysis] failed to cache recommendations: {e}") return {"recommendations": recs, "meta": {**meta, "source": "ai", "cached": False}} def clear_ai_cache(user_id): execute("DELETE FROM ai_recommendations WHERE user_id = ?", [user_id]) # --- AI coach: briefing, per-screen insights, attribution, Copilot ---------- # Same caching rationale as the recommendations above, with one addition: no # screen can wait on a generation, so every one of them answers immediately # from the rule engine and queues the model's version, which replaces it on a # later poll. The queue lives in services/jobs.py. def _read_insight(user_id, kind, subject, fingerprint): row = query_one( "SELECT * FROM ai_insights WHERE user_id = ? AND kind = ? AND subject = ?", [user_id, kind, subject], ) if not row or row["fingerprint"] != fingerprint: return None try: payload = json.loads(row["payload"]) except (ValueError, TypeError): return None return payload, { "source": "ai", "model": row["model"], "upstream": row["upstream"], "cached": True, "generatedAt": row.get("created_at"), } def _write_insight(user_id, kind, subject, fingerprint, payload, meta): cols = ["id", "user_id", "kind", "subject", "fingerprint", "model", "upstream", "payload", "created_at"] placeholders = ", ".join(["?"] * len(cols)) updatable = [c for c in cols if c != "id"] if DB_TYPE == "mariadb": updates = ", ".join(f"{c}=VALUES({c})" for c in updatable) sql = (f"INSERT INTO ai_insights ({', '.join(cols)}) " f"VALUES ({placeholders}) ON DUPLICATE KEY UPDATE {updates}") else: updates = ", ".join(f"{c}=excluded.{c}" for c in updatable) sql = (f"INSERT INTO ai_insights ({', '.join(cols)}) " f"VALUES ({placeholders}) ON CONFLICT(id) DO UPDATE SET {updates}") # The id is derived rather than random so a re-generation overwrites the # row it replaces instead of accumulating one per attempt. row_id = hashlib.sha256( f"{user_id}|{kind}|{subject}".encode("utf-8") ).hexdigest()[:64] execute(sql, [ row_id, user_id, kind, subject, fingerprint, meta.get("model"), meta.get("upstream"), json.dumps(payload, ensure_ascii=False), datetime.datetime.utcnow().isoformat(timespec="seconds"), ]) def _context_fingerprint(context): """Digest of everything the prompt will contain. The whole context rather than a chosen subset: an insight is derived from all of it, so any change to any field — a corrected sleep stage, a newly synced activity — should expire the stored answer. """ blob = json.dumps(context, ensure_ascii=False, sort_keys=True) return hashlib.sha256(blob.encode("utf-8")).hexdigest()[:64] def generate_briefing(user_id, context, model=None): """Ask a model for the briefing and store it. Returns (briefing, meta).""" completion, meta = ai_svc.complete(coach.briefing_messages(context), model) briefing = coach.parse_briefing(completion.text) _write_insight( user_id, "briefing", context["snapshotDate"], _context_fingerprint(context), briefing, meta, ) return briefing, meta def get_briefing(user_id, date=None, model=None, refresh=False, wait=False): """The morning briefing for one day. Non-blocking by default: a cached answer is returned if it matches the current data, otherwise the rule-based briefing is returned straight away and a model generation starts in the background. `wait=True` blocks for the model instead — for callers that can afford minutes, such as a manual "regenerate" or a scheduled pre-warm. """ context = insights.build_context(user_id, date) if not context: return { "briefing": None, "context": None, "meta": {"source": "none", "reason": "无健康数据"}, } fingerprint = _context_fingerprint(context) subject = context["snapshotDate"] if not refresh: cached = _read_insight(user_id, "briefing", subject, fingerprint) if cached: briefing, meta = cached return {"briefing": briefing, "context": context, "meta": meta} else: # Drop the stored answer, not just skip it. Without this the poll that # follows a regenerate reads the *old* row, sees `cached: true`, and # stops polling — so the user keeps looking at the text they just # asked to replace until something else expires it. _delete_insight(user_id, "briefing", subject) if wait: try: briefing, meta = generate_briefing(user_id, context, model) return { "briefing": briefing, "context": context, "meta": {**meta, "source": "ai", "cached": False}, } except ai_svc.AIError as e: return { "briefing": coach.rule_briefing(context), "context": context, "meta": {"source": "rules", "reason": str(e)}, } # `pending` in the meta is what tells the client to poll again: the card it # is showing is the placeholder, not the final answer. state = jobs.enqueue(user_id, "briefing", subject, fingerprint, jobs.PRIORITY_INTERACTIVE) return { "briefing": coach.rule_briefing(context), "context": context, "meta": _queued_meta(state, user_id, "briefing", subject), } def get_trend_insight(user_id, metric, start, end, model=None, refresh=False): """Attribution for a user-selected span of one metric (chart brush). Blocking, unlike the briefing: this one is requested by an explicit gesture on a chart, so there is a spinner to attach the wait to and no useful placeholder to show in the meantime. """ window = insights.window_context(user_id, metric, start, end) if not window: return {"insight": None, "window": None, "meta": {"source": "none", "reason": "所选区间没有数据"}} subject = f"{metric}:{start}:{end}" fingerprint = _context_fingerprint(window) if not refresh: cached = _read_insight(user_id, "trend", subject, fingerprint) if cached: insight, meta = cached return {"insight": insight, "window": window, "meta": meta} try: completion, meta = ai_svc.complete(coach.trend_messages(window), model) insight = coach.parse_trend_insight(completion.text) except ai_svc.AIError as e: return { "insight": coach.rule_trend_insight(window), "window": window, "meta": {"source": "rules", "reason": str(e)}, } try: _write_insight(user_id, "trend", subject, fingerprint, insight, meta) except Exception as e: # noqa: BLE001 - a cache write must never fail the request print(f"[analysis] failed to cache trend insight: {e}") return {"insight": insight, "window": window, "meta": {**meta, "source": "ai", "cached": False}} def copilot_stream(user_id, question, history=None, date=None, model=None): """Stream a Copilot answer, yielding (event, data) pairs. A generator rather than a return value so the route can forward each delta as it arrives; the health context is assembled once, here, so the route stays free of feature logic. """ context = insights.build_context(user_id, date) if not context: yield "error", {"message": "暂无健康数据，请先同步 Garmin 数据。"} return messages = coach.copilot_messages(context, history or [], question) yield "start", {"snapshotDate": context["snapshotDate"]} upstream = None try: for delta in ai_svc.stream_chat(messages, model): upstream = delta.upstream or upstream yield "delta", {"text": delta.text} except ai_svc.AIError as e: yield "error", {"message": str(e)} return yield "done", {"upstream": upstream} def _delete_insight(user_id, kind, subject): execute( "DELETE FROM ai_insights WHERE user_id = ? AND kind = ? AND subject = ?", [user_id, kind, subject], ) def generate_scope_insight(user_id, scope, subject=None): """Generate and store one screen's insight. Raises on failure.""" built = scopes.build(user_id, scope, subject) if not built: return None resolved, context = built completion, meta = ai_svc.complete(coach.scope_messages(context)) insight = coach.parse_scope_insight(completion.text) _write_insight(user_id, scope, resolved, _context_fingerprint(context), insight, meta) return insight, meta def get_scope_insight(user_id, scope, subject=None, refresh=False): """One screen's AI insight, answered immediately. Returns the stored model answer when it matches the current data. Otherwise the computed highlights are returned right away and the generation is queued **at interactive priority** — so opening a screen puts it ahead of whatever backfill is still working through. """ if scope not in scopes.SCOPES: raise KeyError(scope) built = scopes.build(user_id, scope, subject) if not built: return {"insight": None, "context": None, "meta": {"source": "none", "reason": "这个页面还没有可分析的数据"}} resolved, context = built fingerprint = _context_fingerprint(context) if refresh: _delete_insight(user_id, scope, resolved) else: cached = _read_insight(user_id, scope, resolved, fingerprint) if cached: insight, meta = cached return {"insight": insight, "context": context, "meta": meta} state = jobs.enqueue(user_id, scope, resolved, fingerprint, jobs.PRIORITY_INTERACTIVE) return { "insight": coach.rule_scope_insight(context), "context": context, "meta": _queued_meta(state, user_id, scope, resolved), } def _queued_meta(state, user_id, kind, subject, **extra): """Meta for an answer that is standing in for a queued generation. `pending` drives the client's poll loop, so it must be False once the queue has given up — otherwise the screen keeps polling for minutes for an answer that is not coming, and shows a spinner the whole time. """ meta = {"source": "rules", "pending": state in ("pending", "running"), "queue": state, "subject": subject, **extra} if state == "failed": info = jobs.status_of(user_id, kind, subject) or {} meta["reason"] = info.get("error") or "生成失败，稍后会自动重试" return meta def prefetch_insights(user_id): """Queue every screen's insight at background priority. Called after a sync: the data has changed, so every stored answer is stale. These run for as long as they run — anything the user actually opens jumps the queue ahead of them. """ queued = [] for scope in scopes.PREFETCH_SCOPES: try: built = scopes.build(user_id, scope) except Exception as e: # noqa: BLE001 - one screen must not stop the rest print(f"[analysis] prefetch {scope} failed to build: {e}") continue if not built: continue resolved, context = built jobs.enqueue(user_id, scope, resolved, _context_fingerprint(context), jobs.PRIORITY_PREFETCH) queued.append(scope) context = insights.build_context(user_id) if context: jobs.enqueue(user_id, "briefing", context["snapshotDate"], _context_fingerprint(context), jobs.PRIORITY_PREFETCH) queued.append("briefing") return queued def _run_job(user_id, kind, subject): """What the queue worker calls. Dispatches on the job's kind.""" if kind == "briefing": context = insights.build_context(user_id, subject) if not context: return generate_briefing(user_id, context) return generate_scope_insight(user_id, kind, subject) jobs.set_runner(_run_job) def clear_insight_cache(user_id, kind=None): if kind: execute( "DELETE FROM ai_insights WHERE user_id = ? AND kind = ?", [user_id, kind] ) else: execute("DELETE FROM ai_insights WHERE user_id = ?", [user_id])