> ## 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 Core SDK Overview

> Unified SDK for human-state intelligence — single integration point for all Synheart features

## 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](/hsi/overview)) to the cloud with explicit user consent.

<Note>
  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](/guides/how-it-fits-together) — a one-page mental model of the stack with a mandatory-vs-optional table.
</Note>

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

<Note>
  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.
</Note>

### Multi-Platform Support

| Platform         | Language | Min OS                        | Status | Repository                                                                    |
| ---------------- | -------- | ----------------------------- | ------ | ----------------------------------------------------------------------------- |
| **Flutter/Dart** | Dart     | iOS 13+ / Android API 21+     | Ready  | [synheart-core-flutter](https://github.com/synheart-ai/synheart-core-flutter) |
| **Android**      | Kotlin   | Android API 21+ (Android 5.0) | Ready  | [synheart-core-kotlin](https://github.com/synheart-ai/synheart-core-kotlin)   |
| **iOS**          | Swift    | iOS 13.0+                     | Ready  | [synheart-core-swift](https://github.com/synheart-ai/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:

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

<Card title="Flutter SDK Guide" icon="flutter" href="/synheart-core/flutter">
  Complete Flutter integration guide
</Card>

**Installation:**

```yaml theme={null}
dependencies:
  synheart_core: ^0.0.4
```

**Basic Usage:**

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

<Card title="Kotlin SDK Guide" icon="android" href="/synheart-core/kotlin">
  Complete Android integration guide
</Card>

**Installation:**

```kotlin theme={null}
dependencies {
    implementation("ai.synheart:synheart-core:0.0.4")
}
```

**Basic Usage:**

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

<Card title="Swift SDK Guide" icon="apple" href="/synheart-core/swift">
  Complete iOS integration guide
</Card>

**Installation:**

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/synheart-ai/synheart-core-swift.git", from: "0.0.4")
]
```

**Basic Usage:**

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

<CardGroup cols={3}>
  <Card title="Flutter SDK" icon="flutter" href="/synheart-core/flutter">
    Flutter integration
  </Card>

  <Card title="Kotlin SDK" icon="android" href="/synheart-core/kotlin">
    Android/Kotlin integration
  </Card>

  <Card title="Swift SDK" icon="apple" href="/synheart-core/swift">
    iOS/Swift integration
  </Card>
</CardGroup>

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

## 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](/hsi/overview#versioning-policy).

## Technical Documentation

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/synheart-core/architecture">
    Module system and HSI Runtime
  </Card>

  <Card title="HSV Specification" icon="brain" href="/synheart-core/hsv-specification">
    The typed inference output of the Synheart Runtime — six heads + 64D JL embedding
  </Card>

  <Card title="Capability System" icon="shield" href="/synheart-core/capability-system">
    Access level enforcement
  </Card>

  <Card title="Consent System" icon="user-shield" href="/synheart-core/consent-system">
    Permission model and enforcement
  </Card>
</CardGroup>

## Use cases

### Mental health platforms

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

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

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

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

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Get started in 5 minutes
  </Card>

  <Card title="Architecture Guide" icon="diagram-project" href="/synheart-core/architecture">
    Deep dive into the system
  </Card>

  <Card title="HSV Specification" icon="brain" href="/synheart-core/hsv-specification">
    Understand Synheart Core’s internal state model
  </Card>

  <Card title="Flutter SDK on GitHub" icon="github" href="https://github.com/synheart-ai/synheart-core-flutter">
    View source code
  </Card>
</CardGroup>

## Related Projects

* [Synheart Wear](/synheart-wear/overview) - Wearable device integration
* [Synheart Behavior](/synheart-behavior/overview) - Digital behavioral signal capture
* [Synheart Session](/synheart-session/overview) - Time-bounded HR + behavioral sessions