Synheart Core SDK Overview - Synheart Documentation

What is Synheart Core SDK?

Synheart Core SDK is the unified integration point for developers who want to collect multimodal signals, process human state on-device via the Synheart runtime (native), and upload derived state snapshots (HSI 1.3 format) to the cloud with explicit user consent.

Not sure whether you need Core or just one of the standalone SDKs (synheart_wear, synheart_behavior, synheart_session)? Start with How it fits together — a one-page mental model of the stack with a mandatory-vs-optional table.

Key Features

Unified API

Single SDK: One integration point for all Synheart features
Modular Design: Enable only the modules you need
Consistent Interface: Same API patterns across all platforms
Multi-Module Support: Wear, Phone, Behavior, HSI Runtime, Consent, Cloud

On-Device Processing

HSI Runtime: Powered by the Synheart runtime (native) — on-device human state fusion
Privacy-First: All processing happens on-device
Designed for low overhead: targets sub-100ms HSI emission and a single-digit-percent CPU budget on a typical mid-range device

The numbers above are design targets, not measurements — actual footprint varies by device class and workload. Profile your app and read Synheart.runtimeDiagnostics() for live counters.

Multi-Platform Support

Platform	Language	Min OS	Status	Repository
Flutter/Dart	Dart	iOS 13+ / Android API 21+	Ready	synheart-core-flutter
Android	Kotlin	Android API 21+ (Android 5.0)	Ready	synheart-core-kotlin
iOS	Swift	iOS 13.0+	Ready	synheart-core-swift

Capability System

Access levels tied to app signature and tenant ID:

Module	Core	Extended	Research
Wear	Derived biosignals	Higher frequency	Raw streams
Phone	Motion, screen	Advanced app context	Full context
Behavior	Basic metrics	Extended metrics	Event-level streams
HSI Runtime	Basic state	Full embedding	Full fusion vectors
Cloud	Ingest (HSI 1.3)	Extended ingest	Lab session export

By default, third-party apps run under Core capabilities. Extended and Research capabilities are enabled only for first‑party Synheart apps and approved partners, since they may unlock higher-sensitivity data access and require additional privacy/security review and contractual controls.

Module System

The Core SDK consolidates all Synheart signal channels:

Synheart Core SDK
│
├── Wear Module
│      (HR, HRV, sleep, motion — derived signals only)
│
├── Phone Module
│      (motion, screen state, coarse app context)
│
├── Synheart Behavior (Module)
│      (interaction patterns: taps, scrolls, typing cadence)
│
├── HSI Runtime (On-device, Synheart Runtime)
│      - feature pipeline: raw signals → FeatureSet
│      - inference engine: HSV[] (6 cognitive/physio heads + MotionState) + 64D JL embedding
│      - flux: HSV[] → HSI 1.3 JSON envelope
│      - sliding-window state with configurable cadence
│
├── Consent Module
│      (permissions, masking, enforcement)
│
└── Cloud Connector
       (secure, consent-gated uploads)

Quick Start

Flutter/Dart

Flutter SDK Guide

Complete Flutter integration guide

Installation:

dependencies:
  synheart_core: ^0.0.4

Basic Usage:

import 'package:synheart_core/synheart_core.dart';

// Initialize Core SDK
await Synheart.initialize(
  userId: 'anon_user_123',
  config: SynheartConfig(
    allowUnsignedCapabilities: true,  // Use capabilityToken in production
  ),
);

// Subscribe to HSI updates (raw JSON from the Synheart Runtime)
Synheart.onHSIUpdate.listen((hsiJson) {
  print('HSI JSON: $hsiJson');
});

// Activate the features your app needs.
//   SynheartFeature.wear / .behavior / .phoneContext / .cloud
Synheart.activate(SynheartFeature.wear);
Synheart.activate(SynheartFeature.cloud);

Android (Kotlin)

Kotlin SDK Guide

Complete Android integration guide

Installation:

dependencies {
    implementation("ai.synheart:synheart-core:0.0.4")
}

Basic Usage:

import ai.synheart.core.Synheart
import ai.synheart.core.config.SynheartConfig
import ai.synheart.core.config.SynheartFeature

Synheart.initialize(
    context = context,
    userId = "anon_user_123",
    config = SynheartConfig(
        allowUnsignedCapabilities = true  // Use capabilityToken in production
    )
)

Synheart.onHSIUpdate.collect { hsiJson ->
    println("HSI JSON: $hsiJson")
}

Synheart.activate(SynheartFeature.WEAR)
Synheart.activate(SynheartFeature.CLOUD)

iOS (Swift)

Swift SDK Guide

Complete iOS integration guide

Installation:

dependencies: [
    .package(url: "https://github.com/synheart-ai/synheart-core-swift.git", from: "0.0.4")
]

Basic Usage:

import SynheartCore
import Combine

var cancellables = Set<AnyCancellable>()

try await Synheart.initialize(
    userId: "anon_user_123",
    config: SynheartConfig(
        allowUnsignedCapabilities: true  // Use capabilityToken in production
    )
)

Synheart.onHSIUpdate
    .sink { hsiJson in print("HSI JSON: \(hsiJson)") }
    .store(in: &cancellables)

Synheart.activate(.wear)
Synheart.activate(.cloud)

Privacy & security

Zero raw content: no text, microphone audio, URLs, or messages.
On-device processing: HSI inference runs locally on the host.
Consent-gated cloud: uploads require an explicit cloudUpload grant from the consent service.
Capability-enforced: feature access is bound to the consent token’s capability tier; the SDK silently downgrades responses when the tier is insufficient.

Performance targets

These are internal targets, not measured runtime numbers. Use Synheart.runtimeDiagnostics() and the uploadQueueLength / lastUploadAt getters to inspect what the SDK is doing in your app.

Available SDKs

Flutter SDK

Flutter integration

Kotlin SDK

Android/Kotlin integration

Swift SDK

iOS/Swift integration

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

Stability

Synheart Core is pre-1.0. Minor version bumps may include breaking API changes — pin exact versions (or a tight constraint like 0.0.x) in production, and read the CHANGELOG before upgrading. The HSI wire contract is versioned separately and follows its own policy.

Technical Documentation

Architecture

Module system and HSI Runtime

HSV Specification

The typed inference output of the Synheart Runtime — six heads + 64D JL embedding

Capability System

Access level enforcement

Consent System

Permission model and enforcement

Use cases

Mental health platforms

Subscribe to the typed HSIState stream and read the affect axis to monitor arousal/valence over time:

await Synheart.initialize(
  userId: userId,
  config: SynheartConfig(allowUnsignedCapabilities: true),
);
Synheart.activate(SynheartFeature.wear);

Synheart.onStateUpdate.listen((state) {
  final arousal = state.axes.affect?.arousalIndex;
  if (arousal != null && arousal > 0.7) {
    showHighArousalAlert();
  }
});

Productivity apps

The engagement axis tracks interaction stability over the session window:

await Synheart.initialize(
  userId: userId,
  config: SynheartConfig(allowUnsignedCapabilities: true),
);
Synheart.activate(SynheartFeature.behavior);

Synheart.onStateUpdate.listen((state) {
  final stability = state.axes.engagement?.engagementStability;
  if (stability != null && stability < 0.3) {
    suggestBreak();
  }
});

Research applications

Use a research-tier capability token to collect data with broader fidelity bounds, and activate the cloud connector to upload HSI snapshots:

await Synheart.initialize(
  userId: participantId,
  config: SynheartConfig(
    capabilityToken: researchToken,  // server-issued capability JWT
  ),
);
Synheart.activate(SynheartFeature.wear);
Synheart.activate(SynheartFeature.behavior);
Synheart.activate(SynheartFeature.cloud);

Next Steps

Quick Start

Get started in 5 minutes

Architecture Guide

Deep dive into the system

HSV Specification

Understand Synheart Core’s internal state model

Flutter SDK on GitHub

View source code

Synheart Wear - Wearable device integration
Synheart Behavior - Digital behavioral signal capture
Synheart Session - Time-bounded HR + behavioral sessions

​What is Synheart Core SDK?

​Key Features

​Unified API

​On-Device Processing

​Multi-Platform Support

​Capability System

​Module System

​Quick Start

​Flutter/Dart

Flutter SDK Guide

​Android (Kotlin)

Kotlin SDK Guide

​iOS (Swift)

Swift SDK Guide

​Privacy & security

​Performance targets

​Available SDKs

Flutter SDK

Kotlin SDK

Swift SDK

​Stability

​Technical Documentation

Architecture

HSV Specification

Capability System

Consent System

​Use cases

​Mental health platforms

​Productivity apps

​Research applications

​Next Steps

Quick Start

Architecture Guide

HSV Specification

Flutter SDK on GitHub

​Related Projects

What is Synheart Core SDK?

Key Features

Unified API

On-Device Processing

Multi-Platform Support

Capability System

Module System

Quick Start

Flutter/Dart

Android (Kotlin)

iOS (Swift)

Privacy & security

Performance targets

Available SDKs

Stability

Technical Documentation

Use cases

Mental health platforms

Productivity apps

Research applications

Next Steps

Related Projects