Providers

The session SDK decouples the engine from data sources via two abstractions. This page covers the contracts, the bundled implementations, and how the engine uses them. Providers are constructor arguments of SynheartSession, not fields of SessionConfig:

SynheartSession(biosignalProvider: ..., behaviorProvider: ...)        // Dart

SynheartSession(provider = ..., behaviorProvider = ...)              // Kotlin

SynheartSession(provider: ..., behaviorProvider: ...)                // Swift

BiosignalProvider

The heart-rate source. The engine starts it once per session and stops it when the session ends.

Contract (Dart)

Stream-based:

abstract class BiosignalProvider {
  bool get isAvailable;
  String get name;
  Stream<BiosignalSample> startStreaming();
  void stopStreaming();
}

Contract (Kotlin and Swift)

Callback-based:

interface BiosignalProvider {
    val isAvailable: Boolean
    val name: String
    fun startStreaming(onSample: (BiosignalSample) -> Unit)
    fun stopStreaming()
}

public protocol BiosignalProvider {
    var isAvailable: Bool { get }
    var name: String { get }
    func startStreaming(onSample: @escaping (BiosignalSample) -> Void) throws
    func stopStreaming()
}

name is a debug identifier. The Dart live engine skips the subscription when isAvailable is false. The Kotlin and Swift engines do not check isAvailable; they call startStreaming, and if it throws, the session emits a sensor_unavailable error event and ends.

BiosignalSample

Dart:

class BiosignalSample {
  final int timestampMs;
  final double bpm;
  final double? rrIntervalMs;
  final ({double x, double y, double z})? accelerometer;  // record type
  final double? spo2;
}

Kotlin and Swift:

data class BiosignalSample(
    val timestampMs: Long,
    val bpm: Double,
    val rrIntervalsMs: List<Double>? = null,
    val deviceId: String? = null,
    val source: String
)

The Swift struct has the same fields (timestampMs: Int64, bpm, rrIntervalsMs, deviceId, source). source is required and is copied into raw biosignal_frame samples. Kotlin and Swift samples have no accelerometer or SpO₂ fields.

Engine consumption

The engine pushes each sample into a sliding window (see Lifecycle) and computes hr_mean_bpm from it. There is no provider-side rate limiting. RR intervals, accelerometer, and SpO₂ are not used to compute any metric. Kotlin and Swift copy RR intervals into raw biosignal_frame samples; the Dart live engine does not emit raw frames.

Bundled implementations

Implementation	SDK	Notes
`MockBiosignalProvider`	all three	1 Hz sinusoid around 72 BPM with noise. Dart takes an optional `seed`; Kotlin and Swift are unseeded and emit the first sample immediately. Source tag `mock`.
`WatchBiosignalProvider`	Dart	Bridges watch events through `SessionChannel`. `isAvailable = true` optimistically. Also turns on watch routing in `SynheartSession`.
`WearBiosignalProvider`	Kotlin, Swift	Bridges a synheart-wear `BleHrmProvider` (BLE heart-rate monitor). Kotlin takes it as `Any` and reads it via reflection; Swift takes `init(bleHrmProvider:)` in the `SynheartSessionWear` product. Throws `SensorUnavailable` from `startStreaming` if the HRM is not connected. Source tag `ble_hrm`.
`HealthConnectBiosignalProvider`	Kotlin	Wraps a synheart-wear `HealthConnectAdapter` (passed as `Any`, read via reflection) and polls its `readSnapshot()` every 2 seconds by default. RR is derived from BPM. Source tag `health_connect`.
`HealthKitBiosignalProvider`	Swift	`init(wear:)` in the `SynheartSessionHealthKit` product. Subscribes to `SynheartWear.streamHR(interval: 1.0)`. Source tag `apple_healthkit`.

Seeded mocks are Dart-only. The Dart SDK has no BLE HRM, Health Connect, or HealthKit provider; implement BiosignalProvider over your source.

BehaviorProvider

The behavioral signal source. Pull-based: the engine calls currentSnapshot() at each frame and once more for the summary.

Contract

abstract class BehaviorProvider {
  bool get isAvailable;
  String get name;
  BehaviorSnapshot? currentSnapshot();
}

Kotlin (interface BehaviorProvider) and Swift (protocol BehaviorProvider) have the same three members. The engine skips the provider when isAvailable is false. A null snapshot means “nothing right now”; the engine omits the behavior field on that frame.

BehaviorSnapshot

class BehaviorSnapshot {
  final int timestamp;            // epoch ms when captured

  // typing
  final double? typingCadence;
  final double? interKeyLatency;
  final int? burstLength;

  // scrolling
  final double? scrollVelocity;
  final double? scrollAcceleration;
  final double? scrollJitter;

  // taps and app context
  final double? tapRate;
  final int appSwitchesPerMinute;          // default 0, not nullable
  final double? foregroundDuration;
  final double? idleGapSeconds;

  // session-level indices
  final double? stabilityIndex;
  final double? fragmentationIndex;
}

The shape is field-for-field aligned with synheart-behavior’s BehaviorStats, so the two SDKs share a contract without an import dependency. Kotlin and Swift define the same fields. On a frame’s behavior map, keys are snake_case and only non-null fields appear; app_switches_per_minute and timestamp are always present.

Bundled implementations

Implementation	SDK	Notes
`MockBehaviorProvider`	all three	Returns stable mid-range values for tests.
`BehaviorSdkProvider`	Kotlin, Swift	Wraps synheart-behavior’s `SynheartBehavior` and reads `getCurrentStats()`. Kotlin takes the SDK as `Any` (reflection) and reports `isAvailable` from `isInitialized()`; Swift takes `init(sdk:)` in the `SynheartSessionBehavior` product and always reports available.

The Dart SDK does not bundle a synheart_behavior wrapper; implement BehaviorProvider over your behavior source.

Integration with the engine

SynheartSession(constructor)
  ├── biosignal provider → started for the duration of each session
  └── behavior provider  → snapshot pulled at each frame
                           (and once more for SessionSummary)

Both are optional. Kotlin and Swift default the biosignal provider to MockBiosignalProvider. In the Dart live mode, with no biosignal provider:

LiveSessionEngine still emits SessionStarted, frames with sample_count = 0 and hr_mean_bpm = 0.0, and a final SessionSummary.
This is useful for testing the framing logic itself.

Provider state machine (informal)

provider constructed
    │ Dart: isAvailable = false → engine skips subscription
    ▼
startStreaming() called       (Kotlin / Swift: a throw ends the session with an error event)
    │
    ▼
streaming
    │ stopStreaming() called  (session end / dispose)
    ▼
stopped

Providers must tolerate stopStreaming() being called more than once — the Kotlin and Swift engines call it on session end and again on dispose(). They should stop emitting after stopStreaming() returns.

Watch provider specifics

WatchBiosignalProvider (Dart):

BiosignalFrame events → each BiosignalSample is passed to the engine directly.
SessionFrame events → one sample synthesised from metrics.hr_mean_bpm (when it is above 0) with rrIntervalMs = 60000.0 / bpm.
SessionStarted, SessionSummary, SessionError → ignored (lifecycle, not biosignal data).

Channel errors are non-fatal: the provider swallows them so a disconnect does not end the session.

Authoring a provider

A custom BiosignalProvider should:

Allocate sensor resources (BLE GATT subscribe, HealthKit authorization, etc.) on startStreaming() and release them on stopStreaming().
Dart: emit samples on the Stream<BiosignalSample> returned from startStreaming().
Kotlin / Swift: call onSample for each sample, with a source tag that describes the real source. Throw SessionError.SensorUnavailable / .sensorUnavailable from startStreaming if the source cannot start.
Not block the calling thread — startStreaming is called synchronously from startSession.

A custom BehaviorProvider should:

Maintain its own internal accumulators.
Return a fresh BehaviorSnapshot on each currentSnapshot() call (or null when no recent activity).
Use the current epoch milliseconds for the snapshot timestamp.

Lifecycle — when the engine starts and stops providers.
Watch Protocol — the watch events WatchBiosignalProvider consumes.

Get Started

Security

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

BiosignalProvider

Contract (Dart)

Contract (Kotlin and Swift)

BiosignalSample

Engine consumption

Bundled implementations

BehaviorProvider

Contract

BehaviorSnapshot

Bundled implementations

Integration with the engine

Provider state machine (informal)

Watch provider specifics

Authoring a provider

BiosignalProvider

Contract (Dart)

Contract (Kotlin and Swift)

BiosignalSample

Engine consumption

Bundled implementations

BehaviorProvider

Contract

BehaviorSnapshot

Bundled implementations

Integration with the engine

Provider state machine (informal)

Watch provider specifics

Authoring a provider

Related