fallback_cmd.py 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252
  1. """hermes fallback — manage the fallback provider chain (tried in order when the primary fails).
  2. Subcommands: ``list`` (default), ``add`` (same picker as `hermes model`), ``remove``, ``clear``.
  3. """
  4. from __future__ import annotations
  5. import copy
  6. from typing import Any, Dict, List, Optional
  7. from hermes_cli.fallback_config import get_fallback_chain
  8. # Normalized fallback chain (merges legacy ``fallback_model``); always a fresh copy.
  9. _read_chain = get_fallback_chain
  10. _MISSING_ACTIVE_PROVIDER = object()
  11. def _identity(entry: dict[str, Any]):
  12. """BackendIdentity for a ``{provider, model, base_url?}`` entry."""
  13. from agent.backend_identity import BackendIdentity
  14. return BackendIdentity.build(provider=entry.get("provider"), model=entry.get("model"), base_url=entry.get("base_url"))
  15. def _write_chain(config: dict[str, Any], chain: list[dict[str, Any]]) -> None:
  16. """Persist the chain to ``fallback_providers``; drop the legacy key so there is one source of truth."""
  17. config["fallback_providers"] = chain
  18. config.pop("fallback_model", None)
  19. def _format_entry(entry: dict[str, Any]) -> str:
  20. """One-line human-readable rendering of a fallback entry."""
  21. base = entry.get("base_url")
  22. return f"{entry.get('model', '?')} (via {entry.get('provider', '?')}){f' [{base}]' if base else ''}"
  23. def _extract_fallback_from_model_cfg(model_cfg: Any) -> Optional[dict[str, Any]]:
  24. """Pull the ``{provider, model, base_url?, api_mode?}`` dict from a ``config["model"]`` snapshot."""
  25. if not isinstance(model_cfg, dict):
  26. return None
  27. provider = (model_cfg.get("provider") or "").strip()
  28. model = (model_cfg.get("default") or model_cfg.get("model") or "").strip() # the picker writes ``model.default``
  29. if not provider or not model:
  30. return None
  31. entry: dict[str, Any] = {"provider": provider, "model": model}
  32. entry.update({key: value for key in ("base_url", "api_mode") if (value := (model_cfg.get(key) or "").strip())})
  33. return entry
  34. def _snapshot_auth_active_provider() -> Any:
  35. """Return the current ``active_provider`` in auth.json."""
  36. from hermes_cli.auth import _auth_store_lock, _load_auth_store
  37. with _auth_store_lock():
  38. store = _load_auth_store()
  39. return store.get("active_provider", _MISSING_ACTIVE_PROVIDER)
  40. def _restore_auth_active_provider(value: Any) -> None:
  41. """Write back a previously snapshotted ``active_provider`` value."""
  42. from hermes_cli.auth import _auth_store_lock, _load_auth_store, _save_auth_store
  43. with _auth_store_lock():
  44. store = _load_auth_store()
  45. if value is _MISSING_ACTIVE_PROVIDER:
  46. store.pop("active_provider", None)
  47. else:
  48. store["active_provider"] = value
  49. _save_auth_store(store)
  50. def _restore_model_cfg(model_before: Any) -> None:
  51. """Restore ``config["model"]`` to a previously-captured snapshot."""
  52. from hermes_cli.config import load_config, save_config
  53. cfg = load_config()
  54. cfg.pop("model", None)
  55. if model_before is not None:
  56. cfg["model"] = copy.deepcopy(model_before)
  57. save_config(cfg)
  58. def _restore_primary_route(model_before: Any, active_provider_before: Any) -> None:
  59. """Attempt both halves of temporary picker-route restoration."""
  60. errors: list[BaseException] = []
  61. try:
  62. _restore_model_cfg(model_before)
  63. except BaseException as exc:
  64. errors.append(exc)
  65. try:
  66. _restore_auth_active_provider(active_provider_before)
  67. except BaseException as exc:
  68. errors.append(exc)
  69. if errors:
  70. details = "; ".join(str(exc) for exc in errors)
  71. raise RuntimeError(f"Could not fully restore the primary route: {details}") from errors[0]
  72. def _entries(n: int) -> str:
  73. return f"{n} {'entry' if n == 1 else 'entries'}"
  74. def _print_chain(heading: str, chain: list[dict[str, Any]]) -> None:
  75. print(f" {heading} ({_entries(len(chain))}):")
  76. print("".join(f" {i}. {_format_entry(entry)}\n" for i, entry in enumerate(chain, 1)))
  77. def _load_chain(empty_message: str):
  78. """Load config + chain; print ``empty_message`` block and return ``(config, None)`` when empty."""
  79. from hermes_cli.config import load_config
  80. config = load_config()
  81. chain = _read_chain(config)
  82. if not chain:
  83. print(f"\n{empty_message}\n")
  84. return config, chain or None
  85. def _describe_primary(config: dict[str, Any]) -> Optional[str]:
  86. """One-line description of the primary model for display purposes."""
  87. model_cfg = config.get("model")
  88. if isinstance(model_cfg, dict):
  89. provider = (model_cfg.get("provider") or "?").strip() or "?"
  90. model = (model_cfg.get("default") or model_cfg.get("model") or "?").strip() or "?"
  91. return f"{model} (via {provider})"
  92. return model_cfg.strip() or None if isinstance(model_cfg, str) else None
  93. def cmd_fallback_list(args) -> None:
  94. """Print the current fallback chain."""
  95. config, chain = _load_chain(" No fallback providers configured.")
  96. if chain is None:
  97. print(" Add one with: hermes fallback add\n")
  98. return
  99. print()
  100. if primary := _describe_primary(config):
  101. print(f" Primary: {primary}\n")
  102. _print_chain("Fallback chain", chain)
  103. print(" Tried in order when the primary fails (rate-limit, 5xx, connection errors).")
  104. print(" Docs: https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers\n")
  105. def cmd_fallback_add(args) -> None:
  106. """Launch the same picker as `hermes model`, then append the selection to the chain."""
  107. from hermes_cli.main import _require_tty, select_provider_and_model
  108. from hermes_cli.config import load_config, save_config
  109. _require_tty("fallback add")
  110. # Snapshot BEFORE the picker runs; both route stores must be restored on every exit path.
  111. model_before = copy.deepcopy(load_config().get("model"))
  112. active_provider_before = _snapshot_auth_active_provider()
  113. print("\n Adding a fallback provider. The picker below is the same one used by\n"
  114. " `hermes model` — select the provider + model you want as a fallback.\n")
  115. try:
  116. select_provider_and_model(args=args)
  117. after_cfg = load_config()
  118. model_after = after_cfg.get("model")
  119. new_entry = _extract_fallback_from_model_cfg(model_after)
  120. except BaseException as picker_error:
  121. try:
  122. _restore_primary_route(model_before, active_provider_before)
  123. except Exception as restore_error:
  124. picker_error.add_note(
  125. "Could not fully restore the primary route after fallback "
  126. f"selection failed: {restore_error}"
  127. )
  128. raise
  129. # From here onward no identity/import/append failure can strand the temporary picker route.
  130. _restore_primary_route(model_before, active_provider_before)
  131. if not new_entry:
  132. print("\n No fallback added.")
  133. return
  134. from agent.backend_identity import same_deployment
  135. new_ident = _identity(new_entry)
  136. primary_entry = _extract_fallback_from_model_cfg(model_before)
  137. if primary_entry and same_deployment(_identity(primary_entry), new_ident):
  138. print(f"\n Selected model matches the current primary ({_format_entry(new_entry)}).")
  139. print(" A provider cannot be a fallback for itself — no change.")
  140. return
  141. # Reload after primary restoration; picker-created providers/credentials remain.
  142. final_cfg = load_config()
  143. chain = _read_chain(final_cfg)
  144. if any(same_deployment(_identity(existing), new_ident) for existing in chain):
  145. print(f"\n {_format_entry(new_entry)} is already in the fallback chain — skipped.")
  146. return
  147. chain.append(new_entry)
  148. _write_chain(final_cfg, chain)
  149. save_config(final_cfg)
  150. print(f"\n Added fallback: {_format_entry(new_entry)}")
  151. print(f" Chain is now {_entries(len(chain))} long.\n")
  152. print(" Run `hermes fallback list` to view, or `hermes fallback remove` to delete.")
  153. def cmd_fallback_remove(args) -> None:
  154. """Pick an entry from the chain and remove it."""
  155. from hermes_cli.config import save_config
  156. config, chain = _load_chain(" No fallback providers configured — nothing to remove.")
  157. if chain is None:
  158. return
  159. # The curses menu owns its own non-TTY guard and numbered fallback; -1 means cancelled.
  160. from hermes_cli.setup import _curses_prompt_choice
  161. idx = _curses_prompt_choice("Select a fallback to remove:", [_format_entry(e) for e in chain] + ["Cancel"], 0)
  162. if idx is None or idx < 0 or idx >= len(chain):
  163. print("\n Cancelled — no change.")
  164. return
  165. removed = chain.pop(idx)
  166. _write_chain(config, chain)
  167. save_config(config)
  168. print(f"\n Removed fallback: {_format_entry(removed)}")
  169. print(f" Chain is now {_entries(len(chain))} long.\n" if chain else " Fallback chain is now empty.\n")
  170. def cmd_fallback_clear(args) -> None:
  171. """Remove all fallback entries (with confirmation)."""
  172. from hermes_cli.config import save_config
  173. config, chain = _load_chain(" No fallback providers configured — nothing to clear.")
  174. if chain is None:
  175. return
  176. print()
  177. _print_chain("Current fallback chain", chain)
  178. try:
  179. resp = input(" Clear all entries? [y/N]: ").strip().lower()
  180. except (KeyboardInterrupt, EOFError):
  181. print("\n Cancelled.")
  182. return
  183. if resp not in {"y", "yes"}:
  184. print(" Cancelled — no change.")
  185. return
  186. _write_chain(config, [])
  187. save_config(config)
  188. print("\n Fallback chain cleared.\n")
  189. def cmd_fallback(args) -> None:
  190. """Top-level dispatcher for ``hermes fallback [subcommand]``."""
  191. sub = getattr(args, "fallback_command", None)
  192. handler = _SUBCOMMANDS.get(sub)
  193. if handler is None:
  194. print(f"Unknown fallback subcommand: {sub}")
  195. print("Use one of: list, add, remove, clear")
  196. raise SystemExit(2)
  197. handler(args)
  198. _SUBCOMMANDS = {
  199. **dict.fromkeys((None, "", "list", "ls"), cmd_fallback_list), "add": cmd_fallback_add,
  200. **dict.fromkeys(("remove", "rm"), cmd_fallback_remove), "clear": cmd_fallback_clear,
  201. }