provider_catalog.py 5.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112
  1. """Unified provider catalog — one source of truth for the provider universe.
  2. The provider list shown by ``hermes model`` (CLI/TUI) and the desktop Settings → Providers tabs
  3. (Accounts + API keys) **must be the same set**; providers added after those lists were written
  4. silently went missing from the GUI. ``auth_type`` / ``api_key_env_vars`` / ``base_url_env_var``
  5. come from :data:`hermes_cli.auth.PROVIDER_REGISTRY` (credential truth); ``display_name`` /
  6. ``description`` / ``signup_url`` from the provider's :class:`providers.base.ProviderProfile`, falling
  7. back to the ``CANONICAL_PROVIDERS`` entry's ``label`` / ``tui_desc`` and the ``OPTIONAL_ENV_VARS``
  8. signup URL (many profiles leave these blank, and openai-api, tencent-tokenplan, xai-oauth have no
  9. profile at all — the fallbacks are load-bearing).
  10. """
  11. from __future__ import annotations
  12. from dataclasses import dataclass
  13. # Auth types that authenticate via an account / sign-in flow rather than a pasted API key; these
  14. # route to the desktop "Accounts" tab, everything else (api_key, and aws_sdk configured via
  15. # AWS_REGION/AWS_PROFILE) to "API keys". Mirrors the auth_type strings in PROVIDER_REGISTRY and
  16. # ProviderProfile: external_process = a spawned CLI that owns its own login (e.g. an ACP agent).
  17. _ACCOUNTS_AUTH_TYPES: frozenset[str] = frozenset(
  18. {"oauth_device_code", "oauth_external", "oauth_minimax", "external_process"}
  19. )
  20. @dataclass(frozen=True)
  21. class ProviderDescriptor:
  22. """One provider, as seen by every surface (CLI picker + both GUI tabs)."""
  23. slug: str # canonical id, e.g. "openai-codex"
  24. label: str # human display name
  25. description: str # one-line description
  26. auth_type: str # api_key | oauth_* | external_process | aws_sdk
  27. tab: str # "keys" | "accounts"
  28. api_key_env_vars: tuple[str, ...] # credential env vars (may be empty)
  29. base_url_env_var: str # base-URL override env var (may be "")
  30. signup_url: str # signup / console URL (may be "")
  31. order: int # CANONICAL_PROVIDERS index — mirrors `hermes model`
  32. def tab_for_auth_type(auth_type: str) -> str:
  33. """Return the desktop tab ("keys"|"accounts") a provider's auth maps to."""
  34. return "accounts" if auth_type in _ACCOUNTS_AUTH_TYPES else "keys"
  35. def _is_url_var(name: str) -> bool:
  36. return name.endswith("_BASE_URL") or name.endswith("_URL")
  37. def _split_env_vars(env_vars: tuple[str, ...]) -> tuple[tuple[str, ...], str]:
  38. """Split a profile's ``env_vars`` into (api_key_vars, base_url_var)."""
  39. return tuple(v for v in env_vars if not _is_url_var(v)), next((v for v in env_vars if _is_url_var(v)), "")
  40. def _safe_import(module: str, attr: str, default):
  41. """Import ``attr`` from ``module``; ``default`` on ANY failure — this module is on the import
  42. path of the web server and the CLI, and a provider-plugin import error must never blank the
  43. whole catalog."""
  44. try:
  45. return getattr(__import__(module, fromlist=[attr]), attr)
  46. except Exception:
  47. return default
  48. def provider_catalog() -> list[ProviderDescriptor]:
  49. """One descriptor per provider in the ``hermes model`` universe (:data:`CANONICAL_PROVIDERS`,
  50. auto-extended by provider plugins). Auth/env from ``PROVIDER_REGISTRY``; display metadata from
  51. ``ProviderProfile`` with canonical/env fallbacks so profile-less providers still resolve."""
  52. from hermes_cli.models_catalog_static import listed_canonical_providers
  53. PROVIDER_REGISTRY = _safe_import("hermes_cli.auth", "PROVIDER_REGISTRY", {})
  54. OPTIONAL_ENV_VARS = _safe_import("hermes_cli.config", "OPTIONAL_ENV_VARS", {})
  55. # Overlays carry auth_type for providers with no registry/profile entry — notably the ``moa``
  56. # virtual provider (auth_type "virtual"), which has no credential and no network endpoint.
  57. HERMES_OVERLAYS = _safe_import("hermes_cli.providers", "HERMES_OVERLAYS", {})
  58. try:
  59. from providers import list_providers
  60. profiles = {p.name: p for p in list_providers()}
  61. except Exception:
  62. profiles = {}
  63. out: list[ProviderDescriptor] = []
  64. for order, entry in enumerate(listed_canonical_providers()):
  65. slug = entry.slug
  66. cfg = PROVIDER_REGISTRY.get(slug)
  67. prof = profiles.get(slug)
  68. overlay = HERMES_OVERLAYS.get(slug)
  69. # auth_type: registry is authoritative; then profile, then overlay (moa → "virtual"), then api_key.
  70. auth_type = ((cfg.auth_type if cfg else "") or (prof.auth_type if prof else "")
  71. or (overlay.auth_type if overlay else "") or "api_key")
  72. # Credential env vars: registry first (already normalized), else derived from the profile.
  73. if cfg and cfg.api_key_env_vars:
  74. api_key_vars, base_url_var = tuple(cfg.api_key_env_vars), cfg.base_url_env_var or ""
  75. elif prof and prof.env_vars:
  76. api_key_vars, base_url_var = _split_env_vars(tuple(prof.env_vars))
  77. else:
  78. api_key_vars, base_url_var = (), ""
  79. label = (prof.display_name if prof else "") or entry.label or slug
  80. signup_url = (prof.signup_url if prof else "") or ""
  81. if not signup_url and api_key_vars:
  82. signup_url = (OPTIONAL_ENV_VARS.get(api_key_vars[0]) or {}).get("url") or ""
  83. out.append(
  84. ProviderDescriptor(
  85. slug=slug, label=label, description=(prof.description if prof else "") or entry.tui_desc or label,
  86. auth_type=auth_type, tab=tab_for_auth_type(auth_type), api_key_env_vars=api_key_vars,
  87. base_url_env_var=base_url_var, signup_url=signup_url, order=order,
  88. )
  89. )
  90. return out
  91. def provider_catalog_by_slug() -> dict[str, ProviderDescriptor]:
  92. """Convenience: the catalog keyed by slug."""
  93. return {d.slug: d for d in provider_catalog()}