Skip to main content

​
What is Synheart Flux?

Synheart Flux is a Rust-based on-device compute engine that transforms raw wearable vendor payloads (e.g., WHOOP, Garmin) and smartphone behavioral data into HSI-compliant human state signals. Flux centralizes two parallel pipelines:
  • Wearable Pipeline: vendor adaptation → normalization → feature derivation → baseline computation → HSI encoding
  • Behavioral Pipeline: session parsing → normalization → metric computation → baseline tracking → HSI encoding

​
Key Features

​
Wearable Processing

  • Parse vendor JSON into canonical, vendor-agnostic structures
  • Normalize units and scales (and surface data quality flags)
  • Derive features (sleep efficiency/fragmentation, normalized load, etc.)
  • Maintain rolling baselines for relative interpretation (HRV, RHR, sleep)
  • Encode daily windows into HSI JSON with provenance + quality/confidence

​
Behavioral Metrics

  • Parse behavioral session JSON (taps, scrolls, notifications, app switches, typing)
  • Compute engagement metrics (distraction score, focus hint, burstiness, interaction intensity)
  • Detect patterns (idle segments, engagement blocks, scroll jitter, deep focus periods)
  • Maintain rolling baselines across sessions (20-session default window)
  • Encode behavioral windows into HSI JSON with deviation tracking

​
Non-goals

  • Emotion inference or labeling
  • Medical/diagnostic claims
  • UI, visualization, or cloud-side compute
  • Replacing wearable ingestion/auth SDKs

​
Installation

​
Rust (crate)

Add to your Cargo.toml: 
[dependencies]
synheart-flux = "0.1"

​
Platform Installs (Android / iOS / Flutter / Desktop)

Flux is typically bundled into a host SDK (e.g., Synheart Wear, Synheart Behavior) as native artifacts.
  • Recommended (prebuilt): Download artifacts from GitHub Releases and vendor them into your SDK repo
  • Fallback (from source): Build artifacts in CI using the scripts in scripts/

​
Android (JNI .so inside an AAR)

src/main/jniLibs/
  arm64-v8a/libsynheart_flux.so
  armeabi-v7a/libsynheart_flux.so
  x86_64/libsynheart_flux.so

​
iOS (XCFramework)

ios/Frameworks/SynheartFlux.xcframework

​
Flutter

Bundle the same artifacts in your Flutter plugin: 
android/src/main/jniLibs/*/libsynheart_flux.so
ios/Frameworks/SynheartFlux.xcframework

​
WebAssembly (WASI)

Flux can be compiled to WASM for cross-language integration: 
rustup target add wasm32-wasip1
cargo build --target wasm32-wasip1 --release

​
Usage

​
One-shot Conversion (Stateless)

use synheart_flux::{garmin_to_hsi_daily, whoop_to_hsi_daily};

fn main() -> Result<(), synheart_flux::ComputeError> {
    let whoop_json = r#"{"sleep": [], "recovery": [], "cycle": []}"#.to_string();
    let garmin_json = r#"{"dailies": [], "sleep": []}"#.to_string();

    let whoop_hsi = whoop_to_hsi_daily(
        whoop_json,
        "America/New_York".to_string(),
        "device-123".to_string(),
    )?;

    let garmin_hsi = garmin_to_hsi_daily(
        garmin_json,
        "America/Los_Angeles".to_string(),
        "garmin-device-456".to_string(),
    )?;

    println!("WHOOP payloads: {}", whoop_hsi.len());
    println!("Garmin payloads: {}", garmin_hsi.len());
    Ok(())
}

​
Persistent Baselines Across Calls

For baselines that accumulate across multiple payloads (e.g., across app launches), use FluxProcessor: 
use synheart_flux::FluxProcessor;

fn main() -> Result<(), synheart_flux::ComputeError> {
    let mut p = FluxProcessor::with_baseline_window(7);

    // Load baseline state from disk/keychain/etc.
    // p.load_baselines(&saved_json)?;

    let whoop_json = r#"{"sleep": [], "recovery": [], "cycle": []}"#;
    let hsi = p.process_whoop(whoop_json, "America/New_York", "device-123")?;

    // Save baseline state for next run
    let saved_json = p.save_baselines()?;
    println!("HSI payloads: {}", hsi.len());
    Ok(())
}

​
Behavioral Metrics (One-shot)

use synheart_flux::behavior_to_hsi;

fn main() -> Result<(), synheart_flux::ComputeError> {
    let session_json = r#"{
        "session_id": "sess-123",
        "device_id": "device-456",
        "timezone": "America/New_York",
        "start_time": "2024-01-15T14:00:00Z",
        "end_time": "2024-01-15T14:30:00Z",
        "events": [
            {"timestamp": "2024-01-15T14:01:00Z", "event_type": "scroll", "scroll": {"velocity": 150.5, "direction": "down"}},
            {"timestamp": "2024-01-15T14:02:00Z", "event_type": "tap", "tap": {"tap_duration_ms": 120}},
            {"timestamp": "2024-01-15T14:03:00Z", "event_type": "notification", "interruption": {"action": "ignored"}}
        ]
    }"#.to_string();

    let hsi_json = behavior_to_hsi(session_json)?;
    println!("Behavioral HSI: {}", hsi_json);
    Ok(())
}

​
Behavioral Metrics with Persistent Baselines

use synheart_flux::BehaviorProcessor;

fn main() -> Result<(), synheart_flux::ComputeError> {
    let mut processor = BehaviorProcessor::with_baseline_window(20); // 20 sessions

    let session_json = r#"{"session_id": "...", "device_id": "...", ...}"#;
    let hsi = processor.process(session_json)?;

    // Save baseline state for next run
    let saved_json = processor.save_baselines()?;
    println!("Behavioral HSI: {}", hsi);
    Ok(())
}

​
Behavioral Axes

AxisDirectionDescription
distractionhigher_is_moreComposite distraction score (0-1)
focushigher_is_moreInverse of distraction (0-1)
task_switch_ratehigher_is_moreApp switch frequency (normalized)
notification_loadhigher_is_moreNotification frequency (normalized)
burstinessbidirectionalTemporal clustering (Barabasi index)
scroll_jitter_ratehigher_is_moreDirection reversals ratio
interaction_intensityhigher_is_moreEvents per second (normalized)
idle_ratiohigher_is_moreIdle time ratio

​
HSI Output Format

Flux emits HSI 1.0 JSON payloads that conform to the Human State Interface specification.

​
Required Fields

  • hsi_version — Schema version (e.g., "1.0")
  • observed_at_utc — When the data was observed
  • computed_at_utc — When HSI was computed
  • producer — Name, version, and instance_id of the producing software
  • window_ids / windows — Time windows with start/end timestamps
  • source_ids / sources — Data sources with type and quality
  • axes — Behavioral readings organized by domain
  • privacy — Data handling declarations

​
Feature Flags

  • ffi: Enables the C FFI bindings for mobile and cross-language integration

​
Resources

​
License

Licensed under the Apache License, Version 2.0.