expo-ai-kit 0.5.0 → 0.7.0

package/build/types.d.ts

@@ -129,6 +129,179 @@ export type LLMStreamEvent = {
  * Callback function for streaming events.
  */
 export type LLMStreamCallback = (event: LLMStreamEvent) => void;
+/**
+ * The set of JSON Schema primitive `type` values understood by
+ * {@link generateObject}'s local validator.
+ */
+export type JSONSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+/**
+ * A JSON Schema describing the shape you want {@link generateObject} to return.
+ *
+ * A pragmatic subset is enforced locally — `type`, `properties`, `required`,
+ * `items`, and `enum` — which covers most extraction shapes. Any other JSON
+ * Schema keywords you include (e.g. `description`, `minLength`) are still sent
+ * to the model to guide it, but are not validated on-device. Keep schemas small:
+ * on-device models follow flat, shallow shapes far more reliably than deeply
+ * nested ones.
+ */
+export type JSONSchema = {
+    /** Expected JSON type (or a union of types). */
+    type?: JSONSchemaType | JSONSchemaType[];
+    /** Human-readable hint passed through to the model. */
+    description?: string;
+    /** For `object` schemas: the schema of each named property. */
+    properties?: Record<string, JSONSchema>;
+    /** For `object` schemas: property names that must be present. */
+    required?: string[];
+    /** For `array` schemas: the schema each element must satisfy. */
+    items?: JSONSchema;
+    /** Restrict the value to this set of literals. */
+    enum?: ReadonlyArray<string | number | boolean | null>;
+    /** Other JSON Schema keywords are accepted and forwarded to the model. */
+    [key: string]: unknown;
+};
+/**
+ * Options for {@link generateObject}.
+ */
+export type GenerateObjectOptions = {
+    /**
+     * System prompt used when the messages array has no system message. Defaults
+     * to a structured-output-oriented instruction. If a system message is present
+     * in the array, this is ignored (the schema instruction is appended to it).
+     */
+    systemPrompt?: string;
+    /**
+     * Abort the request. Behaves like {@link LLMSendOptions.signal} — the returned
+     * promise rejects with an INFERENCE_CANCELLED {@link ModelError}.
+     */
+    signal?: AbortSignal;
+    /**
+     * How many times to re-prompt the model when its output is not valid JSON or
+     * does not match the schema. Each repair feeds the error back to the model.
+     * Defaults to 2 (i.e. up to 3 generations total).
+     */
+    maxRepairAttempts?: number;
+};
+/**
+ * Result of {@link generateObject}.
+ */
+export type GenerateObjectResult<T = unknown> = {
+    /** The parsed value, validated against the schema. */
+    object: T;
+    /** The raw model output that produced `object` (useful for debugging). */
+    text: string;
+};
+/**
+ * A tool (function) the model may call to fetch data or take an action.
+ *
+ * The model never runs anything itself — it *proposes* a call (a name + JSON
+ * arguments), {@link generateText} validates the arguments against `parameters`,
+ * and only then invokes your `execute`. The result is fed back into the
+ * conversation so the model can use it to produce its final answer.
+ *
+ * @typeParam TArgs - Shape of the validated arguments passed to `execute`.
+ * @typeParam TResult - What `execute` returns (serialized back to the model).
+ */
+export type Tool<TArgs = any, TResult = any> = {
+    /**
+     * What the tool does and when to use it. This is how the model decides
+     * whether a request matches this tool — make it specific and action-oriented.
+     */
+    description: string;
+    /**
+     * JSON Schema for the tool's arguments. The model is told to conform to it,
+     * and the args it proposes are validated against it (same pragmatic subset as
+     * {@link generateObject}) before `execute` runs. Keep it small and shallow.
+     */
+    parameters: JSONSchema;
+    /**
+     * Runs the tool with the validated arguments and returns a result.
+     *
+     * **Optional on purpose.** If you omit it, {@link generateText} does not run
+     * anything — it stops with `finishReason: 'tool-calls'` and hands you the
+     * proposed call so you can confirm, gate, or execute it yourself.
+     */
+    execute?: (args: TArgs) => TResult | Promise<TResult>;
+};
+/** A map of tool name → {@link Tool}, passed to {@link generateText}. */
+export type ToolSet = Record<string, Tool>;
+/** A tool invocation the model proposed (name + validated arguments). */
+export type ToolCall = {
+    /** The tool's key in the {@link ToolSet}. */
+    toolName: string;
+    /** Arguments the model supplied, validated against the tool's `parameters`. */
+    args: unknown;
+};
+/** The outcome of running a {@link ToolCall} via its `execute`. */
+export type ToolResult = {
+    /** The tool's key in the {@link ToolSet}. */
+    toolName: string;
+    /** The arguments that were passed to `execute`. */
+    args: unknown;
+    /** Whatever `execute` returned (or `{ error }` if it threw). */
+    result: unknown;
+};
+/** One model round-trip in the {@link generateText} loop. */
+export type StepResult = {
+    /** Assistant text produced this step (empty when the step only called a tool). */
+    text: string;
+    /** Tool calls proposed this step (at most one in the current protocol). */
+    toolCalls: ToolCall[];
+    /** Results of the tool calls executed this step. */
+    toolResults: ToolResult[];
+};
+/**
+ * Why {@link generateText} stopped.
+ *
+ * - `'stop'`: the model produced a final text answer.
+ * - `'tool-calls'`: stopped because a proposed tool has no `execute` — the call
+ *   is returned for you to handle (human-in-the-loop).
+ * - `'max-steps'`: hit the `maxSteps` cap while still calling tools. Raise the cap.
+ */
+export type GenerateTextFinishReason = 'stop' | 'tool-calls' | 'max-steps';
+/**
+ * Options for {@link generateText}.
+ */
+export type GenerateTextOptions = {
+    /** Tools the model may call. Omit (or pass `{}`) for a plain text generation. */
+    tools?: ToolSet;
+    /**
+     * Maximum number of model round-trips (each call + tool execution is one step).
+     * Bounds the tool-calling chain so it can't run away. Defaults to 5.
+     */
+    maxSteps?: number;
+    /**
+     * System prompt used when the messages array has no system message. The tool
+     * instructions are appended to it (or to the array's system message if present).
+     */
+    systemPrompt?: string;
+    /**
+     * Abort the request. Behaves like {@link LLMSendOptions.signal} — the returned
+     * promise rejects with an INFERENCE_CANCELLED {@link ModelError}.
+     */
+    signal?: AbortSignal;
+    /**
+     * How many times to re-prompt within a step when the model emits a malformed
+     * tool call, an unknown tool name, or arguments that fail schema validation.
+     * Defaults to 2. If it still can't comply, `generateText` throws INFERENCE_FAILED.
+     */
+    maxRepairAttempts?: number;
+};
+/**
+ * Result of {@link generateText}.
+ */
+export type GenerateTextResult = {
+    /** The final assistant text (empty if it stopped on a tool call without `execute`). */
+    text: string;
+    /** Every step taken, in order — useful for tracing or debugging. */
+    steps: StepResult[];
+    /** All tool calls across every step, flattened. */
+    toolCalls: ToolCall[];
+    /** All tool results across every step, flattened. */
+    toolResults: ToolResult[];
+    /** Why generation stopped. See {@link GenerateTextFinishReason}. */
+    finishReason: GenerateTextFinishReason;
+};
 /**
  * A built-in model provided by the OS (e.g. Apple Foundation Models, ML Kit).
  * These are always available on supported devices -- no download needed.

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,iEAAiE;IACjE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B;;;;OAIG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAOhE;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,MAAM,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,gDAAgD;IAChD,IAAI,CAAC,EAAE,cAAc,GAAG,cAAc,EAAE,CAAC;IACzC,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,kDAAkD;IAClD,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IACvD,0EAA0E;IAC1E,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,GAAG,OAAO,IAAI;IAC9C,sDAAsD;IACtD,MAAM,EAAE,CAAC,CAAC;IACV,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAOF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,IAAI,CAAC,KAAK,GAAG,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI;IAC7C;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,EAAE,UAAU,CAAC;IACvB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD,CAAC;AAEF,yEAAyE;AACzE,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAE3C,yEAAyE;AACzE,MAAM,MAAM,QAAQ,GAAG;IACrB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEF,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG;IACvB,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,EAAE,OAAO,CAAC;IACd,gEAAgE;IAChE,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG;IACvB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,oDAAoD;IACpD,WAAW,EAAE,UAAU,EAAE,CAAC;CAC3B,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,YAAY,GAAG,WAAW,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uFAAuF;IACvF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,mDAAmD;IACnD,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,qDAAqD;IACrD,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,oEAAoE;IACpE,YAAY,EAAE,wBAAwB,CAAC;CACxC,CAAC;AAOF;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,6CAA6C;IAC7C,QAAQ,EAAE,KAAK,GAAG,SAAS,CAAC;IAC5B,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,+BAA+B;IAC/B,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,GAC/B,gBAAgB,GAChB,aAAa,GACb,YAAY,GACZ,SAAS,GACT,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,sBAAsB,GACtB,iBAAiB,GACjB,kBAAkB,GAClB,uBAAuB,GACvB,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,qBAAqB,GACrB,mBAAmB,GACnB,sBAAsB,GACtB,SAAS,CAAC;AAEd;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;gBAEJ,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAMpE;AAED;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC"}

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+NA;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,IAAI,CAAiB;IACrB,OAAO,CAAS;IAEhB,YAAY,IAAoB,EAAE,OAAe,EAAE,OAAgB;QACjE,KAAK,CAAC,OAAO,IAAI,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["/**\n * Hardware backend for on-device model inference.\n *\n * - 'auto': Try GPU first, fall back to CPU (default)\n * - 'gpu': Force GPU — faster (~40-50 tok/s) but needs more memory\n * - 'cpu': Force CPU — slower (~2-5 tok/s) but works on low-RAM devices\n */\nexport type InferenceBackend = 'auto' | 'gpu' | 'cpu';\n\n/**\n * Sampling / generation parameters applied to a model session.\n *\n * Support is per-backend (on-device runtimes expose different knobs), so these\n * are best-effort — unsupported fields are ignored rather than erroring:\n *\n * | field       | Gemma (LiteRT-LM) | Apple Foundation Models | ML Kit |\n * |-------------|:-----------------:|:-----------------------:|:------:|\n * | temperature | ✓                 | ✓                       | —      |\n * | topK        | ✓                 | —                       | —      |\n * | topP        | ✓                 | —                       | —      |\n * | seed        | ✓ (iOS only)      | —                       | —      |\n * | maxTokens   | —                 | ✓ (max output)          | —      |\n *\n * Notes:\n * - Gemma/LiteRT-LM has no per-generation output-token cap (its `maxNumTokens`\n *   is the total KV-cache size, set at load), so `maxTokens` is not honored\n *   there. Its sampler (topK/topP/temperature[/seed]) is fixed at conversation\n *   creation, which is why generation config lives on setModel() rather than\n *   per-call. `seed` is currently wired on iOS only.\n * - The ML Kit built-in (Android default) does not yet apply generation config;\n *   it uses its own defaults.\n */\nexport type GenerationConfig = {\n  /** Sampling temperature. Lower = more deterministic. Typically 0.0–2.0. */\n  temperature?: number;\n  /** Nucleus sampling: number of top logits to consider. Must be > 0. */\n  topK?: number;\n  /** Nucleus sampling: cumulative probability threshold in [0, 1]. */\n  topP?: number;\n  /** RNG seed for reproducible sampling (Gemma only). */\n  seed?: number;\n  /** Maximum number of output tokens to generate (Apple FM / ML Kit only). */\n  maxTokens?: number;\n};\n\n/**\n * Options for setModel.\n */\nexport type SetModelOptions = {\n  /** Hardware backend to use for inference. Defaults to 'auto'. */\n  backend?: InferenceBackend;\n  /**\n   * Default sampling parameters for this model session. Applied when the model\n   * is activated and used for all subsequent sendMessage/streamMessage calls\n   * until the next setModel(). See {@link GenerationConfig} for per-backend support.\n   */\n  generation?: GenerationConfig;\n};\n\n/**\n * Role in a conversation message.\n */\nexport type LLMRole = 'system' | 'user' | 'assistant';\n\n/**\n * A single message in a conversation.\n */\nexport type LLMMessage = {\n  role: LLMRole;\n  content: string;\n};\n\n/**\n * Options for sendMessage.\n */\nexport type LLMSendOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n  /**\n   * Abort the request. When the signal fires, the returned promise rejects with\n   * an INFERENCE_CANCELLED {@link ModelError}.\n   *\n   * Note: on-device, non-streaming generation cannot always be interrupted\n   * mid-decode — abort always unblocks the caller, but the model may keep\n   * computing in the background until it finishes, during which a new\n   * sendMessage/streamMessage will throw INFERENCE_BUSY. To truly interrupt a\n   * long generation, prefer streamMessage().stop().\n   */\n  signal?: AbortSignal;\n};\n\n/**\n * Response from sendMessage.\n */\nexport type LLMResponse = {\n  /** The generated response text */\n  text: string;\n};\n\n/**\n * Options for streamMessage.\n */\nexport type LLMStreamOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Handle returned by streamMessage.\n */\nexport type LLMStreamHandle = {\n  /** Resolves with the final text when streaming completes or is stopped. */\n  promise: Promise<LLMResponse>;\n  /** Stop streaming. Resolves `promise` with the text accumulated so far. */\n  stop: () => void;\n};\n\n/**\n * Event payload for streaming tokens.\n */\nexport type LLMStreamEvent = {\n  /** Unique identifier for this streaming session */\n  sessionId: string;\n  /** The token/chunk of text received */\n  token: string;\n  /** Accumulated text so far */\n  accumulatedText: string;\n  /** Whether this is the final chunk */\n  isDone: boolean;\n};\n\n/**\n * Callback function for streaming events.\n */\nexport type LLMStreamCallback = (event: LLMStreamEvent) => void;\n\n\n// ============================================================================\n// Model Types\n// ============================================================================\n\n/**\n * A built-in model provided by the OS (e.g. Apple Foundation Models, ML Kit).\n * These are always available on supported devices -- no download needed.\n */\nexport type BuiltInModel = {\n  /** Unique model identifier (e.g. 'apple-fm', 'mlkit') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Whether this model is available on the current device/OS */\n  available: boolean;\n  /** Platform this model is associated with */\n  platform: 'ios' | 'android';\n  /** Maximum context window in tokens */\n  contextWindow: number;\n};\n\n/**\n * A downloadable model that the user manages (download, load, delete).\n * These require explicit download before use.\n */\nexport type DownloadableModel = {\n  /** Unique model identifier (e.g. 'gemma-e2b', 'gemma-e4b') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Parameter count label (e.g. '2.3B') */\n  parameterCount: string;\n  /** Download file size in bytes */\n  sizeBytes: number;\n  /** Maximum context window in tokens */\n  contextWindow: number;\n  /** Minimum device RAM in bytes required to run */\n  minRamBytes: number;\n  /** Whether this device meets the model's minimum RAM requirement */\n  meetsRequirements: boolean;\n  /** Current lifecycle status */\n  status: DownloadableModelStatus;\n};\n\n/**\n * Lifecycle status of a downloadable model.\n *\n * - 'not-downloaded': Model file is not on disk\n * - 'downloading': Model file is being downloaded\n * - 'downloaded': Model file is on disk but not loaded into memory. Call\n *   setModel() to load it. This survives app restarts, so use it to decide\n *   whether a (re-)download is needed.\n * - 'loading': File is on disk, model is being loaded into memory for inference\n * - 'ready': Model is loaded in memory and ready for inference\n */\nexport type DownloadableModelStatus =\n  | 'not-downloaded'\n  | 'downloading'\n  | 'downloaded'\n  | 'loading'\n  | 'ready';\n\n/**\n * Error codes for model-related operations.\n */\nexport type ModelErrorCode =\n  | 'MODEL_NOT_FOUND'\n  | 'MODEL_NOT_DOWNLOADED'\n  | 'DOWNLOAD_FAILED'\n  | 'DOWNLOAD_CORRUPT'\n  | 'DOWNLOAD_STORAGE_FULL'\n  | 'DOWNLOAD_CANCELLED'\n  | 'INFERENCE_OOM'\n  | 'INFERENCE_FAILED'\n  | 'INFERENCE_BUSY'\n  | 'INFERENCE_CANCELLED'\n  | 'MODEL_LOAD_FAILED'\n  | 'DEVICE_NOT_SUPPORTED'\n  | 'UNKNOWN';\n\n/**\n * Structured error for model operations.\n */\nexport class ModelError extends Error {\n  code: ModelErrorCode;\n  modelId: string;\n\n  constructor(code: ModelErrorCode, modelId: string, message?: string) {\n    super(message ?? `${code}: ${modelId}`);\n    this.name = 'ModelError';\n    this.code = code;\n    this.modelId = modelId;\n  }\n}\n\n/**\n * Event payload for model download progress.\n */\nexport type ModelDownloadProgressEvent = {\n  /** Model being downloaded */\n  modelId: string;\n  /** Download progress from 0 to 1 */\n  progress: number;\n};\n\n/**\n * Event payload for model state changes.\n */\nexport type ModelStateChangeEvent = {\n  /** Model whose state changed */\n  modelId: string;\n  /** New status */\n  status: DownloadableModelStatus;\n};\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAyaA;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,IAAI,CAAiB;IACrB,OAAO,CAAS;IAEhB,YAAY,IAAoB,EAAE,OAAe,EAAE,OAAgB;QACjE,KAAK,CAAC,OAAO,IAAI,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["/**\n * Hardware backend for on-device model inference.\n *\n * - 'auto': Try GPU first, fall back to CPU (default)\n * - 'gpu': Force GPU — faster (~40-50 tok/s) but needs more memory\n * - 'cpu': Force CPU — slower (~2-5 tok/s) but works on low-RAM devices\n */\nexport type InferenceBackend = 'auto' | 'gpu' | 'cpu';\n\n/**\n * Sampling / generation parameters applied to a model session.\n *\n * Support is per-backend (on-device runtimes expose different knobs), so these\n * are best-effort — unsupported fields are ignored rather than erroring:\n *\n * | field       | Gemma (LiteRT-LM) | Apple Foundation Models | ML Kit |\n * |-------------|:-----------------:|:-----------------------:|:------:|\n * | temperature | ✓                 | ✓                       | —      |\n * | topK        | ✓                 | —                       | —      |\n * | topP        | ✓                 | —                       | —      |\n * | seed        | ✓ (iOS only)      | —                       | —      |\n * | maxTokens   | —                 | ✓ (max output)          | —      |\n *\n * Notes:\n * - Gemma/LiteRT-LM has no per-generation output-token cap (its `maxNumTokens`\n *   is the total KV-cache size, set at load), so `maxTokens` is not honored\n *   there. Its sampler (topK/topP/temperature[/seed]) is fixed at conversation\n *   creation, which is why generation config lives on setModel() rather than\n *   per-call. `seed` is currently wired on iOS only.\n * - The ML Kit built-in (Android default) does not yet apply generation config;\n *   it uses its own defaults.\n */\nexport type GenerationConfig = {\n  /** Sampling temperature. Lower = more deterministic. Typically 0.0–2.0. */\n  temperature?: number;\n  /** Nucleus sampling: number of top logits to consider. Must be > 0. */\n  topK?: number;\n  /** Nucleus sampling: cumulative probability threshold in [0, 1]. */\n  topP?: number;\n  /** RNG seed for reproducible sampling (Gemma only). */\n  seed?: number;\n  /** Maximum number of output tokens to generate (Apple FM / ML Kit only). */\n  maxTokens?: number;\n};\n\n/**\n * Options for setModel.\n */\nexport type SetModelOptions = {\n  /** Hardware backend to use for inference. Defaults to 'auto'. */\n  backend?: InferenceBackend;\n  /**\n   * Default sampling parameters for this model session. Applied when the model\n   * is activated and used for all subsequent sendMessage/streamMessage calls\n   * until the next setModel(). See {@link GenerationConfig} for per-backend support.\n   */\n  generation?: GenerationConfig;\n};\n\n/**\n * Role in a conversation message.\n */\nexport type LLMRole = 'system' | 'user' | 'assistant';\n\n/**\n * A single message in a conversation.\n */\nexport type LLMMessage = {\n  role: LLMRole;\n  content: string;\n};\n\n/**\n * Options for sendMessage.\n */\nexport type LLMSendOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n  /**\n   * Abort the request. When the signal fires, the returned promise rejects with\n   * an INFERENCE_CANCELLED {@link ModelError}.\n   *\n   * Note: on-device, non-streaming generation cannot always be interrupted\n   * mid-decode — abort always unblocks the caller, but the model may keep\n   * computing in the background until it finishes, during which a new\n   * sendMessage/streamMessage will throw INFERENCE_BUSY. To truly interrupt a\n   * long generation, prefer streamMessage().stop().\n   */\n  signal?: AbortSignal;\n};\n\n/**\n * Response from sendMessage.\n */\nexport type LLMResponse = {\n  /** The generated response text */\n  text: string;\n};\n\n/**\n * Options for streamMessage.\n */\nexport type LLMStreamOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Handle returned by streamMessage.\n */\nexport type LLMStreamHandle = {\n  /** Resolves with the final text when streaming completes or is stopped. */\n  promise: Promise<LLMResponse>;\n  /** Stop streaming. Resolves `promise` with the text accumulated so far. */\n  stop: () => void;\n};\n\n/**\n * Event payload for streaming tokens.\n */\nexport type LLMStreamEvent = {\n  /** Unique identifier for this streaming session */\n  sessionId: string;\n  /** The token/chunk of text received */\n  token: string;\n  /** Accumulated text so far */\n  accumulatedText: string;\n  /** Whether this is the final chunk */\n  isDone: boolean;\n};\n\n/**\n * Callback function for streaming events.\n */\nexport type LLMStreamCallback = (event: LLMStreamEvent) => void;\n\n\n// ============================================================================\n// Structured Output (generateObject)\n// ============================================================================\n\n/**\n * The set of JSON Schema primitive `type` values understood by\n * {@link generateObject}'s local validator.\n */\nexport type JSONSchemaType =\n  | 'object'\n  | 'array'\n  | 'string'\n  | 'number'\n  | 'integer'\n  | 'boolean'\n  | 'null';\n\n/**\n * A JSON Schema describing the shape you want {@link generateObject} to return.\n *\n * A pragmatic subset is enforced locally — `type`, `properties`, `required`,\n * `items`, and `enum` — which covers most extraction shapes. Any other JSON\n * Schema keywords you include (e.g. `description`, `minLength`) are still sent\n * to the model to guide it, but are not validated on-device. Keep schemas small:\n * on-device models follow flat, shallow shapes far more reliably than deeply\n * nested ones.\n */\nexport type JSONSchema = {\n  /** Expected JSON type (or a union of types). */\n  type?: JSONSchemaType | JSONSchemaType[];\n  /** Human-readable hint passed through to the model. */\n  description?: string;\n  /** For `object` schemas: the schema of each named property. */\n  properties?: Record<string, JSONSchema>;\n  /** For `object` schemas: property names that must be present. */\n  required?: string[];\n  /** For `array` schemas: the schema each element must satisfy. */\n  items?: JSONSchema;\n  /** Restrict the value to this set of literals. */\n  enum?: ReadonlyArray<string | number | boolean | null>;\n  /** Other JSON Schema keywords are accepted and forwarded to the model. */\n  [key: string]: unknown;\n};\n\n/**\n * Options for {@link generateObject}.\n */\nexport type GenerateObjectOptions = {\n  /**\n   * System prompt used when the messages array has no system message. Defaults\n   * to a structured-output-oriented instruction. If a system message is present\n   * in the array, this is ignored (the schema instruction is appended to it).\n   */\n  systemPrompt?: string;\n  /**\n   * Abort the request. Behaves like {@link LLMSendOptions.signal} — the returned\n   * promise rejects with an INFERENCE_CANCELLED {@link ModelError}.\n   */\n  signal?: AbortSignal;\n  /**\n   * How many times to re-prompt the model when its output is not valid JSON or\n   * does not match the schema. Each repair feeds the error back to the model.\n   * Defaults to 2 (i.e. up to 3 generations total).\n   */\n  maxRepairAttempts?: number;\n};\n\n/**\n * Result of {@link generateObject}.\n */\nexport type GenerateObjectResult<T = unknown> = {\n  /** The parsed value, validated against the schema. */\n  object: T;\n  /** The raw model output that produced `object` (useful for debugging). */\n  text: string;\n};\n\n\n// ============================================================================\n// Tool / Function Calling (generateText)\n// ============================================================================\n\n/**\n * A tool (function) the model may call to fetch data or take an action.\n *\n * The model never runs anything itself — it *proposes* a call (a name + JSON\n * arguments), {@link generateText} validates the arguments against `parameters`,\n * and only then invokes your `execute`. The result is fed back into the\n * conversation so the model can use it to produce its final answer.\n *\n * @typeParam TArgs - Shape of the validated arguments passed to `execute`.\n * @typeParam TResult - What `execute` returns (serialized back to the model).\n */\nexport type Tool<TArgs = any, TResult = any> = {\n  /**\n   * What the tool does and when to use it. This is how the model decides\n   * whether a request matches this tool — make it specific and action-oriented.\n   */\n  description: string;\n  /**\n   * JSON Schema for the tool's arguments. The model is told to conform to it,\n   * and the args it proposes are validated against it (same pragmatic subset as\n   * {@link generateObject}) before `execute` runs. Keep it small and shallow.\n   */\n  parameters: JSONSchema;\n  /**\n   * Runs the tool with the validated arguments and returns a result.\n   *\n   * **Optional on purpose.** If you omit it, {@link generateText} does not run\n   * anything — it stops with `finishReason: 'tool-calls'` and hands you the\n   * proposed call so you can confirm, gate, or execute it yourself.\n   */\n  execute?: (args: TArgs) => TResult | Promise<TResult>;\n};\n\n/** A map of tool name → {@link Tool}, passed to {@link generateText}. */\nexport type ToolSet = Record<string, Tool>;\n\n/** A tool invocation the model proposed (name + validated arguments). */\nexport type ToolCall = {\n  /** The tool's key in the {@link ToolSet}. */\n  toolName: string;\n  /** Arguments the model supplied, validated against the tool's `parameters`. */\n  args: unknown;\n};\n\n/** The outcome of running a {@link ToolCall} via its `execute`. */\nexport type ToolResult = {\n  /** The tool's key in the {@link ToolSet}. */\n  toolName: string;\n  /** The arguments that were passed to `execute`. */\n  args: unknown;\n  /** Whatever `execute` returned (or `{ error }` if it threw). */\n  result: unknown;\n};\n\n/** One model round-trip in the {@link generateText} loop. */\nexport type StepResult = {\n  /** Assistant text produced this step (empty when the step only called a tool). */\n  text: string;\n  /** Tool calls proposed this step (at most one in the current protocol). */\n  toolCalls: ToolCall[];\n  /** Results of the tool calls executed this step. */\n  toolResults: ToolResult[];\n};\n\n/**\n * Why {@link generateText} stopped.\n *\n * - `'stop'`: the model produced a final text answer.\n * - `'tool-calls'`: stopped because a proposed tool has no `execute` — the call\n *   is returned for you to handle (human-in-the-loop).\n * - `'max-steps'`: hit the `maxSteps` cap while still calling tools. Raise the cap.\n */\nexport type GenerateTextFinishReason = 'stop' | 'tool-calls' | 'max-steps';\n\n/**\n * Options for {@link generateText}.\n */\nexport type GenerateTextOptions = {\n  /** Tools the model may call. Omit (or pass `{}`) for a plain text generation. */\n  tools?: ToolSet;\n  /**\n   * Maximum number of model round-trips (each call + tool execution is one step).\n   * Bounds the tool-calling chain so it can't run away. Defaults to 5.\n   */\n  maxSteps?: number;\n  /**\n   * System prompt used when the messages array has no system message. The tool\n   * instructions are appended to it (or to the array's system message if present).\n   */\n  systemPrompt?: string;\n  /**\n   * Abort the request. Behaves like {@link LLMSendOptions.signal} — the returned\n   * promise rejects with an INFERENCE_CANCELLED {@link ModelError}.\n   */\n  signal?: AbortSignal;\n  /**\n   * How many times to re-prompt within a step when the model emits a malformed\n   * tool call, an unknown tool name, or arguments that fail schema validation.\n   * Defaults to 2. If it still can't comply, `generateText` throws INFERENCE_FAILED.\n   */\n  maxRepairAttempts?: number;\n};\n\n/**\n * Result of {@link generateText}.\n */\nexport type GenerateTextResult = {\n  /** The final assistant text (empty if it stopped on a tool call without `execute`). */\n  text: string;\n  /** Every step taken, in order — useful for tracing or debugging. */\n  steps: StepResult[];\n  /** All tool calls across every step, flattened. */\n  toolCalls: ToolCall[];\n  /** All tool results across every step, flattened. */\n  toolResults: ToolResult[];\n  /** Why generation stopped. See {@link GenerateTextFinishReason}. */\n  finishReason: GenerateTextFinishReason;\n};\n\n\n// ============================================================================\n// Model Types\n// ============================================================================\n\n/**\n * A built-in model provided by the OS (e.g. Apple Foundation Models, ML Kit).\n * These are always available on supported devices -- no download needed.\n */\nexport type BuiltInModel = {\n  /** Unique model identifier (e.g. 'apple-fm', 'mlkit') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Whether this model is available on the current device/OS */\n  available: boolean;\n  /** Platform this model is associated with */\n  platform: 'ios' | 'android';\n  /** Maximum context window in tokens */\n  contextWindow: number;\n};\n\n/**\n * A downloadable model that the user manages (download, load, delete).\n * These require explicit download before use.\n */\nexport type DownloadableModel = {\n  /** Unique model identifier (e.g. 'gemma-e2b', 'gemma-e4b') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Parameter count label (e.g. '2.3B') */\n  parameterCount: string;\n  /** Download file size in bytes */\n  sizeBytes: number;\n  /** Maximum context window in tokens */\n  contextWindow: number;\n  /** Minimum device RAM in bytes required to run */\n  minRamBytes: number;\n  /** Whether this device meets the model's minimum RAM requirement */\n  meetsRequirements: boolean;\n  /** Current lifecycle status */\n  status: DownloadableModelStatus;\n};\n\n/**\n * Lifecycle status of a downloadable model.\n *\n * - 'not-downloaded': Model file is not on disk\n * - 'downloading': Model file is being downloaded\n * - 'downloaded': Model file is on disk but not loaded into memory. Call\n *   setModel() to load it. This survives app restarts, so use it to decide\n *   whether a (re-)download is needed.\n * - 'loading': File is on disk, model is being loaded into memory for inference\n * - 'ready': Model is loaded in memory and ready for inference\n */\nexport type DownloadableModelStatus =\n  | 'not-downloaded'\n  | 'downloading'\n  | 'downloaded'\n  | 'loading'\n  | 'ready';\n\n/**\n * Error codes for model-related operations.\n */\nexport type ModelErrorCode =\n  | 'MODEL_NOT_FOUND'\n  | 'MODEL_NOT_DOWNLOADED'\n  | 'DOWNLOAD_FAILED'\n  | 'DOWNLOAD_CORRUPT'\n  | 'DOWNLOAD_STORAGE_FULL'\n  | 'DOWNLOAD_CANCELLED'\n  | 'INFERENCE_OOM'\n  | 'INFERENCE_FAILED'\n  | 'INFERENCE_BUSY'\n  | 'INFERENCE_CANCELLED'\n  | 'MODEL_LOAD_FAILED'\n  | 'DEVICE_NOT_SUPPORTED'\n  | 'UNKNOWN';\n\n/**\n * Structured error for model operations.\n */\nexport class ModelError extends Error {\n  code: ModelErrorCode;\n  modelId: string;\n\n  constructor(code: ModelErrorCode, modelId: string, message?: string) {\n    super(message ?? `${code}: ${modelId}`);\n    this.name = 'ModelError';\n    this.code = code;\n    this.modelId = modelId;\n  }\n}\n\n/**\n * Event payload for model download progress.\n */\nexport type ModelDownloadProgressEvent = {\n  /** Model being downloaded */\n  modelId: string;\n  /** Download progress from 0 to 1 */\n  progress: number;\n};\n\n/**\n * Event payload for model state changes.\n */\nexport type ModelStateChangeEvent = {\n  /** Model whose state changed */\n  modelId: string;\n  /** New status */\n  status: DownloadableModelStatus;\n};\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "expo-ai-kit",
-  "version": "0.5.0",
-  "description": "On-device AI for Expo apps — run Gemma 4, Apple Foundation Models, and ML Kit locally with zero API keys",
+  "version": "0.7.0",
+  "description": "On-device AI for Expo — run Gemma 4, Apple Foundation Models & ML Kit locally: streaming, structured output, tool calling, zero API keys",
   "main": "build/index.js",
   "types": "build/index.d.ts",
   "files": [
@@ -13,6 +13,7 @@
     "android/build.gradle",
     "scripts/install-litertlm.sh",
     "src",
+    "!src/__tests__",
     "expo-module.config.json"
   ],
   "scripts": {
@@ -43,6 +44,10 @@
     "apple-foundation-models",
     "ml-kit",
     "local-inference",
+    "structured-output",
+    "tool-calling",
+    "function-calling",
+    "json-schema",
     "expo-ai-kit",
     "ExpoAiKit"
   ],

package/src/index.ts

@@ -14,7 +14,29 @@ import {
   ModelError,
   ModelErrorCode,
   SetModelOptions,
+  JSONSchema,
+  GenerateObjectOptions,
+  GenerateObjectResult,
+  GenerateTextOptions,
+  GenerateTextResult,
+  ToolCall,
+  ToolResult,
+  StepResult,
 } 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';
@@ -23,6 +45,9 @@ 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(): string {
   return `gen_${Date.now()}_${++streamIdCounter}`;
@@ -382,6 +407,328 @@ export function streamMessage(
   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<T = unknown>(
+  messages: LLMMessage[],
+  schema: JSONSchema,
+  options?: GenerateObjectOptions
+): Promise<GenerateObjectResult<T>> {
+  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: LLMMessage[];
+  let systemPrompt: string | undefined;
+  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 as T, 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: LLMMessage[],
+  options?: GenerateTextOptions
+): Promise<GenerateTextResult> {
+  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: LLMMessage[];
+  let systemPrompt: string | undefined;
+  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: StepResult[] = [];
+  const allToolCalls: ToolCall[] = [];
+  const allToolResults: ToolResult[] = [];
+
+  for (let step = 0; step < maxSteps; step++) {
+    // One model round-trip, with an inner repair loop for malformed/invalid calls.
+    let call: ToolCall | null = 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: unknown;
+    try {
+      result = await tool.execute(call.args);
+    } catch (e) {
+      result = { error: String((e as any)?.message ?? e) };
+    }
+    const toolResult: 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
 // ============================================================================