[API Proposal]: ChatOptions Reasoning values None and Minimal

[SlowFourierTransform]

Background and motivation

The ReasoningEffort enum was introduced in #7252 however this enum is missing the Minimal value, as supported by OpenAI.

OpenAI recently introduced a reasoning value of None. The ReasoningEffort enum does have a value of None, however it seems that this value is ignored and not passed to the OpenAI library, causing confusion.

The none and minimal values are mentioned in the inital issue #7192

API Proposal

namespace Microsoft.Extensions.AI;

public enum ReasoningEffort
{
    None, // this already exists but is ignored

    Minimal,

    // existing values
}

API Usage

ChatResponse response = await chatClient.GetResponseAsync("Hi", new ChatOptions
{
    Reasoning = Reasoning.Minimal,
});

Alternative Designs

No response

Risks

No response

[stephentoub]

The ReasoningEffort enum does have a value of None, however it seems that this value is ignored and not passed to the OpenAI library, causing confusion.

Can you elaborate on "causing confusion"? What is the impact you're seeing from that?

[SlowFourierTransform]

I would expect the library to send the reasoning effort of none to Azure OpenAI, and generate 0 reasoning tokens, but it seems to be doing medium reasoning (the default for models before gpt 5.1), so a simple message gets returned with a few hundred reasoning tokens used instead of 0.

[stephentoub]

Regarding "minimal", it's not a goal to expose every option from every provider. It's not clear how minimal would differ from none or low for most providers. You can also still use RawRepresentationFactory when you need to control things in a way the abstraction doesn't expose. What's the scenario where this is critical?

[stephentoub]

I would expect the library to send the reasoning effort of none to Azure OpenAI, and generate 0 reasoning tokens, but it seems to be doing medium reasoning (the default for models before gpt 5.1), so a simple message gets returned with a few hundred reasoning tokens used instead of 0.

Got it, we'll fix that.

[SlowFourierTransform]

Thanks.

Regarding "minimal", it's not a goal to expose every option from every provider. It's not clear how minimal would differ from none or low for most providers. You can also still use RawRepresentationFactory when you need to control things in a way the abstraction doesn't expose. What's the scenario where this is critical?

I see that none has replaced minimal on GPT-5.1 and up so no need to add minimal.

[stephentoub]

Fixed by #7319