Studio: add Gemini provider with web_search, code_execution, prompt caching, and Nano Banana image generation

studio/backend/core/inference/providers.py

@@ -65,28 +65,77 @@
     },
     "gemini": {
         "display_name": "Google Gemini",
-        "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
-        # Curated lineup — Google's /v1beta/openai/models returns dozens
-        # of historical / experimental / embedding ids. Cap to the current
-        # 3.x family plus the rolling `*-latest` aliases.
+        # Native Gemini REST endpoint -- the Gemini API does NOT speak
+        # OpenAI Chat Completions on this base. Requests/responses are
+        # translated in `_stream_gemini` in external_provider.py.
+        # API reference: https://ai.google.dev/gemini-api/docs
+        "base_url": "https://generativelanguage.googleapis.com/v1beta",
+        # Curated lineup -- the live ListModels response returns dozens
+        # of historical / experimental / embedding ids. Cap to the
+        # current chat-capable Gemini families (3.5 / 3.1 / 3 Flash /
+        # 2.5) plus the Nano Banana image trio and the rolling
+        # `*-latest` aliases. Excluded on purpose:
+        #   - `gemini-2.0-flash*` (Google retired 2026-06-01; 404 on use)
+        #   - `gemini-3-pro-preview` (shut down 2026-03-09; auto-redirects
+        #     to `gemini-3.1-pro-preview` per Google's deprecation notice,
+        #     so we surface 3.1 directly and skip the redirect).
+        # The allowlist below blocks the retired ids from re-appearing
+        # via the live ListModels fetch. Verified against the live
+        # `/v1beta/models` catalog 2026-05-24.
         "default_models": [
             "gemini-3.1-pro-preview",
+            "gemini-3.5-flash",
             "gemini-3.1-flash-lite",
             "gemini-3-flash-preview",
             "gemini-pro-latest",
             "gemini-flash-latest",
             "gemini-flash-lite-latest",
+            "gemini-2.5-pro",
+            "gemini-2.5-flash",
+            "gemini-2.5-flash-lite",
+            "gemini-3-pro-image-preview",
+            "gemini-3.1-flash-image-preview",
+            "gemini-2.5-flash-image",
         ],
         "supports_streaming": True,
         "supports_vision": True,
         "supports_tool_calling": True,
-        "auth_header": "Authorization",
-        "auth_prefix": "Bearer ",
-        "notes": "OpenAI-compatible endpoint. API key from https://aistudio.google.com/apikey.",
+        # The native API takes the API key on the `x-goog-api-key`
+        # header. An empty `auth_prefix` ensures we send the bare key.
+        "auth_header": "x-goog-api-key",
+        "auth_prefix": "",
+        "openai_compatible": False,
+        "notes": (
+            "Native Gemini API. Translation lives in _stream_gemini. "
+            "API key from https://aistudio.google.com/apikey. "
+            "See https://ai.google.dev/gemini-api/docs for endpoint shapes."
+        ),
+        # Even after the regex match, drop ids that Google still
+        # returns from ListModels but routes via implicit redirect.
+        # gemini-3-pro-preview was shut down 2026-03-09 and is
+        # auto-aliased to gemini-3.1-pro-preview; we surface the
+        # canonical id only so users do not see two cards for the
+        # same underlying model.
+        "model_id_deny_exact": ("gemini-3-pro-preview",),
+        # Matches the chat-capable 3.5 / 3.1 / 3 / 2.5 families plus the
+        # rolling *-latest aliases (which Google rolls forward as new
+        # generations ship). Image-tier ids (`-image`, `-image-preview`,
+        # `nano-banana-pro-preview`) flow through the Nano Banana
+        # `responseModalities` path in `_stream_gemini`. Retired 2.0
+        # ids ARE NOT in this regex on purpose -- Google's ListModels
+        # would otherwise re-surface them and they 404 on use.
         "model_id_allowlist": re.compile(
-            r"^(gemini-3\.1-flash-lite|gemini-3-flash-preview|"
-            r"gemini-3\.1-pro-preview|gemini-pro-latest|"
-            r"gemini-flash-latest|gemini-flash-lite-latest)$"
+            r"^("
+            r"gemini-3\.5-(?:flash|pro)(?:-preview)?|"
+            r"gemini-3\.1-(?:flash|pro|flash-lite)(?:-preview)?(?:-customtools)?|"
+            r"gemini-3\.1-flash-image-preview|"
+            r"gemini-3-(?:flash|pro)(?:-preview)?|"
+            r"gemini-3-pro-image-preview|"
+            r"nano-banana-pro-preview|"
+            r"gemini-2\.5-pro|gemini-2\.5-flash|gemini-2\.5-flash-lite|"
+            r"gemini-2\.5-flash-image|"
+            r"gemini-pro-latest|gemini-flash-latest|gemini-flash-lite-latest"
+            r")$"
         ),
     },
     "deepseek": {

studio/backend/models/inference.py

@@ -541,6 +541,14 @@ class ChatMessage(BaseModel):
         None,
         description = "OpenAI tool-result messages: name of the tool whose result this is.",
     )
+    extra_content: Optional[dict] = Field(
+        None,
+        description = (
+            "Provider-specific extra fields the translator may read. "
+            "Gemini reads `extra_content.google.thought_signature` "
+            "from assistant messages to replay text-part signatures."
+        ),
+    )
 
     @model_validator(mode = "after")
     def _validate_role_shape(self) -> "ChatMessage":
@@ -712,17 +720,42 @@ class ChatCompletionRequest(BaseModel):
         None,
         description = "[x-unsloth] Override base URL for the external provider.",
     )
-    enable_prompt_caching: Optional[bool] = Field(
+    enable_prompt_caching: Optional[Union[bool, str]] = Field(
         None,
         description = (
             "[x-unsloth] Opt in to provider-side prompt caching. On Anthropic, "
-            "attaches cache_control={type:ephemeral} to the system block so the "
-            "static prefix is reused across turns. On OpenAI cloud, caching is "
-            "automatic for prompts >=1024 tokens and this flag is informational. "
-            "Ignored for every other provider (mistral, gemini, kimi, openrouter, "
-            "vllm, local, etc.). Treated as enabled when omitted."
+            "boolean true attaches cache_control={type:ephemeral} to the system "
+            "block so the static prefix is reused across turns. On OpenAI cloud, "
+            "caching is automatic for prompts >=1024 tokens and the boolean is "
+            "informational. On Gemini, pass a string cache resource name such "
+            "as `cachedContents/abc123` to attach `cachedContent` on the native "
+            "request (boolean true is a no-op on Gemini because creating the "
+            "cache requires a separate POST /cachedContents call). Ignored for "
+            "every other provider. Treated as enabled when omitted."
         ),
     )
+
+    @field_validator("enable_prompt_caching", mode = "before")
+    @classmethod
+    def _coerce_enable_prompt_caching(cls, value: Any) -> Any:
+        """Preserve the pre-PR coercion: the field used to be Optional[bool],
+        so callers historically sent JSON strings `"true"` / `"false"` and
+        Pydantic v1 coerced them. Widening to Optional[Union[bool, str]] for
+        Gemini cache resource names lets `"false"` slip through as a truthy
+        string. Coerce the canonical bool literals back so explicit opt-outs
+        stay opt-out."""
+        if isinstance(value, str):
+            lowered = value.strip().lower()
+            # Match Pydantic v1's BooleanField coercion table (yes/y/on/t/1
+            # and no/n/off/f/0) so opt-outs that used to parse still parse.
+            # Anything else is preserved as a string for Gemini's
+            # cachedContent resource path.
+            if lowered in ("true", "t", "1", "yes", "y", "on"):
+                return True
+            if lowered in ("false", "f", "0", "no", "n", "off"):
+                return False
+        return value
+
     prompt_cache_ttl: Optional[str] = Field(
         None,
         description = (

studio/backend/routes/inference.py

@@ -1697,6 +1697,7 @@ def _build_external_messages(
     messages: list,
     supports_vision: bool,
     provider_type: Optional[str] = None,
+    base_url: Optional[str] = None,
 ) -> list[dict]:
     """
     Convert ChatMessage list to OpenAI-compatible dicts for external providers.
@@ -1717,14 +1718,61 @@ def _build_external_messages(
     """
     document_provider = provider_type in _INPUT_DOCUMENT_PROVIDERS
     anthropic = provider_type == "anthropic"
+    # `extra_content` is a Gemini-specific carrier for the assistant's
+    # text-part `thoughtSignature` round-trip on the native
+    # streamGenerateContent endpoint. Custom Gemini OpenAI-compatible
+    # gateways (LiteLLM etc.) route through /chat/completions where
+    # the field is unknown and can be rejected -- gate strictly on the
+    # Google-hosted Gemini base.
+    _native_gemini = False
+    if provider_type == "gemini" and base_url:
+        try:
+            from urllib.parse import urlparse as _urlparse
+
+            _host = (_urlparse(base_url).hostname or "").lower()
+            _native_gemini = _host == "generativelanguage.googleapis.com"
+        except Exception:
+            _native_gemini = False
+    emit_extra_content = _native_gemini
     result = []
     for msg in messages:
         if isinstance(msg.content, str):
-            # Skip assistant messages with empty content (some providers reject them)
-            if msg.role == "assistant" and not msg.content.strip():
+            # Drop bare assistant messages with no content AND no
+            # tool_calls (some providers reject empty assistant turns).
+            # Preserve assistant turns whose only payload is tool_calls
+            # so multi-turn function-call loops round-trip.
+            if (
+                msg.role == "assistant"
+                and not msg.content.strip()
+                and not msg.tool_calls
+            ):
                 continue
-            result.append({"role": msg.role, "content": msg.content})
-        elif isinstance(msg.content, list):
+            out: dict[str, Any] = {"role": msg.role, "content": msg.content}
+            if msg.role == "assistant" and msg.tool_calls:
+                out["tool_calls"] = msg.tool_calls
+            if msg.role == "tool":
+                if msg.tool_call_id:
+                    out["tool_call_id"] = msg.tool_call_id
+                if msg.name:
+                    out["name"] = msg.name
+            if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                out["extra_content"] = msg.extra_content
+            result.append(out)
+            continue
+        # Assistant messages with content=None but populated tool_calls
+        # are valid (post-tool-call assistant turn). Forward them so the
+        # provider helper can rebuild the functionCall part.
+        if msg.content is None and msg.role == "assistant" and msg.tool_calls:
+            _assistant_only: dict[str, Any] = {
+                "role": "assistant",
+                "content": "",
+                "tool_calls": msg.tool_calls,
+            }
+            if emit_extra_content and msg.extra_content:
+                _assistant_only["extra_content"] = msg.extra_content
+            result.append(_assistant_only)
+            continue
+        if isinstance(msg.content, list):
             if supports_vision:
                 parts = []
                 for part in msg.content:
@@ -1758,7 +1806,17 @@ def _build_external_messages(
                         # provider would 400 on the unknown part, so
                         # gate by provider_type.
                         parts.append({"type": "compaction", "content": part.content})
-                result.append({"role": msg.role, "content": parts})
+                entry: dict[str, Any] = {"role": msg.role, "content": parts}
+                if msg.role == "assistant" and msg.tool_calls:
+                    entry["tool_calls"] = msg.tool_calls
+                if msg.role == "tool":
+                    if msg.tool_call_id:
+                        entry["tool_call_id"] = msg.tool_call_id
+                    if msg.name:
+                        entry["name"] = msg.name
+                if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                    entry["extra_content"] = msg.extra_content
+                result.append(entry)
             else:
                 # Non-vision provider: strip images / documents, keep
                 # text, optionally keep compaction (Anthropic only --
@@ -1774,9 +1832,19 @@ def _build_external_messages(
                 if len(preserved) == 1 and preserved[0]["type"] == "text":
                     # Single text part collapses back to a string for
                     # providers that don't accept content arrays.
-                    result.append({"role": msg.role, "content": preserved[0]["text"]})
+                    entry = {"role": msg.role, "content": preserved[0]["text"]}
                 else:
-                    result.append({"role": msg.role, "content": preserved})
+                    entry = {"role": msg.role, "content": preserved}
+                if msg.role == "assistant" and msg.tool_calls:
+                    entry["tool_calls"] = msg.tool_calls
+                if msg.role == "tool":
+                    if msg.tool_call_id:
+                        entry["tool_call_id"] = msg.tool_call_id
+                    if msg.name:
+                        entry["name"] = msg.name
+                if emit_extra_content and msg.role == "assistant" and msg.extra_content:
+                    entry["extra_content"] = msg.extra_content
+                result.append(entry)
     return result
 
 
@@ -1851,6 +1919,7 @@ async def _proxy_to_external_provider(
         payload.messages,
         _supports_vision,
         provider_type = provider_type,
+        base_url = base_url,
     )
 
     client = ExternalProviderClient(
@@ -1859,6 +1928,14 @@ async def _proxy_to_external_provider(
         api_key = api_key,
     )
 
+    # `top_k` defaults to 20 in ChatCompletionRequest because the local
+    # inference path expects an int, but the external-provider path
+    # should treat "field omitted from JSON" as "use provider default"
+    # so callers that send only model/messages do not silently get
+    # different sampling than before this PR. Pydantic's
+    # `model_fields_set` tracks explicit-vs-default per request.
+    _top_k_explicit = payload.top_k if "top_k" in payload.model_fields_set else None
+
     async def _stream():
         gen = client.stream_chat_completion(
             messages = chat_messages,
@@ -1867,7 +1944,7 @@ async def _stream():
             top_p = payload.top_p,
             max_tokens = payload.max_tokens,
             presence_penalty = payload.presence_penalty,
-            top_k = payload.top_k,
+            top_k = _top_k_explicit,
             enable_thinking = payload.enable_thinking,
             reasoning_effort = payload.reasoning_effort,
             enabled_tools = payload.enabled_tools,
@@ -1876,6 +1953,8 @@ async def _stream():
             anthropic_code_exec_container_id = payload.anthropic_code_exec_container_id,
             prompt_cache_ttl = payload.prompt_cache_ttl,
             compaction_threshold = payload.compaction_threshold,
+            tools = payload.tools,
+            tool_choice = payload.tool_choice,
             stream = payload.stream,
         )
         try:

studio/backend/tests/test_anthropic_code_execution.py

@@ -275,7 +275,13 @@ async def run():
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "code_execution"
     assert start["tool_call_id"] == "srvtoolu_1"
-    assert start["arguments"] == {"kind": "bash", "command": "ls -la"}
+    # `_server_tool: True` marks this as a provider-side synthetic
+    # tool card for the frontend's history serializer.
+    assert start["arguments"] == {
+        "kind": "bash",
+        "command": "ls -la",
+        "_server_tool": True,
+    }
 
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_1"

studio/backend/tests/test_anthropic_web_fetch.py

@@ -285,7 +285,12 @@ async def run():
     assert start["type"] == "tool_start"
     assert start["tool_name"] == "web_fetch"
     assert start["tool_call_id"] == "srvtoolu_wf1"
-    assert start["arguments"] == {"url": "https://example.com/article"}
+    # `_server_tool: True` marks this as a provider-side synthetic
+    # tool card for the frontend's history serializer.
+    assert start["arguments"] == {
+        "url": "https://example.com/article",
+        "_server_tool": True,
+    }
     assert end["type"] == "tool_end"
     assert end["tool_call_id"] == "srvtoolu_wf1"
     # The source pill uses Title / URL / snippet as parseSourcesFromResult expects.