alvis/oO
1
0
Fork 0
Code Issues 34 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(agents): quiet window + peak hours + tz prefs for time-of-day agent (#112)

Browse Source 
Adds four InferredParams (all TTL=24h, min_history=50 except preferred_hour=10):
- quiet_start / quiet_end: longest contiguous below-baseline hour run (HH:MM)
- peak_hours: top-quartile done-event hours, sorted ascending
- tz: cold-start only ("UTC"); populated from auth provider, no inference function

compute() updated:
- in_quiet check (quiet window) takes precedence over peak hours
- in_peak emits "peak productivity hour" language when current hour is in peak_hours
- approaching peak (within 2h) surfaces for orchestrator timing
- tz surfaced in snippet header when not UTC
- snapshot adds peak_hours, in_quiet, in_peak, tz

- Agent bumped to v1.2.0
- 21 new tests: night-owl, early-bird, shift-worker, quiet/peak snippet rendering
- Fixed test_snapshot_keys in test_agents.py to include new snapshot fields

Closes #112

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
alvis
2026-05-06 06:05:51 +00:00
parent bc71dc203d
commit 1d9a395591
4 changed files with 291 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
ml/agents/time_of_day.py
View File

@@ -1,5 +1,6 @@
from __future__ import annotations
import statistics
from collections import Counter
from typing import ClassVar
@@ -9,6 +10,9 @@ from .manifest import AgentManifest, InferredParam
_DOW_NAMES = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
# min_history required before quiet/peak inference is meaningful (issue #112)
_MIN_HISTORY = 50
def _infer_preferred_hour(history: UserHistory) -> int:
"""Mode hour of day across all 'done' feedback events; falls back to 9."""
@@ -18,9 +22,75 @@ def _infer_preferred_hour(history: UserHistory) -> int:
return Counter(done_hours).most_common(1)[0][0]
def _quiet_window_hours(history: UserHistory) -> tuple[int, int]:
"""Return (start_hour, end_hour) of the longest below-baseline quiet window.
Counts all engagement events by hour. Baseline = mean hourly count.
Finds the longest contiguous run of below-baseline hours on the circular
clock; that run defines the quiet window.
"""
by_hour: Counter[int] = Counter(e.hour for e in history.events)
total = sum(by_hour.values())
baseline = total / 24
# Mark each of the 24 hours as below-baseline (True = quiet)
quiet: list[bool] = [by_hour.get(h, 0) < baseline for h in range(24)]
# Find longest contiguous run in circular array
best_start, best_len = 0, 0
run_start, run_len = 0, 0
# Double the sequence to handle wrap-around
for i in range(48):
h = i % 24
if quiet[h]:
if run_len == 0:
run_start = i
run_len += 1
if run_len > best_len:
best_len = run_len
best_start = run_start
else:
run_len = 0
if best_len == 0:
return (22, 7) # fallback
start = best_start % 24
end = (best_start + best_len) % 24
return (start, end)
def _infer_quiet_start(history: UserHistory) -> str:
start, _ = _quiet_window_hours(history)
return f"{start:02d}:00"
def _infer_quiet_end(history: UserHistory) -> str:
_, end = _quiet_window_hours(history)
return f"{end:02d}:00"
def _infer_peak_hours(history: UserHistory) -> list[int]:
"""Top-quartile hours by done-event count.
Computes done_count per hour, then returns hours above the 75th percentile
of non-zero hourly counts, sorted ascending.
"""
done_by_hour: Counter[int] = Counter(
e.hour for e in history.events if e.action == "done"
)
if not done_by_hour:
return [9, 14, 20]
counts = list(done_by_hour.values())
threshold = statistics.quantiles(counts, n=4)[-1] # 75th percentile
return sorted(h for h, c in done_by_hour.items() if c >= threshold)
MANIFEST = AgentManifest(
id="time-of-day",
version="1.1.0", # bumped: inferred_params added (ADR-0014 §3, #112)
version="1.2.0", # #112: quiet_start/end + peak_hours + tz inference
description="Frames the current moment relative to the user's productive peak and quiet hours.",
pref_schema={
"type": "object",
@@ -36,6 +106,23 @@ MANIFEST = AgentManifest(
"pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
"description": "HH:MM end of quiet hours.",
},
"peak_hours": {
"type": "array",
"items": {"type": "integer", "minimum": 0, "maximum": 23},
"default": [9, 14, 20],
"description": "Hours (0–23) with top-quartile completion density.",
},
"tz": {
"type": "string",
"default": "UTC",
"description": "IANA timezone; populated from auth provider, fallback UTC.",
},
"preferred_hour": {
"type": "integer",
"minimum": 0,
"maximum": 23,
"description": "Mode done-hour (legacy; superseded by peak_hours).",
},
},
},
context_schema=["profile.features"],
@@ -45,11 +132,40 @@ MANIFEST = AgentManifest(
inferred_params=[
InferredParam(
key="preferred_hour",
ttl_sec=3_600, # recompute hourly
ttl_sec=3_600,
cold_start_default=None,
min_history=10, # need at least 10 feedback events to be meaningful
min_history=10,
infer=_infer_preferred_hour,
),
InferredParam(
key="quiet_start",
ttl_sec=86_400,
cold_start_default="22:00",
min_history=_MIN_HISTORY,
infer=_infer_quiet_start,
),
InferredParam(
key="quiet_end",
ttl_sec=86_400,
cold_start_default="07:00",
min_history=_MIN_HISTORY,
infer=_infer_quiet_end,
),
InferredParam(
key="peak_hours",
ttl_sec=86_400,
cold_start_default=[9, 14, 20],
min_history=_MIN_HISTORY,
infer=_infer_peak_hours,
),
# tz is populated from the auth provider; no infer function.
InferredParam(
key="tz",
ttl_sec=86_400,
cold_start_default="UTC",
min_history=999_999, # effectively never inferred — always cold_start
infer=None,
),
],
)
@@ -62,18 +178,23 @@ class TimeOfDayAgent(BaseAgent):
def compute(self, inp: AgentInput) -> AgentOutput:
hour = inp.now.hour
dow = inp.now.weekday() # 0=Monday … 6=Sunday
dow = inp.now.weekday()
is_weekend = dow >= 5
# agent_prefs (inferred or user-set) take precedence over ML profile features.
preferred_raw = inp.agent_prefs.get("preferred_hour", inp.profile.get("preferred_hour"))
preferred = int(preferred_raw) if preferred_raw is not None else None
quiet_start: str | None = inp.agent_prefs.get("quiet_start")
quiet_end: str | None = inp.agent_prefs.get("quiet_end")
peak_hours: list[int] = inp.agent_prefs.get("peak_hours", [])
tz: str = inp.agent_prefs.get("tz", "UTC")
in_quiet = self._in_quiet_window(hour, quiet_start, quiet_end)
in_peak = hour in peak_hours
parts = [f"It is {hour:02d}:00 on {_DOW_NAMES[dow]} ({self._label(hour)})."]
if tz != "UTC":
parts[0] = f"It is {hour:02d}:00 ({tz}) on {_DOW_NAMES[dow]} ({self._label(hour)})."
if is_weekend:
parts.append("Weekend context — prefer personal or reflective tips over work tasks.")
@@ -83,8 +204,18 @@ class TimeOfDayAgent(BaseAgent):
f"User is in their quiet window ({quiet_start}–{quiet_end}) — "
"avoid urgent or demanding tips."
)
if preferred is not None:
elif in_peak:
parts.append(
f"Hour {hour:02d}:00 is a peak productivity hour for this user — "
"a high-impact or challenging tip is appropriate."
)
elif peak_hours:
# Report nearest peak so orchestrator can time advice accordingly.
nearest = min(peak_hours, key=lambda p: min(abs(p - hour), 24 - abs(p - hour)))
delta = min(abs(nearest - hour), 24 - abs(nearest - hour))
if delta <= 2:
parts.append(f"Approaching peak productivity window ({nearest:02d}:00).")
elif preferred is not None:
delta = min(abs(hour - preferred), 24 - abs(hour - preferred))
if delta == 0:
parts.append(
@@ -103,6 +234,10 @@ class TimeOfDayAgent(BaseAgent):
"preferred_hour": preferred,
"quiet_start": quiet_start,
"quiet_end": quiet_end,
"peak_hours": peak_hours,
"in_quiet": in_quiet,
"in_peak": in_peak,
"tz": tz,
}
return self._make_output(inp, prompt, snapshot)