@dr33m/react-native-litert-lm 0.5.0

package/lib/memoryTracker.d.ts

@@ -0,0 +1,128 @@
+/**
+ * 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.35+) 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`);
+ * ```
+ */
+/**
+ * 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;
+}
+/**
+ * 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 declare function createMemoryTracker(maxSnapshots?: number): MemoryTracker;
+/**
+ * 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 declare function createNativeBuffer(size: number): ArrayBuffer;

package/lib/memoryTracker.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * 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.35+) 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`);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMemoryTracker = createMemoryTracker;
+exports.createNativeBuffer = createNativeBuffer;
+const react_native_nitro_modules_1 = require("react-native-nitro-modules");
+/** Number of Float64 fields per snapshot */
+const FIELDS_PER_SNAPSHOT = 4;
+/** Bytes per Float64 value */
+const BYTES_PER_FIELD = Float64Array.BYTES_PER_ELEMENT; // 8
+/**
+ * Create a new memory tracker backed by a native ArrayBuffer.
+ *
+ * @param maxSnapshots Maximum number of snapshots to store (default: 256)
+ * @returns A MemoryTracker instance
+ */
+function createMemoryTracker(maxSnapshots = 256) {
+    const bufferSize = maxSnapshots * FIELDS_PER_SNAPSHOT * BYTES_PER_FIELD;
+    // Use NitroModules.createNativeArrayBuffer for native-backed allocation.
+    const nativeBuffer = react_native_nitro_modules_1.NitroModules.createNativeArrayBuffer(bufferSize);
+    const view = new Float64Array(nativeBuffer);
+    let currentIndex = 0;
+    return {
+        record(snapshot) {
+            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() {
+            const snapshots = [];
+            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() {
+            return currentIndex;
+        },
+        getCapacity() {
+            return maxSnapshots;
+        },
+        getPeakMemory() {
+            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() {
+            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() {
+            return nativeBuffer;
+        },
+        getView() {
+            return view;
+        },
+        reset() {
+            view.fill(0);
+            currentIndex = 0;
+        },
+        getSummary() {
+            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
+ */
+function createNativeBuffer(size) {
+    return react_native_nitro_modules_1.NitroModules.createNativeArrayBuffer(size);
+}

package/lib/modelFactory.d.ts

@@ -0,0 +1,24 @@
+import { LiteRTLM, LLMConfig } from "./specs/LiteRTLM.nitro";
+import { MemoryTracker } from "./memoryTracker";
+/**
+ * Extended LiteRT-LM instance with optional memory tracking and
+ * augmented loadModel that accepts a download progress callback.
+ */
+export type LiteRTLMInstance = Omit<LiteRTLM, "loadModel"> & {
+    memoryTracker?: MemoryTracker;
+    loadModel: (pathOrUrl: string, config?: LLMConfig, onDownloadProgress?: (progress: number) => void) => Promise<void>;
+};
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * Optionally creates a native-backed memory tracker using
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) 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 declare function createLLM(options?: {
+    enableMemoryTracking?: boolean;
+    maxMemorySnapshots?: number;
+}): LiteRTLMInstance;

package/lib/modelFactory.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLLM = createLLM;
+const react_native_nitro_modules_1 = require("react-native-nitro-modules");
+const memoryTracker_1 = require("./memoryTracker");
+const modelRegistry_1 = require("./modelRegistry");
+const inferenceRouting_1 = require("./inferenceRouting");
+/**
+ * Creates a new LiteRT-LM inference engine instance.
+ *
+ * Optionally creates a native-backed memory tracker using
+ * `NitroModules.createNativeArrayBuffer()` (v0.35+) 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)
+ */
+function createLLM(options) {
+    const native = react_native_nitro_modules_1.NitroModules.createHybridObject("LiteRTLM");
+    const enableTracking = options?.enableMemoryTracking ?? false;
+    const tracker = enableTracking
+        ? (0, memoryTracker_1.createMemoryTracker)(options?.maxMemorySnapshots ?? 256)
+        : undefined;
+    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 {
+            // Non-critical
+        }
+    };
+    const augmentedLoadModel = async (pathOrUrl, config, onDownloadProgress) => {
+        console.log(`Resolving model at ${pathOrUrl}...`);
+        const modelPath = await modelRegistry_1.ModelRegistry.resolveModel(pathOrUrl, {
+            onProgress: onDownloadProgress,
+        });
+        console.log(`Model resolved to: ${modelPath}`);
+        const result = await native.loadModel(modelPath, config);
+        if (tracker) {
+            tracker.reset();
+            recordMemorySnapshot();
+        }
+        return result;
+    };
+    /** Single JS inference path — always calls native execute(). */
+    const runExecute = (parts, onToken) => {
+        const processedParts = parts.map((part) => {
+            if (part.path?.startsWith("file://")) {
+                return { ...part, path: part.path.substring(7) };
+            }
+            return part;
+        });
+        if (onToken) {
+            const wrapped = (token, done) => {
+                onToken(token, done);
+                if (done)
+                    recordMemorySnapshot();
+            };
+            return native.execute(processedParts, wrapped);
+        }
+        return native.execute(processedParts, undefined).then((result) => {
+            recordMemorySnapshot();
+            return result;
+        });
+    };
+    return new Proxy(native, {
+        get(target, prop, receiver) {
+            if (typeof prop !== "string") {
+                return Reflect.get(target, prop, receiver);
+            }
+            if (prop === "memoryTracker") {
+                return tracker;
+            }
+            if (prop === "loadModel") {
+                return augmentedLoadModel;
+            }
+            if (prop === "execute") {
+                return (parts, onToken) => runExecute(parts, onToken);
+            }
+            if (prop === "stopGeneration") {
+                return () => target.stopGeneration();
+            }
+            if (prop === "resetConversation") {
+                return () => {
+                    const result = target.resetConversation();
+                    recordMemorySnapshot();
+                    return result;
+                };
+            }
+            if (prop === "sendToolResponse") {
+                return (responses, onToken) => {
+                    if (onToken) {
+                        const wrapped = (token, done) => {
+                            onToken(token, done);
+                            if (done)
+                                recordMemorySnapshot();
+                        };
+                        return native.sendToolResponse(responses, wrapped);
+                    }
+                    return native.sendToolResponse(responses, undefined).then((result) => {
+                        recordMemorySnapshot();
+                        return result;
+                    });
+                };
+            }
+            if ((0, inferenceRouting_1.isLegacyInferenceMethod)(prop)) {
+                return (...args) => {
+                    const route = (0, inferenceRouting_1.routeLegacyInference)(prop, args);
+                    const promise = runExecute(route.parts, route.onToken);
+                    return prop.endsWith("Async") ? promise.then(() => { }) : promise;
+                };
+            }
+            const original = target[prop];
+            if (typeof original === "function") {
+                return original.bind(target);
+            }
+            return original;
+        },
+    });
+}

package/lib/modelPath.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonical path/URL helpers for model files.
+ * Used by ModelRegistry, hooks, and any download/cache logic.
+ */
+/** Extract a filename from a URL or file path (query string stripped). */
+export declare function extractFileName(pathOrUrl: string): string;
+/** Resolve a cache key from a filename, local path, or HTTPS URL. */
+export declare function resolveModelFileName(pathOrUrl: string): string;

package/lib/modelPath.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Canonical path/URL helpers for model files.
+ * Used by ModelRegistry, hooks, and any download/cache logic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractFileName = extractFileName;
+exports.resolveModelFileName = resolveModelFileName;
+/** Extract a filename from a URL or file path (query string stripped). */
+function extractFileName(pathOrUrl) {
+    const urlWithoutQuery = pathOrUrl.split("?")[0];
+    const name = urlWithoutQuery.split("/").pop();
+    return name || "model.bin";
+}
+/** Resolve a cache key from a filename, local path, or HTTPS URL. */
+function resolveModelFileName(pathOrUrl) {
+    return pathOrUrl.includes("/") ? extractFileName(pathOrUrl) : pathOrUrl;
+}

package/lib/modelRegistry.d.ts

@@ -0,0 +1,55 @@
+import type { ModelFile } from "./specs/LiteRTLM.nitro";
+export type { ModelFile } from "./specs/LiteRTLM.nitro";
+export interface ModelDownloadOptions {
+    headers?: Record<string, string>;
+    onProgress?: (progress: number) => void;
+}
+/**
+ * High-performance Model Registry for react-native-litert-lm.
+ *
+ * Coordinates URL sniffing, HTTPS enforcement, atomic downloading with progress,
+ * and cache queries. Serves as the single source of truth for model storage status.
+ */
+export declare const ModelRegistry: {
+    /**
+     * Check if a model file is cached locally.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL
+     * @returns true if cached and has size > 0
+     */
+    isCached(pathOrUrl: string): boolean;
+    /**
+     * Get the absolute local path of a cached model.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL
+     * @returns The absolute local path
+     */
+    getFilePath(pathOrUrl: string): string;
+    /**
+     * List all locally cached model files.
+     *
+     * @returns Array of ModelFile descriptors containing path, size, and mod time
+     */
+    listCachedFiles(): ModelFile[];
+    /**
+     * Delete a cached model file.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL to delete
+     */
+    deleteFile(pathOrUrl: string): void;
+    /**
+     * Resolve a model path or URL.
+     *
+     * Sniffs the protocol. If it is an HTTPS URL, downloads it to the native
+     * cache directory (and throttles callbacks) if not already cached. If it is a
+     * local path, returns it directly.
+     *
+     * @param pathOrUrl Local filepath or HTTPS download URL
+     * @param options Custom HTTP headers and progress callback
+     * @returns Promise resolving to the absolute local path of the model
+     */
+    resolveModel(pathOrUrl: string, options?: ModelDownloadOptions): Promise<string>;
+};

package/lib/modelRegistry.js

@@ -0,0 +1,82 @@
+"use strict";
+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");
+/**
+ * High-performance Model Registry for react-native-litert-lm.
+ *
+ * Coordinates URL sniffing, HTTPS enforcement, atomic downloading with progress,
+ * and cache queries. Serves as the single source of truth for model storage status.
+ */
+exports.ModelRegistry = {
+    /**
+     * Check if a model file is cached locally.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL
+     * @returns true if cached and has size > 0
+     */
+    isCached(pathOrUrl) {
+        return nativeStore.isCached((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+    },
+    /**
+     * Get the absolute local path of a cached model.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL
+     * @returns The absolute local path
+     */
+    getFilePath(pathOrUrl) {
+        return nativeStore.getFilePath((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+    },
+    /**
+     * List all locally cached model files.
+     *
+     * @returns Array of ModelFile descriptors containing path, size, and mod time
+     */
+    listCachedFiles() {
+        return nativeStore.listCachedFiles();
+    },
+    /**
+     * Delete a cached model file.
+     * Accepts a filename, local path, or HTTPS URL.
+     *
+     * @param pathOrUrl Filename, local path, or download URL to delete
+     */
+    deleteFile(pathOrUrl) {
+        nativeStore.deleteFile((0, modelPath_1.resolveModelFileName)(pathOrUrl));
+    },
+    /**
+     * Resolve a model path or URL.
+     *
+     * Sniffs the protocol. If it is an HTTPS URL, downloads it to the native
+     * cache directory (and throttles callbacks) if not already cached. If it is a
+     * local path, returns it directly.
+     *
+     * @param pathOrUrl Local filepath or HTTPS download URL
+     * @param options Custom HTTP headers and progress callback
+     * @returns Promise resolving to the absolute local path of the model
+     */
+    async resolveModel(pathOrUrl, options) {
+        const cleanPath = pathOrUrl.startsWith("file://") ? pathOrUrl.substring(7) : pathOrUrl;
+        if (cleanPath.startsWith("http://") || cleanPath.startsWith("https://")) {
+            if (cleanPath.startsWith("http://")) {
+                throw new Error("Insecure HTTP URLs are not allowed for model downloads. " +
+                    "Use HTTPS instead: " +
+                    cleanPath.replace("http://", "https://"));
+            }
+            const urlWithoutQuery = cleanPath.split("?")[0];
+            const fileName = urlWithoutQuery.split("/").pop();
+            if (!fileName) {
+                throw new Error(`Invalid model URL: ${cleanPath}`);
+            }
+            const headersJson = options?.headers ? JSON.stringify(options.headers) : "{}";
+            return nativeStore.downloadFile(cleanPath, fileName, headersJson, (progress) => {
+                options?.onProgress?.(progress);
+            });
+        }
+        return cleanPath;
+    }
+};