fix: fix parameter schema generation for gemini

this fixes https://github.com/google/adk-python/issues/1055
and https://github.com/google/adk-python/issues/881

PiperOrigin-RevId: 766288394

src/google/adk/tools/_gemini_schema_util.py

@@ -0,0 +1,130 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from typing import Optional
+
+from google.genai.types import JSONSchema
+from google.genai.types import Schema
+from pydantic import Field
+
+from ..utils.variant_utils import get_google_llm_variant
+
+
+class _ExtendedJSONSchema(JSONSchema):
+  property_ordering: Optional[list[str]] = Field(
+      default=None,
+      description="""Optional. The order of the properties. Not a standard field in open api spec. Only used to support the order of the properties.""",
+  )
+
+
+def _to_snake_case(text: str) -> str:
+  """Converts a string into snake_case.
+
+  Handles lowerCamelCase, UpperCamelCase, or space-separated case, acronyms
+  (e.g., "REST API") and consecutive uppercase letters correctly.  Also handles
+  mixed cases with and without spaces.
+
+  Examples:
+  ```
+  to_snake_case('camelCase') -> 'camel_case'
+  to_snake_case('UpperCamelCase') -> 'upper_camel_case'
+  to_snake_case('space separated') -> 'space_separated'
+  ```
+
+  Args:
+      text: The input string.
+
+  Returns:
+      The snake_case version of the string.
+  """
+
+  # Handle spaces and non-alphanumeric characters (replace with underscores)
+  text = re.sub(r"[^a-zA-Z0-9]+", "_", text)
+
+  # Insert underscores before uppercase letters (handling both CamelCases)
+  text = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", text)  # lowerCamelCase
+  text = re.sub(
+      r"([A-Z]+)([A-Z][a-z])", r"\1_\2", text
+  )  # UpperCamelCase and acronyms
+
+  # Convert to lowercase
+  text = text.lower()
+
+  # Remove consecutive underscores (clean up extra underscores)
+  text = re.sub(r"_+", "_", text)
+
+  # Remove leading and trailing underscores
+  text = text.strip("_")
+
+  return text
+
+
+def _sanitize_schema_formats_for_gemini(schema_node: Any) -> Any:
+  """Helper function to sanitize schema formats for Gemini compatibility"""
+  if isinstance(schema_node, dict):
+    new_node = {}
+    current_type = schema_node.get("type")
+
+    for key, value in schema_node.items():
+      key = _to_snake_case(key)
+
+      # special handle of format field
+      if key == "format":
+        current_format = value
+        format_to_keep = None
+        if current_format:
+          if current_type == "integer" or current_type == "number":
+            if current_format in ("int32", "int64"):
+              format_to_keep = current_format
+          elif current_type == "string":
+            # only 'enum' and 'date-time' are supported for STRING type"
+            if current_format in ("date-time", "enum"):
+              format_to_keep = current_format
+          # For any other type or unhandled format
+          # the 'format' key will be effectively removed for that node.
+          if format_to_keep:
+            new_node[key] = format_to_keep
+        continue
+      # don't change property name
+      if key == "properties":
+        new_node[key] = {
+            k: _sanitize_schema_formats_for_gemini(v) for k, v in value.items()
+        }
+        continue
+      # Recursively sanitize other parts of the schema
+      new_node[key] = _sanitize_schema_formats_for_gemini(value)
+    return new_node
+  elif isinstance(schema_node, list):
+    return [_sanitize_schema_formats_for_gemini(item) for item in schema_node]
+  else:
+    return schema_node
+
+
+def _to_gemini_schema(openapi_schema: dict[str, Any]) -> Schema:
+  """Converts an OpenAPI schema dictionary to a Gemini Schema object."""
+  if openapi_schema is None:
+    return None
+
+  if not isinstance(openapi_schema, dict):
+    raise TypeError("openapi_schema must be a dictionary")
+
+  openapi_schema = _sanitize_schema_formats_for_gemini(openapi_schema)
+  return Schema.from_json_schema(
+      json_schema=_ExtendedJSONSchema.model_validate(openapi_schema),
+      api_option=get_google_llm_variant(),
+  )

src/google/adk/tools/apihub_tool/apihub_toolset.py

@@ -12,6 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
 
 from typing import List
 from typing import Optional
@@ -23,9 +24,9 @@ import yaml
 from ...agents.readonly_context import ReadonlyContext
 from ...auth.auth_credential import AuthCredential
 from ...auth.auth_schemes import AuthScheme
+from .._gemini_schema_util import _to_snake_case
 from ..base_toolset import BaseToolset
 from ..base_toolset import ToolPredicate
-from ..openapi_tool.common.common import to_snake_case
 from ..openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
 from ..openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
 from .clients.apihub_client import APIHubClient
@@ -171,7 +172,7 @@ class APIHubToolset(BaseToolset):
     if not spec_dict:
       return
 
-    self.name = self.name or to_snake_case(
+    self.name = self.name or _to_snake_case(
         spec_dict.get('info', {}).get('title', 'unnamed')
     )
     self.description = self.description or spec_dict.get('info', {}).get(

src/google/adk/tools/application_integration_tool/integration_connector_tool.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import logging
 from typing import Any
 from typing import Dict
@@ -24,8 +26,8 @@ from typing_extensions import override
 from .. import BaseTool
 from ...auth.auth_credential import AuthCredential
 from ...auth.auth_schemes import AuthScheme
+from .._gemini_schema_util import _to_gemini_schema
 from ..openapi_tool.openapi_spec_parser.rest_api_tool import RestApiTool
-from ..openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
 from ..openapi_tool.openapi_spec_parser.tool_auth_handler import ToolAuthHandler
 from ..tool_context import ToolContext
 
@@ -128,7 +130,7 @@ class IntegrationConnectorTool(BaseTool):
       if field in schema_dict['required']:
         schema_dict['required'].remove(field)
 
-    parameters = to_gemini_schema(schema_dict)
+    parameters = _to_gemini_schema(schema_dict)
     function_decl = FunctionDeclaration(
         name=self.name, description=self.description, parameters=parameters
     )

src/google/adk/tools/mcp_tool/mcp_tool.py

@@ -20,6 +20,7 @@ from typing import Optional
 from google.genai.types import FunctionDeclaration
 from typing_extensions import override
 
+from .._gemini_schema_util import _to_gemini_schema
 from .mcp_session_manager import MCPSessionManager
 from .mcp_session_manager import retry_on_closed_resource
 
@@ -42,7 +43,6 @@ except ImportError as e:
 from ...auth.auth_credential import AuthCredential
 from ...auth.auth_schemes import AuthScheme
 from ..base_tool import BaseTool
-from ..openapi_tool.openapi_spec_parser.rest_api_tool import to_gemini_schema
 from ..tool_context import ToolContext
 
 logger = logging.getLogger("google_adk." + __name__)
@@ -99,7 +99,7 @@ class MCPTool(BaseTool):
         FunctionDeclaration: The Gemini function declaration for the tool.
     """
     schema_dict = self._mcp_tool.inputSchema
-    parameters = to_gemini_schema(schema_dict)
+    parameters = _to_gemini_schema(schema_dict)
     function_decl = FunctionDeclaration(
         name=self.name, description=self.description, parameters=parameters
     )

src/google/adk/tools/openapi_tool/common/common.py

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import keyword
-import re
 from typing import Any
 from typing import Dict
 from typing import List
@@ -26,47 +27,7 @@ from pydantic import BaseModel
 from pydantic import Field
 from pydantic import model_serializer
 
-
-def to_snake_case(text: str) -> str:
-  """Converts a string into snake_case.
-
-  Handles lowerCamelCase, UpperCamelCase, or space-separated case, acronyms
-  (e.g., "REST API") and consecutive uppercase letters correctly.  Also handles
-  mixed cases with and without spaces.
-
-  Examples:
-  ```
-  to_snake_case('camelCase') -> 'camel_case'
-  to_snake_case('UpperCamelCase') -> 'upper_camel_case'
-  to_snake_case('space separated') -> 'space_separated'
-  ```
-
-  Args:
-      text: The input string.
-
-  Returns:
-      The snake_case version of the string.
-  """
-
-  # Handle spaces and non-alphanumeric characters (replace with underscores)
-  text = re.sub(r'[^a-zA-Z0-9]+', '_', text)
-
-  # Insert underscores before uppercase letters (handling both CamelCases)
-  text = re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', text)  # lowerCamelCase
-  text = re.sub(
-      r'([A-Z]+)([A-Z][a-z])', r'\1_\2', text
-  )  # UpperCamelCase and acronyms
-
-  # Convert to lowercase
-  text = text.lower()
-
-  # Remove consecutive underscores (clean up extra underscores)
-  text = re.sub(r'_+', '_', text)
-
-  # Remove leading and trailing underscores
-  text = text.strip('_')
-
-  return text
+from ..._gemini_schema_util import _to_snake_case
 
 
 def rename_python_keywords(s: str, prefix: str = 'param_') -> str:
@@ -106,7 +67,7 @@ class ApiParameter(BaseModel):
     self.py_name = (
         self.py_name
         if self.py_name
-        else rename_python_keywords(to_snake_case(self.original_name))
+        else rename_python_keywords(_to_snake_case(self.original_name))
     )
     if isinstance(self.param_schema, str):
       self.param_schema = Schema.model_validate_json(self.param_schema)

src/google/adk/tools/openapi_tool/openapi_spec_parser/__init__.py

@@ -20,7 +20,6 @@ from .operation_parser import OperationParser
 from .rest_api_tool import AuthPreparationState
 from .rest_api_tool import RestApiTool
 from .rest_api_tool import snake_to_lower_camel
-from .rest_api_tool import to_gemini_schema
 from .tool_auth_handler import ToolAuthHandler
 
 __all__ = [
@@ -30,7 +29,6 @@ __all__ = [
     'OpenAPIToolset',
     'OperationParser',
     'RestApiTool',
-    'to_gemini_schema',
     'snake_to_lower_camel',
     'AuthPreparationState',
     'ToolAuthHandler',

src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_spec_parser.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import copy
 from typing import Any
 from typing import Dict
@@ -23,8 +25,8 @@ from pydantic import BaseModel
 
 from ....auth.auth_credential import AuthCredential
 from ....auth.auth_schemes import AuthScheme
+from ..._gemini_schema_util import _to_snake_case
 from ..common.common import ApiParameter
-from ..common.common import to_snake_case
 from .operation_parser import OperationParser
 
 
@@ -112,7 +114,7 @@ class OpenApiSpecParser:
         # If operation ID is missing, assign an operation id based on path
         # and method
         if "operationId" not in operation_dict:
-          temp_id = to_snake_case(f"{path}_{method}")
+          temp_id = _to_snake_case(f"{path}_{method}")
           operation_dict["operationId"] = temp_id
 
         url = OperationEndpoint(base_url=base_url, path=path, method=method)

src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 import inspect
 from textwrap import dedent
 from typing import Any
@@ -25,9 +27,9 @@ from fastapi.openapi.models import Operation
 from fastapi.openapi.models import Parameter
 from fastapi.openapi.models import Schema
 
+from ..._gemini_schema_util import _to_snake_case
 from ..common.common import ApiParameter
 from ..common.common import PydocHelper
-from ..common.common import to_snake_case
 
 
 class OperationParser:
@@ -189,7 +191,7 @@ class OperationParser:
     operation_id = self._operation.operationId
     if not operation_id:
       raise ValueError('Operation ID is missing')
-    return to_snake_case(operation_id)[:60]
+    return _to_snake_case(operation_id)[:60]
 
   def get_return_type_hint(self) -> str:
     """Returns the return type hint string (like 'str', 'int', etc.)."""

src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py

@@ -12,45 +12,36 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from __future__ import annotations
+
 from typing import Any
 from typing import Dict
 from typing import List
 from typing import Literal
 from typing import Optional
-from typing import Sequence
 from typing import Tuple
 from typing import Union
 
 from fastapi.openapi.models import Operation
 from google.genai.types import FunctionDeclaration
-from google.genai.types import Schema
 import requests
 from typing_extensions import override
 
 from ....auth.auth_credential import AuthCredential
 from ....auth.auth_schemes import AuthScheme
-from ....tools.base_tool import BaseTool
+from ..._gemini_schema_util import _to_gemini_schema
+from ..._gemini_schema_util import _to_snake_case
+from ...base_tool import BaseTool
 from ...tool_context import ToolContext
 from ..auth.auth_helpers import credential_to_param
 from ..auth.auth_helpers import dict_to_auth_scheme
 from ..auth.credential_exchangers.auto_auth_credential_exchanger import AutoAuthCredentialExchanger
 from ..common.common import ApiParameter
-from ..common.common import to_snake_case
 from .openapi_spec_parser import OperationEndpoint
 from .openapi_spec_parser import ParsedOperation
 from .operation_parser import OperationParser
 from .tool_auth_handler import ToolAuthHandler
 
-# Not supported by the Gemini API
-_OPENAPI_SCHEMA_IGNORE_FIELDS = (
-    "title",
-    "default",
-    "format",
-    "additional_properties",
-    "ref",
-    "def",
-)
-
 
 def snake_to_lower_camel(snake_case_string: str):
   """Converts a snake_case string to a lower_camel_case string.
@@ -70,117 +61,6 @@ def snake_to_lower_camel(snake_case_string: str):
   ])
 
 
-# TODO: Switch to Gemini `from_json_schema` util when it is released
-# in Gemini SDK.
-def normalize_json_schema_type(
-    json_schema_type: Optional[Union[str, Sequence[str]]],
-) -> tuple[Optional[str], bool]:
-  """Converts a JSON Schema Type into Gemini Schema type.
-
-  Adopted and modified from Gemini SDK. This gets the first available schema
-  type from JSON Schema, and use it to mark Gemini schema type. If JSON Schema
-  contains a list of types, the first non null type is used.
-
-  Remove this after switching to Gemini `from_json_schema`.
-  """
-  if json_schema_type is None:
-    return None, False
-  if isinstance(json_schema_type, str):
-    if json_schema_type == "null":
-      return None, True
-    return json_schema_type, False
-
-  non_null_types = []
-  nullable = False
-  # If json schema type is an array, pick the first non null type.
-  for type_value in json_schema_type:
-    if type_value == "null":
-      nullable = True
-    else:
-      non_null_types.append(type_value)
-  non_null_type = non_null_types[0] if non_null_types else None
-  return non_null_type, nullable
-
-
-# TODO: Switch to Gemini `from_json_schema` util when it is released
-# in Gemini SDK.
-def to_gemini_schema(openapi_schema: Optional[Dict[str, Any]] = None) -> Schema:
-  """Converts an OpenAPI schema dictionary to a Gemini Schema object.
-
-  Args:
-      openapi_schema: The OpenAPI schema dictionary.
-
-  Returns:
-      A Pydantic Schema object.  Returns None if input is None.
-      Raises TypeError if input is not a dict.
-  """
-  if openapi_schema is None:
-    return None
-
-  if not isinstance(openapi_schema, dict):
-    raise TypeError("openapi_schema must be a dictionary")
-
-  pydantic_schema_data = {}
-
-  # Adding this to force adding a type to an empty dict
-  # This avoid "... one_of or any_of must specify a type" error
-  if not openapi_schema.get("type"):
-    openapi_schema["type"] = "object"
-
-  for key, value in openapi_schema.items():
-    snake_case_key = to_snake_case(key)
-    # Check if the snake_case_key exists in the Schema model's fields.
-    if snake_case_key in Schema.model_fields:
-      if snake_case_key in _OPENAPI_SCHEMA_IGNORE_FIELDS:
-        # Ignore these fields as Gemini backend doesn't recognize them, and will
-        # throw exception if they appear in the schema.
-        # Format: properties[expiration].format: only 'enum' and 'date-time' are
-        # supported for STRING type
-        continue
-      elif snake_case_key == "type":
-        schema_type, nullable = normalize_json_schema_type(
-            openapi_schema.get("type", None)
-        )
-        # Adding this to force adding a type to an empty dict
-        # This avoid "... one_of or any_of must specify a type" error
-        pydantic_schema_data["type"] = schema_type if schema_type else "object"
-        pydantic_schema_data["type"] = pydantic_schema_data["type"].upper()
-        if nullable:
-          pydantic_schema_data["nullable"] = True
-      elif snake_case_key == "properties" and isinstance(value, dict):
-        pydantic_schema_data[snake_case_key] = {
-            k: to_gemini_schema(v) for k, v in value.items()
-        }
-      elif snake_case_key == "items" and isinstance(value, dict):
-        pydantic_schema_data[snake_case_key] = to_gemini_schema(value)
-      elif snake_case_key == "any_of" and isinstance(value, list):
-        pydantic_schema_data[snake_case_key] = [
-            to_gemini_schema(item) for item in value
-        ]
-      # Important:  Handle cases where the OpenAPI schema might contain lists
-      # or other structures that need to be recursively processed.
-      elif isinstance(value, list) and snake_case_key not in (
-          "enum",
-          "required",
-          "property_ordering",
-      ):
-        new_list = []
-        for item in value:
-          if isinstance(item, dict):
-            new_list.append(to_gemini_schema(item))
-          else:
-            new_list.append(item)
-        pydantic_schema_data[snake_case_key] = new_list
-      elif isinstance(value, dict) and snake_case_key not in ("properties"):
-        # Handle dictionary which is neither properties or items
-        pydantic_schema_data[snake_case_key] = to_gemini_schema(value)
-      else:
-        # Simple value assignment (int, str, bool, etc.)
-        pydantic_schema_data[snake_case_key] = value
-
-  return Schema(**pydantic_schema_data)
-
-
 AuthPreparationState = Literal["pending", "done"]
 
 
@@ -273,7 +153,7 @@ class RestApiTool(BaseTool):
         parsed.operation, parsed.parameters, parsed.return_value
     )
 
-    tool_name = to_snake_case(operation_parser.get_function_name())
+    tool_name = _to_snake_case(operation_parser.get_function_name())
     generated = cls(
         name=tool_name,
         description=parsed.operation.description
@@ -306,7 +186,7 @@ class RestApiTool(BaseTool):
   def _get_declaration(self) -> FunctionDeclaration:
     """Returns the function declaration in the Gemini Schema format."""
     schema_dict = self._operation_parser.get_json_schema()
-    parameters = to_gemini_schema(schema_dict)
+    parameters = _to_gemini_schema(schema_dict)
     function_decl = FunctionDeclaration(
         name=self.name, description=self.description, parameters=parameters
     )