react-native-litert-lm 0.1.0

package/cpp/include/README.md

@@ -0,0 +1,34 @@
+# LiteRT-LM Headers Fallback
+
+This directory is a fallback location for LiteRT-LM C++ headers when Prefab doesn't expose them correctly.
+
+## If Headers Are Missing
+
+If you get compilation errors like `litert/lm/engine.h: No such file or directory`, you need to manually copy LiteRT-LM headers here:
+
+1. Clone LiteRT-LM repository:
+
+   ```bash
+   git clone https://github.com/google-ai-edge/LiteRT-LM.git /tmp/LiteRT-LM
+   ```
+
+2. Copy the headers:
+   ```bash
+   cp -r /tmp/LiteRT-LM/runtime/include/litert ./
+   ```
+
+The expected directory structure after copying:
+
+```
+cpp/include/
+└── litert/
+    └── lm/
+        ├── engine.h
+        ├── conversation.h
+        ├── types.h
+        └── ...
+```
+
+## Note
+
+The ideal scenario is that the Maven package `litertlm-android:0.9.0-alpha01` exposes headers via Prefab, making this directory unnecessary. This is just a fallback.

package/lib/index.d.ts

@@ -0,0 +1,82 @@
+import type { LiteRTLM, Backend } from "./specs/LiteRTLM.nitro";
+export type { LiteRTLM, LLMConfig, Message, Backend, Role, GenerationStats, } from "./specs/LiteRTLM.nitro";
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from 'react-native-litert-lm';
+ *
+ * // Basic usage with Gemma 3n
+ * const llm = createLLM();
+ * llm.loadModel('/path/to/gemma-3n-e2b.litertlm', {
+ *   backend: 'gpu',
+ *   temperature: 0.7,
+ *   maxTokens: 512
+ * });
+ *
+ * // Simple text generation
+ * const response = llm.sendMessage('Hello, how are you?');
+ * console.log(response);
+ *
+ * // Streaming generation
+ * llm.sendMessageAsync('Tell me about React Native', (token, done) => {
+ *   process.stdout.write(token);
+ *   if (done) console.log('\n--- Done ---');
+ * });
+ *
+ * // Check stats
+ * const stats = llm.getStats();
+ * console.log(`Generated at ${stats.tokensPerSecond} tokens/sec`);
+ *
+ * // Cleanup
+ * llm.close();
+ * ```
+ */
+export declare function createLLM(): LiteRTLM;
+/**
+ * Pre-defined model identifiers for common models.
+ * Use with model download utilities or as reference.
+ */
+export declare const Models: {
+    /** Gemma 3n E2B (2B parameters, efficient) */
+    readonly GEMMA_3N_E2B: "gemma-3n-E2B-it-litert-lm-preview";
+    /** Gemma 3n E4B (4B parameters, higher quality) */
+    readonly GEMMA_3N_E4B: "gemma-3n-E4B-it-litert-lm-preview";
+    /** Gemma 3 1B (smallest Gemma) */
+    readonly GEMMA_3_1B: "Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096";
+    /** Phi-4 Mini Instruct */
+    readonly PHI_4_MINI: "Phi-4-mini-instruct_multi-prefill-seq_q8_ekv4096";
+    /** Qwen 2.5 1.5B Instruct */
+    readonly QWEN_2_5_1_5B: "Qwen2.5-1.5B-Instruct_multi-prefill-seq_q8_ekv4096";
+};
+export type ModelId = (typeof Models)[keyof typeof Models];
+/**
+ * Get the recommended backend for the current platform.
+ * Returns 'gpu' for most devices as it provides the best balance of speed and compatibility.
+ *
+ * @returns The recommended backend ('gpu' for most cases)
+ *
+ * @example
+ * ```typescript
+ * const backend = getRecommendedBackend();
+ * llm.loadModel(path, { backend });
+ * ```
+ */
+export declare function getRecommendedBackend(): Backend;
+/**
+ * Check if a backend configuration is supported on the current platform.
+ * Returns a warning message if the configuration may have issues.
+ *
+ * @param backend The backend to check
+ * @returns Warning message if there may be issues, undefined if OK
+ *
+ * @example
+ * ```typescript
+ * const warning = checkBackendSupport('npu');
+ * if (warning) {
+ *   console.warn(warning);
+ * }
+ * ```
+ */
+export declare function checkBackendSupport(backend: Backend): string | undefined;

package/lib/index.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Models = void 0;
+exports.createLLM = createLLM;
+exports.getRecommendedBackend = getRecommendedBackend;
+exports.checkBackendSupport = checkBackendSupport;
+const react_native_nitro_modules_1 = require("react-native-nitro-modules");
+const react_native_1 = require("react-native");
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * @example
+ * ```typescript
+ * import { createLLM } from 'react-native-litert-lm';
+ *
+ * // Basic usage with Gemma 3n
+ * const llm = createLLM();
+ * llm.loadModel('/path/to/gemma-3n-e2b.litertlm', {
+ *   backend: 'gpu',
+ *   temperature: 0.7,
+ *   maxTokens: 512
+ * });
+ *
+ * // Simple text generation
+ * const response = llm.sendMessage('Hello, how are you?');
+ * console.log(response);
+ *
+ * // Streaming generation
+ * llm.sendMessageAsync('Tell me about React Native', (token, done) => {
+ *   process.stdout.write(token);
+ *   if (done) console.log('\n--- Done ---');
+ * });
+ *
+ * // Check stats
+ * const stats = llm.getStats();
+ * console.log(`Generated at ${stats.tokensPerSecond} tokens/sec`);
+ *
+ * // Cleanup
+ * llm.close();
+ * ```
+ */
+function createLLM() {
+    return react_native_nitro_modules_1.NitroModules.createHybridObject("LiteRTLM");
+}
+/**
+ * Pre-defined model identifiers for common models.
+ * Use with model download utilities or as reference.
+ */
+exports.Models = {
+    /** Gemma 3n E2B (2B parameters, efficient) */
+    GEMMA_3N_E2B: "gemma-3n-E2B-it-litert-lm-preview",
+    /** Gemma 3n E4B (4B parameters, higher quality) */
+    GEMMA_3N_E4B: "gemma-3n-E4B-it-litert-lm-preview",
+    /** Gemma 3 1B (smallest Gemma) */
+    GEMMA_3_1B: "Gemma3-1B-IT_multi-prefill-seq_q4_ekv4096",
+    /** Phi-4 Mini Instruct */
+    PHI_4_MINI: "Phi-4-mini-instruct_multi-prefill-seq_q8_ekv4096",
+    /** Qwen 2.5 1.5B Instruct */
+    QWEN_2_5_1_5B: "Qwen2.5-1.5B-Instruct_multi-prefill-seq_q8_ekv4096",
+};
+/**
+ * Get the recommended backend for the current platform.
+ * Returns 'gpu' for most devices as it provides the best balance of speed and compatibility.
+ *
+ * @returns The recommended backend ('gpu' for most cases)
+ *
+ * @example
+ * ```typescript
+ * const backend = getRecommendedBackend();
+ * llm.loadModel(path, { backend });
+ * ```
+ */
+function getRecommendedBackend() {
+    // GPU is the recommended default for all platforms
+    // It provides good performance and broad compatibility
+    return "gpu";
+}
+/**
+ * Check if a backend configuration is supported on the current platform.
+ * Returns a warning message if the configuration may have issues.
+ *
+ * @param backend The backend to check
+ * @returns Warning message if there may be issues, undefined if OK
+ *
+ * @example
+ * ```typescript
+ * const warning = checkBackendSupport('npu');
+ * if (warning) {
+ *   console.warn(warning);
+ * }
+ * ```
+ */
+function checkBackendSupport(backend) {
+    if (backend === "npu") {
+        if (react_native_1.Platform.OS === "android") {
+            return "NPU backend requires compatible hardware (Qualcomm Hexagon, MediaTek APU, etc.). Will fall back to GPU if unavailable.";
+        }
+        if (react_native_1.Platform.OS === "ios") {
+            return "NPU/CoreML is not yet supported on iOS. LiteRT-LM iOS support is pending.";
+        }
+    }
+    if (react_native_1.Platform.OS === "ios" && backend !== "cpu") {
+        return "LiteRT-LM iOS is not yet released. Only CPU backend may work via fallback.";
+    }
+    return undefined;
+}

package/lib/specs/LiteRTLM.nitro.d.ts

@@ -0,0 +1,165 @@
+import type { HybridObject } from "react-native-nitro-modules";
+/**
+ * Backend types for LLM inference.
+ * - 'cpu': CPU inference (slowest, always available)
+ * - 'gpu': GPU acceleration (fast, recommended for most devices)
+ * - 'npu': NPU/Neural Engine (fastest on supported hardware)
+ *
+ * @remarks
+ * NPU acceleration requires compatible hardware (e.g., Qualcomm Hexagon, MediaTek APU).
+ * If NPU is unavailable, LiteRT-LM automatically falls back to GPU.
+ */
+export type Backend = "cpu" | "gpu" | "npu";
+/**
+ * Message roles for conversation.
+ */
+export type Role = "user" | "model" | "system";
+/**
+ * Configuration options for loading an LLM.
+ */
+export interface LLMConfig {
+    /**
+     * Primary compute backend for text generation.
+     * - 'cpu': CPU inference (slower but always available)
+     * - 'gpu': GPU acceleration (fast, recommended)
+     * - 'npu': NPU/Neural Engine (fastest on supported devices)
+     *
+     * If not specified, defaults to 'gpu'.
+     * If specified backend is unavailable, falls back automatically.
+     *
+     * @remarks
+     * Vision encoder is always set to GPU (required by Gemma 3n).
+     * Audio encoder is always set to CPU (optimal for audio processing).
+     *
+     * @default 'gpu'
+     */
+    backend?: Backend;
+    /**
+     * Maximum number of tokens to generate.
+     * @default 1024
+     */
+    maxTokens?: number;
+    /**
+     * Sampling temperature (0.0 = deterministic, 1.0 = creative).
+     * @default 0.7
+     */
+    temperature?: number;
+    /**
+     * Top-K sampling (number of top tokens to consider).
+     * @default 40
+     */
+    topK?: number;
+    /**
+     * Top-P (nucleus) sampling threshold.
+     * @default 0.95
+     */
+    topP?: number;
+}
+/**
+ * A simple message in the conversation.
+ * For multimodal, use sendMessageWithImage/sendMessageWithAudio instead.
+ */
+export interface Message {
+    /** Role of the message sender */
+    role: Role;
+    /** Text content of the message */
+    content: string;
+}
+/**
+ * Generation statistics returned after completion.
+ */
+export interface GenerationStats {
+    /** Number of tokens in the prompt */
+    promptTokens: number;
+    /** Number of tokens generated */
+    completionTokens: number;
+    /** Total tokens (prompt + completion) */
+    totalTokens: number;
+    /** Time to first token in milliseconds */
+    timeToFirstToken: number;
+    /** Total generation time in milliseconds */
+    totalTime: number;
+    /** Tokens per second */
+    tokensPerSecond: number;
+}
+/**
+ * LiteRT-LM: High-performance LLM inference engine.
+ * Supports Gemma 3n, Phi-4, Qwen, and other .litertlm models.
+ *
+ * @example
+ * ```typescript
+ * const llm = createLLM();
+ * llm.loadModel('/path/to/gemma-3n.litertlm', { backend: 'gpu' });
+ *
+ * // Blocking generation
+ * const response = llm.sendMessage('What is the capital of France?');
+ *
+ * // Streaming generation
+ * llm.sendMessageAsync('Tell me a story', (token, done) => {
+ *   process.stdout.write(token);
+ * });
+ *
+ * llm.close();
+ * ```
+ */
+export interface LiteRTLM extends HybridObject<{
+    ios: "c++";
+    android: "kotlin";
+}> {
+    /**
+     * Load a .litertlm model file.
+     * @param modelPath Absolute path to the .litertlm file.
+     * @param config Optional configuration for backend and sampling.
+     * @throws Error if the model cannot be loaded.
+     */
+    loadModel(modelPath: string, config?: LLMConfig): void;
+    /**
+     * Send a text message and get the complete response (blocking).
+     * @param message User message text.
+     * @returns The model's response text.
+     */
+    sendMessage(message: string): string;
+    /**
+     * Send a text message with an image (multimodal).
+     * @param message User message text.
+     * @param imagePath Absolute path to an image file.
+     * @returns The model's response text.
+     */
+    sendMessageWithImage(message: string, imagePath: string): string;
+    /**
+     * Send a text message with audio (multimodal).
+     * @param message User message text.
+     * @param audioPath Absolute path to an audio file (WAV).
+     * @returns The model's response text.
+     */
+    sendMessageWithAudio(message: string, audioPath: string): string;
+    /**
+     * Send a message with streaming response.
+     * Tokens are delivered via callback as they are generated.
+     * @param message User message text.
+     * @param onToken Callback invoked for each token (token, isDone).
+     */
+    sendMessageAsync(message: string, onToken: (token: string, done: boolean) => void): void;
+    /**
+     * Get the current conversation history.
+     * @returns Array of messages in the conversation.
+     */
+    getHistory(): Message[];
+    /**
+     * Clear the conversation context and start fresh.
+     */
+    resetConversation(): void;
+    /**
+     * Check if a model is loaded and ready for inference.
+     */
+    isReady(): boolean;
+    /**
+     * Get the last generation statistics.
+     */
+    getStats(): GenerationStats;
+    /**
+     * Release all native resources.
+     * Call this when done with the LLM instance.
+     */
+    close(): void;
+}

package/lib/specs/LiteRTLM.nitro.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/nitrogen/generated/.gitattributes

@@ -0,0 +1 @@
+** linguist-generated=true

package/nitrogen/generated/android/LiteRTLM+autolinking.cmake

@@ -0,0 +1,81 @@
+#
+# LiteRTLM+autolinking.cmake
+# This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+# https://github.com/mrousavy/nitro
+# Copyright © Marc Rousavy @ Margelo
+#
+
+# This is a CMake file that adds all files generated by Nitrogen
+# to the current CMake project.
+#
+# To use it, add this to your CMakeLists.txt:
+# ```cmake
+# include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/LiteRTLM+autolinking.cmake)
+# ```
+
+# Define a flag to check if we are building properly
+add_definitions(-DBUILDING_LITERTLM_WITH_GENERATED_CMAKE_PROJECT)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_definitions(-DRN_SERIALIZABLE_STATE)
+
+# Add all headers that were generated by Nitrogen
+include_directories(
+  "../nitrogen/generated/shared/c++"
+  "../nitrogen/generated/android/c++"
+  "../nitrogen/generated/android/"
+)
+
+# Add all .cpp sources that were generated by Nitrogen
+target_sources(
+  # CMake project name (Android C++ library name)
+  LiteRTLM PRIVATE
+  # Autolinking Setup
+  ../nitrogen/generated/android/LiteRTLMOnLoad.cpp
+  # Shared Nitrogen C++ sources
+  ../nitrogen/generated/shared/c++/HybridLiteRTLMSpec.cpp
+  # Android-specific Nitrogen C++ sources
+  ../nitrogen/generated/android/c++/JHybridLiteRTLMSpec.cpp
+)
+
+# From node_modules/react-native/ReactAndroid/cmake-utils/folly-flags.cmake
+# Used in node_modules/react-native/ReactAndroid/cmake-utils/ReactNative-application.cmake
+target_compile_definitions(
+  LiteRTLM PRIVATE
+  -DFOLLY_NO_CONFIG=1
+  -DFOLLY_HAVE_CLOCK_GETTIME=1
+  -DFOLLY_USE_LIBCPP=1
+  -DFOLLY_CFG_NO_COROUTINES=1
+  -DFOLLY_MOBILE=1
+  -DFOLLY_HAVE_RECVMMSG=1
+  -DFOLLY_HAVE_PTHREAD=1
+  # Once we target android-23 above, we can comment
+  # the following line. NDK uses GNU style stderror_r() after API 23.
+  -DFOLLY_HAVE_XSI_STRERROR_R=1
+)
+
+# Add all libraries required by the generated specs
+find_package(fbjni REQUIRED) # <-- Used for communication between Java <-> C++
+find_package(ReactAndroid REQUIRED) # <-- Used to set up React Native bindings (e.g. CallInvoker/TurboModule)
+find_package(react-native-nitro-modules REQUIRED) # <-- Used to create all HybridObjects and use the Nitro core library
+
+# Link all libraries together
+target_link_libraries(
+        LiteRTLM
+        fbjni::fbjni                              # <-- Facebook C++ JNI helpers
+        ReactAndroid::jsi                         # <-- RN: JSI
+        react-native-nitro-modules::NitroModules  # <-- NitroModules Core :)
+)
+
+# Link react-native (different prefab between RN 0.75 and RN 0.76)
+if(ReactAndroid_VERSION_MINOR GREATER_EQUAL 76)
+    target_link_libraries(
+        LiteRTLM
+        ReactAndroid::reactnative                 # <-- RN: Native Modules umbrella prefab
+    )
+else()
+    target_link_libraries(
+        LiteRTLM
+        ReactAndroid::react_nativemodule_core     # <-- RN: TurboModules Core
+    )
+endif()

package/nitrogen/generated/android/LiteRTLM+autolinking.gradle

@@ -0,0 +1,27 @@
+///
+/// LiteRTLM+autolinking.gradle
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+/// This is a Gradle file that adds all files generated by Nitrogen
+/// to the current Gradle project.
+///
+/// To use it, add this to your build.gradle:
+/// ```gradle
+/// apply from: '../nitrogen/generated/android/LiteRTLM+autolinking.gradle'
+/// ```
+
+logger.warn("[NitroModules] 🔥 LiteRTLM is boosted by nitro!")
+
+android {
+  sourceSets {
+    main {
+      java.srcDirs += [
+        // Nitrogen files
+        "${project.projectDir}/../nitrogen/generated/android/kotlin"
+      ]
+    }
+  }
+}

package/nitrogen/generated/android/LiteRTLMOnLoad.cpp

@@ -0,0 +1,46 @@
+///
+/// LiteRTLMOnLoad.cpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#ifndef BUILDING_LITERTLM_WITH_GENERATED_CMAKE_PROJECT
+#error LiteRTLMOnLoad.cpp is not being built with the autogenerated CMakeLists.txt project. Is a different CMakeLists.txt building this?
+#endif
+
+#include "LiteRTLMOnLoad.hpp"
+
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include <NitroModules/HybridObjectRegistry.hpp>
+
+#include "JHybridLiteRTLMSpec.hpp"
+#include "JFunc_void_std__string_bool.hpp"
+#include <NitroModules/DefaultConstructableObject.hpp>
+
+namespace margelo::nitro::litertlm {
+
+int initialize(JavaVM* vm) {
+  using namespace margelo::nitro;
+  using namespace margelo::nitro::litertlm;
+  using namespace facebook;
+
+  return facebook::jni::initialize(vm, [] {
+    // Register native JNI methods
+    margelo::nitro::litertlm::JHybridLiteRTLMSpec::registerNatives();
+    margelo::nitro::litertlm::JFunc_void_std__string_bool_cxx::registerNatives();
+
+    // Register Nitro Hybrid Objects
+    HybridObjectRegistry::registerHybridObjectConstructor(
+      "LiteRTLM",
+      []() -> std::shared_ptr<HybridObject> {
+        static DefaultConstructableObject<JHybridLiteRTLMSpec::javaobject> object("com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLM");
+        auto instance = object.create();
+        return instance->cthis()->shared();
+      }
+    );
+  });
+}
+
+} // namespace margelo::nitro::litertlm

package/nitrogen/generated/android/LiteRTLMOnLoad.hpp

@@ -0,0 +1,25 @@
+///
+/// LiteRTLMOnLoad.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#include <jni.h>
+#include <NitroModules/NitroDefines.hpp>
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * Initializes the native (C++) part of LiteRTLM, and autolinks all Hybrid Objects.
+   * Call this in your `JNI_OnLoad` function (probably inside `cpp-adapter.cpp`).
+   * Example:
+   * ```cpp (cpp-adapter.cpp)
+   * JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+   *   return margelo::nitro::litertlm::initialize(vm);
+   * }
+   * ```
+   */
+  int initialize(JavaVM* vm);
+
+} // namespace margelo::nitro::litertlm

package/nitrogen/generated/android/c++/JBackend.hpp

@@ -0,0 +1,61 @@
+///
+/// JBackend.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include "Backend.hpp"
+
+namespace margelo::nitro::litertlm {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ enum "Backend" and the the Kotlin enum "Backend".
+   */
+  struct JBackend final: public jni::JavaClass<JBackend> {
+  public:
+    static auto constexpr kJavaDescriptor = "Lcom/margelo/nitro/dev/litert/litertlm/Backend;";
+
+  public:
+    /**
+     * Convert this Java/Kotlin-based enum to the C++ enum Backend.
+     */
+    [[maybe_unused]]
+    [[nodiscard]]
+    Backend toCpp() const {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldOrdinal = clazz->getField<int>("value");
+      int ordinal = this->getFieldValue(fieldOrdinal);
+      return static_cast<Backend>(ordinal);
+    }
+
+  public:
+    /**
+     * Create a Java/Kotlin-based enum with the given C++ enum's value.
+     */
+    [[maybe_unused]]
+    static jni::alias_ref<JBackend> fromCpp(Backend value) {
+      static const auto clazz = javaClassStatic();
+      switch (value) {
+        case Backend::CPU:
+          static const auto fieldCPU = clazz->getStaticField<JBackend>("CPU");
+          return clazz->getStaticFieldValue(fieldCPU);
+        case Backend::GPU:
+          static const auto fieldGPU = clazz->getStaticField<JBackend>("GPU");
+          return clazz->getStaticFieldValue(fieldGPU);
+        case Backend::NPU:
+          static const auto fieldNPU = clazz->getStaticField<JBackend>("NPU");
+          return clazz->getStaticFieldValue(fieldNPU);
+        default:
+          std::string stringValue = std::to_string(static_cast<int>(value));
+          throw std::invalid_argument("Invalid enum value (" + stringValue + "!");
+      }
+    }
+  };
+
+} // namespace margelo::nitro::litertlm