@swiftbrowser/web 0.18.3 → 0.21.0

package/src/languageModel.ts

@@ -0,0 +1,309 @@
+/**
+ * Foundation Models for a JavaScript app, the page's side (docs/ops-protocol.md,
+ * "The on-device language model"): `LanguageModelSession` in
+ * @swiftbrowser/react sends `languageModel` commands, which natively
+ * FoundationModels answers (packages/native, LanguageModelBridge.swift) and on
+ * a page Chrome's Prompt API (`LanguageModel`), the browser's own on-device
+ * model, where the page has it. Without it the model is unavailable, as on an
+ * iPhone without Apple Intelligence (`deviceNotEligible`).
+ *
+ * - `availability` → `{ status: "available" }` or
+ *   `{ status: "unavailable", reason: "deviceNotEligible" |
+ *   "appleIntelligenceNotEnabled" | "modelNotReady" }` (a model the browser
+ *   can download counts as available, its first prompt starting the download;
+ *   one downloading is not ready). Natively, a model the app fetches itself
+ *   (SwiftBrowserLocalModel) adds `download`: its size, whether it is here,
+ *   a download's progress and failure.
+ * - `download` starts fetching such a model and `deleteDownload` removes it
+ *   (nothing on a page: the browser manages its own model).
+ * - Natively, availability lists `models` to choose from (Apple Intelligence
+ *   where it answers, then an app's own), and `select` picks one.
+ * - `open` may give the session `tools`; natively each `toolCall` answers the
+ *   model's next call (`{ call, name, arguments }`) for the app to run and
+ *   answer with `toolResult`. A page has no tool calls: `toolCall` answers
+ *   `{ closed: true }` and its sessions answer without tools.
+ * - `open` names a session and its instructions; `prewarm` loads it; `close`
+ *   ends it. A session keeps its conversation, as FoundationModels' does.
+ * - `respond` → `{ content }`, the whole response.
+ * - `stream` starts a response; each `next` answers `{ content, done }`, the
+ *   response so far, once it has grown or ended (snapshots, never deltas: a
+ *   slow reader skips what it missed); `cancel` ends it.
+ *
+ * A failure rejects with a tagged message, as FoundationModels'
+ * `GenerationError`: `unavailable: …` (`assetsUnavailable`), `context: …`
+ * (`exceededContextWindowSize`), `guardrail: …` (`guardrailViolation`),
+ * `language: …` (`unsupportedLanguageOrLocale`), `concurrent: …` (a session
+ * asked while it is still responding, `concurrentRequests`), `rateLimited: …`,
+ * `refusal: …`.
+ *
+ * Generation options (`temperature`, `maximumResponseTokens`, `sampling`) are
+ * the native model's; Chrome takes its sampling per session and is left at its
+ * defaults.
+ */
+
+export type LanguageModelUnavailableReason = 'deviceNotEligible' | 'appleIntelligenceNotEnabled' | 'modelNotReady';
+
+/** Where a model the app fetches itself stands (natively, SwiftBrowserLocalModel). */
+export interface LanguageModelDownload {
+  /** In bytes, where known. */
+  size?: number;
+  /** Whether the model is on the device. */
+  downloaded: boolean;
+  /** From 0 to 1 while a download is under way. */
+  progress?: number;
+  /** Why the last download failed, until the next starts. */
+  failure?: string;
+}
+
+/** A model the viewer can choose (natively: Apple Intelligence, an app's own). */
+export interface LanguageModelChoice {
+  id: string;
+  name: string;
+  summary?: string;
+  selected: boolean;
+  download?: LanguageModelDownload;
+}
+
+export type LanguageModelAvailability = ({ status: 'available' } | { status: 'unavailable'; reason: LanguageModelUnavailableReason }) & {
+  download?: LanguageModelDownload;
+  /** The models to choose from, when there is a choice. */
+  models?: LanguageModelChoice[];
+};
+
+/** A tool as the command carries it: its arguments a JSON schema. */
+export interface ToolSpec {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+}
+
+/** `GenerationOptions`, as the command carries them. */
+export interface GenerationOptionsSpec {
+  temperature?: number;
+  maximumResponseTokens?: number;
+  /** `greedy` always picks the likeliest token; `random` (the default) samples. */
+  sampling?: 'greedy' | 'random';
+}
+
+export type LanguageModelCommand =
+  | { action: 'availability' }
+  | { action: 'download' }
+  | { action: 'deleteDownload' }
+  | { action: 'open'; session: number; instructions?: string; tools?: ToolSpec[] }
+  | { action: 'select'; id: string }
+  | { action: 'toolCall'; session: number }
+  | { action: 'toolResult'; session: number; call: number; output?: string; error?: string }
+  | { action: 'prewarm'; session: number }
+  | { action: 'respond'; session: number; prompt: string; options?: GenerationOptionsSpec }
+  | { action: 'stream'; session: number; stream: number; prompt: string; options?: GenerationOptionsSpec }
+  | { action: 'next'; stream: number }
+  | { action: 'cancel'; stream: number }
+  | { action: 'close'; session: number };
+
+/** What answers a `LanguageModelSession`'s commands. */
+export interface LanguageModelHost {
+  perform(command: LanguageModelCommand): Promise<unknown>;
+}
+
+// MARK: Chrome's Prompt API, as much of it as this uses
+
+export type PromptAvailability = 'available' | 'downloadable' | 'downloading' | 'unavailable';
+
+export interface PromptSessionLike {
+  prompt(input: string, options?: { signal?: AbortSignal }): Promise<string>;
+  promptStreaming(input: string, options?: { signal?: AbortSignal }): AsyncIterable<string>;
+  destroy(): void;
+}
+
+export interface PromptAPI {
+  availability(): Promise<PromptAvailability>;
+  create(options: { initialPrompts?: { role: 'system'; content: string }[] }): Promise<PromptSessionLike>;
+}
+
+/** Chrome's `LanguageModel`, where the page has it. */
+export function browserPromptAPI(): PromptAPI | undefined {
+  const api = (globalThis as unknown as { LanguageModel?: PromptAPI }).LanguageModel;
+  return api && typeof api.create === 'function' && typeof api.availability === 'function' ? api : undefined;
+}
+
+// MARK: The host
+
+interface SessionState {
+  instructions: string | undefined;
+  model: Promise<PromptSessionLike> | undefined;
+  responding: boolean;
+}
+
+interface StreamState {
+  content: string;
+  done: boolean;
+  error: unknown;
+  /** Whether the reader has had the content as it is now. */
+  delivered: boolean;
+  /** Wakes a `next` waiting for the content to grow. */
+  wake: (() => void) | undefined;
+  abort: AbortController;
+}
+
+const UNAVAILABLE = 'unavailable: the on-device language model is not available in this browser';
+
+/** A failure of Chrome's, tagged as FoundationModels' `GenerationError` would be. */
+function tagged(error: unknown): Error {
+  const name = error instanceof Error || (typeof DOMException !== 'undefined' && error instanceof DOMException) ? (error as Error).name : '';
+  const message = error instanceof Error ? error.message : String(error);
+  if (/^(unavailable|context|guardrail|language|concurrent|rateLimited|refusal):/.test(message)) return new Error(message);
+  switch (name) {
+    case 'QuotaExceededError':
+      return new Error(`context: ${message}`);
+    case 'NotSupportedError':
+      return new Error(`language: ${message}`);
+    case 'NotAllowedError':
+    case 'NotReadableError':
+      return new Error(`unavailable: ${message}`);
+    default:
+      return error instanceof Error ? error : new Error(message);
+  }
+}
+
+/**
+ * The commands over a Prompt API (`browserPromptAPI()`, or a stand-in in
+ * tests); without one every session fails with `unavailable`.
+ */
+export class PromptLanguageModel implements LanguageModelHost {
+  private readonly sessions = new Map<number, SessionState>();
+  private readonly streams = new Map<number, StreamState>();
+
+  constructor(private readonly api: PromptAPI | undefined) {}
+
+  async perform(command: LanguageModelCommand): Promise<unknown> {
+    switch (command.action) {
+      case 'availability':
+        return this.availability();
+      case 'download':
+      case 'deleteDownload':
+      case 'select':
+      case 'toolResult':
+        // The browser fetches and keeps its own model, of which there is one.
+        return {};
+      case 'toolCall':
+        // Chrome's model calls no tools here.
+        return { closed: true };
+      case 'open':
+        this.sessions.set(command.session, { instructions: command.instructions, model: undefined, responding: false });
+        return {};
+      case 'prewarm':
+        if (this.api) this.model(command.session).catch(() => {});
+        return {};
+      case 'respond':
+        return { content: await this.respond(command.session, command.prompt) };
+      case 'stream':
+        this.stream(command.session, command.stream, command.prompt);
+        return {};
+      case 'next':
+        return this.next(command.stream);
+      case 'cancel': {
+        const stream = this.streams.get(command.stream);
+        if (stream && !stream.done) {
+          stream.abort.abort();
+          this.finish(stream);
+        }
+        return {};
+      }
+      case 'close': {
+        const session = this.sessions.get(command.session);
+        this.sessions.delete(command.session);
+        session?.model?.then((model) => model.destroy()).catch(() => {});
+        return {};
+      }
+      default:
+        throw new Error(`unsupported: languageModel action ${String((command as { action: unknown }).action)}`);
+    }
+  }
+
+  private async availability(): Promise<LanguageModelAvailability> {
+    if (!this.api) return { status: 'unavailable', reason: 'deviceNotEligible' };
+    const availability = await this.api.availability();
+    // A model the browser can download is ready to use: the first prompt
+    // (a tap, which a download needs) starts it. One already downloading is
+    // not ready yet, as Apple Intelligence's model while it downloads.
+    if (availability === 'available' || availability === 'downloadable') return { status: 'available' };
+    if (availability === 'downloading') return { status: 'unavailable', reason: 'modelNotReady' };
+    return { status: 'unavailable', reason: 'deviceNotEligible' };
+  }
+
+  /** The session's Prompt API session, made on first use with its instructions. */
+  private model(id: number): Promise<PromptSessionLike> {
+    const session = this.sessions.get(id);
+    if (!session) return Promise.reject(new Error(`languageModel: no session ${id}`));
+    if (!this.api) return Promise.reject(new Error(UNAVAILABLE));
+    if (!session.model) {
+      const instructions = session.instructions?.trim();
+      session.model = this.api.create(instructions ? { initialPrompts: [{ role: 'system', content: instructions }] } : {});
+      session.model.catch(() => {
+        session.model = undefined;
+      });
+    }
+    return session.model;
+  }
+
+  /** Marks the session responding for the length of `work`, refusing a second request meanwhile. */
+  private async responding<T>(id: number, work: (model: PromptSessionLike) => Promise<T>): Promise<T> {
+    const session = this.sessions.get(id);
+    if (!session) throw new Error(`languageModel: no session ${id}`);
+    if (session.responding) throw new Error('concurrent: the session is still responding to a prompt');
+    session.responding = true;
+    try {
+      return await work(await this.model(id));
+    } catch (error) {
+      throw tagged(error);
+    } finally {
+      session.responding = false;
+    }
+  }
+
+  private respond(id: number, prompt: string): Promise<string> {
+    return this.responding(id, (model) => model.prompt(prompt));
+  }
+
+  private stream(id: number, streamId: number, prompt: string): void {
+    const stream: StreamState = { content: '', done: false, error: undefined, delivered: true, wake: undefined, abort: new AbortController() };
+    this.streams.set(streamId, stream);
+    this.responding(id, async (model) => {
+      for await (const chunk of model.promptStreaming(prompt, { signal: stream.abort.signal })) {
+        if (stream.done) break;
+        // Chrome has sent the response so far and, since, what it added: take either.
+        stream.content = stream.content && chunk.startsWith(stream.content) ? chunk : stream.content + chunk;
+        stream.delivered = false;
+        stream.wake?.();
+      }
+    }).then(
+      () => this.finish(stream),
+      (error: unknown) => {
+        if (!stream.abort.signal.aborted) stream.error = error;
+        this.finish(stream);
+      },
+    );
+  }
+
+  private finish(stream: StreamState): void {
+    stream.done = true;
+    stream.delivered = false;
+    stream.wake?.();
+  }
+
+  private async next(id: number): Promise<{ content: string; done: boolean }> {
+    const stream = this.streams.get(id);
+    if (!stream) throw new Error(`languageModel: no stream ${id}`);
+    while (stream.delivered) await new Promise<void>((resolve) => (stream.wake = resolve));
+    stream.wake = undefined;
+    stream.delivered = true;
+    if (stream.done) this.streams.delete(id);
+    if (stream.error !== undefined) throw stream.error;
+    return { content: stream.content, done: stream.done };
+  }
+}
+
+/** The page's language model: Chrome's, or none (every session `unavailable`). */
+export function browserLanguageModel(): LanguageModelHost {
+  return new PromptLanguageModel(browserPromptAPI());
+}