Crate synheart_flux 

Synheart Flux

On-device compute engine for HSI-compliant human state signals.

Flux transforms raw wearable vendor data and smartphone behavioral events into HSI 1.0 (Human State Interface) compliant signals through a deterministic pipeline:

Raw Vendor JSON ──▸ Adaptation ──▸ Normalization ──▸ Feature Derivation
                                                         │
                     HSI JSON ◂── Encoding ◂── Baseline Computation

Quick Start

Stateless one-shot conversion

Process a single day of wearable data without maintaining baselines:

use synheart_flux::whoop_to_hsi_daily;

let raw_json = std::fs::read_to_string("whoop_payload.json").unwrap();
let hsi_payloads = whoop_to_hsi_daily(
    raw_json,
    "America/New_York".to_string(),
    "device-123".to_string(),
).expect("pipeline error");

for payload in &hsi_payloads {
    println!("{payload}");
}

Stateful processing with persistent baselines

Use FluxProcessor to maintain rolling baselines across multiple calls:

use synheart_flux::FluxProcessor;

let mut processor = FluxProcessor::with_baseline_window(7);

// Process daily wearable data
let hsi = processor.process_whoop(
    r#"{"sleep":[],"recovery":[],"cycle":[]}"#,
    "America/New_York",
    "device-123",
).expect("pipeline error");

// Persist baselines for next session
let saved = processor.save_baselines().unwrap();

Behavioral metrics

Process smartphone session data into behavioral HSI signals:

use synheart_flux::behavior_to_hsi;

let session_json = std::fs::read_to_string("session.json").unwrap();
let hsi_json = behavior_to_hsi(session_json).expect("pipeline error");
println!("{hsi_json}");

Architecture

The crate is organized into domain modules that mirror the processing pipeline:

synheart_flux
├── core        ─ Shared infrastructure (errors, HSI types, raw-event schema)
├── biosignal   ─ Wearable physiology: adapters → normalize → features → baseline → encode
├── behavior    ─ Smartphone behavior:  parser   → normalize → features → baseline → encode
├── pipeline    ─ Top-level orchestration (FluxProcessor, stateless flows, context)
├── snapshot_adapter ─ Conversion to synheart-adapt-engine's HsiSnapshot format
├── stats       ─ Extended statistical computations (HRV, RHR, sleep)
└── ffi         ─ C-compatible FFI bindings (feature-gated)

Modules

Module	Purpose
core	ComputeError, HsiPayload and all HSI 1.0 types, raw-event schema
biosignal	Vendor adapters (WhoopAdapter, GarminAdapter), normalization, features, baselines, encoding
behavior	Session parsing, behavioral normalization, distraction/focus derivation, HSI encoding
pipeline	FluxProcessor (stateful), whoop_to_hsi_daily / garmin_to_hsi_daily (stateless), BioDailyContext
snapshot_adapter	SnapshotAdapter for adapt-engine integration
stats	ExtendedStats for HRV, RHR, and sleep research statistics
ffi	C FFI bindings (requires ffi feature)

Feature Flags

Feature	Description
ffi	Enables the C-compatible FFI bindings in the ffi module
cli	Enables the flux CLI binary (adds clap and atty dependencies)

HSI Output

All pipeline functions produce JSON conforming to the HSI 1.0 schema. Each payload contains an HsiPayload with:

• hsi_version: Always "1.0"
• producer: HsiProducer identifying this crate
• axes: HsiAxes containing domain readings (physiological, behavioral, context)
• privacy: HsiPrivacy consent and data-handling metadata
• windows / sources: Temporal and provenance metadata

Re-exports

pub use core::error::ComputeError;

pub use core::hsi::HsiAxes;

pub use core::hsi::HsiAxesDomain;

pub use core::hsi::HsiAxisReading;

pub use core::hsi::HsiConsent;

pub use core::hsi::HsiDirection;

pub use core::hsi::HsiPayload;

pub use core::hsi::HsiPrivacy;

pub use core::hsi::HsiProducer;

pub use core::hsi::HsiSource;

pub use core::hsi::HsiSourceType;

pub use core::hsi::HsiWindow;

pub use core::hsi::HSI_VERSION;

pub use core::schema::RawEvent;

pub use core::schema::RawEventAdapter;

pub use core::schema::ValidationError;

pub use core::schema::SCHEMA_VERSION;

pub use snapshot_adapter::AdaptSnapshot;

pub use snapshot_adapter::DataSource;

pub use snapshot_adapter::HsiScores;

pub use snapshot_adapter::MappingConfig;

pub use snapshot_adapter::ScoreConfidence;

pub use snapshot_adapter::SnapshotAdapter;

pub use biosignal::BaselineStore;

pub use biosignal::FeatureDeriver;

pub use biosignal::GarminAdapter;

pub use biosignal::HsiEncoder;

pub use biosignal::Normalizer;

pub use biosignal::VendorPayloadAdapter;

pub use biosignal::WhoopAdapter;

pub use biosignal::DEFAULT_BASELINE_WINDOW;

pub use pipeline::context::BioDailyContext;

pub use pipeline::context::DecayedBioContext;

pub use pipeline::context::DEFAULT_DECAY_HALF_LIFE_HOURS;

pub use pipeline::garmin_to_hsi_daily;

pub use pipeline::hr_window_to_hsi;

pub use pipeline::whoop_to_hsi_daily;

pub use pipeline::FluxProcessor;

pub use stats::ExtendedStats;

pub use behavior::behavior_to_hsi;

pub use behavior::BehaviorProcessor;

pub use biosignal::types::*;

Modules

behavior

Smartphone behavioral data processing — session parsing, normalization, and HSI encoding. Behavioral metrics computation module.

biosignal

Wearable physiology processing — vendor adapters, normalization, features, baselines, and HSI encoding. Biosignal domain — wearable physiology processing.

core

Core shared infrastructure (error types, HSI schema, raw-event definitions). Core shared infrastructure for Synheart Flux.

ffiffi

C-compatible FFI bindings for calling Flux from other languages.

pipeline

Top-level pipeline orchestration — stateful FluxProcessor and stateless conversion functions. Pipeline orchestration — the main public API for Synheart Flux.

snapshot_adapter

Snapshot adapter for synheart-adapt-engine integration. Snapshot adapter for synheart-adapt-engine integration.

stats

Extended statistical computations for HRV, RHR, and sleep research metrics. Extended statistical features for wellness prediction.

Constants

FLUX_VERSION

Flux version string embedded in all HSI payloads, sourced from Cargo.toml.

PRODUCER_NAME

Producer name included in every HsiProducer block.