Skip to main content

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.

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

​
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
Earlier docs published specific CPU/memory/battery figures. Those were design targets, not measurements — they varied by device class and workload. For the current build, profile your app and read Synheart.runtimeDiagnostics() for live counters.

​
Multi-Platform Support

PlatformLanguageStatusRepository
Flutter/DartDartReadysynheart-core-flutter
AndroidKotlinReadysynheart-core-kotlin
iOSSwiftReadysynheart-core-swift

​
Capability System

Access levels tied to app signature and tenant ID:
ModuleCoreExtendedResearch
WearDerived biosignalsHigher frequencyRaw streams
PhoneMotion, screenAdvanced app contextFull context
BehaviorBasic metricsExtended metricsEvent-level streams
HSI RuntimeBasic stateFull embeddingFull fusion vectors
CloudIngest (HSI 1.3)Extended ingestLab 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

​
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

GitHub

View source code