From caebf18d247b5e6b2aa61abfd4085ed073db7d5d Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Mon, 15 Jun 2026 15:24:11 +0200 Subject: [PATCH 1/8] Update Prompt API spec and explainer with Sampling Params changes Introduce LanguageModelSamplingMode enum and expose it as an option during session creation, as well as a read-only attribute on the session interface. Mark topK and temperature options as deprecated. They remain exposed in the IDL so pages can log deprecation warnings, but are ignored at runtime in standard web contexts. Bug: 521833754 --- README.md | 42 +++++++++++++++++++++++++++++++----------- index.bs | 6 ++++++ 2 files changed, 37 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 492ac37..fa7964a 100644 --- a/README.md +++ b/README.md @@ -458,28 +458,48 @@ The promise returned by `append()` will reject if the prompt cannot be appended Note that `append()` can also cause [overflow](#tokenization-context-window-length-limits-and-overflow), in which case it will evict the oldest non-system prompts from the session and fire the `"contextoverflow"` event. -### Configuration of per-session parameters +### Configuration of sampling modes -Tuning language model sampling parameters can be useful for both testing and adjusting task-specific model behavior. Common sampling parameters include [temperature](https://huggingface.co/blog/how-to-generate#sampling) and [topK](https://huggingface.co/blog/how-to-generate#top-k-sampling). +For standard web page contexts, developers can specify a high-level `samplingMode` during session creation to configure the model's output variety and creativity without worrying about model-internal scalar parameters. -**Notice:** Sampling parameter features are currently only available within extension and experimental contexts. While they are useful for exploring model behavior, the current fields are not guaranteed to be supported or interpreted consistently across all models or user agents. +The allowed values for `samplingMode` are: +* `"most-predictable"`: For tasks requiring strict consistency and reproducibility (e.g., code generation or factual extraction). +* `"predictable"`: For focused outputs with minimal variation. +* `"balanced"` (default): The standard preset for most conversational interactions. +* `"creative"`: For tasks where variety and creativity are preferred over strict factual reproducibility. +* `"most-creative"`: For maximum diversity of tokens and creative brainstorming. -_The limited applicability and non-universal nature of these sampling hyperparameters are discussed further in [issue #42](https://github.com/webmachinelearning/prompt-api/issues/42): sampling hyperparameters are not universal among models._ +Example: +```js +const creativeSession = await LanguageModel.create({ + samplingMode: "creative" +}); +console.log(creativeSession.samplingMode); // "creative" +``` + +The resolved `samplingMode` used to create the session is exposed as a read-only attribute on the session object. + +### Legacy: Configuration of per-session raw parameters + +**Deprecation Notice:** The `topK` and `temperature` options for `LanguageModel.create()`, the `LanguageModel.params()` static method, and the `languageModel.topK` and `languageModel.temperature` instance attributes are now **deprecated**. These features are only functional within web extension contexts and will be ignored in standard web page contexts. They may be completely removed in a future release. + +To avoid breaking existing pages, standard web page contexts can still pass `topK` and `temperature` in the options object without throwing an error (to log deprecation warnings in the console), but they are ignored at runtime and the corresponding properties on the session object will be `undefined` (or fallback to default values). -In extension and experimental contexts: -* The `LanguageModel.params()` static method provides default and maximum values for temperature and topK parameters, once the user agent has ascertained or downloaded the specific underlying model. -* The `temperature` and `topK` instance attributes provide the current values for these parameters for a given session. -* Sampling parameters can also be configured at session creation time via the `temperature` and `topK` options for `LanguageModel.create()` +Furthermore, in contexts where raw parameters are supported (e.g. Chrome Extensions), passing both `samplingMode` and a raw parameter (`topK` or `temperature`) will reject the `create()` promise with a `TypeError`. +The `LanguageModel.params()` API, only available in extensions, can be used to query the default and maximum values for these parameters. +_The limited applicability and non-universal nature of these sampling hyperparameters are discussed further in [issue #42](https://github.com/webmachinelearning/prompt-api/issues/42) and [issue #203](https://github.com/webmachinelearning/prompt-api/issues/203)._ ```js -// Sampling parameter support is limited to extension and experimental web contexts. -// Accessors are undefined, and options are ignored, outside of those contexts. +// The topK and temperature members of the options object are deprecated. They will only be considered when +// LanguageModel.create() is called from within a Chrome Extension. In web page contexts, they are ignored. const customSession = await LanguageModel.create({ temperature: 0.8, topK: 10 }); +// This interface and all its attributes (`defaultTopK`, `maxTopK`, `defaultTemperature`, `maxTemperature`) +// are now only available within Chrome Extension contexts. Web pages can no longer call this method. const params = await LanguageModel.params(); const conditionalSession = await LanguageModel.create({ temperature: isCreativeTask ? params.defaultTemperature * 1.1 : params.defaultTemperature * 0.8, @@ -489,7 +509,7 @@ const conditionalSession = await LanguageModel.create({ If the language model is not available at all in this browser, `params()` will fulfill with `null`. -Error-handling behavior: +Error-handling behavior (only applicable in contexts where legacy parameters are active, e.g. Chrome Extensions): * If values below 0 are passed for `temperature`, then `create()` will return a promise rejected with a `RangeError`. * If values above `maxTemperature` are passed for `temperature`, then `create()` will clamp to `maxTemperature`. (`+Infinity` is specifically allowed, as a way of requesting maximum temperature.) diff --git a/index.bs b/index.bs index 2c9982e..9231d53 100644 --- a/index.bs +++ b/index.bs @@ -85,6 +85,8 @@ interface LanguageModel : EventTarget { // **EXPERIMENTAL**: Only available in extension and experimental contexts. readonly attribute float temperature; + readonly attribute LanguageModelSamplingMode? samplingMode; + Promise clone(optional LanguageModelCloneOptions options = {}); }; LanguageModel includes DestroyableModel; @@ -119,6 +121,8 @@ dictionary LanguageModelCreateCoreOptions { // **EXPERIMENTAL**: Only available in extension and experimental contexts. unrestricted double temperature; + LanguageModelSamplingMode samplingMode; + sequence expectedInputs; sequence expectedOutputs; sequence tools; @@ -172,6 +176,8 @@ dictionary LanguageModelMessageContent { required LanguageModelMessageValue value; }; +enum LanguageModelSamplingMode { "most-predictable", "predictable", "balanced", "creative", "most-creative" }; + enum LanguageModelMessageRole { "system", "user", "assistant" }; enum LanguageModelMessageType { "text", "image", "audio", "tool-call", "tool-response" }; From 07c4a52076340a70e03d14aaa32d327b2a82ff33 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Tue, 16 Jun 2026 12:08:40 +0200 Subject: [PATCH 2/8] Update index.bs Co-authored-by: Reilly Grant --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 9231d53..32458bb 100644 --- a/index.bs +++ b/index.bs @@ -121,7 +121,7 @@ dictionary LanguageModelCreateCoreOptions { // **EXPERIMENTAL**: Only available in extension and experimental contexts. unrestricted double temperature; - LanguageModelSamplingMode samplingMode; + LanguageModelSamplingMode samplingMode = "default"; sequence expectedInputs; sequence expectedOutputs; From 81d5def157fb27059c2d53296e7a84a7e6069c6b Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Tue, 16 Jun 2026 12:08:58 +0200 Subject: [PATCH 3/8] Update index.bs Co-authored-by: Reilly Grant --- index.bs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.bs b/index.bs index 32458bb..424376d 100644 --- a/index.bs +++ b/index.bs @@ -85,7 +85,7 @@ interface LanguageModel : EventTarget { // **EXPERIMENTAL**: Only available in extension and experimental contexts. readonly attribute float temperature; - readonly attribute LanguageModelSamplingMode? samplingMode; + readonly attribute LanguageModelSamplingMode samplingMode; Promise clone(optional LanguageModelCloneOptions options = {}); }; From 72fc28e7cebec30e78dfa718f9778351ec8e50bd Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Tue, 16 Jun 2026 12:09:54 +0200 Subject: [PATCH 4/8] Update README.md Co-authored-by: Reilly Grant --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fa7964a..dc4c2f5 100644 --- a/README.md +++ b/README.md @@ -483,7 +483,7 @@ The resolved `samplingMode` used to create the session is exposed as a read-only **Deprecation Notice:** The `topK` and `temperature` options for `LanguageModel.create()`, the `LanguageModel.params()` static method, and the `languageModel.topK` and `languageModel.temperature` instance attributes are now **deprecated**. These features are only functional within web extension contexts and will be ignored in standard web page contexts. They may be completely removed in a future release. -To avoid breaking existing pages, standard web page contexts can still pass `topK` and `temperature` in the options object without throwing an error (to log deprecation warnings in the console), but they are ignored at runtime and the corresponding properties on the session object will be `undefined` (or fallback to default values). +To avoid breaking existing pages, standard web page contexts can still pass `topK` and `temperature` in the options object without throwing an error (a deprecation warning will be logged in the console), but they are ignored at runtime and the corresponding properties on the session object will be `undefined` (or fallback to default values). Furthermore, in contexts where raw parameters are supported (e.g. Chrome Extensions), passing both `samplingMode` and a raw parameter (`topK` or `temperature`) will reject the `create()` promise with a `TypeError`. From a7befb4af79caae84602411c5f10bf402dfc9655 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Tue, 16 Jun 2026 12:10:09 +0200 Subject: [PATCH 5/8] Update README.md Co-authored-by: Reilly Grant --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dc4c2f5..8451126 100644 --- a/README.md +++ b/README.md @@ -509,7 +509,7 @@ const conditionalSession = await LanguageModel.create({ If the language model is not available at all in this browser, `params()` will fulfill with `null`. -Error-handling behavior (only applicable in contexts where legacy parameters are active, e.g. Chrome Extensions): +Error-handling behavior (only applicable in contexts where legacy parameters are active, e.g. Web Extensions): * If values below 0 are passed for `temperature`, then `create()` will return a promise rejected with a `RangeError`. * If values above `maxTemperature` are passed for `temperature`, then `create()` will clamp to `maxTemperature`. (`+Infinity` is specifically allowed, as a way of requesting maximum temperature.) From 19d7fb02d78d12173253ec3815a9d35b762196c1 Mon Sep 17 00:00:00 2001 From: Isaac Ahouma Date: Tue, 16 Jun 2026 12:10:23 +0200 Subject: [PATCH 6/8] Update README.md Co-authored-by: Reilly Grant --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8451126..e94dc80 100644 --- a/README.md +++ b/README.md @@ -485,7 +485,7 @@ The resolved `samplingMode` used to create the session is exposed as a read-only To avoid breaking existing pages, standard web page contexts can still pass `topK` and `temperature` in the options object without throwing an error (a deprecation warning will be logged in the console), but they are ignored at runtime and the corresponding properties on the session object will be `undefined` (or fallback to default values). -Furthermore, in contexts where raw parameters are supported (e.g. Chrome Extensions), passing both `samplingMode` and a raw parameter (`topK` or `temperature`) will reject the `create()` promise with a `TypeError`. +Furthermore, in contexts where raw parameters are supported (e.g. Web Extensions), passing both `samplingMode` and a raw parameter (`topK` or `temperature`) will reject the `create()` promise with a `TypeError`. The `LanguageModel.params()` API, only available in extensions, can be used to query the default and maximum values for these parameters. From af9953b83374c1ad2adff04c59ff7aa4847361ac Mon Sep 17 00:00:00 2001 From: Reilly Grant Date: Tue, 16 Jun 2026 09:56:09 -0700 Subject: [PATCH 7/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e94dc80..61ad711 100644 --- a/README.md +++ b/README.md @@ -493,7 +493,7 @@ _The limited applicability and non-universal nature of these sampling hyperparam ```js // The topK and temperature members of the options object are deprecated. They will only be considered when -// LanguageModel.create() is called from within a Chrome Extension. In web page contexts, they are ignored. +// LanguageModel.create() is called from within a web extension. In web page contexts, they are ignored. const customSession = await LanguageModel.create({ temperature: 0.8, topK: 10 From f37f8a87d723f38ae4ce1703443d47aed00ea4fb Mon Sep 17 00:00:00 2001 From: Reilly Grant Date: Tue, 16 Jun 2026 09:56:17 -0700 Subject: [PATCH 8/8] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 61ad711..27b71bb 100644 --- a/README.md +++ b/README.md @@ -499,7 +499,7 @@ const customSession = await LanguageModel.create({ topK: 10 }); // This interface and all its attributes (`defaultTopK`, `maxTopK`, `defaultTemperature`, `maxTemperature`) -// are now only available within Chrome Extension contexts. Web pages can no longer call this method. +// are now only available within web extension contexts. Web pages can no longer call this method. const params = await LanguageModel.params(); const conditionalSession = await LanguageModel.create({ temperature: isCreativeTask ? params.defaultTemperature * 1.1 : params.defaultTemperature * 0.8,