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

# Overview

> Adaptive on-device LLM inference for Synheart apps — what Syni is and how the pieces fit together.

**Syni** is Synheart's on-device LLM stack. It runs adaptive, persona-conditioned
language model inference locally on the user's device, with an optional cloud
fallback for higher-capability requests.

Syni is composed of four artifacts, each released independently and pinned by
the consumer at install time:

| Piece                             | What it is                                                                              | Released as                      |
| --------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------- |
| [Syni Flutter SDK](/syni/flutter) | Dart/Flutter consumer SDK — agent, install lifecycle, persona binding, streaming chat   | `package:syni` on pub.dev        |
| [Syni Runtime](/syni/runtime-ffi) | Native inference engine with a stable C ABI (FFI). The native artifact every SDK calls. | `dist.synheart.ai/syni-runtime/` |
| [Syni Spec](/syni-spec/overview)  | Canonical persona / safety / schema / grammar contracts                                 | `dist.synheart.ai/syni-spec/`    |
| Syni Cloud Gateway                | HTTP + SSE chat endpoint for cloud-fallback inference, persona-aware                    | `api.synheart.ai`                |

The same persona id resolves to the same behavior whether served by the local
runtime or the cloud gateway. That's the entire point of the spec — it pins
behavior independently of model choice.

## What "adaptive" means

Syni adapts its output to the user's current physiological and behavioral
state. The runtime's `PromptBuilder` reads an opaque conditioning map
passed in via the `hsi:` parameter on every request, and shapes the
prompt — system context, persona modulation, and decoded structured fields —
based on what's in it.

Synheart-stack apps populate that map with [HSI](/hsi/overview), Synheart's
unified Human State Interface derived from biosignal SDKs (wear, behavior,
session) via [`synheart_core`](/synheart-core/overview). Non-Synheart apps
can pass any `Map<String, dynamic>` — an ad-hoc context dict, a stress
score from another source, or `null` for unconditioned inference — and
the same persona will resolve to a coherent response.

In short: Syni is the LLM substrate; HSI is the differentiator that makes it
adapt rather than just respond.

## Install

The Synheart CLI handles the runtime + spec on disk:

```bash theme={null}
synheart install syni             # both runtime + spec (entitled subset)
synheart install runtime syni     # just the LLM engine
synheart install spec             # just the persona contracts
```

Lands artifacts under `synheart/vendor/syni-runtime/` and
`synheart/vendor/syni-spec/`. The verb shape is product + component:
product nouns (`syni`, `core`) install every component you're entitled
to; component nouns (`runtime`, `spec`) fan out across products; two-arg
forms pin to one canonical package.

The Flutter SDK is added separately via `pub`:

```bash theme={null}
flutter pub add syni
```

It uses the runtime artifacts that the CLI dropped into your app's
`synheart/vendor/syni-runtime/` tree.

## Why Syni is split this way

* **Runtime ≠ SDK.** The native runtime + C ABI is the slow-changing artifact.
  SDKs in three languages (Dart, Swift, Kotlin) layer over the same ABI.
* **Spec ≠ code.** Persona behavior, safety rails, output schemas, and
  grammars are versioned contracts that can ship independently of any
  inference change. Same spec id → same behavior on local + cloud.
* **Cloud is opt-in.** Every persona declares an `execution_policy`
  (`local` / `cloud` / `hybrid`). Apps can run fully offline, or fall back
  to cloud per call.

## Persona model

Personas are JSON contracts in [`syni-spec`](/syni-spec/overview). Each one
declares:

* a stable id (e.g. `focus.coach.v1`)
* `output_schema_id` — the JSON Schema the response must satisfy
* `safety_rule_ids` — global policies that constrain output
* `execution_policy` — local / cloud / hybrid
* `capability_tier` *(optional)* — preferred cloud-model lane: `fast` /
  `standard` / `deep`. The cloud gateway uses it to pick a route when
  the caller hasn't pinned a model. Omit (or set `standard`) for the
  default lane; pick `fast` for conversational personas that don't need
  deep reasoning; pick `deep` for long-range analytical personas that
  do. Unknown values fall back to the default lane.
* `privacy` — what data may leave the device
* `budget` — token / request limits

Production-tier personas in the current spec:

* `focus.coach.v1`
* `stress.coach.v1`
* `cognitive.companion.v1`
* `performance.coach.v1`
* `wellness.guide.v1`

Apps load them by id. Out-of-spec ids fail closed.

## Related

* [Syni Flutter SDK](/syni/flutter) — getting started in a Flutter app
* [Syni Runtime FFI](/syni/runtime-ffi) — the C ABI for SDK authors
* [Syni Spec](/syni-spec/overview) — persona / safety / schema contracts
* [Install via CLI](/syni-spec/install) — `synheart install syni`