expo-ai-kit 0.5.0 → 0.7.0

package/README.md

@@ -1,13 +1,14 @@
 # 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)
 
 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.
+— with streaming, structured output, tool calling, cancellation, and runtime model switching,
+all on-device.
 
 ## Install
 
@@ -17,7 +18,7 @@ npx expo install expo-ai-kit
 
 Bare RN: run `npx pod-install`. Android needs `minSdkVersion 26`. Requires Expo SDK 54+.
 
-## Quick start
+## Text
 
 ```tsx
 import { isAvailable, sendMessage, streamMessage } from 'expo-ai-kit';
@@ -36,6 +37,67 @@ if (await isAvailable()) {
 `messages` is `{ role: 'system' | 'user' | 'assistant'; content: string }[]`. On-device
 models are stateless — pass the full history each call.
 
+## Structured output
+
+Get a typed object back instead of a string. Pass a JSON Schema; expo-ai-kit prompts the
+model, extracts the JSON (tolerating prose and code fences), validates it against the
+schema, and repairs on a mismatch. Works on every backend.
+
+```tsx
+import { generateObject } from 'expo-ai-kit';
+
+type Recipe = { title: string; minutes: number; ingredients: string[] };
+
+const { object } = await generateObject<Recipe>(
+  [{ role: 'user', content: 'A quick weeknight pasta.' }],
+  {
+    type: 'object',
+    properties: {
+      title: { type: 'string' },
+      minutes: { type: 'integer' },
+      ingredients: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['title', 'minutes', 'ingredients'],
+  },
+);
+
+object.title; // typed Recipe
+```
+
+Throws `INFERENCE_FAILED` if the model can't produce schema-valid JSON after the repair
+attempts (`maxRepairAttempts`, default 2). Keep schemas small and shallow for best results.
+
+## Tool calling
+
+Let the model call functions you provide. It proposes a call, expo-ai-kit validates the
+arguments against the tool's schema, runs your `execute`, feeds the result back, and loops
+until it produces an answer (bounded by `maxSteps`, default 5). Works on every backend.
+
+```tsx
+import { generateText } from 'expo-ai-kit';
+
+const { text } = await generateText(
+  [{ role: 'user', content: 'What should I wear in Paris today?' }],
+  {
+    tools: {
+      getWeather: {
+        description: 'Get the current weather for a city.',
+        parameters: {
+          type: 'object',
+          properties: { city: { type: 'string' } },
+          required: ['city'],
+        },
+        execute: async ({ city }: { city: string }) => fetchWeather(city),
+      },
+    },
+  },
+);
+```
+
+Omit a tool's `execute` to gate it yourself: the loop stops with `finishReason: 'tool-calls'`
+and hands you the proposed call to confirm before running. Keep tool sets small and parameter
+schemas flat — on-device models pick tools more reliably that way.
+
 ## Downloadable Gemma 4
 
 ```tsx
@@ -45,13 +107,13 @@ const best = await getRecommendedModel();          // E4B on high-RAM phones, el
 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
+  // sendMessage / streamMessage / generateObject / generateText now use it; unloadModel() reverts to the OS model
 }
 ```
 
 ## API
 
-Inference: `isAvailable`, `sendMessage`, `streamMessage`.
+Inference: `isAvailable`, `sendMessage`, `streamMessage`, `generateObject`, `generateText`.
 Models: `getBuiltInModels`, `getDownloadableModels`, `getRecommendedModel`,
 `downloadModel`, `cancelDownload`, `deleteModel`, `setModel`, `unloadModel`, `getActiveModel`.
 

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { LLMMessage, LLMSendOptions, LLMResponse, LLMStreamOptions, LLMStreamCallback, LLMStreamHandle, BuiltInModel, DownloadableModel, SetModelOptions } from './types';
+import { LLMMessage, LLMSendOptions, LLMResponse, LLMStreamOptions, LLMStreamCallback, LLMStreamHandle, BuiltInModel, DownloadableModel, SetModelOptions, JSONSchema, GenerateObjectOptions, GenerateObjectResult, GenerateTextOptions, GenerateTextResult } from './types';
 export * from './types';
 export * from './models';
 /**
@@ -76,6 +76,104 @@ export declare function sendMessage(messages: LLMMessage[], options?: LLMSendOpt
  * ```
  */
 export declare function streamMessage(messages: LLMMessage[], onToken: LLMStreamCallback, options?: LLMStreamOptions): LLMStreamHandle;
+/**
+ * Generate a typed object instead of free text.
+ *
+ * You describe the shape you want with a JSON Schema. expo-ai-kit appends a
+ * strict instruction to the system prompt, runs the on-device model, extracts
+ * the JSON from its output (tolerating prose and ```json fences), validates it
+ * against the schema, and — on a parse error or schema mismatch — feeds the
+ * error back and re-prompts up to `maxRepairAttempts` times.
+ *
+ * Works on every backend (Apple Foundation Models, ML Kit, Gemma) because it is
+ * orchestrated over {@link sendMessage}: it honors the same single-flight guard,
+ * `AbortSignal`, and `systemPrompt` semantics. Keep schemas small and shallow —
+ * on-device models follow flat shapes far more reliably than deeply nested ones.
+ *
+ * @param messages - The conversation, same shape as {@link sendMessage}.
+ * @param schema - A JSON Schema describing the desired result.
+ * @param options - Optional settings (systemPrompt, signal, maxRepairAttempts).
+ * @returns `{ object, text }` — the validated value and the raw output.
+ * @throws {ModelError} INFERENCE_FAILED if no schema-valid JSON is produced
+ *   after the repair attempts. Also propagates INFERENCE_BUSY / INFERENCE_CANCELLED
+ *   from the underlying generation.
+ *
+ * @example
+ * ```ts
+ * type Recipe = { title: string; minutes: number; ingredients: string[] };
+ *
+ * const { object } = await generateObject<Recipe>(
+ *   [{ role: 'user', content: 'A quick weeknight pasta.' }],
+ *   {
+ *     type: 'object',
+ *     properties: {
+ *       title: { type: 'string' },
+ *       minutes: { type: 'integer' },
+ *       ingredients: { type: 'array', items: { type: 'string' } },
+ *     },
+ *     required: ['title', 'minutes', 'ingredients'],
+ *   },
+ * );
+ * object.title; // typed Recipe
+ * ```
+ */
+export declare function generateObject<T = unknown>(messages: LLMMessage[], schema: JSONSchema, options?: GenerateObjectOptions): Promise<GenerateObjectResult<T>>;
+/**
+ * Generate text, optionally letting the model call tools (functions) you provide.
+ *
+ * Unlike {@link generateObject} (where the JSON *is* the answer), tool calling is
+ * a loop: the model proposes a call, expo-ai-kit validates the arguments against
+ * the tool's `parameters`, runs your `execute`, feeds the result back, and lets
+ * the model continue — until it produces a plain-text answer or the `maxSteps`
+ * budget is reached. With no `tools`, this is a single text generation.
+ *
+ * Orchestrated in JS over {@link sendMessage}, so it works on every backend
+ * (Apple Foundation Models, ML Kit, Gemma) and inherits the single-flight guard,
+ * `AbortSignal`, and `systemPrompt` semantics. On-device models are imperfect at
+ * tool selection, so the loop is defensive: malformed calls, unknown tool names,
+ * and schema-invalid arguments are re-prompted up to `maxRepairAttempts` times,
+ * and a tool with no `execute` stops the loop and returns the proposed call for
+ * you to gate. Keep tool sets small and `parameters` flat for best reliability.
+ *
+ * @param messages - The conversation, same shape as {@link sendMessage}.
+ * @param options - Tools, `maxSteps`, `systemPrompt`, `signal`, `maxRepairAttempts`.
+ * @returns `{ text, steps, toolCalls, toolResults, finishReason }`.
+ * @throws {ModelError} INFERENCE_FAILED if the model keeps proposing an unknown
+ *   tool or schema-invalid arguments after the repair attempts. Also propagates
+ *   INFERENCE_BUSY / INFERENCE_CANCELLED from the underlying generation.
+ *
+ * @example
+ * ```ts
+ * const { text } = await generateText(
+ *   [{ role: 'user', content: 'What should I wear in Paris today?' }],
+ *   {
+ *     tools: {
+ *       getWeather: {
+ *         description: 'Get the current weather for a city.',
+ *         parameters: {
+ *           type: 'object',
+ *           properties: { city: { type: 'string' } },
+ *           required: ['city'],
+ *         },
+ *         execute: async ({ city }: { city: string }) => fetchWeather(city),
+ *       },
+ *     },
+ *   },
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Human-in-the-loop: omit `execute` to gate the call yourself.
+ * const res = await generateText(messages, {
+ *   tools: { deleteAccount: { description: '…', parameters: { type: 'object' } } },
+ * });
+ * if (res.finishReason === 'tool-calls') {
+ *   const call = res.toolCalls[0]; // confirm with the user before running
+ * }
+ * ```
+ */
+export declare function generateText(messages: LLMMessage[], options?: GenerateTextOptions): Promise<GenerateTextResult>;
 /**
  * Get all built-in models available on the current platform.
  *

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,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"}
+{"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,EACf,UAAU,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAInB,MAAM,SAAS,CAAC;AAiBjB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AA0HzB;;;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;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,cAAc,CAAC,CAAC,GAAG,OAAO,EAC9C,QAAQ,EAAE,UAAU,EAAE,EACtB,MAAM,EAAE,UAAU,EAClB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAoElC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,UAAU,EAAE,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAmJ7B;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"}

package/build/index.js

@@ -1,10 +1,13 @@
 import ExpoAiKitModule from './ExpoAiKitModule';
 import { Platform } from 'react-native';
 import { ModelError, } from './types';
+import { buildSchemaInstruction, buildSchemaRepair, extractJson, validateAgainstSchema, REPAIR_INVALID_JSON, } from './structured';
+import { buildToolInstruction, parseToolCall, buildUnknownToolRepair, buildToolArgsRepair, formatToolResult, } from './tools';
 import { MODEL_REGISTRY, getRegistryEntry } from './models';
 export * from './types';
 export * from './models';
 const DEFAULT_SYSTEM_PROMPT = 'You are a helpful, friendly assistant. Answer the user directly and concisely.';
+const DEFAULT_OBJECT_SYSTEM_PROMPT = 'You output structured data as JSON. Follow the provided JSON Schema exactly.';
 let streamIdCounter = 0;
 function generateSessionId() {
     return `gen_${Date.now()}_${++streamIdCounter}`;
@@ -318,6 +321,282 @@ export function streamMessage(messages, onToken, options) {
     };
     return { promise, stop };
 }
+/**
+ * Generate a typed object instead of free text.
+ *
+ * You describe the shape you want with a JSON Schema. expo-ai-kit appends a
+ * strict instruction to the system prompt, runs the on-device model, extracts
+ * the JSON from its output (tolerating prose and ```json fences), validates it
+ * against the schema, and — on a parse error or schema mismatch — feeds the
+ * error back and re-prompts up to `maxRepairAttempts` times.
+ *
+ * Works on every backend (Apple Foundation Models, ML Kit, Gemma) because it is
+ * orchestrated over {@link sendMessage}: it honors the same single-flight guard,
+ * `AbortSignal`, and `systemPrompt` semantics. Keep schemas small and shallow —
+ * on-device models follow flat shapes far more reliably than deeply nested ones.
+ *
+ * @param messages - The conversation, same shape as {@link sendMessage}.
+ * @param schema - A JSON Schema describing the desired result.
+ * @param options - Optional settings (systemPrompt, signal, maxRepairAttempts).
+ * @returns `{ object, text }` — the validated value and the raw output.
+ * @throws {ModelError} INFERENCE_FAILED if no schema-valid JSON is produced
+ *   after the repair attempts. Also propagates INFERENCE_BUSY / INFERENCE_CANCELLED
+ *   from the underlying generation.
+ *
+ * @example
+ * ```ts
+ * type Recipe = { title: string; minutes: number; ingredients: string[] };
+ *
+ * const { object } = await generateObject<Recipe>(
+ *   [{ role: 'user', content: 'A quick weeknight pasta.' }],
+ *   {
+ *     type: 'object',
+ *     properties: {
+ *       title: { type: 'string' },
+ *       minutes: { type: 'integer' },
+ *       ingredients: { type: 'array', items: { type: 'string' } },
+ *     },
+ *     required: ['title', 'minutes', 'ingredients'],
+ *   },
+ * );
+ * object.title; // typed Recipe
+ * ```
+ */
+export async function generateObject(messages, schema, options) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
+        throw new ModelError('DEVICE_NOT_SUPPORTED', '', 'generateObject is only available on iOS and Android');
+    }
+    if (!messages || messages.length === 0) {
+        throw new Error('messages array cannot be empty');
+    }
+    if (!schema || typeof schema !== 'object') {
+        throw new Error('schema must be a JSON Schema object');
+    }
+    const maxRepairAttempts = Math.max(0, options?.maxRepairAttempts ?? 2);
+    const instruction = buildSchemaInstruction(schema);
+    // Inject the schema instruction. If the caller supplied a system message we
+    // append to it (sendMessage reads system from the array); otherwise we carry
+    // the instruction via the systemPrompt option, which sendMessage applies when
+    // the array has no system message — including on the repair turns we append.
+    const sysIdx = messages.findIndex((m) => m.role === 'system');
+    let working;
+    let systemPrompt;
+    if (sysIdx >= 0) {
+        working = messages.map((m, i) => i === sysIdx ? { role: m.role, content: `${m.content}\n\n${instruction}` } : m);
+        systemPrompt = undefined; // the array carries the system message
+    }
+    else {
+        working = [...messages];
+        systemPrompt = `${options?.systemPrompt ?? DEFAULT_OBJECT_SYSTEM_PROMPT}\n\n${instruction}`;
+    }
+    let lastText = '';
+    for (let attempt = 0; attempt <= maxRepairAttempts; attempt++) {
+        const { text } = await sendMessage(working, { systemPrompt, signal: options?.signal });
+        lastText = text;
+        const parsed = extractJson(text);
+        if (parsed.ok) {
+            const errors = validateAgainstSchema(parsed.value, schema);
+            if (errors.length === 0) {
+                return { object: parsed.value, text };
+            }
+            if (attempt < maxRepairAttempts) {
+                working = [
+                    ...working,
+                    { role: 'assistant', content: text },
+                    { role: 'user', content: buildSchemaRepair(errors) },
+                ];
+            }
+        }
+        else if (attempt < maxRepairAttempts) {
+            working = [
+                ...working,
+                { role: 'assistant', content: text },
+                { role: 'user', content: REPAIR_INVALID_JSON },
+            ];
+        }
+    }
+    throw new ModelError('INFERENCE_FAILED', getActiveModel(), `generateObject: model did not return schema-valid JSON after ${maxRepairAttempts + 1} attempt(s). ` +
+        `Last output: ${lastText.slice(0, 200)}`);
+}
+/**
+ * Generate text, optionally letting the model call tools (functions) you provide.
+ *
+ * Unlike {@link generateObject} (where the JSON *is* the answer), tool calling is
+ * a loop: the model proposes a call, expo-ai-kit validates the arguments against
+ * the tool's `parameters`, runs your `execute`, feeds the result back, and lets
+ * the model continue — until it produces a plain-text answer or the `maxSteps`
+ * budget is reached. With no `tools`, this is a single text generation.
+ *
+ * Orchestrated in JS over {@link sendMessage}, so it works on every backend
+ * (Apple Foundation Models, ML Kit, Gemma) and inherits the single-flight guard,
+ * `AbortSignal`, and `systemPrompt` semantics. On-device models are imperfect at
+ * tool selection, so the loop is defensive: malformed calls, unknown tool names,
+ * and schema-invalid arguments are re-prompted up to `maxRepairAttempts` times,
+ * and a tool with no `execute` stops the loop and returns the proposed call for
+ * you to gate. Keep tool sets small and `parameters` flat for best reliability.
+ *
+ * @param messages - The conversation, same shape as {@link sendMessage}.
+ * @param options - Tools, `maxSteps`, `systemPrompt`, `signal`, `maxRepairAttempts`.
+ * @returns `{ text, steps, toolCalls, toolResults, finishReason }`.
+ * @throws {ModelError} INFERENCE_FAILED if the model keeps proposing an unknown
+ *   tool or schema-invalid arguments after the repair attempts. Also propagates
+ *   INFERENCE_BUSY / INFERENCE_CANCELLED from the underlying generation.
+ *
+ * @example
+ * ```ts
+ * const { text } = await generateText(
+ *   [{ role: 'user', content: 'What should I wear in Paris today?' }],
+ *   {
+ *     tools: {
+ *       getWeather: {
+ *         description: 'Get the current weather for a city.',
+ *         parameters: {
+ *           type: 'object',
+ *           properties: { city: { type: 'string' } },
+ *           required: ['city'],
+ *         },
+ *         execute: async ({ city }: { city: string }) => fetchWeather(city),
+ *       },
+ *     },
+ *   },
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Human-in-the-loop: omit `execute` to gate the call yourself.
+ * const res = await generateText(messages, {
+ *   tools: { deleteAccount: { description: '…', parameters: { type: 'object' } } },
+ * });
+ * if (res.finishReason === 'tool-calls') {
+ *   const call = res.toolCalls[0]; // confirm with the user before running
+ * }
+ * ```
+ */
+export async function generateText(messages, options) {
+    if (Platform.OS !== 'ios' && Platform.OS !== 'android') {
+        throw new ModelError('DEVICE_NOT_SUPPORTED', '', 'generateText is only available on iOS and Android');
+    }
+    if (!messages || messages.length === 0) {
+        throw new Error('messages array cannot be empty');
+    }
+    const tools = options?.tools ?? {};
+    const toolNames = Object.keys(tools);
+    const maxSteps = Math.max(1, options?.maxSteps ?? 5);
+    const maxRepairAttempts = Math.max(0, options?.maxRepairAttempts ?? 2);
+    // Inject the tool instruction the same way generateObject injects its schema
+    // instruction: into the array's system message if present, else via the
+    // systemPrompt option. With no tools, this is a plain single-shot generation.
+    const instruction = toolNames.length > 0 ? buildToolInstruction(tools) : '';
+    const sysIdx = messages.findIndex((m) => m.role === 'system');
+    let working;
+    let systemPrompt;
+    if (instruction === '') {
+        working = [...messages];
+        systemPrompt = options?.systemPrompt;
+    }
+    else if (sysIdx >= 0) {
+        working = messages.map((m, i) => i === sysIdx ? { role: m.role, content: `${m.content}\n\n${instruction}` } : m);
+        systemPrompt = undefined; // the array carries the system message
+    }
+    else {
+        working = [...messages];
+        systemPrompt = `${options?.systemPrompt ?? DEFAULT_SYSTEM_PROMPT}\n\n${instruction}`;
+    }
+    const steps = [];
+    const allToolCalls = [];
+    const allToolResults = [];
+    for (let step = 0; step < maxSteps; step++) {
+        // One model round-trip, with an inner repair loop for malformed/invalid calls.
+        let call = null;
+        let text = '';
+        for (let repair = 0;; repair++) {
+            const r = await sendMessage(working, { systemPrompt, signal: options?.signal });
+            text = r.text;
+            if (toolNames.length === 0)
+                break; // no tools → this is the final answer
+            const parsed = parseToolCall(text, toolNames);
+            if (parsed.kind === 'text')
+                break; // plain answer, no tool call
+            if (parsed.kind === 'unknown-tool') {
+                if (repair >= maxRepairAttempts) {
+                    throw new ModelError('INFERENCE_FAILED', getActiveModel(), `generateText: model called unknown tool "${parsed.toolName}" after ${maxRepairAttempts + 1} attempt(s).`);
+                }
+                working = [
+                    ...working,
+                    { role: 'assistant', content: text },
+                    { role: 'user', content: buildUnknownToolRepair(parsed.toolName, toolNames) },
+                ];
+                continue;
+            }
+            // parsed.kind === 'tool' — validate the proposed args before executing.
+            const errors = validateAgainstSchema(parsed.args, tools[parsed.toolName].parameters);
+            if (errors.length === 0) {
+                call = { toolName: parsed.toolName, args: parsed.args };
+                break;
+            }
+            if (repair >= maxRepairAttempts) {
+                throw new ModelError('INFERENCE_FAILED', getActiveModel(), `generateText: arguments for "${parsed.toolName}" failed schema validation after ` +
+                    `${maxRepairAttempts + 1} attempt(s): ${errors.slice(0, 4).join('; ')}`);
+            }
+            working = [
+                ...working,
+                { role: 'assistant', content: text },
+                { role: 'user', content: buildToolArgsRepair(parsed.toolName, errors) },
+            ];
+        }
+        // No tool call this step → the model produced its final text answer.
+        if (!call) {
+            steps.push({ text, toolCalls: [], toolResults: [] });
+            return {
+                text,
+                steps,
+                toolCalls: allToolCalls,
+                toolResults: allToolResults,
+                finishReason: 'stop',
+            };
+        }
+        allToolCalls.push(call);
+        const tool = tools[call.toolName];
+        // No execute → hand the proposed call back to the caller (human-in-the-loop).
+        if (typeof tool.execute !== 'function') {
+            steps.push({ text, toolCalls: [call], toolResults: [] });
+            return {
+                text,
+                steps,
+                toolCalls: allToolCalls,
+                toolResults: allToolResults,
+                finishReason: 'tool-calls',
+            };
+        }
+        // Run the tool. A thrown error is fed back as the result so the model can recover.
+        let result;
+        try {
+            result = await tool.execute(call.args);
+        }
+        catch (e) {
+            result = { error: String(e?.message ?? e) };
+        }
+        const toolResult = { toolName: call.toolName, args: call.args, result };
+        allToolResults.push(toolResult);
+        steps.push({ text, toolCalls: [call], toolResults: [toolResult] });
+        // Feed the call + result back into the conversation for the next step.
+        working = [
+            ...working,
+            { role: 'assistant', content: text },
+            { role: 'user', content: formatToolResult(call.toolName, result) },
+        ];
+    }
+    // Step budget exhausted while still calling tools — no final answer was
+    // produced. Signal it via finishReason so the caller can raise maxSteps.
+    return {
+        text: '',
+        steps,
+        toolCalls: allToolCalls,
+        toolResults: allToolResults,
+        finishReason: 'max-steps',
+    };
+}
 // ============================================================================
 // Model Management API
 // ============================================================================