Models

Use OS-managed models, download open models at runtime, or register your own — all behind one API.

Overview

expo-ai-kit runs two kinds of model. Built-in models are provided and maintained by the OS — Apple Foundation Models on iOS and ML Kit on Android. Android may prepare its model on first use, but it is not bundled into your app. Downloadable models (Gemma, Qwen, Phi) are fetched at runtime via LiteRT-LM and run on both platforms. You switch between any of them with setModel().

Built-in vs Downloadable

The Catalog

The built-in registry ships a size ladder across three families. Each entry carries a license — check it before shipping a model to your users.

Download & Switch

Download a model (with progress), then activate it with setModel(). After that, every inference call — sendMessage, streamMessage, generateObject, generateText — uses it. unloadModel() reverts to the OS built-in.

import { downloadModel, setModel, unloadModel } from 'expo-ai-kit';

await downloadModel('qwen3-1.7b', {
  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
});

await setModel('qwen3-1.7b', { generation: { temperature: 0.7 } });
// ...all inference now runs on Qwen3 1.7B

await unloadModel(); // back to the OS model

Pick the Right Model

getDownloadableModels() returns the full catalog enriched with per-device status, size, license, and whether the device meets the model's RAM requirement. getRecommendedModel() returns the most capable model the current device can actually run, or null.

import { getDownloadableModels, getRecommendedModel } from 'expo-ai-kit';

const all = await getDownloadableModels();
all.forEach((m) => console.log(m.id, m.meetsRequirements, m.status, m.license));

const best = await getRecommendedModel();
if (best) await downloadModel(best.id);

Status & Lifecycle

Each downloadable model reports a status:

• not-downloaded — no file on disk
• downloading — fetch in progress
• downloaded — on disk but not loaded; survives app restarts
• loading — being loaded into memory
• ready — loaded and ready for inference

Downloads are integrity-checked with SHA-256. UsecancelDownload(id) to stop an active download anddeleteModel(id) to remove a downloaded model. Interrupted downloads restart from the beginning.

Bring Your Own Model

Not limited to the built-in list — register any LiteRT-LM model at runtime with registerModel(). Once registered, the id works with downloadModel / setModel / getDownloadableModels exactly like a built-in, and the download is still integrity-checked against the sha256 you provide.

import { registerModel, downloadModel, setModel } from 'expo-ai-kit';

registerModel({
  id: 'qwen3-4b-custom',
  name: 'Qwen3 4B',
  parameterCount: '4B',
  quantization: 'int4',
  downloadUrl:
    'https://huggingface.co/litert-community/Qwen3-4B/resolve/main/qwen3_4b_mixed_int4.litertlm',
  sha256: 'f0794bc77efeaaf4f7af815f04c483b19b8f2ae4a102cef1b7b760a25848a18e',
  sizeBytes: 2_659_057_664,
  contextWindow: 4096,
  minRamBytes: 3_000_000_000,
  supportedPlatforms: ['ios', 'android'],
  license: 'Apache-2.0',
});

await downloadModel('qwen3-4b-custom');
await setModel('qwen3-4b-custom');

fetchModelMetadata()

Rather than computing the sha256 and sizeBytes by hand, fetchModelMetadata() looks them up from a HuggingFace resolve URL.

import { fetchModelMetadata } from 'expo-ai-kit';

const { sha256, sizeBytes } = await fetchModelMetadata(
  'https://huggingface.co/litert-community/Qwen3-4B/resolve/main/qwen3_4b_mixed_int4.litertlm',
);