How it fits together

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.

If you’re trying to figure out which pieces of Synheart your app actually needs, read this page first. Everything else in the docs assumes the shape laid out below.

​

The mental model

Synheart is a stack with four layers. Most apps use one or two of them; very few use all four. The dotted arrows are optional paths. Solid arrows are the default flow for an app using Synheart Core.

​

What each layer does

1. Sensors are the data sources. You bring these — a paired wearable, the phone the app is running on, the user typing or scrolling inside your app. Synheart does not capture any of this without an SDK in your app code. 2. SDKs are the per-language entry points that capture data. They live in your app process. Four of them ship today:

• Synheart Wear — normalises HR, HRV, sleep, motion from any supported wearable into one API.
• Synheart Behavior — content-free interaction events (taps, scrolls, typing cadence, app context).
• Synheart Session — watch-driven session capture with pluggable biosignal and behavior providers. Use this when the watch is computing session frames locally and streaming them to the phone.
• Synheart Core — the fusion SDK. Consumes Wear + Behavior + phone signals and produces a single human-state stream.

Each standalone SDK can be used on its own. You only need Core if you want fused human-state output. 3. The Synheart Runtime is a native binary (the artifact you install with synheart install runtime) that does the heavy lifting: features → inference → packing into HSI. Only Synheart Core links to it. The standalone SDKs don’t. See Architecture for the full pipeline. 4. Outputs are how data leaves the runtime:

• Your app is always an output. The SDK exposes HSI envelopes and typed projections via reactive streams (e.g. Synheart.onHSIUpdate / onStateUpdate).
• Syni is the optional on-device LLM. It consumes HSI as a conditioning input on inference requests, but works without it.
• The cloud is optional and consent-gated. With cloudUpload consent granted, HSI envelopes are uploaded to api.synheart.ai (or your enterprise gateway). RAMEN is the other direction: cloud → app, for real-time vendor and platform events.

​

Mandatory vs optional

The smallest useful Synheart app is one SDK and your code. Everything else is opt-in.

​

How the concepts relate

A few terms recur across the docs. Holding these in mind makes the rest of the site easier to skim:

• HSI (Human State Interface) — the JSON wire contract. Version 1.3 today. See HSI overview.
• HSV (Human State Vector) — the typed in-runtime representation. The inference engine produces HSV[].
• Flux — the runtime step that packs HSV[] into an HSI envelope on the wire.
• Capability tier — what your app is entitled to (core, extended, research).
• Consent type — what the user allows (biosignals, behavior, phoneContext, cloudUpload, vendorSync, research).
• Data access requires both the capability tier and the user consent. See Capability system and Consent system.

A more compact list lives in the Glossary.

​

Two common paths

Path A — “I just want wearable readings.” Add synheart_wear (or the Kotlin / Swift equivalent). No CLI, no platform account, no runtime. Stream HR / HRV / sleep into your own code. Stop here. Path B — “I want a focus / capacity / recovery score.” Add Synheart Core. Install the runtime (synheart install runtime), authenticate the CLI, ship the SDK in your app. The runtime fuses whatever modules you’ve enabled (Wear + Behavior + Phone) into HSI. Subscribe to onHSIUpdate or onStateUpdate. If you’re not sure which path you’re on, the Quickstart has a one-sentence filter at the top and side-by-side code for both.

​

Where to go next