Files
kshitijk4poor 10533b43c8 feat(cli): hermes fallback check, fallback-chain readiness without an agent session (#63852)
`hermes fallback check [--live] [--json]` reports, per fallback entry, whether the switch
could use it:

- static (default): the entry resolves through resolve_runtime_provider with the switch's
  own kwargs (fallback_entry_runtime_kwargs), no chain walk, then the session-readiness
  credential predicate. No inference request; plugin installs held.
- --live: one minimal completion per statically ready entry, in parallel, on the client the
  swap itself builds (route_binding.resolve_route_entry_client; Anthropic Messages, Codex
  Responses, Bedrock and ACP on their own wire), shaped by the auxiliary request builder and
  streamed where the provider is stream-only. Never through call_llm, whose recovery ladder
  retries or answers from another provider and would hide a dead entry. SDK retries off, the
  provider's request_timeout_seconds (else 30 s), the aux response shape check. An empty
  answer fails as live_response; a provider-reported model other than the one sent (or a
  dated snapshot of it) fails as model_mismatch, except where the reported id proves nothing
  (adapter wires, Azure, local/private endpoints, router meta-models, Bedrock ARNs).
  ``auto`` and ``moa`` entries are not one fixed route and keep their static verdict.
  run_probes gains ``aws_imds`` so an EC2 instance role counts for a Bedrock probe.
- exit 1 when any entry is not ready; --json carries profile, checked_at and a stable
  per-entry record; credentials are never printed; error and model text are redacted,
  including the entry's own key when it has no recognisable prefix.
- no AIAgent, session, prompt context or fallback notice.

Based on #63914 by @webtecnica, which proposed the command; rebuilt on the existing
resolvers instead of copied alias/env tables and a raw chat-completions POST.

Co-authored-by: webtecnica <75556242+webtecnica@users.noreply.github.com>
2026-11-10 13:36:29 +05:30

32 lines
1.7 KiB
Python

"""``hermes fallback`` subcommand parser."""
from __future__ import annotations
def build_fallback_parser(subparsers) -> None:
"""Attach the ``fallback`` subcommand to ``subparsers``."""
from hermes_cli.fallback_cmd import cmd_fallback
from hermes_cli.subcommands._shared import add_json_flag
fallback_parser = subparsers.add_parser(
"fallback", help="Manage fallback providers (tried when the primary model fails)",
description="Manage the fallback provider chain. Fallback providers are tried "
"in order when the primary model fails with rate-limit, overload, or "
"connection errors. See: "
"https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers")
fallback_subparsers = fallback_parser.add_subparsers(dest="fallback_command")
fallback_subparsers.add_parser(
"list", aliases=["ls"], help="Show the current fallback chain (default when no subcommand)")
fallback_subparsers.add_parser(
"add",
help="Pick a provider + model (same picker as `hermes model`) and append to the chain")
fallback_subparsers.add_parser(
"remove", aliases=["rm"], help="Pick an entry to delete from the chain")
fallback_subparsers.add_parser("clear", help="Remove all fallback entries")
check = fallback_subparsers.add_parser(
"check", help="Check each fallback entry is usable, without starting an agent session (exit 1 if not)")
check.add_argument("--live", action="store_true",
help="Also send one minimal inference request per entry (on that entry's own provider/model)")
add_json_flag(check, "Print the results as JSON")
fallback_parser.set_defaults(func=cmd_fallback)