kmplitert

KMPLiteRT 🚀

KMPLiteRT brings the power of Google LiteRT (formerly TensorFlow Lite) to the Kotlin Multiplatform ecosystem. It provides a unified, type-safe API to run machine learning inference across mobile, desktop, and web platforms.

[!CAUTION] UNDER ACTIVE DEVELOPMENT This project is currently in early development (Alpha). APIs are unstable and subject to change. Many platforms are not yet tested or validated. NOT RECOMMENDED FOR PRODUCTION USE.

---

✨ Features

• 🏗️ Unified API: Write your inference logic once in commonMain and run it everywhere.
• ⚡ Coroutine Support: First-class support for asynchronous initialization and inference.
• 📊 Metadata Inspection: Query tensor types, shapes (layout), and buffer requirements at runtime.
• 🚀 Hardware Acceleration: Support for CPU, GPU, and NPU where available on the platform.
• 🔒 Type-Safe Tensors: Direct and safe access to Float, Int, Long, Boolean, and Byte buffers via TFBuffer.
• 🖼️ Image Preprocessing: Built-in utilities for image resizing and format conversion.

---

🏛️ Architecture: kmplitert-core

kmplitert-core is the foundational module of the project. It abstracts the native LiteRT runtimes into a clean, idiomatic Kotlin API.

• Platform Abstraction: Uses Kotlin expect/actual to wrap JNI (Android), C-API via JNA (JVM), C-Interop (Native), and JS/Wasm JS wrappers.
• Efficient Buffers: The TFBuffer API manages memory efficiently across the Kotlin/Native boundary, minimizing copies.
• Consistent Lifecycle: Provides a predictable init() -> run() -> close() lifecycle across all platforms.

---

💻 Platform Support & Acceleration Matrix

Platform	Status	Implementation	Hardware Acceleration
Android	⚠️ Alpha	LiteRT Android SDK	CPU / GPU / NNAPI
JVM (Desktop)	⚠️ Alpha	LiteRT C API via JNA	CPU
Web (JS/Wasm)	⚠️ Alpha	@litertjs/core	Browser / WebGL / WebGPU
Native (Win/Linux/Mac)	⚠️ Alpha	LiteRT C API	CPU / GPU
iOS	🚧 Placeholder	-	Metal (Planned)

---

📦 Installation

Add the dependency to your commonMain source set in build.gradle.kts:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.leitingzi:kmplitert-core:0.1.1")
        }
    }
}

---

💡 Usage Examples

1. Basic Vector Inference with Metadata Inspection

Suitable for regression, classification, or any model processing simple numerical vectors.

import io.github.leitingzi.kmplitert.core.*

suspend fun runInference(modelPath: String) {
    // 1. Instantiate the compiler
    val compiler = LiteRTCompiler(filePath = modelPath, accelerator = LiteRTAccelerator.CPU)
    
    try {
        // 2. Initialize (load model and prepare environment)
        compiler.init()

        // 3. Inspect Model Metadata (Optional but helpful)
        val inputType = compiler.getInputTensorType("input_0")
        println("Input Type: ${inputType.elementType}, Shape: ${inputType.layout?.dimensions}")
        
        val reqs = compiler.getInputBufferRequirements("input_0")
        println("Required Buffer Size: ${reqs.bufferSize} bytes")

        // 4. Get managed buffers
        val inputs = compiler.getInputBuffers()
        val outputs = compiler.getOutputBuffers()

        // 5. Fill input data
        inputs[0].writeFloat(floatArrayOf(1.0f, 2.0f, 3.0f))

        // 6. Execute
        compiler.run(inputs, outputs)

        // 7. Extract results
        val result = outputs[0].readFloat()
        println("Inference result: ${result.contentToString()}")
        
    } finally {
        // 8. Always close to release native resources
        compiler.close()
    }
}

2. Image Classification

For computer vision models, use LiteRtImage for seamless preprocessing (resizing and format conversion).

import io.github.leitingzi.kmplitert.core.*

suspend fun classifyImage(modelPath: String, rawImageBytes: ByteArray) {
    val compiler = LiteRTCompiler(filePath = modelPath)
    
    try {
        compiler.init()
        val inputs = compiler.getInputBuffers()
        val outputs = compiler.getOutputBuffers()

        // 1. Preprocessing: Load -> Resize -> Convert to model format
        val inputData = LiteRtImage.fromBytes(rawImageBytes)
            .resize(224, 224)
            .toFloatArray() 

        inputs[0].writeFloat(inputData)
        compiler.run(inputs, outputs)

        val result = outputs[0].readFloat()
        val maxIndex = result.indices.maxByOrNull { result[it] }
        println("Identified class index: $maxIndex")
        
    } finally {
        compiler.close()
    }
}

---

📐 Model Input / Output Metadata

KMPLiteRT provides explicit APIs to query your model’s structure. This is essential for dynamic buffer allocation or validating that the model matches your expectations.

• getInputTensorType(name): Returns LiteRTTensorType containing the LiteRTElementType (FLOAT, INT, etc.) and LiteRTLayout (dimensions and rank).
• getInputBufferRequirements(name): Returns LiteRTBufferRequirements, describing the exact memory bufferSize and strides needed for a custom buffer.

While the application usually knows the model contract, these APIs enable building more generic tools and safer data pipelines.

---

🤝 Contributing

Contributions are welcome! If you encounter issues or have ideas for improvements, please:

• Open an Issue to report bugs or suggest features.
• Submit a Pull Request with your enhancements.

---

📄 License

Copyright 2026 leitingzi (yebintang)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

---

Made with ❤️ for the Kotlin Multiplatform community.

This site is open source. Improve this page.