Synheart Core SDK - Flutter #

Synheart Core SDK is the single, unified integration point for developers who want to collect HSI-compatible data, process human state on-device, generate focus/emotion signals, and integrate with Syni.

📦 SDK Implementations: This is the Flutter/Dart implementation. For documentation and other platforms, see the repositories below.

📦 Repository Structure #

The Synheart Core SDK is organized across multiple repositories:

Overview #

The Synheart Core SDK consolidates all Synheart signal channels into one SDK:

• Wear Module → Biosignals (HR, HRV, sleep, motion)
• Phone Module → Motion + context signals
• Behavior Module → Digital interaction patterns
• HSI Runtime → Signal fusion + state computation
• Consent Module → User permission management
• Cloud Connector → Secure HSI snapshot uploads
• Syni Hooks → LLM conditioning

Key principle:

One SDK, many modules, unified human-state model

Architecture #

Core Principle #

HSI represents human state.

Interpretation is downstream and optional.

The Core SDK strictly separates:

• Representation (HSI) - State axes, indices, embeddings
• Interpretation (Focus, Emotion) - Optional, explicit modules
• Application logic - Your app

Core Modules #

1. Capabilities Module - Feature gating (core/extended/research)
2. Consent Module - User permission management
3. Wear Module - Biosignal collection from wearables
4. Phone Module - Device motion and context signals
5. Behavior Module - User-device interaction patterns
6. HSI Runtime - Signal fusion and state representation
7. Cloud Connector - Secure HSI snapshot uploads

Optional Interpretation Modules #

• Synheart Focus - Focus/engagement estimation (optional, explicit enable)
• Synheart Emotion - Affect modeling (optional, explicit enable)

Data Flow #

Wear, Phone, Behavior Modules
    ↓
HSI Runtime
    ↓
HSI (State Representation)
    ↓
Optional: Focus Module → Focus Estimates
Optional: Emotion Module → Emotion Estimates

Usage #

Basic Usage #

The Core SDK provides HSI (Human State Interface) as the core state representation, with optional interpretation modules for Focus and Emotion:

import 'package:synheart_core/synheart_core.dart';

// Initialize the Core SDK
await Synheart.initialize(
  userId: 'anon_user_123',
  config: SynheartConfig(
    enableWear: true,
    enablePhone: true,
    enableBehavior: true,
  ),
);

// Subscribe to HSI updates (core state representation)
Synheart.onHSIUpdate.listen((hsi) {
  print('Arousal Index: ${hsi.affect.arousalIndex}');
  print('Engagement Stability: ${hsi.engagement.engagementStability}');
});

// Optional: Enable interpretation modules
await Synheart.enableFocus();
Synheart.onFocusUpdate.listen((focus) {
  print('Focus Score: ${focus.estimate.score}');
});

await Synheart.enableEmotion();
Synheart.onEmotionUpdate.listen((emotion) {
  print('Stress Index: ${emotion.stressIndex}');
});

// Optional: Enable cloud sync (requires consent)
await Synheart.enableCloud();

Consent Management #

The SDK requires explicit user consent for data collection:

// Grant consent for specific data types
await Synheart.grantConsent('biosignals');
await Synheart.grantConsent('behavior');
await Synheart.grantConsent('phoneContext');

// Check consent status
bool hasConsent = await Synheart.hasConsent('biosignals');

// Revoke consent
await Synheart.revokeConsent('biosignals');

// Alternatively, update all consents at once
await Synheart.updateConsent(ConsentSnapshot(
  biosignals: true,
  behavior: true,
  motion: true,
  cloudUpload: false,  // User must explicitly opt-in
  syni: false,
));

Prerequisites #

Wearable Data Collection #

The Core SDK uses the synheart_wear package for wearable data collection. This package handles all device integrations (Apple Watch, Fitbit, Garmin, etc.) and provides a unified API.

iOS - HealthKit Permissions #

The synheart_wear package handles HealthKit permissions automatically. Add the following to your Info.plist:

<key>NSHealthShareUsageDescription</key>
<string>This app needs access to your health data to monitor your wellbeing</string>
<key>NSHealthUpdateUsageDescription</key>
<string>This app needs to update your health data</string>

Android - Health Connect #

The synheart_wear package handles Health Connect permissions automatically. Add permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>
<uses-permission android:name="android.permission.health.READ_HEART_RATE"/>

Supported Devices #

The Core SDK supports all devices that synheart_wear supports.

Privacy & Security #

• All processing is on-device by default
• No raw biosignals leave the device without explicit consent
• Cloud sync uses aggregated HSV only
• HSI is strictly non-medical; no diagnoses or clinical labels

📚 Documentation #

For complete documentation, see the main Synheart Core repository:

• HSI Specification - State axes, indices, and embeddings
• Consent System - Permission model and enforcement
• Cloud Protocol - Secure ingestion protocol

Dart-Specific Documentation #

• ARCHITECTURE - Dart implementation architecture
• HSV Technical Spec - HSV data structure details

👥 Contributing #

We welcome contributions! Here's how to get started:

1. Read the guides:
   • CONTRIBUTING.md - Contribution guidelines

📋 Module Overview #

The Synheart Core SDK consists of 7 core modules:

1. Capabilities Module - Feature gating (core/extended/research)
2. Consent Module - User permission management
3. Wear Module - Biosignal collection from wearables
4. Phone Module - Device motion and context signals
5. Behavior Module - User-device interaction patterns
6. HSI Runtime - Signal fusion and state computation
7. Cloud Connector - Secure HSI snapshot uploads

See ARCHITECTURE for detailed implementation specifications.

🔒 Privacy & Security #

• All processing is on-device by default
• No raw biosignals leave the device without explicit consent
• Cloud sync uses aggregated HSV only
• HSI is strictly non-medical; no diagnoses or clinical labels
• Zero raw data policy enforced throughout

📄 License #

Apache 2.0 License - see LICENSE for details.

Copyright 2025 Synheart AI Inc.

👤 Author #

Synheart Teeam <3

Patent Pending Notice #

This project is provided under an open-source license. Certain underlying systems, methods, and architectures described or implemented herein may be covered by one or more pending patent applications.

Nothing in this repository grants any license, express or implied, to any patents or patent applications, except as provided by the applicable open-source license.