runtime_provider_backends.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282
  1. """Provider-specific runtime builders for :mod:`hermes_cli.runtime_provider`: Azure Foundry, the
  2. OpenRouter / bare-custom fallback resolver, Bedrock, and external-process providers. Origin-internal
  3. collaborators are resolved on the origin module at call time via :func:`_rp` so test patches on
  4. ``hermes_cli.runtime_provider.*`` (``_get_model_config``, ``load_config``, ``has_usable_secret``,
  5. ``_try_resolve_from_custom_pool``, …) still apply."""
  6. from __future__ import annotations
  7. import os
  8. import re
  9. from typing import Any, Dict, Optional
  10. from agent.azure_identity_adapter import is_token_provider
  11. from agent.secret_scope import get_secret_str
  12. from hermes_constants import OPENROUTER_BASE_URL
  13. from utils import base_url_host_matches, base_url_hostname, base_url_origin
  14. def _rp():
  15. import hermes_cli.runtime_provider as origin
  16. return origin
  17. # ── Azure Foundry ──────────────────────────────────────────────────────────────────────────
  18. def _azure_entra_credentials(cfg_entra: dict[str, Any]) -> Any:
  19. """Callable api_key minting a fresh Entra JWT per request (OpenAI SDK accepts it natively;
  20. ``build_anthropic_client`` injects the bearer via an httpx hook)."""
  21. AuthError = _rp().AuthError
  22. try:
  23. from agent.azure_identity_adapter import SCOPE_AI_AZURE_DEFAULT, EntraIdentityConfig, build_token_provider
  24. except Exception as exc:
  25. raise AuthError(
  26. "Could not load the Azure Foundry Entra ID adapter. "
  27. "Run hermes pm repair, then restart Hermes. "
  28. f"(import failed: {exc})"
  29. ) from exc
  30. scope = str(cfg_entra.get("scope") or "").strip() or SCOPE_AI_AZURE_DEFAULT
  31. try:
  32. return build_token_provider(config=EntraIdentityConfig(scope=scope))
  33. except ImportError as exc:
  34. raise AuthError(str(exc)) from exc
  35. def _azure_foundry_api_key(rp, explicit_api_key: str) -> str:
  36. if explicit_api_key:
  37. return explicit_api_key
  38. try:
  39. from hermes_cli.config import get_env_value
  40. api_key = get_env_value("AZURE_FOUNDRY_API_KEY") or ""
  41. except Exception:
  42. api_key = ""
  43. api_key = api_key or get_secret_str("AZURE_FOUNDRY_API_KEY", "").strip()
  44. if not api_key:
  45. raise rp.AuthError(
  46. "Azure Foundry requires an API key. Set AZURE_FOUNDRY_API_KEY in "
  47. "~/.hermes/.env or run 'hermes model' to configure. To use "
  48. "keyless Microsoft Entra ID auth instead, set "
  49. "model.auth_mode: entra_id in config.yaml (or pick "
  50. "'Microsoft Entra ID' in 'hermes model')."
  51. )
  52. return api_key
  53. def _resolve_azure_foundry_runtime(*, requested_provider: str, model_cfg: dict[str, Any],
  54. explicit_api_key: Optional[str] = None, explicit_base_url: Optional[str] = None,
  55. target_model: Optional[str] = None) -> dict[str, Any]:
  56. """Azure Foundry: ``model.base_url`` + ``model.api_mode`` (or explicit overrides), API key from
  57. ``.env``/env or a per-request Entra ID token, trailing ``/v1`` stripped for Anthropic-style
  58. endpoints (the Anthropic SDK appends /v1/messages itself)."""
  59. rp = _rp()
  60. # Aux ``provider: auto`` forwards the main runtime's api_key — under entra_id that is the token
  61. # provider callable; str() would turn it into a function repr sent as a static key (401, #72421).
  62. forwarded_token_provider = explicit_api_key if is_token_provider(explicit_api_key) else None
  63. explicit_api_key = "" if forwarded_token_provider else str(explicit_api_key or "").strip()
  64. explicit_base_url_clean = str(explicit_base_url or "").strip().rstrip("/")
  65. cfg_base_url, cfg_api_mode, cfg_auth_mode, cfg_entra = "", "chat_completions", "api_key", {}
  66. if rp._cfg_provider(model_cfg) == "azure-foundry":
  67. cfg_base_url = rp._config_base_url_for_provider(model_cfg, "azure-foundry")
  68. cfg_api_mode = rp._parse_api_mode(model_cfg.get("api_mode")) or "chat_completions"
  69. cfg_auth_mode = str(model_cfg.get("auth_mode") or "api_key").strip().lower() or "api_key"
  70. if isinstance(model_cfg.get("entra"), dict):
  71. cfg_entra = model_cfg["entra"]
  72. # GPT-5.x / codex / o1-o4 deployments are Responses-API-only on Foundry.
  73. effective_model = str(target_model or model_cfg.get("default") or "").strip()
  74. cfg_api_mode = rp._azure_inferred_api_mode(effective_model, cfg_api_mode)
  75. env_base_url = get_secret_str("AZURE_FOUNDRY_BASE_URL", "").strip().rstrip("/")
  76. base_url = explicit_base_url_clean or cfg_base_url or env_base_url
  77. if not base_url:
  78. raise rp.AuthError(
  79. "Azure Foundry requires a base URL. Set it via 'hermes model' or "
  80. "the AZURE_FOUNDRY_BASE_URL environment variable."
  81. )
  82. if cfg_api_mode == "anthropic_messages":
  83. base_url = re.sub(r"/v1/?$", "", base_url)
  84. if cfg_auth_mode == "entra_id":
  85. # --api-key on the CLI while config says entra_id: honour the explicit string (escape hatch
  86. # for one-off testing).
  87. if explicit_api_key:
  88. api_key, source, auth_mode, entra = explicit_api_key, "explicit", "api_key", {}
  89. else:
  90. scope = str(cfg_entra.get("scope") or "").strip()
  91. api_key = forwarded_token_provider or _azure_entra_credentials(cfg_entra)
  92. source, auth_mode, entra = "entra_id", "entra_id", ({"scope": scope} if scope else {})
  93. return rp._runtime("azure-foundry", cfg_api_mode, base_url, api_key, auth_mode=auth_mode, entra=entra, source=source,
  94. requested_provider=requested_provider)
  95. return rp._runtime("azure-foundry", cfg_api_mode, base_url, _azure_foundry_api_key(rp, explicit_api_key),
  96. auth_mode="api_key", source="explicit" if (explicit_api_key or explicit_base_url) else "config",
  97. requested_provider=requested_provider)
  98. # ── OpenRouter / bare custom fallback ──────────────────────────────────────────────────────
  99. def _resolve_openrouter_runtime(
  100. *, requested_provider: str, explicit_api_key: Optional[str] = None, explicit_base_url: Optional[str] = None
  101. ) -> dict[str, Any]:
  102. """Terminal resolver: OpenRouter, or a bare/aliased ``custom`` endpoint. base_url precedence:
  103. explicit > CUSTOM_BASE_URL > trusted ``model.base_url`` > OPENROUTER_BASE_URL > default.
  104. OPENAI_BASE_URL never picks the endpoint (config.yaml is the single source of truth for endpoint
  105. URLs); it is read only to keep an OPENAI_API_KEY bound to another host out of the OpenRouter
  106. fallback. OpenRouter contexts prefer OPENROUTER_API_KEY; custom endpoints never receive the
  107. OpenRouter key and only get env keys gated on their authoritative hosts."""
  108. rp = _rp()
  109. model_cfg = rp._get_model_config()
  110. cfg_base_url = model_cfg.get("base_url") if isinstance(model_cfg.get("base_url"), str) else ""
  111. cfg_provider = (model_cfg.get("provider") if isinstance(model_cfg.get("provider"), str) else "").strip().lower()
  112. cfg_api_key = next((v.strip() for v in (model_cfg.get("api_key"), model_cfg.get("api")) if isinstance(v, str) and v.strip()), "")
  113. requested_norm = (requested_provider or "").strip().lower()
  114. # Aliases resolving to "custom" (ollama, vllm, …) follow bare-custom trust + routing rules.
  115. if requested_norm and requested_norm != "custom" and rp._resolves_to_custom(requested_norm):
  116. requested_norm = "custom"
  117. env_openrouter_base_url = get_secret_str("OPENROUTER_BASE_URL", "").strip()
  118. env_custom_base_url = get_secret_str("CUSTOM_BASE_URL", "").strip()
  119. use_config_base_url = bool(cfg_base_url.strip()) and not explicit_base_url and (
  120. (requested_norm == "auto" and cfg_provider in ("", "auto"))
  121. or (requested_norm == "custom" and rp._config_base_url_trustworthy_for_bare_custom(cfg_base_url, cfg_provider))
  122. # provider: openrouter + base_url in config.yaml is a deliberate mirror/proxy (#10622).
  123. or (requested_norm == "openrouter" and cfg_provider == "openrouter")
  124. )
  125. base_url = ((explicit_base_url or "").strip() or env_custom_base_url or (cfg_base_url.strip() if use_config_base_url else "")
  126. or env_openrouter_base_url or OPENROUTER_BASE_URL).rstrip("/")
  127. # Choose API key based on whether the resolved base_url targets OpenRouter. When hitting OpenRouter,
  128. # prefer OPENROUTER_API_KEY (issue #289). When hitting a custom endpoint (e.g. Z.ai, local LLM), prefer
  129. # OPENAI_API_KEY so the OpenRouter key doesn't leak to an unrelated provider (issues #420, #560).
  130. is_openrouter_url = base_url_host_matches(base_url, "openrouter.ai")
  131. # Explicitly-configured OpenRouter mirrors (OPENROUTER_BASE_URL, or a config.yaml base_url under
  132. # provider: openrouter) still count as OpenRouter for key selection — otherwise the mirror's host
  133. # fails the openrouter.ai match and the generic custom-endpoint branch never selects
  134. # OPENROUTER_API_KEY for it (#10622).
  135. is_openrouter_context = is_openrouter_url or (
  136. requested_norm == "openrouter" and (
  137. (use_config_base_url and cfg_provider == "openrouter" and base_url == cfg_base_url.strip().rstrip("/"))
  138. or ((env_openrouter_base_url or base_url == env_openrouter_base_url)
  139. and base_url == (env_openrouter_base_url or "").rstrip("/"))
  140. )
  141. )
  142. # A bare ``custom`` route to a URL a ``providers:`` entry owns, when that entry declares a credential:
  143. # the entry's key replaces the implicit env keys (on its built-in's host those are another account's).
  144. from hermes_cli.runtime_provider_custom import _model_cfg_key_env_for, _owning_entry_credential
  145. declared, entry_key = _owning_entry_credential(rp, base_url) if requested_norm == "custom" else (False, "")
  146. if is_openrouter_context:
  147. # Same read order as the credential pool and _resolve_api_key_provider_secret
  148. # (.env, then scope-aware os.environ, raw op:// references yielding to the resolved
  149. # scoped value). get_secret_str sees os.environ only, so a key living solely in
  150. # ~/.hermes/.env was lost once the pool entry went exhausted/benched (#117667).
  151. # OPENAI_API_KEY is a legacy home for an OpenRouter key. When OPENAI_BASE_URL binds it, it
  152. # goes only to that origin: another scheme or port on the same host is another endpoint.
  153. # Unbound, openrouter.ai gets it only when it is OpenRouter-shaped (sk-or-), so a real OpenAI
  154. # key never reaches a third party.
  155. from hermes_cli.config import get_env_value_prefer_dotenv
  156. openai_key = get_env_value_prefer_dotenv("OPENAI_API_KEY") or ""
  157. openai_base_url = get_secret_str("OPENAI_BASE_URL", "").strip()
  158. if base_url_hostname(openai_base_url):
  159. openai_origin = base_url_origin(openai_base_url) # empty on a bad port: bound, matches nothing
  160. openai_key_ok = bool(openai_origin[1]) and openai_origin == base_url_origin(base_url)
  161. else:
  162. openai_key_ok = not is_openrouter_url or rp.looks_like_openrouter_key(openai_key)
  163. candidates = [explicit_api_key]
  164. if not declared: # an owning entry's declared credential replaces the implicit env keys
  165. candidates += [get_env_value_prefer_dotenv("OPENROUTER_API_KEY"), openai_key if openai_key_ok else ""]
  166. else:
  167. # ``model.api_key`` and ``model.key_env`` back a trusted config base_url only; the key_env
  168. # rung is what a bare ``provider: custom`` block relies on (#67453).
  169. candidates = [explicit_api_key, (cfg_api_key if use_config_base_url else ""),
  170. (_model_cfg_key_env_for(model_cfg, base_url) if use_config_base_url else ""),
  171. *([] if declared else rp._host_gated_env_key_candidates(base_url, ollama=True))]
  172. api_key = next((str(c or "").strip() for c in candidates if rp.has_usable_secret(c)), "") or entry_key
  173. source = "explicit" if (explicit_api_key or explicit_base_url) else "env/config"
  174. cfg_api_mode = rp._parse_api_mode(model_cfg.get("api_mode"))
  175. # Explicit "custom" stays "custom" rather than relabeling to "openrouter".
  176. if requested_norm != "custom":
  177. return rp._runtime("openrouter", cfg_api_mode or rp._detect_api_mode_for_url(base_url) or "chat_completions", base_url,
  178. api_key, source=source)
  179. # An explicit launch key is the operator's credential for this route and wins over the pool (R2-M1).
  180. if base_url and not rp.has_usable_secret(explicit_api_key):
  181. pool_result = rp._try_resolve_from_custom_pool(base_url, "custom", cfg_api_mode, provider_name=None)
  182. if pool_result:
  183. return pool_result
  184. # Local no-auth servers get a placeholder key — the OpenAI SDK requires a non-empty string.
  185. if not api_key and not is_openrouter_url:
  186. api_key = "no-key-required"
  187. return rp._runtime("custom", rp._resolve_plain_custom_api_mode(model_cfg, base_url), base_url, api_key, source=source)
  188. # ── AWS Bedrock ────────────────────────────────────────────────────────────────────────────
  189. def _resolve_bedrock_runtime(requested_provider: str, model_cfg: dict[str, Any], target_model: Optional[str]) -> dict[str, Any]:
  190. """AWS Bedrock with triple-path routing: bare in-Region OpenAI IDs → Bedrock Mantle's Responses
  191. endpoint (their ``us.``/``global.`` profile IDs are bedrock-runtime IDs and take Converse);
  192. Claude → AnthropicBedrock SDK (prompt caching, thinking budgets); others → Converse API.
  193. AWS_BEARER_TOKEN_BEDROCK auth is unsupported by AnthropicBedrock (SigV4 only), so bearer users
  194. go through Converse regardless of model."""
  195. from agent.bedrock_adapter import (bedrock_openai_base_url, bedrock_openai_uses_mantle, has_aws_credentials,
  196. is_anthropic_bedrock_model, resolve_aws_auth_env_var, resolve_bedrock_bearer_token,
  197. resolve_bedrock_runtime_region, bedrock_guardrail_config)
  198. from hermes_cli.config import load_config # direct (not the origin delegate), as before
  199. rp = _rp()
  200. # Explicitly selected bedrock trusts boto3's credential chain (IMDS, ECS/Lambda roles, SSO)
  201. # which the env-var check can't detect.
  202. is_explicit = requested_provider in {"bedrock", "aws", "aws-bedrock", "amazon-bedrock", "amazon"}
  203. if not is_explicit and not has_aws_credentials():
  204. raise rp.AuthError(
  205. "No AWS credentials found for Bedrock. Configure one of:\n"
  206. " - AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY\n"
  207. " - AWS_PROFILE (for SSO / named profiles)\n"
  208. " - IAM instance role (EC2, ECS, Lambda)\n"
  209. "Or run 'aws configure' to set up credentials.",
  210. code="no_aws_credentials",
  211. )
  212. bedrock_cfg = load_config().get("bedrock", {})
  213. # Region priority (config.yaml bedrock.region → env → us-east-1) lives in the adapter.
  214. region = resolve_bedrock_runtime_region({"bedrock": bedrock_cfg})
  215. auth_source = resolve_aws_auth_env_var() or "aws-sdk-default-chain"
  216. guardrail_config = bedrock_guardrail_config({"bedrock": bedrock_cfg})
  217. current_model = str(target_model or model_cfg.get("default") or "").strip()
  218. has_bearer_token = bool(os.environ.get("AWS_BEARER_TOKEN_BEDROCK", "").strip())
  219. runtime = rp._runtime("bedrock", "bedrock_converse", f"https://bedrock-runtime.{region}.amazonaws.com", "aws-sdk",
  220. source=auth_source, region=region, requested_provider=requested_provider)
  221. if bedrock_openai_uses_mantle(current_model):
  222. bearer = resolve_bedrock_bearer_token()
  223. runtime.update(api_mode="codex_responses", base_url=bedrock_openai_base_url(region), api_key=bearer or "aws-sdk",
  224. source="AWS_BEARER_TOKEN_BEDROCK" if bearer else auth_source, model=current_model, bedrock_openai=True)
  225. elif is_anthropic_bedrock_model(current_model) and not has_bearer_token:
  226. runtime.update(api_mode="anthropic_messages", bedrock_anthropic=True)
  227. if guardrail_config:
  228. runtime["guardrail_config"] = guardrail_config
  229. return runtime
  230. # ── External-process (agent CLI over stdio, e.g. ACP) ──────────────────────────────────────
  231. def _is_external_process_provider(provider: str) -> bool:
  232. """Keyed on the registered provider's auth_type (CLI registry first, then the profile registry
  233. so the check works before the CLI registry has been extended)."""
  234. name = (provider or "").strip().lower()
  235. if not name:
  236. return False
  237. try:
  238. pconfig = _rp().PROVIDER_REGISTRY.get(name)
  239. if pconfig is not None:
  240. return pconfig.auth_type == "external_process"
  241. except Exception:
  242. pass
  243. try:
  244. from providers import get_provider_profile
  245. profile = get_provider_profile(name)
  246. except Exception:
  247. return False
  248. return profile is not None and getattr(profile, "auth_type", "") == "external_process"
  249. def _resolve_external_process_runtime(provider: str, requested_provider: str) -> dict[str, Any]:
  250. rp = _rp()
  251. creds = rp.resolve_external_process_provider_credentials(provider)
  252. return rp._runtime(provider, "chat_completions", creds.get("base_url", "").rstrip("/"), creds.get("api_key", ""),
  253. command=creds.get("command", ""), args=list(creds.get("args") or []),
  254. source=creds.get("source", "process"), requested_provider=requested_provider)