react-native-ai-core 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Alberto Fernandez
+Copyright (c) 2026 Alberto Fernandez (@albertoroda)
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/README.md

@@ -47,7 +47,14 @@ Add to `android/gradle.properties`:
 minSdkVersion=26
 ```
 
-No additional permissions are required. The native module is auto-linked.
+The native module is auto-linked. No manual permission declarations are needed — the library's `AndroidManifest.xml` is merged automatically into your app and includes:
+
+- `FOREGROUND_SERVICE` — keeps the process alive during background generation
+- `FOREGROUND_SERVICE_DATA_SYNC` — required foreground service type (Android 14+)
+
+These permissions will appear in your compiled app manifest and may be visible in Play Store security reviews.
+
+> **Note:** Testing requires a physical Android device. The Android emulator does not support NPU hardware or the AICore system service, so the ML Kit AICore backend will not function on it. The MediaPipe backend may run in an emulator but is not officially supported or tested in that environment.
 
 ---
 
@@ -99,6 +106,90 @@ To start a fresh conversation without releasing the model:
 await AICore.resetConversation();
 ```
 
+### Structured output with runtime validation
+
+For app-internal AI features such as extraction, classification, routing, or tool orchestration, use `generateStructuredResponse(...)`.
+
+- Validates optional structured input before generation
+- Forces JSON-only output
+- Extracts JSON even if the model wraps it in extra text
+- Validates the final payload with `zod`
+- Retries automatically with a repair prompt when validation fails
+- Uses a stateless native request so it does not pollute chat conversation history
+- Supports an `AbortSignal` to cancel mid-generation
+
+```tsx
+import { z } from 'zod';
+import { generateStructuredResponse } from 'react-native-ai-core';
+
+const TicketSchema = z.object({
+  category: z.enum(['bug', 'billing', 'feature']),
+  priority: z.enum(['low', 'medium', 'high']),
+  summary: z.string(),
+  needsHuman: z.boolean(),
+});
+
+const ctrl = new AbortController();
+
+const result = await generateStructuredResponse({
+  prompt: 'Classify this support request and summarize it.',
+  input: {
+    message: 'The app crashes when I try to export a PDF invoice.',
+  },
+  output: TicketSchema,
+  signal: ctrl.signal,
+});
+
+// Cancel mid-way
+ctrl.abort();
+```
+
+Recommended for reliability on-device:
+- Keep the prompt short and task-specific
+- Keep `input` compact and validated before sending it
+- Prefer small output schemas over deeply nested ones
+- Use this API for internal app workflows, not long-form generation
+- Repair retries are bounded and prompt size is trimmed internally to avoid hitting the same context limits as chat flows
+
+There is also a concrete demo helper in [example/src/examples/structuredOutputExample.ts](example/src/examples/structuredOutputExample.ts).
+
+### Cancelling generation
+
+Both chat and structured generation can be stopped at any point.
+
+**Chat / streaming:**
+
+```tsx
+import { cancelGeneration } from 'react-native-ai-core';
+
+// Stop an ongoing generateResponse or generateResponseStream call
+await cancelGeneration();
+```
+
+For streaming, the `onComplete` callback fires normally after cancellation — `onError` is not called.
+
+**Structured output:**
+
+Pass an `AbortSignal` from an `AbortController` to `generateStructuredResponse`. When you call `ctrl.abort()` the tree-walker stops at the next field boundary and rejects with an `Error` whose `name` is `'AbortError'`.
+
+```tsx
+const ctrl = new AbortController();
+
+// Start generation
+const promise = generateStructuredResponse({ ..., signal: ctrl.signal });
+
+// Cancel from a button handler
+ctrl.abort();
+
+try {
+  await promise;
+} catch (err) {
+  if (err.name === 'AbortError') {
+    console.log('Cancelled by user');
+  }
+}
+```
+
 ---
 
 ## API Reference
@@ -120,6 +211,23 @@ Returns `true` on success. Throws on failure.
 
 ---
 
+### `cancelGeneration(): Promise<void>`
+
+Cancels the in-progress generation immediately.
+
+- For **streaming** (`generateResponseStream`): stops the token stream and fires `onComplete` (not `onError`).
+- For **blocking** (`generateResponse`): rejects the pending promise with code `CANCELLED`.
+- Safe to call even when no generation is running.
+
+```tsx
+await AICore.cancelGeneration();
+// or named export:
+import { cancelGeneration } from 'react-native-ai-core';
+await cancelGeneration();
+```
+
+---
+
 ### `generateResponse(prompt: string): Promise<string>`
 
 Generates a complete response synchronously (waits for the full output).
@@ -134,6 +242,47 @@ const response = await AICore.generateResponse('Tell me a joke');
 
 ---
 
+### `generateStructuredResponse(options): Promise<T>`
+
+Generates stateless structured JSON and validates it against a user-defined `zod` schema.
+
+```tsx
+import { z } from 'zod';
+
+const OutputSchema = z.object({
+  intent: z.enum(['search', 'reply', 'ignore']),
+  confidence: z.number(),
+});
+
+const ctrl = new AbortController();
+
+const output = await generateStructuredResponse({
+  prompt: 'Determine the next action for this message.',
+  input: { message: 'Can you send me the invoice again?' },
+  output: OutputSchema,
+  signal: ctrl.signal,
+});
+```
+
+Options:
+
+| Option | Type | Description |
+|---|---|---|
+| `prompt` | `string` | Natural language instruction |
+| `input` | `unknown` | Optional structured input object |
+| `inputSchema` | `ZodType` | Optional schema to validate `input` before generation |
+| `output` | `ZodType` | Required schema to validate the model output |
+| `strategy` | `'single' \| 'chunked'` | `'single'` (default) generates the whole JSON in one call. `'chunked'` walks the schema field-by-field — use for large or complex schemas |
+| `maxRetries` | `number` | Repair attempts when validation fails (default `2`) |
+| `maxContinuations` | `number` | Max continuation calls when JSON is truncated (default `8`) |
+| `timeoutMs` | `number` | Per-call timeout in ms (default `300000`) |
+| `onProgress` | `(field, done) => void` | Called for each field during `'chunked'` generation |
+| `signal` | `AbortSignal` | Pass a signal to cancel mid-generation. Rejects with `Error { name: 'AbortError' }` |
+
+Throws `StructuredOutputError` if valid JSON matching the schema cannot be produced after retries.
+
+---
+
 ### `generateResponseStream(prompt: string, callbacks: StreamCallbacks): () => void`
 
 Generates a response token by token via streaming. Returns a cleanup function to remove event listeners.
@@ -217,6 +366,7 @@ A ready-to-use React hook is available in the example app as a reference impleme
 - Streaming with incremental message updates
 - Conversation history reset on clear
 - Error state management
+- `stopGeneration()` — calls `cancelGeneration()` to abort the in-progress response
 
 See [`example/src/hooks/useAICore.ts`](example/src/hooks/useAICore.ts).
 
@@ -249,7 +399,7 @@ Dependency: `com.google.mediapipe:tasks-genai:0.10.22`
 - [ ] Model quantization options
 - [ ] System prompt / persona configuration
 - [ ] Token count estimation
-- [ ] Abort/cancel streaming mid-generation
+- [x] Abort/cancel streaming mid-generation
 - [ ] Web support (WebGPU / WASM)
 
 ---
@@ -266,7 +416,7 @@ Contributions, issues and feature requests are welcome.
 
 ## License
 
-MIT © [Alberto Fernandez](https://github.com/albertofernandezroda)
+MIT © [Alberto Fernandez](https://github.com/albertoroda)
 
 ---
 

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,14 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <!-- Keeps the process alive while AI generation runs in background -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+
+    <application>
+        <service
+            android:name=".InferenceService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync" />
+    </application>
+
 </manifest>