Skip to content

0.8.0

Choose a tag to compare

View all tags
@rfivesix rfivesix released this 09 Apr 14:39
· 1488 commits to main since this release
v0.8.0
7182643

Hypertrack 0.8.0

Hypertrack 0.8.0 introduces the first full release of the new adaptive nutrition recommendation system.

This release adds a mathematically grounded calorie and macro recommendation flow that is designed to be:

  • adaptive instead of static
  • conservative under uncertainty
  • explicit about confidence and edge cases
  • deterministic and testable
  • user-controlled rather than silently auto-applied

The biggest change in this release is that adaptive nutrition is no longer just a rough heuristic or a preview path. It is now built around a canonical Bayesian recursive estimator with stable persistence, backup/restore continuity, phase tracking, uncertainty UI, and broad scenario coverage.

Highlights

Adaptive nutrition is now a real system

Hypertrack can now generate adaptive calorie and macro recommendations from:

  • recent bodyweight trend
  • logged intake
  • profile priors
  • activity context
  • goal direction (cut, maintain, bulk)

The recommendation is generated weekly and stays stable within the same due week unless the user explicitly forces a recalculation.

Explicit user control

Generation and application are intentionally separate:

  • Generate computes a new recommendation
  • Apply copies that recommendation into active targets

This means Hypertrack does not silently overwrite the user’s current goals.

User-facing uncertainty

The app now exposes:

  • an estimated maintenance calorie value
  • a likely maintenance range
  • uncertainty/stabilization hints
  • freshness metadata such as:
    • calculated at
    • next due time
    • whether a recommendation is currently due

This makes the adaptive system much more transparent than a single opaque calorie number.

Phase-aware observation model

The model now accounts for the fact that early scale-weight changes in a new cut or bulk are often distorted by glycogen and water shifts.

Instead of assuming a fixed 7700 kcal/kg immediately, Hypertrack now uses a confirmed-phase-age ramp:

  • week 1 of a confirmed phase: 3000 kcal/kg
  • then a linear increase
  • reaching 7700 kcal/kg by week 9+
  • staying at 7700 afterward

This makes early-phase behavior more realistic while keeping the implementation simple and deterministic.

Stronger persistence and recovery

Adaptive nutrition state is now persisted canonically with:

  • coherent snapshot persistence
  • recursive estimator state persistence
  • adaptive phase tracking state
  • legacy-key migration fallback
  • self-healing recovery from malformed canonical keys

This means the system is much more robust across app restarts, backup/restore, and older saved states.

What is new in 0.8.0

Adaptive recommendation model

Hypertrack now uses a Bayesian recursive maintenance estimator as the core of adaptive calorie estimation.

The model maintains a latent estimate of true maintenance calories and updates it over time using:

  • a prior / previous posterior
  • a prediction step
  • an observation step based on intake and bodyweight trend
  • uncertainty propagation

This allows the model to adapt over time without overreacting to a single noisy week.

Weekly scheduling semantics

Adaptive recommendations now follow a due-week model:

  • weeks are Monday-anchored
  • one recommendation per due week
  • same-week runs stay deterministic
  • forced recalculation reuses the same stable anchor and replay prior behavior

This avoids Monday-vs-Wednesday drift and keeps repeated runs consistent.

Diet phase tracking

Hypertrack now tracks adaptive phase state canonically:

  • cut
  • maintain
  • bulk

Phase changes are not committed instantly. Instead:

  • a phase change becomes pending
  • it must remain unchanged for 7 consecutive days
  • only then it becomes the confirmed phase

This avoids resetting the model because of accidental taps or very short-lived experiments.

Credible interval / likely range

The maintenance estimate now exposes a simple uncertainty interval to the UI:

  • maintenance estimate
  • lower bound
  • upper bound

This is presented as practical user guidance, not as a scientific guarantee.

Stabilization hints

The system now surfaces when the recursive model is still settling, for example:

  • early bootstrap
  • transient high-uncertainty behavior
  • noisier input regimes

This helps explain why the recommendation may still move more in the early phase than later on.

Due notifications

The recommendation due-notification seam is now implemented with strict gating:
a notification only fires if:

  • a recommendation is due
  • no recommendation exists for the current due week
  • no due-notification has already been sent for that due week

Backup / restore continuity

Adaptive nutrition state is now covered by the existing backup/restore system through SharedPreferences export/import, including:

  • adaptive settings
  • latest snapshot
  • recursive state
  • phase tracking state
  • due-week metadata

Continuity was also validated with dedicated restore tests.

Mathematical model overview

At the center of the system is a scalar Bayesian recursive filter for maintenance calories.

Latent state

The model tracks:

  • x_t = true maintenance calories per day at week t

and an uncertainty term:

  • P_t = posterior variance

Prediction step

Before seeing the new week’s observation, the model predicts forward:

  • x_pred = x_prev
  • P_pred = min(P_prev + Q, P_cap)

Interpretation:

  • the maintenance estimate itself carries forward
  • uncertainty grows slightly over time
  • uncertainty is capped so the model never fully forgets everything

Observation model

The weekly observation is derived from:

  • average logged calories
  • smoothed weight slope
  • effective kcal/kg scaling

Conceptually:

  • z ≈ avgLoggedCalories - weightSlope * (effectiveKcalPerKg / 7)

The effective kcal/kg is phase-age dependent:

  • lower in the first confirmed weeks of a phase
  • gradually ramps up
  • reaches the mature long-run assumption later

Update step

If there is a usable observation, the model computes a Kalman-style gain:

  • K = P_pred / (P_pred + R)

and updates the estimate:

  • x_post = x_pred + K * (z - x_pred)
  • P_post = (1 - K) * P_pred

Interpretation:

  • if uncertainty is high and the observation is trustworthy, the model moves more
  • if the observation is noisy, the model moves less
  • the posterior becomes next week’s prior

Missing-observation behavior

If a user has missing or unusable logs:

  • prediction still runs
  • uncertainty increases
  • no update is applied

So the model becomes less certain without inventing a false adjustment.

Why this matters

This is fundamentally different from a static calorie formula.
Instead of recomputing calories from scratch every week, Hypertrack:

  • carries forward memory
  • updates cautiously
  • represents uncertainty explicitly
  • avoids reset-like behavior unless there is real evidence

Noise handling and calibration

The model distinguishes two important uncertainty sources:

Q: maintenance drift

This describes expected week-to-week drift in true maintenance.

R: observation noise

This describes uncertainty in the weekly observation, driven by things like:

  • intake noise
  • sparse logging
  • weight-trend uncertainty
  • unresolved calorie inputs
  • short-horizon scale noise

Hypertrack uses deterministic base behavior with bounded calibration support and explicit fallback behavior when history is insufficient.

There is also an internal residual-bias diagnostic seam to help evaluate whether the current energy-density assumptions appear systematically too high or too low.

Safety and product semantics

Manual apply only

New recommendations do not auto-apply to active goals.

Stable within due week

Repeated generation within the same due week does not drift because same-week replay uses stored prior context.

Bounded uncertainty

Long no-log gaps increase uncertainty, but variance caps prevent the estimator from turning into a full reset.

Coherent persistence

Snapshot, recursive state, and phase tracking all include consistency validation and recovery logic.

Testing and validation

A large amount of regression and scenario coverage was added for this release.

Covered areas include

  • repository persistence
  • migration fallback
  • malformed-key recovery
  • due-week determinism
  • same-week replay behavior
  • onboarding bootstrap behavior
  • backup/restore integrity
  • phase transition behavior
  • long-horizon adaptive runs
  • profile variation scenarios
  • sparse logging scenarios
  • prediction-only weeks
  • deterministic repeatability
  • chaotic realistic trajectories
  • synthetic ground-truth convergence scenarios

Scenario examples

Tests now simulate things like:

  • long clean cut / maintain / bulk runs
  • sparse weight logging
  • sparse intake logging
  • no-log gaps
  • phase re-entry style transitions
  • weekend spikes
  • refeed blocks
  • water jumps
  • illness periods
  • fluctuating step counts
  • good → poor → good logging quality
  • very light / very heavy / lean / high-body-fat profiles
  • male / female / unknown gender cases
  • low / high activity cases

This release does not claim the model is final.
It does mean the current implementation is now broad enough, deterministic enough, and validated enough to ship as a serious first public version.

Documentation and release hygiene

The adaptive nutrition documentation was consolidated into the canonical current-state doc, and stale planning/spec material was removed from the primary documentation path.

The release also includes clearer release-facing wording and a finalized 0.8.0 changelog entry.

Acknowledgements

Special thanks to @Whatsonyourmind for thoughtful feedback on:

  • Bayesian update framing
  • uncertainty presentation
  • phase-aware observation behavior
  • edge-case discipline
  • evidence-first handling of unresolved model questions

That feedback materially improved both the implementation and the decision to keep unresolved edge cases out of the shipped core until stronger evidence exists.

Closing note

Hypertrack 0.8.0 is the first release where adaptive nutrition becomes a mathematically structured, persistent, and user-facing system rather than a static estimate or a hidden rule set.

It is intentionally conservative where the evidence is strong, and intentionally restrained where the evidence is not yet strong enough. That tradeoff is central to this release.

What's Changed

  • Propagate AI meal-capture save result to trigger Diary refresh by @Copilot in #237
  • Expand and harden 0.8 adaptive nutrition spec with MVP model, gating semantics, and documentation cleanup by @Copilot in #239
  • development v0 by @rfivesix in #240
  • 0.8.0_dev_v1 by @rfivesix in #246
  • bayesien-tdee-estimator by @rfivesix in #249

Full Changelog: v0.7.10...v0.8.0

Contributors

rfivesix and Whatsonyourmind
Assets 4
Loading