package com.gzzm.lobster.llm;

/**
 * ModelThinkingMode —— 模型思考模式 / Per-model thinking mode tri-state.
 *
 * <p>取代旧 {@code Boolean thinkingEnabled} 的 boolean 二态。原二态语义有歧义：
 * "thinkingEnabled=false" 既可能表示「显式关闭思考」也可能表示「按模型默认行为」，
 * 部分 provider（vLLM Qwen3 / DashScope Qwen / Qwen-QwQ）默认开 thinking，不传字段
 * 等于"开思考" → 延迟激增 + 流式格式可能不对。
 *
 * <p>三态明确语义：
 * <ul>
 *   <li>{@link #auto} —— adapter 不传任何 thinking 字段，由 provider 默认决定。
 *       OpenAI / Anthropic / DeepSeek-V3 / Claude 等默认不思考的 provider 用这个最稳。</li>
 *   <li>{@link #on} —— 显式开启：传 {@code reasoning_effort=high} + {@code thinking={type:enabled}}。
 *       适配 deepseek-v4-flash / Qwen3 thinking 部署等。</li>
 *   <li>{@link #off} —— 显式关闭：传一组业界常见 disable 字段
 *       （{@code enable_thinking=false} + {@code chat_template_kwargs.enable_thinking=false}）。
 *       专门解决 vLLM Qwen3 / DashScope Qwen 默认开思考被误伤的场景。
 *       <b>注意</b>：传给严格 schema 的 OpenAI 真身可能 400——OpenAI 真身应配 {@link #auto}。</li>
 * </ul>
 *
 * <p>向后兼容：旧 {@code thinkingEnabled=true} 的 ModelProfile 当 {@code thinkingMode=null + thinkingEnabled=true}
 * 时仍按 {@link #on} 解释，无需运维手动迁移；新 profile 应直接用 {@code thinkingMode}。
 */
public enum ModelThinkingMode {
    /** Provider 默认行为：adapter 不传 thinking 字段. */
    auto,
    /** 显式开启 thinking. */
    on,
    /** 显式关闭 thinking（适合 Qwen3 / DashScope 这类默认开的 provider）. */
    off
}