Kotlin SDK
Build local AI apps with Kotlin coroutines and self-contained Android runtimes.
Overview
The Kotlin SDK (io.tether:qvac-sdk-kotlin) is the Kotlin client for QVAC. It
drives the same worker contract as the JS/TS and Python clients, and provides
Kotlin data classes, Flow streams, structured completion runs, and an
isolated Android service host.
The Kotlin SDK is in preview and is not on Maven Central yet. Install it from the GitHub release archives or build it from source, and open a GitHub issue if you need something else.
Requirements
- Android:
arm64-v8a, API 29 or newer. - Desktop JVM: experimental. The client resolves and starts a local
@qvac/sdkworker. - A Kotlin 2.3 or newer compiler. The artifacts depend on
bare-rpc-kotlin, which is compiled with Kotlin 2.4.
Kotlin/Native targets are not published.
Install
The Kotlin SDK is not published to a public Maven registry. Each SDK release on GitHub carries it as Maven repository archives that you download and point Gradle at. There is one archive per Android runtime profile:
| Archive | Dependency | Capabilities |
|---|---|---|
qvac-sdk-android-0.23.0-maven.zip | io.tether:qvac-sdk-android | all current SDK addons/capabilities |
qvac-sdk-android-assistant-0.23.0-maven.zip | io.tether:qvac-sdk-android-assistant | chat and transcription |
qvac-sdk-android-llm-0.23.0-maven.zip | io.tether:qvac-sdk-android-llm | completion and embeddings |
qvac-sdk-android-speech-0.23.0-maven.zip | io.tether:qvac-sdk-android-speech | Whisper, Parakeet and BCI transcription, translation, and TTS |
qvac-sdk-android-vision-0.23.0-maven.zip | io.tether:qvac-sdk-android-vision | multimodal completion, OCR, and classification |
qvac-sdk-android-media-0.23.0-maven.zip | io.tether:qvac-sdk-android-media | audio, image, video, world generation, and upscaling |
qvac-sdk-android-robotics-0.23.0-maven.zip | io.tether:qvac-sdk-android-robotics | VLA inference |
For the experimental desktop JVM client, see the package README.
Download the archive of the profile your app needs, and the release's
checksums, from the
sdk-v0.23.0 release.
For example, the LLM profile:
curl -fLO https://github.com/tetherto/qvac/releases/download/sdk-v0.23.0/qvac-sdk-android-llm-0.23.0-maven.zip
curl -fLO https://github.com/tetherto/qvac/releases/download/sdk-v0.23.0/qvac-sdk-kotlin-0.23.0-SHA256SUMS
sha256sum --check --ignore-missing qvac-sdk-kotlin-0.23.0-SHA256SUMS
# macOS: shasum -a 256 --check --ignore-missing qvac-sdk-kotlin-0.23.0-SHA256SUMSExtract it. The archive is a Maven repository: it holds the runtime and the Kotlin client modules it depends on.
unzip qvac-sdk-android-llm-0.23.0-maven.zip -d qvac-maven-repositoryDeclare the extracted directory as a Maven repository, next to JitPack, which
serves the bare-rpc-kotlin dependency the archive does not include:
// settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
exclusiveContent {
forRepository { maven("https://jitpack.io") } // bare-rpc-kotlin
filter { includeGroupByRegex("com\\.github\\.holepunchto\\..*") }
}
maven { url = uri("/absolute/path/to/qvac-maven-repository") }
}
}Add the dependency of the archive you downloaded:
// app/build.gradle.kts
dependencies {
implementation("io.tether:qvac-sdk-android-llm:0.23.0")
}A project on AGP 9 compiles with the Kotlin Gradle plugin on its classpath, and bundles Kotlin 2.2 when none is declared. Add the plugin without applying it:
// app/build.gradle.kts
plugins {
id("com.android.application")
id("org.jetbrains.kotlin.android") version "2.4.20" apply false
}All artifacts use the io.tether.qvac.sdk namespace, so the Kotlin API is the
same whichever profile you choose. Each profile embeds a capability manifest
that is checked before each request; calling a capability the profile does not
contain throws UnsupportedCapabilityException. Inspect it with
client.runtimeProfile.
To build the artifacts yourself instead, see the package README.
Quickstart
Run your first example using the desktop JVM client, which you build from the QVAC repository. Every example in this documentation is a desktop JVM program. On Android the SDK calls are the same: connect with AndroidServiceTransport as shown in Connect, and replace desktop-only helpers, such as the javax.sound.sampled audio code, with Android equivalents.
You need git, JDK 17, Node.js 22, Python 3, and an Android SDK with NDK 29.0.14206865 at ANDROID_HOME.
Clone the repository and go to the Kotlin SDK:
git clone --depth 1 https://github.com/tetherto/qvac.git
cd qvac/packages/sdk-kotlinThe examples live in examples/src/. This is the quickstart script, examples/src/Quickstart.kt:
// Kotlin port of packages/sdk/examples/quickstart.ts.
//
// Load a model (with download progress), run a streaming completion, unload.
//
// The client is coroutine-based, so the script body lives in `runBlocking`.
// On desktop JVM, `JvmBareKitTransport.connect()` starts the worker inside this
// JVM process.
//
// RUN: ./gradlew -p examples run -Pexample=Quickstart
import io.tether.qvac.sdk.QvacClient
import io.tether.qvac.sdk.QvacCompletionEvent
import io.tether.qvac.sdk.QvacMessage
import io.tether.qvac.sdk.QvacProgressEvent
import io.tether.qvac.sdk.completion
import io.tether.qvac.sdk.generated.ModelConstant
import io.tether.qvac.sdk.generated.Models
import io.tether.qvac.sdk.generated.schema.LoadModelResponse
import io.tether.qvac.sdk.generated.schema.ModelProgressResponse
import io.tether.qvac.sdk.jvm.JvmBareKitTransport
import io.tether.qvac.sdk.models
import io.tether.qvac.sdk.run
import kotlinx.coroutines.runBlocking
fun main(): Unit = runBlocking {
val client = QvacClient(JvmBareKitTransport.connect())
try {
val modelId = client.loadWithProgress(Models.LLAMA_3_2_1B_INST_Q4_0)
val run = client.completion.run(
modelId = modelId,
history = listOf(QvacMessage.user("Explain quantum computing in one sentence")),
)
run.events.collect { event ->
if (event is QvacCompletionEvent.ContentDelta) print(event.text)
}
println()
client.models.unload(modelId)
} finally {
client.close()
}
}
/** Load [model], printing download progress, and return its model id. */
private suspend fun QvacClient.loadWithProgress(model: ModelConstant): String {
var result: LoadModelResponse? = null
models.loadWithProgress(model.src, model.engine, model.name).collect { event ->
when (event) {
is QvacProgressEvent.Progress -> printProgress(event.value)
is QvacProgressEvent.Result -> result = event.value
}
}
val loaded = checkNotNull(result) { "loadModel ended without a result" }
return loaded.modelId ?: error(loaded.error ?: "loadModel failed")
}
private fun printProgress(p: ModelProgressResponse) {
val line = "▸ Downloading %.0f%% (%.1f/%.1f MB)".format(p.percentage, p.downloaded / 1e6, p.total / 1e6)
if (System.console() != null) System.err.print("\r$line") else System.err.println(line)
if (p.percentage >= 100) System.err.println()
}Run the quickstart script:
./gradlew -p examples run -Pexample=QuickstartThe first run builds the SDK and its desktop worker, which takes a few minutes.
Running examples
Follow these instructions to run any example in this documentation:
- All examples are self-contained, runnable Kotlin programs in
packages/sdk-kotlin/examples/src/. Run one by file name, frompackages/sdk-kotlin:./gradlew -p examples run -Pexample=<FileName>. - Each file compiles on its own, so you can save your own copy of an example in
examples/src/and run it the same way../gradlew -p examples compileExamplescompiles them all. - Pass arguments with
--args, for example./gradlew -p examples run -Pexample=Transcription --args="path/to/audio.wav". Each example's header comment shows how to run it. - The JS/TS examples read worker settings from a
qvac.config.*file. The Kotlin examples pass them inline instead, as theconfigargument ofJvmBareKitTransport.connect(). - Some examples need companion files — sample audio, an image, or a dataset — that aren't part of the embedded code. These can be found in the examples directories of the JS/TS and Kotlin SDKs.
Connect
val transport = AndroidServiceTransport.connect(applicationContext)
val client = QvacClient(transport)
try {
println(client.heartbeat())
} finally {
client.close()
}The service runs in the app's private :qvac_worker process. Desktop JVM uses
JvmBareRpcTransport.connectResolved(), which starts the resolved @qvac/sdk
worker over a loopback channel. Kotlin/Native targets are not published until
they have tested worker hosts.
Completion and multimodal input
val run = client.completion.run(
modelId = modelId,
history = listOf(
QvacMessage.system("Be concise."),
QvacMessage.user(
"What is in this image?",
attachments = listOf(QvacAttachment("/data/user/0/app/files/photo.jpg")),
),
),
)
run.tokens.collect(::print)
val answer = run.final.await()
println("${answer.stopReason}: ${answer.stats?.tokensPerSecond} tok/s")Generation defaults to predict = -1, so chat does not stop at an arbitrary
token count. A run exposes events, tokens, toolCallEvents, accumulated
text, thinking text, tool calls, statistics, stop reason, and cancel().
Tool handlers
val weather = QvacTool(
name = "weather",
description = "Read local weather",
parameters = mapOf(
"city" to QvacToolParameter(QvacToolParameterType.STRING),
),
required = setOf("city"),
handler = { args -> JsonPrimitive("Sunny in ${args.getValue("city")}") },
)
val run = client.completion.orchestrate(
modelId = modelId,
history = listOf(QvacMessage.user("Do I need an umbrella in Rome?")),
tools = listOf(weather),
)
println(run.text())Capability examples
val transcript = client.speech.transcribe(
modelId = whisperModelId,
audio = QvacDataInput.FilePath("/data/user/0/app/files/sample.wav"),
)
val speech = client.speech.synthesize(ttsModelId, "Hello from QVAC")
val page = client.vision.ocr(ocrModelId, QvacDataInput.FilePath("/data/user/0/app/files/page.png"))
val vector = client.embeddings.embed(embeddingModelId, "private local AI")
val translation = client.translation.run(nmtModelId, "hello", modelType = "nmt")
val imageRun = client.media.diffusion(diffusionModelId, "a small red robot")
val imageBase64 = imageRun.final.await().data.first()
val classes = client.vision.classify(classifierModelId, imageBase64)
val hparams = client.vla.hparams(vlaModelId).hparams
val actions = client.vla.run(
modelId = vlaModelId,
images = listOf(frontCamera, wristCamera),
imgWidth = hparams.visionImageSize,
imgHeight = hparams.visionImageSize,
state = qvacVlaPadState(robotState, hparams.maxStateDim),
tokens = instructionTokens,
mask = instructionMask,
).actionsclient.media also wraps audio generation, video/world generation, and
upscaling. client.bci handles buffered and duplex neural transcription;
client.vla handles VLA hparams, inference, and embodiment switching.
The Android Feature Lab sample exercises completion, multimodal vision, OCR,
transcription, TTS, embeddings, translation, and classification with small
models suitable for a Pixel 8a.
API surface
| Kotlin entry point | Purpose |
|---|---|
client.models | registry, download, load, unload, and progress |
client.completion | completion runs and tool orchestration |
client.speech | transcription and TTS results |
client.vision | OCR and classification results |
client.translation | streaming translation run and cancellation |
client.embeddings | single and batch embeddings |
client.media | audio, diffusion, video, and upscale runs |
client.bci | buffered and duplex BCI transcription |
client.vla | VLA preprocessing, hparams, inference, and embodiment switching |
| generated client methods | typed operation for every contract method |
client.raw | JSON call, stream, and duplex escape hatch |
Generated request and response types live in io.tether.qvac.sdk.generated.schema;
io.tether.qvac.sdk.generated contains the model constants, error codes, and call
shapes in the shared contract.