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:
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 onceprogress 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.textPartial 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 secondsXybridResult Properties
| Property | Type | Description |
|---|---|---|
success | Bool | Always true; a failed run throws instead |
outputType | XybridOutputType | .text, .audio, .embedding, .decisions, or .unknown |
text | String? | Text output (ASR, LLM) |
audioBytes | Data? | Audio output (TTS) |
embedding | [Float]? | Embedding vector |
latencyMs | UInt32 | Inference latency in ms |
isFailure | Bool | true when the result carries no output (outputType == .unknown) |
latency | TimeInterval | Latency in seconds |
modelId | String | ID of the model that produced the result |
reasoningContent | String? | Model reasoning, kept apart from the answer text |
toolCalls | [XybridToolCall] | Tool calls the model emitted; empty unless the request offered tools |
observation | XybridObservationRef? | 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:
| Alias | Full Type |
|---|---|
Model | XybridModel |
Envelope | XybridEnvelope |
Result | XybridResult |
VoiceInfo | XybridVoiceInfo |
GenerationConfig | XybridGenerationConfig |
XybridSDKError | XybridError |
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 format | iOS device | iOS Simulator |
|---|---|---|
| GGUF (llama.cpp: LLMs, vision-language models) | Metal GPU | CPU |
| 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 file | CPU; the same Core ML encoder path applies |
| ONNX (ONNX Runtime) | CPU | CPU |
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.