import { PackageManagerTabs } from '@theme'

# Getting Started

The Core AI provider runs model bundles exported with Apple's [`coreai-models`](https://github.com/apple/coreai-models) on iOS 27, through Apple's Core AI runtime. Your app downloads or bundles the models it uses, and the provider runs them with the Vercel AI SDK, or through direct native calls for tasks the AI SDK has no API for.

| Task               | API                                                                            | Hosted model                                                    |
| ------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| Text generation    | `generateText`, `streamText` with `coreAI.languageModel`                       | [Qwen3 0.6B](./models#hosted-exports)                           |
| Image generation   | `generateImage` with `coreAI.imageModel`                                       | [FLUX.2 klein 4B](./models#hosted-exports)                      |
| Video generation   | `experimental_generateVideo` with `coreAI.videoModel`                          | [Wan 2.1 T2V 1.3B](./models#hosted-exports), macOS only for now |
| Transcription      | `transcribe`, `experimental_streamTranscribe` with `coreAI.transcriptionModel` | [Parakeet TDT 0.6B v3](./models#hosted-exports)                 |
| Embeddings         | `embed`, `embedMany` with `coreAI.embeddingModel`                              | [CLIP ViT-B/32](./models#hosted-exports)                        |
| Object detection   | `CoreAI.runTask('object-detection', ...)`                                      | [YOLOS-tiny](./models#hosted-exports)                           |
| Segmentation       | `CoreAI.runTask('segmentation', ...)`                                          | [EfficientSAM-Ti](./models#hosted-exports)                      |
| Video segmentation | `CoreAI.runTask('video-segmentation', ...)`                                    | [SAM 3 video](./models#hosted-exports)                          |
| Super-resolution   | `CoreAI.runTask('super-resolution', ...)`                                      | [EDSR x2](./models#hosted-exports)                              |
| Classification     | `CoreAI.runTask('classification', ...)`                                        | [PVT v2 b0](./models#hosted-exports)                            |
| Depth estimation   | `CoreAI.runTask('depth', ...)`                                                 | [Depth Anything 3 small](./models#hosted-exports)               |
| Any `.aimodel`     | `CoreAI.runRawFunction(...)`                                                   | Your own export                                                 |

For Apple's built-in system models (Foundation Models, SpeechAnalyzer and others), use the [Apple provider](../apple/getting-started) instead.

## Installation

<PackageManagerTabs command="install @react-native-ai/core-ai @react-native-ai/apple" />

`@react-native-ai/apple` is a peer dependency: Core AI language models run through the same Foundation Models session as Apple Intelligence. To use the AI SDK functions, you'll need v7+ and [required polyfills](../polyfills.md):

<PackageManagerTabs command="install ai" />

## Requirements

- **React Native New Architecture**
- **Xcode 27** or newer, and an **iOS 27** deployment target
- **A physical device**: the iOS Simulator SDK has no `CoreAI` framework, so apps with this package build for devices only

## Native Setup

The pod links Apple's `coreai-models` Swift Package (1.0.0 up to the next major version) during `pod install`, so there is no Xcode step.

### Expo

Add the config plugin to `app.json`, then run `npx expo prebuild`:

```json
{
  "expo": {
    "plugins": ["@react-native-ai/core-ai"]
  }
}
```

The plugin sets the iOS deployment target to 27.0 in the Podfile and the Xcode project. If you also set `ios.deploymentTarget` in `expo-build-properties`, make it `27.0` or higher.

### Bare React Native

Set `platform :ios, '27.0'` in `ios/Podfile` and the deployment target of the app target in Xcode to 27.0, then run `npx pod-install`.

### Choosing Tasks

The pod links one `coreai-models` product per task, and links all of them by default:

| Task                 | Used by                                     | Linked product            |
| -------------------- | ------------------------------------------- | ------------------------- |
| `language`           | `coreAI.languageModel(...)` and sessions    | `CoreAILM`                |
| `diffusion`          | `coreAI.imageModel(...)`                    | `CoreAIDiffusion`         |
| `video-diffusion`    | `coreAI.videoModel(...)`                    | `CoreAIVideoDiffusion`    |
| `asr`                | `coreAI.transcriptionModel(...)`            | `CoreAISpeech`            |
| `segmentation`       | `CoreAI.runTask('segmentation', ...)`       | `CoreAISegmentation`      |
| `video-segmentation` | `CoreAI.runTask('video-segmentation', ...)` | `CoreAIVideoSegmentation` |
| `object-detection`   | `CoreAI.runTask('object-detection', ...)`   | `CoreAIObjectDetection`   |

Embeddings, super-resolution, classification, depth estimation and raw function calls run on the Core AI runtime itself, and need no product of their own.

To link fewer, list the tasks you use. With Expo, pass them to the plugin:

```json
{
  "expo": {
    "plugins": [["@react-native-ai/core-ai", { "tasks": ["language"] }]]
  }
}
```

In a bare app, set `CORE_AI_TASKS` (comma-separated) on every `pod install`:

```bash
CORE_AI_TASKS=language npx pod-install
```

Calls for a task that isn't linked reject with `CORE_AI_MISSING_SPM_PRODUCT`, and `CoreAI.getCapabilities()` reports which products are linked.

## Loading Models

Core AI loads models from local files. Download a model folder into app storage, or bundle it with the app, and pass its path as `source`:

```typescript
import { coreAI } from '@react-native-ai/core-ai'

const model = coreAI.languageModel({
  id: 'qwen3-0.6b',
  source: {
    type: 'file',
    uri: `${documentDirectory}/coreai-models/qwen3-0.6b`,
  },
  variant: 'iOS',
})
```

Bundled models use `source: { type: 'bundle', name, extension, subdirectory }`. The [Models](./models) page lists exports hosted on Hugging Face for every task, and how to export your own.

## Basic Usage

```typescript
import { streamText } from 'ai'

const result = streamText({
  model,
  prompt: 'Explain Core AI in one sentence.',
})

for await (const delta of result.textStream) {
  console.log(delta)
}
```

## Next Steps

- [Generating](./generating): text, structured output, reasoning and native sessions
- [Images and Video](./images-and-video): image and video generation
- [Transcription](./transcription): files and live audio
- [Embeddings](./embeddings): text and image embeddings
- [Vision](./vision): detection, segmentation, video segmentation, super-resolution, classification and depth
- [Raw Function Calls](./raw-functions): any `.aimodel`, with tensors
- [Error Handling](./errors): error codes, and models that stop loading
- [Models](./models): hosted exports and how to make your own