Scoring models

Overview

The Synheart runtime computes three daily scores:

Score	What it answers
Sleep	”How good was last night’s sleep?”
Recovery	”How recovered is the user today?”
Readiness	”How much strain should the user take today?”

Each scorer takes a typed input bundle, returns a typed result, and emits a JSON shape that’s byte-equivalent across Flutter / Kotlin / Swift. The Synheart Core SDKs expose Dart / Kotlin / Swift data classes that round-trip with the runtime’s wire format.

Sleep score

Three input shapes — pick the one matching your data source:

Segmented: stage-by-stage timeline (Apple HealthKit, some Wear OS sources, BLE chest straps)
Aggregated: totals only (vendor APIs that don’t expose stages — Whoop summary, basic Health Connect, self-report)
Vendor score: a single 0-100 number from a vendor that has its own pipeline (Whoop Recovery, Garmin Body Battery)

Kotlin

val input = SleepScoreInput(
    tonight = NightRaw(
        wakeCalendarDate = epochDayForWake,
        detail = NightInput.Aggregated(
            sessionStartMs = bedtime.toEpochMilli(),
            sessionEndMs = wakeTime.toEpochMilli(),
            totals = AggregatedTotals(
                totalSleepMinutes = 420.0,
                awakeMinutes = 30.0,
                deepSleepMinutes = 90.0,  // null when source can't break stages out
                remSleepMinutes  = 110.0,
            ),
        ),
        avgHrBpm = 58.0,
    ),
    priorsNewestFirst = recentNights,
    pipelineVersion = "v1",
)
// Engine returns wire JSON; parse with SleepScoreResult.fromJsonString

Swift

let input = SleepScoreInput(
    tonight: NightRaw(
        wakeCalendarDate: epochDayForWake,
        detail: .aggregated(
            sessionStartMs: Int64(bedtime.timeIntervalSince1970 * 1000),
            sessionEndMs: Int64(wakeTime.timeIntervalSince1970 * 1000),
            totals: AggregatedTotals(
                totalSleepMinutes: 420,
                deepSleepMinutes: 90,  // nil when source can't break stages out
                remSleepMinutes: 110,
                awakeMinutes: 30
            )
        ),
        avgHrBpm: 58
    ),
    priorsNewestFirst: recentNights,
    pipelineVersion: "v1"
)

SleepScoreResult carries score: Int?, confidence: Double, path: SleepPath (stage / aggregated / vendor_score / proxy), mode: SleepScoreMode (cold_start / short_history / stable), components, adjustments, effectiveWeights, and a reason: SleepScoreReason? for absent/degraded scores.

Recovery score

Three-stage scorer — the engine adapts the formula to the available history:

Stage 1 (FirstDay) — 1 night of sleep + (HR or HRV)
Stage 2 (ShortHistory) — ≥ 3 nights with HR/HRV trends
Stage 3 (Personalized) — ≥ 7 nights + stable wearable baselines

// Kotlin
val input = RecoveryScoreInput(
    tonight = NightSummary(wakeCalendarDate = today, totalSleepMinutes = 420.0),
    priors = recentNights,
    overnight = OvernightPhysiology(hrvRmssdMs = 42.5, overnightHrBpm = 58.0),
    priorsOvernight = recentOvernight,
    baselines = stage3Baselines,  // null until ≥ 7 nights
)

RecoveryScoreResult carries score: Int, stage (first_day / short_history / personalized), mode (estimate / trended / personalized), components, confidence, and a List<RecoveryFactor> explaining the score (hrv_above_baseline, resting_hr_elevated, strong_sleep_quality, etc.).

Readiness score

Layers acute load / fatigue / history context on top of today’s Recovery anchor:

// Kotlin
val input = ReadinessScoreInput(
    recoveryScore = 65,
    recoveryConfidence = 0.85,
    acuteWorkload = AcuteWorkloadContext(acuteChronicRatio = 1.1),
    fatigue = FatigueContext(sleepDebtHours = 2.5, recoverySlopePerDay = -3.0),
    history = HistoryContext(consecutiveHighStrainDays = 2, daysSinceRest = 5),
)
// or minimal:
val minimal = ReadinessScoreInput.fromRecovery(72)

ReadinessScoreResult carries score: Int, band: ReadinessBand (.rest / .light / .normal / .push), recoveryAnchor: Int, components, confidence, and a List<ReadinessFactor> (strong_recovery, acute_load_optimal, sleep_debt, etc.).

Sleep questionnaire

Phase-2 self-report input lane — converts subjective answers into the same AggregatedTotals shape vendor payloads produce, so the engine scores them without special-casing.

// Kotlin
val q = SleepQuestionnaireAnswers(
    bedtime = Instant.parse("2026-01-15T22:00:00Z"),
    wakeTime = Instant.parse("2026-01-16T06:00:00Z"),
    sleepLatencyMinutes = 20,
    awakenings = 4,
    subjectiveQuality = 4,
    feltRested = SleepFeltRested.YES,
)
val payload = q.toIngestPayload()
// → feed payload to Baselines.ingestVendorSleep equivalent

The engine accepts null deep/REM on the aggregated path and falls back to duration + continuity components — that’s deliberate. Don’t invent stage durations from subjective signals; surface subjective quality / rested-feeling in the UI alongside the score instead.

Cross-language parity

All three scorers emit identical snake_case JSON on every platform:

Flutter: lib/src/models/{sleep,recovery,readiness}_score.dart + sleep_questionnaire.dart
Kotlin: synheart-core/src/main/kotlin/ai/synheart/core/models/{SleepScore,RecoveryScore,ReadinessScore,SleepQuestionnaire}.kt
Swift: SynheartCore/Models/{SleepScore,RecoveryScore,ReadinessScore,SleepQuestionnaire}.swift

A Flutter, Android, and iOS app talking to the same backend produce byte-equivalent scorer payloads.

Baselines — reactive snapshot of latest scores + 7-night recent-scores ring
Synheart Core overview
HSI specification

Get Started

Setup

CLI

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

Overview

Sleep score

Kotlin

Swift

Recovery score

Readiness score

Sleep questionnaire

Cross-language parity

​Overview

​Sleep score

​Kotlin

​Swift

​Recovery score

​Readiness score

​Sleep questionnaire

​Cross-language parity

​Related

Overview

Sleep score

Kotlin

Swift

Recovery score

Readiness score

Sleep questionnaire

Cross-language parity

Related