expo-ai-kit 0.4.0 → 0.5.0

package/README.md

@@ -1,18 +1,13 @@
 # expo-ai-kit
 
-On-device AI for Expo & React Native. Run LLMs locally — no API keys, no cloud, no cost.
+On-device AI for Expo & React Native — run LLMs locally, no API keys, no cloud, no cost.
 
 [![npm version](https://img.shields.io/npm/v/expo-ai-kit.svg)](https://www.npmjs.com/package/expo-ai-kit)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Run Google's **Gemma 4** (E2B / E4B), **Apple Foundation Models**, and **ML Kit**
-entirely on-device — chat, streaming, and downloadable models, all local.
-
-- **Private** — inference never leaves the device
-- **Free** — no API costs, rate limits, or subscriptions
-- **Native** — Apple Foundation Models (iOS 26+), ML Kit (Android), Gemma 4 via [LiteRT-LM](https://ai.google.dev/edge/litert-lm)
-- **Streaming** — progressive token output with cancellation
-- **Model management** — download, load, and switch Gemma 4 models at runtime
+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, cancellation, and runtime model switching, all on-device.
 
 ## Install
 
@@ -20,111 +15,48 @@ entirely on-device — chat, streaming, and downloadable models, all local.
 npx expo install expo-ai-kit
 ```
 
-Bare React Native projects: run `npx pod-install` afterwards. Android needs
-`minSdkVersion 26` — set it via `expo-build-properties` in `app.json`.
+Bare RN: run `npx pod-install`. Android needs `minSdkVersion 26`. Requires Expo SDK 54+.
 
 ## Quick start
 
 ```tsx
-import { isAvailable, sendMessage } from 'expo-ai-kit';
+import { isAvailable, sendMessage, streamMessage } from 'expo-ai-kit';
 
 if (await isAvailable()) {
-  const { text } = await sendMessage([
-    { role: 'user', content: 'What is the capital of France?' },
-  ]);
-  console.log(text); // "Paris"
-}
-```
-
-Add a system prompt, or include `system`/`assistant` messages for multi-turn context.
-On-device models are stateless — pass the full message history on every call.
-
-```tsx
-const { text } = await sendMessage(
-  [{ role: 'user', content: 'Tell me a joke' }],
-  { systemPrompt: 'You are a stand-up comedian.' }
-);
-```
+  const { text } = await sendMessage([{ role: 'user', content: 'Capital of France?' }]);
 
-## Streaming
-
-```tsx
-import { streamMessage } from 'expo-ai-kit';
-
-const { promise, stop } = streamMessage(
-  [{ role: 'user', content: 'Write a short story' }],
-  (event) => setText(event.accumulatedText), // fired per token
-);
-
-await promise; // resolves with the final { text }
-// stop();     // cancel at any point
+  const { promise, stop } = streamMessage(
+    [{ role: 'user', content: 'Write a short story' }],
+    (e) => setText(e.accumulatedText),
+  );
+  await promise; // stop() to cancel
+}
 ```
 
-## Downloadable models (Gemma 4)
+`messages` is `{ role: 'system' | 'user' | 'assistant'; content: string }[]`. On-device
+models are stateless — pass the full history each call.
 
-On Android, download and run Gemma 4 models on top of the built-in OS model.
+## Downloadable Gemma 4
 
 ```tsx
-import {
-  getDownloadableModels, downloadModel, setModel, sendMessage,
-} from 'expo-ai-kit';
-
-// List models with their on-device status
-const models = await getDownloadableModels();
+import { getRecommendedModel, downloadModel, setModel } from 'expo-ai-kit';
 
-// Download with progress, then activate
-await downloadModel('gemma-e2b', {
-  onProgress: (p) => console.log(`${Math.round(p * 100)}%`),
-});
-await setModel('gemma-e2b', { backend: 'auto' }); // 'auto' | 'gpu' | 'cpu'
-
-// sendMessage / streamMessage now use the active model
-const { text } = await sendMessage([{ role: 'user', content: 'Hi!' }]);
+const best = await getRecommendedModel();          // E4B on high-RAM phones, else E2B
+if (best) {
+  await downloadModel(best.id, { onProgress: (p) => console.log(p) });
+  await setModel(best.id, { generation: { temperature: 0.7 } });
+  // sendMessage / streamMessage now use it; unloadModel() reverts to the OS model
+}
 ```
 
-`unloadModel()` frees memory and reverts to the OS model; `deleteModel(id)` removes the file.
-
-| Model | Params | Size | Platforms |
-|-------|--------|------|-----------|
-| `gemma-e2b` | 2.3B | ~2.6 GB | Android |
-| `gemma-e4b` | 4.5B | ~3.7 GB | Android |
-
-> iOS downloadable models are planned, pending LiteRT-LM Swift APIs from Google.
-
-## Platform support
-
-| Platform | Engine | Models |
-|----------|--------|--------|
-| iOS 26+ | [Apple Foundation Models](https://developer.apple.com/documentation/FoundationModels) | Built-in |
-| Android ([supported devices](https://developers.google.com/ml-kit/genai#prompt-device)) | [ML Kit Prompt API](https://developers.google.com/ml-kit/genai#prompt-device) | Built-in + downloadable Gemma 4 |
-| iOS < 26 / unsupported Android | — | `isAvailable()` returns `false` |
-
-Requires Expo SDK 54+.
-
 ## API
 
-**Inference**
-
-- `isAvailable()` → `Promise<boolean>`
-- `sendMessage(messages, options?)` → `Promise<{ text }>`
-- `streamMessage(messages, onToken, options?)` → `{ promise, stop }`
-
-**Models**
-
-- `getBuiltInModels()` → `Promise<BuiltInModel[]>`
-- `getDownloadableModels()` → `Promise<DownloadableModel[]>`
-- `downloadModel(id, { onProgress? })` / `deleteModel(id)`
-- `setModel(id, { backend? })` / `unloadModel()` / `getActiveModel()`
-
-`messages` is `{ role: 'system' | 'user' | 'assistant'; content: string }[]` and
-`options` accepts `{ systemPrompt?: string }`. Model operations throw `ModelError`
-with a `.code` (e.g. `MODEL_NOT_FOUND`, `DOWNLOAD_CORRUPT`, `INFERENCE_OOM`).
-Full TypeScript definitions ship with the package.
-
-## Links
+Inference: `isAvailable`, `sendMessage`, `streamMessage`.
+Models: `getBuiltInModels`, `getDownloadableModels`, `getRecommendedModel`,
+`downloadModel`, `cancelDownload`, `deleteModel`, `setModel`, `unloadModel`, `getActiveModel`.
 
-- [Docs](https://expo-ai-kit.dev) · [npm](https://www.npmjs.com/package/expo-ai-kit) · [GitHub](https://github.com/saidkaban/expo-ai-kit) · [Issues](https://github.com/saidkaban/expo-ai-kit/issues)
-- [Apple Foundation Models](https://developer.apple.com/documentation/foundationmodels) · [ML Kit GenAI](https://developers.google.com/ml-kit/genai) · [LiteRT-LM](https://ai.google.dev/edge/litert-lm)
+Failures throw `ModelError` with a typed `.code`. Full TypeScript definitions ship with
+the package — see [the docs](https://expo-ai-kit.dev) for the complete reference.
 
 ## License
 

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

@@ -40,7 +40,9 @@ class ExpoAiKitModule : Module() {
       promptClient.isAvailableBlocking()
     }
 
-    AsyncFunction("sendMessage") Coroutine { messages: List<Map<String, Any>>, fallbackSystemPrompt: String ->
+    // sessionId is accepted for API parity with iOS. Non-streaming generation on
+    // Android isn't separately cancellable (best-effort), so the id is unused here.
+    AsyncFunction("sendMessage") Coroutine { messages: List<Map<String, Any>>, fallbackSystemPrompt: String, sessionId: String ->
       // Extract system prompt from messages, or use fallback
       val systemPrompt = messages
         .firstOrNull { it["role"] == "system" }
@@ -144,11 +146,12 @@ class ExpoAiKitModule : Module() {
     }
 
     Function("getDownloadableModelStatus") { modelId: String ->
-      // Status reflects runtime state: "ready" if loaded in memory,
-      // "not-downloaded" otherwise (even if file is on disk -- setModel
-      // is the gatekeeper that transitions through loading -> ready).
+      // "ready" if loaded in memory; "downloaded" if the file is on disk but not
+      // loaded (survives restarts -- use it to skip a redundant re-download);
+      // "not-downloaded" if no file is present.
       when {
         gemmaClient.getLoadedModelId() == modelId && gemmaClient.isModelLoaded() -> "ready"
+        gemmaClient.isModelFileDownloaded(modelId) -> "downloaded"
         else -> "not-downloaded"
       }
     }
@@ -168,7 +171,7 @@ class ExpoAiKitModule : Module() {
     // Model selection & memory management
     // ==================================================================
 
-    AsyncFunction("setModel") Coroutine { modelId: String, minRamBytes: Long, backend: String ->
+    AsyncFunction("setModel") Coroutine { modelId: String, minRamBytes: Long, backend: String, generation: Map<String, Double> ->
       if (modelId == "mlkit") {
         // Switch to built-in: unload any Gemma model
         if (gemmaClient.isModelLoaded()) {
@@ -177,7 +180,7 @@ class ExpoAiKitModule : Module() {
           if (previousId != "mlkit") {
             sendEvent("onModelStateChange", mapOf(
               "modelId" to previousId,
-              "status" to "not-downloaded"
+              "status" to if (gemmaClient.isModelFileDownloaded(previousId)) "downloaded" else "not-downloaded"
             ))
           }
         }
@@ -198,7 +201,12 @@ class ExpoAiKitModule : Module() {
 
       try {
         val modelPath = gemmaClient.getModelFilePath(modelId)
-        gemmaClient.loadModel(modelId, modelPath, minRamBytes, backend)
+        gemmaClient.loadModel(
+          modelId, modelPath, minRamBytes, backend,
+          temperature = generation["temperature"],
+          topK = generation["topK"]?.toInt(),
+          topP = generation["topP"]
+        )
         activeModelId = modelId
 
         // Emit ready state
@@ -207,10 +215,10 @@ class ExpoAiKitModule : Module() {
           "status" to "ready"
         ))
       } catch (e: Exception) {
-        // Emit failure -- revert status
+        // Load failed, but the file is still on disk -> "downloaded", not "not-downloaded".
         sendEvent("onModelStateChange", mapOf(
           "modelId" to modelId,
-          "status" to "not-downloaded"
+          "status" to if (gemmaClient.isModelFileDownloaded(modelId)) "downloaded" else "not-downloaded"
         ))
         throw e
       }
@@ -227,7 +235,7 @@ class ExpoAiKitModule : Module() {
         activeModelId = "mlkit"
         sendEvent("onModelStateChange", mapOf(
           "modelId" to previousId,
-          "status" to "not-downloaded"
+          "status" to if (gemmaClient.isModelFileDownloaded(previousId)) "downloaded" else "not-downloaded"
         ))
       }
     }
@@ -250,20 +258,25 @@ class ExpoAiKitModule : Module() {
           ))
         }
 
-        // Download complete -- file is on disk but not loaded
+        // Download succeeded: file is on disk, awaiting setModel() to load it.
         sendEvent("onModelStateChange", mapOf(
           "modelId" to modelId,
-          "status" to "not-downloaded"
+          "status" to "downloaded"
         ))
       } catch (e: Exception) {
+        // On failure, report whatever is actually on disk (a prior good copy may remain).
         sendEvent("onModelStateChange", mapOf(
           "modelId" to modelId,
-          "status" to "not-downloaded"
+          "status" to if (gemmaClient.isModelFileDownloaded(modelId)) "downloaded" else "not-downloaded"
         ))
         throw e
       }
     }
 
+    AsyncFunction("cancelDownload") Coroutine { modelId: String ->
+      gemmaClient.cancelDownload(modelId)
+    }
+
     AsyncFunction("deleteModel") Coroutine { modelId: String ->
       // If this model is active, switch back to mlkit first
       if (activeModelId == modelId) {

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

@@ -10,6 +10,7 @@ import com.google.ai.edge.litertlm.Backend
 import com.google.ai.edge.litertlm.Message
 import com.google.ai.edge.litertlm.MessageCallback
 import com.google.ai.edge.litertlm.Contents
+import com.google.ai.edge.litertlm.SamplerConfig
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
@@ -45,6 +46,9 @@ class GemmaInferenceClient(private val context: Context) {
   @Volatile
   private var isDownloading = false
 
+  @Volatile
+  private var cancelDownloadRequested = false
+
   // -------------------------------------------------------------------------
   // Model lifecycle
   // -------------------------------------------------------------------------
@@ -54,7 +58,15 @@ class GemmaInferenceClient(private val context: Context) {
    * Unloads any previously loaded model first.
    * Caller is responsible for emitting onModelStateChange events.
    */
-  suspend fun loadModel(modelId: String, modelPath: String, minRamBytes: Long = 0, backend: String = "auto") = mutex.withLock {
+  suspend fun loadModel(
+    modelId: String,
+    modelPath: String,
+    minRamBytes: Long = 0,
+    backend: String = "auto",
+    temperature: Double? = null,
+    topK: Int? = null,
+    topP: Double? = null
+  ) = mutex.withLock {
     // Unload previous model if different
     if (loadedModelId != null && loadedModelId != modelId) {
       conversation?.close()
@@ -117,7 +129,21 @@ class GemmaInferenceClient(private val context: Context) {
           }
         }
 
-        val newConversation = newEngine.createConversation(ConversationConfig())
+        // Sampling knobs are fixed at conversation creation by LiteRT-LM. If any
+        // is provided, build a SamplerConfig (filling unspecified values with
+        // Gemma-typical defaults); otherwise use the engine/model defaults.
+        val convConfig = if (temperature != null || topK != null || topP != null) {
+          ConversationConfig(
+            samplerConfig = SamplerConfig(
+              topK = topK ?: 64,
+              topP = topP ?: 0.95,
+              temperature = temperature ?: 1.0
+            )
+          )
+        } else {
+          ConversationConfig()
+        }
+        val newConversation = newEngine.createConversation(convConfig)
 
         engine = newEngine
         conversation = newConversation
@@ -191,6 +217,9 @@ class GemmaInferenceClient(private val context: Context) {
           )
         }
       }
+    } catch (e: kotlinx.coroutines.CancellationException) {
+      // Cooperative cancellation — propagate, don't mask as an inference failure.
+      throw e
     } catch (e: OutOfMemoryError) {
       throw RuntimeException("INFERENCE_OOM:${loadedModelId ?: "unknown"}:Out of memory during inference")
     } catch (e: Exception) {
@@ -260,6 +289,9 @@ class GemmaInferenceClient(private val context: Context) {
           )
         }
       }
+    } catch (e: kotlinx.coroutines.CancellationException) {
+      // Cooperative cancellation — propagate, don't mask as an inference failure.
+      throw e
     } catch (e: OutOfMemoryError) {
       throw RuntimeException("INFERENCE_OOM:${loadedModelId ?: "unknown"}:Out of memory during inference")
     } catch (e: Exception) {
@@ -288,6 +320,7 @@ class GemmaInferenceClient(private val context: Context) {
       throw RuntimeException("DOWNLOAD_FAILED:$modelId:Download already in progress")
     }
     isDownloading = true
+    cancelDownloadRequested = false
 
     try {
       withContext(Dispatchers.IO) {
@@ -308,6 +341,9 @@ class GemmaInferenceClient(private val context: Context) {
               val buffer = ByteArray(8192)
               var read: Int
               while (input.read(buffer).also { read = it } != -1) {
+                if (cancelDownloadRequested) {
+                  throw RuntimeException("DOWNLOAD_CANCELLED:$modelId:Download cancelled")
+                }
                 output.write(buffer, 0, read)
                 bytesRead += read
                 if (totalBytes > 0) {
@@ -336,6 +372,7 @@ class GemmaInferenceClient(private val context: Context) {
           tempFile.delete()
           when {
             e is RuntimeException && e.message?.startsWith("DOWNLOAD_CORRUPT") == true -> throw e
+            e is RuntimeException && e.message?.startsWith("DOWNLOAD_CANCELLED") == true -> throw e
             context.filesDir.freeSpace < 100_000_000 ->
               throw RuntimeException("DOWNLOAD_STORAGE_FULL:$modelId:Insufficient disk space")
             else ->
@@ -372,6 +409,14 @@ class GemmaInferenceClient(private val context: Context) {
     }
   }
 
+  /**
+   * Request cancellation of the in-flight download, if any. The download loop
+   * checks this flag and throws DOWNLOAD_CANCELLED. No-op if nothing is downloading.
+   */
+  fun cancelDownload(modelId: String) {
+    cancelDownloadRequested = true
+  }
+
   /**
    * Check if a model file exists on disk.
    */

package/build/ExpoAiKitModule.d.ts

@@ -5,18 +5,27 @@ export type ExpoAiKitModuleEvents = {
     onDownloadProgress: (event: ModelDownloadProgressEvent) => void;
     onModelStateChange: (event: ModelStateChangeEvent) => void;
 };
+/** Generation parameters passed to native. All fields optional; -1 / absent means "unset". */
+export type NativeGenerationConfig = {
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    seed?: number;
+    maxTokens?: number;
+};
 export interface ExpoAiKitNativeModule {
     isAvailable(): boolean;
-    sendMessage(messages: LLMMessage[], systemPrompt: string): Promise<LLMResponse>;
+    sendMessage(messages: LLMMessage[], systemPrompt: string, sessionId: string): Promise<LLMResponse>;
     startStreaming(messages: LLMMessage[], systemPrompt: string, sessionId: string): Promise<void>;
     stopStreaming(sessionId: string): Promise<void>;
     getBuiltInModels(): BuiltInModel[];
-    getDownloadableModelStatus(modelId: string): DownloadableModelStatus;
+    getDownloadableModelStatus(modelId: string): Promise<DownloadableModelStatus>;
     getDeviceRamBytes(): number;
-    setModel(modelId: string, minRamBytes: number, backend: string): Promise<void>;
+    setModel(modelId: string, minRamBytes: number, backend: string, generation: NativeGenerationConfig): Promise<void>;
     getActiveModel(): string;
     unloadModel(): Promise<void>;
     downloadModel(modelId: string, url: string, sha256: string): Promise<void>;
+    cancelDownload(modelId: string): Promise<void>;
     deleteModel(modelId: string): Promise<void>;
     addListener<K extends keyof ExpoAiKitModuleEvents>(eventName: K, listener: ExpoAiKitModuleEvents[K]): EventSubscription;
 }

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,MAAM,WAAW,qBAAqB;IAEpC,WAAW,IAAI,OAAO,CAAC;IACvB,WAAW,CACT,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,GACnB,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;IACjB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAGhD,gBAAgB,IAAI,YAAY,EAAE,CAAC;IACnC,0BAA0B,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,CAAC;IACrE,iBAAiB,IAAI,MAAM,CAAC;IAK5B,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,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;IACjB,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;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"}

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;AA6DxD,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\nexport interface ExpoAiKitNativeModule {\n  // Existing inference API\n  isAvailable(): boolean;\n  sendMessage(\n    messages: LLMMessage[],\n    systemPrompt: string\n  ): Promise<LLMResponse>;\n  startStreaming(\n    messages: LLMMessage[],\n    systemPrompt: string,\n    sessionId: string\n  ): Promise<void>;\n  stopStreaming(sessionId: string): Promise<void>;\n\n  // Model discovery\n  getBuiltInModels(): BuiltInModel[];\n  getDownloadableModelStatus(modelId: string): 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  setModel(modelId: string, minRamBytes: number, backend: string): 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  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;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"]}

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { LLMMessage, LLMSendOptions, LLMResponse, LLMStreamOptions, LLMStreamCallback, BuiltInModel, DownloadableModel, SetModelOptions } from './types';
+import { LLMMessage, LLMSendOptions, LLMResponse, LLMStreamOptions, LLMStreamCallback, LLMStreamHandle, BuiltInModel, DownloadableModel, SetModelOptions } from './types';
 export * from './types';
 export * from './models';
 /**
@@ -75,10 +75,7 @@ export declare function sendMessage(messages: LLMMessage[], options?: LLMSendOpt
  * setTimeout(() => stop(), 5000);
  * ```
  */
-export declare function streamMessage(messages: LLMMessage[], onToken: LLMStreamCallback, options?: LLMStreamOptions): {
-    promise: Promise<LLMResponse>;
-    stop: () => void;
-};
+export declare function streamMessage(messages: LLMMessage[], onToken: LLMStreamCallback, options?: LLMStreamOptions): LLMStreamHandle;
 /**
  * Get all built-in models available on the current platform.
  *
@@ -97,6 +94,26 @@ export declare function getBuiltInModels(): Promise<BuiltInModel[]>;
  * @returns Array of downloadable models with their current status
  */
 export declare function getDownloadableModels(): Promise<DownloadableModel[]>;
+/**
+ * Pick the best downloadable model the current device can run.
+ *
+ * Returns the most capable model (largest, by RAM requirement) whose
+ * `meetsRequirements` is true — e.g. Gemma 4 E4B on high-spec phones, falling
+ * back to E2B on more constrained ones — or `null` if the device can't run any.
+ *
+ * This is a convenience over {@link getDownloadableModels}; the caller still
+ * downloads + activates explicitly. Pass `platform` is implicit (current OS).
+ *
+ * @example
+ * ```ts
+ * const best = await getRecommendedModel();
+ * if (best) {
+ *   await downloadModel(best.id, { onProgress });
+ *   await setModel(best.id);
+ * }
+ * ```
+ */
+export declare function getRecommendedModel(): Promise<DownloadableModel | null>;
 /**
  * Download a model to the device.
  *
@@ -115,6 +132,15 @@ export declare function getDownloadableModels(): Promise<DownloadableModel[]>;
 export declare function downloadModel(modelId: string, options?: {
     onProgress?: (progress: number) => void;
 }): Promise<void>;
+/**
+ * Cancel an in-flight download for a model.
+ *
+ * The in-progress {@link downloadModel} promise rejects with a
+ * DOWNLOAD_CANCELLED {@link ModelError}. No-op if the model isn't downloading.
+ *
+ * @param modelId - ID of the model whose download should be cancelled
+ */
+export declare function cancelDownload(modelId: string): Promise<void>;
 /**
  * Delete a downloaded model from the device.
  *

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAEhB,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EAEjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAGjB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AAczB;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAKpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,WAAW,CAAC,CAgBtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB;IAAE,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAiErD;AAMD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAKhE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA6B1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpD,OAAO,CAAC,IAAI,CAAC,CAiDf;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,UAAU,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAEhB,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,iBAAiB,EAIjB,eAAe,EAChB,MAAM,SAAS,CAAC;AAGjB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AAuHzB;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAKpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,WAAW,CAAC,CAmEtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,GACzB,eAAe,CAwFjB;AAMD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC,CAKhE;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAiC1E;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAM7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GACpD,OAAO,CAAC,IAAI,CAAC,CA+Cf;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnE;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAQxF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAEjD"}