chat : clarify the meaning of reasoning_format

[ngxson]

Ref comment: #15404 (comment)

The long story is that the message.reasoning_content API response format is initially introduced by deepseek hosted API, hence the name deepseek

This enum was added so in case openai wants to have their own API schema, then we can select between either deepseek or openai. However, the meaning is lost in time due to a combination of bad naming and poor documentation.

auto was added as a no-brainer solution since deepseek reasoning_content is now supported by many applications, while OAI migrated to their new Response API.

This reasoning_format solely determines the API schema, it is unrelated to the notion of parser or anything at chat template layer. Parser is determined by the chat template itself.

For this reason, common_reasoning_format should not be touched anymore.

[gabe-l-hart]

Thanks!

[aldehir]

Judging by this determination, it seems reasonable to add an openai format to adhere to the recommendations by OpenAI.

I believe this is a critical piece missing in the gpt-oss implementation.

[ngxson]

If you are implementing a Chat Completions API, there is no official spec for handling chain of thought in the published OpenAI specs, as our hosted models will not offer this feature for the time being. We ask you to follow the following convention from OpenRouter instead.

To be fair, it's not even an official openai spec. They explicitly state that the spec was from OpenRouter.

While we can add it, I doubt if many applications actually support this format. It's better not to add until a subset of users explicitly ask for it, to avoid polluting the code base with features that most users won't use.

[ngxson]

Read along the same article:

For the Responses API we augmented our Responses API spec to cover this case. Below are the changes to the spec as type definitions

So it make more sense to add the Responses API instead of adding a new reasoning_format

[aldehir]

While we can add it, I doubt if many applications actually support this format. It's better not to add until a subset of users explicitly ask for it, to avoid polluting the code base with features that most users won't use.

Understood. I started a discussion to gather community feedback but so far there is no immediate desire from the community. Thank you for that clarification.