1. Introduction
For now, see the explainer .
2. Shared APIs
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 {
AIAvailability ,
"unavailable" ,
"downloadable" ,
"downloading" };
"available" interface mixin {
AIDestroyable undefined destroy (); };
Every
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
.
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
|
Every
interface
including
the
AIDestroyable
interface
mixin
has
a
destruction
abort
controller
,
an
AbortController
,
set
by
the
initialize
as
a
destroyable
algorithm.
The
destruction
abort
controller
is
only
used
internally,
as
a
way
of
tracking
calls
to
destroy()
.
Since
it
is
easy
to
combine
multiple
AbortSignal
s
using
create
a
dependent
abort
signal
,
this
lets
us
centralize
handling
of
any
AbortSignal
the
web
developer
provides
to
specific
method
calls,
with
any
calls
to
destroy()
.
AIDestroyable
object
destroyable
:
-
Let controller be a new
AbortController
created in destroyable ’s relevant realm . -
Set controller ’s signal to a new
AbortSignal
created in destroyable ’s relevant realm . -
Set destroyable ’s destruction abort controller to controller .
The
destroy()
method
steps
are
to
destroy
this
given
a
new
"
AbortError
"
DOMException
.
AIDestroyable
destroyable
,
given
a
JavaScript
value
reason
:
-
Signal abort given destroyable ’s destruction abort controller and reason .
-
The user agent should release any resources associated with destroyable , such as AI models loaded to support its operation, as long as those resources are not needed for other ongoing operations.
3. The summarizer API
partial interface AI {readonly attribute AISummarizerFactory summarizer ; }; [Exposed =(Window ,Worker ),SecureContext ]interface {
AISummarizerFactory Promise <AISummarizer >create (optional AISummarizerCreateOptions = {});
options Promise <AIAvailability >availability (optional AISummarizerCreateCoreOptions = {}); }; [
options 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 ;readonly attribute FrozenArray <DOMString >?expectedInputLanguages ;readonly attribute FrozenArray <DOMString >?expectedContextLanguages ;readonly attribute DOMString ?outputLanguage ;Promise <double >measureInputUsage (DOMString ,
input optional AISummarizerSummarizeOptions = {} );
options readonly attribute unrestricted double inputQuota ; };AISummarizer includes AIDestroyable ;dictionary {
AISummarizerCreateCoreOptions AISummarizerType = "key-points";
type AISummarizerFormat = "markdown";
format AISummarizerLength = "short";
length ; ; ;sequence <DOMString >;
expectedInputLanguages sequence <DOMString >;
expectedContextLanguages DOMString ; };
outputLanguage dictionary :
AISummarizerCreateOptions AISummarizerCreateCoreOptions {AbortSignal ;
signal AICreateMonitorCallback ;
monitor ;DOMString ; };
sharedContext dictionary {
AISummarizerSummarizeOptions AbortSignal ;
signal ;DOMString ; };
context enum {
AISummarizerType "tl;dr" ,"teaser" ,"key-points" ,"headline" };enum {
AISummarizerFormat "plain-text" ,"markdown" };enum {
AISummarizerLength "short" ,"medium" ,"long" };
Every
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
create(
options
)
method
steps
are:
-
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
. -
If options ["
signal
"] exists and is aborted , then return a promise rejected with options ["signal
"]'s abort reason . -
Validate and canonicalize summarizer options given options . If this throws an exception e , catch it, and return a promise rejected with e .
This can mutate options .
-
Return the result of creating an AI model object given this ’s relevant realm , options , computing summarizer options availability , download the summarization model , initialize the summarization model , and create a summarizer object .
AISummarizerCreateCoreOptions
options
,
perform
the
following
steps.
They
mutate
options
in
place
to
canonicalize
and
deduplicate
language
tags,
and
throw
a
TypeError
if
any
are
invalid.
-
Validate and canonicalize language tags given options and "
expectedInputLanguages
". -
Validate and canonicalize language tags given options and "
expectedContextLanguages
". -
Validate and canonicalize language tags given options and "
outputLanguage
".
AISummarizerCreateCoreOptions
options
:
-
Assert : these steps are running in parallel .
-
Initiate the download process for everything the user agent needs to summarize text according to options . This could include a base AI model, fine-tunings for specific languages or option values, or other resources.
-
If the download process cannot be started for any reason, then return false.
-
Return true.
AISummarizerCreateOptions
options
:
-
Assert : these steps are running in parallel .
-
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 the other options expressed by options . -
If initialization failed because the process of loading options resulted in using up all of the model’s input quota, then:
Let requested be the amount of input usage needed to encode options . The encoding of options as input is implementation-defined .
This could be the amount of tokens needed to represent these options in a language model tokenization scheme , possibly with prompt engineering. Or it could be 0, if the implementation plans to send the options to the underlying model with every summarize operation.
Let quota be the maximum input quota that the user agent supports for encoding options .
Assert : requested is greater than quota . (That is how we reached this error branch.)
Return a quota exceeded error information whose requested is requested and quota is quota .
If initialization failed for any other reason, then return
false.a DOMException error information whose name is "OperationError
" and whose details contain appropriate detail.-
Return
true.null.
AISummarizerCreateOptions
options
:
-
Assert : these steps are running on realm ’s surrounding agent ’s event loop .
-
Let inputQuota be the amount of input quota that is available to the user agent for future summarization operations. (This value is implementation-defined , and may be +∞ if there are no specific limits beyond, e.g., the user’s memory, or the limits of JavaScript strings.)
For implementations that do not have infinite quota, this will generally vary for each
AISummarizer
instance, depending on how much input quota was used by encoding options . See this note on that encoding. Return a new
AISummarizer
object, created in realm , with- shared context
-
options ["
sharedContext
"] if it exists ; otherwise null - summary type
-
options ["
type
"] - summary format
-
options ["
format
"] - summary length
-
options ["
length
"] - expected input languages
-
the result of creating a frozen array given options ["
expectedInputLanguages
"] if it is not empty ; otherwise null - expected context languages
-
the result of creating a frozen array given options ["
expectedContextLanguages
"] if it is not empty ; otherwise null - output language
-
options ["
outputLanguage
"] if it exists ; otherwise null - input quota
inputQuota
3.2. Availability
availability(
options
)
method
steps
are:
-
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
. -
Validate and canonicalize summarizer options given options .
-
Let promise be a new promise created in this ’s relevant realm .
-
-
Let availability be the result of computing summarizer options availability given options .
-
Queue a global task on the AI task source given this ’s relevant global object to perform the following steps:
-
If availability is null, then reject promise with an "
UnknownError
"DOMException
. -
Otherwise, resolve promise with availability .
-
-
AISummarizerCreateCoreOptions
options
,
perform
the
following
steps.
They
return
either
an
AIAvailability
value
or
null,
and
they
mutate
options
in
place
to
update
language
tags
to
their
best-fit
matches.
-
Assert : this algorithm is running in parallel .
-
Let availability be the summarizer non-language options availability given options ["
type
"], options ["format
"], and options ["length
"]. -
Let languageAvailabilities be the summarizer language availabilities .
-
If languageAvailabilities is null, then return null.
-
Let inputLanguageAvailability be the result of computing summarizer language availability given options ["
expectedInputLanguages
"] and languageAvailabilities ’s input languages . -
Let contextLanguagesAvailability be the result of computing summarizer language availability given options ["
expectedContextLanguages
"] and languageAvailabilities ’s context languages . -
Let outputLanguagesList be « options ["
outputLanguage
"] ». -
Let outputLanguageAvailability be the result of computing summarizer language availability given outputLanguagesList and languageAvailabilities ’s output languages .
-
Set options ["
outputLanguage
"] to outputLanguagesList [0]. -
Return the minimum availability given « availability , inputLanguageAvailability , contextLanguagesAvailability , outputLanguageAvailability ».
AIAvailability
values
to
sets
of
strings
availabilities
,
perform
the
following
steps.
They
return
an
AIAvailability
value,
and
they
mutate
requestedLanguages
in
place
to
update
language
tags
to
their
best-fit
matches.
-
Let availability be "
available
". -
For each language of requestedLanguages :
-
For each availabilityToCheck of « "
available
", "downloading
", "downloadable
" »:-
Let languagesWithThisAvailability be availabilities [ availabilityToCheck ].
-
Let bestMatch be LookupMatchingLocaleByBestFit ( languagesWithThisAvailability , « language »).
-
If bestMatch is not undefined, then:
-
Replace language with bestMatch .[[locale]] in requestedLanguages .
-
Set availability to the minimum availability given availability and availabilityToCheck .
-
Break .
-
-
-
Return "
unavailable
".
-
-
Return availability .
AISummarizerType
type
,
AISummarizerFormat
format
,
and
an
AISummarizerLength
length
,
is
given
by
the
following
steps.
They
return
an
AIAvailability
value
or
null.
-
Assert : this algorithm is running in parallel .
-
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 summarizer non-language options availability could stop producing such an error), then return null.
-
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 "
available
". -
If the user agent believes it can summarize text according to type , format , and length , but only after finishing a download (e.g., of an AI model or fine-tuning) that is already ongoing, then return "
downloadable
". -
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 "
downloadable
". -
Otherwise, return "
unavailable
".
A language availabilities is a struct with the following items :
-
input languages
-
context languages
-
output languages
All
of
these
items
are
maps
from
AIAvailability
values
to
sets
of
strings
representing
Unicode
canonicalized
locale
identifiers
.
Their
keys
will
always
be
one
of
"
downloading
",
"
downloadable
",
or
"
available
"
(i.e.,
they
will
never
be
"
unavailable
").
[ECMA-402]
-
Assert : this algorithm is running in parallel .
-
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 summarizer language availabilities could stop producing such an error), then return null.
-
Return a language availabilities with:
- input languages
-
the result of getting language availabilities given the purpose of summarizing text written in that language
- context languages
-
the result of getting language availabilities given the purpose of summarizing text using web-developer provided context information written in that language
- output languages
-
the result of getting language availabilities given the purpose of producing text summaries in that language
One
way
this
could
be
implemented
would
be
for
summarizer
language
availabilities
to
return
that
"
zh-Hant
"
is
in
the
input
languages
["
available
"]
set,
and
"
zh
"
and
"
zh-Hans
"
are
in
the
input
languages
["
downloadable
"]
set.
This
return
value
conforms
to
the
requirements
of
the
language
tag
set
completeness
rules
,
in
ensuring
that
"
zh
"
is
present.
Per
the
"should"-level
guidance
,
the
implementation
has
determined
that
"
zh
"
belongs
in
the
set
of
downloadable
input
languages,
with
"
zh-Hans
",
instead
of
in
the
set
of
available
input
languages,
with
"
zh-Hant
".
Combined
with
the
use
of
LookupMatchingLocaleByBestFit
,
this
means
availability()
will
give
the
following
answers:
function a( languageTag) { return ai. summarizer. availability({ expectedInputLanguages: [ languageTag] }); } await a( "zh" ) === "downloadable" ; await a( "zh-Hant" ) === "available" ; await a( "zh-Hans" ) === "downloadable" ; await a( "zh-TW" ) === "available" ; // zh-TW will best-fit to zh-Hant await a( "zh-HK" ) === "available" ; // zh-HK will best-fit to zh-Hant await a( "zh-CN" ) === "downloadable" ; // zh-CN will best-fit to zh-Hans await a( "zh-BR" ) === "downloadable" ; // zh-BR will best-fit to zh await a( "zh-Kana" ) === "downloadable" ; // zh-Kana will best-fit to zh
3.3.
The
AISummarizer
class
Every
AISummarizer
has
a
shared
context
,
a
string
-or-null,
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.
Every
AISummarizer
has
an
expected
input
languages
,
a
or
null,
set
during
creation.
FrozenArray
<
DOMString
>
Every
AISummarizer
has
an
expected
context
languages
,
a
or
null,
set
during
creation.
FrozenArray
<
DOMString
>
Every
AISummarizer
has
an
output
language
,
a
string
or
null,
set
during
creation.
Every
AISummarizer
has
a
input
quota
,
a
number,
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
expectedInputLanguages
getter
steps
are
to
return
this
’s
expected
input
languages
.
The
expectedContextLanguages
getter
steps
are
to
return
this
’s
expected
context
languages
.
The
outputLanguage
getter
steps
are
to
return
this
’s
output
language
.
The
inputQuota
getter
steps
are
to
return
this
’s
input
quota
.
summarize(
input
,
options
)
method
steps
are:
-
Let context be options ["
context
"] if it exists ; otherwise null. -
Let operation be an algorithm step which takes arguments chunkProduced , done , error , and stopProducing , and summarizes input given this ’s shared context , context , this ’s summary type , this ’s summary format , this ’s summary length , this ’s output language , this ’s input quota , chunkProduced , done , error , and stopProducing .
-
Return the result of getting an aggregated AI model result given this , options , and operation .
summarizeStreaming(
input
,
options
)
method
steps
are:
-
Let context be options ["
context
"] if it exists ; otherwise null. -
Let operation be an algorithm step which takes arguments chunkProduced , done , error , and stopProducing , and summarizes input given this ’s shared context , context , this ’s summary type , this ’s summary format , this ’s summary length , this ’s output language , this ’s input quota , chunkProduced , done , error , and stopProducing .
-
Return the result of getting a streaming AI model result given this , options , and operation .
measureInputUsage(
input
,
options
)
method
steps
are:
Let context be options ["
context
"] if it exists ; otherwise null.Let measureUsage be an algorithm step which takes argument stopMeasuring , and returns the result of measuring summarizer input usage given input , this ’s shared context , context , this ’s summary type , this ’s summary format , this ’s summary length , this ’s output language , and stopMeasuring .
Return the result of measuring AI model input usage given this , options , and measureUsage .
3.4. Summarization
3.4.1. The algorithm
-
a string input ,
-
a string -or-null sharedContext ,
-
a string -or-null context ,
-
an
AISummarizerType
type , -
an
AISummarizerFormat
format , -
an
AISummarizerLength
length , -
a string -or-null outputLanguage ,
-
a number inputQuota ,
an algorithm chunkProduced that takes a string and returns nothing,
-
an algorithm done that takes no arguments and returns nothing,
-
an algorithm error that takes error information and returns nothing, and
-
an algorithm stopProducing that takes no arguments and returns a boolean,
perform the following steps:
-
Assert : this algorithm is running in parallel .
-
Let requested be the result of measuring summarizer input usage given input , sharedContext , context , type , format , length , and outputLanguage .
If requested is null, then return.
If requested is an error information , then:
Perform error given requested .
Return.
Assert : requested is a number.
If requested is greater than inputQuota , then:
Let errorInfo be a quota exceeded error information with a requested of requested and a quota of inputQuota .
Perform error given errorInfo .
Return.
In reality, we expect that implementations will check the input usage against the quota as part of the same call into the model as the summarization itself. The steps are only separated in the specification for ease of understanding.
In an implementation-defined manner, subject to the following guidelines, begin the processs of summarizing input into a string.
If they are non-null, sharedContext and context should be used to aid in the summarization by providing context on how the web developer wishes the input to be summarized.
If input is the empty string, or otherwise consists of no summarizable content (e.g., only contains whitespace, or control characters), then the resulting summary should be the empty string. In such cases, sharedContext , context , type , format , length , and outputLanguage should be ignored.
The summarization should conform to the guidance given by type , format , and length , in the definitions of each of their enumeration values.
If outputLanguage is non-null, the summarization should be in that language. Otherwise, it should be in the language of input (which might not match that of context or sharedContext ). If input contains multiple languages, or the language of input cannot be detected, then either the output language is implementation-defined , or the implementation may treat this as an error, per the guidance in
§ 3.4.3§ 3.4.4 Errors .-
While true:
-
Wait for the next chunk of summarization data to be produced, for the summarization process to finish, or for the result of calling stopProducing to become true.
-
If such a chunk is successfully produced:
-
Let it be represented as a string chunk .
-
Perform chunkProduced given chunk .
-
-
Otherwise, if the summarization process has finished:
-
Perform done .
-
Break .
-
-
Otherwise, if stopProducing returns true, then break .
-
Otherwise, if an error occurred during summarization:
-
Let the error be represented as error information errorInfo according to the guidance in
§ 3.4.3§ 3.4.4 Errors . -
Perform error given errorInfo .
-
Break .
-
-
3.4.2. Usage
a string input ,
a string -or-null sharedContext ,
a string -or-null context ,
an
AISummarizerType
type ,an
AISummarizerFormat
format ,an
AISummarizerLength
length ,a string -or-null outputLanguage , and
an algorithm stopMeasuring that takes no arguments and returns a boolean,
perform the following steps:
Assert : this algorithm is running in parallel .
Let inputToModel be the implementation-defined string that would be sent to the underlying model in order to summarize given input , sharedContext , context , type , format , length , and outputLanguage .
This might be something similar to the concatenation of input and context , if all of the other options were loaded into the model during initialization, and so the input usage for those was already accounted for when computing the input quota . Or it might consist of more, if the options are sent along with every summarization call, or if there is a per-summarization wrapper prompt of some sort.
If during this process stopMeasuring starts returning true, then return null.
If an error occurs during this process, then return an appropriate error information according to the guidance in § 3.4.4 Errors .
Return the amount of input usage needed to represent inputToModel when given to the underlying model. The exact calculation procedure is implementation-defined , subject to the following constraints.
The returned input usage must be nonnegative and finite. It must be 0, if there are no usage quotas for the summarization process (i.e., if the input quota is +∞). Otherwise, it must be positive and should be roughly proportional to the length of inputToModel .
This might be the number of tokens needed to represent input in a language model tokenization scheme , or it might be input ’s length . It could also be some variation of these which also counts the usage of any prefixes or suffixes necessary to give to the model.
If during this process stopMeasuring starts returning true, then instead return null.
If an error occurs during this process, then instead return an appropriate error information according to the guidance in § 3.4.4 Errors .
3.4.3. Options
The
summarize
algorithm’s
details
are
implementation-defined
,
as
they
are
expected
to
be
powered
by
an
AI
model.
However,
it
is
intended
to
be
controllable
by
the
web
developer
through
the
AISummarizerType
,
AISummarizerFormat
,
and
AISummarizerLength
enumerations.
This section gives normative guidance on how the implementation of summarize should use each enumeration value to guide the summarization process.
Value | Meaning |
---|---|
"
tl;dr
"
|
The summary should be short and to the point, providing a quick overview of the input, suitable for a busy reader. |
"
teaser
"
|
The summary should focus on the most interesting or intriguing parts of the input, designed to draw the reader in to read more. |
"
key-points
"
|
The summary should extract the most important points from the input, presented as a bulleted list. |
"
headline
"
|
The summary should effectively contain the main point of the input in a single sentence, in the format of an article headline. |
Value | Meaning |
---|---|
"
short
"
|
The
guidance
is
dependent
on
the
value
of
|
"
medium
"
|
The
guidance
is
dependent
on
the
value
of
|
"
long
"
|
The
guidance
is
dependent
on
the
value
of
|
As with all " should "-level guidance, user agents might not conform perfectly to these. Especially in the case of counting words, it’s expected that language models might not conform perfectly.
Value | Meaning |
---|---|
"
plain-text
"
|
The summary should not contain any formatting or markup language. |
"
markdown
"
|
The summary should be formatted using the Markdown markup language, ideally as valid CommonMark. [COMMONMARK] |
3.4.3.
3.4.4.
Errors
When
summarization
fails,
the
following
possible
reasons
may
be
surfaced
to
the
web
developer.
This
table
lists
the
possible
DOMException
names
and
the
cases
in
which
an
implementation
should
use
them:
DOMException
name
| Scenarios |
---|---|
"
NotAllowedError
"
|
Summarization is disabled by user choice or user agent policy. |
"
NotReadableError
"
|
The summarization output was filtered by the user agent, e.g., because it was detected to be harmful, inaccurate, or nonsensical. |
"
NotSupportedError
"
|
The
input
to
be
summarized,
or
the
context
to
be
provided,
was
in
a
language
that
the
user
agent
does
not
support,
or
was
not
provided
properly
in
the
call
to
The
summarization
output
ended
up
being
in
a
language
that
the
user
agent
does
not
support
(e.g.,
because
the
user
agent
has
not
performed
sufficient
quality
control
tests
on
that
output
language),
or
was
not
provided
properly
in
the
call
to
The
|
"
"
|
All other scenarios, or if the user agent would prefer not to disclose the failure reason. |
This
table
does
not
give
the
complete
list
of
exceptions
that
can
be
surfaced
by
summarizer.summarize()
and
summarizer.summarizeStreaming()
.
the
summarizer
API.
It
only
contains
those
which
can
come
from
the
certain
implementation-defined
summarize
algorithm.
steps.
4. The writer API
Just IDL for now; full spec coming!
[Exposed =(Window ,Worker ),SecureContext ]interface {
AIWriterFactory = {}); = {});Promise <AIWriter >(
create optional AIWriterCreateOptions = {});
options Promise <AIAvailability >(
availability optional AIWriterCreateCoreOptions = {}); }; [
options Exposed =(Window ,Worker ),SecureContext ]interface {
AIWriter = {}); = {});Promise <DOMString >(
write DOMString ,
writingTask optional AIWriterWriteOptions = {});
options ReadableStream (
writeStreaming DOMString ,
writingTask optional AIWriterWriteOptions = {});
options ;readonly attribute DOMString ;
sharedContext readonly attribute AIWriterTone ;
tone readonly attribute AIWriterFormat ;
format readonly attribute AIWriterLength ;
length ; ; ;readonly attribute FrozenArray <DOMString >?;
expectedInputLanguages readonly attribute FrozenArray <DOMString >?;
expectedContextLanguages readonly attribute DOMString ?;
outputLanguage Promise <double >(
measureInputUsage DOMString ,
input optional AIWriterWriteOptions = {} );
options readonly attribute unrestricted double ; };
inputQuota AIWriter includes AIDestroyable ;dictionary {
AIWriterCreateCoreOptions AIWriterTone = "neutral";
tone AIWriterFormat = "markdown";
format AIWriterLength = "short";
length ; ; ;sequence <DOMString >;
expectedInputLanguages sequence <DOMString >;
expectedContextLanguages DOMString ; };
outputLanguage dictionary :
AIWriterCreateOptions AIWriterCreateCoreOptions {AbortSignal ;
signal AICreateMonitorCallback ;
monitor ;DOMString ; };
sharedContext dictionary {
AIWriterWriteOptions ;DOMString ;
context AbortSignal ; };
signal enum {
AIWriterTone ,
"formal" ,
"neutral" };
"casual" enum {
AIWriterFormat ,
"plain-text" };
"markdown" enum {
AIWriterLength ,
"short" ,
"medium" };
"long"
5. The rewriter API
Just IDL for now; full spec coming!
[Exposed =(Window ,Worker ),SecureContext ]interface {
AIRewriterFactory = {}); = {});Promise <AIRewriter >(
create optional AIRewriterCreateOptions = {});
options Promise <AIAvailability >(
availability optional AIRewriterCreateCoreOptions = {}); }; [
options Exposed =(Window ,Worker ),SecureContext ]interface {
AIRewriter = {}); = {});Promise <DOMString >(
rewrite DOMString ,
input optional AIRewriterRewriteOptions = {});
options ReadableStream (
rewriteStreaming DOMString ,
input optional AIRewriterRewriteOptions = {});
options ;readonly attribute DOMString ;
sharedContext readonly attribute AIRewriterTone ;
tone readonly attribute AIRewriterFormat ;
format readonly attribute AIRewriterLength ;
length ; ; ;readonly attribute FrozenArray <DOMString >?;
expectedInputLanguages readonly attribute FrozenArray <DOMString >?;
expectedContextLanguages readonly attribute DOMString ?;
outputLanguage Promise <double >(
measureInputUsage DOMString ,
input optional AIRewriterRewriteOptions = {} );
options readonly attribute unrestricted double ; };
inputQuota AIRewriter includes AIDestroyable ;dictionary {
AIRewriterCreateCoreOptions AIRewriterTone = "as-is";
tone AIRewriterFormat = "as-is";
format AIRewriterLength = "as-is";
length ; ; ;sequence <DOMString >;
expectedInputLanguages sequence <DOMString >;
expectedContextLanguages DOMString ; };
outputLanguage dictionary :
AIRewriterCreateOptions AIRewriterCreateCoreOptions {AbortSignal ;
signal AICreateMonitorCallback ;
monitor ;DOMString ; };
sharedContext dictionary {
AIRewriterRewriteOptions ;DOMString ;
context AbortSignal ; };
signal enum {
AIRewriterTone ,
"as-is" ,
"more-formal" };
"more-casual" enum {
AIRewriterFormat ,
"as-is" ,
"plain-text" };
"markdown" enum {
AIRewriterLength ,
"as-is" ,
"shorter" };
"longer"
6. Shared infrastructure
6.1. Creation
-
a realm realm ,
-
an ordered map options ,
-
an algorithm getAvailability taking an ordered map and returning an
AIAvailability
or null, -
an algorithm startDownload taking an ordered map and returning a boolean,
-
an algorithm initialize taking an ordered map and returning
a boolean,an error information or null, and -
an algorithm create taking a realm and an ordered map and returning a Web IDL object representing the model,
perform the following steps:
-
Let fireProgressEvent be an algorithm taking two arguments that does nothing.
-
If options ["
monitor
"] exists , then:-
Let monitor be a new
AICreateMonitor
created in realm . -
Invoke options ["
monitor
"] with « monitor » and "rethrow
".If this throws an exception e , catch it, and return a promise rejected with e .
-
Set fireProgressEvent to an algorithm taking argument loaded , which performs the following steps:
-
Assert : this algorithm is running in parallel .
-
Queue a global task on the AI task source given realm ’s global object to perform the following steps:
-
Fire an event named
downloadprogress
at monitor , usingProgressEvent
, with theloaded
attribute initialized to loaded , thetotal
attribute initialized to 1, and thelengthComputable
attribute initialized to true.This assumes whatwg/xhr#394 is merged so that passing non-integer values for
loaded
works as expected.
-
-
-
-
Let abortedDuringDownload be false.
This variable will be written to from the event loop , but read from in parallel .
-
If options ["
signal
"] exists , then add the following abort steps to options ["signal
"]:-
Set abortedDuringDownload to true.
-
-
Let promise be a new promise created in realm .
-
-
Let availability be the result of performing getAvailability given options .
This can mutate options .
-
Switch on availability :
- null
-
-
Reject promise with an "
UnknownError
"DOMException
. -
Abort these steps.
-
-
"
unavailable
" -
-
Reject promise with a "
NotSupportedError
"DOMException
. -
Abort these steps.
-
-
"
available
" -
-
Initialize and return an AI model object given promise , options , fireProgressEvent , initialize , and create .
-
-
"
downloading
"- "
downloadable
" - "
-
-
If availability is "
downloadable
", then let startDownloadResult be the result of performing startDownload given options . -
If startDownloadResult is false, then:
-
Queue a global task on the AI task source given realm ’s global object to reject promise with a "
NetworkError
"DOMException
. -
Abort these steps.
-
-
Run the following steps, but abort when abortedDuringDownload becomes true:
-
Wait for the total number of bytes to be downloaded to become determined, and let that number be totalBytes .
This number must be equal to the number of bytes that the user agent needs to download at the present time, not including any that have already been downloaded.
For example, if another tab has started the download and it is 90% finished, and the user agent is planning to share the model across all tabs, then totalBytes will be 10% of the size of the model, not 100% of the size of the model.
This prevents the web developer-perceived progress from suddenly jumping from 0% to 90%, and then taking a long time to go from 90% to 100%. It also provides some protection against the (admittedly not very powerful) fingerprinting vector of measuring the current download progress across multiple sites.
-
Let lastProgressFraction be 0.
-
Let lastProgressTime be the monotonic clock ’s unsafe current time .
-
Perform fireProgressEvent given 0.
-
While true:
-
If downloading has failed, then:
-
Queue a global task on the AI task source given realm ’s global object to reject promise with a "
NetworkError
"DOMException
. -
Abort these steps.
-
-
Let bytesSoFar be the number of bytes downloaded so far.
-
Assert : bytesSoFar is greater than or equal to 0, and less than or equal to totalBytes .
-
If the monotonic clock ’s unsafe current time minus lastProgressTime is greater than 50 ms, or bytesSoFar equals totalBytes , then:
-
Let rawProgressFraction be bytesSoFar divided by totalBytes .
-
Let progressFraction be floor ( rawProgressFraction × 65,536) ÷ 65,536.
We use a fraction, instead of firing a progress event with the number of bytes downloaded, to avoid giving precise information about the size of the model or other material being downloaded.
progressFraction is calculated from rawProgressFraction to give a precision of one part in 2 16 . This ensures that over most internet speeds and with most model sizes, the
loaded
value will be different from the previous one that was fired ~50 milliseconds ago.Full calculation
Assume a 5 GiB download size, and a 20 Mbps download speed (chosen as a number on the lower range from this source ). Then, downloading 5 GiB will take:
Rounding up to the nearest power of two gives a conservative estimate of 65,536 fifty millisecond intervals, so we want to give progress to 1 part in 2 16 .
-
If progressFraction is not equal to lastProgressFraction , then perform fireProgressEvent given progressFraction .
-
If bytesSoFar equals totalBytes , then break .
Since this is the only non-failure exit condition for the loop, we will never miss firing a
downloadprogress
event for the 100% mark. -
Set lastProgressFraction to progressFraction .
-
Set lastProgressTime to the monotonic clock ’s unsafe current time .
-
-
-
-
If aborted , then:
-
Queue a global task on the AI task source given realm ’s global object to perform the following steps:
-
Reject promise with options ["
signal
"]'s abort reason .
-
Abort these steps.
-
-
Initialize and return an AI model object given promise , options , a no-op algorithm, initialize , and create .
-
-
-
Return promise .
Promise
promise
,
an
ordered
map
options
,
and
algorithms
fireProgressEvent
,
initialize
,
and
create
:
-
Assert : these steps are running in parallel .
-
Perform fireProgressEvent given 0.
-
Perform fireProgressEvent given 1.
-
IfLet result be the result of performing initialize given optionsreturns false, then:. -
Queue a global task on the AI task source given promise ’s relevant global object to
reject promise with an " OperationError " DOMException . Return. Queue a global task on the AI task source given promise ’s relevant global object toperform the following steps:-
If options ["
signal
"] exists and is aborted , then:-
Reject promise with options ["
signal
"]'s abort reason . -
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. -
-
If result is an error information , then:
Reject promise with the result of converting error information into an exception object given result .
Abort these steps.
Let model be the result of performing create given promise ’s relevant global object and options .
-
Assert : model implements an interface that includes
AIDestroyable
. -
Initialize as a destroyable model .
-
If options ["
signal
"] exists , then add the following abort steps to options ["signal
"]:-
Destroy model given options ["
signal
"]'s abort reason .
-
-
Resolve promise with model .
-
6.2. Obtaining results and usage
AIDestroyable
modelObject
,
an
ordered
map
options
,
and
an
algorithm
operation
:
-
If modelObject ’s relevant global object is a
Window
whose associated Document is not fully active , then return a promise rejected with an "InvalidStateError
"DOMException
. -
Let signals be « modelObject ’s destruction abort controller ’s signal ».
-
If options ["
signal
"] exists , then append it to signals . -
Let compositeSignal be the result of creating a dependent abort signal given signals using
AbortSignal
and modelObject ’s relevant realm . -
If compositeSignal is aborted , then return a promise rejected with compositeSignal ’s abort reason .
-
Let abortedDuringOperation be false.
This variable will be written to from the event loop , but read from in parallel .
-
Add the following abort steps to compositeSignal :
-
Set abortedDuringOperation to true.
-
-
Let promise be a new promise created in modelObject ’s relevant realm .
-
-
Let result be the empty string.
-
Let chunkProduced be the following steps given a string chunk :
-
Queue a global task on the AI task source given modelObject ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then reject promise with compositeSignal ’s abort reason .
-
Otherwise, append chunk to result .
-
-
-
Let done be the following steps:
-
Queue a global task on the AI task source given modelObject ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then reject promise with compositeSignal ’s abort reason .
-
Otherwise, resolve promise with result .
-
-
-
Let error be the following steps given error information errorInfo :
-
Queue a global task on the AI task source given modelObject ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then reject promise with compositeSignal ’s abort reason .
-
Otherwise, reject promise with the result
of creating a DOMExceptionconverting error information into an exception objectwith namegivenby errorInfo ’s error name , usingerrorInfo’s error information to populate the message appropriately..
-
-
-
Let stopProducing be the following steps:
-
Return abortedDuringOperation .
-
-
Perform operation given chunkProduced , done , error , and stopProducing .
-
-
Return promise .
AIDestroyable
modelObject
,
an
ordered
map
options
,
and
an
algorithm
operation
:
-
If modelObject ’s relevant global object is a
Window
whose associated Document is not fully active , then throw an "InvalidStateError
"DOMException
. -
Let signals be « modelObject ’s destruction abort controller ’s signal ».
-
If options ["
signal
"] exists , then append it to signals . -
Let compositeSignal be the result of creating a dependent abort signal given signals using
AbortSignal
and modelObject ’s relevant realm . -
If compositeSignal is aborted , then return a promise rejected with compositeSignal ’s abort reason .
-
Let abortedDuringOperation be false.
This variable will be written to from the event loop , but read from in parallel .
-
Add the following abort steps to compositeSignal :
-
Set abortedDuringOperation to true.
-
-
Let stream be a new
ReadableStream
created in this ’s relevant realm . -
Let canceledDuringOperation be false.
This variable tracks web developer stream cancelations via
stream.cancel()
, which are not surfaced as errors. It will be written to from the event loop , but sometimes read from in parallel . -
Set up stream with cancelAlgorithm set to the following steps (ignoring the reason argument):
-
Set canceledDuringOperation to true.
-
-
-
Let chunkProduced be the following steps given a string chunk :
-
Queue a global task on the AI task source given this ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then error stream with compositeSignal ’s abort reason .
-
Otherwise, enqueue chunk into stream .
-
-
-
Let done be the following steps:
-
Queue a global task on the AI task source given this ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then error stream with compositeSignal ’s abort reason .
-
Otherwise, close stream .
-
-
-
Let error be the following steps given error information errorInfo :
-
Queue a global task on the AI task source given this ’s relevant global object to perform the following steps:
-
If abortedDuringOperation is true, then error stream with compositeSignal ’s abort reason .
-
Otherwise, error stream with the result of
creating a DOMExceptionconverting error information into an exception objectwith namegivenby errorInfo ’s error name , usingerrorInfo’s error information to populate the message appropriately..
-
-
-
Let stopProducing be the following steps:
-
If either abortedDuringOperation or canceledDuringOperation are true, then return true.
-
Return false.
-
-
Perform operation given chunkProduced , done , error , and stopProducing .
-
-
Return stream .
AIDestroyable
modelObject
,
an
ordered
map
options
,
and
an
algorithm
measure
:If modelObject ’s relevant global object is a
Window
whose associated Document is not fully active , then return a promise rejected with an "InvalidStateError
"DOMException
.Let signals be « modelObject ’s destruction abort controller ’s signal ».
If options ["
signal
"] exists , then append it to signals .Let compositeSignal be the result of creating a dependent abort signal given signals using
AbortSignal
and modelObject ’s relevant realm .If compositeSignal is aborted , then return a promise rejected with compositeSignal ’s abort reason .
Let abortedDuringMeasurement be false.
This variable will be written to from the event loop , but read from in parallel .
Add the following abort steps to compositeSignal :
Set abortedDuringMeasurement to true.
Let promise be a new promise created in modelObject ’s relevant realm .
Let stopMeasuring be the following steps:
Return abortedDuringMeasurement .
Let result be the result of performing measure given stopMeasuring .
Queue a global task on the AI task source given modelObject ’s relevant global object to perform the following steps:
If abortedDuringMeasurement is true, then reject promise with compositeSignal ’s abort reason .
Otherwise, if result is an error information , then reject promise with the result converting error information into an exception object given result .
Otherwise,
Return promise .
6.3. Language tags
TypeError
if
any
are
invalid.
-
If options [ key ] is a string , then set options [ key ] to the result of validating and canonicalizing a single language tag given options [ key ].
-
Otherwise:
-
Assert : options [ key ] either does not exist , or it is a list of strings .
-
Let languageTags be an empty ordered set .
-
If options [ key ] exists , then for each languageTag of options [ key ]:
-
If IsStructurallyValidLanguageTag ( languageTag ) is false, then throw a
TypeError
. -
Append the result of validating and canonicalizing a single language tag to languageTags .
-
-
Set options [ key ] to languageTags .
-
-
If IsStructurallyValidLanguageTag ( potentialLanguageTag ) is false, then throw a
TypeError
. -
Return CanonicalizeUnicodeLocaleId ( potentialLanguageTag ).
-
Let availabilities be «[ "
available
" → an empty set , "downloading
" → an empty set , "downloadable
" → an empty set ]». -
For each human language languageTag , represented as a Unicode canonicalized locale identifier , for which the user agent supports purpose , without performing any downloading operations:
-
For each human language languageTag , represented as a Unicode canonicalized locale identifier , for which the user agent is currently downloading material (e.g., an AI model or fine-tuning) to support purpose :
-
Append languageTag to availabilities ["
downloading
"].
-
-
For each human language languageTag , represented as a Unicode canonicalized locale identifier , for which the user agent believes it can support purpose , but only after performing a not-currently-ongoing download (e.g., of an AI model or fine-tuning):
-
Append languageTag to availabilities ["
downloadable
"].
-
-
Assert : availabilities ["
available
"], availabilities ["downloading
"], and availabilities ["downloadable
"] are disjoint. -
If the union of availabilities ["
available
"], availabilities ["downloading
"], and availabilities ["downloadable
"] does not meet the language tag set completeness rules , then:-
Let missingLanguageTags be the set of missing language tags necessary to meet the language tag set completeness rules .
-
For each languageTag of missingLanguageTags :
-
Append languageTag to one of the three sets. Which of the sets to append to is implementation-defined , and should be guided by considerations similar to that of LookupMatchingLocaleByBestFit in terms of keeping "best fallback languages" together.
-
-
Return availabilities .
-
This definition is intended to align with that of [[AvailableLocales]] in ECMAScript Internationalization API Specification . [ECMA-402]
de-DE
"
input
text,
it
will
also
count
as
supporting
"
de
"
input
text.
The
converse
direction
is
supported
not
by
the
language
tag
set
completeness
rules
,
but
instead
by
the
use
of
LookupMatchingLocaleByBestFit
,
which
ensures
that
if
an
implementation
supports
summarizing
"
de
"
input
text,
it
also
counts
as
supporting
summarization
of
"
de-CH
",
"
de-Latn-CH
",
etc.
6.4. Availability
AIAvailability
-or-null
values
availabilities
is:
-
If availabilities contains null, then return null.
-
If availabilities contains "
unavailable
", then return "unavailable
". -
If availabilities contains "
downloading
", then return "downloading
". -
If availabilities contains "
downloadable
", then return "downloadable
". -
Return "
available
".
6.5. Errors
An error information is used to communicate error information from in parallel to the event loop . It is either a quota exceeded error information or a DOMException error information .
A DOMException error information is a struct with the following items :
- name
a string that will be used for the
DOMException
’s name .- details
other information necessary to create a useful
DOMException
for the web developer. (Typically, just an exception message.)
A quota exceeded error information is a struct with the following items :
- requested
a number that will be used for the
QuotaExceededError
’s requested .- quota
a number that will be used for the
QuotaExceededError
’s quota .
The parts of this specification related to quota exceeded errors assume that whatwg/webidl#1465 will be merged.
If errorInfo is a DOMException error information , then return a new
DOMException
with name given by errorInfo ’s name , using errorInfo ’s details to populate the message appropriately.Otherwise:
Assert : error is a quota exceeded error information .
Return a new
QuotaExceededError
whose requested is error ’s requested and quota is error ’s quota .
6.6. Task source
Tasks queued by this specification use the AI task source .