Swift SDK for Apple Platforms
Relevant source files
The following files were used as context for generating this wiki page:
The Swift SDK provides a high-level, type-safe interface for integrating RunAnywhere AI capabilities into iOS and macOS applications. It serves as the primary reference implementation for the RunAnywhere platform, defining the architectural standards, public API naming conventions, and lifecycle orchestration for other platform SDKs. The SDK bridges a shared C++ core library to Swift, enabling on-device inference for LLM, STT, TTS, and other AI modalities on Apple hardware.
Sources: AGENTS.md:98-103, CONTRIBUTING.md:128-132, bindings/react-native/AGENTS.md:120-125
Core Architecture and Bridging
The Swift SDK operates as a thin bridge over the C++ runanywhere-commons core. It utilizes XCFrameworks and a CRACommons module map to interface with the core logic. All AI business logic, including model lifecycles, inference routing, and registry management, resides in the C++ core behind a pure C ABI (prefixed with rac_). The Swift layer handles platform-specific services such as file I/O, HTTP networking via URLSession, and secure storage via Keychain.
Sources: AGENTS.md:98-103, AGENTS.md:162-167, bindings/react-native/AGENTS.md:73-83
Native Bridge Mechanism
The following diagram illustrates the relationship between the Swift application, the SDK bridge, and the underlying C++ core:
SDK Components and Modalities
The SDK is organized into namespaces that correspond to specific AI modalities. Each namespace provides specialized functions for inference and model management.
Modality Overview
| Namespace | Primary Capabilities | Backend Engines |
|---|---|---|
| LLM / VLM | Text generation, streaming, structured output, vision tasks | LlamaCPP, MLX |
| STT | Batch and stream speech-to-text transcription | Sherpa-ONNX, MLX |
| TTS | Text-to-speech synthesis and speech playback | Sherpa-ONNX, MLX |
| VAD | Voice Activity Detection | Sherpa-ONNX |
| RAG | Vector search, document ingestion, and retrieval | ONNX, Core |
| Voice | Full-duplex voice agent sessions | Combined Engines |
Sources: AGENTS.md:154-158, bindings/react-native/AGENTS.md:165-180
Initialization Lifecycle
The SDK follows a two-phase initialization pattern to ensure that the native core is ready before attempting network-dependent operations or inference:
- Phase 1 (Synchronous): Registers the platform adapter, configures logging, and initializes the native core state.
- Phase 2 (Asynchronous): Performs authentication, device registration, and fetches model assignments.
Sources: AGENTS.md:172-176, bindings/react-native/AGENTS.md:120-130
Distribution and Binary Management
The Swift SDK is distributed through two primary channels: the main monorepo for development and a specialized standalone distribution repository for consumers.
Standalone Distribution
The runanywhere-swift repository is a lightweight version of the SDK (~3 MB) designed to prevent SwiftPM from cloning the entire monorepo (~340 MB). It contains the Swift source files and points to remote binary targets for the XCFrameworks.
Sources: bindings/swift/scripts/sync-dist-repo.sh:8-16
Binary Artifacts
Apple platforms utilize several XCFrameworks to support different backends and runtimes:
| Artifact Name | Description |
|---|---|
RACommons | Core infrastructure, event system, and proto ABI |
RABackendLLAMACPP | llama.cpp engine for GGUF models |
RABackendMLX | Apple MLX engine (physical devices only) |
RABackendONNX | Generic ONNX runtime backend |
RABackendSherpa | Sherpa-ONNX for speech tasks |
RABackendNeuRT | Apple Neural Engine (ANE) integration |
RunAnywhereMLXRuntime | Shared Swift runtime for MLX |
RunAnywhereMLXMetal | Dynamic Metal carrier for MLX acceleration |
Sources: bindings/swift/scripts/release-swift-binaries.sh:4-8, bindings/swift/scripts/release-swift-binaries.sh:176-200
Release Process Flow
The release pipeline ensures that binaries are built, checksums are verified, and distribution manifests are updated across the ecosystem.
Development and Build Requirements
Building the Swift SDK from source requires specific toolchains and pre-built dependencies.
- OS: macOS (Required for Apple-specific builds).
- Xcode: Version 26+ (minimum) with iOS SDK.
- Swift: Version 6.2.
- Dependencies: Pre-built ONNX Runtime and Sherpa inventories must be present in
core/third_party. - Generated Code: Swift proto bindings are generated from Protobuf IDL schemas and are not tracked in version control; they must be generated via
idl/codegen/generate_all.sh --only swift.
Sources: CONTRIBUTING.md:190-195, bindings/swift/scripts/release-swift-binaries.sh:14-25, bindings/swift/scripts/sync-dist-repo.sh:22-30
Conclusion
The Swift SDK for Apple Platforms provides a high-performance bridge for on-device AI. By maintaining architectural parity with the core C++ logic while leveraging native Apple services like MLX and CoreML, it enables efficient inference across the Apple hardware ecosystem. The use of a specialized distribution repository and deterministic XCFramework packaging ensures a lightweight and reliable integration experience for application developers.
Sources: AGENTS.md:120-125, bindings/swift/scripts/sync-dist-repo.sh:8-16, bindings/react-native/AGENTS.md:73-83