@dr33m/react-native-litert-lm 0.5.3 → 0.5.5

package/android/src/main/java/com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLM.kt

@@ -58,6 +58,10 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         /** Cached result of OpenCL availability probe (null = not yet checked). */
         @Volatile
         private var openCLAvailable: Boolean? = null
+
+        /** Cached result of NPU/QNN availability probe (null = not yet checked). */
+        @Volatile
+        private var npuAvailable: Boolean? = null
         
         /**
          * Initialize the native library.
@@ -197,6 +201,41 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
                         }
                     }
 
+                    // NPU hardware check: probe for QNN HTP runtime libraries.
+                    // LiteRT-LM's NPU delegate requires Qualcomm QNN HTP (Hexagon Tensor
+                    // Processor) runtime. Without it, Engine() crashes with SIGSEGV
+                    // that Kotlin's try/catch cannot intercept.
+                    // Unlike GPU (which throws a catchable Java exception on failure),
+                    // NPU failure is a native crash — so we MUST detect before attempting.
+                    if (npuAvailable == null) {
+                        val hasNpu = run {
+                            // Check for QNN HTP libraries in system vendor paths.
+                            // These are only present on devices with Qualcomm NPU support.
+                            val qnnPaths = arrayOf(
+                                "/vendor/lib64/libQnnHtp.so",
+                                "/vendor/lib/libQnnHtp.so",
+                                "/system/vendor/lib64/libQnnHtp.so",
+                                "/system/lib64/libQnnHtp.so",
+                                "/vendor/lib64/libQnnSystem.so",
+                                "/vendor/lib/libQnnSystem.so"
+                            )
+                            var found = false
+                            for (path in qnnPaths) {
+                                if (java.io.File(path).exists()) {
+                                    found = true
+                                    break
+                                }
+                            }
+                            found
+                        }
+                        npuAvailable = hasNpu
+                        if (!hasNpu) {
+                            Log.w(TAG, "QNN HTP libraries not found — NPU backend unavailable")
+                        } else {
+                            Log.i(TAG, "QNN HTP libraries found — NPU backend may be available")
+                        }
+                    }
+
                     // Detect multimodal support. Check config.multimodal flag first, then fall back to filename sniffing.
                     // Only Gemma 3n bundles vision/audio executors; Gemma 4 E2B is text-only.
                     // Passing vision/audio backends to a text-only model causes
@@ -259,12 +298,13 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
                             }
                         }
                         Backend.NPU -> {
+                            val hasNpu = npuAvailable ?: false
                             val nativeLibDir = LiteRTLMInitProvider.applicationContext?.applicationInfo?.nativeLibraryDir
-                            Log.i(TAG, "NPU backend requested - nativeLibraryDir=$nativeLibDir")
-                            if (nativeLibDir != null) {
+                            Log.i(TAG, "NPU backend requested - available=$hasNpu, nativeLibraryDir=$nativeLibDir")
+                            if (hasNpu && nativeLibDir != null) {
                                 com.google.ai.edge.litertlm.Backend.NPU(nativeLibraryDir = nativeLibDir)
                             } else {
-                                Log.w(TAG, "NPU requested but nativeLibraryDir unavailable — using CPU directly")
+                                Log.w(TAG, "NPU requested but hardware unavailable — using CPU directly")
                                 backend = Backend.CPU
                                 com.google.ai.edge.litertlm.Backend.CPU()
                             }
@@ -662,10 +702,10 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
             tool(apiTool)
         }
 
-        // Create conversation with explicit SamplerConfig (required by Gallery pattern).
-        // GPU backend may fail silently without proper sampler params.
+        // Create conversation config. NPU backend does not support SamplerConfig
+        // (matching Gallery app pattern — setting sampler params on NPU causes crashes).
         val convConfig = ConversationConfig(
-            samplerConfig = SamplerConfig(
+            samplerConfig = if (backend == Backend.NPU) null else SamplerConfig(
                 topK = topK,
                 topP = topP.toDouble(),
                 temperature = temperature.toDouble(),

package/lib/index.d.ts

@@ -84,6 +84,23 @@ export type ModelId = (typeof Models)[keyof typeof Models];
  * ```
  */
 export declare function getRecommendedBackend(): Backend;
+/**
+ * Check whether the native LiteRT-LM module loaded successfully on this
+ * device. Some devices (unsupported ABI, missing native libs) can't load
+ * the native module at all — call this before showing any on-device AI UI
+ * so those devices degrade gracefully instead of throwing when a model is
+ * loaded. Result is cached after the first call.
+ *
+ * @returns true if native inference is available on this device
+ *
+ * @example
+ * ```typescript
+ * if (!isNativeAvailable()) {
+ *   // hide/disable on-device AI features
+ * }
+ * ```
+ */
+export declare function isNativeAvailable(): boolean;
 /**
  * Check if a backend configuration is supported on the current platform.
  * Returns a warning message if the configuration may have issues.

package/lib/index.js

@@ -16,8 +16,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GEMMA_4_E4B_IT = exports.GEMMA_4_E2B_IT = exports.GEMMA_3N_E2B_IT_INT4 = exports.Models = exports.createLLM = exports.ModelRegistry = exports.createNativeBuffer = exports.createMemoryTracker = void 0;
 exports.getRecommendedBackend = getRecommendedBackend;
+exports.isNativeAvailable = isNativeAvailable;
 exports.checkBackendSupport = checkBackendSupport;
 exports.checkMultimodalSupport = checkMultimodalSupport;
+const react_native_nitro_modules_1 = require("react-native-nitro-modules");
 const react_native_1 = require("react-native");
 var memoryTracker_1 = require("./memoryTracker");
 Object.defineProperty(exports, "createMemoryTracker", { enumerable: true, get: function () { return memoryTracker_1.createMemoryTracker; } });
@@ -103,6 +105,35 @@ function getRecommendedBackend() {
     // GPU is faster but may fail on some models/devices.
     return "cpu";
 }
+let nativeAvailable = null;
+/**
+ * Check whether the native LiteRT-LM module loaded successfully on this
+ * device. Some devices (unsupported ABI, missing native libs) can't load
+ * the native module at all — call this before showing any on-device AI UI
+ * so those devices degrade gracefully instead of throwing when a model is
+ * loaded. Result is cached after the first call.
+ *
+ * @returns true if native inference is available on this device
+ *
+ * @example
+ * ```typescript
+ * if (!isNativeAvailable()) {
+ *   // hide/disable on-device AI features
+ * }
+ * ```
+ */
+function isNativeAvailable() {
+    if (nativeAvailable === null) {
+        try {
+            react_native_nitro_modules_1.NitroModules.createHybridObject("ModelStore");
+            nativeAvailable = true;
+        }
+        catch {
+            nativeAvailable = false;
+        }
+    }
+    return nativeAvailable;
+}
 /**
  * Check if a backend configuration is supported on the current platform.
  * Returns a warning message if the configuration may have issues.

package/lib/modelRegistry.js

@@ -3,7 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ModelRegistry = void 0;
 const react_native_nitro_modules_1 = require("react-native-nitro-modules");
 const modelPath_1 = require("./modelPath");
-const nativeStore = react_native_nitro_modules_1.NitroModules.createHybridObject("ModelStore");
+let nativeStore = null;
+// Lazily created — a module-scope createHybridObject() would throw at import
+// time on devices where the native lib failed to load, crashing app startup
+// before any capability check can run.
+function getStore() {
+    if (!nativeStore) {
+        nativeStore = react_native_nitro_modules_1.NitroModules.createHybridObject("ModelStore");
+    }
+    return nativeStore;
+}
 /**
  * High-performance Model Registry for react-native-litert-lm.
  *
@@ -19,7 +28,7 @@ exports.ModelRegistry = {
      * @returns true if cached and has size > 0
      */
     isCached(pathOrUrl) {
-        return nativeStore.isCached((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+        return getStore().isCached((0, modelPath_1.resolveModelFileName)(pathOrUrl));
     },
     /**
      * Get the absolute local path of a cached model.
@@ -29,7 +38,7 @@ exports.ModelRegistry = {
      * @returns The absolute local path
      */
     getFilePath(pathOrUrl) {
-        return nativeStore.getFilePath((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+        return getStore().getFilePath((0, modelPath_1.resolveModelFileName)(pathOrUrl));
     },
     /**
      * List all locally cached model files.
@@ -37,7 +46,7 @@ exports.ModelRegistry = {
      * @returns Array of ModelFile descriptors containing path, size, and mod time
      */
     listCachedFiles() {
-        return nativeStore.listCachedFiles();
+        return getStore().listCachedFiles();
     },
     /**
      * Delete a cached model file.
@@ -46,7 +55,7 @@ exports.ModelRegistry = {
      * @param pathOrUrl Filename, local path, or download URL to delete
      */
     deleteFile(pathOrUrl) {
-        nativeStore.deleteFile((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+        getStore().deleteFile((0, modelPath_1.resolveModelFileName)(pathOrUrl));
     },
     /**
      * Resolve a model path or URL.
@@ -73,7 +82,7 @@ exports.ModelRegistry = {
                 throw new Error(`Invalid model URL: ${cleanPath}`);
             }
             const headersJson = options?.headers ? JSON.stringify(options.headers) : "{}";
-            return nativeStore.downloadFile(cleanPath, fileName, headersJson, (progress) => {
+            return getStore().downloadFile(cleanPath, fileName, headersJson, (progress) => {
                 options?.onProgress?.(progress);
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr33m/react-native-litert-lm",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "litertLm": {
     "version": "0.12.0",
     "androidMavenVersion": "0.12.0",

package/src/index.ts

@@ -8,6 +8,7 @@ import type {
   Role,
   GenerationStats,
   MemoryUsage,
+  ModelStore,
 } from "./specs/LiteRTLM.nitro";
 
 export type {
@@ -125,6 +126,36 @@ export function getRecommendedBackend(): Backend {
   return "cpu";
 }
 
+let nativeAvailable: boolean | null = null;
+
+/**
+ * Check whether the native LiteRT-LM module loaded successfully on this
+ * device. Some devices (unsupported ABI, missing native libs) can't load
+ * the native module at all — call this before showing any on-device AI UI
+ * so those devices degrade gracefully instead of throwing when a model is
+ * loaded. Result is cached after the first call.
+ *
+ * @returns true if native inference is available on this device
+ *
+ * @example
+ * ```typescript
+ * if (!isNativeAvailable()) {
+ *   // hide/disable on-device AI features
+ * }
+ * ```
+ */
+export function isNativeAvailable(): boolean {
+  if (nativeAvailable === null) {
+    try {
+      NitroModules.createHybridObject<ModelStore>("ModelStore");
+      nativeAvailable = true;
+    } catch {
+      nativeAvailable = false;
+    }
+  }
+  return nativeAvailable;
+}
+
 /**
  * Check if a backend configuration is supported on the current platform.
  * Returns a warning message if the configuration may have issues.

package/src/modelRegistry.ts

@@ -9,7 +9,17 @@ export interface ModelDownloadOptions {
   onProgress?: (progress: number) => void;
 }
 
-const nativeStore = NitroModules.createHybridObject<ModelStore>("ModelStore");
+let nativeStore: ModelStore | null = null;
+
+// Lazily created — a module-scope createHybridObject() would throw at import
+// time on devices where the native lib failed to load, crashing app startup
+// before any capability check can run.
+function getStore(): ModelStore {
+  if (!nativeStore) {
+    nativeStore = NitroModules.createHybridObject<ModelStore>("ModelStore");
+  }
+  return nativeStore;
+}
 
 /**
  * High-performance Model Registry for react-native-litert-lm.
@@ -26,7 +36,7 @@ export const ModelRegistry = {
    * @returns true if cached and has size > 0
    */
   isCached(pathOrUrl: string): boolean {
-    return nativeStore.isCached(resolveModelFileName(pathOrUrl));
+    return getStore().isCached(resolveModelFileName(pathOrUrl));
   },
 
   /**
@@ -37,7 +47,7 @@ export const ModelRegistry = {
    * @returns The absolute local path
    */
   getFilePath(pathOrUrl: string): string {
-    return nativeStore.getFilePath(resolveModelFileName(pathOrUrl));
+    return getStore().getFilePath(resolveModelFileName(pathOrUrl));
   },
 
   /**
@@ -46,7 +56,7 @@ export const ModelRegistry = {
    * @returns Array of ModelFile descriptors containing path, size, and mod time
    */
   listCachedFiles(): ModelFile[] {
-    return nativeStore.listCachedFiles();
+    return getStore().listCachedFiles();
   },
 
   /**
@@ -56,7 +66,7 @@ export const ModelRegistry = {
    * @param pathOrUrl Filename, local path, or download URL to delete
    */
   deleteFile(pathOrUrl: string): void {
-    nativeStore.deleteFile(resolveModelFileName(pathOrUrl));
+    getStore().deleteFile(resolveModelFileName(pathOrUrl));
   },
 
   /**
@@ -89,7 +99,7 @@ export const ModelRegistry = {
 
       const headersJson = options?.headers ? JSON.stringify(options.headers) : "{}";
       
-      return nativeStore.downloadFile(
+      return getStore().downloadFile(
         cleanPath,
         fileName,
         headersJson,