DeliteAI Android SDK¶

A powerful On-Device Android SDK for creating real-time AI-powered experiences natively integrated in your applications.

Table of Contents¶

Android Project Overview
Prerequisites
Quick Start
Configuration
Integrating DeliteAI Android SDK into your App
Integration Example
Running Tests
API Reference

Android Project Overview¶

The DeliteAI Android SDK features a modular architecture designed for flexibility and separation of concerns. It leverages a high-performance native C++ core while exposing a clean and developer-friendly Kotlin API.

Project Structure¶

sdks/android/
├── app/                   # Sample application demonstrating SDK usage
├── buildSrc/              # Gradle build configuration and dependencies
├── nimblenet_ktx/         # Kotlin SDK - Main developer interface
├── nimblenet_core/        # Native bridge and C++ core runtime
└── benchmarking/          # Performance benchmarking tools

Modules¶

1. `buildSrc`¶

Contains centralized Gradle dependencies, versions, and build tasks shared across all modules. This ensures consistent dependency management and build configuration.

2. `nimblenet_ktx`¶

The primary Kotlin SDK module that developers interact with. It provides:

High-level Kotlin APIs for AI model execution
Event tracking and analytics
Configuration management
Coroutine-based asynchronous operations

3. `nimblenet_core`¶

The native bridge module that contains:

JNI bindings to the C++ core runtime
Native library management
Performance-critical operations
Symlinked core runtime components

4. `benchmarking`¶

Performance measurement tools including:

Python scripts for SDK benchmarking
Memory usage analysis
Latency measurement utilities

Build Flavors¶

The SDK supports two build flavors to accommodate different use cases:

1. `External` (Release)¶

Standard production-ready build
Optimized for performance and size
Contains all essential LLM and AI capabilities
Recommended for production applications

2. `Internal` (Debug)¶

Extended debugging capabilities over External flavor
Development utilities (database reset, cache management)

Prerequisites¶

Before you begin, ensure your development environment meets the following requirements:

1. Android Studio¶

Version: Arctic Fox (2020.3.1) or later
Gradle: 7.4 or later
Build Tools: 33.0.0 or later

2. Java Development Kit (JDK)¶

Version: JDK 11 or later
Ensure JAVA_HOME environment variable is properly set

3. Android Debug Bridge (ADB)¶

Required for device testing and debugging
Usually installed with Android SDK Platform Tools
Verify installation: adb version

4. Device Requirements¶

Minimum API Level: 21 (Android 5.0)
Architecture: ARM64 (arm64-v8a) recommended
RAM: 4GB minimum, 8GB recommended
Storage: 2GB free space for models and cache

5. Project Configuration¶

Create a local.properties file in the root of deliteAI/sdks/android to configure your credentials and build settings:

# Android SDK path
sdk.dir=/path/to/android/sdk

# NimbleNet Configuration (Required)
APP_CLIENT_ID=your_client_id
APP_CLIENT_SECRET=your_client_secret
APP_HOST=https://your-api-endpoint.com

# Optional: Android Test Configuration
ANDROID_TEST_CLIENT_ID=test_client_id
ANDROID_TEST_CLIENT_SECRET=test_client_secret
ANDROID_TEST_HOST=https://test-api-endpoint.com

# Optional: Remote Logging
REMOTE_LOGGER_KEY=your_logger_key
REMOTE_LOGGER_URL=https://your-logging-endpoint.com

# Optional: Publishing (For SDK developers only)
ANDROID_DEV_AWS_ACCESS_KEY_ID=your_aws_key
ANDROID_DEV_AWS_SECRET_ACCESS_KEY=your_aws_secret
ANDROID_DEV_AWS_S3_URL=your_s3_url
OSS_USER=your_maven_user
OSS_PASSWORD=your_maven_password

# Optional: Code Signing (For release builds)
storeFile=/path/to/keystore.jks
storePassword=your_store_password
keyPassword=your_key_password
keyAlias=your_key_alias

6. External Dependencies¶

Run the following command to download all the required dependencies:

cd "$(git rev-parse --show-toplevel)" && ./setup.sh --sdk android

Quick Start¶

Follow these steps to get the sample application running in minutes.

Run Sample Application¶

Using Android Studio¶

Open deliteAI/sdks/android in Android Studio
Wait for Gradle sync to complete
Select the app module
Click Run or press Ctrl+R (Windows/Linux) / Cmd+R (Mac)

Using Command Line¶

cd deliteAI/sdks/android

# Build and install debug version
./gradlew assembleExternalDebug
./gradlew installExternalDebug

# Launch the app
adb shell monkey -p dev.deliteai.android.sampleapp.debug -c android.intent.category.LAUNCHER 1

Configuration¶

Note: If you’re using the pre-released version of the SDK from our repository, you can skip this section entirely.

This section describes how to configure the SDK for development and release builds. It is primarily relevant for:

SDK maintainers and contributors
Organizations creating custom SDK builds
Developers who need to modify SDK behavior at build time

The SDK’s native behavior is controlled by deliteAI/config.yml.

common:
  sdk_version: "1.0.0"
  cmake_args: "-DONNX_EXECUTOR=1 -DONNXGENAI_EXECUTOR=1 -DCMAKE_BUILD_TYPE=Release -DSCRIPTING=1"

android:
  ndk: "25.1.8937393"
  cmake_args: "-DANDROID_STL=c++_shared -DEXECUTORCH_EXECUTOR=0 -DONNXBuild=1_21_0_full"

Configuration Options¶

sdk_version: Defines the SDK version for release builds.
common.cmake_args: Common CMake arguments applied across all platforms (Android, iOS).
android.cmake_args: Additional CMake arguments applied only to the Android build.
android.ndk: Specifies the Android NDK version used for native C++ compilation.

(TODO: replace with working link) For a complete list of supported flags, refer to our CoreRuntime Documentation.

Integrating DeliteAI Android SDK into your App¶

Add the following dependencies to your module-level build.gradle.kts or build.gradle file.

Gradle (Kotlin DSL)¶

dependencies {
    implementation("dev.deliteai:nimblenet_ktx:x.y.z")
    implementation("dev.deliteai:nimblenet_core:x.y.z")
}

Gradle (Groovy)¶

dependencies {
    implementation 'dev.deliteai:nimblenet_ktx:x.y.z'
    implementation 'dev.deliteai:nimblenet_core:x.y.z'
}

Integration Example¶

This section demonstrates a complete integration workflow for the DeliteAI Android SDK. Follow these steps to get started with implementing AI-powered functionality in your Android application.

Overview¶

The integration workflow includes:

Initialize the SDK - Configure and start the NimbleNet SDK
Check SDK readiness - Verify the SDK is ready for use
Execute AI models - Run Python workflow scripts and call Python methods with AI logic from Kotlin
Track events - Optional analytics and event tracking

1. Initialize the SDK¶

The SDK supports two mutually exclusive initialization modes:

Online Mode¶

Downloads all required assets (models, scripts, configuration) on first launch
Caches assets locally for subsequent offline use
Automatically checks for updates when online

Offline Mode (Default)¶

Bundles all required assets in your app’s assets/ folder at build time
No network calls at runtime - perfect for fully offline deployments

Example Python Script¶

For offline mode, create a Python script “deliteai_script.py” with your AI workflow:

def myFunction(inputMap):
    text = inputMap["input_key"]
    print(text)  # Visible in Logcat
    return {"output_key": text + "Output"}

Convert Script to AST (Offline Only)¶

Android assets cannot contain raw Python source files. Convert your script to AST format:

cd "$(git rev-parse --show-toplevel)"
python3 coreruntime/scripts/gen_python_ast.py <path to deliteai_script.py>

This generates deliteai_script.ast. Place this file in app/src/main/assets/.

SDK Initialization Code¶

import dev.deliteai.NimbleNet
import dev.deliteai.NimbleNetConfig
import dev.deliteai.NIMBLENET_VARIANTS
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

private fun initializeNimbleNet() {
    val offlineConfig = NimbleNetConfig(online = false)

    // Configuration for offline mode assets
    val assetsJsonStr = """
        [
            {
                "name": "workflow_script",
                "version": "1.0.0",
                "type": "script",
                "location": {
                    "path": "deliteai_script.ast"
                }
            }
        ]"""

    val assetsJson = JSONArray(assetsJsonStr)

    CoroutineScope(Dispatchers.Default).launch {
        // Initialize SDK in offline mode
        val result = NimbleNet.initialize(applicationContext, offlineConfig, assetsJson)

        if (result.status) {
            Log.d("NimbleNet", "SDK initialized successfully")
            // SDK is ready for use
        } else {
            Log.e("NimbleNet", "Initialization failed: ${result.error?.message}")
            // Handle initialization failure
        }
    }
}

2. Check SDK Readiness¶

Before using SDK functionality, verify it’s ready:

private fun checkSDKReadiness() {
    val readyStatus = NimbleNet.isReady()

    if (readyStatus.status) {
        Log.d("NimbleNet", "SDK is ready for use")
        // Safe to call other NimbleNet methods
    } else {
        Log.w("NimbleNet", "SDK not ready: ${readyStatus.error?.message}")
        // Wait for initialization to complete or handle the error
    }
}

3. Execute AI Models¶

Run Python workflows from your Kotlin code:

import dev.deliteai.datamodels.NimbleNetTensor
import dev.deliteai.impl.common.DATATYPE

private fun runPyWorkflow() {
    val inputs = hashMapOf(
        "input_key" to NimbleNetTensor(
            data = "hello world",
            datatype = DATATYPE.STRING,
            shape = intArrayOf() // Populate only if data is an array
        )
    )

    CoroutineScope(Dispatchers.Default).launch {
        // The hashmap inputs (defined above) will be passed to the Python function named myFunction,
        // and the data can be accessed as "hello world" using inputs["input_key"]
        val result = NimbleNet.runMethod(
            methodName = "myFunction",
            inputs = inputs
        )

        withContext(Dispatchers.Main) {
            if (result.status) {
                // A dictionary will be returned by the Python script and you can access the data
                // using the key set in the Python script, in our example, that's "output_key"
                val outputs = result.payload!!
                val output = outputs["output_key"]?.data as? String

                Log.d("NimbleNet", "Output: $output")
            } else {
                Log.e("NimbleNet", "Failed to get output: ${result.error?.message}")
            }
        }
    }
}

4. Track Events (Optional)¶

Track user interactions and custom analytics events in Python workflow scripts for use in your AI logic:

private fun trackUserInteraction() {
    val eventData = mapOf(
        "user_id" to 12345,
        "item_id" to 8001,
        "action" to "click",
        "category" to "electronics",
        "price" to 299.99,
        "timestamp" to System.currentTimeMillis()
    )

    val result = NimbleNet.addEvent(
        eventData = eventData,
        tableName = "UserInteractionsTable"
    )

    if (result.status) {
        Log.d("NimbleNet", "Event tracked successfully")
    } else {
        Log.e("NimbleNet", "Failed to track event: ${result.error?.message}")
    }
}

Running Tests¶

The DeliteAI Android SDK includes comprehensive test suites to ensure reliability and functionality. You can run both unit tests and instrumented Android tests.

Unit Tests¶

Run unit tests to verify core business logic and SDK functionality:

./gradlew :nimblenet_ktx:testExternalDebugUnitTest

Android Tests¶

Run instrumented tests on a connected device or emulator:

./gradlew :nimblenet_ktx:connectedExternalDebugAndroidTest

Prerequisites for Android Tests:

Connected Android device or running emulator
Device meets the minimum requirements listed in Prerequisites
Proper configuration in local.properties