Expo AI Runtime

A mobile-native AI runtime for Expo and React Native. One TypeScript API over:

• Apple Foundation Models (on-device, iOS 26+), plus opt-in Apple Private Cloud Compute (iOS 27+)
• Android Gemini Nano via ML Kit GenAI / AICore (on-device)
• An explicit, app-controlled cloud fallback

…with runtime capability detection, normalized errors, privacy metadata and token usage on every result, an app-wide privacy policy, sessions, streaming, and structured output (natively guided on Apple).

Requests stay on-device by default. Off-device providers (Private Cloud Compute, cloud) are used only when you name them or set fallback: 'cloud' | 'any', and a sensitive prompt reaches a third-party cloud only with fallback: 'cloud'.

This is the v1 provider layer described in docs/prd.md — a reliable way to call the best available native or local model from a React Native app. It is intentionally not an agent framework yet.

Packages

Package	What it is	Version
@stewmore/expo-ai-core	Pure-TS heart: public ExpoAI API, adapter contract, provider router, capability registry, sessions, structured-output validation/repair, privacy, normalized errors. No native code.
@stewmore/expo-ai-react	React hooks for the ExpoAI API.
@stewmore/expo-ai-apple-foundation-models	iOS adapter wrapping Apple's FoundationModels framework (Swift).
@stewmore/expo-ai-android-aicore	Android adapter wrapping ML Kit GenAI / Gemini Nano via AICore (Kotlin).
@stewmore/expo-ai-cloud	Cloud fallback client adapter (configurable endpoint, streaming via expo/fetch).
@stewmore/expo-ai-evals	Node-first evaluation harness (quality, schema validity, latency, fallback frequency).

Examples

App	Demonstrates
examples/basic-generate	Capability card + prompt → ExpoAI.generate, provider + privacy badge, errors.
examples/structured-output	ExpoAI.generateObject with a JSON schema.
examples/streaming-chat	ExpoAI.stream with live tokens + cancel.
examples/cloud-fallback	Explicit cloud routing, sensitivity gating, privacy disclosure.
examples/server	Reference cloud backend (mock-by-default).

Quick start

import { ExpoAI } from '@stewmore/expo-ai-core';
import '@stewmore/expo-ai-apple-foundation-models'; // registers the iOS adapter
import '@stewmore/expo-ai-android-aicore'; // registers the Android adapter

const caps = await ExpoAI.getCapabilities();
if (caps.available) {
  const result = await ExpoAI.generate({
    prompt: 'Summarize this note in five bullets.',
    fallback: 'cloud',
  });
  console.log(result.text, result.provider, result.privacy.privacyMode);
}

Development

npm install                 # install the whole workspace
npm test                    # run unit tests (core, cloud, evals)
npm run typecheck           # type-check all packages
npm run build               # build all packages
npm run eval                # run the eval harness against a mock on-device adapter (no cloud)
npm run eval -- --providers apple-foundation-models,cloud --fallback cloud
                            # add cloud: a cloud mock, or the reference server if ENDPOINT is set
npm run server              # start the reference cloud backend (mock mode)

Example apps use custom native code, so they require a development build (not Expo Go):

cd examples/basic-generate
npx expo prebuild
npx expo run:ios       # iOS 26 simulator (Apple Silicon) with Apple Intelligence enabled
npx expo run:android   # supported device for on-device; otherwise cloud fallback

See docs/prd.md for the full product definition and roadmap.

Use as an agent skill

This repo ships an agent skill that teaches AI coding agents how to build with this runtime — wiring providers, capability detection, structured output, sessions, and the privacy-aware routing rules. Add it to your agent with the skills CLI:

npx skills add stewartmoreland/expo-ai-runtime

License

MIT