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

# Syni — Flutter SDK

> Adaptive on-device LLM inference with hybrid local/cloud chat, persona conditioning, and a streaming API designed for the UI thread.

## Overview

The Syni Flutter SDK (`package:syni`) is the Dart/Flutter consumer of the
[Syni runtime](/syni/runtime-ffi). It wraps the C FFI in a Dart agent API:
install lifecycle, persona binding, streaming chat, and hybrid local/cloud
routing.

**Key features**

* **On-device inference** — Qwen 2 / 2.5 and Gemma 3 GGUF models out of the
  box; bring your own GGUF for other supported architectures.
* **Hybrid local / cloud** — same agent API, choose execution mode per call
  (`localFirst`, `cloudFirst`, `localOnly`, `cloudOnly`).
* **Versioned personas** — load by id from bundled
  [`syni-spec`](/syni-spec/overview); the same id resolves to the same
  behavior on client and server.
* **Worker isolate** so engine load + token generation don't block the UI
  thread.
* **Verified model downloads** — pinned SHA-256 per model, checked at
  install time.
* **Streaming chat** with token-level deltas plus a final structured
  response.

## Platform support

| Android | iOS | macOS | Linux | Windows | Web |
| :-----: | :-: | :---: | :---: | :-----: | :-: |
|    ✅    |  ✅  |   🚧  |   🚧  |    🚧   |  ❌  |

Android + iOS are the supported targets today. Desktop targets are in the
works. Web is out of scope.

## Installation

### 1. Pull the native runtime artifacts

The Flutter plugin doesn't ship the native engine — that's [Syni Runtime](/syni/runtime-ffi),
distributed separately via the Synheart CLI:

```bash theme={null}
synheart install syni     # runtime + spec (entitled subset)
```

This lands `SyniRuntime.xcframework/`, `android/jniLibs/<abi>/libsyni_ffi.so`,
and the spec payload under your app's `synheart/vendor/` tree. The plugin's
`build.gradle` / `Podspec` resolve these paths automatically.

Re-run any time you want a fresher version — installs are idempotent.

### 2. Add the Dart package

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

```yaml theme={null}
# pubspec.yaml
dependencies:
  syni: ^0.1.0
```

## Basic usage

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:syni/agent.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final agent = SyniAgent();

  // Load a persona by id from the bundled spec assets.
  final persona = await SyniSpecPersona.load('focus.coach.v1');

  // First-run install: download + verify the model, load the engine,
  // bind the persona. Emits lifecycle events on agent.installState.
  await agent.install(
    persona: persona,
    model: SyniModels.qwen25_15bInstructQ4,
  );

  // Single-turn chat.
  final response = await agent.chat('How can I focus right now?');
  debugPrint(response.displayText);
}
```

## Streaming

```dart theme={null}
agent.chatStream('hello').listen((event) {
  switch (event) {
    case SyniChatDelta(:final delta):
      stdout.write(delta);
    case SyniChatFinal(:final response):
      print('\n[${response.displayText.length} chars]');
  }
});
```

## Hybrid local / cloud

```dart theme={null}
final agent = SyniAgent(
  cloudConfig: SyniCloudConfig(
    baseUrl: 'https://api.synheart.ai',
    authToken: () async => '<bearer-token>',
    tenantId: '<tenant>',
    userId: '<user>',
  ),
);

await agent.chat(
  'how was my recent session?',
  mode: SyniExecutionMode.cloudFirst, // try cloud, fall back to local
);
```

Execution policy can be set per call (`SyniExecutionMode.{localFirst,
cloudFirst, localOnly, cloudOnly}`) or pinned by the persona via its
`execution_policy` field in the spec.

## Where this fits

`package:syni` is the **agent layer** — inference, install lifecycle,
persona binding, chat orchestration. It does not own:

* HSI signal collection (the
  [`synheart_core`](/synheart-core/flutter) SDK does), or
* the four-authority gate (consent + capability + activation + session;
  also a host concern).

Synheart-ecosystem apps typically depend on both `synheart_core` and `syni`,
and use `Synheart.syni` (in `synheart_core`) which wraps the agent with
those layers. Standalone use of `package:syni` is fully supported when you
don't need the wider Synheart contract.

## Models

Two pre-pinned entries ship in `SyniModels`:

* `qwen25_15bInstructQ4` (Qwen 2.5 1.5B Instruct Q4\_K\_M, \~1.1 GB)
* `gemma3_1bInstructQ4` (Gemma 3 1B Instruct Q4\_K\_M, \~770 MB,
  Synheart-hosted mirror)

Both ship with pinned SHA-256 verified at install time. Bring your own
GGUF for other supported architectures via `SyniModelSpec`.

## API reference

The full Dart API is on
[pub.dev](https://pub.dev/documentation/syni/latest/).

Surface highlights:

* `SyniAgent` — install lifecycle, model catalog, persona binding,
  `chat` / `chatStream` orchestration, hybrid local/cloud routing.
* `SyniInstaller` — model download, tokenizer fetch, SHA-256
  verification, cold-start restore.
* `SyniCloudClient` — HTTP + SSE client for the Syni cloud chat endpoint;
  sticky session id; HSI forwarded as request `context`.
* `SyniSpecPersona.load(id)` — resolves persona JSON from bundled spec
  assets so the same id consistently produces the same behavior on client
  and server.
* `SyniRuntime` — worker-isolate wrapper over the on-device inference
  engine.

## Related

* [Syni overview](/syni/overview) — how the pieces fit
* [Syni Runtime FFI](/syni/runtime-ffi) — the C ABI under the hood
* [Syni Spec](/syni-spec/overview) — persona / safety / schema contracts
* Package on pub.dev: [`syni`](https://pub.dev/packages/syni)