fallback_config.py 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167
  1. """Helpers for reading the effective fallback provider chain from config."""
  2. from __future__ import annotations
  3. import logging
  4. from typing import Any
  5. logger = logging.getLogger(__name__)
  6. def _normalized_base_url(value: Any) -> str:
  7. return value.strip().rstrip("/") if isinstance(value, str) else ""
  8. def _normalize_provider_id(value: str) -> str:
  9. """Collapse provider aliases to the canonical id (lazy to avoid import cycles).
  10. ``opencode-zen`` is the legacy pre-rename id of ``opencode``; ``zen`` is a
  11. short alias. Without normalization, two fallback entries naming the same
  12. backend under different ids are kept as separate slots, shifting the chain
  13. and letting an alias slip past the same-backend skip (#85235).
  14. """
  15. try:
  16. from hermes_cli.providers import normalize_provider
  17. except Exception: # pragma: no cover - import resilience
  18. # Silent degradation: alias collapse is disabled and we fall back to a
  19. # bare lowercase. Log so a future import cycle/refactor can't regress
  20. # the dedup invisibly.
  21. logger.warning(
  22. "fallback provider alias collapse degraded to lowercase: "
  23. "could not import hermes_cli.providers.normalize_provider",
  24. exc_info=True,
  25. )
  26. return value.lower()
  27. return normalize_provider(value)
  28. def resolve_entry_api_key(entry: dict[str, Any] | None) -> str | None:
  29. """API key for one fallback entry: inline ``api_key``, else ``key_env``.
  30. Mirrors the custom-provider convention (``api_key_env`` accepted as alias); None when neither
  31. yields a value so ``resolve_runtime_provider`` falls through to standard credential resolution.
  32. ``key_env`` goes through ``agent.secret_scope.get_secret``, not raw ``os.getenv``: in a
  33. multiplexed gateway a bare env read ignores the active profile's scope and can return another
  34. profile's credential.
  35. """
  36. if not isinstance(entry, dict):
  37. return None
  38. if inline := str(entry.get("api_key") or "").strip():
  39. return inline
  40. if key_env := str(entry.get("key_env") or entry.get("api_key_env") or "").strip():
  41. from agent.secret_scope import get_secret
  42. return (get_secret(key_env) or "").strip() or None
  43. return None
  44. def effective_runtime_provider(
  45. entry: dict[str, Any] | None, runtime: dict[str, Any] | None
  46. ) -> str:
  47. """Provider identity to persist/display for a resolved fallback entry.
  48. ``resolve_runtime_provider`` returns the bare billing class ``"custom"``
  49. for every named ``providers:`` / ``custom_providers:`` entry; the entry's
  50. configured id only survives in ``requested_provider``. Fallback resolvers
  51. that persist ``runtime["provider"]`` as the agent identity therefore label
  52. sessions/billing rows ``custom`` instead of the configured provider name —
  53. while the manual ``/model`` switch path correctly persists the named id
  54. (#98739). Same class as the delegation fix in ``tools/delegate_tool.py``.
  55. Returns the entry's requested identity when the resolved provider is the
  56. bare ``custom`` class; a genuinely ad-hoc endpoint (requested provider IS
  57. ``custom``) keeps the bare class unchanged.
  58. """
  59. runtime = runtime or {}
  60. resolved = str(runtime.get("provider") or "").strip()
  61. if resolved.lower() != "custom":
  62. return resolved
  63. requested = str(
  64. runtime.get("requested_provider")
  65. or (entry or {}).get("provider")
  66. or ""
  67. ).strip()
  68. if requested and requested.lower() != "custom":
  69. return requested
  70. return resolved
  71. def pre_agent_fallback_notice(
  72. primary_provider: Any, primary_model: Any, fallback_provider: Any, fallback_model: Any
  73. ) -> str:
  74. """User-visible one-shot line for a provider switch made during credential resolution, before
  75. any AIAgent exists (#74349). Shared by the messaging gateway, the TUI/Desktop gateway and cron
  76. so the three pre-agent fallback paths cannot drift in wording."""
  77. primary_desc = "/".join(str(p).strip() for p in (primary_provider, primary_model) if p) or "primary"
  78. fallback_desc = "/".join(str(p).strip() for p in (fallback_provider, fallback_model) if p) or "fallback"
  79. return f"⚠️ Provider fallback: {primary_desc} unavailable; using {fallback_desc} for this response."
  80. def _iter_fallback_entries(raw: Any) -> list[dict[str, Any]]:
  81. candidates = [raw] if isinstance(raw, dict) else raw if isinstance(raw, list) else []
  82. entries: list[dict[str, Any]] = []
  83. for entry in candidates:
  84. if not isinstance(entry, dict):
  85. continue
  86. provider = str(entry.get("provider") or "").strip()
  87. model = str(entry.get("model") or "").strip()
  88. if not provider or not model:
  89. continue
  90. normalized = {**entry, "provider": provider, "model": model}
  91. base_url = _normalized_base_url(entry.get("base_url"))
  92. if base_url:
  93. normalized["base_url"] = base_url
  94. entries.append(normalized)
  95. return entries
  96. def _entry_identity(entry: dict[str, Any]) -> tuple[str, str, str]:
  97. return (
  98. _normalize_provider_id(str(entry.get("provider") or "").strip()),
  99. str(entry.get("model") or "").strip().lower(),
  100. _normalized_base_url(entry.get("base_url")).lower(),
  101. )
  102. def get_fallback_chain(config: dict[str, Any] | None) -> list[dict[str, Any]]:
  103. """Return the effective fallback chain merged across old and new config keys.
  104. ``fallback_providers`` remains the primary source of truth and keeps its order. Legacy
  105. ``fallback_model`` entries are appended afterwards unless they target the same
  106. provider/model/base_url route as an earlier entry. The returned list always contains fresh dict
  107. copies.
  108. """
  109. config = config or {}
  110. chain: list[dict[str, Any]] = []
  111. seen: set[tuple[str, str, str]] = set()
  112. for key in ("fallback_providers", "fallback_model"):
  113. for entry in _iter_fallback_entries(config.get(key)):
  114. identity = _entry_identity(entry)
  115. if identity not in seen:
  116. seen.add(identity)
  117. chain.append(entry)
  118. return chain
  119. def scoped_fallback_chain(
  120. inherited: list[dict[str, Any]] | None, declared: Any, *, pinned: bool, owner: str,
  121. ) -> list[dict[str, Any]] | None:
  122. """Fallback chain for a route owner that can pin its own primary (delegated child, cron job).
  123. A pinned owner (explicit provider, endpoint or model) never borrows the *inherited* chain: the
  124. operator chose that route, and a chain entry is a different provider and usually a different
  125. model. Predictability beats liveness for an explicit pin. An unpinned owner inherits the chain
  126. when *declared* is absent/None. An explicit ``[]`` disables fallback either way; any other
  127. *declared* value is the owner's own chain, normalized by :func:`get_fallback_chain` (malformed
  128. entries are dropped; nothing usable left falls back to the pinned/inherited default).
  129. """
  130. default = None if pinned else (inherited or None)
  131. if declared is None:
  132. return default
  133. if declared == []:
  134. return None
  135. normalized = get_fallback_chain({"fallback_providers": declared})
  136. if not normalized:
  137. logger.warning("%s fallback_providers has no usable routes; using the %s default",
  138. owner, "pinned" if pinned else "inherited")
  139. return normalized or default