From 336644a90a622b8467c35e43c78c9202b41bdcab Mon Sep 17 00:00:00 2001 From: alvis Date: Wed, 6 May 2026 06:28:30 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20update=20CLAUDE.md=20with=20rich=20per-?= =?UTF-8?q?agent=20inference=20completions=20(#112=E2=80=93#116)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Inference framework table updated: all agents at v1.2.0 with full param list - Documents UserHistory.task_completions and AgentInferRequest.task_completions - Marks #112/114/115/116 complete in recent completions - Active work updated: #78 closed, #61 and #97/#113 as next priorities Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b06f380..bec8897 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -107,10 +107,11 @@ Recent completions: - Admin UX refinements: feedback consolidation, settings placement (#100–102) - ADR-0012 — ε-greedy v2 (D=12) — 2026-04-26 (now superseded by ADR-0013) - ADR-0014 complete: unified Profile schema + backfill, manifest plumbing, `/api/profile` read-through, registry-driven eligibility filter, inference framework + per-agent inference, legacy consent column drop — 2026-05-05 +- Rich per-agent inference for all four active agents (#112, #114, #115, #116) — 2026-05-06: quiet/peak hours (time-of-day), z-score baseline (momentum), p50 lateness + project realness (overdue-task), adaptive lookback + weekly/daily cycles (recent-patterns) Active work (M2): -- Signal abstraction for multi-source support (#78) - Per-user feature freshness SLAs (#61, ADR-0011 phase B) +- Embedding-based task clustering for focus-area inference (#97, #113) ## ADR-0014 endpoint map (as of step 6) @@ -131,15 +132,18 @@ Lives in `ml/agents/inference/`. `run_inference(manifest, history)` evaluates al - `infer()` error → emit `cold_start_default` (never crashes) - Results written to `user_preferences` with `source='inferred'`; keys with `source='user'` are never overwritten -All five agents are at v1.1.0. Per-agent inferred params: -| Agent | Inferred param | Logic | -|-------|---------------|-------| -| `time-of-day` | `preferred_hour` | Mode done-hour from feedback history | -| `momentum` | `engagement_trend` | Done-rate last 7d vs prior 7d | -| `overdue-task` | `lateness_tolerance_days` | Snooze rate → 0/1/2 days | -| `recent-patterns` | `window_days` | Event density → 7/14/30 days | +All five agents are at v1.2.0. Per-agent inferred params (all live in `ml/agents/.py`): + +| Agent | Inferred params | Notes | +|-------|----------------|-------| +| `time-of-day` | `preferred_hour`, `quiet_start`, `quiet_end`, `peak_hours`, `tz` | Quiet window = longest below-baseline hour run; peak = top-quartile done hours; tz cold-start only (from auth provider) | +| `momentum` | `engagement_trend`, `baseline_completions_per_day`, `stdev` | Baseline = 28d rolling mean done/day; snippet uses z-score language | +| `overdue-task` | `lateness_tolerance_days`, `project_realness` | Tolerance = p50 lateness from TaskCompletion history; realness = project median vs global median | +| `recent-patterns` | `lookback_days`, `weekly_cycle`, `daily_cycle` | Lookback sized to ≥30 done events; cycles use peak-to-mean ratio; snippet hints when strength > 0.5 | | `focus-area` | *(none yet)* | Needs project-level feedback linkage (#78) | +`UserHistory` carries both `events: list[FeedbackEvent]` and `task_completions: list[TaskCompletion]`. `AgentInferRequest` (ml/serving) accepts `task_completions: list[dict]` alongside `feedback_history`. + ## What NOT to do - Don't copy Todoist's data into our DB. Store the OAuth token + computed features/derivatives we need, fetch raw on demand.