> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Synheart Behavior Overview

> On-device behavioral signal inference from digital interactions with privacy-first design

## 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.

```text theme={null}
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](/synheart-core/overview) to fuse with biosignals into HSI.

## Quick Start Examples

```dart theme={null}
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 →](/synheart-behavior/flutter)

## Use Cases

### Focus and Distraction Apps

Monitor user focus in real-time:

```dart theme={null}
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:

```dart theme={null}
// 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:

```dart theme={null}
// 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:

```dart theme={null}
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:**

```kotlin theme={null}
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

<CardGroup cols={3}>
  <Card title="Flutter SDK" icon="flutter" href="/synheart-behavior/flutter">
    Cross-platform mobile apps (iOS + Android)
  </Card>

  <Card title="Kotlin/Android SDK" icon="android" href="/synheart-behavior/kotlin">
    Native Android applications
  </Card>

  <Card title="Swift/iOS SDK" icon="apple" href="/synheart-behavior/swift">
    Native iOS applications
  </Card>
</CardGroup>

Each repo ships a runnable example in its `example/` directory:
[Flutter](https://github.com/synheart-ai/synheart-behavior-flutter/tree/main/example) ·
[Kotlin](https://github.com/synheart-ai/synheart-behavior-kotlin/tree/main/example) ·
[Swift](https://github.com/synheart-ai/synheart-behavior-swift/tree/main/Example).

## 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](https://github.com/synheart-ai/synheart-behavior-flutter) · [pub.dev](https://pub.dev/packages/synheart_behavior)
* **Kotlin**: [synheart-behavior-kotlin](https://github.com/synheart-ai/synheart-behavior-kotlin) · [JitPack](https://jitpack.io/#synheart-ai/synheart-behavior-kotlin)
* **Swift**: [synheart-behavior-swift](https://github.com/synheart-ai/synheart-behavior-swift)

## Citation

If you use this SDK in your research:

```bibtex theme={null}
@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}
}
```