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 をその場で変異させて、言語タグをその最適適合の一致へ更新する。

Assert: このアルゴリズムは並列に実行されている。
options["includeCorrectionTypes"], options["includeCorrectionExplanations"] を与えた校正の非言語オプションの可用性を availability とする。
校正言語可用性ダブルを double とする。
double が null の場合、null を返す。
options["expectedInputLanguages"] および double の入力言語を与えて言語の可用性を計算する結果を inputLanguageAvailability とする。
« options["correctionExplanationLanguage"] » を correctionExplanationLanguagesList とする。
correctionExplanationLanguagesList および double の訂正説明言語を与えて言語の可用性を計算する結果を correctionExplanationLanguageAvailability とする。
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 を返す。

Assert: このアルゴリズムは並列に実行されている。
ユーザーエージェントがテキスト校正をサポートできるかどうかを判断しようとして何らかのエラーがあり、ユーザーエージェントがそれを一時的である（再問い合わせによりそのようなエラーが生じなくなる可能性がある）と考える場合、null を返す。
以下を持つ言語可用性ダブルを返す。

入力言語

その言語で書かれたテキストを校正する目的が与えられたときの言語可用性パーティションを取得する結果

訂正説明言語

その言語で校正訂正のテキスト説明を生成する目的が与えられたときの言語可用性パーティションを取得する結果

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

これを実装する方法の 1 つは、校正言語可用性ダブルが、 "zh-Hant" は入力言語["available"] 集合内にあり、"zh" および "zh-Hans" は入力言語["downloadable"] 集合内にある、と返すようにすることです。この戻り値は、"zh" が存在することを保証する点で、言語タグ集合の完全性規則の要件に適合します。「should」レベルの指針に従い、実装は、"zh" が "zh-Hant" とともに available 入力言語の集合内ではなく、 "zh-Hans" とともに downloadable 入力言語の集合内に属すると判断しています。

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. 言語の可用性

言語可用性パーティションは map であり、その keys は "downloading", "downloadable", または "available" であり、その values は、Unicode 正規化済みロケール識別子を表す文字列の sets である。 [ECMA-402]

言語可用性ダブルは、次のitems を持つ struct である。

入力言語、言語可用性パーティション
訂正説明言語、言語可用性パーティション

言語可用性を確認している目的の説明 purpose が与えられたとき、言語可用性パーティションを取得するには、次の手順を実行する。

«[ "available" → 空のset, "downloading" → 空のset, "downloadable" → 空のset ]» を partition とする。
ユーザーエージェントが purpose を現在サポートしている、Unicode 正規化済みロケール識別子として表される各人間言語 languageTag について、For each:
1. languageTag を partition["available"] に Append する。
ユーザーエージェントが purpose をサポートできるようになると考えるが、それはすでに進行中のダウンロードが完了した後に限られる、Unicode 正規化済みロケール識別子として表される各人間言語 languageTag について、For each:
1. languageTag を partition["downloading"] に Append する。
ユーザーエージェントが purpose をサポートできるようになると考えるが、それは現在進行中ではないダウンロードを実行した後に限られる、Unicode 正規化済みロケール識別子として表される各人間言語 languageTag について、For each:
1. languageTag を partition["downloadable"] に Append する。
Assert: partition["available"], partition["downloading"], および partition["downloadable"] は互いに素である。
partition["available"], partition["downloading"], および partition["downloadable"] の union が言語タグ集合の完全性規則を満たさない場合:
1. その union が言語タグ集合の完全性規則を満たすために必要な欠落言語タグの set を missingLanguageTags とする。
2. missingLanguageTags の各 languageTag について For each:
3. languageTag を 3 つの集合のいずれかに Append する。どの集合に追加するかは実装定義であり、「最適なフォールバック言語」をまとめておくという観点では LookupMatchingLocaleByBestFit と同様の考慮に導かれるべきである。
4. partition を返す。

文字列のordered set requestedLanguages および言語可用性パーティション partition が与えられたとき、言語の可用性を計算するには、次の手順を実行する。これらは Availability 値を返し、requestedLanguages をその場で変異させて、言語タグをその最適適合の一致へ更新する。

"available" を availability とする。
requestedLanguages の各 language について For each:
1. true を unavailable とする。
2. « "available", "downloading", "downloadable" » の各 availabilityToCheck について For each:
3. partition[availabilityToCheck] を languagesWithThisAvailability とする。
4. LookupMatchingLocaleByBestFit(languagesWithThisAvailability, « language ») を bestMatch とする。
5. bestMatch が undefined でない場合:
  1. requestedLanguages 内で language を bestMatch.[[locale]] に Replace する。
  2. availability および availabilityToCheck を与えた最小可用性を availability に設定する。
  3. unavailable を false に設定する。
  4. Break する。
6. unavailable が true の場合、"unavailable" を返す。
availability を返す。

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,

次の手順を実行する。

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

input が空文字列である場合、またはそれ以外で校正可能な内容を含まない場合（例: 空白文字のみ、または制御文字のみを含む場合）、結果の校正済みテキストは空文字列であるべきである。そのような場合、 includeCorrectionTypes, includeCorrectionExplanations, および correctionExplanationLanguage は無視されるべきである。

校正は、includeCorrectionTypes および includeCorrectionExplanations によって与えられる指針に適合すべきである。

校正処理は、§ 4 プライバシーに関する考慮事項および § 5 セキュリティに関する考慮事項で与えられる指針に適合しなければならない。特に（ただしこれに限られない）Writing Assistance APIs § 6.4 User input および Writing Assistance APIs § 7.2 Runtime shared resources を含む。

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

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

たとえば、input が "what is capital of France" である場合、この質問に答えること、たとえば "Paris is the capital of France." を出力することは不正確である。より正しい出力は、たとえば "What is the capital of France?" である。
1. 校正データの次のチャンクが生成されるか、校正処理が完了するか、stopProducing を呼び出した結果が true になるまで待つ。
2. そのようなチャンクが正常に生成された場合:
3. それを string chunk として表す。
4. chunk を与えて chunkProduced を実行する。
5. そうでなく、校正処理が完了している場合:
6. done を実行する。
7. Break する。
8. そうでなく、stopProducing が true を返す場合は、break する。
9. そうでなく、校正中にエラーが発生した場合:
10. そのエラーを、§ 3.5.4 エラーの指針に従ってエラー情報 errorInfo として表す。
11. errorInfo を与えて error を実行する。
12. Break する。

3.5.2. 使用量

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

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

次の手順を実行する。

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

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

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

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

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

この処理中に 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` クラス

文書の慣例

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

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