Thinking effort API - level options

[sushraja-msft]

Following up on the recent addition to support thinking effort

#217

Is it better to expose constants or static methods on the LanguageModel ?

LanguageModel.minThinkingEffort
LanguageModel.maxThinkingEffort

where they are integer values

minThinkingEffort=0
maxThinkingEffort=0 for UA with models that dont support thinking.

and
maxThinkingEffort=4 for UA with models that have the 4 levels of thinking mode.

This mitigates concerns for interop between models where

• some models may only have /nothink, /think and no graduation in between.

• some models may have different graduation of thinking levels
  Models like qwen have https://huggingface.co/Qwen/Qwen3.8-27B#api-usage
  xhigh, medium, low which does map to your enum today but may not in the future.

additionally the current API will require developers to call availability

const status = await LanguageModel.availability({
  thinking: { effort: "high" }
});

four times to discover all the possible thinking modes. The constant on languageModel simplifies discovery.

[michaelwasserman]

This is a good question; FYI @isaacahouma, @tomayac, and @reillyeon

I suppose the difference here is whether we're:

• exposing backend granularity for clients to interpolate
• divining sensible presets and mapping them onto backends with more or fewer presets (I suggest avoiding unavailable)

Do you think exposing the backend effort granularity is important to clients?

Hand waving some implementation- or spec-defined mapping/scaling/interpolation:

• more JS to binary backend: an impl could select /think for JS low/medium/high, and select /nothink for JS none.
• more JS to fewer backend: if 'medium' wasn't an option, impls could choose between low/high or the spec could suggest how to round
• fewer JS to more backend: similarly, impls could round as they see fit, or we could define a spec algorithm for effort level.

[isaacahouma]

Thanks for raising this @sushraja-msft, and +1 to @michaelwasserman's points!

A few quick thoughts on the two main concerns here:

• Discovery only needs one availability() call: The intent is that any model supporting thinking mode accepts all four presets ("none", "low", "medium", "high") and maps them to the backend, rather than returning "unavailable" for intermediate levels like "medium". Because of that, developers only need to call LanguageModel.availability({ thinking: { effort: "high" } }) once to check if the model supports thinking.
• Mapping to binary (/think) or 3-level models: Even when a model's template only has a binary /think toggle, the runtime can still graduate "low", "medium", and "high" by setting a different token budget before closing the thought block (</think>). And if a backend only uses native template levels without token budgets, it can map each preset to the closest supported option (for example, mapping "low", "medium", and "high" to /think on a binary model, or "high" to xhigh on Qwen).
• Why presets over minThinkingEffort / maxThinkingEffort: If maxThinkingEffort is 1 on one browser, 3 on another, and 4 on a third, developers have to write custom scaling logic for each model instead of just expressing what their task needs ("none" for simple follow-ups, "high" for complex math or planning). This is similar to why we moved from exposing raw temperature and topK bounds in LanguageModel.params() toward semantic samplingMode presets.

If we clarify in the explainer that implementations should map all four presets whenever the model supports thinking (so a single availability() call is enough and intermediate levels never return "unavailable"), would that address your concern?

[tomayac]

If we work with enums, I expect implementers to map all enums to the most reasonable internal value, even if it may map adjacent enums to the same values if the internal values don't allow for the same granularity. I would not make this fact web-exposed, and instead convey that these enums are best-effort. Example:

• A model supports thinking on or off.
• Enums are "none", "low", "medium", "high".

In this case the mapping would be:

• "none": thinking off
• "low", "medium", "high": thinking on