syni

Flutter SDK for Syni — adaptive on-device LLM inference with hybrid local/cloud chat, structured persona conditioning, and a streaming chat API designed for the UI thread.

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

Getting started

Add the dependency:

flutter pub add syni

Install the runtime via the Synheart CLI:

synheart install syni

This drops the platform binaries into your app's vendor tree (synheart/vendor/syni/) so Gradle / Cocoapods can link them. Re-run the command anytime you want to refresh — it's idempotent.

Then import the agent layer:

import 'package:syni/agent.dart';

Usage

A complete runnable Flutter app lives in example/. The abridged version:

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

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 synheart_core and use Synheart.syni, which wraps this package with those layers. Standalone use of package:syni is fully supported when you don't need the wider Synheart contract.

Documentation

API reference on pub.dev
Syni overview — Synheart's on-device LLM stack
Syni Spec — canonical persona / safety / schema contracts

Contributing

This is a source-available repository. Issues and feature requests are welcome; pull requests are not accepted at this time. See CONTRIBUTING.md for the rationale and the supported contribution path. Security reports go through SECURITY.md.