Synheart Core

Overview

The Synheart Core Swift SDK collects approved signals, processes human state on-device, and delivers HSI 1.3 state windows to native Apple applications. Key features:

iOS, macOS, watchOS, and tvOS support
On-device HSI processing
Typed and raw Combine publishers
Modular signal collection
Consent-aware local storage and cloud delivery

Installation

Add the Swift package

In Xcode, choose File → Add Package Dependencies and enter:

https://github.com/synheart-ai/synheart-core-swift.git

Or add the package dependency directly:

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

Install the native runtime

The Swift package provides the Apple integration layer. On-device HSI computation requires the native Synheart runtime.

synheart runtime install \
  --from /path/to/runtime-distribution \
  --project /path/to/YourApp.xcodeproj

See Install the runtime for runtime variants and linking instructions.

Stable and lab runtime variants require onnxruntime-c to be linked by the host application. Do not embed duplicate copies of the runtime or ONNX library.

Apple permissions

Add only the usage descriptions required by the features your app enables:

<key>NSHealthShareUsageDescription</key>
<string>This app uses approved health data to provide private human-state insights.</string>

<key>NSMotionUsageDescription</key>
<string>This app uses motion data to improve state context and signal quality.</string>

Enable HealthKit in Xcode when using wearable collection.

Quick start

The normal lifecycle is:

Initialize → Grant consent → Activate features → Start → Observe → Stop

import Combine
import SynheartCore

final class HumanStateModel: ObservableObject {
    @Published private(set) var state: HSIState?
    private var cancellables = Set<AnyCancellable>()

    func start(subjectId: String) async throws {
        let config = SynheartConfig(
            appId: "com.example.myapp",
            subjectId: subjectId,
            appVersion: "1.0.0",
            appName: "My App",
            category: "wellness",
            developer: "Example, Inc.",
            allowUnsignedCapabilities: true
        )

        try await Synheart.initialize(
            config: config,
            userId: subjectId,
            autoStart: false
        )

        try await Synheart.grantConsent("biosignals")
        Synheart.activate(.wear)

        Synheart.onStateUpdate
            .receive(on: DispatchQueue.main)
            .sink { [weak self] in self?.state = $0 }
            .store(in: &cancellables)

        try await Synheart.startSession()
    }

    func stop() async throws {
        try await Synheart.stopSession()
    }

    func dispose() async throws {
        try await Synheart.dispose()
    }
}

allowUnsignedCapabilities: true is for local development only. Production apps must use a verified capability configuration.

Production configuration

Use pseudonymous subject identifiers and the service origins issued for your environment. Do not embed API secrets or shared signing keys in the application.

let serviceOrigin = "https://api.synheart.ai"
let appId = "com.example.myapp"
let subjectId = "subject_7f8a..."
let deviceId = UUID().uuidString

let config = SynheartConfig(
    appId: appId,
    subjectId: subjectId,
    appVersion: "1.0.0",
    appName: "My App",
    category: "wellness",
    developer: "Example, Inc.",
    deviceId: deviceId,
    storage: StorageConfig(enabled: true, retentionDays: 30),
    sync: SyncConfig(enabled: true, baseUrl: serviceOrigin),
    cloudConfig: CloudConfig(
        subjectId: subjectId,
        instanceId: deviceId,
        orgId: "org_example",
        baseUrl: serviceOrigin
    ),
    consentConfig: ConsentConfig(
        consentServiceUrl: serviceOrigin,
        appId: appId,
        deviceId: deviceId,
        userId: subjectId
    ),
    deviceAuthConfig: DeviceAuthConfig(
        authBaseUrl: serviceOrigin,
        packageName: appId
    )
)

Production cloud requests use registered device identity. Ensure registration and cloud consent are ready before enabling cloud delivery:

_ = await Synheart.ensureDeviceAuthRegistered()
let consentReady = await Synheart.ensureCloudConsentReady()

if consentReady {
    Synheart.activate(.cloud)
}

A feature operates only when it is activated, consented, allowed by capability policy, and an eligible session is active.

Feature	Required consent	Purpose
`.wear`	`biosignals`	Approved wearable signals
`.behavior`	`behavior`	Interaction telemetry
`.phoneContext`	`phoneContext`	Motion and device context
`.cloud`	`cloudUpload`	HSI cloud delivery
`.synsync`	`cloudUpload`	Cross-device synchronization
`.syni`	`syni`	Entitled Syni services

try await Synheart.grantConsent("biosignals")
Synheart.activate(.wear)

// Revoke it later when requested by the user.
try await Synheart.revokeConsent("biosignals")

Consent revocation stops future use of that consent. It is separate from deleting previously retained data.

HSI state updates

Use the typed publisher for application logic:

Synheart.onStateUpdate
    .sink { state in
        print(state.hasDataBasis)
    }
    .store(in: &cancellables)

Use the raw publisher when you need the complete HSI 1.3 payload:

Synheart.onHSIUpdate
    .sink { rawJson in
        print(rawJson)
    }
    .store(in: &cancellables)

currentHSIState provides the latest typed value and currentState provides the latest raw JSON. HSI is emitted in windows, not for every sensor sample, so applications should show a collecting state while waiting for the first valid window. See the HSI specification for the wire format.

Cloud delivery and diagnostics

Cloud delivery requires cloud configuration, consent, feature activation, device registration, and network availability.

let queue = Synheart.uploadQueueStatus
let result = await Synheart.flushUploads(requireConsent: true)

print(queue)
print(result)

For runtime and collection troubleshooting:

print(CoreRuntimeBridge.symbolDiagnostics)
print(CoreRuntimeBridge.dependencyDiagnostics)
print(Synheart.runtimeVersion ?? "unavailable")

for (module, reason) in Synheart.collectionStartupFailures {
    print("\(module): \(reason)")
}

A zero-length queue does not by itself confirm successful ingestion. Inspect the flush result and the latest upload diagnostics.

Advanced capabilities

The Swift SDK also exposes the following runtime-backed features. Availability depends on the linked runtime and the application’s capability policy.

Capability	Main APIs
Sync spaces	Create, pair, join, recover, inspect, leave, and delete a space
Baselines	Hydrate, inspect, and securely import or export baseline envelopes
Scores	Compute sleep, recovery, and readiness scores
Runtime inputs	Push RR batches, vendor HRV, vitals, and wearable events
History	Read local HSI history or fetch permitted cloud windows
Personalization	Supply task, focus, and workout context
Privacy	Request and monitor customer-data deletion
Syni	Access entitled Syni cloud operations
Independent instances	Run isolated native instances for advanced tooling and research

Pairing tokens, recovery keys, and exported baseline material are sensitive. Keep them out of logs and analytics and store them using platform-protected storage.

Error handling

do {
    try await Synheart.initialize(
        config: config,
        userId: subjectId,
        autoStart: false
    )
} catch SynheartError.runtimeIncompatible(let missingSymbols) {
    print("Runtime mismatch: \(missingSymbols)")
} catch SynheartError.runtimeDependencyMissing(let dependencies) {
    print("Missing dependency: \(dependencies)")
} catch SynheartError.capabilityTokenRequired {
    print("Verified device authorization is required")
} catch {
    print(error.localizedDescription)
}

Troubleshooting

Symptom	Check first
Initialization fails	Configuration, embedded runtime, and native dependencies
Session will not start	Activation, consent, capability, and device role
No HSI appears	Active session, incoming signals, and window duration
HSI has no data basis	Signal coverage, provenance, quality, and baseline status
Upload does not complete	Device registration, subject binding, consent, origin, and network
Sync is unavailable	Sync readiness and the linked runtime’s supported capabilities

Get Started

Setup

CLI

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

Synheart Core - Swift SDK

Overview

Installation

Add the Swift package

Install the native runtime

Apple permissions

Quick start

Production configuration

HSI state updates

Cloud delivery and diagnostics

Advanced capabilities

Error handling

Troubleshooting

Resources

​Overview

​Installation

​Add the Swift package

​Install the native runtime

​Apple permissions

​Quick start

​Production configuration

​Features and consent

​HSI state updates

​Cloud delivery and diagnostics

​Advanced capabilities

​Error handling

​Troubleshooting

​Resources

Overview

Installation

Add the Swift package

Install the native runtime

Apple permissions

Quick start

Production configuration

Features and consent

HSI state updates

Cloud delivery and diagnostics

Advanced capabilities

Error handling

Troubleshooting

Resources