fix(gemini): let 4xx fall through the structured-output ladder and gate the no_think strategy by model - #3613

AgentScope Version

2.0.12dev (main @ 2350af9)

Description

GeminiChatModel is the only mainline provider without a _get_structured_output_fallback_exceptions override, and its _get_retryable_exceptions returns the wide (google.genai.errors.APIError,) (model/_gemini/_model.py:250-258) — the parent of both ClientError (4xx) and ServerError (5xx). In the structured-output ladder, the retryable check runs before the fallback check, and retry-exhaustion raises unconditionally (model/_base.py:582). So any 4xx aborts the whole ladder — the auto / no_think / none strategies are never tried. Every other provider declares a narrow retryable set whose members never intersect its fallback tuple, so 4xx falls through for them.

Changes

1. model/_base.py (give-up branch): when a retryable exception exhausts its retries but is also fallback-eligible, walk the ladder instead of raising. Providers whose retryable and fallback sets are disjoint (all but Gemini today) are unaffected — the new branch is unreachable for them. A purely transient error that is not fallback-eligible still raises as before.
2. model/_gemini/_model.py: declare _get_structured_output_fallback_exceptions → (errors.ClientError,) so 4xx switches strategies (5xx stay retryable).
3. model/_gemini/_model.py: implement _get_disable_thinking_kwargs, the same gap [Bug]: Ollama structured-output fallback never tries no_think — _get_disable_thinking_kwargs is not overridden #3583/fix(ollama): implement _get_disable_thinking_kwargs so structured-output fallback can disable thinking #3588 fixed for Ollama, gated by model — 2.5 Flash / Flash-Lite accept thinking_budget: 0, but the pro models reject it with 400 and Gemini 3 deprecates thinking_budget, so those return {} and keep the server default.

Complementary to #3523 (tri-state thinking_enable): that fix stopped out-of-the-box budget-0 failures for pro models; this adds the structured-output no_think step for the models that support it.

Open question for maintainers: with the give-up branch consulting the fallback tuple, a 429 (also a ClientError) now falls to the next strategy after its retries instead of aborting — bounded extra calls to a rate-limited endpoint. If that is undesirable, the alternative is gating the no_think kwargs more narrowly and leaving the base branch untouched, at the cost of keeping the abort for schema-type 4xx.

How to test

Regression cases added to the existing test files:

• tests/model_base_test.py::StructuredOutputRetryableFallbackTest — an exception that is both retryable and fallback-eligible walks the ladder after exhausting retries (fails on main: the ladder aborts);
• tests/model_gemini_test.py::GeminiStructuredFallbackTest — a mocked 400 walks all four strategies (len(attempts) > (max_retries + 1) * 2; fails on main with 4 not greater than 8), plus assertions pinning the fallback-exception tuple and the model-gated no_think kwargs.

python -m pytest tests/model_base_test.py tests/model_gemini_test.py
# 24 + 43 passed.

Fixes #3612

Checklist

• An issue has been created for this PR
• I have read the CONTRIBUTING.md
• Docstrings are in Google style
• Related documentation has been updated (e.g. links, examples, etc.) in documentation repository
• Code is ready for review