@automatalabs/react-native-transformers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Automata Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,346 @@
+# @automatalabs/react-native-transformers
+
+Use [`@huggingface/transformers`](https://www.npmjs.com/package/@huggingface/transformers) in Expo / React Native apps through [`onnxruntime-react-native`](https://www.npmjs.com/package/onnxruntime-react-native), without forking Transformers.js.
+
+## What this package does
+
+- adds an Expo config plugin that composes `onnxruntime-react-native`
+- adds a Metro helper that aliases Transformers.js onto a React Native wrapper
+- routes `onnxruntime-node` and `onnxruntime-web` imports to a React Native adapter
+- normalizes React Native-friendly device options like `coreml`, `xnnpack`, `nnapi`, and `qnn`
+- prefers `expo/fetch` automatically when available for streamed model downloads
+- caches downloaded model files with `expo-file-system` so they survive app restarts
+- supports ONNX models that use external data files (for example `*.onnx_data`)
+
+The package keeps the public app-facing API centered on:
+
+```js
+import { pipeline, AutoTokenizer, AutoModelForSequenceClassification } from '@huggingface/transformers';
+```
+
+## Requirements
+
+- Node `>= 18`
+- `@huggingface/transformers` `^4`
+- `onnxruntime-react-native` `>= 1.24.3 < 2`
+- `react`
+- `react-native`
+- `expo` is optional, but this package is primarily aimed at Expo / Expo dev-client workflows
+- `expo-file-system` is optional, but recommended if you want persistent model caching across app restarts
+
+## Install
+
+In an Expo app, install your native/runtime dependencies with Expo and then install this package plus Transformers.js. Include `expo-file-system` if you want automatic persistent model caching:
+
+```sh
+npx expo install expo react react-native onnxruntime-react-native expo-file-system
+npm install @huggingface/transformers @automatalabs/react-native-transformers
+```
+
+If your app already has Expo / React Native set up, you only need to add the missing packages.
+
+## Expo config plugin
+
+Add the plugin in your app config:
+
+```js
+// app.config.js
+module.exports = {
+  expo: {
+    plugins: ['@automatalabs/react-native-transformers'],
+  },
+};
+```
+
+For local development against this repository's bundled `example/` app, a relative plugin path is more reliable:
+
+```json
+{
+  "expo": {
+    "plugins": ["../app.plugin.js"]
+  }
+}
+```
+
+### ONNX Runtime Extensions
+
+You **do not** need ONNX Runtime Extensions just to use the `coreml`, `xnnpack`, `cpu`, `nnapi`, or `qnn` execution providers.
+
+Only enable extensions if the model itself requires ONNX Runtime Extensions custom ops. When needed, add this top-level field to your app's root `package.json`:
+
+```json
+{
+  "onnxruntimeExtensionsEnabled": "true"
+}
+```
+
+Then rebuild native code.
+
+## Metro
+
+Install the Metro helper so React Native resolves Transformers.js through the wrapper and adds `onnx` / `ort` asset extensions:
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config');
+const { withTransformersReactNativeMetro } = require('@automatalabs/react-native-transformers/metro');
+
+module.exports = withTransformersReactNativeMetro(getDefaultConfig(__dirname));
+```
+
+### Monorepos / local `file:..` development
+
+If you are developing the library and the app side by side, you may also want `watchFolders` and explicit singleton aliases for packages like `react-native` and `onnxruntime-react-native`.
+
+See [`example/metro.config.js`](./example/metro.config.js) for a working local-dev setup.
+
+## Babel
+
+The published `@huggingface/transformers` web bundle uses `import.meta`, so Expo apps need Babel's import-meta transform enabled:
+
+```js
+// babel.config.js
+module.exports = function babelConfig(api) {
+  api.cache(true);
+
+  return {
+    presets: [['babel-preset-expo', { unstable_transformImportMeta: true }]],
+  };
+};
+```
+
+## Basic usage
+
+Once Metro is configured, import from `@huggingface/transformers` as usual.
+
+### Example: sentiment analysis pipeline
+
+```js
+import { pipeline } from '@huggingface/transformers';
+
+const classifier = await pipeline(
+  'sentiment-analysis',
+  'Xenova/distilbert-base-uncased-finetuned-sst-2-english',
+  {
+    device: 'coreml', // iOS: coreml -> cpu, Android users would typically use nnapi/qnn/xnnpack/cpu
+    dtype: 'q8',
+  },
+);
+
+const result = await classifier('Running Transformers.js in Expo feels great.');
+console.log(result);
+```
+
+### Example: direct model helpers
+
+```js
+import {
+  AutoModelForSequenceClassification,
+  AutoTokenizer,
+} from '@huggingface/transformers';
+
+const MODEL_ID = 'Xenova/distilbert-base-uncased-finetuned-sst-2-english';
+
+const tokenizer = await AutoTokenizer.from_pretrained(MODEL_ID, {
+  device: 'coreml',
+});
+
+const model = await AutoModelForSequenceClassification.from_pretrained(MODEL_ID, {
+  device: 'coreml',
+  dtype: 'q8',
+});
+
+const inputs = await tokenizer('React Native inference on device is useful.');
+const output = await model(inputs);
+console.log(output.logits.dims);
+```
+
+### Example: chat generation with `onnx-community/LFM2.5-350M-ONNX`
+
+This model card explicitly documents chat-style usage with Transformers.js, and this package supports its ONNX external-data layout on React Native.
+
+```js
+import { pipeline } from '@huggingface/transformers';
+
+const generator = await pipeline(
+  'text-generation',
+  'onnx-community/LFM2.5-350M-ONNX',
+  {
+    device: 'coreml',
+    dtype: 'q4',
+  },
+);
+
+const messages = [
+  {
+    role: 'system',
+    content: 'You are a helpful assistant. Reply with one short sentence.',
+  },
+  {
+    role: 'user',
+    content: 'Explain one benefit of running AI directly on a phone.',
+  },
+];
+
+const output = await generator(messages, {
+  max_new_tokens: 64,
+  do_sample: false,
+  repetition_penalty: 1.05,
+});
+
+const assistantMessage = output[0].generated_text.at(-1)?.content;
+console.log(assistantMessage);
+```
+
+## React Native-specific device options
+
+This package accepts React Native-oriented device shorthands and translates them into ONNX Runtime execution providers.
+
+Common values:
+
+- `auto`
+- `coreml` (iOS)
+- `xnnpack`
+- `cpu`
+- `nnapi` (Android)
+- `qnn` (Android)
+
+Example:
+
+```js
+const generator = await pipeline('text-generation', MODEL_ID, {
+  device: 'xnnpack',
+});
+```
+
+Under the hood these are normalized into `session_options.executionProviders` so they work with current Transformers.js expectations.
+
+## Runtime helpers
+
+The package also exports a few helpers from the root entrypoint.
+
+### List supported execution providers
+
+```js
+import { getSupportedExecutionProviderNames } from '@automatalabs/react-native-transformers';
+
+console.log(getSupportedExecutionProviderNames());
+// e.g. ['cpu', 'xnnpack', 'coreml']
+```
+
+### Normalize options explicitly
+
+```js
+import { normalizeTransformersOptions } from '@automatalabs/react-native-transformers';
+
+const options = normalizeTransformersOptions({
+  device: 'coreml',
+});
+
+console.log(options.session_options.executionProviders);
+```
+
+## Notes
+
+### `coreml` means CoreML execution provider, not native `.mlmodel` loading
+
+Inference still goes through ONNX Runtime. Using:
+
+```js
+{ device: 'coreml' }
+```
+
+means “prefer ONNX Runtime's CoreML execution provider on iOS”, not “load a native CoreML model artifact directly”.
+
+### `expo/fetch`
+
+The wrapper automatically prefers `expo/fetch` when available, because the default React Native fetch implementation does not expose the response stream reader that Transformers.js expects for efficient downloads.
+
+You can still override `env.fetch` manually if you want to.
+
+### Model file caching
+
+When `expo-file-system` is installed, downloaded model files are cached automatically under Expo's cache directory at:
+
+- `Paths.cache/automatalabs-react-native-transformers/models`
+
+That cache survives normal app restarts, but because it lives in the cache directory the OS may still evict it under storage pressure.
+
+If you want a different location, you can provide your own cache implementation:
+
+```js
+import { env } from '@huggingface/transformers';
+import { Paths } from 'expo-file-system';
+import { createExpoFileSystemCache } from '@automatalabs/react-native-transformers';
+
+env.customCache = createExpoFileSystemCache({
+  directory: Paths.document,
+});
+env.useCustomCache = true;
+```
+
+If `expo-file-system` is not installed, the package still works — it simply skips persistent model caching.
+
+To disable persistent model caching entirely:
+
+```js
+env.customCache = null;
+env.useCustomCache = false;
+```
+
+### Fallback visibility
+
+ONNX Runtime's JavaScript API does not expose exact per-node execution-provider usage for a successful session. You can know:
+
+- what execution-provider order was requested
+- whether your app retried on a different device / execution-provider chain
+
+But you generally cannot prove exact per-op fallback from JavaScript alone.
+
+## How it works
+
+This package takes a no-fork approach:
+
+- aliases `@huggingface/transformers` to `src/transformers.js`
+- aliases `onnxruntime-node`, `onnxruntime-web`, and `onnxruntime-web/webgpu` to a React Native adapter
+- reuses the unified ONNX Runtime JavaScript API shape exposed by `onnxruntime-react-native`
+- patches the create-session path for React Native buffer / external-data model loading
+- normalizes public `from_pretrained()` and `pipeline()` options for React Native execution providers
+
+## Example app
+
+The repository includes an Expo example in [`example/`](./example).
+
+Run it with:
+
+```sh
+npm install
+npm run example:ios
+```
+
+If you need a clean Metro session:
+
+```sh
+cd example
+npx expo start --dev-client --clear
+```
+
+The current example app validates:
+
+- speech text generation with `onnx-community/granite-4.0-1b-speech-ONNX`
+- chat generation with `onnx-community/LFM2.5-350M-ONNX`
+- requested execution-provider order and app-level retry / fallback reporting
+
+## Package exports
+
+- `@automatalabs/react-native-transformers`
+  - runtime helpers like `getSupportedExecutionProviderNames()`
+  - cache helpers like `createExpoFileSystemCache()`
+- `@automatalabs/react-native-transformers/metro`
+  - Metro helper
+- `@automatalabs/react-native-transformers/plugin`
+  - Expo config plugin entrypoint
+- `@automatalabs/react-native-transformers/transformers`
+  - explicit wrapper entrypoint
+- `@automatalabs/react-native-transformers/app.plugin`
+  - root plugin file

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./plugin/src');

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@automatalabs/react-native-transformers",
+  "version": "0.1.0",
+  "description": "Use @huggingface/transformers in Expo and React Native apps through onnxruntime-react-native.",
+  "license": "MIT",
+  "author": "Automata Labs",
+  "homepage": "https://github.com/VikashLoomba/react-native-transformers#readme",
+  "bugs": {
+    "url": "https://github.com/VikashLoomba/react-native-transformers/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VikashLoomba/react-native-transformers.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "expo",
+    "react-native",
+    "huggingface",
+    "transformers",
+    "onnxruntime",
+    "onnxruntime-react-native",
+    "mobile-ai",
+    "on-device-ai"
+  ],
+  "scripts": {
+    "check": "node --check app.plugin.js plugin/src/index.js src/index.js src/runtime.js src/expoFileSystemCache.js src/metro.js src/transformers.js src/adapter/onnxruntime-web-webgpu.js",
+    "prepublishOnly": "npm run check",
+    "example": "npm --prefix example run start",
+    "example:ios": "npm --prefix example run ios"
+  },
+  "main": "./src/index.js",
+  "react-native": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./metro": "./src/metro.js",
+    "./plugin": "./plugin/src/index.js",
+    "./transformers": "./src/transformers.js",
+    "./adapter/onnxruntime-web-webgpu": "./src/adapter/onnxruntime-web-webgpu.js",
+    "./app.plugin": "./app.plugin.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "plugin",
+    "src",
+    "app.plugin.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.0.0",
+    "expo": "*",
+    "expo-file-system": "*",
+    "onnxruntime-react-native": ">=1.24.3 <2",
+    "react": "*",
+    "react-native": "*"
+  },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    },
+    "expo-file-system": {
+      "optional": true
+    }
+  },
+  "dependencies": {}
+}

package/plugin/src/index.js

@@ -0,0 +1,13 @@
+function requireFromProject(moduleId) {
+  return require(require.resolve(moduleId, { paths: [process.cwd(), __dirname] }));
+}
+
+function withReactNativeTransformers(config) {
+  const onnxruntimeReactNativePlugin = requireFromProject('onnxruntime-react-native/app.plugin');
+  const withOnnxruntimeReactNative =
+    onnxruntimeReactNativePlugin.default ?? onnxruntimeReactNativePlugin;
+
+  return withOnnxruntimeReactNative(config);
+}
+
+module.exports = withReactNativeTransformers;

package/src/adapter/onnxruntime-web-webgpu.js

@@ -0,0 +1,246 @@
+const { NativeModules } = require('react-native');
+const ortReactNative = require('onnxruntime-react-native');
+const { sanitizeSessionOptions } = require('../runtime');
+
+const Module = NativeModules?.Onnxruntime;
+
+if (typeof globalThis.OrtApi === 'undefined' && typeof Module?.install === 'function') {
+  Module.install();
+}
+
+const OrtApi =
+  globalThis.OrtApi ??
+  new Proxy(
+    {},
+    {
+      get() {
+        throw new Error(
+          'OrtApi is not initialized. Please make sure Onnxruntime installation is successful.',
+        );
+      },
+    },
+  );
+
+const dataTypeStrings = [
+  undefined,
+  'float32',
+  'uint8',
+  'int8',
+  'uint16',
+  'int16',
+  'int32',
+  'int64',
+  'string',
+  'bool',
+  'float16',
+  'float64',
+  'uint32',
+  'uint64',
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  undefined,
+  'uint4',
+  'int4',
+];
+
+function fillNamesAndMetadata(rawMetadata = []) {
+  const names = [];
+  const metadata = [];
+
+  for (const item of rawMetadata) {
+    names.push(item.name);
+
+    if (!item.isTensor) {
+      metadata.push({
+        name: item.name,
+        isTensor: false,
+      });
+      continue;
+    }
+
+    const type = dataTypeStrings[item.type];
+    if (type === undefined) {
+      throw new Error(`Unsupported data type: ${item.type}`);
+    }
+
+    const shape = [];
+    for (let index = 0; index < item.shape.length; index += 1) {
+      const dim = item.shape[index];
+      if (dim === -1) {
+        shape.push(item.symbolicDimensions[index]);
+      } else if (dim >= 0) {
+        shape.push(dim);
+      } else {
+        throw new Error(`Invalid dimension: ${dim}`);
+      }
+    }
+
+    metadata.push({
+      name: item.name,
+      isTensor: true,
+      type,
+      shape,
+    });
+  }
+
+  return [names, metadata];
+}
+
+function getLogLevelValue(logLevel) {
+  switch (logLevel) {
+    case 'verbose':
+      return 0;
+    case 'info':
+      return 1;
+    case 'warning':
+    case undefined:
+      return 2;
+    case 'error':
+      return 3;
+    case 'fatal':
+      return 4;
+    default:
+      throw new Error(`Unsupported log level: ${logLevel}`);
+  }
+}
+
+function normalizeCreateArguments(args) {
+  const [arg0, arg1, arg2, arg3] = args;
+
+  if (typeof arg0 === 'string') {
+    if (arg1 !== undefined && (typeof arg1 !== 'object' || arg1 === null || Array.isArray(arg1))) {
+      throw new TypeError("'options' must be an object.");
+    }
+
+    return {
+      modelPath: arg0,
+      modelBytes: null,
+      options: arg1 ?? {},
+    };
+  }
+
+  if (arg0 instanceof Uint8Array) {
+    if (arg1 !== undefined && (typeof arg1 !== 'object' || arg1 === null || Array.isArray(arg1))) {
+      throw new TypeError("'options' must be an object.");
+    }
+
+    return {
+      modelPath: null,
+      modelBytes: arg0,
+      options: arg1 ?? {},
+    };
+  }
+
+  if (
+    arg0 instanceof ArrayBuffer ||
+    (typeof SharedArrayBuffer !== 'undefined' && arg0 instanceof SharedArrayBuffer)
+  ) {
+    let byteOffset = 0;
+    let byteLength = arg0.byteLength;
+    let options = {};
+
+    if (typeof arg1 === 'object' && arg1 !== null) {
+      options = arg1;
+    } else if (typeof arg1 === 'number') {
+      byteOffset = arg1;
+      byteLength = typeof arg2 === 'number' ? arg2 : arg0.byteLength - byteOffset;
+      options = typeof arg3 === 'object' && arg3 !== null ? arg3 : {};
+    } else if (arg1 !== undefined) {
+      throw new TypeError("'options' must be an object.");
+    }
+
+    return {
+      modelPath: null,
+      modelBytes: new Uint8Array(arg0, byteOffset, byteLength),
+      options,
+    };
+  }
+
+  throw new TypeError("Unexpected argument[0]: must be 'path' or 'buffer'.");
+}
+
+function toExactArrayBuffer(uint8Array) {
+  if (uint8Array.byteOffset === 0 && uint8Array.byteLength === uint8Array.buffer.byteLength) {
+    return uint8Array.buffer;
+  }
+
+  return uint8Array.buffer.slice(
+    uint8Array.byteOffset,
+    uint8Array.byteOffset + uint8Array.byteLength,
+  );
+}
+
+class ReactNativeSessionHandler {
+  #inferenceSession;
+
+  constructor(session) {
+    this.#inferenceSession = session;
+
+    const [inputNames, inputMetadata] = fillNamesAndMetadata(session.inputMetadata);
+    const [outputNames, outputMetadata] = fillNamesAndMetadata(session.outputMetadata);
+
+    this.inputNames = inputNames;
+    this.outputNames = outputNames;
+    this.inputMetadata = inputMetadata;
+    this.outputMetadata = outputMetadata;
+  }
+
+  async run(feeds, fetches, options) {
+    return this.#inferenceSession.run(feeds, fetches, options);
+  }
+
+  async dispose() {
+    this.#inferenceSession.dispose();
+  }
+
+  async release() {
+    this.#inferenceSession.dispose();
+  }
+
+  startProfiling() {
+    // no-op; profiling is enabled at load time by session options if requested
+  }
+
+  endProfiling() {
+    return this.#inferenceSession.endProfiling();
+  }
+}
+
+class PatchedInferenceSession extends ortReactNative.InferenceSession {
+  static #initialized = false;
+
+  static async create(...args) {
+    const { modelPath, modelBytes, options } = normalizeCreateArguments(args);
+    const sessionOptions = sanitizeSessionOptions({
+      ...options,
+      ortExtLibPath: options?.ortExtLibPath ?? Module?.ORT_EXTENSIONS_PATH,
+    });
+
+    if (!PatchedInferenceSession.#initialized) {
+      PatchedInferenceSession.#initialized = true;
+      OrtApi.initOrtOnce(getLogLevelValue(ortReactNative.env.logLevel), ortReactNative.Tensor);
+    }
+
+    const session = OrtApi.createInferenceSession();
+
+    if (typeof modelPath === 'string') {
+      await session.loadModel(modelPath, sessionOptions);
+    } else {
+      await session.loadModel(toExactArrayBuffer(modelBytes), sessionOptions);
+    }
+
+    return new PatchedInferenceSession(new ReactNativeSessionHandler(session));
+  }
+}
+
+module.exports = {
+  ...ortReactNative,
+  InferenceSession: PatchedInferenceSession,
+  Tensor: ortReactNative.Tensor,
+  env: ortReactNative.env,
+  listSupportedBackends: OrtApi.listSupportedBackends ?? ortReactNative.listSupportedBackends,
+};