fix(gemini): follow provider defaults for Gemini 3 thinking

[Sameerlite]

Summary

• stop forcing thinkingLevel for Gemini 3 when thinking params are passed, so default behavior follows provider defaults
• keep legacy low/minimal forcing available via feature flag enable_gemini_default_thinking_level_low
• add/update Gemini translation tests and provider docs to clarify default vs opt-in behavior

Docs: BerriAI/litellm-docs#60

---

Note

Medium Risk
Changes Gemini 3 request translation to stop forcing thinkingLevel when thinking is provided, which can alter model behavior/output and token usage for existing integrations; legacy behavior is retained behind a new feature flag.

Overview
Gemini 3+ thinking parameter mapping now follows provider defaults by default: VertexGeminiConfig._map_thinking_param sets includeThoughts but no longer injects a thinkingLevel value.

Adds litellm.enable_gemini_default_thinking_level_low (default False) to optionally restore the prior behavior of forcing thinkingLevel (minimal for gemini-3-flash*, otherwise low). Tests are updated/split to cover both default and feature-flagged behavior, including the full map_openai_params flow.

^{Reviewed by Cursor Bugbot for commit 8d9db7b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Apr 15, 2026 9:33am

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing litellm_gemini_provider_default_thinking (f029346) with main (72a461b)}

[greptile-apps]

Greptile Summary

This PR changes Gemini 3 thinking parameter translation to stop forcing thinkingLevel by default, instead delegating to provider defaults, with legacy forced-low behavior preserved behind litellm.enable_gemini_default_thinking_level_low.

• The feature flag defaults to False (new behavior), which is backwards-incompatible: existing Gemini 3 users who previously received a forced thinkingLevel will silently get different model behavior after upgrading without any opt-in action. Per project convention, the flag should default to preserving the old behavior (True) and users should opt in to the new provider-default path.
• Hardcoded \"gemini-3-flash\" / \"gemini-3-flash-preview\" string checks in the feature-flag branch should be moved to model_prices_and_context_window.json per the project's model-capability pattern.

Confidence Score: 4/5

Safe to merge after addressing the flag default direction; logic itself is correct but the default silently breaks existing Gemini 3 thinking integrations.

One P1 finding: the feature flag defaults to the new behavior rather than preserving the old one, creating an unannounced breaking change for existing users. The core translation logic and test coverage are sound, limiting exposure, but the default choice conflicts with the project's backwards-compatibility policy.

litellm/init.py — flag default direction needs review before merging.

Important Files Changed

Filename	Overview
litellm/init.py	Adds enable_gemini_default_thinking_level_low flag (default False); flag defaults to new behavior, creating a backwards-incompatible change for existing Gemini 3 users.
litellm/llms/vertex_ai/gemini/vertex_and_google_ai_studio_gemini.py	Removes forced thinkingLevel injection for Gemini 3 models; now only sets it when feature flag is True. Logic is correct; retains pre-existing hardcoded model-name checks.
tests/llm_translation/test_gemini.py	Existing test split into default-behavior and feature-flag paths; assertions correctly updated to reflect new provider-default behavior; flag state is restored in finally blocks.

_{Reviews (4): Last reviewed commit: "fix(gemini): follow provider defaults fo..." | Re-trigger Greptile}

[gitguardian]

⚠️ GitGuardian has uncovered 2 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
29203092	Triggered	Generic High Entropy Secret	0c4aaa2	tests/test_litellm/proxy/test_api_key_masking_in_errors.py	View secret
29203053	Triggered	Generic Password	a86f426	.circleci/config.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ex_ai/gemini/vertex_and_google_ai_studio_gemini.py	0.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 8d9db7b. Configure here.}

[mateo-berri]

@greptileai

[greptile-apps]

Backwards-incompatible default — existing users will silently get new behavior

The flag defaults to False, which means every Gemini 3 user upgrading litellm will immediately stop receiving a forced thinkingLevel in their requests without any action on their part. Per the project's backwards-compatibility rule, the safe default is to preserve the existing behavior (defaulting to True) and require users to explicitly opt in to the new provider-default behavior. As written, users who relied on thinkingLevel being set need to find and set this flag to restore it — discovery is poor and the risk of silent regressions is high.

Consider either defaulting to True (preserve old behavior, opt-in to new), or naming the flag around the new behavior (e.g. enable_gemini_provider_default_thinking) and defaulting it to False so existing behavior is unchanged until users explicitly enable it.

Rule Used: What: avoid backwards-incompatible changes without... (source)

[mateo-berri]

Is greptile issue a concern?

[Sameerlite]

@mateo-berri It is talking about backward compatibility, we can just tell the users to use this flag if the want litellm to set default thinking. I don't think we should by default set a thinking level. So i don't think the comment is relevant

[mateo-berri]

OK, makes sense. LGTM!