# expo-ai-kit

> On-device AI for React Native and Expo: LLMs, speech-to-text, vision, and embeddings.
> Native module, no API key, zero runtime JavaScript dependencies.

Install: `npx expo install expo-ai-kit`. Requires Expo SDK 54+ or compatible Expo modules
in a React Native app. Use a native development/production build, not Expo Go.
All features are off by default. Turn them on with the config plugin options `llm`, `speech`,
`vision`, and `androidEmbeddings`; an app ships only the native code it enables, and the
other APIs throw a typed *_NOT_ENABLED error. Changing an option needs a new native build.
Bare React Native sets `expoAiKit.<option>=true` in android/gradle.properties and
`"expoAiKit.llm": "true"` in ios/Podfile.properties.json. Android minimum API 24; `llm` and
`speech` require 26. Device and OS support vary by feature.

## LLM

- [Generate text](https://expo-ai-kit.dev/guides/llm): sendMessage, streamMessage.
- [Structured output](https://expo-ai-kit.dev/guides/structured-output): generateObject(messages, jsonSchema).
- [Tool calling](https://expo-ai-kit.dev/guides/tool-calling): generateText(messages, { tools, maxSteps }).
- [Conversations](https://expo-ai-kit.dev/guides/multi-turn): pass the complete message history on each call.

Enable the llm option and rebuild; it links the LiteRT-LM runtime (about 30 MB iOS arm64,
21 MB Android). Without it isAvailable() is false and generation throws LLM_NOT_ENABLED.
Check isAvailable(), then await prepareBuiltInModel() before built-in generation.
Built-ins: Apple Foundation Models on Apple Intelligence devices with iOS 26+;
ML Kit Prompt API on supported Android devices. Downloadable models use LiteRT-LM.
All generation APIs share one guard and reject overlap with INFERENCE_BUSY.
setModel owns activation and generation settings. The message APIs are stateless.

## Speech

- [Speech-to-text](https://expo-ai-kit.dev/guides/speech): transcribe files, streamTranscription from the microphone.

Enable the speech plugin option and rebuild. Check getSpeechRecognitionAvailability;
prepareSpeechRecognition downloads when needed. Request microphone permission for live input
and Android file input. iOS 26+: timestamps and faster-than-real-time files. Android 12+:
text only, files ingested at real-time rate. Live updates contain the full transcript so far.
Speech has its own single-flight guard (SPEECH_BUSY).

## Vision

- [Images](https://expo-ai-kit.dev/guides/vision): removeBackground, labelImage, recognizeText.
- [Face detection](https://expo-ai-kit.dev/guides/face-detection): detectFaces({ uri }).

Enable vision on Android and rebuild: `"vision": true` for every feature, or an array of
background-removal, image-labeling, text-recognition, face-detection to compile only those (each
adds only its ML Kit client and bundled model). No new permissions. iOS needs no plugin option.
Vision does not need the llm option; a face-detection-only app ships only the face detector.
Features left out report { status: 'unavailable', reason: 'not-enabled' } and throw
VISION_NOT_ENABLED; prepareVision() with no features prepares only the compiled-in ones.
getVisionAvailability reports backgroundRemoval, imageLabeling, textRecognition, and faceDetection.
prepareVision is the only call that downloads: Android segmentation and OCR use Play services
models. Image labeling and face detection are bundled and work without preparation.
Every vision call accepts { uri } (local file:// or path; Android also content://).
detectFaces returns { width, height, faces }: upright image pixels and faces sorted largest first,
each with bounds (normalized 0–1, origin top-left, clamped) and pixelBounds (upright pixels), plus
confidence on iOS. It only detects; "one dominant face" or minimum-size rules belong to the app.
Face detection requires a physical iOS device. All vision bounds are normalized 0–1.
Vision is independent of generation and speech. Face detection may run concurrently.

## Embeddings

- [Embeddings](https://expo-ai-kit.dev/guides/embeddings): embed, chunkText, cosineSimilarity, createVectorStore.

iOS 17+: NLContextualEmbedding. Android: enable androidEmbeddings, rebuild, and call
prepareEmbeddingModel explicitly for the EmbeddingGemma download. embed never downloads
implicitly. Persist { id, revision } with vectors; compare only identical model identities.

## Reference

- [Installation](https://expo-ai-kit.dev/get-started)
- [Models](https://expo-ai-kit.dev/guides/models)
- [Platform support](https://expo-ai-kit.dev/guides/platform-support)
- [AI SDK provider](https://expo-ai-kit.dev/guides/vercel-ai-sdk): expo-ai-kit/ai, same core lifecycle and guards.
- [API reference](https://expo-ai-kit.dev/api): signatures, config plugin, types, typed ModelError codes.
- [Examples](https://expo-ai-kit.dev/examples)
- [Troubleshooting](https://expo-ai-kit.dev/troubleshooting)
- [GitHub](https://github.com/saidkaban/expo-ai-kit)