Kotlin SDK for Android
Relevant source files
The following files were used as context for generating this wiki page:
The Kotlin SDK for Android provides a typed wrapper around a shared C++ core library for on-device AI inference. It enables Android applications to perform tasks including Large Language Model (LLM) generation, Speech-to-Text (STT), Text-to-Speech (TTS), and Voice Activity Detection (VAD).
The SDK follows a bridge-based architecture where Kotlin code calls into a native library (librunanywhere_jni.so) via the Java Native Interface (JNI). It uses Wire-generated Protobuf types as the canonical data model and integrates with Kotlin coroutines and Flows for asynchronous and streaming operations.
Sources: bindings/kotlin/AGENTS.md:55-63, AGENTS.md:65-75
Architecture Overview
The Kotlin SDK builds as a standard Android library (.aar). It serves as a thin abstraction layer over the runanywhere-commons C++ core.
Layered Structure
The SDK architecture consists of four distinct layers:
- Public API: The
RunAnywheresingleton and extension functions providing the developer-facing interface. - Bridge Extensions:
CppBridge*objects that handle type conversion and error mapping. - JNI Boundary:
RunAnywhereBridgeexternal function declarations. - C++ Core: Native C functions in
librac_commons.soandlibrunanywhere_jni.so.
Sources: bindings/kotlin/AGENTS.md:65-72, bindings/kotlin/AGENTS.md:111-118
The diagram shows the call flow from the Android application through the Kotlin layers into the native C++ core.
Sources: bindings/kotlin/AGENTS.md:111-118
Two-Phase Initialization
The SDK mirrors the iOS SDK initialization pattern, splitting the setup into a synchronous native load and an asynchronous service registration.
| Phase | Method | Operation |
|---|---|---|
| Phase 1 | initialize() | Synchronously loads runanywhere_jni library and registers platform adapters (OkHttp, logging, telemetry). |
| Phase 2 | completeServicesInitialization() | Asynchronously authenticates with the backend, fetches model assignments, and registers Android System TTS callbacks. |
Sources: bindings/kotlin/AGENTS.md:92-109, AGENTS.md:104-110
Core Components
Public API Surface
The RunAnywhere object (located in public/RunAnywhere.kt) is the sole entry point. Capabilities are added via extension functions located under public/extensions/.
- LLM: Text generation and streaming.
- STT/TTS: Speech recognition and synthesis.
- Models: Lifecycle management, registry, and downloads.
- VoiceAgent: High-level voice interaction management.
Sources: bindings/kotlin/AGENTS.md:120-125, bindings/kotlin/example/AGENTS.md:54-61
Type System
The SDK uses Wire Protobuf as the canonical data model. Generated bindings are located in the com.runanywhere.sdk.generated package. The SDK uses these types directly or via typealiases for ergonomics.
typealias SDKEnvironment = ai.runanywhere.proto.v1.SDKEnvironment
typealias AudioFormat = ai.runanywhere.proto.v1.AudioFormat
Sources: bindings/kotlin/AGENTS.md:127-142
Event System
The EventBus singleton uses a MutableSharedFlow<SDKEvent> to publish typed events. Components emit events for model download progress, LLM tokens, and lifecycle updates.
The sequence illustrates how SDK components broadcast events to application subscribers via a shared flow.
Sources: bindings/kotlin/AGENTS.md:154-162
Optional Backend Modules
The SDK supports modular backends packaged as sub-module AARs. These modules register specific inference engines with the core plugin system.
| Module Name | Purpose | Native Library |
|---|---|---|
runanywhere-core-llamacpp | LLM and VLM backend. | librac_backend_llamacpp_jni.so |
runanywhere-core-onnx | ONNX and Sherpa speech backends. | librac_backend_onnx_jni.so |
runanywhere-core-qhexrt | Qualcomm Hexagon NPU backend (arm64-v8a only). | Binary-only proprietary library |
Sources: bindings/kotlin/AGENTS.md:164-180, bindings/kotlin/CLAUDE.md:76-85
Build and Development
Gradle Commands
The SDK is built using Gradle. Native library sourcing is controlled by gradle.properties.
- Build AAR:
./gradlew build - Native Setup:
./gradlew setupLocalDevelopment(builds C++ JNI libs from source) - Linting:
./gradlew detektand./gradlew ktlintCheck
Sources: bindings/kotlin/AGENTS.md:14-43
Native Lib Sourcing
- Local Natives:
runanywhere.useLocalNatives=truecompiles C++ from thecore/directory. - Pre-built Natives:
runanywhere.useLocalNatives=falsedownloads.sofiles from GitHub Releases.
Sources: bindings/kotlin/AGENTS.md:46-52
Error Handling
The SDK uses SDKException to wrap Protobuf SDKError objects. It provides extension functions to map C ABI negative return codes to typed exceptions.
val result = racLlmGenerate(...)
result.throwIfCAbiErrorAsException("llm.generate") // Throws if < 0
Sources: bindings/kotlin/AGENTS.md:145-152
Summary
The Kotlin SDK for Android provides a high-performance, typed interface for on-device AI. By wrapping the C++ core with JNI and exposing it through Kotlin-friendly abstractions like coroutines and Protobuf-generated types, it enables developers to integrate advanced AI capabilities while maintaining binary compatibility with the broader RunAnywhere ecosystem.