react-native-litert-lm 0.2.1 → 0.2.2

package/nitrogen/generated/shared/c++/MemoryUsage.hpp

@@ -0,0 +1,95 @@
+///
+/// MemoryUsage.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+
+
+namespace margelo::nitro::litertlm {
+
+  /**
+   * A struct which can be represented as a JavaScript object (MemoryUsage).
+   */
+  struct MemoryUsage final {
+  public:
+    double nativeHeapBytes     SWIFT_PRIVATE;
+    double residentBytes     SWIFT_PRIVATE;
+    double availableMemoryBytes     SWIFT_PRIVATE;
+    bool isLowMemory     SWIFT_PRIVATE;
+
+  public:
+    MemoryUsage() = default;
+    explicit MemoryUsage(double nativeHeapBytes, double residentBytes, double availableMemoryBytes, bool isLowMemory): nativeHeapBytes(nativeHeapBytes), residentBytes(residentBytes), availableMemoryBytes(availableMemoryBytes), isLowMemory(isLowMemory) {}
+
+  public:
+    friend bool operator==(const MemoryUsage& lhs, const MemoryUsage& rhs) = default;
+  };
+
+} // namespace margelo::nitro::litertlm
+
+namespace margelo::nitro {
+
+  // C++ MemoryUsage <> JS MemoryUsage (object)
+  template <>
+  struct JSIConverter<margelo::nitro::litertlm::MemoryUsage> final {
+    static inline margelo::nitro::litertlm::MemoryUsage fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::litertlm::MemoryUsage(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "residentBytes"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes"))),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::litertlm::MemoryUsage& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes"), JSIConverter<double>::toJSI(runtime, arg.nativeHeapBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "residentBytes"), JSIConverter<double>::toJSI(runtime, arg.residentBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes"), JSIConverter<double>::toJSI(runtime, arg.availableMemoryBytes));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory"), JSIConverter<bool>::toJSI(runtime, arg.isLowMemory));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "nativeHeapBytes")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "residentBytes")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "availableMemoryBytes")))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "isLowMemory")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-litert-lm",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "High-performance LLM inference for React Native using LiteRT-LM. Optimized for Gemma 3n and other on-device language models.",
   "license": "MIT",
   "author": "Hugh Chen (https://github.com/hung-yueh)",
@@ -65,7 +65,7 @@
     "@expo/config-plugins": "~54.0.4",
     "@types/react": "~19.1.10",
     "expo": "^54.0.31",
-    "nitrogen": "^0.33.2",
+    "nitrogen": "^0.34.1",
     "react": "19.1.0",
     "react-native": "0.81.5",
     "release-it": "^19.2.4",
@@ -82,6 +82,6 @@
     }
   },
   "dependencies": {
-    "react-native-nitro-modules": "^0.33.2"
+    "react-native-nitro-modules": "^0.34.1"
   }
 }

package/src/hooks.ts

@@ -1,9 +1,23 @@
 import { useState, useEffect, useRef, useCallback } from "react";
 import { LiteRTLM, LLMConfig } from "./index";
 import { createLLM } from "./modelFactory";
+import type { MemoryTracker, MemoryTrackerSummary } from "./memoryTracker";
 
 export interface UseModelConfig extends LLMConfig {
   autoLoad?: boolean;
+  /**
+   * Enable memory tracking using native ArrayBuffers (v0.34+).
+   * When enabled, memory usage is tracked after each inference call
+   * using `NitroModules.createNativeArrayBuffer()` for zero-copy storage.
+   * @default false
+   */
+  enableMemoryTracking?: boolean;
+  /**
+   * Maximum number of memory snapshots to store.
+   * Each snapshot uses 32 bytes of native memory.
+   * @default 256
+   */
+  maxMemorySnapshots?: number;
 }
 
 export interface UseModelResult {
@@ -16,24 +30,50 @@ export interface UseModelResult {
   reset: () => void;
   deleteModel: (fileName: string) => Promise<void>;
   load: () => Promise<void>;
+  /**
+   * Memory tracker instance (available when enableMemoryTracking is true).
+   * Uses native ArrayBuffers allocated via `NitroModules.createNativeArrayBuffer()`
+   * for efficient, zero-copy memory usage tracking.
+   */
+  memoryTracker: MemoryTracker | null;
+  /**
+   * Current memory tracking summary (null if tracking is disabled).
+   * Updates automatically after each inference call.
+   */
+  memorySummary: MemoryTrackerSummary | null;
 }
 
 export function useModel(
   pathOrUrl: string,
   config?: UseModelConfig,
 ): UseModelResult {
-  const modelRef = useRef<LiteRTLM | null>(null);
+  const modelRef = useRef<(LiteRTLM & { memoryTracker?: MemoryTracker }) | null>(null);
   const [isReady, setIsReady] = useState(false);
   const [isGenerating, setIsGenerating] = useState(false);
   const [downloadProgress, setDownloadProgress] = useState(0);
   const [error, setError] = useState<string | null>(null);
+  const [memorySummary, setMemorySummary] = useState<MemoryTrackerSummary | null>(null);
 
-  // Extract autoLoad (default true)
+  // Extract autoLoad (default true) and memory tracking options
   const autoLoad = config?.autoLoad ?? true;
+  const enableMemoryTracking = config?.enableMemoryTracking ?? false;
+  const maxMemorySnapshots = config?.maxMemorySnapshots ?? 256;
+
+  /**
+   * Refresh memory summary from the tracker's native buffer.
+   */
+  const refreshMemorySummary = useCallback(() => {
+    if (modelRef.current?.memoryTracker) {
+      setMemorySummary(modelRef.current.memoryTracker.getSummary());
+    }
+  }, []);
 
   // Initialize the model instance
   useEffect(() => {
-    modelRef.current = createLLM();
+    modelRef.current = createLLM({
+      enableMemoryTracking,
+      maxMemorySnapshots,
+    });
     let isMounted = true;
 
     // Cleanup on unmount
@@ -45,7 +85,7 @@ export function useModel(
         console.warn("Failed to close model", e);
       }
     };
-  }, []);
+  }, [enableMemoryTracking, maxMemorySnapshots]);
 
   const load = useCallback(async () => {
     setIsReady(false);
@@ -106,6 +146,7 @@ export function useModel(
               (token: string, done: boolean) => {
                 fullResponse += token;
                 if (done) {
+                  refreshMemorySummary();
                   resolve(fullResponse);
                 }
               },
@@ -121,7 +162,7 @@ export function useModel(
         setIsGenerating(false);
       }
     },
-    [isReady],
+    [isReady, refreshMemorySummary],
   );
 
   const reset = useCallback(() => {
@@ -148,5 +189,7 @@ export function useModel(
     reset,
     deleteModel,
     load,
+    memoryTracker: modelRef.current?.memoryTracker ?? null,
+    memorySummary,
   };
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import type {
   Backend,
   Role,
   GenerationStats,
+  MemoryUsage,
 } from "./specs/LiteRTLM.nitro";
 
 export type {
@@ -16,6 +17,7 @@ export type {
   Backend,
   Role,
   GenerationStats,
+  MemoryUsage,
 } from "./specs/LiteRTLM.nitro";
 
 // Re-export template utilities
@@ -26,6 +28,14 @@ export {
   applyLlamaTemplate,
 } from "./templates";
 
+// Re-export memory tracking utilities (uses NitroModules.createNativeArrayBuffer v0.34+)
+export type {
+  MemorySnapshot,
+  MemoryTracker,
+  MemoryTrackerSummary,
+} from "./memoryTracker";
+export { createMemoryTracker, createNativeBuffer } from "./memoryTracker";
+
 export * from "./hooks";
 
 /**

package/src/memoryTracker.ts

@@ -0,0 +1,268 @@
+/**
+ * Memory tracking utilities for LiteRT-LM using real native memory metrics.
+ *
+ * Records real memory usage from OS-level APIs via `getMemoryUsage()`,
+ * and stores snapshots in a native-backed ArrayBuffer allocated via
+ * `NitroModules.createNativeArrayBuffer()` (v0.34+) for zero-copy interop.
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryTracker } from 'react-native-litert-lm';
+ *
+ * const tracker = createMemoryTracker(100);
+ *
+ * // Record a real snapshot (typically called internally after inference)
+ * tracker.record({
+ *   timestamp: Date.now(),
+ *   nativeHeapBytes: usage.nativeHeapBytes,
+ *   residentBytes: usage.residentBytes,
+ *   availableMemoryBytes: usage.availableMemoryBytes,
+ * });
+ *
+ * console.log(`Peak RSS: ${tracker.getPeakMemory()} bytes`);
+ * ```
+ */
+
+import { NitroModules } from "react-native-nitro-modules";
+
+/**
+ * A single memory usage snapshot with real data from OS APIs.
+ */
+export interface MemorySnapshot {
+  /** Unix timestamp in milliseconds */
+  timestamp: number;
+  /** Native heap allocated bytes (Debug.getNativeHeapAllocatedSize on Android, task_info on iOS) */
+  nativeHeapBytes: number;
+  /** Process resident set size (RSS) in bytes */
+  residentBytes: number;
+  /** Available system memory in bytes */
+  availableMemoryBytes: number;
+}
+
+/** Number of Float64 fields per snapshot */
+const FIELDS_PER_SNAPSHOT = 4;
+/** Bytes per Float64 value */
+const BYTES_PER_FIELD = Float64Array.BYTES_PER_ELEMENT; // 8
+
+/**
+ * Memory tracker that stores snapshots in a native-backed ArrayBuffer.
+ *
+ * Uses `NitroModules.createNativeArrayBuffer()` to allocate the backing
+ * buffer in native (C++) memory, ensuring zero-copy interop with native
+ * methods and keeping memory tracking data off the JS heap.
+ */
+export interface MemoryTracker {
+  /**
+   * Record a new memory snapshot.
+   * @param snapshot The memory usage data to record
+   * @returns true if recorded, false if buffer is full
+   */
+  record(snapshot: MemorySnapshot): boolean;
+
+  /**
+   * Get all recorded snapshots as structured objects.
+   */
+  getSnapshots(): MemorySnapshot[];
+
+  /**
+   * Get the number of recorded snapshots.
+   */
+  getSnapshotCount(): number;
+
+  /**
+   * Get the maximum number of snapshots this tracker can hold.
+   */
+  getCapacity(): number;
+
+  /**
+   * Get the peak resident set size across all snapshots.
+   */
+  getPeakMemory(): number;
+
+  /**
+   * Get the latest memory snapshot, or undefined if none recorded.
+   */
+  getLatestSnapshot(): MemorySnapshot | undefined;
+
+  /**
+   * Get the underlying native ArrayBuffer.
+   * This buffer is allocated via `NitroModules.createNativeArrayBuffer()`
+   * and lives in native memory, enabling zero-copy transfer to native methods.
+   */
+  getNativeBuffer(): ArrayBuffer;
+
+  /**
+   * Get the Float64Array view over the native buffer.
+   */
+  getView(): Float64Array;
+
+  /**
+   * Reset the tracker, clearing all recorded snapshots.
+   * The native buffer is preserved (not reallocated).
+   */
+  reset(): void;
+
+  /**
+   * Get a summary of memory usage statistics.
+   */
+  getSummary(): MemoryTrackerSummary;
+}
+
+/**
+ * Summary statistics from the memory tracker.
+ */
+export interface MemoryTrackerSummary {
+  /** Number of snapshots recorded */
+  snapshotCount: number;
+  /** Peak resident set size in bytes */
+  peakResidentBytes: number;
+  /** Average resident set size in bytes */
+  averageResidentBytes: number;
+  /** Latest resident set size in bytes */
+  currentResidentBytes: number;
+  /** Peak native heap allocated in bytes */
+  peakNativeHeapBytes: number;
+  /** Latest native heap allocated in bytes */
+  currentNativeHeapBytes: number;
+  /** RSS delta from first to last snapshot in bytes */
+  residentDeltaBytes: number;
+  /** Size of the native tracking buffer itself in bytes */
+  trackerBufferSizeBytes: number;
+}
+
+/**
+ * Create a new memory tracker backed by a native ArrayBuffer.
+ *
+ * @param maxSnapshots Maximum number of snapshots to store (default: 256)
+ * @returns A MemoryTracker instance
+ */
+export function createMemoryTracker(maxSnapshots: number = 256): MemoryTracker {
+  const bufferSize = maxSnapshots * FIELDS_PER_SNAPSHOT * BYTES_PER_FIELD;
+
+  // Use NitroModules.createNativeArrayBuffer for native-backed allocation.
+  const nativeBuffer = NitroModules.createNativeArrayBuffer(bufferSize);
+  const view = new Float64Array(nativeBuffer);
+
+  let currentIndex = 0;
+
+  return {
+    record(snapshot: MemorySnapshot): boolean {
+      if (currentIndex >= maxSnapshots) {
+        return false;
+      }
+
+      const offset = currentIndex * FIELDS_PER_SNAPSHOT;
+      view[offset] = snapshot.timestamp;
+      view[offset + 1] = snapshot.nativeHeapBytes;
+      view[offset + 2] = snapshot.residentBytes;
+      view[offset + 3] = snapshot.availableMemoryBytes;
+      currentIndex++;
+
+      return true;
+    },
+
+    getSnapshots(): MemorySnapshot[] {
+      const snapshots: MemorySnapshot[] = [];
+      for (let i = 0; i < currentIndex; i++) {
+        const offset = i * FIELDS_PER_SNAPSHOT;
+        snapshots.push({
+          timestamp: view[offset]!,
+          nativeHeapBytes: view[offset + 1]!,
+          residentBytes: view[offset + 2]!,
+          availableMemoryBytes: view[offset + 3]!,
+        });
+      }
+      return snapshots;
+    },
+
+    getSnapshotCount(): number {
+      return currentIndex;
+    },
+
+    getCapacity(): number {
+      return maxSnapshots;
+    },
+
+    getPeakMemory(): number {
+      let peak = 0;
+      for (let i = 0; i < currentIndex; i++) {
+        const rss = view[i * FIELDS_PER_SNAPSHOT + 2]!;
+        if (rss > peak) {
+          peak = rss;
+        }
+      }
+      return peak;
+    },
+
+    getLatestSnapshot(): MemorySnapshot | undefined {
+      if (currentIndex === 0) return undefined;
+      const offset = (currentIndex - 1) * FIELDS_PER_SNAPSHOT;
+      return {
+        timestamp: view[offset]!,
+        nativeHeapBytes: view[offset + 1]!,
+        residentBytes: view[offset + 2]!,
+        availableMemoryBytes: view[offset + 3]!,
+      };
+    },
+
+    getNativeBuffer(): ArrayBuffer {
+      return nativeBuffer;
+    },
+
+    getView(): Float64Array {
+      return view;
+    },
+
+    reset(): void {
+      view.fill(0);
+      currentIndex = 0;
+    },
+
+    getSummary(): MemoryTrackerSummary {
+      let peakRss = 0;
+      let peakHeap = 0;
+      let sumRss = 0;
+      let firstRss = 0;
+      let lastRss = 0;
+      let lastHeap = 0;
+
+      for (let i = 0; i < currentIndex; i++) {
+        const offset = i * FIELDS_PER_SNAPSHOT;
+        const heap = view[offset + 1]!;
+        const rss = view[offset + 2]!;
+
+        if (rss > peakRss) peakRss = rss;
+        if (heap > peakHeap) peakHeap = heap;
+        sumRss += rss;
+        if (i === 0) firstRss = rss;
+        if (i === currentIndex - 1) {
+          lastRss = rss;
+          lastHeap = heap;
+        }
+      }
+
+      return {
+        snapshotCount: currentIndex,
+        peakResidentBytes: peakRss,
+        averageResidentBytes: currentIndex > 0 ? sumRss / currentIndex : 0,
+        currentResidentBytes: lastRss,
+        peakNativeHeapBytes: peakHeap,
+        currentNativeHeapBytes: lastHeap,
+        residentDeltaBytes: lastRss - firstRss,
+        trackerBufferSizeBytes: bufferSize,
+      };
+    },
+  };
+}
+
+/**
+ * Create a native ArrayBuffer for efficient data transfer.
+ *
+ * A convenience wrapper around `NitroModules.createNativeArrayBuffer()`.
+ *
+ * @param size Size in bytes
+ * @returns A native-backed ArrayBuffer
+ */
+export function createNativeBuffer(size: number): ArrayBuffer {
+  return NitroModules.createNativeArrayBuffer(size);
+}

package/src/modelFactory.ts

@@ -1,14 +1,49 @@
 import { NitroModules } from "react-native-nitro-modules";
 import { LiteRTLM, LLMConfig } from "./specs/LiteRTLM.nitro";
+import { createMemoryTracker, MemoryTracker } from "./memoryTracker";
 
 /**
  * Creates a new LiteRT-LM inference engine instance.
+ *
+ * Optionally creates a native-backed memory tracker using
+ * `NitroModules.createNativeArrayBuffer()` (v0.34+) for efficient
+ * zero-copy memory usage tracking.
+ *
+ * @param options.enableMemoryTracking Enable automatic memory tracking (default: false)
+ * @param options.maxMemorySnapshots Maximum number of memory snapshots to store (default: 256)
  */
-export function createLLM(): LiteRTLM {
+export function createLLM(options?: {
+  enableMemoryTracking?: boolean;
+  maxMemorySnapshots?: number;
+}): LiteRTLM & { memoryTracker?: MemoryTracker } {
   const native = NitroModules.createHybridObject<LiteRTLM>("LiteRTLM");
 
+  const enableTracking = options?.enableMemoryTracking ?? false;
+  const tracker = enableTracking
+    ? createMemoryTracker(options?.maxMemorySnapshots ?? 256)
+    : undefined;
+
+  /**
+   * Record a real memory snapshot using OS-level APIs via getMemoryUsage().
+   */
+  const recordMemorySnapshot = () => {
+    if (!tracker) return;
+    try {
+      const usage = native.getMemoryUsage();
+      tracker.record({
+        timestamp: Date.now(),
+        nativeHeapBytes: usage.nativeHeapBytes,
+        residentBytes: usage.residentBytes,
+        availableMemoryBytes: usage.availableMemoryBytes,
+      });
+    } catch {
+      // Ignore errors during memory tracking - it's non-critical
+    }
+  };
+
   return {
     ...native,
+    memoryTracker: tracker,
     loadModel: async (pathOrUrl: string, config?: LLMConfig) => {
       let modelPath = pathOrUrl;
 
@@ -31,17 +66,53 @@ export function createLLM(): LiteRTLM {
         console.log(`Model downloaded to: ${modelPath}`);
       }
 
-      return native.loadModel(modelPath, config);
+      const result = await native.loadModel(modelPath, config);
+
+      // Record initial memory snapshot after model load
+      if (tracker) {
+        tracker.reset();
+        recordMemorySnapshot();
+      }
+
+      return result;
+    },
+    sendMessage: async (...args: Parameters<typeof native.sendMessage>) => {
+      const result = await native.sendMessage(...args);
+      recordMemorySnapshot();
+      return result;
+    },
+    sendMessageAsync: (...args: Parameters<typeof native.sendMessageAsync>) => {
+      const [message, onToken] = args;
+      native.sendMessageAsync(message, (token, done) => {
+        onToken(token, done);
+        if (done) {
+          recordMemorySnapshot();
+        }
+      });
+    },
+    sendMessageWithImage: async (
+      ...args: Parameters<typeof native.sendMessageWithImage>
+    ) => {
+      const result = await native.sendMessageWithImage(...args);
+      recordMemorySnapshot();
+      return result;
+    },
+    sendMessageWithAudio: async (
+      ...args: Parameters<typeof native.sendMessageWithAudio>
+    ) => {
+      const result = await native.sendMessageWithAudio(...args);
+      recordMemorySnapshot();
+      return result;
     },
-    // Bind valid methods to native instance
-    sendMessage: native.sendMessage.bind(native),
-    sendMessageAsync: native.sendMessageAsync.bind(native),
-    sendMessageWithImage: native.sendMessageWithImage.bind(native),
-    sendMessageWithAudio: native.sendMessageWithAudio.bind(native),
     getHistory: native.getHistory.bind(native),
-    resetConversation: native.resetConversation.bind(native),
+    resetConversation: () => {
+      native.resetConversation();
+      // KV cache is cleared on reset, record the drop
+      recordMemorySnapshot();
+    },
     isReady: native.isReady.bind(native),
     getStats: native.getStats.bind(native),
+    getMemoryUsage: native.getMemoryUsage.bind(native),
     close: native.close.bind(native),
     downloadModel: native.downloadModel.bind(native),
     deleteModel: native.deleteModel.bind(native),

package/src/specs/LiteRTLM.nitro.ts

@@ -99,6 +99,21 @@ export interface GenerationStats {
   tokensPerSecond: number;
 }
 
+/**
+ * Real memory usage statistics from the native runtime.
+ * Measured from OS-level APIs, not estimated.
+ */
+export interface MemoryUsage {
+  /** Native heap allocated bytes (Debug.getNativeHeapAllocatedSize on Android, malloc_size on iOS) */
+  nativeHeapBytes: number;
+  /** Total process resident set size (RSS) in bytes */
+  residentBytes: number;
+  /** Available system memory in bytes */
+  availableMemoryBytes: number;
+  /** Whether the system considers memory low */
+  isLowMemory: boolean;
+}
+
 /**
  * LiteRT-LM: High-performance LLM inference engine.
  * Supports Gemma 3n, Phi-4, Qwen, and other .litertlm models.
@@ -204,6 +219,12 @@ export interface LiteRTLM extends HybridObject<{
    */
   getStats(): GenerationStats;
 
+  /**
+   * Get real memory usage from the native runtime.
+   * Uses OS-level APIs to report actual memory consumption.
+   */
+  getMemoryUsage(): MemoryUsage;
+
   /**
    * Release all native resources.
    * Call this when done with the LLM instance.