Proofreader API

1. はじめに

現時点では、解説文書を参照してください。

2. 依存関係

これらの API は、機械学習モデルによって駆動されることが想定される API 群の一部であり、共通の API サーフェスの慣用法および仕様パターンを共有します。現在、これらの共有部分の仕様テキストは Writing Assistance APIs § 5 Shared infrastructure にあり、共通のプライバシーおよびセキュリティ上の考慮事項は Writing Assistance APIs § 6 Privacy considerations および Writing Assistance APIs § 7 Security considerations で議論されています。これらの API を実装するには、その共有インフラストラクチャを実装し、これらのプライバシーおよびセキュリティ上の考慮事項に適合する必要があります。ただし、実際の writing assistance APIs を実装または公開する必要はありません。 [WRITING-ASSISTANCE-APIS]

3. 校正 API

[Exposed=Window, SecureContext]
interface Proofreader {
    static Promise<Proofreader> create(optional ProofreaderCreateOptions options = {});
    static Promise<Availability> availability(optional ProofreaderCreateCoreOptions options = {});

    Promise<ProofreadResult> proofread(
        DOMString input,
        optional ProofreaderProofreadOptions options = {}
    );

    readonly attribute boolean includeCorrectionTypes;
    readonly attribute boolean includeCorrectionExplanations;

    readonly attribute FrozenArray<DOMString>? expectedInputLanguages;
    readonly attribute DOMString? correctionExplanationLanguage;
};

dictionary ProofreaderCreateCoreOptions {
    boolean includeCorrectionTypes = false;
    boolean includeCorrectionExplanations = false;

    sequence<DOMString> expectedInputLanguages;
    DOMString correctionExplanationLanguage;
};

dictionary ProofreaderCreateOptions : ProofreaderCreateCoreOptions {
    AbortSignal signal;
    CreateMonitorCallback monitor;
};

dictionary ProofreaderProofreadOptions {
    AbortSignal signal;
};

dictionary ProofreadResult {
    DOMString correctedInput;
    sequence<ProofreadCorrection> corrections;
};

dictionary ProofreadCorrection {
    unsigned long long startIndex;
    unsigned long long endIndex;
    DOMString correction;
    sequence<CorrectionType> types;
    DOMString explanation;
};

enum CorrectionType { "spelling", "punctuation", "capitalization", "grammar" };

3.1. 作成

静的 create(options) メソッドの手順は次のとおりです。

options, "Proofreader", 校正オプションを検証し正規化する, 校正オプションの可用性を計算する, 校正モデルをダウンロードする, 校正モデルを初期化する, 校正オブジェクトを作成する, および false を与えて AI モデルオブジェクトを作成する結果を返す。

ProofreaderCreateCoreOptions options が与えられたとき、校正オプションを検証し正規化するには、次の手順を実行する。これらは options をその場で変異させて言語タグを正規化および重複除去し、いずれかが不正な場合は例外を投げる。

options および "expectedInputLanguages" を与えて、言語タグを検証し正規化する。
options および "correctionExplanationLanguage" を与えて、言語タグを検証し正規化する。

ProofreaderCreateCoreOptions options が与えられたとき、校正モデルをダウンロードするには、次の手順を実行する。

Assert: これらの手順は並列に実行されている。
options に従ってテキストを校正するためにユーザーエージェントが必要とするすべてのもののダウンロード処理を開始する。これには、基盤 AI モデル、特定の言語またはオプション値向けの微調整、その他のリソースが含まれ得る。
何らかの理由でダウンロード処理を開始できない場合は、false を返す。
true を返す。

ProofreaderCreateOptions options が与えられたとき、校正モデルを初期化するには、次の手順を実行する。

Assert: これらの手順は並列に実行されている。
ユーザーエージェントの校正機能を支える AI モデルのために必要な初期化操作を実行する。

これには、モデルをメモリに読み込むこと、または options によって表される他のオプションをサポートするために必要な微調整を読み込むことが含まれ得る。
他の何らかの理由で初期化に失敗した場合は、DOMException エラー情報を返す。その name は "OperationError" であり、その details は適切な詳細を含む。
null を返す。

realm realm および ProofreaderCreateOptions options が与えられたとき、校正オブジェクトを作成するには、次の手順を実行する。

Assert: これらの手順は realm の周囲のエージェントのイベントループ上で実行されている。
realm 内で作成された新しい Proofreader オブジェクトを、以下を持つものとして返す。

訂正タイプを含める

options["includeCorrectionTypes"] default to false

訂正の説明を含める

options["includeCorrectionExplanations"] default to false

想定入力言語

options["expectedInputLanguages"] が空でない場合は、それを与えて凍結配列を作成する結果。そうでなければ null

訂正説明言語

options["correctionExplanationLanguage"] が存在する場合はそれ。そうでなければ null

3.2. 可用性

静的 availability(options) メソッドの手順は次のとおりです。

options, "Proofreader", 校正オプションを検証し正規化する, および校正オプションの可用性を計算するを与えて、 AI モデルの可用性を計算する結果を返す。

ProofreaderCreateCoreOptions options が与えられたとき、校正オプションの可用性を計算するには、次の手順を実行する。これらは Availability 値または null のいずれかを返し、options をその場で変異させて、言語タグをその最適適合の一致へ更新する。

表明：このアルゴリズムは並行して実行されている。
availability を、options["includeCorrectionTypes"]、 options["includeCorrectionExplanations"]を与えた校正機能の言語以外のオプションの利用可能性とする。
double を、校正機能の言語可用性の二つ組とする。
double が null の場合、null を返す。
inputLanguageAvailability を、 options["expectedInputLanguages"] および double の入力言語を与えて言語の利用可能性を計算した結果とする。
correctionExplanationLanguagesList を « options["correctionExplanationLanguage"] » とする。
correctionExplanationLanguageAvailability を、 correctionExplanationLanguagesList および double の修正の説明言語を与えて言語の利用可能性を計算した結果とする。
options["correctionExplanationLanguage"] を correctionExplanationLanguagesList[0] に設定する。
« availability、inputLanguageAvailability、 correctionExplanationLanguageAvailability » を与えた最小の利用可能性を返す。

boolean includeCorrectionTypes および boolean includeCorrectionExplanations が与えられた校正の非言語オプションの可用性は、次の手順で与えられる。これらは Availability 値または null を返す。

Assert: このアルゴリズムは並列に実行されている。
ユーザーエージェントがテキスト校正をサポートできるかどうかを判断しようとして何らかのエラーがあり、ユーザーエージェントがそれを一時的である（再問い合わせによりそのようなエラーが生じなくなる可能性がある）と考える場合、null を返す。
ユーザーエージェントが、includeCorrectionTypes によって記述されるように訂正タイプあり/なしで、かつ includeCorrectionExplanations によって記述されるように訂正説明あり/なしで、テキスト校正を現在サポートしている場合、"available" を返す。
ユーザーエージェントが、includeCorrectionTypes および includeCorrectionExplanations に従ってテキスト校正をサポートできるようになると考えるが、それはすでに進行中のダウンロードが完了した後に限られる場合、"downloading" を返す。
ユーザーエージェントが、includeCorrectionTypes および includeCorrectionExplanations に従ってテキスト校正をサポートできるようになると考えるが、それは現在進行中ではないダウンロードを実行した後に限られる場合、"downloadable" を返す。
それ以外の場合、"unavailable" を返す。

校正機能の言語可用性の二つ組は、次の手順によって得られる。これらは言語可用性の二つ組または null を返す。

表明：このアルゴリズムは並行して実行されている。
ユーザーエージェントがテキストの校正をサポートできるかどうかを判定しようとした際に、ユーザーエージェントが一時的であると考える何らかのエラー（再照会すればそのようなエラーが発生しなくなる可能性があるもの）が生じた場合、null を返す。
次の内容を持つ言語可用性の二つ組を返す：

入力言語

その言語で記述されたテキストを校正する目的を与えて、言語可用性の区分を取得した結果

修正の説明言語

その言語で校正による修正の説明テキストを生成する目的を与えて、言語可用性の区分を取得した結果

今日のソフトウェアで一般的に見られる構成は、「繁体字中国語」と「簡体字中国語」という、 2 種類の書記中国語をサポートすることである。ユーザーエージェントが、繁体字中国語で記述されたテキストの校正をダウンロードなしでサポートし、簡体字中国語についてはダウンロード後にサポートすると仮定する。

これを実装する方法の一つとして、校正機能の言語可用性の二つ組が、「zh-Hant」は入力言語["available"] 集合に含まれ、「zh」および「zh-Hans」は入力言語["downloadable"] 集合に含まれると返すことが考えられる。この戻り値は、「zh」が存在することを保証することで、言語タグ集合の完全性規則の要件に適合する。言語可用性の区分を取得するアルゴリズムの手順に従い、実装は、「zh」が「zh-Hant」とともに利用可能な入力言語の集合に属するのではなく、「zh-Hans」とともにダウンロード可能な入力言語の集合に属すると判定している。

LookupMatchingLocaleByBestFitの使用と組み合わせると、これは availability() が次の回答を返すことを意味する：

function a(languageTag) {
  return Proofreader.availability({
    expectedInputLanguages: [languageTag]
  });
}

await a("zh") === "downloadable";
await a("zh-Hant") === "available";
await a("zh-Hans") === "downloadable";

await a("zh-TW") === "available";      // zh-TW は zh-Hant に最適適合する
await a("zh-HK") === "available";      // zh-HK は zh-Hant に最適適合する
await a("zh-CN") === "downloadable";   // zh-CN は zh-Hans に最適適合する

await a("zh-BR") === "downloadable";   // zh-BR は zh に最適適合する
await a("zh-Kana") === "downloadable"; // zh-Kana は zh に最適適合する

3.3. 言語の可用性

言語可用性の二つ組は、次の構造体であり、次の項目を持つ：

入力言語、言語可用性の区分
修正の説明言語、言語可用性の区分

3.4. `Proofreader` クラス

すべての Proofreader は、作成時に設定される、boolean または default to false である訂正タイプを含めるを持つ。

すべての Proofreader は、作成時に設定される、boolean または default to false である訂正の説明を含めるを持つ。

すべての Proofreader は、作成時に設定される、 FrozenArray<DOMString> または null である想定入力言語を持つ。

すべての Proofreader は、作成時に設定される、string または null である訂正説明言語を持つ。

includeCorrectionTypes getter 手順は、 this の訂正タイプを含めるを返すことである。

type getter 手順は、this の訂正の説明を含めるを返すことである。

expectedInputLanguages getter 手順は、 this の想定入力言語を返すことである。

correctionExplanationLanguage getter 手順は、this の訂正説明言語を返すことである。

proofread(input, options) メソッドの手順は次のとおりです。

引数 chunkProduced, done, error, および stopProducing を取り、this の訂正タイプを含める, this の訂正の説明を含める, this の訂正説明言語, chunkProduced, done, error, および stopProducing が与えられた input を校正するアルゴリズム手順を operation とする。
集約された AI モデル結果を取得するに、 this, options, および operation を与えた結果を返す。

measureInputUsage(input, options) メソッドの手順は次のとおりです。

引数 stopMeasuring を取り、input, this の訂正タイプを含める, this の訂正の説明を含める, this の訂正説明言語, および stopMeasuring が与えられた、校正入力使用量を測定する結果を返すアルゴリズム手順を measureUsage とする。
AI モデル入力使用量を測定するに、this, options, および measureUsage を与えた結果を返す。

3.5. 校正

3.5.1. アルゴリズム

以下が与えられたとき、校正するには、

string input,
boolean includeCorrectionTypes,
boolean includeCorrectionExplanations,
string-or-null correctionExplanationLanguage,
string を取り何も返さないアルゴリズム chunkProduced,
引数を取らず何も返さないアルゴリズム done,
エラー情報を取り何も返さないアルゴリズム error, および
引数を取らず boolean を返すアルゴリズム stopProducing,

次の手順を実行する。

表明：このアルゴリズムは並行して実行されている。
requested を、input、includeCorrectionTypes、correctionExplanationLanguage、 correctionExplanationLanguage、および stopProducing を与えて校正機能の入力使用量を測定した結果とする。
requested が null の場合、返る。
requested がエラー情報である場合：
1. requested を与えて error を実行する。
2. 返る。
表明：requested は数値である。
以下の指針に従い、実装定義の方法で、input を校正し、校正済みテキストとして文字列 correctedInput を持ち、input から correctedInput を形成するために行われたすべての修正を詳述する ProofreadCorrection corrections を持つ ProofreadResult にする処理を開始する。

input が空文字列であるか、その他の理由で校正可能な内容を含まない場合（例えば、空白文字または制御文字のみを含む場合）、結果として得られる校正済みテキストは空文字列であるべきである。そのような場合、includeCorrectionTypes、 includeCorrectionExplanations、および correctionExplanationLanguage は無視されるべきである。

校正は、includeCorrectionTypes および includeCorrectionExplanations によって示される指針に従うべきである。

校正処理は、§ 4 プライバシーに関する考慮事項および § 5 セキュリティに関する考慮事項で示される指針に従わなければならず、特に、Writing Assistance API § 6.4 ユーザー入力およびWriting Assistance API § 7.2 実行時の共有リソースを含むが、これらに限定されない。

correctionExplanationLanguage が null でない場合、校正はその言語で行われるべきである。それ以外の場合、input の言語で行われるべきである。input が複数の言語を含む場合、または input の言語を検出できない場合、修正の説明言語は実装定義であるか、実装は § 3.5.4 エラーの指針に従って、これをエラーとして扱ってもよい。

実装者は、結果が input によって促された任意の出力ではなく、 input の実際の校正結果となるよう最大限努めるべきである。

例えば、input が「フランスの首都は何ですか」である場合、この質問に回答すること、例えば「パリはフランスの首都です。」と出力することは誤りである。より適切な出力は、例えば「フランスの首都は何ですか？」となる。
1. 次の校正データのチャンクが生成されるか、校正処理が完了するか、stopProducing の呼び出し結果が true になるまで待つ。
2. そのようなチャンクが正常に生成された場合：
3. それを文字列 chunk として表す。
4. chunk を与えて chunkProduced を実行する。
5. それ以外の場合、校正処理が完了していれば：
6. done を実行する。
7. 中断する。
8. それ以外の場合、stopProducing が true を返すなら、中断する。
9. それ以外の場合、校正中にエラーが発生していれば：
10. § 3.5.4 エラーの指針に従って、エラーをエラー情報 errorInfo として表す。
11. errorInfo を与えて error を実行する。
12. 中断する。

3.5.2. 使用量

以下が与えられたとき、校正入力使用量を測定するには、

string input,
boolean includeCorrectionTypes,
boolean includeCorrectionExplanations,
string-or-null correctionExplanationLanguage, および
引数を取らず boolean を返すアルゴリズム stopMeasuring,

次の手順を実行する。

表明：このアルゴリズムは並行して実行されている。
inputToModel を、input、 includeCorrectionTypes、includeCorrectionExplanations、および correctionExplanationLanguage を与えて校正するために、基礎となるモデルへ送信される実装定義の文字列とする。

この処理中に stopMeasuring が true を返し始めた場合、null を返す。

この処理中にエラーが発生した場合、§ 3.5.4 エラーの指針に従って、適切なDOMException エラー情報を返す。
inputToModel を基礎となるモデルに与える際に表現するために必要な入力使用量を返す。正確な計算手順は、次の制約に従う実装定義である。

返される入力使用量は、非負かつ有限でなければならない。校正処理に使用量クォータがない場合は、0 でなければならない。それ以外の場合は正でなければならず、 inputToModel の長さにおおよそ比例するべきである。

これは、言語モデルのトークン化方式で input を表現するために必要なトークン数である場合もあれば、 input の長さである場合もある。また、モデルに与えるために必要な接頭辞または接尾辞の使用量も数える、これらの何らかの変形である場合もある。

この処理中に stopMeasuring が true を返し始めた場合、代わりに null を返す。

この処理中にエラーが発生した場合、代わりに§ 3.5.4 エラーの指針に従って、適切なDOMException エラー情報を返す。

3.5.3. オプション

校正するアルゴリズムの詳細は、 AI モデルによって駆動されることが想定されるため、実装定義である。ただし、Web 開発者が includeCorrectionTypes および includeCorrectionExplanations フラグを通じて制御できることが意図されている。

この節では、校正する実装が各 boolean フラグをどのように使用して校正処理を導くべきかについて、規範的な指針を与える。

`includeCorrectionTypes` 値
値	意味
"true"	校正結果は訂正のリストを含むべきであり、各 `ProofreadCorrection` は、 `startIndex` から `endIndex` までの範囲によって定義され、 `CorrectionType` 列挙に従って訂正されるエラーのタイプを記述すべきである。
"false"	校正結果は訂正のリストを含むべきであり、各 `ProofreadCorrection` は、 `startIndex` から `endIndex` までの範囲によって定義され、訂正されるエラーのタイプを提供しない。

`includeCorrectionExplanations` 値
値	意味
"true"	校正結果は訂正のリストを含むべきであり、各 `ProofreadCorrection` は、 `startIndex` から `endIndex` までの範囲によって定義され、訂正されたエラーについてのテキスト説明を提供すべきである。
"false"	校正結果は訂正のリストを含むべきであり、各 `ProofreadCorrection` は、 `startIndex` から `endIndex` までの範囲によって定義され、訂正されたエラーについてのテキスト説明を提供しない。

すべての "should" レベルの指針と同様に、ユーザーエージェントはこれらに完全には適合しない場合があります。特に、すべての訂正に対して訂正タイプを提供する場合、言語モデルが完全には適合しないことが想定されます。

3.5.4. エラー

校正が失敗した場合、次の考えられる理由が Web 開発者に表面化されることがあります。この表は、考えられる DOMException names と、実装がそれらを使用すべき場合を列挙しています。

`DOMException` name	シナリオ
"`NotAllowedError`"	校正がユーザーの選択またはユーザーエージェントのポリシーによって無効化されている。
"`NotSupportedError`"	校正される入力、または提供されるコンテキストが、ユーザーエージェントがサポートしていない言語であるか、 `create()` の呼び出しで適切に提供されなかった。校正訂正説明言語が、ユーザーエージェントがサポートしていない言語になった（たとえば、ユーザーエージェントがその出力言語について十分な品質管理テストを実行していないため）か、 `create()` の呼び出しで適切に提供されなかった。 `includeCorrectionExplanations` が true に設定され、`correctionExplanationLanguage` オプションが設定されておらず、入力テキストの言語を判定できなかったため、ユーザーエージェントに適切な訂正説明言語の既定値がなかった。
"`UnknownError`"	その他すべてのシナリオ。これには、ユーザーエージェントが校正できず、かつ § 4 プライバシーに関する考慮事項または § 5 セキュリティに関する考慮事項で与えられた要件を満たせないと考える場合が含まれる。または、ユーザーエージェントが失敗理由を開示したくない場合。

この表は、proofreader API によって表面化され得る例外の完全な一覧を与えるものではありません。これは、特定の実装定義手順から生じ得るものだけを含みます。

3.6. 権限ポリシー統合

proofreader API へのアクセスは、ポリシー制御機能 "proofreader" の背後で制限され、これは 'self' の既定の許可リストを持つ。

4. プライバシーに関する考慮事項

translator および language detector API のプライバシーに関する考慮事項の議論については、 Writing Assistance APIs § 6 Privacy considerations を参照してください。そのテキストは、 § 2 依存関係で述べたように、同じインフラストラクチャを共有するすべての API に適用されるように書かれています。

5. セキュリティに関する考慮事項

translator および language detector API のセキュリティに関する考慮事項の議論については、 Writing Assistance APIs § 7 Security considerations を参照してください。そのテキストは、 § 2 依存関係で述べたように、同じインフラストラクチャを共有するすべての API に適用されるように書かれています。

校正 API

概要

この文書のステータス

1. はじめに

2. 依存関係

3. 校正 API

3.1. 作成

3.2. 可用性

3.3. 言語の可用性

3.4. `Proofreader` クラス

3.5. 校正

3.5.1. アルゴリズム

3.5.2. 使用量

3.5.3. オプション

3.5.4. エラー

3.6. 権限ポリシー統合

4. プライバシーに関する考慮事項

5. セキュリティに関する考慮事項

適合性

文書の慣例

索引

この仕様で定義される用語

参照により定義される用語

参考文献

規範参照文献

非規範参照文献

IDL 索引

校正 API

概要

この文書のステータス

1. はじめに

2. 依存関係

3. 校正 API

3.1. 作成

3.2. 可用性

3.3. 言語の可用性

3.4. Proofreader クラス

3.5. 校正

3.5.1. アルゴリズム

3.5.2. 使用量

3.5.3. オプション

3.5.4. エラー

3.6. 権限ポリシー統合

4. プライバシーに関する考慮事項

5. セキュリティに関する考慮事項

適合性

文書の 慣例

索引

この仕様で定義される 用語

参照により定義される 用語

参考文献

規範参照文献

非規範参照文献

IDL 索引

3.4. `Proofreader` クラス

文書の慣例

この仕様で定義される用語

参照により定義される用語