react-native-nitro-mlx 0.1.0

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

@@ -0,0 +1,76 @@
+///
+/// HybridLLMSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `GenerationStats` to properly resolve imports.
+namespace margelo::nitro::mlxreactnative { struct GenerationStats; }
+
+#include <string>
+#include <NitroModules/Promise.hpp>
+#include <functional>
+#include "GenerationStats.hpp"
+
+namespace margelo::nitro::mlxreactnative {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `LLM`
+   * Inherit this class to create instances of `HybridLLMSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridLLM: public HybridLLMSpec {
+   * public:
+   *   HybridLLM(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridLLMSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridLLMSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridLLMSpec() override = default;
+
+    public:
+      // Properties
+      virtual bool getIsLoaded() = 0;
+      virtual bool getIsGenerating() = 0;
+      virtual std::string getModelId() = 0;
+      virtual bool getDebug() = 0;
+      virtual void setDebug(bool debug) = 0;
+      virtual std::string getSystemPrompt() = 0;
+      virtual void setSystemPrompt(const std::string& systemPrompt) = 0;
+
+    public:
+      // Methods
+      virtual std::shared_ptr<Promise<void>> load(const std::string& modelId, const std::function<void(double /* progress */)>& onProgress) = 0;
+      virtual std::shared_ptr<Promise<std::string>> generate(const std::string& prompt) = 0;
+      virtual std::shared_ptr<Promise<std::string>> stream(const std::string& prompt, const std::function<void(const std::string& /* token */)>& onToken) = 0;
+      virtual void stop() = 0;
+      virtual GenerationStats getLastGenerationStats() = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "LLM";
+  };
+
+} // namespace margelo::nitro::mlxreactnative

package/nitrogen/generated/shared/c++/HybridModelManagerSpec.cpp

@@ -0,0 +1,27 @@
+///
+/// HybridModelManagerSpec.cpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+#include "HybridModelManagerSpec.hpp"
+
+namespace margelo::nitro::mlxreactnative {
+
+  void HybridModelManagerSpec::loadHybridMethods() {
+    // load base methods/properties
+    HybridObject::loadHybridMethods();
+    // load custom methods/properties
+    registerHybrids(this, [](Prototype& prototype) {
+      prototype.registerHybridGetter("debug", &HybridModelManagerSpec::getDebug);
+      prototype.registerHybridSetter("debug", &HybridModelManagerSpec::setDebug);
+      prototype.registerHybridMethod("download", &HybridModelManagerSpec::download);
+      prototype.registerHybridMethod("isDownloaded", &HybridModelManagerSpec::isDownloaded);
+      prototype.registerHybridMethod("getDownloadedModels", &HybridModelManagerSpec::getDownloadedModels);
+      prototype.registerHybridMethod("deleteModel", &HybridModelManagerSpec::deleteModel);
+      prototype.registerHybridMethod("getModelPath", &HybridModelManagerSpec::getModelPath);
+    });
+  }
+
+} // namespace margelo::nitro::mlxreactnative

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

@@ -0,0 +1,70 @@
+///
+/// HybridModelManagerSpec.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2025 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/HybridObject.hpp>)
+#include <NitroModules/HybridObject.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+#include <NitroModules/Promise.hpp>
+#include <functional>
+#include <vector>
+
+namespace margelo::nitro::mlxreactnative {
+
+  using namespace margelo::nitro;
+
+  /**
+   * An abstract base class for `ModelManager`
+   * Inherit this class to create instances of `HybridModelManagerSpec` in C++.
+   * You must explicitly call `HybridObject`'s constructor yourself, because it is virtual.
+   * @example
+   * ```cpp
+   * class HybridModelManager: public HybridModelManagerSpec {
+   * public:
+   *   HybridModelManager(...): HybridObject(TAG) { ... }
+   *   // ...
+   * };
+   * ```
+   */
+  class HybridModelManagerSpec: public virtual HybridObject {
+    public:
+      // Constructor
+      explicit HybridModelManagerSpec(): HybridObject(TAG) { }
+
+      // Destructor
+      ~HybridModelManagerSpec() override = default;
+
+    public:
+      // Properties
+      virtual bool getDebug() = 0;
+      virtual void setDebug(bool debug) = 0;
+
+    public:
+      // Methods
+      virtual std::shared_ptr<Promise<std::string>> download(const std::string& modelId, const std::function<void(double /* progress */)>& progressCallback) = 0;
+      virtual std::shared_ptr<Promise<bool>> isDownloaded(const std::string& modelId) = 0;
+      virtual std::shared_ptr<Promise<std::vector<std::string>>> getDownloadedModels() = 0;
+      virtual std::shared_ptr<Promise<void>> deleteModel(const std::string& modelId) = 0;
+      virtual std::shared_ptr<Promise<std::string>> getModelPath(const std::string& modelId) = 0;
+
+    protected:
+      // Hybrid Setup
+      void loadHybridMethods() override;
+
+    protected:
+      // Tag for logging
+      static constexpr auto TAG = "ModelManager";
+  };
+
+} // namespace margelo::nitro::mlxreactnative

package/package.json

@@ -0,0 +1,96 @@
+{
+  "name": "react-native-nitro-mlx",
+  "version": "0.1.0",
+  "description": "Nitro module package",
+  "main": "./lib/module/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "react-native": "src/index",
+  "source": "src/index",
+  "scripts": {
+    "build": "rm -rf lib && bun typecheck && bob build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf android/build node_modules/**/android/build lib android/.cxx node_modules/**/android/.cxx",
+    "release": "release-it",
+    "specs": "bun typecheck && nitrogen --logLevel=\\\"debug\\\" && bun run build",
+    "specs:pod": "bun specs && bun --cwd ../example pod"
+  },
+  "keywords": [
+    "react-native",
+    "nitro",
+    "nitro-modile",
+    "expo",
+    "llm",
+    "mlx",
+    "mlx-swift",
+    "apple",
+    "react-native-nitro-mlx",
+    "ai"
+  ],
+  "files": [
+    "src",
+    "react-native.config.js",
+    "lib",
+    "nitrogen",
+    "cpp",
+    "android/build.gradle",
+    "android/gradle.properties",
+    "android/CMakeLists.txt",
+    "android/src",
+    "ios/**/*.h",
+    "ios/**/*.m",
+    "ios/**/*.mm",
+    "ios/**/*.cpp",
+    "ios/specs/**/*.swift",
+    "app.plugin.js",
+    "*.podspec",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/henrypaulino/react-native-nitro-mlx.git"
+  },
+  "author": "Henry Paulino",
+  "license": "MIT",
+  "bugs": "https://github.com/henrypaulino/react-native-nitro-mlx/issues",
+  "homepage": "https://github.com/henrypaulino/react-native-nitro-mlx#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "^9.0.10",
+    "nitrogen": "^0.31.10",
+    "react-native-builder-bob": "^0.40.13"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "*"
+  },
+  "release-it": {
+    "npm": {
+      "publish": true
+    },
+    "git": false,
+    "github": {
+      "release": false
+    },
+    "hooks": {
+      "before:init": "bun typecheck",
+      "after:bump": "bun build"
+    }
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      "typescript"
+    ]
+  }
+}

package/src/index.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'

package/src/llm.ts

@@ -0,0 +1,116 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { GenerationStats, LLM as LLMSpec } from './specs/LLM.nitro'
+
+let instance: LLMSpec | null = null
+
+function getInstance(): LLMSpec {
+  if (!instance) {
+    instance = NitroModules.createHybridObject<LLMSpec>('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: string, onProgress: (progress: number) => void): Promise<void> {
+    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: string): Promise<string> {
+    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: string, onToken: (token: string) => void): Promise<string> {
+    return getInstance().stream(prompt, onToken)
+  },
+
+  /**
+   * Stop the current generation. Safe to call even if not generating.
+   */
+  stop(): void {
+    getInstance().stop()
+  },
+
+  /**
+   * Get statistics from the last generation.
+   * @returns Statistics including token count, tokens/sec, TTFT, and total time
+   */
+  getLastGenerationStats(): GenerationStats {
+    return getInstance().getLastGenerationStats()
+  },
+
+  /** Whether a model is currently loaded and ready for generation */
+  get isLoaded(): boolean {
+    return getInstance().isLoaded
+  },
+
+  /** Whether text is currently being generated */
+  get isGenerating(): boolean {
+    return getInstance().isGenerating
+  },
+
+  /** The ID of the currently loaded model, or empty string if none */
+  get modelId(): string {
+    return getInstance().modelId
+  },
+
+  /** Enable debug logging to console */
+  get debug(): boolean {
+    return getInstance().debug
+  },
+
+  set debug(value: boolean) {
+    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(): string {
+    return getInstance().systemPrompt
+  },
+
+  set systemPrompt(value: string) {
+    getInstance().systemPrompt = value
+  },
+}

package/src/modelManager.ts

@@ -0,0 +1,88 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { ModelManager as ModelManagerSpec } from './specs/ModelManager.nitro'
+
+let instance: ModelManagerSpec | null = null
+
+function getInstance(): ModelManagerSpec {
+  if (!instance) {
+    instance = NitroModules.createHybridObject<ModelManagerSpec>('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: string,
+    progressCallback: (progress: number) => void,
+  ): Promise<string> {
+    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: string): Promise<boolean> {
+    return getInstance().isDownloaded(modelId)
+  },
+
+  /**
+   * Get a list of all downloaded model IDs.
+   * @returns Array of model IDs that are available locally
+   */
+  getDownloadedModels(): Promise<string[]> {
+    return getInstance().getDownloadedModels()
+  },
+
+  /**
+   * Delete a downloaded model to free up disk space.
+   * @param modelId - HuggingFace model ID
+   */
+  deleteModel(modelId: string): Promise<void> {
+    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: string): Promise<string> {
+    return getInstance().getModelPath(modelId)
+  },
+
+  /** Enable debug logging to console */
+  get debug(): boolean {
+    return getInstance().debug
+  },
+
+  set debug(value: boolean) {
+    getInstance().debug = value
+  },
+}

package/src/models.ts

@@ -0,0 +1,45 @@
+export enum MLXModel {
+  // Llama 3.2 (Meta) - 1B and 3B variants
+  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',
+
+  // Qwen 2.5 (Alibaba) - 0.5B, 1.5B, 3B variants
+  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',
+
+  // Qwen 3 - 1.7B variant
+  Qwen3_1_7B_4bit = 'mlx-community/Qwen3-1.7B-4bit',
+  Qwen3_1_7B_8bit = 'mlx-community/Qwen3-1.7B-8bit',
+
+  // Gemma 3 (Google) - 1B variant
+  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 (Microsoft) - ~3.8B but runs well on mobile
+  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 (Microsoft)
+  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 (HuggingFace) - 1.7B
+  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 (HuggingFace) - 1.7B
+  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 (Apple) - 1.1B and 3B
+  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',
+}

package/src/specs/LLM.nitro.ts

@@ -0,0 +1,66 @@
+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
+}

package/src/specs/ModelManager.nitro.ts

@@ -0,0 +1,44 @@
+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
+}