gemini_native_adapter.py 58 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045
  1. """OpenAI-compatible facade over Google AI Studio's native Gemini API: the ``gemini``
  2. provider keeps ``api_mode='chat_completions'`` so the agent loop stays OpenAI-shaped,
  3. and this shim converts ``messages[]``/``tools[]`` into ``models/{model}:generateContent``
  4. payloads and responses back. Google's OpenAI-compat endpoint is brittle for the
  5. multi-turn tool loop (auth churn, tool-call replay, thought signatures); native is canonical."""
  6. from __future__ import annotations
  7. import asyncio
  8. import base64
  9. import contextlib
  10. import json
  11. import logging
  12. import re
  13. import time
  14. import uuid
  15. from types import SimpleNamespace
  16. from typing import Any, Dict, Iterator, List, Optional
  17. import httpx
  18. from agent.bounded_response import read_streaming_error_body
  19. from agent.gemini_long_decode import continuation_token, long_decode_hops, merge_hop_responses, merge_hop_usage, split_stream_continuation
  20. from agent.retry_utils import parse_retry_after_seconds
  21. from agent.gemini_schema import prepare_gemini_tool_parameters, sanitize_gemini_tool_parameters
  22. logger = logging.getLogger(__name__)
  23. from hermes_cli.version_info import hermes_user_agent
  24. def _api_client() -> str:
  25. return hermes_user_agent("hermes-agent") # client context per Gemini's partner-integration guidance
  26. DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
  27. # A Vertex AI express-mode base, when the user configures one explicitly: aiplatform serves the
  28. # same native API under ``{version}/publishers/google/models/…``; the base carries that prefix so
  29. # every ``{base}/models/{model}:…`` builder (chat, tier probe, TTS) needs no path branching.
  30. # The key itself never decides routing — Google now issues ``AQ.…`` keys for BOTH Google AI Studio
  31. # and Vertex express mode (#115306), so an express key reaches aiplatform only via this base config.
  32. VERTEX_EXPRESS_BASE_URL = "https://aiplatform.googleapis.com/v1beta1/publishers/google"
  33. # Published max output-token ceiling shared by every current Gemini text model; used
  34. # for max_tokens=None because the native API's low internal default truncates output.
  35. GEMINI_DEFAULT_MAX_OUTPUT_TOKENS = 65535
  36. _FREE_TIER_GUIDANCE = (
  37. "\n\nYour Google API key is on the free tier (a few hundred requests/day for Gemini Flash models). "
  38. "Hermes typically makes 3-10 API calls per user turn, so the free tier is exhausted in a handful of "
  39. "messages and cannot sustain an agent session. Enable billing on your Google Cloud project and "
  40. "regenerate the key in a billing-enabled project: https://aistudio.google.com/apikey"
  41. )
  42. _STANDARD_KEY_GUIDANCE = (
  43. "\n\nGoogle Gemini rejected this API key's type — you do NOT need OAuth. Google began rejecting legacy "
  44. "'Standard' Google Cloud keys for the Gemini API on June 19, 2026, and all Standard keys stop working in "
  45. "September 2026. Open https://aistudio.google.com/api-keys, check the key's type and status, and create a "
  46. "replacement Gemini API key (or, as a temporary bridge, restrict the Standard key to "
  47. "generativelanguage.googleapis.com). Then update GEMINI_API_KEY / GOOGLE_API_KEY in ~/.hermes/.env, "
  48. "delete any leftover Windows/system copy of those variables, and restart. A stale shell key can hide "
  49. "the .env value. Details: https://ai.google.dev/gemini-api/docs/api-key"
  50. )
  51. # Google issues ``AQ.…`` keys for both AI Studio and Vertex express mode; each surface only accepts
  52. # its own keys, so a 403 usually means the key/host pairing is crossed rather than a bad key (#115306).
  53. _EXPRESS_KEY_ON_STUDIO_GUIDANCE = (
  54. "\n\nGoogle issues 'AQ.' keys for both Google AI Studio and Vertex AI express mode, and each surface "
  55. "only accepts its own keys: a Vertex express key always gets 403 PERMISSION_DENIED on "
  56. "generativelanguage.googleapis.com. If this key came from Google Cloud / Vertex (express mode), point "
  57. "the provider at the express surface, e.g. set base_url / GEMINI_BASE_URL to "
  58. "https://aiplatform.googleapis.com/v1beta1."
  59. )
  60. _STUDIO_KEY_ON_EXPRESS_GUIDANCE = (
  61. "\n\nIf this 'AQ.' key came from Google AI Studio (https://aistudio.google.com/apikey), it only works "
  62. "on the default generativelanguage.googleapis.com host — remove the explicit aiplatform base_url so "
  63. "the default surface is used."
  64. )
  65. # Stands in for a model turn that never arrived (stream failure / interrupt / quota
  66. # fallback) when a human user text turn directly follows a tool-result turn, keeping
  67. # the request alternation-valid while the user's message stays a turn of its own
  68. # (mirrors gemini-cli's placeholder repair).
  69. _INTERRUPTED_RESPONSE_PLACEHOLDER = "[The previous response was interrupted before it completed.]"
  70. # Cross-provider tool_calls (e.g. fallback from xAI/Anthropic) carry no Gemini thoughtSignature;
  71. # without this sentinel Gemini 3 thinking models reject replayed history with 400 INVALID_ARGUMENT.
  72. _SKIP_SIGNATURE = "skip_thought_signature_validator"
  73. _END = object() # stream-exhausted marker for _advance_stream_iterator
  74. _MAX_TOKEN_SENDS = 3 # requests one long-decode token may ride, so a network that keeps dropping ends in an error
  75. _TOOL_CHOICE_MODES = {"auto": "AUTO", "required": "ANY", "none": "NONE"}
  76. _FINISH_REASON_MAP = {
  77. "STOP": "stop", "MAX_TOKENS": "length", "SAFETY": "content_filter", "RECITATION": "content_filter", "OTHER": "stop",
  78. "CONTINUATION": "length", # only reachable without a continuationToken: the output was cut short
  79. }
  80. _HTTP_ERROR_CODES = {401: "gemini_unauthorized", 429: "gemini_rate_limited", 404: "gemini_model_not_found"}
  81. _MISSING_KEY_ERROR = (
  82. "Gemini native client requires an API key, but none was provided. Set GOOGLE_API_KEY or GEMINI_API_KEY in your "
  83. "environment / ~/.hermes/.env (get one at https://aistudio.google.com/app/apikey), or run `hermes setup` to "
  84. "configure the Google provider."
  85. )
  86. def bare_gemini_model_id(model: str) -> str:
  87. """Strip Gemini's own provider prefix from an aggregator-style model id."""
  88. name = (model or "").strip()
  89. for prefix in ("google/", "gemini/"):
  90. if name.lower().startswith(prefix):
  91. return name[len(prefix):].strip() or name
  92. return name
  93. def gemini_requires_tool_call_ids(model: str) -> bool:
  94. """Gemini 3+ needs explicit functionCall/functionResponse ids so replayed parallel tool calls
  95. pair with their responses; 2.x rejects the field.
  96. Gemini 3+ models require explicit tool call IDs in replayed history — without them, multi-tool turns can
  97. be rejected or mismatched. Older Gemini models (2.x) reject unexpected ``id`` fields, so this is gated
  98. on the major version. Mirrors earendil-works/pi#7494 (their fix for the same class of bug in the
  99. google-shared converter).
  100. """
  101. return _gemini_version(model) >= (3, 0)
  102. def _gemini_version(model: str) -> tuple[int, int]:
  103. """(major, minor) of a Gemini model id: ``gemini-4-argon`` -> (4, 0), ``google/gemini-3.8-flash`` ->
  104. (3, 8); (0, 0) for non-Gemini and unversioned ids (``gemini-flash-latest``, ``gemini-exp-1206``)."""
  105. match = re.match(r"gemini-(\d+)(?:\.(\d+))?", bare_gemini_model_id(model).lower())
  106. return (int(match.group(1)), int(match.group(2) or 0)) if match else (0, 0)
  107. def gemini_uses_thinking_level(model: str) -> bool:
  108. """Gemini 3 and every later generation steer thinking with the ``thinkingLevel`` enum (``thinkingBudget``
  109. is deprecated there), as do the ``gemini-*-latest`` aliases, which Google hot-swaps to the newest
  110. release of each variant. A version-number gate, not a ``gemini-3`` prefix, so a new generation
  111. (``gemini-4-argon``) isn't silently treated as legacy."""
  112. bare = bare_gemini_model_id(model).lower()
  113. return (bare.startswith("gemini-") and bare.endswith("-latest")) or _gemini_version(bare) >= (3, 0)
  114. def gemini_sampling_deprecated(model: str) -> bool:
  115. """Gemini 3.6+ (Gemini 4 Argon included) ignores ``temperature``/``top_p``/``top_k`` and Google
  116. slated them for removal; older families (2.x, 3.0-3.5) keep them."""
  117. return _gemini_version(model) >= (3, 6)
  118. _API_VERSION_SEGMENT = re.compile(r"^v\d+(?:alpha|beta)?\d*$", re.IGNORECASE)
  119. def is_vertex_express_base_url(base_url: str) -> bool:
  120. """An aiplatform host speaking the native API with an API key: the bare express surface, or its
  121. ``…/projects/{p}/locations/{l}`` form, which reaches models served only in ``global`` (Gemini 4).
  122. The OAuth Vertex provider's ``…/endpoints/openapi`` base is OpenAI-compatible and must stay off
  123. the native adapter."""
  124. normalized = str(base_url or "").strip().lower()
  125. return "aiplatform.googleapis.com" in normalized and "/endpoints/" not in normalized
  126. def normalize_gemini_base_url(base_url: Optional[str]) -> str:
  127. """Gemini native base URL with the API version segment guaranteed. Google's own client treats the
  128. base as a host root and appends the version itself, so users configure ``GEMINI_BASE_URL`` (or a
  129. proxy root like ``http://localhost:4000/gemini``) that way; our request builders expect
  130. ``{base}/models/{model}:generateContent`` — without ``/v1beta`` that is a guaranteed 404. Trailing
  131. slashes and an ``/openai`` suffix are stripped; an existing version segment (``v1``, ``v1beta``,
  132. ``v1alpha``, ...) is kept; empty input returns ``DEFAULT_GEMINI_BASE_URL``. Only the LAST path
  133. segment is inspected, so ``.../v1beta/extra`` still gets ``/v1beta`` appended; this does not
  134. decide routing (see ``is_native_gemini_base_url``).
  135. A Vertex express base (``aiplatform.googleapis.com``, ``…/v1beta1`` or the full
  136. ``…/v1beta1/publishers/google``) is completed to the ``publishers/google`` form. The key never
  137. decides routing: Google issues ``AQ.…`` keys for both AI Studio and Vertex express mode
  138. (#115306), so an express key reaches aiplatform only through this explicit base configuration."""
  139. trimmed = str(base_url or "").strip().rstrip("/")
  140. trimmed = re.sub(r"/openai\Z", "", trimmed, flags=re.IGNORECASE).rstrip("/")
  141. if not trimmed:
  142. trimmed = DEFAULT_GEMINI_BASE_URL
  143. if is_vertex_express_base_url(trimmed):
  144. if trimmed.lower().endswith("/publishers/google"):
  145. return trimmed
  146. if "/projects/" not in trimmed.lower() and not _API_VERSION_SEGMENT.match(trimmed.rsplit("/", 1)[-1]):
  147. trimmed = f"{trimmed}/v1beta1"
  148. return f"{trimmed}/publishers/google"
  149. if _API_VERSION_SEGMENT.match(trimmed.rsplit("/", 1)[-1]):
  150. return trimmed
  151. return f"{trimmed}/v1beta"
  152. def is_native_gemini_base_url(base_url: str) -> bool:
  153. """True when the endpoint speaks Gemini's native REST API (not ``/openai``)."""
  154. normalized = str(base_url or "").strip().rstrip("/").lower()
  155. if normalized.endswith("/openai"):
  156. return False
  157. return "generativelanguage.googleapis.com" in normalized or is_vertex_express_base_url(normalized)
  158. def gemini_accepts_parameters_json_schema(base_url: str) -> bool:
  159. """``FunctionDeclaration.parametersJsonSchema`` exists only in the ``v1beta`` surface of
  160. generativelanguage (absent from ``v1`` / ``v1alpha`` content.proto); other versions and
  161. unknown proxies get the legacy ``parameters`` subset."""
  162. return str(base_url or "").strip().rstrip("/").lower().endswith("/v1beta")
  163. def probe_gemini_tier(
  164. api_key: str, base_url: str = DEFAULT_GEMINI_BASE_URL, *, model: str = "gemini-3.7-flash", timeout: float = 10.0
  165. ) -> str:
  166. """Probe a Google AI Studio key → ``"free"`` | ``"paid"`` | ``"unknown"`` (probe failed; callers proceed without blocking)."""
  167. key = (api_key or "").strip()
  168. if not key:
  169. return "unknown"
  170. base = normalize_gemini_base_url(base_url)
  171. payload = {"contents": [{"role": "user", "parts": [{"text": "hi"}]}], "generationConfig": {"maxOutputTokens": 1}}
  172. headers = {"Content-Type": "application/json", "X-Goog-Api-Client": _api_client()}
  173. try:
  174. with httpx.Client(timeout=timeout) as client:
  175. resp = client.post(f"{base}/models/{model}:generateContent", params={"key": key}, json=payload, headers=headers)
  176. except Exception as exc:
  177. logger.debug("probe_gemini_tier: network error: %s", exc)
  178. return "unknown"
  179. rpd_header = {k.lower(): v for k, v in resp.headers.items()}.get("x-ratelimit-limit-requests-per-day")
  180. try:
  181. if rpd_header: # free-tier daily caps top out at 1000 (flash-lite); Tier 1 starts ~1500+
  182. return "free" if int(rpd_header) <= 1000 else "paid"
  183. except (TypeError, ValueError):
  184. pass
  185. if resp.status_code == 429:
  186. return "free" if "free_tier" in _response_text(resp).lower() else "paid"
  187. return "paid" if 200 <= resp.status_code < 300 else "unknown"
  188. def _response_text(response: Any) -> str:
  189. try:
  190. return response.text or ""
  191. except Exception:
  192. return ""
  193. def is_free_tier_quota_error(error_message: str) -> bool:
  194. """True when a Gemini 429 message indicates free-tier exhaustion."""
  195. return bool(error_message) and "free_tier" in error_message.lower()
  196. def wrong_gemini_surface_guidance(base_url: str, api_key: str, err_status: str) -> str:
  197. """Guidance text for the 403 PERMISSION_DENIED key/host mismatches Google's AQ. rollout created.
  198. Google issues ``AQ.…`` keys for both AI Studio and Vertex express mode, so neither the key prefix
  199. nor the host alone proves the pairing; on a PERMISSION_DENIED, point the user at the surface their
  200. key likely belongs to: an AQ. key rejected by the Studio host may be an express key (the explicit
  201. aiplatform base_url is that key's only route there), and any key rejected by an explicitly
  202. configured aiplatform base may be an AI Studio key (#115306). Empty string when the shape matches
  203. neither."""
  204. if (err_status or "").strip().upper() != "PERMISSION_DENIED":
  205. return ""
  206. normalized = str(base_url or "").strip().lower()
  207. if is_vertex_express_base_url(normalized):
  208. return _STUDIO_KEY_ON_EXPRESS_GUIDANCE
  209. if "generativelanguage.googleapis.com" in normalized and str(api_key or "").strip().upper().startswith("AQ."):
  210. return _EXPRESS_KEY_ON_STUDIO_GUIDANCE
  211. return ""
  212. def is_standard_key_auth_error(
  213. status: int, error_message: str, reason: str = "", *, api_key: str = "",
  214. ) -> bool:
  215. """True when Google rejected a legacy "Standard" (AIza) Cloud key.
  216. Original shape (June 2026): 401 + ``ACCESS_TOKEN_TYPE_UNSUPPORTED`` / "expected OAuth 2
  217. access token". After the September 2026 cutoff the same leftover AIza key often comes
  218. back as 400 ``API_KEY_INVALID`` ("API key not valid") — attach migration guidance on
  219. that 400 only when the presented key is still AIza-shaped, so a mistyped Auth (``AQ.``)
  220. key keeps the raw invalid-key message.
  221. """
  222. msg = (error_message or "").lower()
  223. if status == 401 and (reason == "ACCESS_TOKEN_TYPE_UNSUPPORTED" or "expected oauth 2 access token" in msg):
  224. return True
  225. if (
  226. status == 400
  227. and (api_key or "").startswith("AIza")
  228. and (reason == "API_KEY_INVALID" or "api key not valid" in msg)
  229. ):
  230. return True
  231. return False
  232. class GeminiAPIError(Exception):
  233. """Error shape compatible with Hermes retry/error classification."""
  234. def __init__(self, message: str, *, code: str = "gemini_api_error", status_code: Optional[int] = None,
  235. response: Optional[httpx.Response] = None, retry_after: Optional[float] = None, details: Optional[dict[str, Any]] = None):
  236. super().__init__(message)
  237. self.code, self.status_code, self.response = code, status_code, response
  238. self.retry_after, self.details = retry_after, details or {}
  239. # ── OpenAI → Gemini request translation ──────────────────────────────────────
  240. def _text_of(item: Any) -> Optional[str]:
  241. """Text of an OpenAI content item (plain str or ``{"type": "text"}`` dict), else None."""
  242. if isinstance(item, dict) and item.get("type") == "text" and isinstance(item.get("text"), str):
  243. return item["text"]
  244. return item if isinstance(item, str) else None
  245. def _coerce_content_to_text(content: Any) -> str:
  246. if isinstance(content, list):
  247. return "\n".join(t for t in map(_text_of, content) if t is not None)
  248. return "" if content is None else str(content)
  249. def _inline_data_part(item: dict[str, Any]) -> Optional[dict[str, Any]]:
  250. """``inlineData`` part for an ``image_url`` item carrying a ``data:`` URL; None otherwise."""
  251. url = (item.get("image_url") or {}).get("url") or ""
  252. if item.get("type") != "image_url" or not isinstance(url, str) or not url.startswith("data:"):
  253. return None
  254. try:
  255. header, encoded = url.split(",", 1)
  256. data = base64.b64encode(base64.b64decode(encoded)).decode("ascii")
  257. return {"inlineData": {"mimeType": header.split(":", 1)[1].split(";", 1)[0], "data": data}}
  258. except Exception:
  259. return None
  260. def _multimodal_part(item: Any) -> Optional[dict[str, Any]]:
  261. text = _text_of(item)
  262. if text or isinstance(item, str):
  263. return {"text": text}
  264. return _inline_data_part(item) if isinstance(item, dict) else None
  265. def _extract_multimodal_parts(content: Any) -> list[dict[str, Any]]:
  266. if isinstance(content, list):
  267. return [p for p in map(_multimodal_part, content) if p]
  268. text = _coerce_content_to_text(content)
  269. return [{"text": text}] if text else []
  270. def _tool_call_extra_signature(tool_call: dict[str, Any]) -> Optional[str]:
  271. """Replayed Gemini thoughtSignature from ``extra_content`` (``google.thought_signature`` or flat)."""
  272. extra = tool_call.get("extra_content") or {}
  273. sig = (extra.get("google") or extra.get("thought_signature")) if isinstance(extra, dict) else None
  274. if isinstance(sig, dict):
  275. sig = sig.get("thought_signature") or sig.get("thoughtSignature")
  276. return sig if isinstance(sig, str) and sig else None
  277. def _tool_call_id(tool_call: dict[str, Any]) -> str:
  278. return str(tool_call.get("id") or tool_call.get("call_id") or "")
  279. def _translate_tool_call_to_gemini(tool_call: dict[str, Any], include_ids: bool = False) -> dict[str, Any]:
  280. fn = tool_call.get("function") or {}
  281. args_raw = fn.get("arguments", "")
  282. try:
  283. args = json.loads(args_raw) if isinstance(args_raw, str) and args_raw else {}
  284. except json.JSONDecodeError:
  285. args = {"_raw": args_raw}
  286. call: dict[str, Any] = {"name": str(fn.get("name") or ""), "args": args if isinstance(args, dict) else {"_value": args}}
  287. if include_ids and (call_id := _tool_call_id(tool_call)):
  288. call["id"] = call_id
  289. return {"functionCall": call, "thoughtSignature": _tool_call_extra_signature(tool_call) or _SKIP_SIGNATURE}
  290. def _looks_like_json_schema(node: Any) -> bool:
  291. """True if a parsed value contains a JSON-Schema ``$ref`` pointer (``#/...``): Gemini 3 resolves
  292. ``$ref``/``$defs`` inside functionResponse.response and rejects unknown pointers with HTTP 400, so a
  293. tool result that is itself a JSON Schema (e.g. ``tool_describe`` output) is forwarded as opaque text.
  294. False positives only lose the structured shape, never the content."""
  295. if isinstance(node, dict):
  296. return any((k == "$ref" and isinstance(v, str) and v.startswith("#/")) or _looks_like_json_schema(v) for k, v in node.items())
  297. return isinstance(node, list) and any(_looks_like_json_schema(item) for item in node)
  298. def _translate_tool_result_to_gemini(
  299. message: dict[str, Any], tool_name_by_call_id: Optional[dict[str, str]] = None, include_ids: bool = False, *, is_gemini3: bool = False,
  300. ) -> dict[str, Any]:
  301. tool_call_id = str(message.get("tool_call_id") or "")
  302. # functionResponse.name must echo the matching functionCall.name, so the call-id
  303. # mapping beats the result's own name (may be an unwrapped MCP name via `tool_call`).
  304. name = str((tool_name_by_call_id or {}).get(tool_call_id) or message.get("name") or tool_call_id or "tool")
  305. raw_content = message.get("content")
  306. content = _coerce_content_to_text(raw_content)
  307. try:
  308. parsed = json.loads(content) if content.strip().startswith(("{", "[")) else None
  309. except json.JSONDecodeError:
  310. parsed = None
  311. # Gemini 3 resolves JSON-Schema ``$ref`` pointers inside a functionResponse.response payload and rejects
  312. # unknown references with HTTP 400 INVALID_ARGUMENT ("referenced name '#/$defs/...' does not match a
  313. # display_name"; see vercel/ai#14369). A tool result that is itself a JSON Schema (e.g. tool_describe
  314. # output for an MCP tool) must therefore be forwarded as opaque text, not as a structured response.
  315. structured = isinstance(parsed, dict) and not _looks_like_json_schema(parsed)
  316. function_response: dict[str, Any] = {"name": name, "response": parsed if structured else {"output": content}}
  317. if include_ids and tool_call_id:
  318. function_response["id"] = tool_call_id
  319. # Gemini 3.x accepts images inside functionResponse.parts; 2.x rejects the field.
  320. if image_parts := [p for p in _extract_multimodal_parts(raw_content) if "inlineData" in p] if is_gemini3 else []:
  321. function_response["parts"] = image_parts
  322. return {"functionResponse": function_response}
  323. def _has_function_response(content: dict[str, Any]) -> bool:
  324. return any(isinstance(part, dict) and "functionResponse" in part for part in content.get("parts", []))
  325. def _merge_alternating(contents: list[dict[str, Any]]) -> list[dict[str, Any]]:
  326. """Alternation contract for generateContent: 1) adjacent same-role contents merge (else HTTP 400
  327. "multiturn requests [must] alternate"); 2) EXCEPT never fuse a human user text turn into a preceding
  328. user content that only carries functionResponse parts (or vice versa) — Gemini 3 accepts the fold but
  329. reads the text as a continuation of the tool result and returns an empty candidate (parallel
  330. functionResponse + functionResponse still merge); 3) the split pair stays API-valid via an interposed
  331. placeholder model turn."""
  332. merged: list[dict[str, Any]] = []
  333. # Compatibility contract for native Gemini generateContent: 1) Same-role adjacent contents still merge
  334. # in general (strict user/model alternation for ordinary text turns and parallel tool-result grouping;
  335. # consecutive same-role contents are rejected with HTTP 400 "Please ensure that multiturn requests
  336. # alternate between user and model"). 2) Exception: do NOT fuse a human user text turn into a preceding
  337. # user content that only carries functionResponse parts (or vice versa). Gemini 3 accepts that fold with
  338. # HTTP 200 but then reads the trailing text as a continuation of the tool result — it returns an empty
  339. # candidate or "finishes the user's sentence" instead of answering (same defect gemini-cli fixed in
  340. # google-gemini/gemini-cli#28700). 3) Because rule 1's HTTP 400 makes two consecutive user contents
  341. # unsafe to emit (#55125 — the reason this merge exists), the split pair is kept API-valid by
  342. # interposing a placeholder model turn between the functionResponse content and the human text content,
  343. # mirroring gemini-cli's INTERRUPTED_RESPONSE_PLACEHOLDER repair.
  344. for content in contents:
  345. prev = merged[-1] if merged else None
  346. same_role = prev is not None and prev["role"] == content["role"]
  347. if same_role and content["role"] == "user" and _has_function_response(prev) != _has_function_response(content):
  348. same_role = False
  349. merged.append({"role": "model", "parts": [{"text": _INTERRUPTED_RESPONSE_PLACEHOLDER}]})
  350. if same_role:
  351. merged[-1]["parts"].extend(content["parts"])
  352. else:
  353. merged.append(content)
  354. return merged
  355. def _build_gemini_contents(
  356. messages: list[dict[str, Any]], include_tool_call_ids: bool = False, *, is_gemini3: bool = False
  357. ) -> tuple[list[dict[str, Any]], Optional[dict[str, Any]]]:
  358. system_text_parts: list[str] = []
  359. contents: list[dict[str, Any]] = []
  360. tool_name_by_call_id: dict[str, str] = {}
  361. for msg in messages:
  362. if not isinstance(msg, dict):
  363. continue
  364. role = str(msg.get("role") or "user")
  365. if role == "system":
  366. system_text_parts.append(_coerce_content_to_text(msg.get("content")))
  367. continue
  368. if role in {"tool", "function"}:
  369. part = _translate_tool_result_to_gemini(msg, tool_name_by_call_id, include_tool_call_ids, is_gemini3=is_gemini3)
  370. contents.append({"role": "user", "parts": [part]})
  371. continue
  372. parts = _extract_multimodal_parts(msg.get("content"))
  373. tool_calls = msg.get("tool_calls") or []
  374. for tool_call in (tc for tc in tool_calls if isinstance(tc, dict)) if isinstance(tool_calls, list) else ():
  375. tool_name = str((tool_call.get("function") or {}).get("name") or "")
  376. if (call_id := _tool_call_id(tool_call)) and tool_name:
  377. tool_name_by_call_id[call_id] = tool_name
  378. parts.append(_translate_tool_call_to_gemini(tool_call, include_ids=include_tool_call_ids))
  379. # Text-turn signature goes back on the last part, where it was received (a functionCall part
  380. # keeps its own signature).
  381. if role == "assistant" and parts and "functionCall" not in parts[-1] and (
  382. sig := _tool_call_extra_signature(msg)):
  383. parts[-1] = {**parts[-1], "thoughtSignature": sig}
  384. if parts:
  385. contents.append({"role": "model" if role == "assistant" else "user", "parts": parts})
  386. joined_system = "\n".join(part for part in system_text_parts if part).strip()
  387. return _merge_alternating(contents), ({"role": "system", "parts": [{"text": joined_system}]} if joined_system else None)
  388. def _function_declaration(tool: Any, *, json_schema: bool = False) -> Optional[dict[str, Any]]:
  389. fn = (tool.get("function") or {}) if isinstance(tool, dict) else None
  390. if not isinstance(fn, dict) or not (isinstance(fn.get("name"), str) and fn["name"]):
  391. return None
  392. decl: dict[str, Any] = {"name": fn["name"]}
  393. if isinstance(fn.get("description"), str) and fn["description"]:
  394. decl["description"] = fn["description"]
  395. if isinstance(fn.get("parameters"), dict):
  396. # Full JSON Schema where the API version has the field (unions, bare arrays,
  397. # $ref survive); the lossy OpenAPI subset elsewhere. Mutually exclusive on the wire.
  398. if json_schema:
  399. decl["parametersJsonSchema"] = prepare_gemini_tool_parameters(fn["parameters"])
  400. else:
  401. decl["parameters"] = sanitize_gemini_tool_parameters(fn["parameters"])
  402. return decl
  403. def _translate_tools_to_gemini(tools: Any, *, json_schema: bool = False) -> list[dict[str, Any]]:
  404. declarations = [d for d in (_function_declaration(t, json_schema=json_schema)
  405. for t in (tools if isinstance(tools, list) else [])) if d]
  406. return [{"functionDeclarations": declarations}] if declarations else []
  407. def _translate_tool_choice_to_gemini(tool_choice: Any) -> Optional[dict[str, Any]]:
  408. if isinstance(tool_choice, str) and tool_choice in _TOOL_CHOICE_MODES:
  409. return {"functionCallingConfig": {"mode": _TOOL_CHOICE_MODES[tool_choice]}}
  410. name = (tool_choice.get("function") or {}).get("name") if isinstance(tool_choice, dict) else None
  411. return {"functionCallingConfig": {"mode": "ANY", "allowedFunctionNames": [name]}} if isinstance(name, str) and name else None
  412. # (camelCase key, snake_case alias, accepted types, normalizer)
  413. _THINKING_KEYS = (
  414. ("thinkingBudget", "thinking_budget", (int, float), int),
  415. ("includeThoughts", "include_thoughts", bool, lambda v: v),
  416. ("thinkingLevel", "thinking_level", str, lambda v: v.strip().lower()),
  417. )
  418. def _normalize_thinking_config(config: Any) -> Optional[dict[str, Any]]:
  419. if not isinstance(config, dict):
  420. return None
  421. values = {key: config.get(key, config.get(alias)) for key, alias, _, _ in _THINKING_KEYS}
  422. normalized = {key: norm(values[key]) for key, _, types, norm in _THINKING_KEYS
  423. if isinstance(values[key], types) and (values[key].strip() if isinstance(values[key], str) else True)}
  424. return normalized or None
  425. def _thinking_requests_output_headroom(thinking_config: Any) -> bool:
  426. """True when Gemini will spend output tokens on thinking: thought tokens bill against ``maxOutputTokens``,
  427. so a global 4096/16384 cap can be consumed entirely by high thinking (``finishReason=MAX_TOKENS``, no answer)."""
  428. normalized = _normalize_thinking_config(thinking_config) or {}
  429. if normalized.get("includeThoughts") is False:
  430. # Hidden thoughts = reasoning disabled/minimised: never ask for headroom, or a small
  431. # caller budget (title generation's 64 tokens) balloons to the model ceiling. Gemini 3
  432. # still carries a "low" thinkingLevel here (no off-switch), which must not re-enable the
  433. # bump. (#91927)
  434. return False
  435. budget = normalized.get("thinkingBudget")
  436. has_level = "thinkingLevel" in normalized
  437. return bool(normalized) and not (isinstance(budget, int) and budget <= 0 and not has_level)
  438. def _effective_gemini_max_output_tokens(max_tokens: Optional[int], thinking_config: Any) -> int:
  439. """Native ``maxOutputTokens``: an omitted/invalid cap becomes the published ceiling (Gemini
  440. truncates on its low internal default); an explicit cap is raised to the ceiling when
  441. thinking is enabled so thoughts don't starve the answer."""
  442. try:
  443. requested = int(max_tokens)
  444. except (TypeError, ValueError):
  445. requested = 0
  446. if requested <= 0 or _thinking_requests_output_headroom(thinking_config):
  447. return max(requested, GEMINI_DEFAULT_MAX_OUTPUT_TOKENS)
  448. return requested
  449. def _translate_response_format(response_format: Any, *, json_schema: bool = False) -> dict[str, Any]:
  450. """OpenAI ``response_format`` → Gemini ``generationConfig`` JSON-output keys.
  451. Full-JSON-Schema ``responseJsonSchema`` exists only on the generativelanguage ``v1beta``
  452. surface (same gate as ``parametersJsonSchema``); ``v1`` / ``v1alpha``, Vertex express
  453. ``v1beta1`` and unknown proxies take the OpenAPI-subset ``responseSchema`` path.
  454. """
  455. if not isinstance(response_format, dict) or response_format.get("type") not in ("json_object", "json_schema"):
  456. return {}
  457. spec = response_format.get("json_schema") if response_format.get("type") == "json_schema" else None
  458. # A ``json_schema`` spec with no ``schema`` key has nothing to constrain with (the Anthropic
  459. # translator bails the same way) — ask for JSON and let the model shape it.
  460. schema = spec.get("schema") if isinstance(spec, dict) else None
  461. if not isinstance(schema, dict):
  462. return {"responseMimeType": "application/json"}
  463. key, prep = ("responseJsonSchema", prepare_gemini_tool_parameters) if json_schema else ("responseSchema", sanitize_gemini_tool_parameters)
  464. return {"responseMimeType": "application/json", key: prep(schema)}
  465. def build_gemini_request(
  466. *, messages: list[dict[str, Any]], tools: Any = None, tool_choice: Any = None, temperature: Optional[float] = None,
  467. max_tokens: Optional[int] = None, top_p: Optional[float] = None, stop: Any = None, thinking_config: Any = None,
  468. response_format: Any = None, model: str = "", tools_as_json_schema: bool = False,
  469. ) -> dict[str, Any]:
  470. # Gemini 3+ both requires tool-call ids and accepts multimodal functionResponse parts.
  471. is_gemini3 = gemini_requires_tool_call_ids(model)
  472. contents, system_instruction = _build_gemini_contents(messages, include_tool_call_ids=is_gemini3, is_gemini3=is_gemini3)
  473. gemini_tools = _translate_tools_to_gemini(tools, json_schema=tools_as_json_schema)
  474. tool_config = _translate_tool_choice_to_gemini(tool_choice)
  475. optional = (("systemInstruction", system_instruction), ("tools", gemini_tools), ("toolConfig", tool_config))
  476. request: dict[str, Any] = {"contents": contents, **{k: v for k, v in optional if v}}
  477. # Key order is part of the wire format (prompt-cache parity): temperature, maxOutputTokens, topP, stop, thinking.
  478. generation = (
  479. ("temperature", temperature), ("maxOutputTokens", _effective_gemini_max_output_tokens(max_tokens, thinking_config)),
  480. ("topP", top_p), ("stopSequences", (stop if isinstance(stop, list) else [str(stop)]) if stop else None),
  481. ("thinkingConfig", _normalize_thinking_config(thinking_config)),
  482. )
  483. json_output = _translate_response_format(response_format, json_schema=tools_as_json_schema)
  484. # Gemini 400s when forced function calling (mode ANY, from ``tool_choice="required"`` or a named
  485. # function) is combined with a JSON responseMimeType, and pre-Gemini-3 models reject JSON output
  486. # alongside ANY function declarations ("Function calling with a response mime type:
  487. # 'application/json' is unsupported"); only Gemini 3+ combines tools with structured output.
  488. # The tools win; JSON can come on a later turn, and callers tolerate an unconstrained reply.
  489. forced_call = (tool_config or {}).get("functionCallingConfig", {}).get("mode") == "ANY"
  490. if json_output and (forced_call or (gemini_tools and not is_gemini3)):
  491. logger.debug("Gemini: dropping JSON response_format — %s",
  492. "tool_choice forces function calling (mode ANY)" if forced_call else "pre-Gemini-3 model with tools")
  493. json_output = {}
  494. request["generationConfig"] = {**{k: v for k, v in generation if v is not None}, **json_output}
  495. return request
  496. # ── Gemini → OpenAI response translation ─────────────────────────────────────
  497. def _tool_call_extra_from_part(part: dict[str, Any]) -> Optional[dict[str, Any]]:
  498. sig = part.get("thoughtSignature")
  499. return {"google": {"thought_signature": sig}} if isinstance(sig, str) and sig else None
  500. def _provider_call_id(fc: dict[str, Any]) -> Optional[str]:
  501. fc_id = fc.get("id")
  502. return fc_id if isinstance(fc_id, str) and fc_id else None
  503. def _new_call_id(fc: dict[str, Any]) -> str:
  504. """Echo the functionCall/delta ``id`` when present, else mint an OpenAI-style one."""
  505. return _provider_call_id(fc) or f"call_{uuid.uuid4().hex[:12]}"
  506. def _dump_call_args(fc: dict[str, Any], **kwargs: Any) -> str:
  507. try:
  508. return json.dumps(fc.get("args") or {}, ensure_ascii=False, **kwargs)
  509. except (TypeError, ValueError):
  510. return "{}"
  511. def _usage_from_metadata(usage_meta: dict[str, Any]) -> SimpleNamespace:
  512. """Gemini ``usageMetadata`` → OpenAI-shaped usage.
  513. Hidden thinking is reported separately in ``thoughtsTokenCount``:
  514. ``candidatesTokenCount`` counts visible output only, while ``totalTokenCount``
  515. already includes thoughts. OpenAI's ``completion_tokens`` covers reasoning, so
  516. thoughts are folded in (otherwise a thinking turn bills a few percent of its
  517. real output and ``prompt + completion != total``) and also surfaced under
  518. ``completion_tokens_details.reasoning_tokens``, where ``normalize_usage`` reads
  519. them. Absent on non-thinking/older responses, which keeps their numbers as-is."""
  520. count = lambda key: int(usage_meta.get(key) or 0)
  521. reasoning_tokens = count("thoughtsTokenCount")
  522. # Multi-hop long decode: the counts are summed over hops (billing); the context size is hop 1's prompt.
  523. initial = {"initial_prompt_tokens": count("initialPromptTokenCount"),
  524. "initial_cached_tokens": count("initialCachedContentTokenCount")} if "initialPromptTokenCount" in usage_meta else {}
  525. return SimpleNamespace(
  526. prompt_tokens=count("promptTokenCount"), completion_tokens=count("candidatesTokenCount") + reasoning_tokens,
  527. total_tokens=count("totalTokenCount"), prompt_tokens_details=SimpleNamespace(cached_tokens=count("cachedContentTokenCount")),
  528. completion_tokens_details=SimpleNamespace(reasoning_tokens=reasoning_tokens), **initial,
  529. )
  530. def _envelope(model: str, object_: str, choice: SimpleNamespace, usage: Any, cls: type = SimpleNamespace) -> Any:
  531. """OpenAI chat.completion / chat.completion.chunk envelope around one choice."""
  532. return cls(id=f"chatcmpl-{uuid.uuid4().hex[:12]}", object=object_, created=int(time.time()), model=model,
  533. choices=[choice], usage=usage)
  534. def _tool_call_ns(name: str, arguments: str, index: int, call_id: str, extra_content: Any) -> SimpleNamespace:
  535. """OpenAI-shaped tool call; ``extra_content`` attached only when it is a dict."""
  536. extra = {"extra_content": extra_content} if isinstance(extra_content, dict) else {}
  537. return SimpleNamespace(id=call_id, type="function", index=index, function=SimpleNamespace(name=name, arguments=arguments), **extra)
  538. def _part_text(part: dict[str, Any]) -> tuple[Optional[str], bool]:
  539. """``(text, is_thought)`` for a candidate part; ``(None, False)`` when it carries no text."""
  540. text = part.get("text")
  541. return (text, part.get("thought") is True) if isinstance(text, str) else (None, False)
  542. def _text_part_signature(part: dict[str, Any]) -> Optional[str]:
  543. """``thoughtSignature`` on a non-functionCall part (a text turn's last part; in streams an empty-text
  544. part). Replay is optional, but the server rehydrates the turn's thoughts from it (live: 31 -> 237
  545. prompt tokens), so it is kept as the message-level ``extra_content`` signature."""
  546. sig = part.get("thoughtSignature")
  547. return sig if isinstance(sig, str) and sig and "functionCall" not in part else None
  548. def _part_function_call(part: dict[str, Any]) -> Optional[dict[str, Any]]:
  549. fc = part.get("functionCall")
  550. return fc if isinstance(fc, dict) and fc.get("name") else None
  551. # Guidance per ``promptFeedback.blockReason`` value with a specific remedy; the rest (OTHER, Vertex's
  552. # MODEL_ARMOR / JAILBREAK) get the generic text. A prompt-level block is an HTTP 200 with no candidates;
  553. # translated as-is it becomes an empty "stop" turn the user sees as silence.
  554. _BLOCK_REASON_GUIDANCE = {
  555. "BLOCKLIST": "The prompt includes blocked terms. Rephrase and try again.",
  556. "PROHIBITED_CONTENT": "The prompt may contain prohibited content. Adjust it and try again.",
  557. "SAFETY": "The prompt was blocked by Gemini's safety filters. Adjust it and try again.",
  558. "IMAGE_SAFETY": "The image was blocked for safety reasons.",
  559. }
  560. def raise_on_prompt_block(payload: dict[str, Any]) -> None:
  561. """Raise a terminal error when ``promptFeedback.blockReason`` is set (unary response or stream event).
  562. No HTTP status: the wire said 200. ``agent.error_classifier`` keys on the ``gemini_prompt_blocked`` code
  563. and routes it to content_policy_blocked — deterministic for the unchanged prompt, so no retry."""
  564. feedback = payload.get("promptFeedback")
  565. reason = feedback.get("blockReason") if isinstance(feedback, dict) else None
  566. if not reason:
  567. return
  568. reason = str(reason).upper()
  569. # Vertex explains the block in ``blockReasonMessage``; prefer it over the canned guidance.
  570. message = feedback.get("blockReasonMessage")
  571. guidance = (message.strip() if isinstance(message, str) and message.strip()
  572. else _BLOCK_REASON_GUIDANCE.get(reason, "The prompt was blocked. Adjust it and try again."))
  573. raise GeminiAPIError(f"Gemini blocked this prompt (blockReason={reason}): {guidance}",
  574. code="gemini_prompt_blocked", details={"promptFeedback": feedback})
  575. def translate_gemini_response(resp: dict[str, Any], model: str) -> SimpleNamespace:
  576. raise_on_prompt_block(resp)
  577. candidates = resp.get("candidates") or []
  578. cand = parts = None
  579. if isinstance(candidates, list) and candidates:
  580. cand = candidates[0] if isinstance(candidates[0], dict) else {}
  581. content_obj = cand.get("content")
  582. parts = content_obj.get("parts") if isinstance(content_obj, dict) else []
  583. pieces: dict[bool, list[str]] = {False: [], True: []} # is_thought → text pieces
  584. tool_calls: list[SimpleNamespace] = []
  585. text_signature = None
  586. for index, part in enumerate(parts or []):
  587. if not isinstance(part, dict):
  588. continue
  589. text, is_thought = _part_text(part)
  590. if text is not None:
  591. pieces[is_thought].append(text)
  592. text_signature = _text_part_signature(part) or text_signature
  593. elif fc := _part_function_call(part):
  594. tool_calls.append(_tool_call_ns(str(fc["name"]), _dump_call_args(fc), index, _new_call_id(fc), _tool_call_extra_from_part(part)))
  595. finish_reason = "tool_calls" if tool_calls else _FINISH_REASON_MAP.get(str((cand or {}).get("finishReason") or "").upper(), "stop")
  596. usage = _usage_from_metadata((resp.get("usageMetadata") or {}) if cand is not None else {})
  597. reasoning = "".join(pieces[True]) or None
  598. message = SimpleNamespace(role="assistant", content="".join(pieces[False]) if pieces[False] else ("" if cand is None else None),
  599. tool_calls=tool_calls or None, reasoning=reasoning, reasoning_content=reasoning, reasoning_details=None,
  600. extra_content=_tool_call_extra_from_part({"thoughtSignature": text_signature}))
  601. return _envelope(model, "chat.completion", SimpleNamespace(index=0, message=message, finish_reason=finish_reason), usage)
  602. class _GeminiStreamChunk(SimpleNamespace): ...
  603. def _make_stream_chunk(
  604. *, model: str, content: str = "", tool_call_delta: Optional[dict[str, Any]] = None, finish_reason: Optional[str] = None, reasoning: str = "",
  605. text_signature: Optional[str] = None,
  606. ) -> _GeminiStreamChunk:
  607. d = tool_call_delta
  608. tool_calls = None if d is None else [
  609. _tool_call_ns(d.get("name") or "", d.get("arguments") or "", d.get("index", 0), _new_call_id(d), d.get("extra_content"))
  610. ]
  611. delta = SimpleNamespace(role="assistant", content=content or None, tool_calls=tool_calls, reasoning=reasoning or None,
  612. reasoning_content=reasoning or None,
  613. extra_content=_tool_call_extra_from_part({"thoughtSignature": text_signature}))
  614. choice = SimpleNamespace(index=0, delta=delta, finish_reason=finish_reason)
  615. return _envelope(model, "chat.completion.chunk", choice, None, cls=_GeminiStreamChunk)
  616. _SSE_DONE = object() # sentinel: terminal [DONE] frame
  617. def _parse_sse_line(line: str) -> Any:
  618. """One SSE line → payload dict, ``_SSE_DONE`` for the terminal frame, or None."""
  619. line = line.rstrip("\r")
  620. if not line.startswith("data: "):
  621. return None
  622. if (data := line[6:]) == "[DONE]":
  623. return _SSE_DONE
  624. try:
  625. payload = json.loads(data)
  626. except json.JSONDecodeError:
  627. logger.debug("Non-JSON Gemini SSE line: %s", data[:200])
  628. return None
  629. return payload if isinstance(payload, dict) else None
  630. def _iter_sse_events(response: httpx.Response) -> Iterator[dict[str, Any]]:
  631. buffer = ""
  632. for chunk in response.iter_text():
  633. buffer += chunk or ""
  634. while "\n" in buffer:
  635. line, buffer = buffer.split("\n", 1)
  636. payload = _parse_sse_line(line)
  637. if payload is _SSE_DONE:
  638. return
  639. if payload is not None:
  640. yield payload
  641. # The final frame may not be newline-terminated: flush the residual buffer
  642. # after EOF instead of silently dropping its content (pi#8997 bug class).
  643. if buffer:
  644. payload = _parse_sse_line(buffer)
  645. if payload is not None and payload is not _SSE_DONE:
  646. yield payload
  647. def _tool_call_slot(fc: dict[str, Any], part: dict[str, Any], part_index: int, args_str: str,
  648. tool_call_indices: dict[str, dict[str, Any]]) -> tuple[str, Optional[dict[str, Any]]]:
  649. """``(key, existing slot or None)`` for a streamed functionCall.
  650. Gemini 3 ids each tool call, so the id is the slot identity (``part_index`` and the thought
  651. signature drift across events of one call). Gemini 2.5 sends no id and ``part_index`` restarts
  652. at 0 per event, so two different calls to one tool in separate events would share a slot and
  653. have their arguments concatenated into unparseable JSON: Gemini re-sends full arguments, so a
  654. payload that is not a prefix-extension (or resend) of the slot's accumulated arguments is a
  655. different call and gets its own ``key#N`` slot, kept reachable so its own resend lands on it.
  656. """
  657. if fc_id := _provider_call_id(fc):
  658. key = json.dumps({"provider_call_id": fc_id}, sort_keys=True)
  659. return key, tool_call_indices.get(key)
  660. thought_signature = part.get("thoughtSignature") if isinstance(part.get("thoughtSignature"), str) else ""
  661. key = json.dumps({"part_index": part_index, "name": fc["name"], "thought_signature": thought_signature}, sort_keys=True)
  662. slot = tool_call_indices.get(key)
  663. if slot is None or args_str.startswith(slot["last_arguments"]):
  664. return key, slot
  665. for other_key, other in tool_call_indices.items():
  666. if other_key.startswith(f"{key}#") and args_str.startswith(other["last_arguments"]):
  667. return other_key, other
  668. return f"{key}#{len(tool_call_indices)}", None
  669. def translate_stream_event(event: dict[str, Any], model: str, tool_call_indices: dict[str, dict[str, Any]]) -> list[_GeminiStreamChunk]:
  670. raise_on_prompt_block(event)
  671. candidates = event.get("candidates") or []
  672. if not candidates:
  673. return []
  674. cand = candidates[0] if isinstance(candidates[0], dict) else {}
  675. parts = (cand.get("content") or {}).get("parts") or []
  676. chunks: list[_GeminiStreamChunk] = []
  677. for part_index, part in enumerate(parts):
  678. if not isinstance(part, dict):
  679. continue
  680. text, is_thought = _part_text(part)
  681. if is_thought:
  682. chunks.append(_make_stream_chunk(model=model, reasoning=text))
  683. continue
  684. if text:
  685. chunks.append(_make_stream_chunk(model=model, content=text))
  686. if sig := _text_part_signature(part):
  687. chunks.append(_make_stream_chunk(model=model, text_signature=sig))
  688. if fc := _part_function_call(part):
  689. name = str(fc["name"])
  690. args_str = _dump_call_args(fc, sort_keys=True)
  691. call_key, slot = _tool_call_slot(fc, part, part_index, args_str, tool_call_indices)
  692. if slot is None:
  693. slot = tool_call_indices[call_key] = {"index": len(tool_call_indices), "id": _new_call_id(fc), "last_arguments": ""}
  694. # Gemini re-sends the full args each event; emit only the new suffix.
  695. last_arguments = slot["last_arguments"]
  696. slot["last_arguments"] = args_str
  697. delta = {"index": slot["index"], "id": slot["id"], "name": name, "extra_content": _tool_call_extra_from_part(part),
  698. "arguments": args_str.removeprefix(last_arguments)}
  699. chunks.append(_make_stream_chunk(model=model, tool_call_delta=delta))
  700. if finish_reason_raw := str(cand.get("finishReason") or ""):
  701. finish_reason = "tool_calls" if tool_call_indices else _FINISH_REASON_MAP.get(finish_reason_raw.upper(), "stop")
  702. finish_chunk = _make_stream_chunk(model=model, finish_reason=finish_reason)
  703. if usage_meta := event.get("usageMetadata") or {}: # rides on the finish chunk so the stream loop records tokens
  704. finish_chunk.usage = _usage_from_metadata(usage_meta)
  705. chunks.append(finish_chunk)
  706. return chunks
  707. def _error_info(err_obj: dict[str, Any]) -> tuple[str, dict[str, Any]]:
  708. """``(reason, metadata)`` from the first google.rpc.ErrorInfo detail (later ones fill gaps until reason is set)."""
  709. reason, metadata = "", {}
  710. details = err_obj.get("details")
  711. for detail in details if isinstance(details, list) else []:
  712. if isinstance(detail, dict) and not reason and str(detail.get("@type") or "").endswith("/google.rpc.ErrorInfo"):
  713. reason = detail["reason"] if isinstance(detail.get("reason"), str) else reason
  714. metadata = detail["metadata"] if isinstance(detail.get("metadata"), dict) else metadata
  715. return reason, metadata
  716. def _error_object(body_text: str) -> dict[str, Any]:
  717. """The ``error`` object of a Google JSON error body, or ``{}``."""
  718. try:
  719. parsed = json.loads(body_text) if body_text else None
  720. except (ValueError, TypeError):
  721. return {}
  722. err_obj = parsed.get("error") if isinstance(parsed, dict) else None
  723. return err_obj if isinstance(err_obj, dict) else {}
  724. def gemini_http_error(
  725. response: httpx.Response, *, body_text: Optional[str] = None, api_key: str = "", base_url: str = "",
  726. key_guidance: bool = True,
  727. ) -> GeminiAPIError:
  728. """``key_guidance=False`` for OAuth-bearer callers: the API-key fixes (free tier, Standard key, wrong
  729. key surface) are wrong advice when the credential is a user's OAuth access token."""
  730. status = response.status_code
  731. body_text = (_response_text(response) if body_text is None else body_text) or ""
  732. err_obj = _error_object(body_text)
  733. err_status, err_message = (str(err_obj.get(k) or "").strip() for k in ("status", "message"))
  734. reason, metadata = _error_info(err_obj)
  735. retry_after = parse_retry_after_seconds(response.headers)
  736. message = (
  737. f"Gemini HTTP {status} ({err_status or 'error'}): {err_message}" if err_message
  738. else f"Gemini returned HTTP {status}: {body_text[:500]}"
  739. )
  740. # Users who bypassed the setup wizard (raw GOOGLE_API_KEY in .env) still need to learn the free
  741. # tier cannot sustain an agent session; a legacy "Standard" key gets the real fix (Google's raw
  742. # 401 asks for OAuth; after Sept 2026 the same AIza key is often a 400 API_KEY_INVALID).
  743. if key_guidance and status == 429 and is_free_tier_quota_error(err_message or body_text):
  744. message += _FREE_TIER_GUIDANCE
  745. if key_guidance and is_standard_key_auth_error(status, err_message or body_text, reason, api_key=api_key):
  746. message += _STANDARD_KEY_GUIDANCE
  747. if key_guidance and status == 403:
  748. message += wrong_gemini_surface_guidance(base_url, api_key, err_status)
  749. return GeminiAPIError(
  750. message, code=_HTTP_ERROR_CODES.get(status, f"gemini_http_{status}"), status_code=status, response=response,
  751. retry_after=retry_after, details={"status": err_status, "reason": reason, "metadata": metadata, "message": err_message},
  752. )
  753. class GeminiNativeClient:
  754. """Minimal OpenAI-SDK-compatible facade (``client.chat.completions.create(**kwargs)``) over Gemini's native REST API."""
  755. # For agent/auxiliary_client.py: a complete client, never re-dispatched through a wire adapter.
  756. # (No HERMES_SKIP_ASYNC_WRAP — the async path has a real conversion, AsyncGeminiNativeClient.)
  757. HERMES_SKIP_TRANSPORT_WRAP = True
  758. # Seams for a subclass that speaks the same wire under another credential (an OAuth bearer on the
  759. # per-user-quota methods): RPC method names, the missing-credential text, and ``_auth_headers``.
  760. GENERATE_METHOD, STREAM_METHOD = "generateContent", "streamGenerateContent"
  761. MISSING_KEY_ERROR = _MISSING_KEY_ERROR
  762. def __init__(
  763. self, *, api_key: str, base_url: Optional[str] = None, default_headers: Optional[dict[str, str]] = None,
  764. timeout: Any = None, http_client: Optional[httpx.Client] = None, **_: Any,
  765. ) -> None:
  766. if not (api_key or "").strip():
  767. raise RuntimeError(self.MISSING_KEY_ERROR)
  768. self.api_key, self.is_closed = api_key, False
  769. self.base_url = normalize_gemini_base_url(base_url)
  770. self._default_headers = dict(default_headers or {})
  771. self.chat = SimpleNamespace(completions=SimpleNamespace(create=self._create_chat_completion))
  772. # read=1200: Gemini 4 hops can think for minutes; Google asks for a >=20 min read timeout (its
  773. # stream limit), and a shorter one cuts long-decode hops off mid-think.
  774. self._http = http_client or httpx.Client(timeout=timeout or httpx.Timeout(connect=15.0, read=1200.0, write=30.0, pool=30.0))
  775. def close(self) -> None:
  776. self.is_closed = True
  777. with contextlib.suppress(Exception):
  778. self._http.close()
  779. # OpenAI-client duck-type surface: callers may use ``with client:``.
  780. def __enter__(self):
  781. return self
  782. def __exit__(self, exc_type, exc_val, exc_tb):
  783. self.close()
  784. def _auth_headers(self) -> dict[str, str]:
  785. return {"x-goog-api-key": self.api_key}
  786. def _headers(self) -> dict[str, str]:
  787. return {"Content-Type": "application/json", "Accept": "application/json", **self._auth_headers(),
  788. "User-Agent": f"{_api_client()} (gemini-native)", "X-Goog-Api-Client": _api_client(), **self._default_headers}
  789. def _http_error(self, response: httpx.Response, body_text: Optional[str] = None) -> GeminiAPIError:
  790. return gemini_http_error(response, body_text=body_text, api_key=self.api_key, base_url=self.base_url)
  791. @staticmethod
  792. def _advance_stream_iterator(iterator: Iterator[_GeminiStreamChunk]) -> tuple[bool, Optional[_GeminiStreamChunk]]:
  793. chunk = next(iterator, _END)
  794. return (True, None) if chunk is _END else (False, chunk)
  795. def _create_chat_completion(
  796. self, *, model: str = "gemini-3.7-flash", messages: Optional[list[dict[str, Any]]] = None, stream: bool = False,
  797. tools: Any = None, tool_choice: Any = None, temperature: Optional[float] = None, max_tokens: Optional[int] = None,
  798. top_p: Optional[float] = None, stop: Any = None, response_format: Any = None, extra_body: Optional[dict[str, Any]] = None,
  799. timeout: Any = None, **_: Any,
  800. ) -> Any:
  801. extra = extra_body if isinstance(extra_body, dict) else {}
  802. # Long-decode budget (Gemini 4, effort above high) raises the total cap; an explicit larger cap still wins.
  803. budget = extra.get("max_output_tokens")
  804. if isinstance(budget, int) and budget > int(max_tokens or 0):
  805. max_tokens = budget
  806. request = build_gemini_request(
  807. messages=messages or [], tools=tools, tool_choice=tool_choice, temperature=temperature, max_tokens=max_tokens,
  808. top_p=top_p, stop=stop, thinking_config=extra.get("thinking_config") or extra.get("thinkingConfig"),
  809. response_format=response_format or extra.get("response_format"), model=model,
  810. tools_as_json_schema=gemini_accepts_parameters_json_schema(self.base_url),
  811. )
  812. model = bare_gemini_model_id(model)
  813. url = f"{self.base_url}/models/{model}:"
  814. if stream:
  815. return self._stream_completion(model, f"{url}{self.STREAM_METHOD}?alt=sse", request, timeout)
  816. hops = [self._generate(url + self.GENERATE_METHOD, request, timeout)]
  817. max_hops = long_decode_hops(request["generationConfig"].get("maxOutputTokens")) + 1
  818. # Long decode: same request + token, never the partial output. Past the ceiling the last hop's
  819. # CONTINUATION finish translates to ``length``.
  820. while (token := continuation_token(hops[-1])) and len(hops) < max_hops:
  821. hops.append(self._generate(url + self.GENERATE_METHOD, {**request, "continuationToken": token}, timeout))
  822. return translate_gemini_response(merge_hop_responses(hops) if len(hops) > 1 else hops[0], model=model)
  823. def _generate(self, url: str, request: dict[str, Any], timeout: Any) -> dict[str, Any]:
  824. response = self._http.post(url, json=request, headers=self._headers(), timeout=timeout)
  825. if response.status_code != 200:
  826. raise self._http_error(response)
  827. try:
  828. return response.json()
  829. except ValueError as exc:
  830. raise GeminiAPIError(
  831. f"Invalid JSON from Gemini native API: {exc}", code="gemini_invalid_json", status_code=response.status_code, response=response,
  832. ) from exc
  833. def _stream_completion(self, model: str, url: str, request: dict[str, Any], timeout: Any) -> Iterator[_GeminiStreamChunk]:
  834. tool_call_indices: dict[str, dict[str, Any]] = {} # shared across hops: they form one model turn
  835. hop_usage: list[dict[str, Any]] = []
  836. max_hops = long_decode_hops(request["generationConfig"].get("maxOutputTokens")) + 1
  837. body: dict[str, Any] = request
  838. # ``resume``: the latest token (hop end or mid-stream checkpoint) with nothing yielded after it.
  839. # The next hop, or a dropped stream, resends the request with it; ``sends`` bounds a stuck token.
  840. resume, sends = None, 0
  841. while True:
  842. try:
  843. headers = {**self._headers(), "Accept": "text/event-stream"}
  844. with self._http.stream("POST", url, json=body, headers=headers, timeout=timeout) as response:
  845. if response.status_code != 200:
  846. raise self._http_error(response, read_streaming_error_body(response))
  847. for event in _iter_sse_events(response):
  848. hops_done = len(hop_usage)
  849. event, token = split_stream_continuation(event, hop_usage)
  850. if token and len(hop_usage) > hops_done and len(hop_usage) >= max_hops:
  851. # Hop ceiling: end the turn as truncated, usage summed over every hop.
  852. cand = {**event["candidates"][0], "finishReason": "MAX_TOKENS"}
  853. event, token = {**event, "candidates": [cand], "usageMetadata": merge_hop_usage(hop_usage)}, None
  854. chunks = translate_stream_event(event, model, tool_call_indices)
  855. if token or chunks: # a token commits its own event's chunks; a later chunk voids it
  856. resume, sends = token, 0 if token else sends
  857. yield from chunks
  858. except httpx.HTTPError as exc:
  859. if not resume or sends >= _MAX_TOKEN_SENDS: # nothing committed to resume from: retry from the start
  860. raise GeminiAPIError(f"Gemini streaming request failed: {exc}", code="gemini_stream_error") from exc
  861. logger.warning("Gemini stream dropped (%s); resuming from its last checkpoint", exc)
  862. if not resume or sends >= _MAX_TOKEN_SENDS:
  863. return
  864. body, sends = {**request, "continuationToken": resume}, sends + 1
  865. class AsyncGeminiNativeClient:
  866. """Async wrapper used by auxiliary_client for native Gemini calls."""
  867. def __init__(self, sync_client: GeminiNativeClient):
  868. # ``_real_client``: the auxiliary cache evicts entries by leaf client; GeminiNativeClient is itself the leaf.
  869. self._sync = self._real_client = sync_client
  870. self.api_key, self.base_url = sync_client.api_key, sync_client.base_url
  871. self.chat = SimpleNamespace(completions=SimpleNamespace(create=self._create_chat_completion))
  872. # Expose the underlying sync client as _real_client so the auxiliary cache's eviction-by-leaf-client
  873. # helper (#23482) can find and drop this async entry when the sync GeminiNativeClient is poisoned.
  874. # GeminiNativeClient is itself the leaf (no OpenAI client beneath it), so we point at the sync_client
  875. # directly.
  876. async def _create_chat_completion(self, **kwargs: Any) -> Any:
  877. result = await asyncio.to_thread(self._sync.chat.completions.create, **kwargs)
  878. return self._async_stream(result) if kwargs.get("stream") else result
  879. async def _async_stream(self, iterator: Iterator[_GeminiStreamChunk]) -> Any:
  880. while not (step := await asyncio.to_thread(self._sync._advance_stream_iterator, iterator))[0]:
  881. yield step[1]
  882. async def close(self) -> None:
  883. await asyncio.to_thread(self._sync.close)