expo-ai-kit 0.5.0 → 0.7.0

package/src/structured.ts

@@ -0,0 +1,202 @@
+import type { JSONSchema, JSONSchemaType } from './types';
+
+// ---------------------------------------------------------------------------
+// Pure helpers for generateObject().
+//
+// This module is deliberately free of any native-module import so its logic can
+// be unit-tested in plain Node. generateObject() (in index.ts) orchestrates the
+// inference call + repair loop on top of these.
+// ---------------------------------------------------------------------------
+
+/** Build the instruction appended to the system prompt to elicit schema-shaped JSON. */
+export function buildSchemaInstruction(schema: JSONSchema): string {
+  return [
+    'You must respond with a single JSON value that strictly conforms to this JSON Schema:',
+    '',
+    JSON.stringify(schema),
+    '',
+    'Rules:',
+    '- Output ONLY the JSON value. No prose, no explanation, no markdown code fences.',
+    '- Include every property listed under "required".',
+    '- Use the exact property names and value types defined by the schema.',
+  ].join('\n');
+}
+
+/** Follow-up prompt when the model returned something that could not be parsed as JSON. */
+export const REPAIR_INVALID_JSON =
+  'Your previous response was not valid JSON. Respond again with ONLY a single valid ' +
+  'JSON value that conforms to the schema — no prose, no markdown code fences.';
+
+/** Follow-up prompt when the model returned valid JSON that violated the schema. */
+export function buildSchemaRepair(errors: string[]): string {
+  const detail = errors.slice(0, 8).join('; ');
+  return (
+    `Your previous JSON did not match the schema: ${detail}. ` +
+    'Respond again with ONLY the corrected JSON value — no prose, no markdown code fences.'
+  );
+}
+
+export type ParseResult = { ok: true; value: unknown } | { ok: false };
+
+/**
+ * Best-effort extraction of a JSON value from model output.
+ *
+ * On-device models often wrap JSON in a ```json fence or add a sentence of prose
+ * around it. We try, in order: a fenced block, the trimmed whole string, then the
+ * first balanced {...}/[...] block found anywhere in the text.
+ */
+export function extractJson(text: string): ParseResult {
+  if (!text) return { ok: false };
+
+  const candidates: string[] = [];
+  const fence = /```(?:json)?\s*([\s\S]*?)```/i.exec(text);
+  if (fence && fence[1]) candidates.push(fence[1]);
+  candidates.push(text);
+
+  for (const raw of candidates) {
+    const trimmed = raw.trim();
+    const direct = tryParse(trimmed);
+    if (direct.ok) return direct;
+
+    const sliced = sliceBalanced(trimmed);
+    if (sliced != null) {
+      const p = tryParse(sliced);
+      if (p.ok) return p;
+    }
+  }
+  return { ok: false };
+}
+
+function tryParse(s: string): ParseResult {
+  if (!s) return { ok: false };
+  try {
+    return { ok: true, value: JSON.parse(s) };
+  } catch {
+    return { ok: false };
+  }
+}
+
+/**
+ * Return the first balanced `{...}` or `[...]` substring, or null if none.
+ * Tracks string state so braces inside JSON strings are not counted.
+ */
+export function sliceBalanced(text: string): string | null {
+  const start = text.search(/[{[]/);
+  if (start < 0) return null;
+
+  const open = text[start];
+  const close = open === '{' ? '}' : ']';
+  let depth = 0;
+  let inStr = false;
+  let escaped = false;
+
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inStr) {
+      if (escaped) escaped = false;
+      else if (ch === '\\') escaped = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === open) depth++;
+    else if (ch === close) {
+      depth--;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate `value` against the supported subset of `schema`.
+ * Returns a list of human-readable error strings (empty ⇒ valid).
+ *
+ * Intentionally lenient: unknown keywords and extra object properties are
+ * allowed. The goal is to catch structural mistakes worth re-prompting over
+ * (wrong type, missing required field), not full JSON Schema conformance.
+ */
+export function validateAgainstSchema(value: unknown, schema: JSONSchema): string[] {
+  const errors: string[] = [];
+  validateInto(value, schema, 'value', errors);
+  return errors;
+}
+
+function validateInto(
+  value: unknown,
+  schema: JSONSchema,
+  path: string,
+  errors: string[]
+): void {
+  if (!schema || typeof schema !== 'object') return;
+
+  // enum is authoritative — when present, the value must be one of its members.
+  if (Array.isArray(schema.enum)) {
+    if (!schema.enum.some((e) => jsonEqual(e, value))) {
+      errors.push(`${path} must be one of ${JSON.stringify(schema.enum)}`);
+    }
+    return;
+  }
+
+  const types = normalizeTypes(schema);
+  if (types && !types.some((t) => matchesType(value, t))) {
+    errors.push(`${path} must be of type ${types.join(' | ')}`);
+    return; // don't descend into a value of the wrong shape
+  }
+
+  if (isPlainObject(value)) {
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!(key in value)) errors.push(`${path}.${key} is required`);
+      }
+    }
+    if (schema.properties) {
+      for (const [key, sub] of Object.entries(schema.properties)) {
+        if (key in value) validateInto(value[key], sub, `${path}.${key}`, errors);
+      }
+    }
+  }
+
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => validateInto(item, schema.items as JSONSchema, `${path}[${i}]`, errors));
+  }
+}
+
+/** Resolve the declared type(s), inferring object/array from properties/items. */
+function normalizeTypes(schema: JSONSchema): JSONSchemaType[] | null {
+  const t = schema.type;
+  if (typeof t === 'string') return [t];
+  if (Array.isArray(t)) return t;
+  if (schema.properties) return ['object'];
+  if (schema.items) return ['array'];
+  return null;
+}
+
+function matchesType(value: unknown, type: JSONSchemaType): boolean {
+  switch (type) {
+    case 'object':
+      return isPlainObject(value);
+    case 'array':
+      return Array.isArray(value);
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return typeof value === 'number' && Number.isFinite(value);
+    case 'integer':
+      return typeof value === 'number' && Number.isInteger(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'null':
+      return value === null;
+    default:
+      return true;
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function jsonEqual(a: unknown, b: unknown): boolean {
+  return a === b || JSON.stringify(a) === JSON.stringify(b);
+}

package/src/tools.ts

@@ -0,0 +1,126 @@
+import type { JSONSchema, ToolSet } from './types';
+import { extractJson } from './structured';
+
+// ---------------------------------------------------------------------------
+// Pure helpers for generateText() tool calling.
+//
+// Like structured.ts, this module imports no native module so its logic can be
+// unit-tested in plain Node. generateText() (in index.ts) drives the inference
+// + tool-execution loop on top of these.
+//
+// On-device backends have no native tool-call channel, so we define a tiny text
+// protocol: the model emits a JSON object `{"tool": "<name>", "arguments": {…}}`
+// to request a call, or plain text to answer. We parse that back out tolerantly
+// (reusing extractJson), validate the name + args, and run the tool in JS.
+// ---------------------------------------------------------------------------
+
+/** Build the instruction appended to the system prompt to enable tool calling. */
+export function buildToolInstruction(tools: ToolSet): string {
+  const names = Object.keys(tools);
+  const lines: string[] = [
+    'You have access to the following tools. Use one only when it helps answer the request:',
+    '',
+  ];
+  for (const name of names) {
+    const tool = tools[name];
+    lines.push(`- ${name}: ${tool.description}`);
+    lines.push(`  arguments JSON Schema: ${JSON.stringify(tool.parameters)}`);
+  }
+  lines.push(
+    '',
+    'To call a tool, respond with ONLY a JSON object of this exact form and nothing else:',
+    '{"tool": "<tool name>", "arguments": { ... }}',
+    '',
+    'Rules:',
+    '- Call at most one tool per response.',
+    `- "tool" must be exactly one of: ${names.join(', ')}.`,
+    '- "arguments" must conform to that tool\'s arguments JSON Schema.',
+    '- If you do not need a tool, answer the user directly in plain text with no JSON.',
+    '- After you receive a tool result, use it to answer; do not repeat the same call.'
+  );
+  return lines.join('\n');
+}
+
+/**
+ * What {@link parseToolCall} found in a model response.
+ *
+ * - `tool`: a well-formed call to a known tool (args still need schema validation).
+ * - `unknown-tool`: looked like a tool call but the name isn't in the tool set.
+ * - `text`: no tool call — treat the response as the final answer.
+ */
+export type ParsedToolCall =
+  | { kind: 'tool'; toolName: string; args: unknown }
+  | { kind: 'unknown-tool'; toolName: string }
+  | { kind: 'text' };
+
+/**
+ * Detect a tool call in model output.
+ *
+ * A response is a tool call when it contains a JSON object (possibly wrapped in
+ * prose or a ```json fence) with a string `tool` field. We tolerate `arguments`
+ * or `args` for the payload. If `tool` names something not in `toolNames` it's
+ * reported as `unknown-tool` so the loop can re-prompt instead of leaking the
+ * raw JSON as an answer. Anything else is plain `text`.
+ */
+export function parseToolCall(text: string, toolNames: string[]): ParsedToolCall {
+  const parsed = extractJson(text);
+  if (!parsed.ok) return { kind: 'text' };
+
+  const value = parsed.value;
+  if (!isPlainObject(value) || typeof value.tool !== 'string') {
+    return { kind: 'text' };
+  }
+
+  const toolName = value.tool;
+  if (!toolNames.includes(toolName)) {
+    return { kind: 'unknown-tool', toolName };
+  }
+
+  const rawArgs = 'arguments' in value ? value.arguments : value.args;
+  return { kind: 'tool', toolName, args: rawArgs ?? {} };
+}
+
+/** Follow-up prompt when the model named a tool that doesn't exist. */
+export function buildUnknownToolRepair(toolName: string, toolNames: string[]): string {
+  return (
+    `The tool "${toolName}" does not exist. ` +
+    `Available tools are: ${toolNames.join(', ')}. ` +
+    'Either call one of these tools using the required JSON form, or answer in plain text.'
+  );
+}
+
+/** Follow-up prompt when a tool's proposed arguments failed schema validation. */
+export function buildToolArgsRepair(toolName: string, errors: string[]): string {
+  const detail = errors.slice(0, 8).join('; ');
+  return (
+    `The arguments for "${toolName}" did not match its schema: ${detail}. ` +
+    'Respond again with ONLY the corrected {"tool": "' +
+    toolName +
+    '", "arguments": { ... }} JSON — no prose, no markdown code fences.'
+  );
+}
+
+/**
+ * Render a tool result as the user-turn text fed back to the model.
+ * Non-string results are JSON-encoded; strings pass through as-is.
+ */
+export function formatToolResult(toolName: string, result: unknown): string {
+  const body =
+    typeof result === 'string' ? result : safeStringify(result);
+  return `Result of calling the tool "${toolName}":\n${body}`;
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value);
+  } catch {
+    return String(value);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Re-export for callers that want the schema type alongside tool helpers.
+export type { JSONSchema };

package/src/types.ts

@@ -141,6 +141,208 @@ export type LLMStreamEvent = {
 export type LLMStreamCallback = (event: LLMStreamEvent) => void;
 
 
+// ============================================================================
+// Structured Output (generateObject)
+// ============================================================================
+
+/**
+ * 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;
+};
+
+
+// ============================================================================
+// Tool / Function Calling (generateText)
+// ============================================================================
+
+/**
+ * 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;
+};
+
+
 // ============================================================================
 // Model Types
 // ============================================================================