Simulation Engine¶
The simulation engine is a pure Kotlin, offline, rule-based scoring system. It is fully deterministic, requires no internet connection, and produces results in milliseconds.
Philosophy¶
The goal is not clinical precision — it is emotionally tangible feedback. The engine produces scores that feel directionally correct and are easy to explain to a user ("your sleep being low is dragging your recovery score down").
Input¶
SimulationInput is a flat data class assembled by SimulationRepository:
| Field | Type | Source |
|---|---|---|
sleepHoursAvg7d |
Float |
7-day average sleep (wearable or manual fallback) |
stepsAvg7d |
Int |
7-day average steps (wearable or manual fallback) |
restingHeartRateAvg3d |
Int? |
3-day average resting HR (wearable only, nullable) |
stressAvg7d |
Int? |
7-day average stress 1–10 (wearable proxy or manual) |
sleepTrendHours |
Float |
Δ sleep hours: last 3 days vs. prior 4 days |
stepsTrendDelta |
Int |
Δ steps: last 3 days vs. prior 4 days |
wearableCoverageDays |
Int |
Days in the last 7 with wearable data |
ageYears |
Int? |
From UserProfile |
smokingStatus |
SmokingStatus? |
From UserProfile |
alcoholDrinksPerWeek |
Int? |
From UserProfile |
dietQuality |
DietQuality? |
From UserProfile |
basedOnManualFallbacks |
Boolean |
True if any input used a manual baseline |
Scores¶
Five scores on a 0–100 scale (clamped):
Recovery¶
How well is the body recovering?
Base: 55
| Factor | Contribution |
|---|---|
| Sleep < 5h | −28 |
| Sleep 5–6h | −18 |
| Sleep 6–7h | −8 |
| Sleep 7–8.5h | +16 |
| Sleep > 8.5h | +10 |
| Stress ≥ 9 | −22 |
| Stress ≤ 3 | +10 |
| HR ≥ 85 bpm | −12 |
| HR ≤ 60 bpm | +6 |
| Sleep trending up ≥ 0.6h | +8 |
| Sleep trending down ≤ −0.6h | −8 |
| Regular smoking | −8 |
Energy¶
Projected energy level for upcoming days.
Base: 50
Contributions from sleep (±24), steps (±18), stress (±18), and step trend (±8).
Focus¶
Cognitive sharpness and mental clarity.
Base: 52
Contributions from sleep (±18), stress (±20), HR (±8), and diet quality (±8).
Strain¶
Accumulated physical and psychological load.
Base: 40
Stress and HR add strain; good sleep and high steps reduce it.
Long-Term Risk¶
Directional signal for longer-term wellbeing.
Base: 35
Aggregates sleep deprivation, low activity, high stress, elevated HR, age, smoking, alcohol, and poor diet — offset by positive trends.
Confidence¶
SimulationConfidence is derived from wearable coverage:
| Score | Confidence |
|---|---|
| ≥ 55 | HIGH |
| 25–54 | MEDIUM |
| < 25 | LOW |
The confidence level is surfaced in the UI and injected into Claude's context.
Narrative¶
SimulationNarrative contains four text sections generated by SimulationEngine:
- Headline — one-sentence overall assessment
- Short-term insights — what is likely to happen in the next few days given current patterns
- Recommendations — 1–4 actionable changes to improve the situation
- Long-term signals — directional risk or positivity over weeks/months
What-If Scenarios¶
SimulationEngine.compare() applies a SimulationAdjustment to the baseline input and evaluates the projected result. Five built-in scenarios:
| Scenario | Adjustment |
|---|---|
| Sleep +1h | sleepHoursDelta = +1f |
| Sleep −1h | sleepHoursDelta = −1f |
| Steps +3000 | stepsDelta = +3000 |
| Stress −2 | stressDelta = −2 |
| Recovery Push | Sleep +0.8h, Steps +2500, Stress −2, HR −2 |
Each comparison produces a SimulationDelta (score changes) and a plain-English summary string.
UI¶
The SimulationScreen shows:
- Baseline card — headline, confidence badge, five score pills
- Short-term insights card
- Recommendations card
- Long-term signals card
- Scenario cards — one per scenario, with description, summary, and projected headline