Skip to content

v0.5.0

Choose a tag to compare

@Thecimal Thecimal released this 22 Oct 00:44
· 53 commits to main since this release

Added

  • WHOOP import (--source whoop). Reads JSON saved from the WHOOP Developer API v2 (a JSON array of
    records, or one {"records": [...]} response): sleep (sleep_hours, asleep time only), recovery
    (resting_heart_rate, hrv_ms as an RMSSD) and workouts (workout_minutes). Every value is kept as its
    own observation with the source WHOOP, local days come from each record's timezone_offset, repeated
    records import once, and a bad record is skipped and reported without stopping the rest. Written against
    WHOOP's documented v2 sample responses and tested on synthetic data only; the WHOOP app's CSV export is
    not supported. See docs/importing.md for the exact rules and what is left out.
  • Consistent backups and safe restores (quantified-self-backup). Copying health.db is not a backup:
    the database runs in WAL mode, so with anything holding it open a copy of the file alone can be empty or
    miss recent writes. quantified-self-backup create FILE uses SQLite's online-backup API for a consistent
    single-file snapshot, integrity-checks it, owner-only permissions, and never overwrites an existing file.
    quantified-self-backup restore FILE validates the backup first (integrity, health database, schema not
    newer than this release), stages and re-checks a copy, refuses while another program has the database open,
    and moves the current database aside as <name>.pre-restore-<time> instead of deleting it. It is a
    command-line tool only, not an MCP tool.
  • Canonical ingestion contract (ingest.py). The one shape every source adapter's observations
    must take: metric, naive local timestamp, value, canonical unit, source, source record id, original
    timezone and quality, with a strict validator that normalises known unit spellings (count/min to
    bpm), rejects timestamps with a UTC offset, values outside the registry bounds, units that need a
    conversion, and unknown fields, and drops repeated record ids. A bad record is rejected on its own
    with a reason and the rest of a batch still loads. Nothing uses it yet: adapters are moved onto it in
    following changes.
  • Source coverage matrix. python -m source_coverage (or --json) measures what the database
    actually holds, per importer, source and metric: first and latest day, days covered, gaps, freshness,
    the status of the import that produced it, provenance (units, source types, measurement counts) and
    how many days analytics resolved to each source. Each entry is classified green, yellow or red with
    its reasons listed, and a per-domain view (sleep, HRV, heart rate, activity, body measurements,
    workouts) states explicitly that readiness, training load and routes are not modelled. Metrics in
    HEALTH_PRIVATE_FIELDS are left out. HRV recorded as SDNN (Apple Health) and as RMSSD (Health
    Connect) under one metric is flagged as mixed_statistics. Read-only; no new MCP tool.
  • Incremental imports with an audit trail. Re-importing a source no longer deletes and rewrites
    everything: each (metric, day) is compared with what the importer already stored, unchanged days are left
    exactly as they were (ids and imported_at keep recording when they were first imported), and only new
    or changed days are written. Each imports row now records records_seen, records_added,
    records_updated, records_unchanged and records_removed (days dropped by --replace), plus the
    dataset coverage before and after, and get_import_status returns them. quantified-self-init-db prints
    the same counts. Schema migration 9 adds the columns to databases that already have the table.
  • Import history and data freshness. Every quantified-self-init-db run now
    records an imports row (importer, source file name and SHA-256, status
    running / succeeded / failed, rows loaded and skipped, measurements
    written, error). Two read-only MCP tools expose it: get_data_status reports
    whether the database is CURRENT, STALE, INCOMPLETE, NO_DATA or
    IMPORT_FAILED (latest data date, coverage, gaps, last successful import,
    suggested action), and get_import_status lists recent import runs.
    Metrics in HEALTH_PRIVATE_FIELDS are ignored when computing coverage.
  • data_health on every analytics tool. A single
    data-quality state for the window behind the answer: VALID,
    VALID_WITH_GAPS, INSUFFICIENT_DATA, STALE or IMPORT_INCOMPLETE, with
    every applicable reason, the latest observation and its age, the covered
    period, gaps, observation count and the last import. It combines the window's
    existing evidence with the import history and dataset status, and is
    separate from claim (which is unchanged). Results that rest on several
    windows (period comparisons, correlations, recent changes, explanations)
    report the weakest window and list every window's reasons.
  • Agent-loop eval (eval/agent, Phase 1). A real model, the real MCP
    server and real tool results in a multi-turn loop, scored per layer (routing,
    arguments, execution) with replayable traces, deterministic fixtures defined
    relative to today, and a tool coverage matrix built from the live tool list
    (python -m eval.agent --coverage --strict). The harness itself is covered
    by offline tests that need no API key. Interpretation and final-answer
    scoring are not built yet and are reported as not scored.

Changed

  • The evidence registry now describes what is actually evaluated — trend,
    window_comparison, correlation and anomaly list only the dimensions that
    have evaluators (sample and temporal, plus missingness for the first three),
    like baseline. Previously they also listed robustness, practical,
    provenance and measurement_validity, which no evaluator produced, so every
    claim resolved those as not_assessed and could never exceed suggestive.
    Nothing is tolerated to make that go away: those four analyses now carry an
    explicit max_tier: suggestive ceiling whose factor, practical_not_evaluated,
    is added to claim.decision.must_state (a statistically detectable but trivial
    effect cannot be called supported while practical significance is unchecked).
    claim.profile.dimensions for those analyses no longer contains the
    not_assessed robustness/practical/provenance entries, and
    robustness_not_assessed, practical_not_assessed and
    provenance_not_assessed no longer appear in must_state. A parity test now
    fails if a registry dimension has no evaluator or an evaluator's output is not
    in the registry.

Fixed

  • A mistyped or unsupported metric is no longer reported as "no data". read_measurements and
    get_metric_provenance answered a name nothing is stored under (for example sleep instead of
    sleep_hours) with a successful empty result, so a client would tell the user they had no such data.
    They now return the same [invalid_metric] error log_measurement already used, listing the supported
    metrics and suggesting the closest one. A supported metric with no readings in the window still returns
    an empty result, and a metric that has stored readings stays readable even if its aggregation rule was
    removed.

  • The HTTP transport no longer listens on every network interface. Setting PORT (the cloud-deploy
    mode) used to bind 0.0.0.0 with no authentication, so anyone who could reach the machine could call
    every tool, including the ones that write, clear and export data. It now binds loopback (FastMCP's
    default). A deployment that must be reached from outside, such as a container behind a platform
    router, now has to opt in with FASTMCP_HOST=0.0.0.0; that is still allowed but logs a warning that
    nothing authenticates callers. Stdio use (no PORT) is unchanged.

  • read_measurements and read_workout_sessions validate their inputs. A start/end that was not a
    real YYYY-MM-DD date (last week, 2026-3-5), a window ending before it starts, or a limit
    outside 1-1000 used to return a successful empty list (or, for limit=-1 and an unparseable
    end_date, an unbounded one), which reads as "no data". They now return the same structured
    [invalid_range] error as read_health_data. ISO timestamps are still accepted as bounds by
    read_measurements; empty strings still mean "not given".

  • Re-importing changed days no longer scans the whole metric once per day. Replacing a changed
    (metric, day) deleted the importer's old rows with a filter no index could serve, so each changed
    day read every row of that metric. The delete now seeks the day through the existing
    (metric, timestamp) index and keeps the original filter as an exact check, so the same rows are
    deleted. On a 1M-row database with 5% of days changed, the re-import went from about 83s to
    about 24s (measured with a throwaway benchmark, not part of the repo).

  • A failed import is now visible to get_data_status and get_import_status even when it fails
    while reading the file.
    Only failures after parsing were recorded in imports, so a truncated or
    unreadable export left no trace and the status stayed CURRENT. A read failure is now recorded as a
    failed run (status IMPORT_FAILED, action rerun_import). The recorded reason is the error class
    plus its file position for XML/JSON/CSV/encoding errors and the OS reason for I/O errors; a file the
    importer rejects with its own message (e.g. a CSV with no date column) is recorded as rejected, and any
    other error by class name only, so a record value or the file's full path never reaches the
    model. The importer still raises exactly as before.

  • Analytics no longer present a source change as a health change. daily_metrics keeps one source
    per (metric, day), but a baseline, trend, anomaly scan, comparison or correlation read it as one
    anonymous series, so a device switch inside a window, a different device in each compared window,
    or two devices disagreeing with no source_priority all came back data_health: VALID. They now
    report the new status MIXED_SOURCES with the reasons source_changed_within_window,
    source_changed_between_windows or unranked_source_conflict_in_window. A day settled by an
    explicit source_priority entry is a documented rule and is not flagged. The numbers themselves
    are unchanged.

  • Wheel packaging and Dockerfile runtime dependencies. The build wheel include list in
    pyproject.toml and COPY in Dockerfile previously omitted tools/, db/, data_health.py,
    errors.py, privacy.py, schemas.py, and source_coverage.py, causing ModuleNotFoundError
    on package installs or container runs. All modules and database schema files are now included.

  • GitHub Actions action versions. Updated .github/workflows/ci.yml and publish.yml from
    invalid @v7 actions to official actions/checkout@v4 and actions/setup-python@v5.

  • Imports from different importers are no longer summed together. Day totals an importer wrote
    without a source (CSV, Health Connect, and Apple Health's sleep and other daily rows) all fell into one
    unattributed group in the daily projection, so importing the same period through two paths doubled
    sum metrics such as steps and sleep, and reported the day as a single source. An import now stamps
    such rows with the importer's name as source, so the projection resolves between importers with
    source_priority (or its documented fallback) and resolution says so. Schema migration 10 stamps
    existing imported rows the same way and rebuilds daily_metrics, which corrects days that were
    double-counted: those daily values will change. Manual measurements keep no source.

  • Apple Health raw observations are now stored in the metric's canonical unit
    and validated per reading.
    daily_metrics is projected from measurements,
    but the Apple Health adapter wrote raw readings in the device's own unit under
    the canonical metric name: a 154 lb weight became weight_kg = 154 and
    water_ml was summed in litres. It also never bounds-checked raw readings, and
    a day reported as "Skipping date ..." for an out-of-bounds total was imported
    anyway. Pound and litre readings are now converted before storage (the stored
    unit is kg / ml), readings in other weight or volume units (stones, fluid
    ounces) are skipped and counted instead of being read as kg / ml, out-of-bounds
    readings are skipped, and a skipped day imports none of its raw rows.

  • NaN / infinity no longer crash an import or reach an aggregate. Apple
    Health, Health Connect and CSV imports now skip and report non-finite values
    like any other bad record (previously int(round(nan)) / int(inf) aborted
    the whole import with a traceback). A rejected Health Connect reading also no
    longer leaves an empty per-day bucket behind.