gemini_schema.py 9.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198
  1. """Tool-schema preparation for Gemini's native API.
  2. Two wire shapes: ``parametersJsonSchema`` (plain JSON Schema, v1beta only) gets a light
  3. normalizer (``prepare_gemini_tool_parameters``); the legacy ``parameters`` field accepts
  4. only the OpenAPI ``Schema`` subset and keeps the lossy translator
  5. (``sanitize_gemini_tool_parameters``) for API versions without the JSON Schema field.
  6. """
  7. from __future__ import annotations
  8. import copy
  9. import logging
  10. import math
  11. from typing import Any, Dict, List, Optional
  12. from tools.schema_sanitizer import _normalize_type_array
  13. logger = logging.getLogger(__name__)
  14. # Gemini's ``FunctionDeclaration.parameters`` accepts only a subset of OpenAPI 3.0 /
  15. # JSON Schema (the ``Schema`` object); everything else is stripped.
  16. _GEMINI_SCHEMA_ALLOWED_KEYS = {
  17. "type", "format", "title", "description", "nullable", "enum", "maxItems", "minItems", "properties", "required",
  18. "minProperties", "maxProperties", "minLength", "maxLength", "pattern", "example", "anyOf", "propertyOrdering",
  19. "default", "items", "minimum", "maximum",
  20. }
  21. _GEMINI_STRUCTURAL_KEYS = {
  22. "array": {"items", "minItems", "maxItems"},
  23. "object": {"properties", "required", "minProperties", "maxProperties", "propertyOrdering"},
  24. }
  25. def _stringify_enum_value(item: Any) -> Any:
  26. """Gemini-safe string for a scalar enum entry, or None to drop it."""
  27. if isinstance(item, bool):
  28. return "true" if item else "false"
  29. if isinstance(item, (int, float)) and math.isfinite(item):
  30. return str(item)
  31. return item if isinstance(item, str) else None
  32. def _normalize_gemini_type_array(type_array: list, cleaned: dict[str, Any]) -> None:
  33. """Keep union alternatives and their branch-local structural constraints."""
  34. derived: dict[str, Any] = {}
  35. _normalize_type_array(type_array, derived)
  36. if "anyOf" in derived:
  37. constraints = {"anyOf": cleaned["anyOf"]} if "anyOf" in cleaned else {}
  38. # Gemini requires items/properties on the typed branch itself, not
  39. # its typeless parent. Keep required paired with those properties.
  40. structural = {key: cleaned.pop(key) for keys in _GEMINI_STRUCTURAL_KEYS.values()
  41. for key in keys if key in cleaned}
  42. cleaned["anyOf"] = [
  43. sanitize_gemini_schema({**branch, **constraints, **{
  44. key: value for key, value in structural.items()
  45. if key in _GEMINI_STRUCTURAL_KEYS.get(branch["type"], ())
  46. }}) for branch in derived["anyOf"]
  47. ]
  48. else:
  49. cleaned["type"] = derived["type"]
  50. if derived.get("nullable"):
  51. # Derived from "null" in the array. Set AFTER the loop so it beats an input
  52. # ``nullable: false`` regardless of which key the producer emitted first.
  53. cleaned["nullable"] = True
  54. def sanitize_gemini_schema(schema: Any) -> dict[str, Any]:
  55. """Gemini-compatible copy of a tool parameter schema: keeps only the documented subset
  56. (drops e.g. ``$schema`` / ``additionalProperties``) and recursively sanitizes nested
  57. ``properties`` / ``items`` / ``anyOf``."""
  58. if not isinstance(schema, dict):
  59. return {}
  60. cleaned: dict[str, Any] = {}
  61. for key, value in schema.items():
  62. if key not in _GEMINI_SCHEMA_ALLOWED_KEYS:
  63. continue
  64. if key == "properties":
  65. if isinstance(value, dict):
  66. cleaned[key] = {name: sanitize_gemini_schema(sub) for name, sub in value.items() if isinstance(name, str)}
  67. elif key == "items":
  68. cleaned[key] = sanitize_gemini_schema(value)
  69. elif key == "anyOf":
  70. if isinstance(value, list):
  71. cleaned[key] = [sanitize_gemini_schema(item) for item in value if isinstance(item, dict)]
  72. else:
  73. cleaned[key] = value
  74. type_array = cleaned.get("type")
  75. if isinstance(type_array, list):
  76. cleaned.pop("type")
  77. _normalize_gemini_type_array(type_array, cleaned)
  78. # Gemini requires every ``enum`` entry to be a string even for
  79. # integer/number/boolean types; the declared type stays intact and Gemini
  80. # still emits typed tool arguments at runtime. dict.fromkeys = ordered dedupe.
  81. enum_val = cleaned.get("enum")
  82. if isinstance(enum_val, list) and (
  83. isinstance(type_array, list) or cleaned.get("type") in {"integer", "number", "boolean"}
  84. ):
  85. if stringified := list(dict.fromkeys(v for v in map(_stringify_enum_value, enum_val) if v is not None)):
  86. cleaned["enum"] = stringified
  87. else:
  88. cleaned.pop("enum", None)
  89. # Gemini validates ``required`` strictly against the same node's ``properties`` (HTTP 400
  90. # "property is not defined") and one bad tool schema fails the ENTIRE request. MCP servers
  91. # routinely emit ``required`` without ``properties``, so keep only names that exist here;
  92. # the tool handler still validates required fields at execution time.
  93. required_val = cleaned.get("required")
  94. if isinstance(required_val, list):
  95. props_val = cleaned.get("properties")
  96. prop_names = set(props_val) if isinstance(props_val, dict) else set()
  97. valid_required = [name for name in required_val if isinstance(name, str) and name in prop_names]
  98. if not valid_required:
  99. cleaned.pop("required", None)
  100. elif len(valid_required) != len(required_val):
  101. cleaned["required"] = valid_required
  102. return cleaned
  103. def sanitize_gemini_tool_parameters(parameters: Any) -> dict[str, Any]:
  104. """Normalize tool parameters to a valid Gemini object schema."""
  105. return sanitize_gemini_schema(parameters) or {"type": "object", "properties": {}}
  106. # ── parametersJsonSchema (full JSON Schema) ─────────────────────────────────
  107. #
  108. # The legacy translator is lossy: anyOf unions without an outer type, bare arrays,
  109. # $ref/$defs and additionalProperties had to be stripped or repaired, and one
  110. # unrepresentable construct 400s the ENTIRE request. Through parametersJsonSchema the
  111. # schema goes as-is; only same-document $refs are inlined (MCP pydantic / zod emit
  112. # them and Google rejects reference indirection) and root ``$schema`` is dropped.
  113. _EMPTY_OBJECT_SCHEMA: dict[str, Any] = {"type": "object", "properties": {}}
  114. # Real tool schemas hold a handful of refs; the cap stops circular pydantic models
  115. # from expanding forever.
  116. _MAX_REF_EXPANSIONS = 256
  117. def _resolve_local_ref(root: dict[str, Any], ref: str) -> Optional[dict[str, Any]]:
  118. """Resolve a same-document JSON pointer (``#/$defs/Foo``) against *root*."""
  119. if not isinstance(ref, str) or not ref.startswith("#/"):
  120. return None
  121. node: Any = root
  122. for raw_part in ref[2:].split("/"):
  123. part = raw_part.replace("~1", "/").replace("~0", "~")
  124. if not isinstance(node, dict) or part not in node:
  125. return None
  126. node = node[part]
  127. return node if isinstance(node, dict) else None
  128. def _inline_refs(node: Any, root: dict[str, Any], budget: list[int], stack: tuple = ()) -> Any:
  129. """Recursively inline same-document ``$ref`` nodes; ``ValueError`` on an unresolvable
  130. or circular reference or an exhausted budget (the caller then keeps the original)."""
  131. if isinstance(node, list):
  132. return [_inline_refs(item, root, budget, stack) for item in node]
  133. if not isinstance(node, dict):
  134. return node
  135. ref = node.get("$ref")
  136. if not isinstance(ref, str):
  137. return {key: _inline_refs(value, root, budget, stack) for key, value in node.items()}
  138. if ref in stack:
  139. raise ValueError(f"circular $ref {ref!r}")
  140. budget[0] -= 1
  141. if budget[0] < 0:
  142. raise ValueError("$ref expansion budget exhausted")
  143. target = _resolve_local_ref(root, ref)
  144. if target is None:
  145. raise ValueError(f"unresolvable $ref {ref!r}")
  146. inlined = _inline_refs(target, root, budget, stack + (ref,))
  147. # JSON Schema: siblings of $ref (description, default, ...) apply alongside the
  148. # referenced schema and win over it.
  149. siblings = {k: v for k, v in node.items() if k != "$ref"}
  150. return {**inlined, **_inline_refs(siblings, root, budget, stack)} if siblings else inlined
  151. def prepare_gemini_tool_parameters(parameters: Any) -> dict[str, Any]:
  152. """Full JSON Schema for ``parametersJsonSchema``: deep-copied, root ``$schema`` dropped,
  153. same-document ``$ref`` inlined, object root guaranteed. A schema whose references
  154. cannot all be resolved is sent untouched so the provider names the real problem."""
  155. if not isinstance(parameters, dict) or not parameters:
  156. return dict(_EMPTY_OBJECT_SCHEMA)
  157. schema = copy.deepcopy(parameters)
  158. schema.pop("$schema", None)
  159. try:
  160. schema = _inline_refs(schema, schema, [_MAX_REF_EXPANSIONS])
  161. except ValueError as exc:
  162. logger.debug("Gemini tool schema kept as-is ($ref inlining skipped): %s", exc)
  163. return schema
  164. schema.pop("$defs", None)
  165. schema.pop("definitions", None)
  166. if not schema:
  167. return dict(_EMPTY_OBJECT_SCHEMA)
  168. if schema.get("type") == "object" and "properties" not in schema:
  169. schema["properties"] = {}
  170. return schema