Skip to main content

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

The Syni Flutter SDK (package:syni) is the Dart/Flutter consumer of the Syni runtime. 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; 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

AndroidiOSmacOSLinuxWindowsWeb
✅✅🚧🚧🚧❌
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, distributed separately via the Synheart CLI: 
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

flutter pub add syni

# pubspec.yaml
dependencies:
  syni: ^0.1.0

​
Basic usage

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

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

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