Synheart Behavior Overview - Synheart Documentation

What is Synheart Behavior?

Synheart Behavior is a multi-platform SDK for inferring behavioral signals from digital interactions (scroll, tap, swipe, typing, notifications, calls) directly on device, ensuring privacy and real-time performance. Supported Motion States:

🛌 LAYING:
🚶 MOVING:
🪑 SITTING:
🧍 STANDING:

Key Features

On-Device Processing

All inference happens locally on your device
No network calls required
No raw interaction data leaves the device
Privacy-first by design

On-Demand Metrics Calculation

Calculate behavioral metrics for custom time ranges within sessions
Query metrics for specific time periods without ending the session
Supports both active and ended sessions
Automatic validation ensures time ranges are within session bounds

Privacy-First Design

No PII: No names, contacts, or user-identifying data
No content capture: No text, images, or semantic data
No keystroke logging: Text input captured only as abstract tap events
Event-level metadata only: Timing and physical metrics only

Multi-Platform

Platform	SDK	Installation	Min OS	Version	Status
Flutter	`synheart_behavior`	`flutter pub add synheart_behavior`	iOS 12+ / Android API 21+	0.2.1	✅ Ready
Kotlin/Android	`ai.synheart:behavior`	Gradle: `implementation 'ai.synheart:behavior:0.4.1'`	Android API 21+	0.4.1	✅ Ready
Swift/iOS	SynheartBehavior	Swift Package: `.package(url: "https://github.com/synheart-ai/synheart-behavior-swift.git", from: "0.3.0")`	iOS 12.0+	0.3.0	✅ Ready

Architecture

Behavior SDKs are input layers: they capture interaction events and stream them out. Higher-level metrics (focus hint, distraction score, etc.) are computed downstream by the Synheart runtime when behavior is fed through Synheart Core.

User Interactions
   └─(scroll, tap, swipe, typing, notifications, calls)──► Synheart Behavior SDK
            [Event Collector] → [Session Aggregator]
                  │                       │
            [ML Motion Model]      BehaviorEvents + Summary
                  │                       │
            MotionState                   ▼
                  │                  Your App  (or Synheart Core
                  │                            for HSI fusion)
                  └──────────────────────►

Components:

Event Collectors: Capture scroll, tap, swipe, app_switch, notification, call, typing, and clipboard events.
Session Aggregator: Aggregates events into session-level summaries on-device.
Motion State Inference: On-device ML model for activity recognition (LAYING, MOVING, SITTING, STANDING).

Behavior is content-free: only timing and physical metadata. Use the SDK standalone for raw events, or feed it into Synheart Core to fuse with biosignals into HSI.

Quick Start Examples

import 'package:synheart_behavior/synheart_behavior.dart';

final behavior = await SynheartBehavior.initialize(
  config: const BehaviorConfig(
    enableInputSignals: true,
    enableAttentionSignals: true,
    enableMotionLite: true,
  ),
);

// Wrap app to enable gesture tracking
return behavior.wrapWithGestureDetector(
  MaterialApp(...),
);

// Listen to real-time events
behavior.onEvent.listen((event) {
  print('Event: ${event.eventType} at ${event.timestamp}');
});

// Start a session
final session = await behavior.startSession();

Full Flutter SDK Guide →

Use Cases

Focus and Distraction Apps

Monitor user focus in real-time:

final behavior = await SynheartBehavior.initialize(
  config: const BehaviorConfig(
    enableInputSignals: true,
    enableAttentionSignals: true,
  ),
);

behavior.onEvent.listen((event) {
  // Track interaction patterns
});

final session = await behavior.startSession();
// ... user interacts with app ...
final summary = await session.end();

if (summary.behavioralMetrics.focusHint > 0.7) {
  print('User is highly focused');
} else if (summary.behavioralMetrics.distractionScore > 0.6) {
  print('User appears distracted');
}

Digital Wellness Analytics

Track behavioral patterns throughout the day:

// Start session when user opens app
final session = await behavior.startSession();

// End session when user closes app
final summary = await session.end();

// Analyze session metrics
print('Interaction Intensity: ${summary.behavioralMetrics.interactionIntensity}');
print('Deep Focus Blocks: ${summary.behavioralMetrics.deepFocusBlocks.length}');
print('Task Switch Rate: ${summary.behavioralMetrics.taskSwitchRate}');

On-Demand Metrics for Time Ranges

Calculate metrics for specific time periods within a session:

// Calculate metrics for a custom time range
final metrics = await behavior.calculateMetricsForTimeRange(
  startTimestampSeconds: 1767688063,  // Unix timestamp in seconds
  endTimestampSeconds: 1767688130,     // Unix timestamp in seconds
  sessionId: 'SESS-1767688063415',     // Optional: session ID
);

// Access calculated metrics
print('Events in range: ${metrics['activity_summary']['total_events']}');
print('Interaction intensity: ${metrics['behavioral_metrics']['interaction_intensity']}');
print('Distraction score: ${metrics['behavioral_metrics']['behavioral_distraction_score']}');

// Motion state (if available)
if (metrics['motion_state'] != null) {
  print('Motion state: ${metrics['motion_state']['major_state']}');
}

Cognitive Load Estimation

Estimate cognitive load from interaction patterns:

final summary = await session.end();

// High interaction intensity + low fragmentation = high cognitive load
final cognitiveLoad = summary.behavioralMetrics.interactionIntensity *
                     (1 - summary.behavioralMetrics.fragmentedIdleRatio);

if (cognitiveLoad > 0.8) {
  // Suggest taking a break
}

Behavioral Metrics

Each BehaviorSessionSummary carries two metric bundles. Per-platform pages document the exact field types — the canonical set is small.

`BehavioralMetrics`

interactionIntensity (0–1): Overall interaction rate and engagement.
taskSwitchRate: Frequency of app switching.
taskSwitchCost: Penalty for fragmented switching.
idleTimeRatio (0–1) / activeTimeRatio (0–1).
fragmentedIdleRatio (0–1): Ratio of fragmented vs continuous idle periods.
burstiness: Temporal clustering of interaction events.
behavioralDistractionScore (0–1): Distraction proxy.
focusHint (0–1): Focus-quality proxy.
deepFocusBlocks: Sustained-engagement intervals.
notificationLoad: Notification pressure proxy.
scrollJitterRate: Scroll-pattern irregularity.

`TypingSessionSummary` (when typing events occurred)

typingSpeed, typingCadenceStability, typingCadenceVariability.
typingActivityRatio, typingGapRatio, typingBurstiness, typingInteractionIntensity.
clipboardActivityRate: (copy + paste + cut) / (typing taps + clipboard actions).
correctionRate: (backspace + delete) / (typing taps + backspace + delete).

All metrics are bounded and numerically stable.

Motion State Inference

When enableMotionLite is enabled, the SDK uses an on-device ML model (LinearSVC, one-vs-rest) to predict motion states from accelerometer / gyroscope features. The native (Kotlin) layer ships the model directly; the Flutter SDK forwards motion classification to the engine runtime instead of surfacing it on the session summary. Native (Kotlin / Swift) — on the session summary:

val summary = session.end()
summary.motionState?.let {
    println("Motion: ${it.majorState} (confidence ${it.confidence})")
}
// States: laying, moving, sitting, standing

Flutter — motion classification is performed by the Synheart runtime when behavior is fed through Synheart Core. It does not appear on BehaviorSessionSummary. Use Synheart.onHSIUpdate to read the runtime’s motion-state output.

API Features

The SDK provides the following functionality:

Feature	Flutter
BehaviorConfig	✅
SynheartBehavior	✅
BehaviorEvent	✅
BehaviorSession	✅
Motion State Inference	✅
Real-Time Event Streaming	✅
Session Management	✅
On-Demand Metrics Calculation	✅
Thread-Safe	✅
Automatic Session Ending	✅

Available SDKs

Flutter SDK

Cross-platform mobile apps (iOS + Android)

Kotlin/Android SDK

Native Android applications

Swift/iOS SDK

Native iOS applications

Each repo ships a runnable example in its example/ directory: Flutter · Kotlin · Swift.

Stability

Synheart Behavior is pre-1.0. Minor version bumps may include breaking API changes — pin exact versions in production, and read the CHANGELOG before upgrading. The three language SDKs are versioned independently (Flutter 0.2.x, Kotlin 0.4.x, Swift 0.3.x at time of writing); check each before bumping.

Privacy & Security

On-Device Processing: All behavioral inference happens locally
No Data Retention: Raw interaction events are not retained after processing
No Network Calls: No data is sent to external servers
Privacy-First Design: No built-in storage - you control what gets persisted
No Content Capture: No text, images, or semantic data collected
Event-Level Metadata Only: Only timing and physical metrics

Resources

Dart: synheart-behavior-flutter · pub.dev
Kotlin: synheart-behavior-kotlin · JitPack
Swift: synheart-behavior-swift

Citation

If you use this SDK in your research:

@software{synheart_behavior,
  title = {Synheart Behavior: Multi-platform SDK for on-device behavioral signal inference from digital interactions},
  author = {Synheart AI Team},
  year = {2025},
  version = {0.2.1},
  url = {https://github.com/synheart-ai/synheart-behavior-flutter}
}

​What is Synheart Behavior?

​Key Features

​On-Device Processing

​On-Demand Metrics Calculation

​Privacy-First Design

​Multi-Platform

​Architecture

​Quick Start Examples

​Use Cases

​Focus and Distraction Apps

​Digital Wellness Analytics

​On-Demand Metrics for Time Ranges

​Cognitive Load Estimation

​Behavioral Metrics

​BehavioralMetrics

​TypingSessionSummary (when typing events occurred)

​Motion State Inference

​API Features

​Available SDKs