fix: reset stale reasoning effort, clarify docs

[steebchen]

Summary

Follow-up to #3028, addressing the CodeRabbit review comments that couldn't land there because the branch was locked in the merge queue.

• Playground: reset uncatalogued reasoning efforts too. A previously selected effort (e.g. max on gpt-5.6-sol) survived switching to a model with no declared reasoningEfforts in the catalog, leaving the selector with no matching item while still sending the unsupported reasoning_effort upstream — which now fails with a provider 4xx since feat: per-mapping reasoning efforts, forward as-is #3028 removed the downgrade. Both reset effects (main chat and comparison panel) now validate against the same effective options the selector renders, via a shared getFallbackReasoningEffortOptions helper that also replaces the inline fallback in the dropdown.
• Docs/API descriptions: clarify that effort tiers are never downgraded by the gateway — enum-based providers receive the value unchanged (unsupported values result in a provider error), while budget-based providers (Anthropic, Google) translate each tier to a native thinking budget. Applied to both reasoning_effort descriptions in the chat completions schema, the Anthropic endpoint comment, and the reasoning docs page.

Testing

• turbo run build --filter=playground --filter=gateway passes.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FPnpiisz8mM8nRGyVpWmUh

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added consistent fallback reasoning-effort options for models without published support details.
  • Reasoning-effort selections now automatically adapt when switching models, clearing unsupported values.

• Bug Fixes

  • Prevented invalid reasoning-effort settings from remaining selected for unsupported models.
  • Clarified that reasoning tiers are not downgraded and are translated appropriately for providers using native thinking budgets.

• Documentation

  • Updated configuration and API descriptions to explain reasoning-effort handling and provider-specific behavior.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: c94dcdc5-eed3-44e6-ae61-5b0a26e64528

📥 Commits

Reviewing files that changed from the base of the PR and between aba51a2 and 1c0b70f.

📒 Files selected for processing (6)

• apps/docs/content/features/reasoning.mdx
• apps/gateway/src/anthropic/anthropic.ts
• apps/gateway/src/chat/schemas/completions.ts
• apps/playground/src/components/playground/chat-page-client.tsx
• apps/playground/src/components/playground/chat-ui.tsx
• apps/playground/src/lib/model-utils.ts

---

Walkthrough

Reasoning-effort documentation now describes non-downgraded provider handling. The playground centralizes fallback effort options and resets unsupported selections using catalog or model-based fallback options.

Changes

Reasoning effort updates

Layer / File(s)	Summary
Reasoning effort semantics apps/docs/content/features/reasoning.mdx, apps/gateway/src/anthropic/anthropic.ts, apps/gateway/src/chat/schemas/completions.ts	Documentation and schema comments clarify tier preservation, provider passthrough, and thinking-budget translation.
Fallback effort options apps/playground/src/lib/model-utils.ts, apps/playground/src/components/playground/chat-ui.tsx	A shared helper provides model-specific fallback effort options, which the dropdown uses when catalog options are unavailable.
Effort state validation apps/playground/src/components/playground/chat-page-client.tsx	The main chat page and extra panel reset reasoning effort when it is unsupported by catalog or fallback options.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• theopenco/llmgateway#2224: Updates reasoning capability detection and effort reset behavior in the playground.

Suggested reviewers: copilot, smakosh

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main changes: resetting stale reasoning effort and clarifying documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/max-reasoning-effort-mapping-320rl2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}