feat(models): reasoning_effort 'max' tier with provider mappings and fixes

OpenAI GPT-5.6 (Sol/Terra/Luna) supports a new top reasoning tier 'max' via
the Responses API only (live-verified 2026-07-11; chat completions rejects
it, and 'minimal' is rejected by both APIs).

- ReasoningEffort: new 'max' member (enumFormat/fromString pick it up via values)
- Anthropic: map to OutputEffort.max ungated - every output-effort model
  accepts max incl. Opus 4.6 / Sonnet 4.6 (live-verified; those two reject
  xhigh); xhigh gate extracted into xhighOutputEffortModels; OutputEffort
  scaladocs corrected (Sonnet 5 was missing)
- Gemini: max -> ThinkingLevel.HIGH (Gemini 3); thinking-budget mapping
  max=32768 with a new 24576 ceiling clamp for non-Pro 2.5 models
  (live-verified: Flash/Flash-Lite return 400 above 24576)
- Chat-completions conversions: gpt5_6 now downgrades reasoning_effort
  max->xhigh and minimal->low instead of letting the remote API 400
- ModelId / GPT-5.6 comments scoped to the verified per-API behavior
- Examples: AnthropicOpus48ReasoningEffortMapping covers max + Opus 4.6;
  new CreateModelResponseGPT56SolMaxReasoning (Responses API smoke test)
- .gitignore: TODO.md (local follow-up notes)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FFbEyiUjjhE5jhEBwoTncu

Author: peterbanda

.gitignore

@@ -12,3 +12,4 @@ target
 **/build.properties
 **/metals.sbt
 *.log
+/TODO.md

anthropic-client/src/main/scala/io/cequence/openaiscala/anthropic/domain/settings/AnthropicCreateMessageSettings.scala

@@ -93,18 +93,21 @@ final case class OutputConfig(
 
 sealed trait OutputEffort extends EnumValue
 
-// The effort parameter is supported by Claude Fable 5, Opus 4.8/4.7/4.6, and Sonnet 4.6.
+// The effort parameter is supported by Claude Fable 5, Opus 4.8/4.7/4.6, Sonnet 5, and
+// Sonnet 4.6.
 object OutputEffort {
   case object low extends OutputEffort
   case object medium extends OutputEffort
   case object high extends OutputEffort
 
   // Claude always thinks deeply with extended exploration.
-  // Fable 5 and Opus 4.7+ only - requests using xhigh on other models will return an error.
+  // Fable 5, Opus 4.7+, and Sonnet 5 only - requests using xhigh on other models
+  // (e.g. Opus 4.6, Sonnet 4.6) return an error (live-verified 2026-07-11).
   case object xhigh extends OutputEffort
 
   // Absolute maximum capability with no constraints on token spending.
-  // Available on Fable 5, Opus 4.8/4.7/4.6, and Sonnet 4.6.
+  // Available on every effort-supporting model, including Opus 4.6 and Sonnet 4.6,
+  // which reject xhigh (live-verified 2026-07-11).
   case object max extends OutputEffort
 
   def values: Seq[OutputEffort] = Seq(low, medium, high, xhigh, max)

anthropic-client/src/main/scala/io/cequence/openaiscala/anthropic/service/impl/package.scala

@@ -275,6 +275,15 @@ package object impl extends AnthropicServiceConsts with HasOpenAIConfig {
     NonOpenAIModelId.claude_sonnet_4_6
   )
 
+  // Models that accept output_config.effort = xhigh - narrower than outputEffortModels:
+  // Opus 4.6 / Sonnet 4.6 reject xhigh though they do accept max (live-verified 2026-07-11).
+  private val xhighOutputEffortModels: Set[String] = Set(
+    NonOpenAIModelId.claude_fable_5,
+    NonOpenAIModelId.claude_opus_4_8,
+    NonOpenAIModelId.claude_opus_4_7,
+    NonOpenAIModelId.claude_sonnet_5
+  )
+
   // Models where extended thinking with budget_tokens and the sampling params
   // (temperature, top_p, top_k) are fully removed - sending them returns a 400.
   // Adaptive thinking is the only thinking mode.
@@ -317,19 +326,19 @@ package object impl extends AnthropicServiceConsts with HasOpenAIConfig {
       // OutputEffort.xhigh is supported only on Opus 4.7+ (Opus 4.7, Opus 4.8), Fable 5, and
       // Sonnet 5; downgrade to high on Opus 4.6 / Sonnet 4.6 to avoid a remote 400 from Anthropic.
       val m = model.toLowerCase
-      if (
-        m.contains(NonOpenAIModelId.claude_fable_5) ||
-        m.contains(NonOpenAIModelId.claude_opus_4_8) ||
-        m.contains(NonOpenAIModelId.claude_opus_4_7) ||
-        m.contains(NonOpenAIModelId.claude_sonnet_5)
-      ) {
+      if (xhighOutputEffortModels.exists(m.contains)) {
         Some(OutputEffort.xhigh)
       } else {
         logger.warn(
           s"reasoning_effort=xhigh is Opus 4.7+ only; downgrading to 'high' for model '$model'."
         )
         Some(OutputEffort.high)
       }
+    case ReasoningEffort.max =>
+      // OutputEffort.max is supported by every output-effort model - including Opus 4.6 and
+      // Sonnet 4.6, which reject xhigh (live-verified 2026-07-11) - and toOutputEffort is only
+      // reached when supportsOutputEffort(model) holds, so no model gate is needed here.
+      Some(OutputEffort.max)
   }
 
   def toAnthropicSettings(

google-gemini-client/src/main/scala/io/cequence/openaiscala/gemini/service/impl/OpenAIGeminiChatCompletionService.scala

@@ -622,9 +622,10 @@ private[service] class OpenAIGeminiChatCompletionService(
     val level: ThinkingLevel = effort match {
       case ReasoningEffort.none | ReasoningEffort.minimal =>
         if (pro) ThinkingLevel.LOW else ThinkingLevel.MINIMAL
-      case ReasoningEffort.low                          => ThinkingLevel.LOW
-      case ReasoningEffort.medium                       => ThinkingLevel.MEDIUM
-      case ReasoningEffort.high | ReasoningEffort.xhigh => ThinkingLevel.HIGH
+      case ReasoningEffort.low    => ThinkingLevel.LOW
+      case ReasoningEffort.medium => ThinkingLevel.MEDIUM
+      case ReasoningEffort.high | ReasoningEffort.xhigh | ReasoningEffort.max =>
+        ThinkingLevel.HIGH
     }
 
     logger.debug(
@@ -657,9 +658,18 @@ private[service] class OpenAIGeminiChatCompletionService(
         )
 
         // budget = 0 is out of range for 2.5 Pro (min 128), so clamp to the minimum.
+        // Conversely, 2.5 Flash / Flash-Lite cap thinkingBudget at 24576 (Pro allows up to
+        // 32768), so clamp the 'max' effort mapping (32768) down on non-Pro models.
+        val nonProMaxBudget = 24576
+        val isPro = model.startsWith(NonOpenAIModelId.gemini_2_5_pro)
         val budgetFinal =
-          if (budget == 0 && model.startsWith(NonOpenAIModelId.gemini_2_5_pro)) 128
-          else budget
+          if (budget == 0 && isPro) 128
+          else if (!isPro && budget > nonProMaxBudget) {
+            logger.warn(
+              s"Thinking budget $budget exceeds the maximum of $nonProMaxBudget for model '$model'. Clamping to $nonProMaxBudget."
+            )
+            nonProMaxBudget
+          } else budget
 
         ThinkingConfig(
           includeThoughts = Some(false),

openai-client/src/main/resources/openai-scala-client.conf

@@ -262,5 +262,11 @@ openai-scala-client {
             gemini = 16384
             anthropic = 16384
         }
+
+        # Highest reasoning tier (GPT-5.6 'max', Responses API only): maximum thinking budget
+        max {
+            gemini = 32768       # Gemini 2.5 Pro thinking_budget ceiling
+            anthropic = 32768
+        }
     }
 }

openai-core/src/main/scala/io/cequence/openaiscala/domain/ModelId.scala

@@ -215,7 +215,10 @@ object ModelId {
   val o1_pro = "o1-pro"
   val o1_pro_2025_03_19 = "o1-pro-2025-03-19"
 
-  // GPT-5.6 (preview announced 2026-06-26; Sol/Terra/Luna capability tiers replace pro/mini/nano)
+  // GPT-5.6 (GA; created 2026-06-23). Sol/Terra/Luna reasoning tiers replace pro/mini/nano.
+  // Reasoning-first: sampling params rejected. reasoning_effort on chat completions supports
+  // none/low/medium/high/xhigh; 'max' is Responses-API-only (chat completions rejects it) and
+  // 'minimal' is rejected by both APIs. Verified against the live API 2026-07-11.
   val gpt_5_6_sol = "gpt-5.6-sol"
   val gpt_5_6_terra = "gpt-5.6-terra"
   val gpt_5_6_luna = "gpt-5.6-luna"

openai-core/src/main/scala/io/cequence/openaiscala/domain/settings/CreateChatCompletionSettings.scala

@@ -185,8 +185,11 @@ object ReasoningEffort {
   case object medium extends ReasoningEffort
   case object high extends ReasoningEffort
   case object xhigh extends ReasoningEffort
+  // Highest reasoning effort; GPT-5.6 (Sol/Terra/Luna) supports it via the Responses API only
+  // (Chat Completions rejects it). Reserve for the hardest quality-first workloads.
+  case object max extends ReasoningEffort
 
-  def values: Seq[ReasoningEffort] = Seq(none, minimal, low, medium, high, xhigh)
+  def values: Seq[ReasoningEffort] = Seq(none, minimal, low, medium, high, xhigh, max)
 
   def fromString(value: String): ReasoningEffort =
     values

openai-core/src/main/scala/io/cequence/openaiscala/service/adapter/ChatCompletionSettingsConversions.scala

@@ -170,6 +170,26 @@ object ChatCompletionSettingsConversions {
       warning = true
     )
 
+    // 'max' is Responses-API-only on GPT-5.6; the chat completions API rejects it with a 400,
+    // so downgrade to the highest chat-completions-supported effort.
+    val reasoningEffortMaxToXHigh: FieldConversionDef = FieldConversionDef(
+      settings => settings.reasoning_effort.contains(ReasoningEffort.max),
+      _.copy(reasoning_effort = Some(ReasoningEffort.xhigh)),
+      Some(settings =>
+        s"${settings.model} model doesn't support reasoning_effort 'max' on the chat completions API (Responses API only), downgrading to 'xhigh'."
+      ),
+      warning = true
+    )
+
+    val reasoningEffortMinimalToLow: FieldConversionDef = FieldConversionDef(
+      settings => settings.reasoning_effort.contains(ReasoningEffort.minimal),
+      _.copy(reasoning_effort = Some(ReasoningEffort.low)),
+      Some(settings =>
+        s"${settings.model} model doesn't support reasoning_effort 'minimal', converting to 'low'."
+      ),
+      warning = true
+    )
+
     val responseFormatTypeMustBeText: FieldConversionDef = FieldConversionDef(
       settings =>
         settings.response_format_type.isDefined && settings.response_format_type.get != ChatCompletionResponseFormatType.text,
@@ -265,16 +285,20 @@ object ChatCompletionSettingsConversions {
   )
 
   // GPT-5.6 (Sol/Terra/Luna) is reasoning-first; restrict all sampling params unconditionally like 5.5.
-  // NOTE: not confirmed against 5.6-specific docs (limited preview); mirrors the GPT-5 reasoning family + 5.5.
-  // TODO: confirm on the live API; if a non-reasoning variant accepts temperature, use gpt5_4's *WithReasoning.
+  // Verified against the live API 2026-07-11: temperature/top_p/presence_penalty/frequency_penalty/logprobs
+  // all return 400 for every tier, and max_tokens must be sent as max_completion_tokens.
+  // reasoning_effort on chat completions supports none/low/medium/high/xhigh only - 'max' is
+  // Responses-API-only and 'minimal' is rejected by both APIs, so downgrade both here.
   val gpt5_6: SettingsConversion = generic(
     Seq(
       maxTokensToMaxCompletionTokens,
       temperatureOneOnly,
       topPOneOnly,
       presencePenaltyZeroOnly,
       frequencyPenaltyZeroOnly,
-      logProbsUnsupported
+      logProbsUnsupported,
+      reasoningEffortMaxToXHigh,
+      reasoningEffortMinimalToLow
     )
   )
 

openai-examples/src/main/scala/io/cequence/openaiscala/examples/anthropic/AnthropicOpus48ReasoningEffortMapping.scala

@@ -29,7 +29,8 @@ object AnthropicOpus48ReasoningEffortMapping extends ExampleBase[OpenAIChatCompl
     ReasoningEffort.low,
     ReasoningEffort.medium,
     ReasoningEffort.high,
-    ReasoningEffort.xhigh
+    ReasoningEffort.xhigh,
+    ReasoningEffort.max
   )
 
   private def report(model: String): Unit = {
@@ -54,6 +55,10 @@ object AnthropicOpus48ReasoningEffortMapping extends ExampleBase[OpenAIChatCompl
     report(NonOpenAIModelId.claude_opus_4_8)
     report(NonOpenAIModelId.bedrock_claude_opus_4_8)
 
+    // Opus 4.6 rejects xhigh (downgraded to high) but accepts max (live-verified 2026-07-11),
+    // so xhigh and max map differently here
+    report(NonOpenAIModelId.claude_opus_4_6)
+
     // sanity: an older non-output-effort model still uses the legacy thinking-budget path
     report(NonOpenAIModelId.claude_3_7_sonnet_latest)
   }

openai-examples/src/main/scala/io/cequence/openaiscala/examples/responsesapi/CreateModelResponseGPT56SolMaxReasoning.scala

@@ -0,0 +1,37 @@
+package io.cequence.openaiscala.examples.responsesapi
+
+import io.cequence.openaiscala.domain.ModelId
+import io.cequence.openaiscala.domain.responsesapi.{
+  CreateModelResponseSettings,
+  Inputs,
+  ReasoningConfig
+}
+import io.cequence.openaiscala.domain.settings.ReasoningEffort
+import io.cequence.openaiscala.examples.Example
+
+import scala.concurrent.Future
+
+/**
+ * Smoke test: GPT-5.6's top reasoning tier 'max' is Responses-API-only - the chat completions
+ * endpoint rejects reasoning_effort=max (and 'minimal') for gpt-5.6 models, while
+ * /v1/responses accepts it (live-verified 2026-07-11). On the chat-completion path,
+ * ChatCompletionSettingsConversions.gpt5_6 downgrades 'max' to 'xhigh' instead.
+ */
+object CreateModelResponseGPT56SolMaxReasoning extends Example {
+
+  override def run: Future[Unit] =
+    service
+      .createModelResponse(
+        Inputs.Text("What is the capital of Norway? One word."),
+        settings = CreateModelResponseSettings(
+          model = ModelId.gpt_5_6_sol,
+          reasoning = Some(ReasoningConfig(effort = Some(ReasoningEffort.max)))
+        )
+      )
+      .map { response =>
+        println(s"Response: ${response.outputText.getOrElse("N/A")}")
+        response.usage.foreach { u =>
+          println(s"Usage: in=${u.inputTokens} out=${u.outputTokens} total=${u.totalTokens}")
+        }
+      }
+}