Syni — Flutter SDK

​

Overview

• 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

​

Installation

​

1. Pull the native runtime artifacts

synheart install syni     # runtime + spec (entitled subset)

​

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
);

​

Where this fits

• HSI signal collection (the synheart_core SDK does), or
• the four-authority gate (consent + capability + activation + session; also a host concern).

​

Models

• 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)

​

API reference

• 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 — how the pieces fit
• Syni Runtime FFI — the C ABI under the hood
• Syni Spec — persona / safety / schema contracts
• Package on pub.dev: syni