Skip to main content

Getting started

There are two setup steps: install the JavaScript packages, then add Google's SDK to your app's Android build.

Before you integrate

Read Privacy & SDK terms first. Model inference requires an eligible Android device with AICore. An emulator can exercise UI and unavailable-provider behavior.

1. Install both packages​

For Android 2.0.0, install both packages in your app directory:

npm install @taaltreelabs/on-device-llm@^1.0.0 @taaltreelabs/on-device-llm-android@^2.0.0

Keep your app's lockfile. Android 2.0.0 requires shared ^1.0.0 (1.0.0 or newer within 1.x). Upgrade both packages together; shared 0.x is no longer supported.

The main package supplies the shared contract, router, context manager, and hooks. The Android package supplies createAndroidProvider() and the native bridge. You need a native development or production build containing the bridge, not Expo Go.

2. Configure all three native build settings​

Expo prebuild projects​

The package ships a config plugin that applies all three Android settings. Merge this into your app configuration:

app.json (excerpt)
{
  "expo": {
    "plugins": [
      [
        "@taaltreelabs/on-device-llm-android",
        {
          "mlKitGenAiPromptVersion": "1.0.0-beta4",
          "minSdkVersion": 26
        }
      ]
    ]
  }
}

For an app that also builds for iOS, add "@taaltreelabs/on-device-llm" to the plugins array and keep the Apple native-build setup. The two package plugins edit different platforms.

Run npx expo prebuild --platform android, then npx expo run:android --device. The Android plugin supports Groovy app Gradle files and preserves its settings across prebuild runs. Its options default to the values shown.

Manually maintained Android projects​

If you do not use the Expo plugin, apply all three settings below to your existing native project.

Add the pinned ML Kit dependency​

android/app/build.gradle
dependencies {
  implementation 'com.google.mlkit:genai-prompt:1.0.0-beta4'
}

The provider uses compileOnly for this SDK. Installing the npm package alone does not include ML Kit at runtime. Without the app dependency, availability() reports unsupportedPlatform; it does not download or silently enable the SDK. The existing google() Maven repository resolves this dependency.

Set the minimum Android SDK to at least 26​

android/gradle.properties
android.minSdkVersion=26

Keep a higher value if your app already requires one. Confirm that your native template reads this property; otherwise set its app minSdkVersion directly. The SDK's manifest requires API 26, so a lower app setting causes a manifest-merger failure. This installation floor does not establish AICore device eligibility.

Configure the app's Kotlin compiler​

Add this top-level block to the app's Groovy Gradle file:

android/app/build.gradle
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
  compilerOptions {
    freeCompilerArgs.add('-Xskip-metadata-version-check')
  }
}

The package's documented toolchain needs this app-level flag to read the newer ML Kit Kotlin metadata. The provider module's own flag does not cover the app's compile tasks. This is a compatibility workaround; validate your native build and runtime on an eligible device.

Preserve reflective classes in minified release builds​

The package includes the consumer R8/ProGuard rules and their Gradle registration. They preserve the classes used by the provider's reflective engine and ML Kit presence checks. No manual rules copy is required. Test an actual minified release build on eligible hardware.

Rebuild the app​

npx expo run:android --device

For Expo/CNG, use the bundled plugin above so native regeneration preserves all three settings.

Keep the SDK version pinned. An upgrade requires reviewing compatibility and validating native behavior again.

3. Check availability before generating​

import { createAndroidProvider } from '@taaltreelabs/on-device-llm-android';

const android = createAndroidProvider();
const availability = await android.availability();

if (!availability.available) {
  console.log('Unavailable:', availability.reason);
} else {
  try {
    const result = await android.generate({
      messages: [{ role: 'user', content: 'Explain how a rainbow forms.' }],
    });
    console.log(result.text);
  } catch (error) {
    // A successful availability check does not guarantee generation.
    console.error('Generation failed', error);
  }
}

AndroidProviderConfig currently accepts an optional id. It has no locale option. The Android native module is named OnDeviceLlmAndroid, separate from the Apple module.

Next steps​

Follow Usage & routing to connect React hooks or a cloud fallback. Use Compatibility & limitations to plan hardware validation and diagnose missing-module or unsupported-device states.