> ## 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 - Android/Kotlin SDK

> Unified SDK for human-state intelligence in Android applications

## Overview

The Synheart Core Android/Kotlin SDK provides a unified API for collecting HSI-compatible data, processing human state on-device, and generating focus/emotion signals in native Android applications.

**Key Features:**

* Native Android support
* On-device HSI Runtime
* Kotlin Coroutines and Flow integration
* Real-time state updates
* Privacy-first architecture

## Installation

Add to your `build.gradle` (app level):

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

## Configuration

### AndroidManifest.xml

Add required permissions:

```xml theme={null}
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required permissions -->
    <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />

    <!-- Health Connect Permissions (if using Wear module) -->
    <uses-permission android:name="android.permission.health.READ_HEART_RATE"/>
    <uses-permission android:name="android.permission.health.READ_HEART_RATE_VARIABILITY"/>

    <application>
        <!-- Your application configuration -->
    </application>
</manifest>
```

## Basic Usage

### Initialize the SDK

```kotlin theme={null}
import ai.synheart.core.Synheart
import ai.synheart.core.SynheartConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

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

### Subscribe to HSI Updates

```kotlin theme={null}
import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

lifecycleScope.launch {
    Synheart.onHSIUpdate.collect { hsiJson ->
        Log.d("HSI", "HSI JSON: $hsiJson")
    }
}
```

### Activate features

The `SynheartFeature` enum gates collection by feature. Activation is
one of four conditions a feature needs (consent, capability tier, an
active session — see [Capability System](/synheart-core/capability-system)).

```kotlin theme={null}
// Available features:
//   SynheartFeature.WEAR          — biosignals from wearables
//   SynheartFeature.BEHAVIOR      — interaction telemetry
//   SynheartFeature.PHONE_CONTEXT — motion / screen / app context
//   SynheartFeature.CLOUD         — HSI upload connector

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

// Stop a feature without uninitializing the SDK.
Synheart.deactivate(SynheartFeature.CLOUD)
```

State signals (focus, emotion, recovery, etc.) are not separate
features — they're axes inside the HSI JSON emitted by
`Synheart.onHSIUpdate`. Parse the JSON to read them.

## Complete example

```kotlin theme={null}
import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.*
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.lifecycle.lifecycleScope
import ai.synheart.core.Synheart
import ai.synheart.core.SynheartConfig
import ai.synheart.core.config.SynheartFeature
import kotlinx.coroutines.launch

class HumanStateActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lifecycleScope.launch {
            Synheart.initialize(
                context = applicationContext,
                userId = "user_123",
                config = SynheartConfig(allowUnsignedCapabilities = true),
            )
            Synheart.activate(SynheartFeature.WEAR)
            Synheart.activate(SynheartFeature.BEHAVIOR)
        }
        setContent { HumanStateMonitor() }
    }
}

@Composable
fun HumanStateMonitor() {
    var hsiJson by remember { mutableStateOf<String?>(null) }
    LaunchedEffect(Unit) {
        Synheart.onHSIUpdate.collect { hsiJson = it }
    }
    Scaffold(topBar = { TopAppBar(title = { Text("Human State") }) }) { p ->
        Column(Modifier.padding(p).padding(16.dp)) {
            Text("HSI: ${hsiJson?.take(100) ?: "Waiting…"}")
        }
    }
}
```

## HSI snapshot reference

The HSI Runtime emits raw JSON strings via `Synheart.onHSIUpdate`
(`Flow<String>`). Parse the JSON to extract fields like the affect /
engagement / activity / context axes. See the
[HSI specification](/hsi/overview) for the wire format.

## Cloud connector

```kotlin theme={null}
// Enable cloud sync (requires cloudConfig in SynheartConfig and a
// granted cloudUpload consent).
Synheart.activate(SynheartFeature.CLOUD)

// Pause uploads without tearing down the SDK.
Synheart.deactivate(SynheartFeature.CLOUD)
```

## Configuration options

```kotlin theme={null}
val config = SynheartConfig(
    allowUnsignedCapabilities = true,  // use capabilityToken in production

    // Cloud configuration (optional).
    cloudConfig = CloudConfig(
        appId = "your_app_id",
        subjectId = "user_123",
        instanceId = "device_abc",
        baseUrl = "https://api.synheart.ai",
    ),

    // Capability JWT (optional, for extended/research access).
    capabilityToken = null,
)

Synheart.initialize(
    context = context,
    userId = "user_123",
    config = config,
)
```

Authentication for cloud uploads is hardware-backed device ECDSA
(Android Keystore) per
RFC-AUTH-MOBILE-0001.
The runtime owns request signing via the host's `synheart-auth`
integration — `CloudConfig` does **not** carry shared secrets or
HMAC keys. See [Synheart Auth overview](/synheart-auth/overview) for
the device-identity flow.

## Diagnostics & upload inspection

Use the diagnostics surface to inspect runtime state and force a
flush when consent and network are eligible.

```kotlin theme={null}
// Live counters / last-error strings.
val diag = Synheart.runtimeDiagnostics()
Log.d("Synheart", diag.toString())

// Synchronous getters — safe to read from UI code.
val depth = Synheart.uploadQueueLength
val lastMs = Synheart.lastIngestSuccessAtMs

// Manually flush queued snapshots when eligible.
val result = Synheart.ingestion.flushIfEligible()
```

## Error Handling

```kotlin theme={null}
try {
    Synheart.initialize(
        context = context,
        userId = userId,
        config = config
    )
} catch (e: PermissionDeniedException) {
    Log.e("Synheart", "Permission denied: ${e.message}")
} catch (e: InitializationException) {
    Log.e("Synheart", "Initialization failed: ${e.message}")
} catch (e: SynheartException) {
    Log.e("Synheart", "SDK error: ${e.message}")
}
```

## Privacy & Consent

```kotlin theme={null}
// Coarse status — granted | pending | expired | denied
val status = Synheart.consentStatus()

// Per-type check (wire strings: biosignals, phoneContext, behavior,
// cloudUpload, vendorSync, research)
val canUpload = Synheart.hasConsent("cloudUpload")
val canRead   = Synheart.hasConsent("biosignals")

// Request consent — opens the cloud consent flow when configured.
val token = Synheart.requestConsent()

if (Synheart.hasConsent("cloudUpload")) {
    Synheart.activate(SynheartFeature.CLOUD)
}

// Revoke a single type or everything
Synheart.revokeConsentType("cloudUpload")
Synheart.revokeConsent()
```

See [Consent System](/synheart-core/consent-system) for the full consent model.

## API Reference

### `Synheart`

Main SDK object.

**Methods:**

| Method                | Description                 | Returns |
| --------------------- | --------------------------- | ------- |
| `initialize()`        | Initialize the SDK          | `Unit`  |
| `activate(feature)`   | Activate a feature module   | `Unit`  |
| `deactivate(feature)` | Deactivate a feature module | `Unit`  |
| `dispose()`           | Cleanup resources           | `Unit`  |

**Flows:**

| Flow          | Type           | Description                                |
| ------------- | -------------- | ------------------------------------------ |
| `onHSIUpdate` | `Flow<String>` | Raw HSI 1.3 JSON, emitted per window close |

## Resources

* **Repository**: [synheart-core-kotlin](https://github.com/synheart-ai/synheart-core-kotlin)
* **Maven**: [ai.synheart:core-sdk](https://mvnrepository.com/artifact/ai.synheart/core-sdk)
* **API Docs**: [API Reference](https://synheart-ai.github.io/synheart-core-kotlin/)
* **Issues**: [GitHub Issues](https://github.com/synheart-ai/synheart-core-kotlin/issues)

## Related Documentation

* [HSV Specification](/synheart-core/hsv-specification) - Understand Synheart Core’s internal state model
* [Architecture](/synheart-core/architecture) - Deep dive into the system
* [Capability System](/synheart-core/capability-system) - Access levels and permissions