Xybrid
SDKs

iOS

Native Swift SDK for on-device ML inference

The Swift SDK provides native bindings to the Xybrid runtime via BoltFFI for iOS applications.

Releases ship a prebuilt XybridFFI xcframework via Swift Package Manager, with slices for iOS devices and the iOS Simulator (both arm64). For cross-platform development, see the Flutter SDK.

Installation

Add the Xybrid package via Swift Package Manager:

Package.swift
dependencies: [
    .package(url: "https://github.com/xybrid-ai/xybrid", from: "0.20.0")
]

Or in Xcode: File > Add Package Dependencies and enter the repository URL.

Supported platforms: iOS 16.0+, on devices and the iOS Simulator on Apple Silicon Macs. Building needs Xcode 15.3+ (Swift 5.10). macOS is not supported; see Platform Support.

Quick Start

import Xybrid

@main
struct MyApp: App {
    init() { Xybrid.initialize() }
    var body: some Scene { /* ... */ }
}

// Describe, then explicitly load a model from the registry
let model = try await Xybrid.model("kokoro-82m").load()

// Run inference
let envelope = Envelope.text("Hello, world!")
let result = try await model.runAsync(envelope: envelope)

print("Output: \(result.text ?? "")")
print("Latency: \(result.latency)s")

On iOS, Xybrid.initialize() enables UIDevice battery monitoring and subscribes to UIDevice.batteryLevelDidChangeNotification, forwarding readings to the routing engine. Thermal state on Apple platforms is sourced from NSProcessInfo.thermalState directly in xybrid-core.

Initialization

Inference runs entirely on-device whether or not you authenticate. The apiKey authenticates the cloud gateway; gatewayUrl overrides it:

Xybrid.initialize(
    apiKey: ProcessInfo.processInfo.environment["XYBRID_API_KEY"]
)

Key prefixes and scopes, what gets exported, and provisional workspaces: see API keys.

Observability

Trace export is off until you configure it — an API key alone does not enable it. Start it once, after initialize(), with one of two presets:

// Traces to Xybrid
try Xybrid.Observability.xybrid(apiKey: key)
    .service("MyApp", version: "1.4.0")
    .start()

// Traces, metrics, and logs to an OTLP/HTTP endpoint (e.g. an OpenTelemetry Collector)
try Xybrid.Observability.otlp(endpoint: "http://collector:4318")
    .start()

Prompts and outputs are captured by default; add .metadataOnly() to export metadata only. .tracesEndpoint(_:) points the Xybrid preset at a self-hosted endpoint. Until export is configured, the first inference logs a one-shot hint (suppress with XYBRID_QUIET=1). Get a key at console.xybrid.dev.

Run options carry per-run trace context, and each result's observation identifies its trace:

let result = try await model.runAsync(
    envelope: envelope,
    options: .make(traceparent: parentTraceparent, conversationId: chatId)
)
if let observation = result.observation {
    try Xybrid.Observability.recordFeedback(for: observation, score: 1, label: "thumbs_up")
}
try await Xybrid.Observability.flushAsync()

Feedback and evaluations (recordEvaluation(for:name:...)) need a logs signal, so they return false with the Xybrid preset, which sends traces only.


Model Loading

From Registry

let model = try await Xybrid.model("whisper-tiny-ggml").load()

From Local Bundle

let model = try await Xybrid.model(.bundle(bundleURL)).load()

Xybrid.model(...) creates a cheap, unloaded reference. Local bundle, directory, and GGUF file sources use URL through .bundle(url), .directory(url), and .modelFile(url); Hugging Face uses .huggingFace("org/repo"). Async load() is the explicit boundary for resolving, downloading, disk access, and runtime initialization. Use loadSync() only from an existing worker thread.

From a Local GGUF File

let model = try await Xybrid.model(.modelFile(ggufURL)).load()

A raw llama.cpp GGUF needs no model_metadata.json. load() generates one from the GGUF header and writes it next to the file, with the context capped at 4,096 tokens (raise its context_length for longer chats). Put each GGUF in its own directory inside the app container, such as Application Support. The app bundle is read-only, so model_metadata.json cannot be written there, and a model_metadata.json already in the directory is used as is: a second GGUF in the same directory would load the first one's model. Copy a file the user picks into the app container before loading it.


Download Progress

load() blocks until the weights are on disk, so it has no progress to report while it runs. Start the download separately and watch it:

let loader = Xybrid.model("qwen3-0.6b")
if let download = loader.download() {
    for await status in download.progress() {
        bar.progress = Float(status.progress)
        label.text = "\(status.downloadedBytes) / \(status.totalBytes ?? 0)"
    }
}
let model = try await loader.load()   // cached: returns at once

progress spans every file the model needs — weights plus companions such as a vision projector — and never moves backwards, so the bar neither restarts per file nor rewinds when a download retries. totalBytes is null when the source publishes no size (a Hugging Face repo); downloadedBytes is exact either way, which is what you need for megabytes, speed and time remaining.

Cancelling the consuming task only unsubscribes from updates. Call cancel() to stop the transfer itself — it takes effect within one chunk read and discards the partial file.


Input Envelopes

Audio (Speech Recognition)

let envelope = Envelope.audio(pcmData: audioData, sampleRate: 16000, channels: 1)
let result = try model.run(envelope: envelope)
print("Transcription: \(result.text ?? "")")

Text (Text-to-Speech)

// Simple text
let envelope = Envelope.text("Hello, how are you?")

// With voice and speed
let voiced = Envelope.text("Hello", voice: "af_heart", speed: 1.0)

let result = try model.run(envelope: envelope)
if let audioBytes = result.audioBytes {
    // Play or save audio
}

Embedding

let envelope = Envelope.embedding(data: [0.1, 0.2, 0.3])
let result = try model.run(envelope: envelope)
if let vector = result.embedding {
    // Process embedding vector
}

Streaming Tokens

runAsync returns once the whole answer is ready. For a chat UI, stream the tokens as they are generated:

let model = try await Xybrid.model("qwen3-0.6b").load()

for try await token in model.streamTokens(envelope: .text("Tell me a joke")) {
    label.text = token.cumulativeText
}

streamTokens returns an AsyncSequence of XybridStreamToken. Cancelling the task that consumes it, or breaking out of the loop, stops generation at the next token. Pass options: .make(generationConfig: config) for generation settings. See Streaming for the other SDKs.


Live Transcription

run() transcribes a finished audio buffer. A session transcribes speech as it arrives, which is what dictation and live captioning need.

Audio must be PCM float32, mono, 16 kHz — converting from the platform's microphone format is the caller's job.

let model = try await Xybrid.model("whisper-tiny").load()
let session = try model.stream(config: .voiceActivity(modelDir: vadModelDir, language: "en"))

Task {
    for await partial in session.partials() {
        label.text = partial.text
    }
}

// From the AVAudioEngine tap, converted to 16 kHz mono Float32:
try session.feed(samples: pcm)

// When the user stops talking:
let result = try session.flush()
let transcript = result.text

Partial text is cumulative, not a delta: render each one in place of the previous rather than appending. A partial produced before you subscribe is delivered immediately, so the opening words of an utterance are never lost.

flush() ends the session and returns an XybridTranscriptionResult: the full transcript in text, plus durationMs, chunksProcessed and the session's observation reference. It throws if any chunk failed to transcribe, because that audio is gone and the transcript would otherwise look complete. cancel() ends the session and discards queued audio.

Earlier releases returned the transcript as a String. Read .text from the result instead.

Voice-activity detection cuts chunks on speech boundaries instead of a fixed clock, which avoids the stutter you get when a window lands mid-word. It needs a Silero VAD model directory containing a model.onnx; none ships with the SDK, and without one the engine falls back to fixed windows.


Result Handling

A failed run throws a XybridError instead of returning a result, so a result needs no success check (see Error Handling). Switch on outputType to read the output:

let result = try model.run(envelope: envelope)

switch result.outputType {
case .text:
    print("Text: \(result.text ?? "")")
case .audio:
    if let audio = result.audioBytes { playAudio(audio) }
case .embedding:
    if let vector = result.embedding { process(vector) }
default:
    break
}
print("Latency: \(result.latency)s")  // TimeInterval in seconds

XybridResult Properties

PropertyTypeDescription
successBoolAlways true; a failed run throws instead
outputTypeXybridOutputType.text, .audio, .embedding, .decisions, or .unknown
textString?Text output (ASR, LLM)
audioBytesData?Audio output (TTS)
embedding[Float]?Embedding vector
latencyMsUInt32Inference latency in ms
isFailureBooltrue when the result carries no output (outputType == .unknown)
latencyTimeIntervalLatency in seconds
modelIdStringID of the model that produced the result
reasoningContentString?Model reasoning, kept apart from the answer text
toolCalls[XybridToolCall]Tool calls the model emitted; empty unless the request offered tools
observationXybridObservationRef?The run's trace reference, when it was traced

Error Handling

The SDK uses a Swift error enum for type-safe error handling:

do {
    let model = try await Xybrid.model("kokoro-82m").load()
    let result = try await model.runAsync(envelope: envelope)
} catch XybridError.modelNotFound(let id) {
    print("Model not found: \(id)")
} catch XybridError.inferenceError(let message) {
    print("Inference failed: \(message)")
} catch XybridError.ioError(let message) {
    print("I/O error: \(message)")
} catch {
    print(error.localizedDescription)
}

Cases are lowerCamelCase with labeled associated values, such as modelNotFound(id:) and inferenceError(message:). XybridError conforms to LocalizedError, so localizedDescription gives a readable message for every case.


Type Aliases

The SDK provides short aliases for convenience:

AliasFull Type
ModelXybridModel
EnvelopeXybridEnvelope
ResultXybridResult
VoiceInfoXybridVoiceInfo
GenerationConfigXybridGenerationConfig
XybridSDKErrorXybridError

ModelLoader is a cheap model reference. Construct it through Xybrid.model(...), then call load() explicitly before inference.


Platform Support

The Swift package supports iOS 16.0 and later only. The prebuilt XybridFFI xcframework ships two slices, iOS device (arm64) and iOS Simulator (arm64), and no macOS slice, so the package does not declare macOS. For a macOS app, use the Flutter SDK (macOS 14+ on Apple Silicon) or the Rust crate from the Quick Start.

Model formatiOS deviceiOS Simulator
GGUF (llama.cpp: LLMs, vision-language models)Metal GPUCPU
Whisper (whisper.cpp)CPU; the encoder runs on Core ML when a <model>-encoder.mlmodelc (e.g. ggml-base.en-encoder.mlmodelc) sits beside the model fileCPU; the same Core ML encoder path applies
ONNX (ONNX Runtime)CPUCPU

GGUF inference runs on llama.cpp's Metal backend, which has no Apple Neural Engine path. Of the paths above, only the optional Core ML Whisper encoder can reach the Neural Engine, and Core ML decides at run time whether it does.

On this page