expo-local-llm 0.7.0 → 0.8.1

package/README.md

@@ -1,53 +1,33 @@
 # expo-local-llm
 
-On-device intelligence for Expo apps, using the models provided by the operating system. Generate text, extract structured data, and build streaming interfaces without distributing model weights or writing native code.
+[![npm](https://img.shields.io/npm/v/expo-local-llm)](https://www.npmjs.com/package/expo-local-llm)
+[![CI](https://github.com/GijungKim/expo-local-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/GijungKim/expo-local-llm/actions/workflows/ci.yml)
+[![Native compile](https://github.com/GijungKim/expo-local-llm/actions/workflows/native.yml/badge.svg)](https://github.com/GijungKim/expo-local-llm/actions/workflows/native.yml)
+[![License: MIT](https://img.shields.io/npm/l/expo-local-llm)](LICENSE)
 
-Wraps Apple Foundation Models (iOS 26+) and Gemini Nano (Android). Inference stays on device; any network access inside your tool handlers is controlled by your app. There is no automatic cloud fallback.
+On-device language models for Expo apps, using the models the operating system already ships: Apple Foundation Models on iOS 26+ and Gemini Nano on Android. Generate text, stream it into a component, extract typed objects and call tools, with no model weights to bundle, no API key, and no network connection needed to generate.
 
-## Platform Requirements
+Inference stays on the device. There is no cloud fallback; network access happens only inside tool handlers you write. The package has no runtime dependencies.
 
-| Platform | Requirement |
-|----------|-------------|
-| iOS | iOS 26+ with Apple Intelligence enabled. Loads on iOS 16.4+ without crashing (returns `notEligible`). Host project must target iOS 16.4+. |
-| Android | Host app uses `minSdkVersion` 26+. Inference requires a Gemini Nano–capable device; most Android devices, including most mid-range phones, report `notEligible`. Build, module loading, eligibility, and unsupported-feature handling are device-verified; generation is not yet validated on Gemini Nano hardware. |
-| Expo SDK | 52+ (peer range); the example targets SDK 57 / React Native 0.86. A peer range is not a tested compatibility matrix. |
+## At a glance
 
-**A native development build is required. Stock Expo Go cannot load this module.** A simulator can compile the module and, when the host Mac has Apple Intelligence enabled and ready, run Apple Foundation Models for real inference; physical hardware is still needed for latency and thermal measurements. See the [release verification matrix](docs/release-verification.md).
+| | iOS 26+ (Foundation Models) | Android (Gemini Nano) |
+|---|---|---|
+| Text generation and streaming | ✅ Verified on device | ⚠️ Experimental: builds and reports eligibility; generation not yet validated on Gemini Nano hardware |
+| Structured output (typed, schema-constrained) | ✅ Constrained decoding, validated in JS | ❌ Rejected explicitly |
+| Tool calling (schema-constrained arguments) | ✅ | ❌ Rejected explicitly |
+| Stable error codes | ✅ | ✅ |
+| Model download | Managed by the OS | `downloadModel()` with progress |
 
-For setup failures, unavailable models, and unsupported features, see [troubleshooting](docs/troubleshooting.md).
+Unsupported features fail with a clear error instead of degrading silently. `getCapabilities()` reports all of this at runtime, including `experimental: true` on Android. See [how this library is verified](#how-this-library-is-verified).
 
-### Xcode 27 requires scene support
-
-Apps built with the iOS 27 SDK must adopt the UIKit scene lifecycle, or UIKit stops them at launch before any JavaScript runs. Expo SDK 57 apps opt in through `expo-build-properties` (Expo `57.0.23`+, `expo-build-properties` `57.0.20`+):
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "expo-build-properties",
-        { "ios": { "deploymentTarget": "16.4", "enableSceneSupport": true } }
-      ]
-    ]
-  }
-}
-```
-
-Then regenerate and rebuild the native app. This is an app-level build setting, not something this library can enable for you.
-
-## Installation
-
-```bash
-npx expo install expo-local-llm expo-dev-client
-```
-
-This module requires **iOS 16.4+** and **Android API 26+** deployment targets. If your app targets an earlier version, raise the relevant target via [`expo-build-properties`](https://docs.expo.dev/versions/latest/sdk/build-properties/):
+## Quick start
 
 ```bash
-npx expo install expo-build-properties
+npx expo install expo-local-llm expo-dev-client expo-build-properties
 ```
 
-In `app.json`, add the plugin with the deployment target:
+Set the deployment targets the module needs in `app.json`:
 
 ```json
 {
@@ -65,43 +45,69 @@ In `app.json`, add the plugin with the deployment target:
 }
 ```
 
-Build and install your development app on a supported physical device:
+Build a development app, since stock Expo Go cannot load native modules:
 
 ```bash
 npx expo run:ios --device
-# or
-npx expo run:android --device
 ```
 
-> If your project targets an iOS version below 16.4, you'll hit `compiling for iOS X.Y, but module 'ExpoLocalLlm' has a minimum deployment target of iOS 16.4` at build time. (Apple Intelligence itself still requires iOS 26+ at runtime — the 16.4 floor is just for compilation; the module returns `notEligible` on iOS 16.4–25.)
+Then stream a response:
 
-The iOS native build requires an Xcode SDK containing Foundation Models; the SDK 57 example requires Xcode 26.4 or newer. `expo run` generates native projects if they do not exist. For projects using Continuous Native Generation, regenerate and rebuild after changing native dependencies or native app configuration. Keep custom native changes in config plugins before using `prebuild --clean`.
+```tsx
+import { Button, Text } from 'react-native';
+import { useLocalLLM } from 'expo-local-llm';
 
-EAS Build is also supported as a build workflow: use a development profile with a compatible native toolchain. Installing this package or upgrading its native implementation requires a new binary; EAS Update cannot add native code. JavaScript-only changes can use the existing binary when they remain compatible with its native API.
+export function Summary({ notes }: { notes: string }) {
+  const { availability, streamResponse, streamedText, error } = useLocalLLM({
+    instructions: 'Summarise the text in two sentences.',
+  });
 
-## Usage
+  if (!streamResponse) return <Text>{error ?? `On-device AI: ${availability}`}</Text>;
+  return (
+    <>
+      <Button title="Summarise" onPress={() => streamResponse(notes)} />
+      <Text>{streamedText}</Text>
+    </>
+  );
+}
+```
 
-### Extract typed data (iOS 26+)
+`streamResponse` is `undefined` until the model is ready, so the component shows why when it isn't: Apple Intelligence switched off, the model still downloading, or an ineligible device.
 
-For classification and extraction, use `generateObject()`. It infers the result type from your schema and validates the generated JSON before returning it:
+## Requirements
 
-```ts
-import { generateObject, getCapabilities } from 'expo-local-llm';
+| | Requirement |
+|---|---|
+| iOS | iOS 26+ with Apple Intelligence enabled to generate. The module loads on iOS 16.4+ and reports `notEligible` below 26. The host project must target iOS 16.4+, and building needs Xcode 26.4 or newer. |
+| Android | `minSdkVersion` 26+. Generation needs a Gemini Nano–capable device; most Android phones, including most mid-range ones, report `notEligible`. |
+| Expo SDK | 52+ peer range. The example app targets SDK 58 / React Native 0.88; the peer range is not a tested compatibility matrix. |
 
-const capabilities = getCapabilities();
-// Capability support and current model readiness are separate checks.
-if (capabilities.structuredOutputMode === 'constrained') {
-  const result = await generateObject('Classify: "Can we move the meeting to Friday?"', {
-    instructions: 'Classify the message by its primary intent.',
-    schema: {
-      intent: { type: 'string', enum: ['scheduling', 'question', 'other'] },
-    },
-  });
-  // result.intent: 'scheduling' | 'question' | 'other'
+A native development build is required, built locally or with EAS Build. Installing or upgrading the package needs a new binary; EAS Update cannot add native code. An iPhone simulator can run Foundation Models when the host Mac has Apple Intelligence enabled; latency and thermals still need real hardware.
+
+If the project targets an iOS version below 16.4, the build fails with `module 'ExpoLocalLlm' has a minimum deployment target of iOS 16.4`. The 16.4 floor is for compilation only; generation still needs iOS 26.
+
+For setup failures, unavailable models and unsupported features, see [troubleshooting](docs/troubleshooting.md).
+
+### Xcode 27 requires scene support
+
+Apps built with the iOS 27 SDK must adopt the UIKit scene lifecycle, or UIKit stops them at launch before any JavaScript runs. Expo SDK 58 apps adopt it by default, so there is nothing to set. Expo SDK 57 apps opt in through `expo-build-properties` (Expo `57.0.23`+, `expo-build-properties` `57.0.20`+):
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-build-properties",
+        { "ios": { "deploymentTarget": "16.4", "enableSceneSupport": true } }
+      ]
+    ]
+  }
 }
 ```
 
-Handle rejected requests in your app: supported capabilities do not imply that the model is downloaded, enabled, or ready. `generateObject()` rejects invalid JSON or schema mismatches with `StructuredOutputValidationError`; it never repairs output silently or falls back to cloud inference.
+Then regenerate and rebuild the native app. This is an app-level build setting, not something this library can enable for you.
+
+## Usage
 
 ### Stream text in a component
 
@@ -152,46 +158,37 @@ function Chat() {
 }
 ```
 
-### Tool Calling (iOS 26+)
+### One-shot generation
 
-```tsx
-import { useLocalLLM } from 'expo-local-llm';
+For a single call with no conversation history, such as classifying or rewriting one message, use `generate()`. It creates a session, responds once and releases it:
 
-function WeatherChat() {
-  const { streamResponse, streamedText, activeToolCalls, error } = useLocalLLM({
-    instructions: 'You are a helpful weather assistant.',
-    tools: [
-      {
-        name: 'getWeather',
-        description: 'Get the current weather for a city',
-        parameters: {
-          city: { type: 'string', description: 'The city name' },
-        },
-        handler: async (args) => {
-          if (typeof args.city !== 'string') throw new Error('city must be a string');
-          const res = await fetch(`https://api.example.com/weather?city=${encodeURIComponent(args.city)}`);
-          return JSON.stringify(await res.json());
-        },
-      },
-    ],
-  });
+```ts
+import { generate } from 'expo-local-llm';
 
-  return (
-    <View>
-      {activeToolCalls.length > 0 && (
-        <Text>Using {activeToolCalls.map((c) => c.toolName).join(', ')}...</Text>
-      )}
-      <Text>{streamedText}</Text>
-    </View>
-  );
-}
+const title = await generate('Suggest a short title for this note: ...', {
+  instructions: 'Reply with the title only.',
+});
 ```
 
-### Structured Output
+### Extract typed data (iOS)
 
-iOS 26+ uses Apple's constrained decoding (`DynamicGenerationSchema`) for schema-driven output.
-Successful generation produces structured JSON; requests can still fail or be refused.
-Android structured output is unsupported and rejected explicitly, rather than silently generating ordinary text.
+`generateObject()` infers the result type from the schema, constrains the model's decoding to it, and validates the JSON before returning it:
+
+```ts
+import { generateObject, getCapabilities } from 'expo-local-llm';
+
+if (getCapabilities().structuredOutputMode === 'constrained') {
+  const result = await generateObject('Classify: "Can we move the meeting to Friday?"', {
+    instructions: 'Classify the message by its primary intent.',
+    schema: {
+      intent: { type: 'string', enum: ['scheduling', 'question', 'other'] },
+    },
+  });
+  // result.intent: 'scheduling' | 'question' | 'other'
+}
+```
+
+A supported capability does not mean the model is ready, so handle rejected calls. A mismatch rejects with `StructuredOutputValidationError`; output is never repaired silently.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/GijungKim/expo-local-llm/main/docs/structured-output.png" alt="Structured output demo — recipe JSON with constrained 'difficulty' enum on iPhone" width="320" />
@@ -199,77 +196,135 @@ Android structured output is unsupported and rejected explicitly, rather than si
 
 *Real device output: the model fills in a recipe schema with `difficulty` constrained to `easy | medium | hard`. The streaming demo lives at `example/App.tsx`.*
 
+### Structured output in the hook
+
+In JSON mode the hook streams a partial object, then publishes the validated result:
+
 ```tsx
-const { respond } = useLocalLLM({
+const { streamResponse, streamedObject, completedObject } = useLocalLLM({
   responseFormat: 'json',
   schema: {
     name: { type: 'string', description: 'Recipe name' },
-    ingredients: {
-      type: 'array',
-      items: { type: 'string' },
-      description: 'List of ingredients',
-    },
-    steps: {
-      type: 'array',
-      items: { type: 'string' },
-      description: 'Cooking steps',
-    },
-    difficulty: {
-      type: 'string',
-      enum: ['easy', 'medium', 'hard'],
-    },
+    ingredients: { type: 'array', items: { type: 'string' } },
+    difficulty: { type: 'string', enum: ['easy', 'medium', 'hard'] },
   },
 });
 
-if (respond) {
-  const recipe = JSON.parse(await respond('Give me a pasta recipe'));
-}
+await streamResponse?.('Give me a pasta recipe');
+// streamedObject: fields appear as the model writes them (every field optional)
+// completedObject: { name: string; ingredients: string[]; difficulty: 'easy' | 'medium' | 'hard' } | null
 ```
 
-For one-shot structured calls (classification, extraction) where you don't want conversation
-history accumulating between calls, use `generate()` instead of a session:
+`respond` and `streamResponse` validate the final JSON and reject with `StructuredOutputValidationError` (`ERR_STRUCTURED_OUTPUT_INVALID`) if it does not match. A cancelled stream keeps its partial `streamedObject` and leaves `completedObject` null. `streamedJSON` holds the raw partial JSON.
 
-```ts
-import { generate } from 'expo-local-llm';
-
-const json = await generate('Classify this message: "how was my sleep?"', {
-  instructions: 'Classify what the message asks for.',
-  responseFormat: 'json',
-  schema: { topic: { type: 'string', enum: ['sleep', 'heart', 'none'] } },
-});
-```
+Schemas are validated before they reach native code; a malformed one throws `SchemaInvalidError` with per-field paths. Call `validateSchema()` yourself when building schemas at runtime.
 
-Streaming with a schema yields progressively-filled snapshots via `streamedJSON` (the current
-partial as a JSON string) and `streamedObject` (the parsed value):
+### Tool calling (iOS)
 
 ```tsx
-const { streamResponse, streamedObject } = useLocalLLM({
-  responseFormat: 'json',
-  schema: { /* ... */ },
+import { Text, View } from 'react-native';
+import { defineTool, useLocalLLM } from 'expo-local-llm';
+
+const getWeather = defineTool({
+  name: 'getWeather',
+  description: 'Get the current weather for a city',
+  parameters: {
+    city: { type: 'string', description: 'The city name' },
+    unit: { type: 'string', description: 'Temperature unit', enum: ['celsius', 'fahrenheit'] },
+  },
+  // Typed from `parameters`: city is a string, unit is 'celsius' | 'fahrenheit'.
+  handler: async ({ city, unit }) => {
+    const res = await fetch(
+      `https://api.example.com/weather?city=${encodeURIComponent(city)}&unit=${unit}`
+    );
+    return JSON.stringify(await res.json());
+  },
 });
 
-await streamResponse?.('Give me a pasta recipe');
-// streamedObject updates as the model fills in fields
+function WeatherChat() {
+  const { streamResponse, streamedText, activeToolCalls, error } = useLocalLLM({
+    instructions: 'You are a helpful weather assistant.',
+    tools: [getWeather],
+  });
+
+  return (
+    <View>
+      {activeToolCalls.length > 0 && (
+        <Text>Using {activeToolCalls.map((c) => c.toolName).join(', ')}...</Text>
+      )}
+      <Text>{streamedText}</Text>
+    </View>
+  );
+}
 ```
 
-#### Schema validation
+`defineTool()` infers the handler's argument types from `parameters`; it returns the tool unchanged. Tools written inline in `tools` still work, with arguments typed as `Record<string, string | number | boolean>`.
+
+Tool arguments use the same constrained decoding as structured output: the model fills in a schema built from `parameters`, so every declared parameter arrives with its declared type and any `enum` is respected. Validate values whose meaning matters (ranges, formats) as you would any input. If a handler throws or times out, the turn rejects with `ERR_TOOL_FAILED`.
+
+### Handle errors
+
+Generation failures and the library's own checks carry a stable `code` (see [Error codes](#error-codes)), so you can respond to *why* generation failed rather than parsing OS messages. The hook exposes it as `errorCode`; for a caught error, use `getLocalLLMErrorCode()`.
+
+Foundation Models has a small context window, so a long conversation eventually fails with `ERR_CONTEXT_WINDOW_EXCEEDED`. On iOS the library never drops turns to make room (Android replays only the last 10 exchanges); decide what your app should do:
 
-`createLLMSession` validates the schema before crossing to native and throws `SchemaInvalidError`
-with per-field paths if anything is malformed (missing `items`, `enum` on the wrong type, unknown
-`type`, etc.). You can also call `validateSchema()` directly when building schemas at runtime:
+```tsx
+const { errorCode, reset } = useLocalLLM({ instructions: 'You are a helpful assistant.' });
+
+if (errorCode === 'ERR_CONTEXT_WINDOW_EXCEEDED') {
+  // Start over, or create a new session seeded with a summary of the chat.
+  reset?.();
+}
+if (errorCode === 'ERR_GUARDRAIL_VIOLATION' || errorCode === 'ERR_REFUSAL') {
+  // The model declined; ask the person to rephrase.
+}
+```
 
 ```ts
-import { validateSchema } from 'expo-local-llm';
+import { generate, getLocalLLMErrorCode } from 'expo-local-llm';
 
-const result = validateSchema(mySchema);
-if (!result.ok) {
-  for (const err of result.errors) {
-    console.warn(`${err.path}: ${err.message}`);
+try {
+  await generate('Summarise my notes');
+} catch (error) {
+  if (error instanceof Error && getLocalLLMErrorCode(error) === 'ERR_RATE_LIMITED') {
+    // The system is throttling on-device generation; retry later.
   }
 }
 ```
 
-## API
+#### Using with Effect
+
+The library has no runtime dependencies, so it does not ship [Effect](https://effect.website) bindings. The error codes map directly onto a tagged error, so a wrapper takes a few lines:
+
+```ts
+import { Data, Effect } from 'effect';
+import { generate, getLocalLLMErrorCode, type LocalLLMErrorCode } from 'expo-local-llm';
+
+class LocalLLMFailure extends Data.TaggedError('LocalLLMFailure')<{
+  code: LocalLLMErrorCode | null;
+  message: string;
+}> {}
+
+const generateEffect = (prompt: string) =>
+  Effect.tryPromise({
+    try: () => generate(prompt),
+    catch: (error) =>
+      new LocalLLMFailure({
+        code: error instanceof Error ? getLocalLLMErrorCode(error) : null,
+        message: error instanceof Error ? error.message : 'Generation failed',
+      }),
+  });
+
+// Recover from one failure by its code.
+const answer = generateEffect('Summarise my notes').pipe(
+  Effect.catchIf(
+    (failure) => failure.code === 'ERR_RATE_LIMITED',
+    () => Effect.succeed('Try again in a moment.'),
+  ),
+);
+```
+
+## API reference
 
 ### `getCapabilities()`
 
@@ -277,7 +332,7 @@ Reports which features the loaded platform integration implements. Use this to d
 
 The function does not download models, start inference, or opt the app into a cloud service.
 
-Returns `platform`, `backend`, `status`, boolean `text`/`streaming`/`tools`/`structuredOutput` flags, and `structuredOutputMode` (`'constrained'` or `'unsupported'`).
+Returns `platform`, `backend`, `status`, boolean `text`/`streaming`/`tools`/`structuredOutput` flags, `structuredOutputMode` (`'constrained'` or `'unsupported'`), and `experimental`. `experimental` is `true` on Android until Gemini Nano generation has been validated on real hardware; gate production features on it if you need verified behavior.
 
 Capability `status` is `'available'`, `'moduleUnavailable'`, `'unsupportedOS'`, or `'unsupportedPlatform'`. Here `'available'` means the integration is supported; use the hook's `availability` for current model readiness.
 
@@ -307,7 +362,7 @@ if (!diagnostics.available) {
 | `tools` | `ToolDefinition[]` | Tools the model can invoke (iOS 26+ only) |
 | `toolTimeout` | `number` | Seconds before an unresolved tool call times out (default 30) |
 | `responseFormat` | `"text" \| "json"` | Set to `"json"` for structured JSON output; requires `schema` |
-| `schema` | `Schema` | Schema for structured output (used with `responseFormat: "json"`) — see Structured Output section |
+| `schema` | `Schema` | Schema for structured output (used with `responseFormat: "json"`); see [Structured output in the hook](#structured-output-in-the-hook) |
 | `includeSchemaInPrompt` | `boolean` | iOS 26+: include the schema definition in the prompt. Default `true`. Set `false` when you've front-loaded few-shot examples. |
 
 #### Returns
@@ -318,9 +373,11 @@ if (!diagnostics.available) {
 | `isGenerating` | `boolean` | Whether a generation is in progress |
 | `streamedText` | `string` | Accumulated text from current text stream |
 | `streamedJSON` | `string` | Current partial JSON from a schema-driven stream |
-| `streamedObject` | `unknown` | Parsed value of `streamedJSON` (or `null` before any partial) |
+| `streamedObject` | `DeepPartial<InferSchema<schema>> \| null` | Parsed value of `streamedJSON` (or `null` before any partial). Fields may be missing until generated. |
+| `completedObject` | `InferSchema<schema> \| null` | The finished JSON-mode response, validated against the schema. `null` while generating and after a cancel. |
 | `downloadProgress` | `number \| null` | Download progress 0-1 (Android only) |
 | `error` | `string \| null` | Last error message |
+| `errorCode` | `LocalLLMErrorCode \| null` | Code of the last error (see [Error codes](#error-codes)); `null` when there is none or it came from your own code |
 | `activeToolCalls` | `ActiveToolCall[]` | In-flight tool calls (`{ callId, toolName }`) |
 | `respond` | `(prompt: string) => Promise<string>` | Non-streaming generation. `undefined` when unavailable. |
 | `session` | `LLMSession \| null` | The native session object. `null` before creation or when unavailable. Use the hook's generation methods for hook-managed state and tool dispatch. |
@@ -363,33 +420,73 @@ try {
 
 Low-level `respond(prompt, requestId?)` and `streamResponse(prompt, requestId?)` accept an optional request identifier. Generation events carry `requestId` so consumers can discard queued events from cancelled or reset requests. Omit it to let native code generate an identifier; `useLocalLLM()` manages identifiers and filtering automatically. Use a distinct identifier for each invocation.
 
+### Error codes
+
+Errors thrown or rejected by the library, and `streamError` events, carry one of these codes. Messages come from the OS and may change; codes do not.
+
+On iOS 27, Foundation Models reports some failures with error types that only the iOS 27 SDK can name. Build with Xcode 27 to classify all of them. An app built with Xcode 26.4 still gets codes for the iOS 26 error types, but reports the newer ones as `ERR_GENERATION_FAILED`.
+
+| Code | Meaning |
+|------|---------|
+| `ERR_CONTEXT_WINDOW_EXCEEDED` | The conversation no longer fits the model's context window. Reset or start a new session. |
+| `ERR_GUARDRAIL_VIOLATION` | Safety guardrails blocked the prompt or response. |
+| `ERR_REFUSAL` | The model declined to answer. |
+| `ERR_UNSUPPORTED_LANGUAGE` | The prompt language or device locale is not supported. |
+| `ERR_UNSUPPORTED_REQUEST` | The request uses a capability the model or helper cannot honour. |
+| `ERR_RATE_LIMITED` | The system is throttling generation (quota, background use, load). Retry later. |
+| `ERR_MODEL_UNAVAILABLE` | Model assets are missing or the device cannot run the model right now. |
+| `ERR_DECODING_FAILED` | Output could not be decoded into the requested structure. |
+| `ERR_TIMEOUT` | Generation exceeded the system's time limit (iOS 27+). |
+| `ERR_TOOL_FAILED` | A tool handler threw or timed out, or the hook had no handler for the tool. |
+| `ERR_GENERATION_FAILED` | Any other generation failure. |
+| `ERR_SESSION_BUSY` | The session already has a generation in progress. |
+| `ERR_SESSION_INVALID` | The session was released or is not ready. |
+| `ERR_NOT_SUPPORTED` | On-device generation is not available on this OS version. |
+| `ERR_RESPONSE_FORMAT_NOT_SUPPORTED` | Structured output is not supported on this platform. |
+| `ERR_TOOL_NOT_SUPPORTED` | Tool calling is not supported on this platform. |
+| `ERR_MODEL_DOWNLOAD_FAILED` | Android: downloading Gemini Nano failed. |
+| `ERR_SCHEMA_INVALID` | A schema is malformed (`SchemaInvalidError`). |
+| `ERR_STRUCTURED_OUTPUT_INVALID` | Generated JSON did not match the schema (`StructuredOutputValidationError`). |
+| `ERR_UNAVAILABLE` | The native module is missing from this build. |
+
 ### `ModelAvailability`
 
 `'available' | 'notEnabled' | 'notReady' | 'notEligible' | 'downloadRequired' | 'downloading' | 'unknown' | 'moduleUnavailable'`
 
 Android readiness is checked asynchronously and may initially be `unknown`. Prefer `useLocalLLM()` for reactive readiness; low-level consumers should listen for the module's `availabilityChange` event instead of treating the first synchronous status read as final.
 
-## Platform Asymmetries
+### `validateSchema(schema)` and `validateStructuredOutput(value, schema)`
+
+`validateSchema` checks a schema and returns `{ ok: true }` or `{ ok: false, errors }` with field paths (missing `items`, `enum` on the wrong type, unknown `type`). `validateStructuredOutput` checks an already-parsed value against a valid schema the same way.
+
+## Platform differences and limitations
 
 | Concern | iOS | Android |
-|---------|-----|---------|
-| System instructions | Native `LanguageModelSession(instructions:)` | Prepended in prompt text |
-| Token limits | OS/model-dependent | SDK/model-dependent |
-| Model availability | Built-in to OS | May need download |
-| Session history | Native session maintains it | `ConversationHistory` class |
-| Streaming | `AsyncSequence` | Kotlin `Flow` |
+|---|---|---|
+| System instructions | Native `LanguageModelSession(instructions:)` | Prepended to the prompt |
+| Conversation history | Kept by the native session | Replayed in the prompt: the last 10 exchanges, with role markers in conversation text neutralised |
+| Model availability | Built into the OS | May need `downloadModel()` |
+| Token limits | OS and model dependent | SDK and model dependent |
+
+- **Context window.** Neither platform trims history to fit the model's context; Android only caps it at 10 exchanges. iOS rejects with `ERR_CONTEXT_WINDOW_EXCEEDED`; call `reset()` or start a new session.
+- **One generation per session.** Overlapping requests reject with `ERR_SESSION_BUSY`. After cancelling, await the original promise before starting another request. Use separate sessions for independent conversations; events belong to their session.
+- **Guardrails.** Apple's model refuses some categories of prompt, such as interpreting personal health data. A refusal arrives as `ERR_GUARDRAIL_VIOLATION` or `ERR_REFUSAL`.
+- **Android is experimental.** The Gemini Nano SDK is in beta and its API may change. Structured output and tools are rejected at session creation.
+- **Readiness gates generation.** `respond` and `streamResponse` need a session and `availability === 'available'`; cancelling and resetting work whenever a session exists.
 
-## Known Limitations
+## How this library is verified
 
-- Events belong to their session. Use a separate session for independent conversations.
-- A session accepts one generation at a time; overlapping requests reject. After cancellation, await the original generation promise before starting another request.
-- **Android**: Gemini Nano SDK is in beta and its API surface may change. Build, module loading, eligibility, and unsupported-feature rejection are device-verified; generation has not been validated on Gemini Nano hardware.
-- **iOS**: Apple's Foundation Model may refuse certain categories of prompts (e.g. personal health data interpretation) due to built-in safety guardrails.
-- Generation methods (`respond`, `streamResponse`) require a session and `availability === 'available'`. Cancellation remains available while a session exists.
-- Tool calling is iOS 26+ only. Android will throw at session creation if tools are passed.
-- Structured output on Android is unsupported. iOS 26+ uses constrained decoding via `DynamicGenerationSchema`.
+- **Every pull request:** lint, unit tests, type-level tests, and a compile of a freshly generated Expo SDK 58 app on both platforms, with the iOS build using Xcode 26.4, the oldest supported toolchain. Android also runs JVM tests of the prompt assembly and error mapping.
+- **Against the real model:** [`tools/model-check`](tools/model-check/README.md) runs the library's Foundation Models code on a Mac with Apple Intelligence: constrained tool arguments, error-code mapping and schema-constrained output. The release checklist runs it before each release.
+- **On devices:** the [release verification record](docs/release-verification.md) lists what has been checked on an iPhone 15 Pro, a simulator and a Galaxy A17, and leaves untested scenarios marked as pending rather than assumed.
 
-## Why an Expo module?
+## Choosing this library
+
+Choose `expo-local-llm` for a small, Expo-first API around system-provided language models: short text generation, classification, extraction, and streaming interfaces on supported devices. You do not select or distribute model weights.
+
+If you need downloadable models, embeddings, speech, or an AI SDK provider interface, evaluate a broader runtime such as [React Native AI](https://github.com/callstackincubator/ai). Check its current provider documentation for platform requirements. This library does not implement those capabilities or automatically route requests to a cloud model.
+
+### Why an Expo module?
 
 The [Expo Modules API](https://docs.expo.dev/modules/overview/) fits OS-provided AI APIs well:
 
@@ -402,16 +499,11 @@ Expo does not improve model quality or remove device eligibility requirements. I
 
 Existing React Native apps can use this library after [installing Expo Modules support](https://docs.expo.dev/bare/installing-expo-modules/). Expo-first does not mean Expo-only.
 
-## Choosing this library
-
-Choose `expo-local-llm` for a small, Expo-first API around system-provided language models: short text generation, classification, extraction, and streaming interfaces on supported devices. You do not select or distribute model weights.
-
-If you need downloadable models, embeddings, speech, or an AI SDK provider interface, evaluate a broader runtime such as [React Native AI](https://github.com/callstackincubator/ai). Check its current provider documentation for platform requirements. This library does not implement those capabilities or automatically route requests to a cloud model.
-
-## Built with expo-local-llm
+## Used by
 
-- [PulseID](https://apps.apple.com/us/app/pulseid-heart-rate-camera/id6754331991) — Heart rate camera
-- [Teamfit Tactics](https://apps.apple.com/us/app/teamfit-tactics-tft-fitness/id6757195493) — TFT fitness
+- [Angular Native](https://github.com/ng-native/ng-native): wraps it as the `LanguageModel` service in `@ng-native/expo`
+- [PulseID](https://apps.apple.com/us/app/pulseid-heart-rate-camera/id6754331991): heart rate camera
+- [Teamfit Tactics](https://apps.apple.com/us/app/teamfit-tactics-tft-fitness/id6757195493): TFT fitness
 
 *Using this library? Open a PR to add your app.*
 

package/android/build/intermediates/incremental/mergeDebugAssets/merger.xml

@@ -1,2 +1,2 @@
 <?xml version="1.0" encoding="utf-8"?>
-<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/swoleknee/chingu/expo-local-llm/example/node_modules/expo-local-llm/android/src/main/assets"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/swoleknee/chingu/expo-local-llm/example/node_modules/expo-local-llm/android/src/debug/assets"/></dataSet><dataSet config="generated" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/swoleknee/chingu/expo-local-llm/example/node_modules/expo-local-llm/android/build/intermediates/shader_assets/debug/compileDebugShaders/out"/></dataSet></merger>
+<merger version="3"><dataSet config="main" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/swoleknee/chingu/expo-local-llm/example/node_modules/expo-local-llm/android/src/main/assets"/></dataSet><dataSet config="debug" ignore_pattern="!.svn:!.git:!.ds_store:!*.scc:.*:&lt;dir>_*:!CVS:!thumbs.db:!picasa.ini:!*~"><source path="/Users/swoleknee/chingu/expo-local-llm/example/node_modules/expo-local-llm/android/src/debug/assets"/></dataSet></merger>

package/android/build.gradle

@@ -5,7 +5,8 @@ plugins {
 }
 
 group = 'expo.modules.localllm'
-version = '0.1.0'
+// Single source of truth: the npm package version.
+version = new groovy.json.JsonSlurper().parse(file('../package.json')).version
 
 android {
   namespace "expo.modules.localllm"
@@ -14,7 +15,8 @@ android {
   defaultConfig {
     minSdk 26
     versionCode 1
-    versionName "0.1.0"
+    versionName project.version
+    consumerProguardFiles 'proguard-rules.pro'
   }
 
   compileOptions {

package/android/proguard-rules.pro

@@ -0,0 +1,8 @@
+# Consumer rules applied to apps that minify release builds (the default from
+# Expo SDK 58). ML Kit discovers its components by instantiating the
+# registrars named in its manifest metadata through reflection. ML Kit's own
+# rules do not keep their no-argument constructors, so R8 removes them and
+# ML Kit never initialises: availability checks then fail on every device.
+-keep class * implements com.google.firebase.components.ComponentRegistrar {
+  <init>();
+}

package/android/src/main/java/expo/modules/localllm/ConversationHistory.kt

@@ -3,12 +3,21 @@ package expo.modules.localllm
 class ConversationHistory(private val systemInstructions: String?) {
   private data class Message(val role: String, val content: String)
 
+  private companion object {
+    // Gemini Nano receives one flat prompt, so roles exist only as these
+    // markers. Neutralise them in conversation text so a message cannot
+    // impersonate the system instructions or another turn.
+    val roleMarker = Regex("""\[\s*(system|user|assistant)\s*]""", RegexOption.IGNORE_CASE)
+
+    fun neutralise(content: String): String = content.replace(roleMarker, "($1)")
+  }
+
   private val messages = mutableListOf<Message>()
   private val maxExchanges = 10
 
   fun addExchange(user: String, assistant: String) {
-    messages.add(Message("User", user))
-    messages.add(Message("Assistant", assistant))
+    messages.add(Message("User", neutralise(user)))
+    messages.add(Message("Assistant", neutralise(assistant)))
     trimHistory()
   }
 
@@ -25,7 +34,7 @@ class ConversationHistory(private val systemInstructions: String?) {
     for (msg in messages) {
       sb.appendLine("[${msg.role}] ${msg.content}")
     }
-    sb.appendLine("[User] $addingUserMessage")
+    sb.appendLine("[User] ${neutralise(addingUserMessage)}")
     return sb.toString().trim()
   }