react-native-nitro-mlx 0.1.0

package/MLXReactNative.podspec

@@ -0,0 +1,42 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "MLXReactNative"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => 26.0, :visionos => 1.0 }
+  s.source       = { :git => "https://github.com/corasan/react-native-nitro-mlx.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/Sources/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  spm_dependency(s,
+    url: "https://github.com/ml-explore/mlx-swift-lm.git",
+    requirement: {kind: "upToNextMinorVersion", minimumVersion: "2.29.2"},
+    products: ["MLXLLM", "MLXLMCommon"]
+  )
+
+  s.pod_target_xcconfig = {
+    # C++ compiler flags, mainly for folly.
+    "GCC_PREPROCESSOR_DEFINITIONS" => "$(inherited) FOLLY_NO_CONFIG FOLLY_CFG_NO_COROUTINES"
+  }
+
+  load 'nitrogen/generated/ios/MLXReactNative+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/ios/Bridge.h

@@ -0,0 +1,8 @@
+//
+//  Bridge.h
+//  mlx
+//
+//  Created by Henry Paulino on 2/20/2025
+//
+
+#pragma once

package/ios/Sources/MLXReactNative.h

@@ -0,0 +1,16 @@
+//
+//  MLXReactNative.h
+//  MLXReactNative
+//
+//  Created by Henry on 2/20/25.
+//
+
+#import <Foundation/Foundation.h>
+
+//! Project version number for MLXReactNative.
+FOUNDATION_EXPORT double MLXReactNativeVersionNumber;
+
+//! Project version string for MLXReactNative.
+FOUNDATION_EXPORT const unsigned char MLXReactNativeVersionString[];
+
+// In this header, you should import all the public headers of your framework using statements like #import <MLXReactNative/PublicHeader.h>

package/lib/module/index.js

@@ -0,0 +1,6 @@
+"use strict";
+
+export { LLM } from "./llm.js";
+export { ModelManager } from "./modelManager.js";
+export { MLXModel } from "./models.js";
+//# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["LLM","ModelManager","MLXModel"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;AAAA,SAASA,GAAG,QAAQ,UAAO;AAC3B,SAASC,YAAY,QAAQ,mBAAgB;AAC7C,SAASC,QAAQ,QAAQ,aAAU","ignoreList":[]}

package/lib/module/llm.js

@@ -0,0 +1,105 @@
+"use strict";
+
+import { NitroModules } from 'react-native-nitro-modules';
+let instance = null;
+function getInstance() {
+  if (!instance) {
+    instance = NitroModules.createHybridObject('LLM');
+  }
+  return instance;
+}
+
+/**
+ * LLM text generation using MLX on Apple Silicon.
+ *
+ * @example
+ * ```ts
+ * import { LLM } from 'react-native-nitro-mlx'
+ *
+ * // Load a model
+ * await LLM.load('mlx-community/Qwen3-0.6B-4bit', progress => {
+ *   console.log(`Loading: ${(progress * 100).toFixed(0)}%`)
+ * })
+ *
+ * // Stream a response
+ * await LLM.stream('Hello!', token => {
+ *   process.stdout.write(token)
+ * })
+ *
+ * // Get generation stats
+ * const stats = LLM.getLastGenerationStats()
+ * console.log(`${stats.tokensPerSecond} tokens/sec`)
+ * ```
+ */
+export const LLM = {
+  /**
+   * Load a model into memory. Downloads the model from HuggingFace if not already cached.
+   * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+   * @param onProgress - Callback invoked with loading progress (0-1)
+   */
+  load(modelId, onProgress) {
+    return getInstance().load(modelId, onProgress);
+  },
+  /**
+   * Generate a complete response for a prompt. Blocks until generation is complete.
+   * For streaming responses, use `stream()` instead.
+   * @param prompt - The input text to generate a response for
+   * @returns The complete generated text
+   */
+  generate(prompt) {
+    return getInstance().generate(prompt);
+  },
+  /**
+   * Stream a response token by token.
+   * @param prompt - The input text to generate a response for
+   * @param onToken - Callback invoked for each generated token
+   * @returns The complete generated text
+   */
+  stream(prompt, onToken) {
+    return getInstance().stream(prompt, onToken);
+  },
+  /**
+   * Stop the current generation. Safe to call even if not generating.
+   */
+  stop() {
+    getInstance().stop();
+  },
+  /**
+   * Get statistics from the last generation.
+   * @returns Statistics including token count, tokens/sec, TTFT, and total time
+   */
+  getLastGenerationStats() {
+    return getInstance().getLastGenerationStats();
+  },
+  /** Whether a model is currently loaded and ready for generation */
+  get isLoaded() {
+    return getInstance().isLoaded;
+  },
+  /** Whether text is currently being generated */
+  get isGenerating() {
+    return getInstance().isGenerating;
+  },
+  /** The ID of the currently loaded model, or empty string if none */
+  get modelId() {
+    return getInstance().modelId;
+  },
+  /** Enable debug logging to console */
+  get debug() {
+    return getInstance().debug;
+  },
+  set debug(value) {
+    getInstance().debug = value;
+  },
+  /**
+   * System prompt used when loading the model.
+   * Set this before calling `load()`. Changes require reloading the model.
+   * @default "You are a helpful assistant."
+   */
+  get systemPrompt() {
+    return getInstance().systemPrompt;
+  },
+  set systemPrompt(value) {
+    getInstance().systemPrompt = value;
+  }
+};
+//# sourceMappingURL=llm.js.map

package/lib/module/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NitroModules","instance","getInstance","createHybridObject","LLM","load","modelId","onProgress","generate","prompt","stream","onToken","stop","getLastGenerationStats","isLoaded","isGenerating","debug","value","systemPrompt"],"sourceRoot":"../../src","sources":["llm.ts"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,IAAIC,QAAwB,GAAG,IAAI;AAEnC,SAASC,WAAWA,CAAA,EAAY;EAC9B,IAAI,CAACD,QAAQ,EAAE;IACbA,QAAQ,GAAGD,YAAY,CAACG,kBAAkB,CAAU,KAAK,CAAC;EAC5D;EACA,OAAOF,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,GAAG,GAAG;EACjB;AACF;AACA;AACA;AACA;EACEC,IAAIA,CAACC,OAAe,EAAEC,UAAsC,EAAiB;IAC3E,OAAOL,WAAW,CAAC,CAAC,CAACG,IAAI,CAACC,OAAO,EAAEC,UAAU,CAAC;EAChD,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,QAAQA,CAACC,MAAc,EAAmB;IACxC,OAAOP,WAAW,CAAC,CAAC,CAACM,QAAQ,CAACC,MAAM,CAAC;EACvC,CAAC;EAED;AACF;AACA;AACA;AACA;AACA;EACEC,MAAMA,CAACD,MAAc,EAAEE,OAAgC,EAAmB;IACxE,OAAOT,WAAW,CAAC,CAAC,CAACQ,MAAM,CAACD,MAAM,EAAEE,OAAO,CAAC;EAC9C,CAAC;EAED;AACF;AACA;EACEC,IAAIA,CAAA,EAAS;IACXV,WAAW,CAAC,CAAC,CAACU,IAAI,CAAC,CAAC;EACtB,CAAC;EAED;AACF;AACA;AACA;EACEC,sBAAsBA,CAAA,EAAoB;IACxC,OAAOX,WAAW,CAAC,CAAC,CAACW,sBAAsB,CAAC,CAAC;EAC/C,CAAC;EAED;EACA,IAAIC,QAAQA,CAAA,EAAY;IACtB,OAAOZ,WAAW,CAAC,CAAC,CAACY,QAAQ;EAC/B,CAAC;EAED;EACA,IAAIC,YAAYA,CAAA,EAAY;IAC1B,OAAOb,WAAW,CAAC,CAAC,CAACa,YAAY;EACnC,CAAC;EAED;EACA,IAAIT,OAAOA,CAAA,EAAW;IACpB,OAAOJ,WAAW,CAAC,CAAC,CAACI,OAAO;EAC9B,CAAC;EAED;EACA,IAAIU,KAAKA,CAAA,EAAY;IACnB,OAAOd,WAAW,CAAC,CAAC,CAACc,KAAK;EAC5B,CAAC;EAED,IAAIA,KAAKA,CAACC,KAAc,EAAE;IACxBf,WAAW,CAAC,CAAC,CAACc,KAAK,GAAGC,KAAK;EAC7B,CAAC;EAED;AACF;AACA;AACA;AACA;EACE,IAAIC,YAAYA,CAAA,EAAW;IACzB,OAAOhB,WAAW,CAAC,CAAC,CAACgB,YAAY;EACnC,CAAC;EAED,IAAIA,YAAYA,CAACD,KAAa,EAAE;IAC9Bf,WAAW,CAAC,CAAC,CAACgB,YAAY,GAAGD,KAAK;EACpC;AACF,CAAC","ignoreList":[]}

package/lib/module/modelManager.js

@@ -0,0 +1,79 @@
+"use strict";
+
+import { NitroModules } from 'react-native-nitro-modules';
+let instance = null;
+function getInstance() {
+  if (!instance) {
+    instance = NitroModules.createHybridObject('ModelManager');
+  }
+  return instance;
+}
+
+/**
+ * Manage MLX model downloads from HuggingFace.
+ *
+ * @example
+ * ```ts
+ * import { ModelManager } from 'react-native-nitro-mlx'
+ *
+ * // Download a model
+ * await ModelManager.download('mlx-community/Qwen3-0.6B-4bit', progress => {
+ *   console.log(`Downloading: ${(progress * 100).toFixed(0)}%`)
+ * })
+ *
+ * // Check if downloaded
+ * const isReady = await ModelManager.isDownloaded('mlx-community/Qwen3-0.6B-4bit')
+ *
+ * // List all downloaded models
+ * const models = await ModelManager.getDownloadedModels()
+ * ```
+ */
+export const ModelManager = {
+  /**
+   * Download a model from HuggingFace.
+   * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+   * @param progressCallback - Callback invoked with download progress (0-1)
+   * @returns Path to the downloaded model directory
+   */
+  download(modelId, progressCallback) {
+    return getInstance().download(modelId, progressCallback);
+  },
+  /**
+   * Check if a model is already downloaded.
+   * @param modelId - HuggingFace model ID
+   * @returns True if the model is fully downloaded
+   */
+  isDownloaded(modelId) {
+    return getInstance().isDownloaded(modelId);
+  },
+  /**
+   * Get a list of all downloaded model IDs.
+   * @returns Array of model IDs that are available locally
+   */
+  getDownloadedModels() {
+    return getInstance().getDownloadedModels();
+  },
+  /**
+   * Delete a downloaded model to free up disk space.
+   * @param modelId - HuggingFace model ID
+   */
+  deleteModel(modelId) {
+    return getInstance().deleteModel(modelId);
+  },
+  /**
+   * Get the local filesystem path for a downloaded model.
+   * @param modelId - HuggingFace model ID
+   * @returns Absolute path to the model directory
+   */
+  getModelPath(modelId) {
+    return getInstance().getModelPath(modelId);
+  },
+  /** Enable debug logging to console */
+  get debug() {
+    return getInstance().debug;
+  },
+  set debug(value) {
+    getInstance().debug = value;
+  }
+};
+//# sourceMappingURL=modelManager.js.map

package/lib/module/modelManager.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["NitroModules","instance","getInstance","createHybridObject","ModelManager","download","modelId","progressCallback","isDownloaded","getDownloadedModels","deleteModel","getModelPath","debug","value"],"sourceRoot":"../../src","sources":["modelManager.ts"],"mappings":";;AAAA,SAASA,YAAY,QAAQ,4BAA4B;AAGzD,IAAIC,QAAiC,GAAG,IAAI;AAE5C,SAASC,WAAWA,CAAA,EAAqB;EACvC,IAAI,CAACD,QAAQ,EAAE;IACbA,QAAQ,GAAGD,YAAY,CAACG,kBAAkB,CAAmB,cAAc,CAAC;EAC9E;EACA,OAAOF,QAAQ;AACjB;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMG,YAAY,GAAG;EAC1B;AACF;AACA;AACA;AACA;AACA;EACEC,QAAQA,CACNC,OAAe,EACfC,gBAA4C,EAC3B;IACjB,OAAOL,WAAW,CAAC,CAAC,CAACG,QAAQ,CAACC,OAAO,EAAEC,gBAAgB,CAAC;EAC1D,CAAC;EAED;AACF;AACA;AACA;AACA;EACEC,YAAYA,CAACF,OAAe,EAAoB;IAC9C,OAAOJ,WAAW,CAAC,CAAC,CAACM,YAAY,CAACF,OAAO,CAAC;EAC5C,CAAC;EAED;AACF;AACA;AACA;EACEG,mBAAmBA,CAAA,EAAsB;IACvC,OAAOP,WAAW,CAAC,CAAC,CAACO,mBAAmB,CAAC,CAAC;EAC5C,CAAC;EAED;AACF;AACA;AACA;EACEC,WAAWA,CAACJ,OAAe,EAAiB;IAC1C,OAAOJ,WAAW,CAAC,CAAC,CAACQ,WAAW,CAACJ,OAAO,CAAC;EAC3C,CAAC;EAED;AACF;AACA;AACA;AACA;EACEK,YAAYA,CAACL,OAAe,EAAmB;IAC7C,OAAOJ,WAAW,CAAC,CAAC,CAACS,YAAY,CAACL,OAAO,CAAC;EAC5C,CAAC;EAED;EACA,IAAIM,KAAKA,CAAA,EAAY;IACnB,OAAOV,WAAW,CAAC,CAAC,CAACU,KAAK;EAC5B,CAAC;EAED,IAAIA,KAAKA,CAACC,KAAc,EAAE;IACxBX,WAAW,CAAC,CAAC,CAACU,KAAK,GAAGC,KAAK;EAC7B;AACF,CAAC","ignoreList":[]}

package/lib/module/models.js

@@ -0,0 +1,41 @@
+"use strict";
+
+export let MLXModel = /*#__PURE__*/function (MLXModel) {
+  // Llama 3.2 (Meta) - 1B and 3B variants
+  MLXModel["Llama_3_2_1B_Instruct_4bit"] = "mlx-community/Llama-3.2-1B-Instruct-4bit";
+  MLXModel["Llama_3_2_1B_Instruct_8bit"] = "mlx-community/Llama-3.2-1B-Instruct-8bit";
+  MLXModel["Llama_3_2_3B_Instruct_4bit"] = "mlx-community/Llama-3.2-3B-Instruct-4bit";
+  MLXModel["Llama_3_2_3B_Instruct_8bit"] = "mlx-community/Llama-3.2-3B-Instruct-8bit";
+  // Qwen 2.5 (Alibaba) - 0.5B, 1.5B, 3B variants
+  MLXModel["Qwen2_5_0_5B_Instruct_4bit"] = "mlx-community/Qwen2.5-0.5B-Instruct-4bit";
+  MLXModel["Qwen2_5_0_5B_Instruct_8bit"] = "mlx-community/Qwen2.5-0.5B-Instruct-8bit";
+  MLXModel["Qwen2_5_1_5B_Instruct_4bit"] = "mlx-community/Qwen2.5-1.5B-Instruct-4bit";
+  MLXModel["Qwen2_5_1_5B_Instruct_8bit"] = "mlx-community/Qwen2.5-1.5B-Instruct-8bit";
+  MLXModel["Qwen2_5_3B_Instruct_4bit"] = "mlx-community/Qwen2.5-3B-Instruct-4bit";
+  MLXModel["Qwen2_5_3B_Instruct_8bit"] = "mlx-community/Qwen2.5-3B-Instruct-8bit";
+  // Qwen 3 - 1.7B variant
+  MLXModel["Qwen3_1_7B_4bit"] = "mlx-community/Qwen3-1.7B-4bit";
+  MLXModel["Qwen3_1_7B_8bit"] = "mlx-community/Qwen3-1.7B-8bit";
+  // Gemma 3 (Google) - 1B variant
+  MLXModel["Gemma_3_1B_IT_4bit"] = "mlx-community/gemma-3-1b-it-4bit";
+  MLXModel["Gemma_3_1B_IT_8bit"] = "mlx-community/gemma-3-1b-it-8bit";
+  // Phi 3.5 Mini (Microsoft) - ~3.8B but runs well on mobile
+  MLXModel["Phi_3_5_Mini_Instruct_4bit"] = "mlx-community/Phi-3.5-mini-instruct-4bit";
+  MLXModel["Phi_3_5_Mini_Instruct_8bit"] = "mlx-community/Phi-3.5-mini-instruct-8bit";
+  // Phi 4 Mini (Microsoft)
+  MLXModel["Phi_4_Mini_Instruct_4bit"] = "mlx-community/Phi-4-mini-instruct-4bit";
+  MLXModel["Phi_4_Mini_Instruct_8bit"] = "mlx-community/Phi-4-mini-instruct-8bit";
+  // SmolLM (HuggingFace) - 1.7B
+  MLXModel["SmolLM_1_7B_Instruct_4bit"] = "mlx-community/SmolLM-1.7B-Instruct-4bit";
+  MLXModel["SmolLM_1_7B_Instruct_8bit"] = "mlx-community/SmolLM-1.7B-Instruct-8bit";
+  // SmolLM2 (HuggingFace) - 1.7B
+  MLXModel["SmolLM2_1_7B_Instruct_4bit"] = "mlx-community/SmolLM2-1.7B-Instruct-4bit";
+  MLXModel["SmolLM2_1_7B_Instruct_8bit"] = "mlx-community/SmolLM2-1.7B-Instruct-8bit";
+  // OpenELM (Apple) - 1.1B and 3B
+  MLXModel["OpenELM_1_1B_4bit"] = "mlx-community/OpenELM-1_1B-4bit";
+  MLXModel["OpenELM_1_1B_8bit"] = "mlx-community/OpenELM-1_1B-8bit";
+  MLXModel["OpenELM_3B_4bit"] = "mlx-community/OpenELM-3B-4bit";
+  MLXModel["OpenELM_3B_8bit"] = "mlx-community/OpenELM-3B-8bit";
+  return MLXModel;
+}({});
+//# sourceMappingURL=models.js.map

package/lib/module/models.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["MLXModel"],"sourceRoot":"../../src","sources":["models.ts"],"mappings":";;AAAA,WAAYA,QAAQ,0BAARA,QAAQ;EAClB;EADUA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAOlB;EAPUA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAelB;EAfUA,QAAQ;EAARA,QAAQ;EAmBlB;EAnBUA,QAAQ;EAARA,QAAQ;EAuBlB;EAvBUA,QAAQ;EAARA,QAAQ;EA2BlB;EA3BUA,QAAQ;EAARA,QAAQ;EA+BlB;EA/BUA,QAAQ;EAARA,QAAQ;EAmClB;EAnCUA,QAAQ;EAARA,QAAQ;EAuClB;EAvCUA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAARA,QAAQ;EAAA,OAARA,QAAQ;AAAA","ignoreList":[]}

package/lib/module/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/module/specs/LLM.nitro.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=LLM.nitro.js.map

package/lib/module/specs/LLM.nitro.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["specs/LLM.nitro.ts"],"mappings":"","ignoreList":[]}

package/lib/module/specs/ModelManager.nitro.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=ModelManager.nitro.js.map

package/lib/module/specs/ModelManager.nitro.js.map

@@ -0,0 +1 @@
+{"version":3,"names":[],"sourceRoot":"../../../src","sources":["specs/ModelManager.nitro.ts"],"mappings":"","ignoreList":[]}

package/lib/typescript/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/lib/typescript/src/index.d.ts

@@ -0,0 +1,6 @@
+export { LLM } from './llm';
+export { ModelManager } from './modelManager';
+export { MLXModel } from './models';
+export type { GenerationStats, LLM as LLMSpec } from './specs/LLM.nitro';
+export type { ModelManager as ModelManagerSpec } from './specs/ModelManager.nitro';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAC3B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,YAAY,EAAE,eAAe,EAAE,GAAG,IAAI,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACxE,YAAY,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,4BAA4B,CAAA"}

package/lib/typescript/src/llm.d.ts

@@ -0,0 +1,69 @@
+import type { GenerationStats } from './specs/LLM.nitro';
+/**
+ * LLM text generation using MLX on Apple Silicon.
+ *
+ * @example
+ * ```ts
+ * import { LLM } from 'react-native-nitro-mlx'
+ *
+ * // Load a model
+ * await LLM.load('mlx-community/Qwen3-0.6B-4bit', progress => {
+ *   console.log(`Loading: ${(progress * 100).toFixed(0)}%`)
+ * })
+ *
+ * // Stream a response
+ * await LLM.stream('Hello!', token => {
+ *   process.stdout.write(token)
+ * })
+ *
+ * // Get generation stats
+ * const stats = LLM.getLastGenerationStats()
+ * console.log(`${stats.tokensPerSecond} tokens/sec`)
+ * ```
+ */
+export declare const LLM: {
+    /**
+     * Load a model into memory. Downloads the model from HuggingFace if not already cached.
+     * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+     * @param onProgress - Callback invoked with loading progress (0-1)
+     */
+    load(modelId: string, onProgress: (progress: number) => void): Promise<void>;
+    /**
+     * Generate a complete response for a prompt. Blocks until generation is complete.
+     * For streaming responses, use `stream()` instead.
+     * @param prompt - The input text to generate a response for
+     * @returns The complete generated text
+     */
+    generate(prompt: string): Promise<string>;
+    /**
+     * Stream a response token by token.
+     * @param prompt - The input text to generate a response for
+     * @param onToken - Callback invoked for each generated token
+     * @returns The complete generated text
+     */
+    stream(prompt: string, onToken: (token: string) => void): Promise<string>;
+    /**
+     * Stop the current generation. Safe to call even if not generating.
+     */
+    stop(): void;
+    /**
+     * Get statistics from the last generation.
+     * @returns Statistics including token count, tokens/sec, TTFT, and total time
+     */
+    getLastGenerationStats(): GenerationStats;
+    /** Whether a model is currently loaded and ready for generation */
+    readonly isLoaded: boolean;
+    /** Whether text is currently being generated */
+    readonly isGenerating: boolean;
+    /** The ID of the currently loaded model, or empty string if none */
+    readonly modelId: string;
+    /** Enable debug logging to console */
+    debug: boolean;
+    /**
+     * System prompt used when loading the model.
+     * Set this before calling `load()`. Changes require reloading the model.
+     * @default "You are a helpful assistant."
+     */
+    systemPrompt: string;
+};
+//# sourceMappingURL=llm.d.ts.map

package/lib/typescript/src/llm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../src/llm.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,mBAAmB,CAAA;AAWxE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,GAAG;IACd;;;;OAIG;kBACW,MAAM,cAAc,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5E;;;;;OAKG;qBACc,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzC;;;;;OAKG;mBACY,MAAM,WAAW,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC;IAIzE;;OAEG;YACK,IAAI;IAIZ;;;OAGG;8BACuB,eAAe;IAIzC,mEAAmE;uBACnD,OAAO;IAIvB,gDAAgD;2BAC5B,OAAO;IAI3B,oEAAoE;sBACrD,MAAM;IAIrB,sCAAsC;WACzB,OAAO;IAQpB;;;;OAIG;kBACiB,MAAM;CAO3B,CAAA"}

package/lib/typescript/src/modelManager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Manage MLX model downloads from HuggingFace.
+ *
+ * @example
+ * ```ts
+ * import { ModelManager } from 'react-native-nitro-mlx'
+ *
+ * // Download a model
+ * await ModelManager.download('mlx-community/Qwen3-0.6B-4bit', progress => {
+ *   console.log(`Downloading: ${(progress * 100).toFixed(0)}%`)
+ * })
+ *
+ * // Check if downloaded
+ * const isReady = await ModelManager.isDownloaded('mlx-community/Qwen3-0.6B-4bit')
+ *
+ * // List all downloaded models
+ * const models = await ModelManager.getDownloadedModels()
+ * ```
+ */
+export declare const ModelManager: {
+    /**
+     * Download a model from HuggingFace.
+     * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+     * @param progressCallback - Callback invoked with download progress (0-1)
+     * @returns Path to the downloaded model directory
+     */
+    download(modelId: string, progressCallback: (progress: number) => void): Promise<string>;
+    /**
+     * Check if a model is already downloaded.
+     * @param modelId - HuggingFace model ID
+     * @returns True if the model is fully downloaded
+     */
+    isDownloaded(modelId: string): Promise<boolean>;
+    /**
+     * Get a list of all downloaded model IDs.
+     * @returns Array of model IDs that are available locally
+     */
+    getDownloadedModels(): Promise<string[]>;
+    /**
+     * Delete a downloaded model to free up disk space.
+     * @param modelId - HuggingFace model ID
+     */
+    deleteModel(modelId: string): Promise<void>;
+    /**
+     * Get the local filesystem path for a downloaded model.
+     * @param modelId - HuggingFace model ID
+     * @returns Absolute path to the model directory
+     */
+    getModelPath(modelId: string): Promise<string>;
+    /** Enable debug logging to console */
+    debug: boolean;
+};
+//# sourceMappingURL=modelManager.d.ts.map

package/lib/typescript/src/modelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelManager.d.ts","sourceRoot":"","sources":["../../../src/modelManager.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,YAAY;IACvB;;;;;OAKG;sBAEQ,MAAM,oBACG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAC3C,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;OAIG;0BACmB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI/C;;;OAGG;2BACoB,OAAO,CAAC,MAAM,EAAE,CAAC;IAIxC;;;OAGG;yBACkB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C;;;;OAIG;0BACmB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9C,sCAAsC;WACzB,OAAO;CAOrB,CAAA"}

package/lib/typescript/src/models.d.ts

@@ -0,0 +1,29 @@
+export declare enum MLXModel {
+    Llama_3_2_1B_Instruct_4bit = "mlx-community/Llama-3.2-1B-Instruct-4bit",
+    Llama_3_2_1B_Instruct_8bit = "mlx-community/Llama-3.2-1B-Instruct-8bit",
+    Llama_3_2_3B_Instruct_4bit = "mlx-community/Llama-3.2-3B-Instruct-4bit",
+    Llama_3_2_3B_Instruct_8bit = "mlx-community/Llama-3.2-3B-Instruct-8bit",
+    Qwen2_5_0_5B_Instruct_4bit = "mlx-community/Qwen2.5-0.5B-Instruct-4bit",
+    Qwen2_5_0_5B_Instruct_8bit = "mlx-community/Qwen2.5-0.5B-Instruct-8bit",
+    Qwen2_5_1_5B_Instruct_4bit = "mlx-community/Qwen2.5-1.5B-Instruct-4bit",
+    Qwen2_5_1_5B_Instruct_8bit = "mlx-community/Qwen2.5-1.5B-Instruct-8bit",
+    Qwen2_5_3B_Instruct_4bit = "mlx-community/Qwen2.5-3B-Instruct-4bit",
+    Qwen2_5_3B_Instruct_8bit = "mlx-community/Qwen2.5-3B-Instruct-8bit",
+    Qwen3_1_7B_4bit = "mlx-community/Qwen3-1.7B-4bit",
+    Qwen3_1_7B_8bit = "mlx-community/Qwen3-1.7B-8bit",
+    Gemma_3_1B_IT_4bit = "mlx-community/gemma-3-1b-it-4bit",
+    Gemma_3_1B_IT_8bit = "mlx-community/gemma-3-1b-it-8bit",
+    Phi_3_5_Mini_Instruct_4bit = "mlx-community/Phi-3.5-mini-instruct-4bit",
+    Phi_3_5_Mini_Instruct_8bit = "mlx-community/Phi-3.5-mini-instruct-8bit",
+    Phi_4_Mini_Instruct_4bit = "mlx-community/Phi-4-mini-instruct-4bit",
+    Phi_4_Mini_Instruct_8bit = "mlx-community/Phi-4-mini-instruct-8bit",
+    SmolLM_1_7B_Instruct_4bit = "mlx-community/SmolLM-1.7B-Instruct-4bit",
+    SmolLM_1_7B_Instruct_8bit = "mlx-community/SmolLM-1.7B-Instruct-8bit",
+    SmolLM2_1_7B_Instruct_4bit = "mlx-community/SmolLM2-1.7B-Instruct-4bit",
+    SmolLM2_1_7B_Instruct_8bit = "mlx-community/SmolLM2-1.7B-Instruct-8bit",
+    OpenELM_1_1B_4bit = "mlx-community/OpenELM-1_1B-4bit",
+    OpenELM_1_1B_8bit = "mlx-community/OpenELM-1_1B-8bit",
+    OpenELM_3B_4bit = "mlx-community/OpenELM-3B-4bit",
+    OpenELM_3B_8bit = "mlx-community/OpenELM-3B-8bit"
+}
+//# sourceMappingURL=models.d.ts.map

package/lib/typescript/src/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/models.ts"],"names":[],"mappings":"AAAA,oBAAY,QAAQ;IAElB,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IAGvE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IACvE,wBAAwB,2CAA2C;IACnE,wBAAwB,2CAA2C;IAGnE,eAAe,kCAAkC;IACjD,eAAe,kCAAkC;IAGjD,kBAAkB,qCAAqC;IACvD,kBAAkB,qCAAqC;IAGvD,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IAGvE,wBAAwB,2CAA2C;IACnE,wBAAwB,2CAA2C;IAGnE,yBAAyB,4CAA4C;IACrE,yBAAyB,4CAA4C;IAGrE,0BAA0B,6CAA6C;IACvE,0BAA0B,6CAA6C;IAGvE,iBAAiB,oCAAoC;IACrD,iBAAiB,oCAAoC;IACrD,eAAe,kCAAkC;IACjD,eAAe,kCAAkC;CAClD"}

package/lib/typescript/src/specs/LLM.nitro.d.ts

@@ -0,0 +1,61 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+/**
+ * Statistics from the last text generation.
+ */
+export interface GenerationStats {
+    /** Total number of tokens generated */
+    tokenCount: number;
+    /** Generation speed in tokens per second */
+    tokensPerSecond: number;
+    /** Time in milliseconds until the first token was generated */
+    timeToFirstToken: number;
+    /** Total generation time in milliseconds */
+    totalTime: number;
+}
+/**
+ * Low-level LLM interface for text generation using MLX.
+ * @internal Use the `LLM` export from `react-native-nitro-mlx` instead.
+ */
+export interface LLM extends HybridObject<{
+    ios: 'swift';
+}> {
+    /**
+     * Load a model into memory. Downloads from HuggingFace if not already cached.
+     * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+     * @param onProgress - Callback invoked with loading progress (0-1)
+     */
+    load(modelId: string, onProgress: (progress: number) => void): Promise<void>;
+    /**
+     * Generate a complete response for a prompt.
+     * @param prompt - The input text to generate a response for
+     * @returns The generated text
+     */
+    generate(prompt: string): Promise<string>;
+    /**
+     * Stream a response token by token.
+     * @param prompt - The input text to generate a response for
+     * @param onToken - Callback invoked for each generated token
+     * @returns The complete generated text
+     */
+    stream(prompt: string, onToken: (token: string) => void): Promise<string>;
+    /**
+     * Stop the current generation.
+     */
+    stop(): void;
+    /**
+     * Get statistics from the last generation.
+     * @returns Statistics including token count, speed, and timing
+     */
+    getLastGenerationStats(): GenerationStats;
+    /** Whether a model is currently loaded */
+    readonly isLoaded: boolean;
+    /** Whether text is currently being generated */
+    readonly isGenerating: boolean;
+    /** The ID of the currently loaded model */
+    readonly modelId: string;
+    /** Enable debug logging */
+    debug: boolean;
+    /** System prompt used when loading the model */
+    systemPrompt: string;
+}
+//# sourceMappingURL=LLM.nitro.d.ts.map

package/lib/typescript/src/specs/LLM.nitro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLM.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/LLM.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,eAAe,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAA;IACxB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,GAAI,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;IACzD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE5E;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAEzE;;OAEG;IACH,IAAI,IAAI,IAAI,CAAA;IAEZ;;;OAGG;IACH,sBAAsB,IAAI,eAAe,CAAA;IAEzC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;IAC9B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;CACrB"}

package/lib/typescript/src/specs/ModelManager.nitro.d.ts

@@ -0,0 +1,41 @@
+import type { HybridObject } from 'react-native-nitro-modules';
+/**
+ * Low-level interface for managing MLX model downloads.
+ * @internal Use the `ModelManager` export from `react-native-nitro-mlx` instead.
+ */
+export interface ModelManager extends HybridObject<{
+    ios: 'swift';
+}> {
+    /**
+     * Download a model from HuggingFace.
+     * @param modelId - HuggingFace model ID (e.g., 'mlx-community/Qwen3-0.6B-4bit')
+     * @param progressCallback - Callback invoked with download progress (0-1)
+     * @returns Path to the downloaded model directory
+     */
+    download(modelId: string, progressCallback: (progress: number) => void): Promise<string>;
+    /**
+     * Check if a model is already downloaded.
+     * @param modelId - HuggingFace model ID
+     * @returns True if the model is downloaded
+     */
+    isDownloaded(modelId: string): Promise<boolean>;
+    /**
+     * Get a list of all downloaded model IDs.
+     * @returns Array of downloaded model IDs
+     */
+    getDownloadedModels(): Promise<string[]>;
+    /**
+     * Delete a downloaded model.
+     * @param modelId - HuggingFace model ID
+     */
+    deleteModel(modelId: string): Promise<void>;
+    /**
+     * Get the local filesystem path for a downloaded model.
+     * @param modelId - HuggingFace model ID
+     * @returns Path to the model directory
+     */
+    getModelPath(modelId: string): Promise<string>;
+    /** Enable debug logging */
+    debug: boolean;
+}
+//# sourceMappingURL=ModelManager.nitro.d.ts.map

package/lib/typescript/src/specs/ModelManager.nitro.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelManager.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/ModelManager.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;;GAGG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,CAAC;IAClE;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAExF;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAE/C;;;OAGG;IACH,mBAAmB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAExC;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE9C,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;CACf"}

package/nitrogen/generated/.gitattributes

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