expo-ai-kit 0.6.0 → 0.7.0

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

@@ -219,6 +219,130 @@ export type GenerateObjectResult<T = unknown> = {
 };
 
 
+// ============================================================================
+// 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
 // ============================================================================