expo-ai-kit 0.9.0 → 0.11.0

package/README.md

@@ -7,8 +7,12 @@ On-device AI for Expo & React Native — run LLMs locally. No API keys, no cloud
 
 Runs **Apple Foundation Models** (iOS 26+), **ML Kit** (Android), and downloadable
 **Gemma 4** (E2B / E4B, iOS + Android via [LiteRT-LM](https://ai.google.dev/edge/litert-lm))
-— with streaming, structured output, tool calling, cancellation, and runtime model switching,
-all on-device.
+— with streaming, structured output, tool calling, **embeddings & on-device RAG**,
+cancellation, and runtime model switching, all on-device.
+
+**New in 0.11:** a [**Vercel AI SDK provider**](#vercel-ai-sdk) — use `generateText`,
+`streamText`, and `embed` from the [AI SDK](https://ai-sdk.dev) with on-device models
+via `expo-ai-kit/ai`. Same `useChat`-style code you'd write for OpenAI, no API key.
 
 ## Install
 
@@ -98,6 +102,94 @@ Omit a tool's `execute` to gate it yourself: the loop stops with `finishReason:
 and hands you the proposed call to confirm before running. Keep tool sets small and parameter
 schemas flat — on-device models pick tools more reliably that way.
 
+## Embeddings & RAG
+
+Turn text into vectors for semantic search and retrieval-augmented generation — find the
+chunks of your own documents most relevant to a question, then feed them to the model. All
+on-device: your data never leaves the phone.
+
+```tsx
+import { embed, chunkText, createVectorStore, sendMessage } from 'expo-ai-kit';
+
+// 1. Index your document once: split → embed → store
+const chunks = chunkText(document);                 // overlapping, sentence-aware chunks
+const { embeddings } = await embed(chunks);          // one vector per chunk
+const store = createVectorStore<{ text: string }>();
+store.addMany(chunks.map((text, i) => ({ id: `c${i}`, vector: embeddings[i], metadata: { text } })));
+
+// 2. At query time: embed the question, retrieve the top matches, answer from them
+const { embeddings: [q] } = await embed([question]);
+const context = store.search(q, { topK: 4 }).map((h) => h.metadata!.text).join('\n\n');
+
+const { text } = await sendMessage([
+  { role: 'system', content: `Answer using only this context:\n${context}` },
+  { role: 'user', content: question },
+]);
+```
+
+`embed()` is backed by Apple's `NLContextualEmbedding` — a **zero-download, OS-maintained**
+model (iOS 17+, works even without Apple Intelligence). **iOS-only for now**; on Android it
+throws `DEVICE_NOT_SUPPORTED` (MediaPipe support is planned). The toolkit —
+`chunkText`, `cosineSimilarity`, and the `createVectorStore` (add / search top-k / `toJSON`
+for persistence) — is pure JS and works on **both platforms with any vector source**.
+
+## Vercel AI SDK
+
+expo-ai-kit ships a first-class [AI SDK](https://ai-sdk.dev) provider: point `model:` at
+`expoAiKit()` and the AI SDK's `generateText` / `streamText` / `generateObject` / `embed`
+run **on-device** — reuse code, examples, and patterns written for cloud providers, with
+no API key and no data leaving the phone.
+
+```bash
+npm i ai   # AI SDK 6+ (the provider implements LanguageModelV3; AI SDK 7 accepts it too)
+```
+
+```tsx
+import { generateText, streamText, embed } from 'ai';
+import { expoAiKit } from 'expo-ai-kit/ai';
+
+// Text — the active on-device model (OS built-in by default)
+const { text } = await generateText({
+  model: expoAiKit(),
+  prompt: 'Capital of France?',
+});
+
+// Streaming — pass a specific model id to activate it first
+const result = streamText({
+  model: expoAiKit('gemma-e2b'),  // must be downloaded; settings ride along:
+  // model: expoAiKit('gemma-e2b', { generation: { temperature: 0.7 } }),
+  prompt: 'Write a short story',
+});
+for await (const chunk of result.textStream) setText((t) => t + chunk);
+
+// Embeddings (iOS) — the same NLContextualEmbedding behind embed()
+const { embedding } = await embed({
+  model: expoAiKit.embeddingModel(),
+  value: 'sunny day at the beach',
+});
+```
+
+Tool calling and `generateObject` work too — they ride the exact same prompt protocol as
+the core `generateText`/`generateObject`, so behavior is identical either way.
+
+**On-device caveats** (the honest fine print):
+
+- **One generation at a time.** Concurrent calls reject with `INFERENCE_BUSY` — on-device
+  models share a single KV-cache. Await one call before starting the next.
+- **Sampling is fixed at model activation**, not per call. A per-call `temperature`/`topK`
+  is reported as an AI SDK warning and ignored; set it via `expoAiKit(id, { generation })`
+  or `setModel()`.
+- **Streaming buffers when tools or JSON output are requested** — the tool-call envelope
+  has to be parsed whole, not leaked as text deltas. Plain-text streaming is token-by-token.
+- **No token usage numbers** (on-device runtimes don't report them) and no image/file inputs
+  (vision is on the roadmap). `embeddingModel()` is iOS-only, like `embed()`.
+- React Native needs the AI SDK's usual polyfills (e.g. `web-streams-polyfill`,
+  `structuredClone`, `TextEncoder`) — see the docs for a copy-paste setup.
+
+The provider is a thin wrapper over the same core functions below — mix and match freely.
+The core stays **zero-dependency**; `@ai-sdk/provider` is an optional peer used only for
+types when you import `expo-ai-kit/ai`.
+
 ## Downloadable models
 
 Beyond the OS built-ins, you can download open models (via LiteRT-LM) and switch to them at
@@ -166,6 +258,8 @@ file persists on disk, so its `'downloaded'` status survives restarts once re-re
 ## API
 
 Inference: `isAvailable`, `sendMessage`, `streamMessage`, `generateObject`, `generateText`.
+Embeddings & RAG: `embed`, `chunkText`, `cosineSimilarity`, `createVectorStore`.
+AI SDK provider (`expo-ai-kit/ai`): `expoAiKit`, `createExpoAiKit`.
 Models: `getBuiltInModels`, `getDownloadableModels`, `getRecommendedModel`,
 `downloadModel`, `cancelDownload`, `deleteModel`, `setModel`, `unloadModel`, `getActiveModel`.
 Custom models: `registerModel`, `unregisterModel`, `getRegisteredModels`, `fetchModelMetadata`.

package/ai.d.ts

@@ -0,0 +1 @@
+export * from './build/ai';

package/ai.js

@@ -0,0 +1,5 @@
+// Subpath entry: `import { expoAiKit } from 'expo-ai-kit/ai'`.
+// A root shim (instead of a package.json "exports" map) so resolution works
+// across Metro, Node, and TypeScript without changing how the existing
+// entry points resolve.
+export * from './build/ai';

package/android/src/main/java/expo/modules/aikit/ExpoAiKitModule.kt

@@ -128,6 +128,20 @@ class ExpoAiKitModule : Module() {
       activeStreamJobs.remove(sessionId)
     }
 
+    // ==================================================================
+    // Embeddings
+    // ==================================================================
+    // iOS-only for now (Apple NLContextualEmbedding). The JS layer guards the
+    // platform and throws before reaching native, so this is a defensive stub
+    // that honors the same "CODE::reason" error contract. Android support via
+    // MediaPipe Text Embedder is planned.
+    AsyncFunction("embed") { _: List<String> ->
+      throw RuntimeException(
+        "DEVICE_NOT_SUPPORTED::On-device embeddings are iOS-only for now " +
+          "(Apple NLContextualEmbedding); Android support via MediaPipe is planned"
+      )
+    }
+
     // ==================================================================
     // Model discovery
     // ==================================================================

package/build/ExpoAiKitModule.d.ts

@@ -18,6 +18,10 @@ export interface ExpoAiKitNativeModule {
     sendMessage(messages: LLMMessage[], systemPrompt: string, sessionId: string): Promise<LLMResponse>;
     startStreaming(messages: LLMMessage[], systemPrompt: string, sessionId: string): Promise<void>;
     stopStreaming(sessionId: string): Promise<void>;
+    embed(texts: string[]): Promise<{
+        embeddings: number[][];
+        dimensions: number;
+    }>;
     getBuiltInModels(): BuiltInModel[];
     getDownloadableModelStatus(modelId: string): Promise<DownloadableModelStatus>;
     getDeviceRamBytes(): number;

package/build/ExpoAiKitModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoAiKitModule.d.ts","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC/C,kBAAkB,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAChE,kBAAkB,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC5D,CAAC;AAEF,8FAA8F;AAC9F,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,qBAAqB;IAEpC,WAAW,IAAI,OAAO,CAAC;IAEvB,WAAW,CACT,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,cAAc,CACZ,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGhD,gBAAgB,IAAI,YAAY,EAAE,CAAC;IAGnC,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC9E,iBAAiB,IAAI,MAAM,CAAC;IAM5B,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,IAAI,MAAM,CAAC;IAGzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAG7B,aAAa,CACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG5C,WAAW,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAC/C,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,iBAAiB,CAAC;CACtB;AAED,QAAA,MAAM,eAAe,uBACoC,CAAC;AAE1D,eAAe,eAAe,CAAC"}
+{"version":3,"file":"ExpoAiKitModule.d.ts","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,cAAc,EACd,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAEjB,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC/C,kBAAkB,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAC;IAChE,kBAAkB,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC5D,CAAC;AAEF,8FAA8F;AAC9F,MAAM,MAAM,sBAAsB,GAAG;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,WAAW,qBAAqB;IAEpC,WAAW,IAAI,OAAO,CAAC;IAEvB,WAAW,CACT,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC;IACxB,cAAc,CACZ,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAIhD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAGhF,gBAAgB,IAAI,YAAY,EAAE,CAAC;IAGnC,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC9E,iBAAiB,IAAI,MAAM,CAAC;IAM5B,QAAQ,CACN,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,GACjC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,cAAc,IAAI,MAAM,CAAC;IAGzB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAG7B,aAAa,CACX,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG5C,WAAW,CAAC,CAAC,SAAS,MAAM,qBAAqB,EAC/C,SAAS,EAAE,CAAC,EACZ,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC,GACjC,iBAAiB,CAAC;CACtB;AAED,QAAA,MAAM,eAAe,uBACoC,CAAC;AAE1D,eAAe,eAAe,CAAC"}

package/build/ExpoAiKitModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoAiKitModule.js","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAmFxD,MAAM,eAAe,GACnB,mBAAmB,CAAwB,WAAW,CAAC,CAAC;AAE1D,eAAe,eAAe,CAAC","sourcesContent":["import { requireNativeModule } from 'expo-modules-core';\nimport type { EventSubscription } from 'expo-modules-core';\nimport {\n  BuiltInModel,\n  DownloadableModelStatus,\n  LLMMessage,\n  LLMResponse,\n  LLMStreamEvent,\n  ModelDownloadProgressEvent,\n  ModelStateChangeEvent,\n} from './types';\n\nexport type ExpoAiKitModuleEvents = {\n  onStreamToken: (event: LLMStreamEvent) => void;\n  onDownloadProgress: (event: ModelDownloadProgressEvent) => void;\n  onModelStateChange: (event: ModelStateChangeEvent) => void;\n};\n\n/** Generation parameters passed to native. All fields optional; -1 / absent means \"unset\". */\nexport type NativeGenerationConfig = {\n  temperature?: number;\n  topK?: number;\n  topP?: number;\n  seed?: number;\n  maxTokens?: number;\n};\n\nexport interface ExpoAiKitNativeModule {\n  // Existing inference API\n  isAvailable(): boolean;\n  // sessionId lets stopStreaming() cancel an in-flight (non-streaming) generation too.\n  sendMessage(\n    messages: LLMMessage[],\n    systemPrompt: string,\n    sessionId: string\n  ): Promise<LLMResponse>;\n  startStreaming(\n    messages: LLMMessage[],\n    systemPrompt: string,\n    sessionId: string\n  ): Promise<void>;\n  // Cancels either a streaming session or a sendMessage session by id.\n  stopStreaming(sessionId: string): Promise<void>;\n\n  // Model discovery\n  getBuiltInModels(): BuiltInModel[];\n  // Async: iOS reads actor-isolated state (so it bridges as a Promise); Android\n  // returns synchronously. Callers must await — see getDownloadableModels.\n  getDownloadableModelStatus(modelId: string): Promise<DownloadableModelStatus>;\n  getDeviceRamBytes(): number;\n\n  // Model selection & memory management\n  // setModel is async: switching to a downloadable model loads it into memory.\n  // Auto-unloads the previous downloadable model (only one loaded at a time).\n  // `generation` carries best-effort sampling defaults for the session.\n  setModel(\n    modelId: string,\n    minRamBytes: number,\n    backend: string,\n    generation: NativeGenerationConfig\n  ): Promise<void>;\n  getActiveModel(): string;\n  // Explicitly free memory from the loaded downloadable model.\n  // Reverts to the platform built-in model.\n  unloadModel(): Promise<void>;\n\n  // Model lifecycle (downloadable models only)\n  downloadModel(\n    modelId: string,\n    url: string,\n    sha256: string\n  ): Promise<void>;\n  // Cancels an in-flight download for the given model (no-op if none).\n  cancelDownload(modelId: string): Promise<void>;\n  deleteModel(modelId: string): Promise<void>;\n\n  // Event subscription\n  addListener<K extends keyof ExpoAiKitModuleEvents>(\n    eventName: K,\n    listener: ExpoAiKitModuleEvents[K]\n  ): EventSubscription;\n}\n\nconst ExpoAiKitModule =\n  requireNativeModule<ExpoAiKitNativeModule>('ExpoAiKit');\n\nexport default ExpoAiKitModule;\n"]}
+{"version":3,"file":"ExpoAiKitModule.js","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAuFxD,MAAM,eAAe,GACnB,mBAAmB,CAAwB,WAAW,CAAC,CAAC;AAE1D,eAAe,eAAe,CAAC","sourcesContent":["import { requireNativeModule } from 'expo-modules-core';\nimport type { EventSubscription } from 'expo-modules-core';\nimport {\n  BuiltInModel,\n  DownloadableModelStatus,\n  LLMMessage,\n  LLMResponse,\n  LLMStreamEvent,\n  ModelDownloadProgressEvent,\n  ModelStateChangeEvent,\n} from './types';\n\nexport type ExpoAiKitModuleEvents = {\n  onStreamToken: (event: LLMStreamEvent) => void;\n  onDownloadProgress: (event: ModelDownloadProgressEvent) => void;\n  onModelStateChange: (event: ModelStateChangeEvent) => void;\n};\n\n/** Generation parameters passed to native. All fields optional; -1 / absent means \"unset\". */\nexport type NativeGenerationConfig = {\n  temperature?: number;\n  topK?: number;\n  topP?: number;\n  seed?: number;\n  maxTokens?: number;\n};\n\nexport interface ExpoAiKitNativeModule {\n  // Existing inference API\n  isAvailable(): boolean;\n  // sessionId lets stopStreaming() cancel an in-flight (non-streaming) generation too.\n  sendMessage(\n    messages: LLMMessage[],\n    systemPrompt: string,\n    sessionId: string\n  ): Promise<LLMResponse>;\n  startStreaming(\n    messages: LLMMessage[],\n    systemPrompt: string,\n    sessionId: string\n  ): Promise<void>;\n  // Cancels either a streaming session or a sendMessage session by id.\n  stopStreaming(sessionId: string): Promise<void>;\n\n  // Embeddings. iOS-only (Apple NLContextualEmbedding); the JS layer guards the\n  // platform, so this is never reached on Android/web.\n  embed(texts: string[]): Promise<{ embeddings: number[][]; dimensions: number }>;\n\n  // Model discovery\n  getBuiltInModels(): BuiltInModel[];\n  // Async: iOS reads actor-isolated state (so it bridges as a Promise); Android\n  // returns synchronously. Callers must await — see getDownloadableModels.\n  getDownloadableModelStatus(modelId: string): Promise<DownloadableModelStatus>;\n  getDeviceRamBytes(): number;\n\n  // Model selection & memory management\n  // setModel is async: switching to a downloadable model loads it into memory.\n  // Auto-unloads the previous downloadable model (only one loaded at a time).\n  // `generation` carries best-effort sampling defaults for the session.\n  setModel(\n    modelId: string,\n    minRamBytes: number,\n    backend: string,\n    generation: NativeGenerationConfig\n  ): Promise<void>;\n  getActiveModel(): string;\n  // Explicitly free memory from the loaded downloadable model.\n  // Reverts to the platform built-in model.\n  unloadModel(): Promise<void>;\n\n  // Model lifecycle (downloadable models only)\n  downloadModel(\n    modelId: string,\n    url: string,\n    sha256: string\n  ): Promise<void>;\n  // Cancels an in-flight download for the given model (no-op if none).\n  cancelDownload(modelId: string): Promise<void>;\n  deleteModel(modelId: string): Promise<void>;\n\n  // Event subscription\n  addListener<K extends keyof ExpoAiKitModuleEvents>(\n    eventName: K,\n    listener: ExpoAiKitModuleEvents[K]\n  ): EventSubscription;\n}\n\nconst ExpoAiKitModule =\n  requireNativeModule<ExpoAiKitNativeModule>('ExpoAiKit');\n\nexport default ExpoAiKitModule;\n"]}

package/build/ai/convert.d.ts

@@ -0,0 +1,55 @@
+import type { LanguageModelV3CallOptions, LanguageModelV3ToolResultOutput, LanguageModelV3Usage, SharedV3Warning } from '@ai-sdk/provider';
+import { type LLMMessage } from '../types';
+/**
+ * On-device runtimes report no token counts, so every usage field is
+ * `undefined` (the shape the spec prescribes for "unknown").
+ */
+export declare const EMPTY_USAGE: LanguageModelV3Usage;
+/** Unique-enough id for stream parts / tool calls within a session. */
+export declare function newPartId(prefix: string): string;
+/** Everything doGenerate/doStream needs, derived from LanguageModelV3CallOptions. */
+export type ConvertedCall = {
+    /** The conversation in our core protocol, instructions merged into the system message. */
+    messages: LLMMessage[];
+    /** Names of function tools offered to the model ([] when none / toolChoice 'none'). */
+    toolNames: string[];
+    /** True when responseFormat is JSON — output should be extracted as JSON. */
+    jsonMode: boolean;
+    /** Spec warnings for settings we cannot honor on-device. */
+    warnings: SharedV3Warning[];
+};
+/**
+ * Map the AI SDK's call options onto our core `LLMMessage[]` protocol.
+ *
+ * - System messages are merged into one leading system message, with the tool
+ *   instruction (tools.ts) and/or JSON-Schema instruction (structured.ts)
+ *   appended — the same prompt protocol as generateText / generateObject.
+ * - Assistant tool-call parts are re-rendered as the `{"tool", "arguments"}`
+ *   envelope and tool results as formatToolResult() text, so multi-step AI SDK
+ *   conversations round-trip through the exact format the model was taught.
+ * - Per-call sampling settings can't be honored (fixed at setModel) and are
+ *   reported as spec warnings instead of being silently dropped.
+ *
+ * @throws {ModelError} DEVICE_NOT_SUPPORTED on file/image prompt parts —
+ *   on-device text models have no media input (vision is on the roadmap).
+ */
+export declare function convertCallOptions(options: LanguageModelV3CallOptions): ConvertedCall;
+/** What the model's raw text turned out to be, per the offered capabilities. */
+export type ExtractedOutput = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'tool-call';
+    toolName: string;
+    input: string;
+};
+/**
+ * Interpret raw model output for the AI SDK: detect a tool-call envelope when
+ * tools were offered (reusing parseToolCall), or extract/clean the JSON value
+ * in json mode (reusing extractJson). Single-shot — the repair loops live in
+ * the core generateText/generateObject, not in the provider.
+ */
+export declare function extractOutput(text: string, toolNames: string[], jsonMode: boolean): ExtractedOutput;
+/** Unwrap the spec's tool-result output union into a plain value for formatToolResult. */
+export declare function unwrapToolOutput(output: LanguageModelV3ToolResultOutput): unknown;
+//# sourceMappingURL=convert.d.ts.map

package/build/ai/convert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.d.ts","sourceRoot":"","sources":["../../src/ai/convert.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAE1B,+BAA+B,EAC/B,oBAAoB,EACpB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAA+B,KAAK,UAAU,EAAgB,MAAM,UAAU,CAAC;AAkBtF;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,oBAYzB,CAAC;AAGF,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,qFAAqF;AACrF,MAAM,MAAM,aAAa,GAAG;IAC1B,0FAA0F;IAC1F,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,uFAAuF;IACvF,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B,CAAC;AAeF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa,CAqIrF;AAED,gFAAgF;AAChF,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EAAE,EACnB,QAAQ,EAAE,OAAO,GAChB,eAAe,CAsBjB;AAED,0FAA0F;AAC1F,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,+BAA+B,GAAG,OAAO,CAiBjF"}

package/build/ai/convert.js

@@ -0,0 +1,270 @@
+import { ModelError } from '../types';
+import { buildSchemaInstruction, extractJson } from '../structured';
+import { buildToolInstruction, formatToolResult, parseToolCall } from '../tools';
+// ---------------------------------------------------------------------------
+// Pure helpers for the Vercel AI SDK provider (src/ai/index.ts).
+//
+// Like structured.ts and tools.ts, this module imports no native module so its
+// logic can be unit-tested in plain Node. It maps the AI SDK's LanguageModelV3
+// call options onto our LLMMessage[] protocol — reusing the exact same tool
+// instruction / tool-call envelope as generateText() and the same JSON-Schema
+// instruction / extraction as generateObject(), so a model behaves identically
+// whether it's driven through the AI SDK or through the core API.
+//
+// Only *type* imports from '@ai-sdk/provider' are allowed here (they compile
+// away), keeping the published JS free of runtime dependencies.
+// ---------------------------------------------------------------------------
+/**
+ * On-device runtimes report no token counts, so every usage field is
+ * `undefined` (the shape the spec prescribes for "unknown").
+ */
+export const EMPTY_USAGE = {
+    inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined,
+    },
+    outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined,
+    },
+};
+let idCounter = 0;
+/** Unique-enough id for stream parts / tool calls within a session. */
+export function newPartId(prefix) {
+    return `${prefix}_${Date.now()}_${++idCounter}`;
+}
+// Per-call sampling knobs the AI SDK passes that on-device runtimes fix at
+// setModel() time (LiteRT-LM builds its sampler at conversation creation).
+const FIXED_AT_SETMODEL = [
+    'temperature',
+    'topP',
+    'topK',
+    'seed',
+    'maxOutputTokens',
+    'stopSequences',
+    'presencePenalty',
+    'frequencyPenalty',
+];
+/**
+ * Map the AI SDK's call options onto our core `LLMMessage[]` protocol.
+ *
+ * - System messages are merged into one leading system message, with the tool
+ *   instruction (tools.ts) and/or JSON-Schema instruction (structured.ts)
+ *   appended — the same prompt protocol as generateText / generateObject.
+ * - Assistant tool-call parts are re-rendered as the `{"tool", "arguments"}`
+ *   envelope and tool results as formatToolResult() text, so multi-step AI SDK
+ *   conversations round-trip through the exact format the model was taught.
+ * - Per-call sampling settings can't be honored (fixed at setModel) and are
+ *   reported as spec warnings instead of being silently dropped.
+ *
+ * @throws {ModelError} DEVICE_NOT_SUPPORTED on file/image prompt parts —
+ *   on-device text models have no media input (vision is on the roadmap).
+ */
+export function convertCallOptions(options) {
+    const warnings = [];
+    for (const setting of FIXED_AT_SETMODEL) {
+        if (options[setting] != null) {
+            warnings.push({
+                type: 'unsupported',
+                feature: setting,
+                details: 'On-device sampling is fixed when the model is activated (setModel / provider settings), not per call.',
+            });
+        }
+    }
+    // --- Tools → the generateText() text protocol -----------------------------
+    const toolSet = {};
+    const toolChoice = options.toolChoice ?? { type: 'auto' };
+    if (options.tools && toolChoice.type !== 'none') {
+        for (const tool of options.tools) {
+            if (tool.type === 'function') {
+                toolSet[tool.name] = {
+                    description: tool.description ?? '',
+                    parameters: toLocalSchema(tool.inputSchema),
+                };
+            }
+            else {
+                warnings.push({
+                    type: 'unsupported',
+                    feature: `provider tool "${tool.id}"`,
+                    details: 'expo-ai-kit runs on-device models; provider-executed tools are not available.',
+                });
+            }
+        }
+    }
+    const toolNames = Object.keys(toolSet);
+    let toolInstruction = toolNames.length > 0 ? buildToolInstruction(toolSet) : '';
+    if (toolNames.length > 0 && toolChoice.type === 'required') {
+        toolInstruction += '\n- For this request you MUST call one of the tools.';
+        warnings.push({
+            type: 'compatibility',
+            feature: "toolChoice: 'required'",
+            details: 'Enforced via a prompt nudge — on-device models have no constrained decoding yet.',
+        });
+    }
+    else if (toolNames.length > 0 && toolChoice.type === 'tool') {
+        toolInstruction += `\n- For this request you MUST call the tool "${toolChoice.toolName}".`;
+        warnings.push({
+            type: 'compatibility',
+            feature: `toolChoice: { type: 'tool' }`,
+            details: 'Enforced via a prompt nudge — on-device models have no constrained decoding yet.',
+        });
+    }
+    // --- responseFormat json → the generateObject() instruction ---------------
+    let jsonMode = false;
+    let schemaInstruction = '';
+    if (options.responseFormat?.type === 'json') {
+        if (toolNames.length > 0) {
+            // The SDK never combines them; if a caller does, tools win.
+            warnings.push({
+                type: 'other',
+                message: 'responseFormat: json is ignored when tools are provided.',
+            });
+        }
+        else {
+            jsonMode = true;
+            schemaInstruction = options.responseFormat.schema
+                ? buildSchemaInstruction(toLocalSchema(options.responseFormat.schema))
+                : 'Respond with ONLY a valid JSON value — no prose, no markdown code fences.';
+        }
+    }
+    // --- Prompt → LLMMessage[] -------------------------------------------------
+    const systemParts = [];
+    const messages = [];
+    for (const message of options.prompt) {
+        switch (message.role) {
+            case 'system': {
+                systemParts.push(message.content);
+                break;
+            }
+            case 'user': {
+                const text = message.content
+                    .map((part) => {
+                    if (part.type === 'text')
+                        return part.text;
+                    throw unsupportedPart(part.type);
+                })
+                    .join('');
+                messages.push({ role: 'user', content: text });
+                break;
+            }
+            case 'assistant': {
+                const chunks = [];
+                for (const part of message.content) {
+                    if (part.type === 'text') {
+                        chunks.push(part.text);
+                    }
+                    else if (part.type === 'tool-call') {
+                        // Re-render past calls in the envelope the model was taught, so
+                        // multi-step conversations stay in-protocol.
+                        chunks.push(JSON.stringify({ tool: part.toolName, arguments: part.input ?? {} }));
+                    }
+                    else if (part.type === 'reasoning') {
+                        // Model-internal; not replayed.
+                    }
+                    else if (part.type === 'tool-result') {
+                        // Provider-executed results never occur here (we execute nothing).
+                    }
+                    else {
+                        throw unsupportedPart(part.type);
+                    }
+                }
+                const text = chunks.join('\n');
+                if (text !== '')
+                    messages.push({ role: 'assistant', content: text });
+                break;
+            }
+            case 'tool': {
+                const chunks = [];
+                for (const part of message.content) {
+                    if (part.type === 'tool-result') {
+                        chunks.push(formatToolResult(part.toolName, unwrapToolOutput(part.output)));
+                    }
+                    // tool-approval-response: we never emit approval requests, so none
+                    // can legitimately appear; ignore defensively.
+                }
+                if (chunks.length > 0)
+                    messages.push({ role: 'user', content: chunks.join('\n\n') });
+                break;
+            }
+        }
+    }
+    const instructions = [toolInstruction, schemaInstruction].filter((s) => s !== '');
+    const system = [...systemParts, ...instructions].join('\n\n');
+    if (system !== '') {
+        messages.unshift({ role: 'system', content: system });
+    }
+    return { messages, toolNames, jsonMode, warnings };
+}
+/**
+ * Interpret raw model output for the AI SDK: detect a tool-call envelope when
+ * tools were offered (reusing parseToolCall), or extract/clean the JSON value
+ * in json mode (reusing extractJson). Single-shot — the repair loops live in
+ * the core generateText/generateObject, not in the provider.
+ */
+export function extractOutput(text, toolNames, jsonMode) {
+    if (toolNames.length > 0) {
+        const parsed = parseToolCall(text, toolNames);
+        if (parsed.kind === 'tool') {
+            return {
+                kind: 'tool-call',
+                toolName: parsed.toolName,
+                input: safeStringify(parsed.args ?? {}),
+            };
+        }
+        // 'unknown-tool' deliberately falls through to text: the provider is
+        // single-shot, so surfacing the raw output beats silently retrying.
+        return { kind: 'text', text };
+    }
+    if (jsonMode) {
+        const parsed = extractJson(text);
+        if (parsed.ok)
+            return { kind: 'text', text: safeStringify(parsed.value) };
+        return { kind: 'text', text }; // let the SDK report the parse failure honestly
+    }
+    return { kind: 'text', text };
+}
+/** Unwrap the spec's tool-result output union into a plain value for formatToolResult. */
+export function unwrapToolOutput(output) {
+    switch (output.type) {
+        case 'text':
+            return output.value;
+        case 'json':
+            return output.value;
+        case 'error-text':
+            return { error: output.value };
+        case 'error-json':
+            return { error: output.value };
+        case 'execution-denied':
+            return { error: `Tool execution denied${output.reason ? `: ${output.reason}` : ''}` };
+        case 'content':
+            return output.value
+                .map((part) => (part.type === 'text' ? part.text : `[${part.type} omitted]`))
+                .join('\n');
+    }
+}
+/**
+ * The spec's JSONSchema7 and our pragmatic JSONSchema subset are structurally
+ * compatible for prompting purposes (both serialize to the same JSON); this
+ * cast localizes the type-system disagreement to one place.
+ */
+function toLocalSchema(schema) {
+    if (typeof schema === 'object' && schema !== null)
+        return schema;
+    return {};
+}
+function unsupportedPart(type) {
+    return new ModelError('DEVICE_NOT_SUPPORTED', '', `expo-ai-kit AI SDK provider: "${type}" prompt parts are not supported — ` +
+        'on-device models take text only (vision input is on the roadmap).');
+}
+function safeStringify(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=convert.js.map

package/build/ai/convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convert.js","sourceRoot":"","sources":["../../src/ai/convert.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  LanguageModelV3CallOptions,\n  LanguageModelV3FunctionTool,\n  LanguageModelV3ToolResultOutput,\n  LanguageModelV3Usage,\n  SharedV3Warning,\n} from '@ai-sdk/provider';\nimport { ModelError, type JSONSchema, type LLMMessage, type ToolSet } from '../types';\nimport { buildSchemaInstruction, extractJson } from '../structured';\nimport { buildToolInstruction, formatToolResult, parseToolCall } from '../tools';\n\n// ---------------------------------------------------------------------------\n// Pure helpers for the Vercel AI SDK provider (src/ai/index.ts).\n//\n// Like structured.ts and tools.ts, this module imports no native module so its\n// logic can be unit-tested in plain Node. It maps the AI SDK's LanguageModelV3\n// call options onto our LLMMessage[] protocol — reusing the exact same tool\n// instruction / tool-call envelope as generateText() and the same JSON-Schema\n// instruction / extraction as generateObject(), so a model behaves identically\n// whether it's driven through the AI SDK or through the core API.\n//\n// Only *type* imports from '@ai-sdk/provider' are allowed here (they compile\n// away), keeping the published JS free of runtime dependencies.\n// ---------------------------------------------------------------------------\n\n/**\n * On-device runtimes report no token counts, so every usage field is\n * `undefined` (the shape the spec prescribes for \"unknown\").\n */\nexport const EMPTY_USAGE: LanguageModelV3Usage = {\n  inputTokens: {\n    total: undefined,\n    noCache: undefined,\n    cacheRead: undefined,\n    cacheWrite: undefined,\n  },\n  outputTokens: {\n    total: undefined,\n    text: undefined,\n    reasoning: undefined,\n  },\n};\n\nlet idCounter = 0;\n/** Unique-enough id for stream parts / tool calls within a session. */\nexport function newPartId(prefix: string): string {\n  return `${prefix}_${Date.now()}_${++idCounter}`;\n}\n\n/** Everything doGenerate/doStream needs, derived from LanguageModelV3CallOptions. */\nexport type ConvertedCall = {\n  /** The conversation in our core protocol, instructions merged into the system message. */\n  messages: LLMMessage[];\n  /** Names of function tools offered to the model ([] when none / toolChoice 'none'). */\n  toolNames: string[];\n  /** True when responseFormat is JSON — output should be extracted as JSON. */\n  jsonMode: boolean;\n  /** Spec warnings for settings we cannot honor on-device. */\n  warnings: SharedV3Warning[];\n};\n\n// Per-call sampling knobs the AI SDK passes that on-device runtimes fix at\n// setModel() time (LiteRT-LM builds its sampler at conversation creation).\nconst FIXED_AT_SETMODEL = [\n  'temperature',\n  'topP',\n  'topK',\n  'seed',\n  'maxOutputTokens',\n  'stopSequences',\n  'presencePenalty',\n  'frequencyPenalty',\n] as const;\n\n/**\n * Map the AI SDK's call options onto our core `LLMMessage[]` protocol.\n *\n * - System messages are merged into one leading system message, with the tool\n *   instruction (tools.ts) and/or JSON-Schema instruction (structured.ts)\n *   appended — the same prompt protocol as generateText / generateObject.\n * - Assistant tool-call parts are re-rendered as the `{\"tool\", \"arguments\"}`\n *   envelope and tool results as formatToolResult() text, so multi-step AI SDK\n *   conversations round-trip through the exact format the model was taught.\n * - Per-call sampling settings can't be honored (fixed at setModel) and are\n *   reported as spec warnings instead of being silently dropped.\n *\n * @throws {ModelError} DEVICE_NOT_SUPPORTED on file/image prompt parts —\n *   on-device text models have no media input (vision is on the roadmap).\n */\nexport function convertCallOptions(options: LanguageModelV3CallOptions): ConvertedCall {\n  const warnings: SharedV3Warning[] = [];\n\n  for (const setting of FIXED_AT_SETMODEL) {\n    if (options[setting] != null) {\n      warnings.push({\n        type: 'unsupported',\n        feature: setting,\n        details:\n          'On-device sampling is fixed when the model is activated (setModel / provider settings), not per call.',\n      });\n    }\n  }\n\n  // --- Tools → the generateText() text protocol -----------------------------\n  const toolSet: ToolSet = {};\n  const toolChoice = options.toolChoice ?? { type: 'auto' };\n  if (options.tools && toolChoice.type !== 'none') {\n    for (const tool of options.tools) {\n      if (tool.type === 'function') {\n        toolSet[tool.name] = {\n          description: tool.description ?? '',\n          parameters: toLocalSchema((tool as LanguageModelV3FunctionTool).inputSchema),\n        };\n      } else {\n        warnings.push({\n          type: 'unsupported',\n          feature: `provider tool \"${tool.id}\"`,\n          details: 'expo-ai-kit runs on-device models; provider-executed tools are not available.',\n        });\n      }\n    }\n  }\n  const toolNames = Object.keys(toolSet);\n\n  let toolInstruction = toolNames.length > 0 ? buildToolInstruction(toolSet) : '';\n  if (toolNames.length > 0 && toolChoice.type === 'required') {\n    toolInstruction += '\\n- For this request you MUST call one of the tools.';\n    warnings.push({\n      type: 'compatibility',\n      feature: \"toolChoice: 'required'\",\n      details: 'Enforced via a prompt nudge — on-device models have no constrained decoding yet.',\n    });\n  } else if (toolNames.length > 0 && toolChoice.type === 'tool') {\n    toolInstruction += `\\n- For this request you MUST call the tool \"${toolChoice.toolName}\".`;\n    warnings.push({\n      type: 'compatibility',\n      feature: `toolChoice: { type: 'tool' }`,\n      details: 'Enforced via a prompt nudge — on-device models have no constrained decoding yet.',\n    });\n  }\n\n  // --- responseFormat json → the generateObject() instruction ---------------\n  let jsonMode = false;\n  let schemaInstruction = '';\n  if (options.responseFormat?.type === 'json') {\n    if (toolNames.length > 0) {\n      // The SDK never combines them; if a caller does, tools win.\n      warnings.push({\n        type: 'other',\n        message: 'responseFormat: json is ignored when tools are provided.',\n      });\n    } else {\n      jsonMode = true;\n      schemaInstruction = options.responseFormat.schema\n        ? buildSchemaInstruction(toLocalSchema(options.responseFormat.schema))\n        : 'Respond with ONLY a valid JSON value — no prose, no markdown code fences.';\n    }\n  }\n\n  // --- Prompt → LLMMessage[] -------------------------------------------------\n  const systemParts: string[] = [];\n  const messages: LLMMessage[] = [];\n\n  for (const message of options.prompt) {\n    switch (message.role) {\n      case 'system': {\n        systemParts.push(message.content);\n        break;\n      }\n      case 'user': {\n        const text = message.content\n          .map((part) => {\n            if (part.type === 'text') return part.text;\n            throw unsupportedPart(part.type);\n          })\n          .join('');\n        messages.push({ role: 'user', content: text });\n        break;\n      }\n      case 'assistant': {\n        const chunks: string[] = [];\n        for (const part of message.content) {\n          if (part.type === 'text') {\n            chunks.push(part.text);\n          } else if (part.type === 'tool-call') {\n            // Re-render past calls in the envelope the model was taught, so\n            // multi-step conversations stay in-protocol.\n            chunks.push(JSON.stringify({ tool: part.toolName, arguments: part.input ?? {} }));\n          } else if (part.type === 'reasoning') {\n            // Model-internal; not replayed.\n          } else if (part.type === 'tool-result') {\n            // Provider-executed results never occur here (we execute nothing).\n          } else {\n            throw unsupportedPart(part.type);\n          }\n        }\n        const text = chunks.join('\\n');\n        if (text !== '') messages.push({ role: 'assistant', content: text });\n        break;\n      }\n      case 'tool': {\n        const chunks: string[] = [];\n        for (const part of message.content) {\n          if (part.type === 'tool-result') {\n            chunks.push(formatToolResult(part.toolName, unwrapToolOutput(part.output)));\n          }\n          // tool-approval-response: we never emit approval requests, so none\n          // can legitimately appear; ignore defensively.\n        }\n        if (chunks.length > 0) messages.push({ role: 'user', content: chunks.join('\\n\\n') });\n        break;\n      }\n    }\n  }\n\n  const instructions = [toolInstruction, schemaInstruction].filter((s) => s !== '');\n  const system = [...systemParts, ...instructions].join('\\n\\n');\n  if (system !== '') {\n    messages.unshift({ role: 'system', content: system });\n  }\n\n  return { messages, toolNames, jsonMode, warnings };\n}\n\n/** What the model's raw text turned out to be, per the offered capabilities. */\nexport type ExtractedOutput =\n  | { kind: 'text'; text: string }\n  | { kind: 'tool-call'; toolName: string; input: string };\n\n/**\n * Interpret raw model output for the AI SDK: detect a tool-call envelope when\n * tools were offered (reusing parseToolCall), or extract/clean the JSON value\n * in json mode (reusing extractJson). Single-shot — the repair loops live in\n * the core generateText/generateObject, not in the provider.\n */\nexport function extractOutput(\n  text: string,\n  toolNames: string[],\n  jsonMode: boolean\n): ExtractedOutput {\n  if (toolNames.length > 0) {\n    const parsed = parseToolCall(text, toolNames);\n    if (parsed.kind === 'tool') {\n      return {\n        kind: 'tool-call',\n        toolName: parsed.toolName,\n        input: safeStringify(parsed.args ?? {}),\n      };\n    }\n    // 'unknown-tool' deliberately falls through to text: the provider is\n    // single-shot, so surfacing the raw output beats silently retrying.\n    return { kind: 'text', text };\n  }\n\n  if (jsonMode) {\n    const parsed = extractJson(text);\n    if (parsed.ok) return { kind: 'text', text: safeStringify(parsed.value) };\n    return { kind: 'text', text }; // let the SDK report the parse failure honestly\n  }\n\n  return { kind: 'text', text };\n}\n\n/** Unwrap the spec's tool-result output union into a plain value for formatToolResult. */\nexport function unwrapToolOutput(output: LanguageModelV3ToolResultOutput): unknown {\n  switch (output.type) {\n    case 'text':\n      return output.value;\n    case 'json':\n      return output.value;\n    case 'error-text':\n      return { error: output.value };\n    case 'error-json':\n      return { error: output.value };\n    case 'execution-denied':\n      return { error: `Tool execution denied${output.reason ? `: ${output.reason}` : ''}` };\n    case 'content':\n      return output.value\n        .map((part) => (part.type === 'text' ? part.text : `[${part.type} omitted]`))\n        .join('\\n');\n  }\n}\n\n/**\n * The spec's JSONSchema7 and our pragmatic JSONSchema subset are structurally\n * compatible for prompting purposes (both serialize to the same JSON); this\n * cast localizes the type-system disagreement to one place.\n */\nfunction toLocalSchema(schema: unknown): JSONSchema {\n  if (typeof schema === 'object' && schema !== null) return schema as JSONSchema;\n  return {};\n}\n\nfunction unsupportedPart(type: string): ModelError {\n  return new ModelError(\n    'DEVICE_NOT_SUPPORTED',\n    '',\n    `expo-ai-kit AI SDK provider: \"${type}\" prompt parts are not supported — ` +\n      'on-device models take text only (vision input is on the roadmap).'\n  );\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value) ?? String(value);\n  } catch {\n    return String(value);\n  }\n}\n"]}

package/build/ai/index.d.ts

@@ -0,0 +1,66 @@
+import type { EmbeddingModelV3, LanguageModelV3 } from '@ai-sdk/provider';
+import { type SetModelOptions } from '../types';
+/**
+ * Sentinel model id meaning "whatever model is currently active" — the OS
+ * built-in by default, or whatever the app last activated via setModel().
+ * The provider never switches models for this id.
+ */
+export declare const AUTO_MODEL_ID = "auto";
+/** Model id for the built-in embedding model (Apple NLContextualEmbedding, iOS 17+). */
+export declare const EMBEDDING_MODEL_ID = "apple-nl-contextual";
+/**
+ * Per-instance model settings, applied when this instance activates its model
+ * (same shape as {@link setModel}'s options). If the model is already active,
+ * it is NOT reloaded — on-device model loads are expensive, so sampling config
+ * effectively belongs to whoever activated the model first.
+ */
+export type ExpoAiKitModelSettings = SetModelOptions;
+export interface ExpoAiKitProvider {
+    /** Shorthand for {@link ExpoAiKitProvider.languageModel}. */
+    (modelId?: string, settings?: ExpoAiKitModelSettings): LanguageModelV3;
+    /**
+     * A LanguageModelV3 over the on-device model. Pass any model id accepted by
+     * setModel() ('apple-fm', 'mlkit', 'gemma-e2b', a registerModel() id, …) to
+     * have the provider activate it before generating, or omit / pass 'auto' to
+     * use whatever model is already active.
+     */
+    languageModel(modelId?: string, settings?: ExpoAiKitModelSettings): LanguageModelV3;
+    /** An EmbeddingModelV3 over embed() — iOS-only (Apple NLContextualEmbedding). */
+    embeddingModel(modelId?: string): EmbeddingModelV3;
+    /** @deprecated Spec alias for {@link ExpoAiKitProvider.embeddingModel}. */
+    textEmbeddingModel(modelId?: string): EmbeddingModelV3;
+    /** expo-ai-kit has no image models; always throws MODEL_NOT_FOUND. */
+    imageModel(modelId: string): never;
+}
+/**
+ * Create an expo-ai-kit provider for the Vercel AI SDK.
+ *
+ * ```ts
+ * import { generateText, streamText } from 'ai';
+ * import { expoAiKit } from 'expo-ai-kit/ai';
+ *
+ * const { text } = await generateText({
+ *   model: expoAiKit(),               // the active on-device model
+ *   prompt: 'Capital of France?',
+ * });
+ *
+ * const result = streamText({
+ *   model: expoAiKit('gemma-e2b'),    // activates gemma-e2b first (must be downloaded)
+ *   prompt: 'Write a short story',
+ * });
+ * ```
+ *
+ * On-device caveats (all documented in the guide):
+ * - One generation at a time — concurrent calls reject with INFERENCE_BUSY.
+ * - Per-call sampling (temperature, topK, …) is reported as an unsupported-
+ *   setting warning; sampling is fixed when the model is activated.
+ * - Tool calling and JSON output ride the same prompt protocol as
+ *   generateText()/generateObject() — single-shot here, since the AI SDK owns
+ *   the loop. Streaming buffers when tools/JSON are requested (the envelope
+ *   must be parsed whole, not surfaced as text deltas).
+ * - embeddingModel() is iOS-only for now; Android throws DEVICE_NOT_SUPPORTED.
+ */
+export declare function createExpoAiKit(): ExpoAiKitProvider;
+/** The default provider instance. */
+export declare const expoAiKit: ExpoAiKitProvider;
+//# sourceMappingURL=index.d.ts.map

package/build/ai/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ai/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EAMhB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAkB5D;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC,wFAAwF;AACxF,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,eAAe,CAAC;AAErD,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAAC;IACvE;;;;;OAKG;IACH,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAAC;IACpF,iFAAiF;IACjF,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACnD,2EAA2E;IAC3E,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC;IACvD,sEAAsE;IACtE,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,IAAI,iBAAiB,CAyBnD;AAED,qCAAqC;AACrC,eAAO,MAAM,SAAS,EAAE,iBAAqC,CAAC"}