@inferrlm/react-native-mlx 0.2.0-inferrlm.1

package/package.json

@@ -0,0 +1,142 @@
+{
+  "name": "@inferrlm/react-native-mlx",
+  "version": "0.2.0-inferrlm.1",
+  "description": "MLX Swift integration for React Native - InferrLM fork with enhanced features",
+  "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-module",
+    "expo",
+    "llm",
+    "mlx",
+    "mlx-swift",
+    "apple",
+    "apple-silicon",
+    "react-native-mlx",
+    "ai",
+    "on-device-ai",
+    "inferrlm",
+    "ios"
+  ],
+  "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/**/*.swift",
+    "app.plugin.js",
+    "*.podspec",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sbhjt-gr/react-native-nitro-mlx.git"
+  },
+  "author": "Subhajit Ghosh <sbhjt.gr@gmail.com>",
+  "contributors": [
+    "Henry Paulino <me@henrypl.com> (original author)"
+  ],
+  "license": "MIT",
+  "bugs": "https://github.com/sbhjt-gr/react-native-nitro-mlx/issues",
+  "homepage": "https://github.com/sbhjt-gr/react-native-nitro-mlx#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "devDependencies": {
+    "@expo/config-plugins": "^9.0.10",
+    "@release-it/bumper": "^7.0.5",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "nitrogen": "^0.31.10",
+    "react-native-builder-bob": "^0.39.1",
+    "release-it": "^19.0.4"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "*"
+  },
+  "release-it": {
+    "npm": {
+      "publish": true,
+      "skipVersion": true
+    },
+    "github": {
+      "release": true,
+      "releaseName": "v${version}"
+    },
+    "hooks": {
+      "after:bump": "bun specs",
+      "before:release": "bun run build"
+    },
+    "git": {
+      "commitMessage": "chore: release ${version}",
+      "tagName": "v${version}",
+      "requireCleanWorkingDir": false
+    },
+    "plugins": {
+      "@release-it/conventional-changelog": {
+        "preset": {
+          "name": "conventionalcommits",
+          "types": [
+            {
+              "type": "feat",
+              "section": "✨ Features"
+            },
+            {
+              "type": "fix",
+              "section": "🐞 Fixes"
+            },
+            {
+              "type": "chore(deps)",
+              "section": "🛠️ Dependency Upgrades"
+            },
+            {
+              "type": "perf",
+              "section": "🏎️ Performance Improvements"
+            },
+            {
+              "type": "docs",
+              "section": "📚 Documentation"
+            }
+          ]
+        }
+      }
+    }
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      "typescript"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { LLM, type Message } from './llm'
+export { ModelManager } from './modelManager'
+export { MLXModel } from './models'
+
+export type { GenerationStats, LLM as LLMSpec, LLMLoadOptions } from './specs/LLM.nitro'
+export type { ModelManager as ModelManagerSpec } from './specs/ModelManager.nitro'

package/src/llm.ts

@@ -0,0 +1,144 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { GenerationStats, LLMLoadOptions, LLM as LLMSpec } from './specs/LLM.nitro'
+
+let instance: LLMSpec | null = null
+
+export type Message = {
+  role: 'user' | 'assistant' | 'system'
+  content: string
+}
+
+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 options - Callback invoked with loading progress (0-1)
+   */
+  load(modelId: string, options: LLMLoadOptions): Promise<void> {
+    return getInstance().load(modelId, options)
+  },
+
+  /**
+   * 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()
+  },
+
+  /**
+   * Unload the current model and release memory.
+   * Call this when you're done with the model to free up memory.
+   */
+  unload(): void {
+    getInstance().unload()
+  },
+
+  /**
+   * Get statistics from the last generation.
+   * @returns Statistics including token count, tokens/sec, TTFT, and total time
+   */
+  getLastGenerationStats(): GenerationStats {
+    return getInstance().getLastGenerationStats()
+  },
+
+  /**
+   * Get the message history if management is enabled.
+   * @returns Array of messages in the history
+   */
+  getHistory(): Message[] {
+    return getInstance().getHistory() as Message[]
+  },
+
+  /**
+   * Clear the message history.
+   */
+  clearHistory(): void {
+    getInstance().clearHistory()
+  },
+
+  /** 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,98 @@
+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
+}
+
+export interface LLMMessage {
+  role: string
+  content: string
+}
+
+/** Options for loading a model.
+ */
+export interface LLMLoadOptions {
+  /** Callback invoked with loading progress (0-1) */
+  onProgress?: (progress: number) => void
+  /** Additional context to provide to the model */
+  additionalContext?: LLMMessage[]
+  /** Whether to automatically manage message history */
+  manageHistory?: boolean
+}
+
+/**
+ * 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 options - Callback invoked with loading progress (0-1)
+   */
+  load(modelId: string, options?: LLMLoadOptions): 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
+
+  /**
+   * Unload the current model and release memory.
+   */
+  unload(): void
+
+  /**
+   * Get statistics from the last generation.
+   * @returns Statistics including token count, speed, and timing
+   */
+  getLastGenerationStats(): GenerationStats
+
+  /**
+   * Get the message history if management is enabled.
+   * @returns Array of messages in the history
+   */
+  getHistory(): LLMMessage[]
+
+  /**
+   * Clear the message history.
+   */
+  clearHistory(): void
+
+  /** 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
+}