Skip to content

README.md

Latest commit

 

History

History
171 lines (133 loc) · 7.58 KB

README.md

File metadata and controls

171 lines (133 loc) · 7.58 KB
Raw

Android JNI Bridge Architecture

Overview

Android bindings provide a Kotlin API for GenieX using a JNI bridge pattern with 4 layers:

┌─────────────────────────────────────────────────────────┐
│ Layer 4: Public API (Kotlin)                          │
│ ModelWrapper.kt - Coroutine-based high-level API      │
│ (LlmWrapper, VlmWrapper)                              │
└────────────────┬────────────────────────────────────────┘
                 │ calls
┌────────────────▼────────────────────────────────────────┐
│ Layer 3: JNI Interface (Kotlin)                        │
│ Model.kt - Declares external native methods           │
│ (Llm, Vlm)                                            │
└────────────────┬────────────────────────────────────────┘
                 │ JNI boundary
┌────────────────▼────────────────────────────────────────┐
│ Layer 2: JNI Bridge (C++)                             │
│ model_bridge_jni.cpp - Implements JNI methods         │
│ Java_com_geniex_sdk_jni_Model_* functions               │
└────────────────┬────────────────────────────────────────┘
                 │ calls C API
┌────────────────▼────────────────────────────────────────┐
│ Layer 1: Core Library (C)                             │
│ libgeniex.so - Provides ml_* API from ml.h       │
│ (ml_llm_create, ml_llm_generate, etc.)               │
└─────────────────────────────────────────────────────────┘

Component Structure

Each AI capability (LLM, VLM) follows this pattern:

LLM (Large Language Model) Example:

Layer 4: LlmWrapper.kt (Public API)

  • Path: app/src/main/java/com/geniex/sdk/LlmWrapper.kt
  • Purpose: High-level Kotlin API with coroutine support
  • Features: Builder pattern, Flow-based streaming, lifecycle management
  • Usage: LlmWrapper.builder().llmCreateInput(...).build()

Layer 3: Llm.kt (JNI Interface)

  • Path: app/src/main/java/com/geniex/sdk/jni/Llm.kt
  • Purpose: Internal class declaring native JNI methods
  • Methods: 
    external fun create(llmCreateInputObj: LlmCreateInput): Long
external fun destroy(handle: Long)
external fun generate(handle: Long, prompt: String, config: GenerationConfig, cb: LLMTokenCallback): LlmGenerateResult
external fun stopStream(handle: Long)
external fun applyChatTemplate(handle: Long, messages: Array<ChatMessage>, tools: String?, enableThinking: Boolean): LlmApplyChatTemplateOutput

Layer 2: llm_bridge_jni.cpp (JNI Bridge)

  • Path: app/src/main/cpp/llm_bridge_jni.cpp
  • Purpose: Implements JNI methods, converts Java/Kotlin types to C types
  • JNI Functions:
    • Java_com_geniex_sdk_jni_Llm_create → calls ml_llm_create()
    • Java_com_geniex_sdk_jni_Llm_destroy → calls ml_llm_destroy()
    • Java_com_geniex_sdk_jni_Llm_generate → calls ml_llm_generate()
    • Java_com_geniex_sdk_jni_Llm_stopStream → manages stop flags
    • Java_com_geniex_sdk_jni_Llm_applyChatTemplate → calls ml_llm_apply_chat_template()

Layer 1: libgeniex.so (Core Library)

  • Path: ../../../build-android/out/libgeniex.so
  • API Header: ../../../include/ml.h
  • Purpose: C API providing mlllm* functions
  • Built from: ../../../src/*.cpp (llm.cpp, vlm.cpp, etc.)

Other Components (Same 4-layer pattern):

Component Wrapper JNI Interface JNI Bridge Core API
Vision-Language VlmWrapper.kt Vlm.kt vlm_bridge_jni.cpp mlvlm*

Build System

Native Library Compilation

  • Build Script: ../../../build_android.sh
  • CMake Entry: app/src/main/cpp/CMakeLists.txt
  • Output:
    • libnpu_jni.so (JNI bridge wrapper loaded by GenieXSdk.kt)
    • libgeniex.so (core ML library linked by JNI wrapper)
    • Plugin libraries: libgeniex_plugin.so (NPU backend for NPU acceleration)

Library Loading

  • GenieXSdk.kt: Initializes SDK and loads native libraries 
    init {
    System.loadLibrary("npu_jni")  // Loads Layer 2 JNI bridge
}

Plugin Registration

  • NPU Backend: Provides NPU acceleration for Qualcomm Snapdragon (using QNN library internally)
  • Path: ../../../build-android/out/npu/
  • Registration: GenieXSdk.init() calls registerPlugin() to dynamically load plugin libraries

Directory Structure

bindings/android/
├── app/
│   ├── src/main/
│   │   ├── cpp/                      # Layer 2: JNI Bridge (C++)
│   │   │   ├── llm_bridge_jni.cpp
│   │   │   ├── vlm_bridge_jni.cpp
│   │   │   ├── geniex_sdk.cpp          # SDK initialization & plugin registration
│   │   │   ├── jniutils.cpp/.h       # JNI type conversion utilities
│   │   │   ├── jni_cb.cpp/.h         # Callback handling for streaming
│   │   │   ├── qnn/CMakeLists.txt    # NPU backend build config (QNN library)
│   │   │   └── CMakeLists.txt
│   │   └── java/com/geniex/sdk/
│   │       ├── jni/                  # Layer 3: JNI Interface (Kotlin)
│   │       │   ├── Llm.kt
│   │       │   └── Vlm.kt
│   │       ├── LlmWrapper.kt         # Layer 4: Public API
│   │       ├── VlmWrapper.kt
│   │       ├── GenieXSdk.kt            # SDK entry point
│   │       └── bean/                 # Data classes
│   └── build.gradle.kts              # Build configuration
└── README.md                         # This file

../../include/ml.h                    # Layer 1: Core C API header
../../src/*.cpp                       # Layer 1: Core implementation
../../build-android/out/
├── libgeniex.so                 # Layer 1: Core library
└── npu/                              # NPU plugin libraries (QNN-based)
    └── libgeniex_plugin.so

Publish to Maven

Preparations for Releasing Android SDK aar

Generating the repo folder in maven format.

Under GenieX-bridge/bindings/android:

  1. Modify tmpVersion in app/update.gradle to the new version.
  2. Sync project with Gradle files.
  3. Execute ./gradlew assembleRelease.
  4. Execute ./gradlew publish to obtain the repo folder.

Publishing to Maven Central

TODO: document the Maven Central publishing procedure.

Publishing to GitHub

TODO: document the GitHub-based Android artifact publishing instructions.

Logging

SDK logs are routed to logcat under the tag GenieXSdk at the corresponding Android priority (VERBOSE/DEBUG/INFO/WARN/ERROR). Filter from your app via the standard logcat tooling:

adb logcat -s GenieXSdk