vertex_adapter.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. """Vertex AI (Google Cloud) auth + base-URL resolution for its OpenAI-compatible endpoint.
  2. Requires ``google-auth`` (lazy-installed). Secrets: GOOGLE_APPLICATION_CREDENTIALS /
  3. VERTEX_CREDENTIALS_PATH (SA JSON path; the latter wins), VERTEX_PROJECT_ID,
  4. VERTEX_REGION. project_id/region may also live in config.yaml ``vertex:``;
  5. env wins over config.
  6. """
  7. import hashlib
  8. import json
  9. import logging
  10. import os
  11. import time
  12. from typing import Any, Optional, Tuple
  13. from agent.credential_source import VERTEX_OAUTH, tag_credential_source
  14. from agent.secret_scope import get_secret as _get_secret, is_multiplex_active
  15. try:
  16. import google.auth
  17. import google.auth.transport.requests
  18. from google.oauth2 import service_account
  19. except ImportError:
  20. google = None # type: ignore[assignment]
  21. def _ensure_google_auth() -> bool:
  22. """Bind ``google.auth`` on first use, installing the [vertex] extra through PM if needed.
  23. The extra left [all] under the lazy-install policy (2026-05-12) so a plain ``hermes-agent``
  24. install still reaches Vertex after selecting a Gemini model. This runs at the first
  25. credential request, never at import: an import-time sync would rebuild the dependency
  26. environment of whatever process happens to import this module.
  27. """
  28. global google, service_account
  29. if google is not None:
  30. return True
  31. try:
  32. from pm import ensure_import
  33. ensure_import("vertex")
  34. import google.auth as _auth
  35. import google.auth.transport.requests
  36. from google.oauth2 import service_account as _service_account
  37. except Exception as exc:
  38. logger.warning("google-auth package not installed (%s). Cannot use Vertex AI.", exc)
  39. return False
  40. import google as _google
  41. google, service_account = _google, _service_account
  42. return True
  43. logger = logging.getLogger(__name__)
  44. DEFAULT_REGION = "global"
  45. _CLOUD_PLATFORM_SCOPES = ["https://www.googleapis.com/auth/cloud-platform"]
  46. _creds_cache: dict = {}
  47. def _vertex_config() -> dict:
  48. """Return the ``vertex:`` section of config.yaml, or {} on any failure."""
  49. try:
  50. from hermes_cli.config import load_config
  51. section = load_config().get("vertex")
  52. return section if isinstance(section, dict) else {}
  53. except Exception:
  54. return {}
  55. def _env_or_config(env_var: str, config_key: str) -> str:
  56. """Setting precedence: env/secret > config.yaml; "" when neither is set."""
  57. return (_get_secret(env_var) or "").strip() or str(_vertex_config().get(config_key) or "").strip()
  58. def _resolve_region(explicit: Optional[str] = None) -> str:
  59. """Region precedence: explicit arg > VERTEX_REGION env > config.yaml > default."""
  60. return explicit or _env_or_config("VERTEX_REGION", "region") or DEFAULT_REGION
  61. def _resolve_project_override() -> Optional[str]:
  62. """Project-ID override (VERTEX_PROJECT_ID env > config.yaml), or None to use the creds' embedded project_id."""
  63. return _env_or_config("VERTEX_PROJECT_ID", "project_id") or None
  64. def _resolve_credentials_path(explicit: Optional[str]) -> Optional[str]:
  65. if explicit and os.path.exists(explicit):
  66. return explicit
  67. # get_secret, not os.environ: under a multiplex gateway os.environ reflects whichever
  68. # .env loaded at boot, and a raw read could mint (and bill) another profile's SA tokens.
  69. for env_var in ("VERTEX_CREDENTIALS_PATH", "GOOGLE_APPLICATION_CREDENTIALS"):
  70. path = _get_secret(env_var)
  71. if path and os.path.exists(path):
  72. return path
  73. return None
  74. def _sa_snapshot(resolved_path: Optional[str]) -> tuple[Optional[bytes], tuple[Any, ...]]:
  75. """Resolve (bytes-or-None, cache key) for one credential attempt.
  76. - No path (ADC): (None, ("__adc__",)) sentinel key.
  77. - Readable file: (bytes, (path, sha256)).
  78. - Unreadable file: (None, (path,)) — the caller falls back to the SDK's own file read.
  79. The key fingerprints file CONTENT, not stat metadata (a metadata-preserving
  80. atomic replacement can swap the private key under an identical stat signature,
  81. and this cache guards an identity). Returning the bytes lets the caller build
  82. credentials from the SAME snapshot the key was computed from (no stat->read TOCTOU).
  83. """
  84. if not resolved_path:
  85. return None, ("__adc__",)
  86. try:
  87. with open(resolved_path, "rb") as fh:
  88. raw = fh.read()
  89. except OSError:
  90. return None, (resolved_path,)
  91. return raw, (resolved_path, hashlib.sha256(raw).hexdigest())
  92. def _load_credentials(resolved_path: Optional[str], sa_raw: Optional[bytes]) -> Optional[tuple[Any, Optional[str]]]:
  93. """Build (credentials, project_id) for a cache miss; None when ADC must be refused."""
  94. if resolved_path:
  95. if sa_raw is not None:
  96. creds = service_account.Credentials.from_service_account_info(json.loads(sa_raw), scopes=_CLOUD_PLATFORM_SCOPES)
  97. else:
  98. # Unreadable at key time: let the SDK try the file directly.
  99. creds = service_account.Credentials.from_service_account_file(resolved_path, scopes=_CLOUD_PLATFORM_SCOPES)
  100. return creds, creds.project_id
  101. # google.auth.default() reads GOOGLE_APPLICATION_CREDENTIALS from os.environ (set by whichever
  102. # profile loaded first); this profile doesn't define it, so refuse a stranger's identity.
  103. if is_multiplex_active() and os.environ.get("GOOGLE_APPLICATION_CREDENTIALS"):
  104. logger.warning(
  105. "Vertex ADC skipped for this profile: GOOGLE_APPLICATION_CREDENTIALS is set in the process environment "
  106. "(from another profile's .env) but not in this profile's own config. Set VERTEX_CREDENTIALS_PATH in this "
  107. "profile's .env instead of relying on ADC."
  108. )
  109. return None
  110. return google.auth.default(scopes=_CLOUD_PLATFORM_SCOPES)
  111. def _needs_refresh(creds) -> bool:
  112. """No token, expired, or within 5 minutes of expiry."""
  113. return (
  114. not getattr(creds, "token", None)
  115. or getattr(creds, "expired", False)
  116. or (getattr(creds, "expiry", None) is not None and (creds.expiry.timestamp() - time.time()) < 300)
  117. )
  118. def _cached_credentials(resolved_path: Optional[str], sa_raw: Optional[bytes], cache_key: tuple[Any, ...]):
  119. """(credentials, project_id) from the per-content cache, loading on a miss; None when refused."""
  120. cached = _creds_cache.get(cache_key)
  121. if cached is None:
  122. cached = _load_credentials(resolved_path, sa_raw)
  123. if cached is None:
  124. return None
  125. _creds_cache[cache_key] = cached
  126. # A rotation leaves the old signature's entry behind; keep at most
  127. # one Credentials per file so stale identities can't be reused.
  128. for k in [k for k in _creds_cache if k != cache_key and k[0] == cache_key[0]]:
  129. _creds_cache.pop(k, None)
  130. return cached
  131. def get_vertex_credentials(credentials_path: Optional[str] = None) -> tuple[Optional[str], Optional[str]]:
  132. """Return (fresh access_token, project_id) or (None, None); Credentials cached per file content."""
  133. if not _ensure_google_auth():
  134. return None, None
  135. resolved_path = _resolve_credentials_path(credentials_path)
  136. # One read serves both the cache key and credential construction (creds always match the fingerprint).
  137. sa_raw, cache_key = _sa_snapshot(resolved_path)
  138. try:
  139. cached = _cached_credentials(resolved_path, sa_raw, cache_key)
  140. if cached is None:
  141. return None, None
  142. creds, project_id = cached
  143. if _needs_refresh(creds):
  144. creds.refresh(google.auth.transport.requests.Request())
  145. return creds.token, _resolve_project_override() or project_id
  146. except Exception as e:
  147. logger.error(f"Failed to resolve Vertex AI credentials: {e}")
  148. _creds_cache.pop(cache_key, None)
  149. # If ADC failed (e.g. expired refresh token), try the SA file before giving
  150. # up — it may have been added after startup. Keyed on this attempt being ADC.
  151. sa_path = None if resolved_path else _resolve_credentials_path(credentials_path)
  152. if sa_path:
  153. logger.info("ADC failed, retrying with service account: %s", sa_path)
  154. return get_vertex_credentials(sa_path)
  155. return None, None
  156. def build_vertex_base_url(project_id: str, region: str = DEFAULT_REGION) -> str:
  157. """OpenAI-compatible Vertex base URL; ``global`` uses the bare host (Gemini 3.x preview is global-only)."""
  158. host = "aiplatform.googleapis.com" if region == "global" else f"{region}-aiplatform.googleapis.com"
  159. return f"https://{host}/v1beta1/projects/{project_id}/locations/{region}/endpoints/openapi"
  160. def get_vertex_config(
  161. credentials_path: Optional[str] = None, region: Optional[str] = None
  162. ) -> tuple[Optional[str], Optional[str]]:
  163. """Resolve (access_token, base_url) for Vertex AI, or (None, None) on failure."""
  164. token, project_id = get_vertex_credentials(credentials_path)
  165. if not token or not project_id:
  166. return None, None
  167. return token, build_vertex_base_url(project_id, _resolve_region(region))
  168. def get_vertex_base_url(credentials_path: Optional[str] = None, region: Optional[str] = None) -> Optional[str]:
  169. """The Vertex base_url WITHOUT minting a token (no OAuth exchange), or None when the credentials
  170. cannot be loaded or no project resolves. For processes that route but never send — the
  171. gateway-backed CLI, whose gateway session mints its own token for the turn."""
  172. if not _ensure_google_auth():
  173. return None
  174. resolved_path = _resolve_credentials_path(credentials_path)
  175. sa_raw, cache_key = _sa_snapshot(resolved_path)
  176. try:
  177. cached = _cached_credentials(resolved_path, sa_raw, cache_key)
  178. except Exception: # health: allow BLE001 -- same boundary as get_vertex_credentials: unloadable credentials are main's AuthError copy
  179. logger.debug("Vertex AI credentials could not be loaded", exc_info=True)
  180. _creds_cache.pop(cache_key, None)
  181. return None
  182. project_id = _resolve_project_override() or (cached[1] if cached else None)
  183. return build_vertex_base_url(project_id, _resolve_region(region)) if cached and project_id else None
  184. def vertex_access_token() -> str:
  185. """Callable API key: a fresh Vertex token, minted on first use and reused until near expiry.
  186. One stable object, so a credential re-resolution never reads as a key change."""
  187. token, _project_id = get_vertex_credentials()
  188. if not token:
  189. raise RuntimeError("Vertex AI OAuth token could not be minted (see the Vertex credential settings)")
  190. return token
  191. tag_credential_source(vertex_access_token, VERTEX_OAUTH)
  192. def has_vertex_credentials() -> bool:
  193. """Fast check (no network): a resolvable SA JSON path, or an explicit project ID (implies ADC)."""
  194. return bool(_resolve_credentials_path(None) or _resolve_project_override())
  195. def has_explicit_vertex_config() -> bool:
  196. """True only when the user deliberately pointed Hermes at Vertex.
  197. Stricter than :func:`has_vertex_credentials`: an ambient ``GOOGLE_APPLICATION_CREDENTIALS``
  198. must NOT gate the model picker open (unknowing spend). Only Hermes-scoped signals count.
  199. """
  200. if _resolve_project_override():
  201. return True
  202. sa_path = _get_secret("VERTEX_CREDENTIALS_PATH")
  203. return bool(sa_path and os.path.isfile(sa_path) and os.access(sa_path, os.R_OK))