azure_detect.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. """Azure Foundry endpoint auto-detection.
  2. The detector never crashes on errors (every HTTP call is wrapped in a broad try/except). Callers get
  3. a :class:`DetectionResult` with whatever information could be gathered, and fall back to manual
  4. entry for the rest.
  5. """
  6. from __future__ import annotations
  7. import json
  8. import logging
  9. import re
  10. from dataclasses import dataclass, field
  11. from typing import Any, Callable, Optional
  12. from urllib import request as urllib_request
  13. from urllib.error import HTTPError, URLError
  14. from urllib.parse import urlparse
  15. from hermes_cli.urllib_security import open_credentialed_url
  16. logger = logging.getLogger(__name__)
  17. TokenProvider = Optional[Callable[[], str]]
  18. # Azure OpenAI ``api-version`` fallbacks for pre-v1 resources; the v1 GA endpoint accepts requests
  19. # without ``api-version`` entirely, so these are only probed second.
  20. _AZURE_OPENAI_PROBE_API_VERSIONS = (
  21. "2025-04-01-preview",
  22. "2024-10-21", # oldest GA that supports /models
  23. )
  24. # Matches the value ``agent/anthropic_adapter.py`` uses when building the Anthropic client.
  25. _AZURE_ANTHROPIC_API_VERSION = "2025-04-15"
  26. _AZURE_DETECT_JSON_BODY_MAX_BYTES = 1024 * 1024
  27. _AZURE_DETECT_ERROR_BODY_MAX_BYTES = 64 * 1024
  28. @dataclass
  29. class DetectionResult:
  30. """Everything auto-detection could gather from a base URL + API key."""
  31. #: ``"chat_completions"``, ``"anthropic_messages"``, or ``None`` when detection failed.
  32. api_mode: Optional[str] = None
  33. #: Deployment / model IDs returned by ``/models`` (best effort; empty when not exposed).
  34. models: list[str] = field(default_factory=list)
  35. #: Lowercased host from the base URL (used for display messages).
  36. hostname: str = ""
  37. #: Human-readable reason the detector chose ``api_mode`` (shown by the wizard).
  38. reason: str = ""
  39. #: ``True`` when ``/models`` returned a valid OpenAI-shaped payload.
  40. models_probe_ok: bool = False
  41. #: ``True`` when the URL was determined to be Anthropic-style (path suffix or live probe).
  42. is_anthropic: bool = False
  43. def _resolve_credential(api_key: Any, token_provider: TokenProvider = None) -> tuple[Optional[str], str]:
  44. """Coerce wizard inputs into ``(token_or_None, mode)``.
  45. ``mode`` is ``"entra_id"`` when a callable token provider was supplied (the token is a freshly
  46. minted bearer JWT, sent ONLY in ``Authorization: Bearer``), else ``"api_key"``.
  47. """
  48. # Token-provider path (callable wins when both supplied).
  49. for provider, label in ((token_provider, "token_provider"), (api_key, "api_key callable")):
  50. if callable(provider) and not isinstance(provider, str):
  51. try:
  52. token = provider()
  53. return (str(token) if token else None), "entra_id"
  54. except Exception as exc:
  55. logger.debug("azure_detect: %s failed: %s", label, exc)
  56. return None, "entra_id"
  57. if isinstance(api_key, str) and api_key:
  58. return api_key, "api_key"
  59. return None, "api_key"
  60. def _authed_request(url: str, api_key: Any, token_provider, *, method: str = "GET",
  61. data: Optional[bytes] = None) -> urllib_request.Request:
  62. """Build a request carrying the right auth headers for the credential mode."""
  63. token, mode = _resolve_credential(api_key, token_provider)
  64. req = urllib_request.Request(url, method=method, data=data)
  65. if token:
  66. # Legacy broad-compat behaviour sends both headers so we land on any Azure resource. In
  67. # entra_id mode send Bearer ONLY — api-key would log a JWT in a slot meant for static keys.
  68. if mode != "entra_id":
  69. req.add_header("api-key", token)
  70. req.add_header("Authorization", f"Bearer {token}")
  71. req.add_header("User-Agent", "hermes-agent/azure-detect")
  72. return req
  73. def _read_limited_response_body(resp: Any, limit: int, *, label: str) -> bytes:
  74. body = resp.read(limit + 1)
  75. if len(body) > limit:
  76. raise ValueError(f"{label} exceeded {limit} bytes")
  77. return body
  78. def _http_get_json(url: str, api_key: Any, timeout: float = 6.0, *,
  79. token_provider: TokenProvider = None) -> tuple[int, Optional[dict]]:
  80. """GET with auth headers; return ``(status_code, parsed_json_or_None)``. Never raises."""
  81. req = _authed_request(url, api_key, token_provider)
  82. try:
  83. with open_credentialed_url(req, timeout=timeout) as resp:
  84. try:
  85. body = _read_limited_response_body(
  86. resp, _AZURE_DETECT_JSON_BODY_MAX_BYTES, label="Azure detection JSON response body",
  87. )
  88. return resp.status, json.loads(body.decode("utf-8", errors="replace"))
  89. except Exception:
  90. return resp.status, None
  91. except HTTPError as exc:
  92. return exc.code, None
  93. except (URLError, TimeoutError, OSError) as exc:
  94. logger.debug("azure_detect: GET %s failed: %s", url, exc)
  95. return 0, None
  96. except Exception as exc: # pragma: no cover — defensive
  97. logger.debug("azure_detect: GET %s unexpected error: %s", url, exc)
  98. return 0, None
  99. def _strip_trailing_v1(url: str) -> str:
  100. """Strip trailing ``/v1`` or ``/v1/`` so we can construct sub-paths."""
  101. return re.sub(r"/v1/?$", "", url.rstrip("/"))
  102. def _looks_like_anthropic_path(url: str) -> bool:
  103. """True when the path ends in ``/anthropic`` or contains a ``/anthropic/`` segment (Foundry Claude routes)."""
  104. try:
  105. path = (urlparse(url).path or "").lower().rstrip("/")
  106. return path.endswith("/anthropic") or "/anthropic/" in path + "/"
  107. except Exception:
  108. return False
  109. def _extract_model_ids(payload: dict) -> list[str]:
  110. """Model IDs from an OpenAI-shaped ``/models`` response; ``[]`` on any shape mismatch."""
  111. data = payload.get("data") if isinstance(payload, dict) else None
  112. if not isinstance(data, list):
  113. return []
  114. ids: list[str] = []
  115. for item in data:
  116. if isinstance(item, dict):
  117. mid = item.get("id") or item.get("model") or item.get("name")
  118. if isinstance(mid, str) and mid:
  119. ids.append(mid)
  120. return ids
  121. def _probe_openai_models(base_url: str, api_key: Any, *, token_provider: TokenProvider = None) -> tuple[bool, list[str]]:
  122. """Probe ``<base>/models`` for an OpenAI-shaped response."""
  123. base_url = base_url.rstrip("/")
  124. # Azure OpenAI v1 needs no api-version for GA paths, so probe without first; then fall back to
  125. # explicit api-versions for pre-v1 resources.
  126. candidates = [f"{base_url}/models"] + [f"{base_url}/models?api-version={v}" for v in _AZURE_OPENAI_PROBE_API_VERSIONS]
  127. for url in candidates:
  128. status, body = _http_get_json(url, api_key, token_provider=token_provider)
  129. if status == 200 and body is not None:
  130. ids = _extract_model_ids(body)
  131. if ids:
  132. logger.info("azure_detect: /models probe OK at %s (%d models)", url, len(ids))
  133. return True, ids
  134. # 200 + empty list still counts as "OpenAI shape, no models listed".
  135. if isinstance(body, dict) and "data" in body:
  136. return True, []
  137. return False, []
  138. def _probe_anthropic_messages(base_url: str, api_key: Any, *, token_provider: TokenProvider = None) -> bool:
  139. """Zero-token POST to ``<base>/v1/messages``: does the endpoint *recognise* the Anthropic shape?
  140. Any 4xx mentioning ``messages``/``model``, or an Anthropic-shaped error body, counts. Never
  141. completes a real chat.
  142. """
  143. url = f"{_strip_trailing_v1(base_url)}/v1/messages?api-version={_AZURE_ANTHROPIC_API_VERSION}"
  144. payload = json.dumps({"model": "probe", "max_tokens": 1, "messages": [{"role": "user", "content": "ping"}]}).encode("utf-8")
  145. req = _authed_request(url, api_key, token_provider, method="POST", data=payload)
  146. req.add_header("anthropic-version", "2023-06-01")
  147. req.add_header("content-type", "application/json")
  148. try:
  149. with open_credentialed_url(req, timeout=6.0) as resp:
  150. # Should never 200 — "probe" isn't a real deployment — but if it does, it speaks Anthropic.
  151. return resp.status < 500
  152. except HTTPError as exc:
  153. try:
  154. with exc:
  155. body = _read_limited_response_body(
  156. exc, _AZURE_DETECT_ERROR_BODY_MAX_BYTES, label="Azure Anthropic probe error response body",
  157. )
  158. lowered = body.decode("utf-8", errors="replace").lower()
  159. if "anthropic" in lowered or '"type"' in lowered and '"error"' in lowered:
  160. return True
  161. # Pre-Azure-v1 Foundry returns a plain 404 for Anthropic-style calls on non-Anthropic
  162. # deployments. A 400 "model not found" IS Anthropic though.
  163. return exc.code == 400 and ("messages" in lowered or "model" in lowered)
  164. except Exception:
  165. return False
  166. except Exception: # URLError, TimeoutError, OSError, anything else
  167. return False
  168. def detect(base_url: str, api_key: Any = "", *, token_provider: TokenProvider = None) -> DetectionResult:
  169. """Inspect an Azure endpoint and describe its transport + models (advisory — None api_mode means ask the user).
  170. ``api_key`` may be a string (legacy API-key auth — sends both ``api-key:`` and ``Authorization:
  171. Bearer``) or a callable returning a bearer JWT (Entra ID auth — sends ONLY ``Authorization:
  172. Bearer``). ``token_provider`` is an explicit name for the callable form; the callable wins.
  173. """
  174. result = DetectionResult()
  175. try:
  176. result.hostname = (urlparse(base_url).hostname or "").lower()
  177. except Exception:
  178. result.hostname = ""
  179. # 1. Path sniff: Foundry exposes Anthropic-style deployments under a dedicated /anthropic path.
  180. if _looks_like_anthropic_path(base_url):
  181. result.is_anthropic = True
  182. result.api_mode = "anthropic_messages"
  183. result.reason = "URL path ends in /anthropic → Anthropic Messages API"
  184. return result
  185. # 2. OpenAI-style /models probe — success means the endpoint definitely speaks OpenAI wire.
  186. ok, models = _probe_openai_models(base_url, api_key, token_provider=token_provider)
  187. if ok:
  188. result.models_probe_ok = True
  189. result.models = models
  190. result.api_mode = "chat_completions"
  191. result.reason = (
  192. f"GET /models returned {len(models)} model(s) — OpenAI-style endpoint" if models
  193. else "GET /models returned an OpenAI-shaped empty list — OpenAI-style endpoint"
  194. )
  195. return result
  196. # 3. Anthropic Messages probe — slower and more intrusive, so only when /models failed.
  197. if _probe_anthropic_messages(base_url, api_key, token_provider=token_provider):
  198. result.is_anthropic = True
  199. result.api_mode = "anthropic_messages"
  200. result.reason = "Endpoint accepts Anthropic Messages shape"
  201. return result
  202. result.reason = (
  203. "Could not probe endpoint (private network, missing model list, or "
  204. "non-standard path) — falling back to manual API-mode selection"
  205. )
  206. return result
  207. def lookup_context_length(model: str, base_url: str, api_key: Any = "", *,
  208. token_provider: TokenProvider = None) -> Optional[int]:
  209. """``get_model_context_length`` that returns None when only the fallback default would fire, so
  210. the wizard can distinguish "we actually know this" from "we guessed".
  211. """
  212. model_id = str(model or "").strip()
  213. if not model_id:
  214. return None
  215. try:
  216. from agent.model_metadata import DEFAULT_FALLBACK_CONTEXT, get_model_context_length
  217. except Exception:
  218. return None
  219. # Resolve the credential once: Entra mode calls the provider; api_key is a string pass-through.
  220. token, _mode = _resolve_credential(api_key, token_provider)
  221. try:
  222. n = get_model_context_length(model_id, base_url=base_url, api_key=token or "")
  223. except Exception as exc:
  224. logger.debug("azure_detect: context length lookup failed: %s", exc)
  225. return None
  226. return n if isinstance(n, int) and n > 0 and n != DEFAULT_FALLBACK_CONTEXT else None
  227. __all__ = ["DetectionResult", "detect", "lookup_context_length"]