Writing Assistance APIs

Draft Community Group Report,

This version:
https://wicg.github.io/writing-assistance-apis
Issue Tracking:
GitHub
Inline In Spec
Editor:
Domenic Denicola (Google)

Abstract

The summarizer, writer, and rewriter APIs provide high-level interfaces to call on a browser or operating system’s built-in language model to help with writing tasks.

Status of this document

This specification was published by the Web Platform Incubator Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1. Introduction

For now, see the explainer.

2. Shared AI APIs and infrastructure

partial interface WindowOrWorkerGlobalScope {
  [Replaceable, SecureContext] readonly attribute AI ai;
};

[Exposed=(Window,Worker), SecureContext]
interface AI {};

[Exposed=(Window,Worker), SecureContext]
interface AICreateMonitor : EventTarget {
  attribute EventHandler ondownloadprogress;
};

callback AICreateMonitorCallback = undefined (AICreateMonitor monitor);

enum AICapabilityAvailability { "readily", "after-download", "no" };

Each WindowOrWorkerGlobalScope has an AI namespace, an AI object. Upon creation of the WindowOrWorkerGlobalScope object, its AI namespace must be set to a new AI object created in the WindowOrWorkerGlobalScope object’s relevant realm.

The ai getter steps are to return this's AI namespace.


Tasks queued by this specification use the AI task source.


The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all AICreateMonitor objects:

Event handler Event handler event type
ondownloadprogress downloadprogress

3. The summarizer API

partial interface AI {
  readonly attribute AISummarizerFactory summarizer;
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerFactory {
  Promise<AISummarizer> create(optional AISummarizerCreateOptions options = {});
  Promise<AISummarizerCapabilities> capabilities();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizer {
  Promise<DOMString> summarize(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );
  ReadableStream summarizeStreaming(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );

  readonly attribute DOMString sharedContext;
  readonly attribute AISummarizerType type;
  readonly attribute AISummarizerFormat format;
  readonly attribute AISummarizerLength length;

  undefined destroy();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerCapabilities {
  readonly attribute AICapabilityAvailability available;

  AICapabilityAvailability createOptionsAvailable(
    optional AISummarizerCreateCoreOptions options = {}
  );
  AICapabilityAvailability languageAvailable(DOMString languageTag);
};

dictionary AISummarizerCreateCoreOptions {
  AISummarizerType type = "key-points";
  AISummarizerFormat format = "markdown";
  AISummarizerLength length = "short";
};

dictionary AISummarizerCreateOptions : AISummarizerCreateCoreOptions {
  AbortSignal signal;
  AICreateMonitorCallback monitor;

  DOMString sharedContext;
};

dictionary AISummarizerSummarizeOptions {
  AbortSignal signal;
  DOMString context;
};

enum AISummarizerType { "tl;dr", "key-points", "teaser", "headline" };
enum AISummarizerFormat { "plain-text", "markdown" };
enum AISummarizerLength { "short", "medium", "long" };

Each AI has an summarizer factory, an AISummarizerFactory object. Upon creation of the AI object, its summarizer factory must be set to a new AISummarizerFactory object created in the AI object’s relevant realm.

The summarizer getter steps are to return this's summarizer factory.

3.1. Creation

The create(options) method steps are:
  1. If this's relevant global object is a Window whose associated Document is not fully active, then return a promise rejected with an "InvalidStateError" DOMException.

  2. If options["signal"] exists and is aborted, then return a promise rejected with options["signal"]'s abort reason.

  3. Let fireProgressEvent be an algorithm taking two arguments that does nothing.

  4. If options["monitor"] exists, then:

    1. Let monitor be a new AICreateMonitor created in this's relevant realm.

    2. Invoke options["monitor"] with « monitor » and "rethrow".

      If an exception e is thrown, return a promise rejected with e.

    3. Set fireProgressEvent to an algorithm taking arguments loaded and total, which performs the following steps:

      1. Assert: this algorithm is running in parallel.

      2. Queue a global task on the AI task source given this's relevant global object to perform the following steps:

        1. Fire an event named downloadprogress at monitor, using ProgressEvent, with the loaded attribute initialized to loaded, the total attribute initialized to total, and the lengthComputable attribute initialized to true.

  5. Let abortedDuringDownload be false.

    This variable will be written to from the event loop, but read from in parallel.

  6. If options["signal"] exists, then add the following abort steps to options["signal"]:

    1. Set abortedDuringDownload to true.

  7. Let promise be a new promise created in this's relevant realm.

  8. In parallel:

    1. Let availability be the current summarizer create options availability given options["type"], options["format"], and options["length"].

    2. Switch on availability:

    null
    1. Reject promise with an "UnknownError" DOMException.

    2. Abort these steps.

    "no"
    1. Reject promise with a "NotSupportedError" DOMException.

    2. Abort these steps.

    "readily"
    1. If initializing the summarization model given promise and options returns false, then abort these steps.

    2. Let totalBytes be the total size of the previously-downloaded summarization capabilities, in bytes.

    3. Assert: totalBytes is greater than 0.

    4. Perform fireProgressEvent given 0 and totalBytes.

    5. Perform fireProgressEvent given totalBytes and totalBytes.

    6. Finalize summarizer creation given promise and options.

    "after-download"
    1. Initiate the download process for everything the user agent needs to summarize text according to options["type"], options["format"], or options["length"].

    2. Run the following steps, by abort when abortedDuringDownload becomes true:

      1. Wait for the total number of bytes to be downloaded to become determined, and let that number be totalBytes.

      2. Let lastProgressTime be the monotonic clock's unsafe current time.

      3. Perform fireProgressEvent given 0 and totalBytes.

      4. While true:

        1. If one or more bytes have been downloaded, then:

          1. If the monotonic clock's unsafe current time minus lastProgressTime is greater than 50 ms, then:

            1. Let bytesSoFar be the number of bytes downloaded so far.

            2. Assert: bytesSoFar is greater than 0 and less than or equal to totalBytes.

            3. Perform fireProgressEvent given bytesSoFar and totalBytes.

            4. If bytesSoFar equals totalBytes, then break.

            5. Set lastProgressTime to the monotonic clock's unsafe current time.

        2. Otherwise, if downloading has failed and cannot continue, then:

          1. Queue a global task on the AI task source given this's relevant global object to reject promise with a "NetworkError" DOMException.

          2. Abort these steps.

    3. If aborted, then:

      1. Queue a global task on the AI task source given this's relevant global object to perform the following steps:

        1. Assert: options["signal"]'s is aborted.

        2. Reject promise with options["signal"]'s abort reason.

      2. Abort these steps.

    4. If initializing the summarization model given promise and options returns false, then abort these steps.

    5. Finalize summarizer creation given promise and options.

  9. Return promise.

To initialize the summarization model, given a Promise promise and an AISummarizerCreateOptions options:
  1. Assert: these steps are running in parallel.

  2. Perform any necessary initialization operations for the AI model backing the user agent's summarization capabilities.

    This could include loading the model into memory, loading options["sharedContext"] into the model’s context window, or loading any fine-tunings necessary to support options["type"], options["format"], or options["length"].

  3. If initialization failed for any reason, then:

    1. Queue a global task on the AI task source given promise’s relevant global object to reject promise with an "OperationError" DOMException.

    2. Return false.

  4. Return true.

To finalize summarizer creation, given a Promise promise and an AISummarizerCreateOptions options:
  1. Assert: these steps are running in parallel.

  2. Assert: the current summarizer create options availability for options["type"], options["format"], and options["length"] is "readily".

  3. Queue a global task on the AI task source given promise’s relevant global object to perform the following steps:

    1. If options["signal"] exists and is aborted, then:

      1. Reject promise with options["signal"]'s abort reason.

      2. Abort these steps.

      This check is necessary in case any code running on the event loop caused the AbortSignal to become aborted before this task ran.

    2. Let summarizer be a new AISummarizer object, created in promise’s relevant realm, with

      shared context

      options["sharedContext"]

      summary type

      options["type"]

      summary format

      options["format"]

      summary length

      options["length"]

    3. If options["signal"] exists, then add the following abort steps to options["signal"]:

      1. Destroy summarizer with options["signal"]'s abort reason.

    4. Resolve promise with summarizer.

3.2. Capabilities

The capabilities() method steps are:
  1. If this's relevant global object is a Window whose associated Document is not fully active, then return a promise rejected with an "InvalidStateError" DOMException.

  2. Let promise be a new promise created in this's relevant realm.

  3. In parallel:

    1. Let availableCreateOptions be a new map from tuples of (AISummarizerType, AISummarizerFormat, AISummarizerLength) values to AICapabilityAvailability values, initially empty.

    2. For each type of AISummarizerType's enumeration values:

      1. For each format of AISummarizerFormat's enumeration values:

        1. For each length of AISummarizerLength's enumeration values:

          1. Set availableCreateOptions[(type, format, length)] to the current summarizer create options availability given type, format, and length.

    3. Let availableLanguages be the current summarizer language availability map.

    4. If availableLanguages is null, or availableCreateOptions’s values contains null, then queue a global task on the AI task source given this to perform the following steps:

      1. Reject promise with an "UnknownError" DOMException.

    5. Otherwise, queue a global task on the AI task source given this to perform the following steps:

      1. Let capabilitiesObject be a new AISummarizerCapabilities object, created in this's relevant realm, with

        available create options

        availableCreateOptions

        available languages

        availableLanguages

      2. Resolve promise with capabilitiesObject.


Every AISummarizerCapabilities has an available create options, a map from tuples of (AISummarizerType, AISummarizerFormat, AISummarizerLength) values to AICapabilityAvailability values, set during creation.

Every AISummarizerCapabilities has an available languages, a map of strings representing BCP 47 language tags to AICapabilityAvailability values, set during creation. The values will never be "no".

The available getter steps are:
  1. If this's available languages are empty, then return "no".

  2. If this's all of this's available create options values are "no", then return "no".

  3. If all of this's available create options's values or all of this's available languages's values are "after-download", then return "after-download".

  4. Return "readily".

The createOptionsAvailable(options) method steps are:
  1. Return this's available create options[(options["type"], options["format"], options["length"])].

The languageAvailable(languageTag) method steps are:
  1. Return this's available languages[languageTag], or "no" if no such entry exists.

Per WICG/translation-api#11 it seems we’re supposed to do something more complex than just straight string comparison for language tags, but it’s not clear what.


The current summarizer create options availability, given a AISummarizerType type, AISummarizerFormat format, and an AISummarizerLength length, is given by the following steps. They return an AICapabilityAvailability value or null.
  1. Assert: this algorithm is running in parallel.

  2. If the user agent supports summarizing text into the type of summary described by type, in the format described by format, and with the length guidance given by length without performing any downloading operations, then return "readily".

  3. If the user agent believes it can summarize text according to type, format, and length, but only after performing a download (e.g., of an AI model or fine-tuning), then return "after-download".

  4. If there is some error attempting to determine whether the user agent supports summarizing text, which the user agent believes to be transient (such that re-querying the current summarizer create options availability could stop producing such an error), then return null.

  5. Otherwise, return "no".

The current summarizer language availability map is given by the following steps. They return a map from strings representing BCP 47 language tags to AICapabilityAvailability values, or null. [RFC5646]
  1. Assert: this algorithm is running in parallel.

  2. If there is some error attempting to determine whether the user agent supports summarizing text, which the user agent believes to be transient (such that re-querying the current summarizer create options availability could stop producing such an error), then return null.

  3. Let availableLanguages be an empty map.

  4. For each human language for which the user agent supports summarizing text written in that language, without performing any downloading operations:

    1. Let languageTag be that language, represented as a BCP 47 language tag string. Describe how to handle subtags.

    2. Set availableLanguages[languageTag] to "readily".

  5. For each human language for which the user agent believes it can summarize text written in that language, but only after performing a download (e.g., of an AI model or fine-tuning):

    1. Let languageTag be that language, represented as a BCP 47 language tag string. Describe how to handle subtags.

    2. Set availableLanguages[languageTag] to "after-download".

  6. Return availableLanguages.

3.3. Summarization

Every AISummarizer has a shared context, a string, set during creation.

Every AISummarizer has a summary type, an AISummarizerType, set during creation.

Every AISummarizer has a summary format, an AISummarizerFormat, set during creation.

Every AISummarizer has a summary length, an AISummarizerLength, set during creation.

The sharedContext getter steps are to return this's shared context.

The type getter steps are to return this's summary type.

The format getter steps are to return this's summary format.

The length getter steps are to return this's summary length.

The destroy() method steps are to destroy this given a new "AbortError" DOMException.

To destroy an AISummarizer summarizer, given a JavaScript value exception:
  1. TODO use summarizer and exception.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[HR-TIME-3]
Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC5646]
A. Phillips, Ed.; M. Davis, Ed.. Tags for Identifying Languages. September 2009. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc5646
[STREAMS]
Adam Rice; et al. Streams Standard. Living Standard. URL: https://streams.spec.whatwg.org/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/
[XHR]
Anne van Kesteren. XMLHttpRequest Standard. Living Standard. URL: https://xhr.spec.whatwg.org/

IDL Index

partial interface WindowOrWorkerGlobalScope {
  [Replaceable, SecureContext] readonly attribute AI ai;
};

[Exposed=(Window,Worker), SecureContext]
interface AI {};

[Exposed=(Window,Worker), SecureContext]
interface AICreateMonitor : EventTarget {
  attribute EventHandler ondownloadprogress;
};

callback AICreateMonitorCallback = undefined (AICreateMonitor monitor);

enum AICapabilityAvailability { "readily", "after-download", "no" };

partial interface AI {
  readonly attribute AISummarizerFactory summarizer;
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerFactory {
  Promise<AISummarizer> create(optional AISummarizerCreateOptions options = {});
  Promise<AISummarizerCapabilities> capabilities();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizer {
  Promise<DOMString> summarize(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );
  ReadableStream summarizeStreaming(
    DOMString input,
    optional AISummarizerSummarizeOptions options = {}
  );

  readonly attribute DOMString sharedContext;
  readonly attribute AISummarizerType type;
  readonly attribute AISummarizerFormat format;
  readonly attribute AISummarizerLength length;

  undefined destroy();
};

[Exposed=(Window,Worker), SecureContext]
interface AISummarizerCapabilities {
  readonly attribute AICapabilityAvailability available;

  AICapabilityAvailability createOptionsAvailable(
    optional AISummarizerCreateCoreOptions options = {}
  );
  AICapabilityAvailability languageAvailable(DOMString languageTag);
};

dictionary AISummarizerCreateCoreOptions {
  AISummarizerType type = "key-points";
  AISummarizerFormat format = "markdown";
  AISummarizerLength length = "short";
};

dictionary AISummarizerCreateOptions : AISummarizerCreateCoreOptions {
  AbortSignal signal;
  AICreateMonitorCallback monitor;

  DOMString sharedContext;
};

dictionary AISummarizerSummarizeOptions {
  AbortSignal signal;
  DOMString context;
};

enum AISummarizerType { "tl;dr", "key-points", "teaser", "headline" };
enum AISummarizerFormat { "plain-text", "markdown" };
enum AISummarizerLength { "short", "medium", "long" };

Issues Index

Per WICG/translation-api#11 it seems we’re supposed to do something more complex than just straight string comparison for language tags, but it’s not clear what.
Describe how to handle subtags.
Describe how to handle subtags.