compiled-model-app-scaffolding

CompiledModel app scaffolding

An app around a verified model is done when three things hold, in this order:

1. the app reproduces the model recipe's verification numbers on the accelerator the recipe verified — before any UI exists,
2. inference is confined and leak-free: one dispatcher owns the model, every buffer is closed, benchmarks include the readback,
3. the inference code is liftable — another app could take the helper file unchanged.

Scope: this scaffolds a new app from a model recipe. Migrating an existing TFLite Interpreter app to CompiledModel is a different task with its own skill, litert-compiled-model-migration. LLMs are served through the LiteRT-LM Engine rather than raw CompiledModel — samples/litert/text_to_speech_lm is the reference for that case; everything below is the non-LLM CompiledModel app.

Step 0: prove parity before building UI

The first milestone has no UI: a bare harness that loads the .tflite, runs the recipe's verification input on the target accelerator, and reproduces the numbers recorded in the recipe README (correlation, residency). If they do not reproduce, stop — that is an on-device-verification problem, and no amount of app code fixes it. Only then build the ViewModel and the screen.

The shape

One sample = one standalone Gradle project, four layers:

app/src/main/java/<pkg>/
  <Task>Helper.kt        inference infra: owns the CompiledModel and its
                         buffers; pre/post-processing; NO Android UI types
  MainViewModel.kt       state machine: drives the helper on a confined
                         dispatcher, exposes UiState
  UiState.kt             one immutable data class
  MainActivity.kt        ComponentActivity + setContent, nothing else
  view/                  Screen.kt, Theme.kt, Color.kt — Compose only
app/src/main/res/values/ strings.xml etc. — no UI strings in Kotlin

The worked example of the full shape is samples/litert/image_segmentation/kotlin_cpu_gpu/android (litert 2.3.0: the GPU accelerator ships in litert-gpu, so declare litert:2.3.0 and litert-gpu:2.3.0; without the second the runtime logs GPU accelerator could not be loaded and registered and a GPU + CPU set runs on the CPU — Galaxy S26. The sample keeps Kotlin 2.2.21 with -Xskip-metadata-version-check; the 2.3.0 classes carry Kotlin 2.4 metadata). The layer boundary that matters most is the helper's: pre/post-processing is part of the model contract (it must match what the recipe exported against), so it lives with the model, not in the screen. Reusable inference code is worth more than UI polish — a reader will lift <Task>Helper.kt and delete the rest.