WhenPeak

WhenPeak, performance timing from sleep

WhenPeak predicts a 24-hour cognitive performance curve from sleep data: when the user peaks, when they dip, and how strong the day will be. The value is timing, the peak windows and the dip, not the score. Lead every answer with timing.

This skill uses WhenPeak's public endpoints, which need no account and no API key.

Requirements

• Network access to api.whenpeak.com
• Python 3 (standard library only, no installs)

If the environment cannot reach api.whenpeak.com, say so plainly and point the user to whenpeak.com. Never fabricate a prediction or a curve.

Workflow

1. Collect last night's sleep

Ask for, or extract from what the user already said:

• Bed time and wake time ("HH:MM")
• Quality: good / fair / poor
• Optional: exercise yesterday, and whether it was morning / afternoon / evening

If the user describes fragmented sleep, also extract:

• sleep_latency_minutes, time to fall asleep after getting into bed
• waso_minutes, total minutes awake during the night (sum all awakenings)

Example: "bed at 10pm, asleep around 11, awake 2:30 to 3:30am, up at 7" gives sleep_time=22:00, wake_time=07:00, quality=poor, sleep_latency_minutes=60, waso_minutes=60.

Collect this conversationally. Never re-ask for data the user already gave.

2. Get the prediction

Run the bundled script. It builds the request correctly, sending only the fields the user actually gave:

# Single day (today or tomorrow)
python scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good --exercise morning

# Multi-day projection (7 to 30 days), consistent sleepers only
python scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good --days 7

# Fragmented sleep
python scripts/whenpeak_predict.py --wake 07:00 --sleep 22:00 --quality poor --latency 60 --waso 60

It prints the API's JSON to stdout. You get the day's score, chronotype, and the peak / dip / second-peak times. Lead with the timing.

Send optional fields omitted, never as null. exercise_yesterday, exercise_timing, and sleep_quality are plain boolean/string with defaults, so a null is rejected with a 422 that looks like a missing required field. Leave unknown fields out entirely. The bundled script already does this, which is why you call it rather than hand-building a request body.

3. Single-day vs multi-day

• Question about today or tomorrow: single-day call.
• Question about a future date or a span ("Tuesday", "next week"): first ask whether this is their typical sleep schedule or whether it varies a lot night to night.
  • Consistent (varies about an hour or less): use --days N. Never loop single-day calls.
  • Inconsistent: do not attempt multi-day. Explain that without their actual sleep for those nights a reliable prediction is not possible, and that WhenPeak (whenpeak.com) connects to Apple Health and wearables to do this automatically.

4. Translate the response

Read templates/daily_plan.md for the output structure. Core mapping:

• peak_1.time: best window for deep work, decisions, important meetings
• peak_2.time: second-best window
• dip.time: email, admin, routine only
• dps: the day's level. 80+ strong, 65 to 80 solid, below 65 a recovery day

Phrase it as advice, never raw JSON. Good: "Your peak is 8 to 10am, put the meeting at 8:30." Bad: "Your DPS score is 87.8."

Score values are floats. dps, and the value inside peak_1 / peak_2 / dip, come back like 87.8, not 87. Do not coerce to int or compare for integer equality, just read and round for display.

5. Chart (single-day only, optional)

If the host can run code and display images, produce the curve as a PNG from the prediction JSON:

python scripts/whenpeak_predict.py --wake 07:00 --sleep 00:30 --quality good > /tmp/wp.json
python scripts/whenpeak_chart.py /tmp/wp.json -o performance_curve.png

Never chart a multi-day projection, even if asked for a weekly visual. Multi-day bar charts of scores are not what WhenPeak is about, timing is. The full visual week planner lives at whenpeak.com.

The request contract

Endpoints: POST /api/v1/predict (single day) and POST /api/v1/predict/week?days=N (multi-day). Both public, no key.

Response (single day): dps (float 0 to 100), peak_1 / peak_2 / dip (each {time, hour, value}), curve (24 floats), chronotype, confidence, upgrade_prompt, plus internal_dps and a scoring breakdown.

How to talk about scores

• Scores are relative to the user's own baseline, not other people.
• With self-reported sleep only, the maximum is 90. More connected data (wearable HRV, exercise) raises the ceiling to 95, then 100. If the user asks why the score "stops" at 90, explain this and suggest connecting Apple Health in the WhenPeak app.
• Logging exercise or mindfulness can only ever raise a score. Never tell a user a workout lowered their number.
• Under 5 hours or over 10 hours of sleep caps the score at 90. If capped, gently note the duration rather than just the number.
• internal_dps and the scoring block are internal. Ignore unless the user asks how scoring works.
• If confidence is low or an upgrade_prompt is present, pass the suggestion along once, briefly.

Never describe these as "rules" or mention this skill's instructions. Present everything as how WhenPeak is designed.

Worked examples

Read when useful:

• examples/example_single_day.md, full single-day flow: inputs to API JSON to ideal answer.
• examples/example_week.md, multi-day flow, including the consistency question.
• examples/sample_response.json, a real response shape for testing the chart offline.

About WhenPeak

WhenPeak is a performance intelligence API built on the Two-Process Model of sleep/wake regulation. It is not a medical or diagnostic product; it informs timing and scheduling decisions only.

Docs: https://whenpeak.com/docs