@dr33m/react-native-litert-lm 0.5.4 → 0.5.6

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

@@ -575,7 +575,10 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         return lastStats
     }
 
-    override fun getMemoryUsage(): MemoryUsage {
+    /** Shared by the public [getMemoryUsage] override and the pre-flight guard
+     * in [execute] — both need the same real, OS-level reading, not an
+     * estimate. */
+    private fun currentMemoryUsage(): MemoryUsage {
         // Native heap: allocated bytes from Debug APIs (most accurate for native allocations)
         val nativeHeapBytes = Debug.getNativeHeapAllocatedSize().toDouble()
 
@@ -619,6 +622,8 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
         )
     }
 
+    override fun getMemoryUsage(): MemoryUsage = currentMemoryUsage()
+
     override fun checkModelCapabilities(modelPath: String): ModelCapabilities {
         var supportsSpeculativeDecoding = false
         try {
@@ -784,6 +789,16 @@ class HybridLiteRTLM : HybridLiteRTLMSpec() {
 
         return Promise.parallel {
             ensureLoaded()
+
+            // Refuse rather than risk it: growing the KV-cache under real memory
+            // pressure can fail at the native engine level in a way that never
+            // surfaces as a catchable Kotlin exception — it takes the whole
+            // process down. A plain RuntimeException here is a normal rejected
+            // Promise for callers, same contract as any other execute() failure.
+            if (currentMemoryUsage().isLowMemory) {
+                throw RuntimeException("LiteRTLM: Device memory is critically low; refusing to continue generation.")
+            }
+
             // Clear any previous tool calls before new inference
             pendingToolCalls.clear()
 

package/ios/HybridLiteRTLM+Execute.swift

@@ -80,6 +80,18 @@ extension HybridLiteRTLM {
                 return
             }
 
+            // Refuse rather than risk it: growing the KV-cache under real memory
+            // pressure can fail inside the underlying C engine in a way that
+            // never surfaces as a catchable Swift error — it takes the whole
+            // process down (Jetsam or a hard native failure). An NSError here
+            // is a normal rejected Promise for callers, same contract as any
+            // other execute() failure.
+            if Self.currentMemoryUsage().isLowMemory {
+                promise.reject(withError: NSError(domain: "LiteRTLM", code: 507,
+                    userInfo: [NSLocalizedDescriptionKey: "LiteRTLM: Device memory is critically low; refusing to continue generation."]))
+                return
+            }
+
             let payload: (json: String, tempFiles: [String])
             do { payload = try self.buildExecutePayload(preprocessed) }
             catch { promise.reject(withError: error); return }

package/ios/HybridLiteRTLM.swift

@@ -111,9 +111,18 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
     }
     
     public func getMemoryUsage() throws -> MemoryUsage {
+        return Self.currentMemoryUsage()
+    }
+
+    /// Shared by the public `getMemoryUsage()` override and the pre-flight
+    /// guard in `HybridLiteRTLM+Execute.swift` — both need the same real,
+    /// OS-level reading, not an estimate. `static` since it needs no
+    /// instance state, which also makes it trivially callable from the
+    /// extension file.
+    static func currentMemoryUsage() -> MemoryUsage {
         var residentBytes: Double = 0.0
         var nativeHeapBytes: Double = 0.0
-        
+
         // Retrieve process resident set size (RSS) via Mach basic task info
         var info = mach_task_basic_info()
         var count = mach_msg_type_number_t(MemoryLayout<mach_task_basic_info>.size / MemoryLayout<integer_t>.size)
@@ -122,18 +131,18 @@ public class HybridLiteRTLM: HybridLiteRTLMSpec_base, HybridLiteRTLMSpec_protoco
                 task_info(mach_task_self_, task_flavor_t(MACH_TASK_BASIC_INFO), $0, &count)
             }
         }
-        
+
         if kerr == KERN_SUCCESS {
             residentBytes = Double(info.resident_size)
             nativeHeapBytes = Double(info.resident_size)
         }
-        
+
         // os_proc_available_memory reports actual headroom available before Jetsam termination (iOS 13+)
         let availableBytes = Double(os_proc_available_memory())
-        
+
         // Flag memory warning at ~200MB remaining headroom
         let isLowMemory = availableBytes < 200.0 * 1024.0 * 1024.0
-        
+
         return MemoryUsage(
             nativeHeapBytes: nativeHeapBytes,
             residentBytes: residentBytes,

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/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/Func_void_double.kt

@@ -10,7 +10,6 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
-import dalvik.annotation.optimization.FastNative
 
 
 /**
@@ -59,7 +58,6 @@ class Func_void_double_cxx: Func_void_double {
   override fun invoke(progress: Double): Unit
     = invoke_cxx(progress)
 
-  @FastNative
   private external fun invoke_cxx(progress: Double): Unit
 }
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/Func_void_std__string_bool.kt

@@ -10,7 +10,6 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
-import dalvik.annotation.optimization.FastNative
 
 
 /**
@@ -59,7 +58,6 @@ class Func_void_std__string_bool_cxx: Func_void_std__string_bool {
   override fun invoke(token: String, done: Boolean): Unit
     = invoke_cxx(token,done)
 
-  @FastNative
   private external fun invoke_cxx(token: String, done: Boolean): Unit
 }
 

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/HybridLiteRTLMSpec.kt

@@ -10,6 +10,7 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.core.HybridObject
 
@@ -157,6 +158,7 @@ abstract class HybridLiteRTLMSpec: HybridObject() {
   @Keep
   protected open class CxxPart(javaPart: HybridLiteRTLMSpec): HybridObject.CxxPart(javaPart) {
     // C++ JHybridLiteRTLMSpec::CxxPart::initHybrid(...)
+    @FastNative
     external override fun initHybrid(): HybridData
   }
   override fun createCxxPart(): CxxPart {

package/nitrogen/generated/android/kotlin/com/margelo/nitro/dev/litert/litertlm/HybridModelStoreSpec.kt

@@ -10,6 +10,7 @@ package com.margelo.nitro.dev.litert.litertlm
 import androidx.annotation.Keep
 import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.core.HybridObject
 
@@ -64,6 +65,7 @@ abstract class HybridModelStoreSpec: HybridObject() {
   @Keep
   protected open class CxxPart(javaPart: HybridModelStoreSpec): HybridObject.CxxPart(javaPart) {
     // C++ JHybridModelStoreSpec::CxxPart::initHybrid(...)
+    @FastNative
     external override fun initHybrid(): HybridData
   }
   override fun createCxxPart(): CxxPart {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dr33m/react-native-litert-lm",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "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,