expo-ai-kit 0.1.15 → 0.1.17

package/README.md

@@ -28,7 +28,9 @@ On-device AI for Expo apps. Run language models locally—no API keys, no cloud,
 - **Free forever** — No API costs, rate limits, or subscriptions
 - **Native performance** — Built on Apple Foundation Models (iOS) and Google ML Kit Prompt API (Android)
 - **Multi-turn conversations** — Full conversation context support
-- **Simple API** — Just 2 functions: `isAvailable()` and `sendMessage()`
+- **Streaming support** — Progressive token streaming for responsive UIs
+- **Simple API** — Core functions plus prompt helpers for common tasks
+- **Prompt helpers** — Built-in `summarize()`, `translate()`, `rewrite()`, and more
 
 ## Requirements
 
@@ -142,6 +144,112 @@ const response = await sendMessage(conversation, {
 console.log(response.text); // "Your name is Alice."
 ```
 
+### Streaming Responses
+
+For a ChatGPT-like experience where text appears progressively:
+
+```tsx
+import { streamMessage } from 'expo-ai-kit';
+
+const [responseText, setResponseText] = useState('');
+
+const { promise, stop } = streamMessage(
+  [{ role: 'user', content: 'Tell me a story' }],
+  (event) => {
+    // Update UI with each token
+    setResponseText(event.accumulatedText);
+
+    // event.token - the new token/chunk
+    // event.accumulatedText - full text so far
+    // event.isDone - whether streaming is complete
+  },
+  { systemPrompt: 'You are a creative storyteller.' }
+);
+
+// Optionally cancel the stream
+// stop();
+
+// Wait for completion
+await promise;
+```
+
+### Prompt Helpers
+
+Use built-in helpers for common AI tasks without crafting prompts:
+
+```tsx
+import { summarize, translate, rewrite, extractKeyPoints, answerQuestion } from 'expo-ai-kit';
+
+// Summarize text
+const summary = await summarize(longArticle, { length: 'short', style: 'bullets' });
+
+// Translate text
+const translated = await translate('Hello, world!', { to: 'Spanish' });
+
+// Rewrite in a different style
+const formal = await rewrite('hey whats up', { style: 'formal' });
+
+// Extract key points
+const points = await extractKeyPoints(article, { maxPoints: 5 });
+
+// Answer questions about content
+const answer = await answerQuestion('What is the main topic?', documentText);
+```
+
+All helpers also have streaming variants (`streamSummarize`, `streamTranslate`, etc.):
+
+```tsx
+const { promise, stop } = streamSummarize(
+  longArticle,
+  (event) => setSummary(event.accumulatedText),
+  { style: 'bullets' }
+);
+```
+
+### Streaming with Cancel Button
+
+```tsx
+import { useState, useRef } from 'react';
+import { streamMessage } from 'expo-ai-kit';
+
+function ChatWithStreaming() {
+  const [text, setText] = useState('');
+  const [isStreaming, setIsStreaming] = useState(false);
+  const stopRef = useRef<(() => void) | null>(null);
+
+  const handleSend = async () => {
+    setIsStreaming(true);
+    setText('');
+
+    const { promise, stop } = streamMessage(
+      [{ role: 'user', content: 'Write a long story' }],
+      (event) => setText(event.accumulatedText)
+    );
+
+    stopRef.current = stop;
+    await promise;
+    stopRef.current = null;
+    setIsStreaming(false);
+  };
+
+  const handleStop = () => {
+    stopRef.current?.();
+    setIsStreaming(false);
+  };
+
+  return (
+    <View>
+      <Text>{text}</Text>
+      {isStreaming ? (
+        <Button title="Stop" onPress={handleStop} />
+      ) : (
+        <Button title="Send" onPress={handleSend} />
+      )}
+    </View>
+  );
+}
+```
+
 ### Complete Chat Example
 
 Here's a full cross-platform chat component:
@@ -264,6 +372,139 @@ console.log(response.text); // "Ahoy, matey!"
 
 ---
 
+### `streamMessage(messages, onToken, options?)`
+
+Streams a conversation response with progressive token updates. Ideal for responsive chat UIs.
+
+```typescript
+function streamMessage(
+  messages: LLMMessage[],
+  onToken: LLMStreamCallback,
+  options?: LLMStreamOptions
+): { promise: Promise<LLMResponse>; stop: () => void }
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `messages` | `LLMMessage[]` | Array of conversation messages |
+| `onToken` | `LLMStreamCallback` | Callback called for each token received |
+| `options.systemPrompt` | `string` | Fallback system prompt (ignored if messages contain a system message) |
+
+**Returns:** Object with:
+- `promise: Promise<LLMResponse>` — Resolves when streaming completes
+- `stop: () => void` — Function to cancel the stream
+
+**Example:**
+```tsx
+const { promise, stop } = streamMessage(
+  [{ role: 'user', content: 'Hello!' }],
+  (event) => {
+    console.log(event.token);           // New token: "Hi"
+    console.log(event.accumulatedText); // Full text: "Hi there!"
+    console.log(event.isDone);          // false until complete
+  }
+);
+
+// Cancel if needed
+setTimeout(() => stop(), 5000);
+
+// Wait for completion
+const response = await promise;
+```
+
+---
+
+### `summarize(text, options?)`
+
+Summarizes text using on-device AI.
+
+```typescript
+function summarize(text: string, options?: LLMSummarizeOptions): Promise<LLMResponse>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Text to summarize |
+| `options.length` | `'short' \| 'medium' \| 'long'` | Summary length (default: `'medium'`) |
+| `options.style` | `'paragraph' \| 'bullets' \| 'tldr'` | Output format (default: `'paragraph'`) |
+
+**Streaming:** `streamSummarize(text, onToken, options?)`
+
+---
+
+### `translate(text, options)`
+
+Translates text to another language.
+
+```typescript
+function translate(text: string, options: LLMTranslateOptions): Promise<LLMResponse>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Text to translate |
+| `options.to` | `string` | Target language (required) |
+| `options.from` | `string` | Source language (auto-detected if omitted) |
+| `options.tone` | `'formal' \| 'informal' \| 'neutral'` | Translation tone (default: `'neutral'`) |
+
+**Streaming:** `streamTranslate(text, onToken, options)`
+
+---
+
+### `rewrite(text, options)`
+
+Rewrites text in a different style.
+
+```typescript
+function rewrite(text: string, options: LLMRewriteOptions): Promise<LLMResponse>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Text to rewrite |
+| `options.style` | `string` | Target style (required) |
+
+**Available styles:** `'formal'`, `'casual'`, `'professional'`, `'friendly'`, `'concise'`, `'detailed'`, `'simple'`, `'academic'`
+
+**Streaming:** `streamRewrite(text, onToken, options)`
+
+---
+
+### `extractKeyPoints(text, options?)`
+
+Extracts key points from text as bullet points.
+
+```typescript
+function extractKeyPoints(text: string, options?: LLMExtractKeyPointsOptions): Promise<LLMResponse>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | `string` | Text to analyze |
+| `options.maxPoints` | `number` | Maximum points to extract (default: `5`) |
+
+**Streaming:** `streamExtractKeyPoints(text, onToken, options?)`
+
+---
+
+### `answerQuestion(question, context, options?)`
+
+Answers a question based on provided context.
+
+```typescript
+function answerQuestion(question: string, context: string, options?: LLMAnswerQuestionOptions): Promise<LLMResponse>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `question` | `string` | Question to answer |
+| `context` | `string` | Context/document to base answer on |
+| `options.detail` | `'brief' \| 'medium' \| 'detailed'` | Answer detail level (default: `'medium'`) |
+
+**Streaming:** `streamAnswerQuestion(question, context, onToken, options?)`
+
+---
+
 ### Types
 
 ```typescript
@@ -279,10 +520,52 @@ type LLMSendOptions = {
   systemPrompt?: string;
 };
 
+type LLMStreamOptions = {
+  /** Fallback system prompt if no system message in messages array */
+  systemPrompt?: string;
+};
+
 type LLMResponse = {
   /** The generated response text */
   text: string;
 };
+
+type LLMStreamEvent = {
+  /** Unique identifier for this streaming session */
+  sessionId: string;
+  /** The token/chunk of text received */
+  token: string;
+  /** Accumulated text so far */
+  accumulatedText: string;
+  /** Whether this is the final chunk */
+  isDone: boolean;
+};
+
+type LLMStreamCallback = (event: LLMStreamEvent) => void;
+
+// Prompt Helper Types
+type LLMSummarizeOptions = {
+  length?: 'short' | 'medium' | 'long';
+  style?: 'paragraph' | 'bullets' | 'tldr';
+};
+
+type LLMTranslateOptions = {
+  to: string;
+  from?: string;
+  tone?: 'formal' | 'informal' | 'neutral';
+};
+
+type LLMRewriteOptions = {
+  style: 'formal' | 'casual' | 'professional' | 'friendly' | 'concise' | 'detailed' | 'simple' | 'academic';
+};
+
+type LLMExtractKeyPointsOptions = {
+  maxPoints?: number;
+};
+
+type LLMAnswerQuestionOptions = {
+  detail?: 'brief' | 'medium' | 'detailed';
+};
 ```
 
 ## Feature Comparison
@@ -291,8 +574,11 @@ type LLMResponse = {
 |---------|---------|---------------------|
 | `isAvailable()` | ✅ | ✅ |
 | `sendMessage()` | ✅ | ✅ |
+| `streamMessage()` | ✅ | ✅ |
+| Prompt helpers | ✅ | ✅ |
 | System prompts | ✅ Native | ✅ Prepended |
 | Multi-turn context | ✅ | ✅ |
+| Cancel streaming | ✅ | ✅ |
 
 ## How It Works
 
@@ -312,7 +598,7 @@ Uses Google's ML Kit Prompt API. The model may need to be downloaded on first us
 - **Empty responses**: The device may not support ML Kit Prompt API. Check the [supported devices list](https://developers.google.com/ml-kit/genai#prompt-device)
 - **Model downloading**: On first use, the model may need to download. Use `isAvailable()` to check status
 
-## Migration from v0.1.x
+## Migration from v0.1.4
 
 If you're upgrading from an earlier version, here are the breaking changes:
 
@@ -335,6 +621,18 @@ const { reply } = await sendMessage(sessionId, messages, {});
 const { text } = await sendMessage(messages, { systemPrompt: '...' });
 ```
 
+## Roadmap
+
+| Feature | Status | Priority |
+|---------|--------|----------|
+| ✅ Streaming responses | Done | - |
+| ✅ Prompt helpers (summarize, translate, etc.) | Done | - |
+| Conversation memory (useChat hook) | Planned | High |
+| Web/generic fallback | Idea | Medium |
+| Configurable hyperparameters (temperature, etc.) | Idea | Low |
+
+Have a feature request? [Open an issue](https://github.com/laraelmas/expo-ai-kit/issues)!
+
 ## License
 
 MIT

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

@@ -3,14 +3,24 @@ package expo.modules.aikit
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 import expo.modules.kotlin.functions.Coroutine
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.cancel
 
 class ExpoAiKitModule : Module() {
 
   private val promptClient by lazy { PromptApiClient() }
+  private val activeStreamJobs = mutableMapOf<String, Job>()
+  private val streamScope = CoroutineScope(Dispatchers.IO)
 
   override fun definition() = ModuleDefinition {
     Name("ExpoAiKit")
 
+    // Declare events that can be sent to JavaScript
+    Events("onStreamToken")
+
     Function("isAvailable") {
       promptClient.isAvailableBlocking()
     }
@@ -31,5 +41,42 @@ class ExpoAiKitModule : Module() {
       val text = promptClient.generateText(userPrompt, systemPrompt)
       mapOf("text" to text)
     }
+
+    AsyncFunction("startStreaming") { messages: List<Map<String, Any>>, fallbackSystemPrompt: String, sessionId: String ->
+      // Extract system prompt from messages, or use fallback
+      val systemPrompt = messages
+        .firstOrNull { it["role"] == "system" }
+        ?.get("content") as? String
+        ?: fallbackSystemPrompt.ifBlank { "You are a helpful, friendly assistant." }
+
+      // Get the last user message as the prompt
+      val userPrompt = messages
+        .lastOrNull { it["role"] == "user" }
+        ?.get("content") as? String
+        ?: ""
+
+      // Launch streaming in a coroutine that can be cancelled
+      val job = streamScope.launch {
+        promptClient.generateTextStream(userPrompt, systemPrompt) { token, accumulatedText, isDone ->
+          sendEvent("onStreamToken", mapOf(
+            "sessionId" to sessionId,
+            "token" to token,
+            "accumulatedText" to accumulatedText,
+            "isDone" to isDone
+          ))
+
+          if (isDone) {
+            activeStreamJobs.remove(sessionId)
+          }
+        }
+      }
+
+      activeStreamJobs[sessionId] = job
+    }
+
+    AsyncFunction("stopStreaming") { sessionId: String ->
+      activeStreamJobs[sessionId]?.cancel()
+      activeStreamJobs.remove(sessionId)
+    }
   }
 }

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

@@ -4,6 +4,8 @@ import android.os.Build
 import com.google.mlkit.genai.common.FeatureStatus
 import com.google.mlkit.genai.prompt.Generation
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.runBlocking
 import kotlinx.coroutines.withContext
 
@@ -64,4 +66,47 @@ class PromptApiClient {
         ""
       }
     }
+
+  /**
+   * Generate streaming text from a prompt.
+   * Returns a Flow that emits chunks of generated text.
+   */
+  suspend fun generateTextStream(
+    prompt: String,
+    systemPrompt: String,
+    onChunk: (token: String, accumulatedText: String, isDone: Boolean) -> Unit
+  ) = withContext(Dispatchers.IO) {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+      onChunk("", "", true)
+      return@withContext
+    }
+
+    try {
+      val status = model.checkStatus()
+      if (status != FeatureStatus.AVAILABLE) {
+        onChunk("", "", true)
+        return@withContext
+      }
+
+      // Prepend system prompt as context if provided
+      val fullPrompt = if (systemPrompt.isNotBlank()) {
+        "$systemPrompt\n\nUser: $prompt"
+      } else {
+        prompt
+      }
+
+      var accumulatedText = ""
+
+      model.generateContentStream(fullPrompt).collect { response ->
+        val newChunk = response.candidates.firstOrNull()?.text.orEmpty()
+        accumulatedText += newChunk
+        onChunk(newChunk, accumulatedText, false)
+      }
+
+      // Send final done event
+      onChunk("", accumulatedText, true)
+    } catch (e: Throwable) {
+      onChunk("", "[Error: ${e.message}]", true)
+    }
+  }
 }

package/build/ExpoAiKitModule.d.ts

@@ -1,8 +1,15 @@
-import { LLMMessage, LLMResponse } from './types';
-export type ExpoAiKitNativeModule = {
+import type { EventSubscription } from 'expo-modules-core';
+import { LLMMessage, LLMResponse, LLMStreamEvent } from './types';
+export type ExpoAiKitModuleEvents = {
+    onStreamToken: (event: LLMStreamEvent) => void;
+};
+export interface ExpoAiKitNativeModule {
     isAvailable(): boolean;
     sendMessage(messages: LLMMessage[], systemPrompt: string): Promise<LLMResponse>;
-};
-declare const NativeModule: ExpoAiKitNativeModule;
-export default NativeModule;
+    startStreaming(messages: LLMMessage[], systemPrompt: string, sessionId: string): Promise<void>;
+    stopStreaming(sessionId: string): Promise<void>;
+    addListener<K extends keyof ExpoAiKitModuleEvents>(eventName: K, listener: ExpoAiKitModuleEvents[K]): EventSubscription;
+}
+declare const ExpoAiKitModule: ExpoAiKitNativeModule;
+export default ExpoAiKitModule;
 //# sourceMappingURL=ExpoAiKitModule.d.ts.map

package/build/ExpoAiKitModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoAiKitModule.d.ts","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,IAAI,OAAO,CAAC;IACvB,WAAW,CACT,QAAQ,EAAE,UAAU,EAAE,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,CAAC,CAAC;CACzB,CAAC;AAEF,QAAA,MAAM,YAAY,EAAE,qBACqC,CAAC;AAE1D,eAAe,YAAY,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,EAAE,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,MAAM,qBAAqB,GAAG;IAClC,aAAa,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;CAChD,CAAC;AAEF,MAAM,WAAW,qBAAqB;IACpC,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;IAChD,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

@@ -1,4 +1,4 @@
 import { requireNativeModule } from 'expo-modules-core';
-const NativeModule = requireNativeModule('ExpoAiKit');
-export default NativeModule;
+const ExpoAiKitModule = requireNativeModule('ExpoAiKit');
+export default ExpoAiKitModule;
 //# sourceMappingURL=ExpoAiKitModule.js.map

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;AAWxD,MAAM,YAAY,GAChB,mBAAmB,CAAwB,WAAW,CAAC,CAAC;AAE1D,eAAe,YAAY,CAAC","sourcesContent":["import { requireNativeModule } from 'expo-modules-core';\nimport { LLMMessage, LLMResponse } from './types';\n\nexport type ExpoAiKitNativeModule = {\n  isAvailable(): boolean;\n  sendMessage(\n    messages: LLMMessage[],\n    systemPrompt: string\n  ): Promise<LLMResponse>;\n};\n\nconst NativeModule: ExpoAiKitNativeModule =\n  requireNativeModule<ExpoAiKitNativeModule>('ExpoAiKit');\n\nexport default NativeModule;\n"]}
+{"version":3,"file":"ExpoAiKitModule.js","sourceRoot":"","sources":["../src/ExpoAiKitModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA0BxD,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 { LLMMessage, LLMResponse, LLMStreamEvent } from './types';\n\nexport type ExpoAiKitModuleEvents = {\n  onStreamToken: (event: LLMStreamEvent) => void;\n};\n\nexport interface ExpoAiKitNativeModule {\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  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"]}