Skip to main content

​
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): 
dependencies {
    implementation("ai.synheart:core-sdk:1.0.0")
}

​
Configuration

​
AndroidManifest.xml

Add required permissions: 
<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

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(
                enableWear = true,
                enablePhone = true,
                enableBehavior = true
            )
        )
    }
}

​
Subscribe to HSI Updates

import kotlinx.coroutines.flow.collect
import kotlinx.coroutines.launch

lifecycleScope.launch {
    Synheart.onHSIUpdate.collect { hsi ->
        // Affect indicators
        Log.d("HSI", "Arousal Index: ${hsi.affect.arousalIndex}")
        Log.d("HSI", "Valence Index: ${hsi.affect.valenceIndex}")

        // Engagement indicators
        Log.d("HSI", "Engagement Stability: ${hsi.engagement.engagementStability}")
        Log.d("HSI", "Cognitive Load: ${hsi.engagement.cognitiveLoad}")
    }
}

​
Enable Interpretation Modules

// Enable Focus tracking
lifecycleScope.launch {
    Synheart.enableFocus()

    Synheart.onFocusUpdate.collect { focus ->
        Log.d("Focus", "Score: ${focus.estimate.score}")
        Log.d("Focus", "State: ${focus.state}")
    }
}

// Enable Emotion tracking
lifecycleScope.launch {
    Synheart.enableEmotion()

    Synheart.onEmotionUpdate.collect { emotion ->
        Log.d("Emotion", "Stress Index: ${emotion.stressIndex}")
        Log.d("Emotion", "Primary Emotion: ${emotion.primaryEmotion}")
    }
}

​
Enable Cloud Sync

lifecycleScope.launch {
    Synheart.enableCloud(
        config = CloudConfig(
            uploadInterval = Duration.ofMinutes(5),
            requireWifi = true
        )
    )

    Synheart.onCloudSync.collect { sync ->
        Log.d("Cloud", "Synced ${sync.snapshotCount} snapshots")
    }
}

​
Complete Example

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.model.*
import kotlinx.coroutines.launch

class HumanStateActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Initialize SDK
        lifecycleScope.launch {
            initializeSynheart()
        }

        setContent {
            HumanStateMonitor()
        }
    }

    private suspend fun initializeSynheart() {
        Synheart.initialize(
            context = applicationContext,
            userId = "user_123",
            config = SynheartConfig(
                enableWear = true,
                enablePhone = true,
                enableBehavior = true
            )
        )

        Synheart.enableFocus()
        Synheart.enableEmotion()
    }
}

@Composable
fun HumanStateMonitor() {
    var hsiState by remember { mutableStateOf<HSIState?>(null) }
    var focusEstimate by remember { mutableStateOf<FocusEstimate?>(null) }
    var emotionState by remember { mutableStateOf<EmotionState?>(null) }

    LaunchedEffect(Unit) {
        launch {
            Synheart.onHSIUpdate.collect { hsiState = it }
        }
        launch {
            Synheart.onFocusUpdate.collect { focusEstimate = it.estimate }
        }
        launch {
            Synheart.onEmotionUpdate.collect { emotionState = it }
        }
    }

    Scaffold(
        topBar = {
            TopAppBar(title = { Text("Human State Monitor") })
        }
    ) { padding ->
        Column(
            modifier = Modifier
                .fillMaxSize()
                .padding(padding)
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            // HSI State Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("HSI State", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    hsiState?.let { hsi ->
                        Text("Arousal: ${"%.2f".format(hsi.affect.arousalIndex)}")
                        Text("Valence: ${"%.2f".format(hsi.affect.valenceIndex)}")
                        Text("Engagement: ${"%.2f".format(hsi.engagement.engagementStability)}")
                    } ?: Text("Waiting for data...")
                }
            }

            // Focus Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("Focus", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    focusEstimate?.let { focus ->
                        Text("Score: ${"%.2f".format(focus.score)}")
                        Text("Confidence: ${"%.2f".format(focus.confidence)}")
                        LinearProgressIndicator(
                            progress = focus.score.toFloat(),
                            modifier = Modifier.fillMaxWidth()
                        )
                    } ?: Text("Waiting for data...")
                }
            }

            // Emotion Card
            Card(modifier = Modifier.fillMaxWidth()) {
                Column(modifier = Modifier.padding(16.dp)) {
                    Text("Emotion", style = MaterialTheme.typography.titleLarge)
                    Spacer(modifier = Modifier.height(8.dp))
                    emotionState?.let { emotion ->
                        Text("Stress: ${"%.2f".format(emotion.stressIndex)}")
                        Text("Energy: ${"%.2f".format(emotion.energyLevel)}")
                        Text("State: ${emotion.primaryEmotion}")
                    } ?: Text("Waiting for data...")
                }
            }
        }
    }
}

​
HSI State Reference

data class HSIState(
    val affect: AffectState,
    val engagement: EngagementState,
    val window: TimeWindow,
    val stateEmbedding: List<Double>,
    val timestamp: Instant
)

data class AffectState(
    val arousalIndex: Double,    // 0.0-1.0
    val valenceIndex: Double,    // -1.0 to 1.0
    val intensity: Double        // 0.0-1.0
)

data class EngagementState(
    val engagementStability: Double, // 0.0-1.0
    val cognitiveLoad: Double,       // 0.0-1.0
    val attentionLevel: Double       // 0.0-1.0
)

​
Focus Module

// Enable focus tracking
Synheart.enableFocus()

lifecycleScope.launch {
    Synheart.onFocusUpdate.collect { focus ->
        when (focus.state) {
            FocusState.FOCUSED -> showNotification("You're in the zone!")
            FocusState.DISTRACTED -> showNotification("Take a break?")
            FocusState.DEEP_FOCUS -> showNotification("Deep focus detected")
            FocusState.NEUTRAL -> { /* No action */ }
        }
    }
}

// Disable when done
Synheart.disableFocus()

​
Emotion Module

// Enable emotion tracking
Synheart.enableEmotion()

lifecycleScope.launch {
    Synheart.onEmotionUpdate.collect { emotion ->
        if (emotion.stressIndex > 0.7) {
            triggerStressAlert()
        }

        Log.d("Emotion", "Stress: ${emotion.stressIndex}")
        Log.d("Emotion", "Energy: ${emotion.energyLevel}")
        Log.d("Emotion", "Primary: ${emotion.primaryEmotion}")
    }
}

// Disable when done
Synheart.disableEmotion()

​
Cloud Connector

// Enable cloud sync
Synheart.enableCloud(
    config = CloudConfig(
        uploadInterval = Duration.ofMinutes(5),
        requireWifi = true,
        batchSize = 100
    )
)

lifecycleScope.launch {
    Synheart.onCloudSync.collect { sync ->
        when (sync.status) {
            SyncStatus.SUCCESS -> {
                Log.d("Cloud", "Uploaded ${sync.snapshotCount} snapshots")
            }
            SyncStatus.FAILED -> {
                Log.e("Cloud", "Sync failed: ${sync.error}")
            }
            SyncStatus.IN_PROGRESS -> {
                Log.d("Cloud", "Syncing...")
            }
        }
    }
}

// Manual sync trigger
Synheart.syncNow()

// Disable cloud sync
Synheart.disableCloud()

​
Configuration Options

val config = SynheartConfig(
    // Module enables
    enableWear = true,
    enablePhone = true,
    enableBehavior = true,

    // Update intervals
    hsiUpdateInterval = Duration.ofSeconds(30),

    // Capability level (default: CORE)
    capabilityLevel = CapabilityLevel.CORE,

    // Debug mode
    debug = false
)

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

​
Error Handling

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}")
}

// Check consent status
val consentStatus = Synheart.getConsentStatus()
Log.d("Consent", "Wear module: ${consentStatus.wear}")
Log.d("Consent", "Cloud sync: ${consentStatus.cloud}")

// Request consent
val granted = Synheart.requestConsent(
    modules = listOf(ConsentModule.WEAR, ConsentModule.CLOUD),
    reason = "We need access to provide personalized insights"
)

if (granted) {
    Synheart.enableCloud()
}

// Revoke consent
Synheart.revokeConsent(ConsentModule.CLOUD)

​
API Reference

​
Synheart

Main SDK object. Methods:
MethodDescriptionReturns
initialize()Initialize the SDKUnit
enableFocus()Enable focus moduleUnit
enableEmotion()Enable emotion moduleUnit
enableCloud()Enable cloud syncUnit
dispose()Cleanup resourcesUnit
Flows:
FlowTypeDescription
onHSIUpdateFlow<HSIState>HSI state updates
onFocusUpdateFlow<FocusUpdate>Focus estimates
onEmotionUpdateFlow<EmotionState>Emotion states
onCloudSyncFlow<SyncEvent>Cloud sync events

​
Resources

Author: Israel Goytom