xybrid library

Xybrid - Hybrid cloud-edge ML inference orchestrator.

This library provides a clean Dart API for running ML models on-device or in the cloud, with intelligent routing based on device capabilities.

Initialization

You must call Xybrid.init once before using any Xybrid functionality:

void main() async {
  await Xybrid.init();
  runApp(MyApp());
}

Quick Start

// Initialize once at app startup
await Xybrid.init();

// Load a model from registry
final loader = XybridModelLoader.fromRegistry('kokoro-82m');
final model = await loader.load();

// Run text-to-speech
final envelope = XybridEnvelope.text('Hello, world!');
final result = await model.run(envelope);
final audioBytes = result.audioBytes;

Pipelines

// Load and run a pipeline
final pipeline = XybridPipeline.fromYaml('''
name: speech-to-text
stages:
  - model: whisper-small
''');
final envelope = XybridEnvelope.audio(bytes: audioData, sampleRate: 16000);
final result = await pipeline.run(envelope);

Conversation Context (LLM)

// Create conversation context for multi-turn chat
final context = ConversationContext();
context.setSystem('You are a helpful assistant.');

// Run with context
context.pushText('Hello!', MessageRole.user);
final result = await model.runWithContext(
  XybridEnvelope.text('Hello!'),
  context,
);
context.pushText(result.text ?? '', MessageRole.assistant);

Classes

• XybridModelLoader - Prepare and load models from registry or bundles
• XybridModel - A loaded model ready for inference
• XybridEnvelope - Input data wrapper for different modalities
• XybridResult - Inference output containing text, audio, or embeddings
• XybridPipeline - Multi-stage inference pipeline
• ConversationContext - Multi-turn conversation memory for LLMs
• MessageRole - Message role for conversation turns
• GenerationConfig - LLM generation parameters (temperature, top-p, etc.)
• ToolDefinition / ToolCall / ToolResult - LLM tool (function) calling

Classes

AbortPolicy

Per-run abort behavior exposed to Flutter callers.

CancellationToken

Cooperative cancel handle for an in-flight streaming run.

ConversationContext

Manages multi-turn conversation history for LLM models.

DeviceSnapshot

Snapshot of the routing-engine's current view of device state.

FfiDownloadStatus

Download progress + state in one consistent read, so a polling UI cannot observe a torn pair (for example Ready with a stale 0.34 progress).

FfiPartialResult

A partial transcript emitted while audio is streaming.

FfiVadMode

GenerationConfig

Generation parameters for LLM inference.

ImagePlane

One memory plane inside a raw pixel image.

LoadComplete

Model loading completed successfully.

LoadError

Model loading failed with an error.

LoadEvent

Event emitted during model loading with progress tracking.

LoadProgress

Download progress update (0.0 to 1.0).

RunOptions

Per-run controls for SDK execution.

StreamToken

A single token emitted during streaming generation.

ToolCall

One tool call the model emitted this turn.

ToolDefinition

A tool the model may ask to call.

ToolResult

The outcome of running one tool, fed back to the model next turn.

Xybrid

Main entry point for the Xybrid SDK.

XybridEnvelope

Envelope containing input data for model inference.

XybridInferenceMetrics

Typed inference metrics surfaced on every XybridResult.

XybridModel

XybridModelLoader

Prepares a model for loading from registry or local bundle.

XybridPipeline

A loaded pipeline ready for multi-stage inference.

XybridResult

Result of a model inference operation.

XybridStageLatency

Per-stage latency entry for pipeline runs.

XybridStreamSession

A live speech-to-text session that transcribes audio as it is fed.

YuvColorInfo

Color metadata required for raw YUV camera frames (nv12, nv21, i420).

Enums

AbortSignal

Resource or cancellation signals that can stop a local run.

FfiDownloadState

Lifecycle of the background download behind a speculative load.

FfiExecutionTarget

Where a result was produced — the observed fact, not a routing preference.

MemoryPressure

Derived memory-pressure classification from available / total.

MessageRole

Message role for conversation turns.

PixelFormat

Raw pixel-buffer format accepted by XybridEnvelope.imageRaw.

ThermalState

Thermal pressure classification matching the desktop pollers' Celsius bands (Normal < 60, Warm 60–70, Hot 70–80, Critical >= 80).

YuvColorMatrix

YUV color conversion matrix for raw YUV camera frames.

YuvColorRange

YUV luma/chroma numeric range.

Functions

jsonSchemaToGbnf({required String schemaJson}) → String

Convert a JSON Schema (as a JSON string) into a GBNF grammar for `FfiGenerationConfig::grammar`.

wrapInWavHeader(Uint8List pcmBytes, {required int sampleRate, required int channels}) → Uint8List

Wraps raw PCM audio bytes in a WAV header for playback.

Exceptions / Errors

XybridException

Exception thrown when Xybrid operations fail.