provider_base.py 2.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566
  1. """Shared base classes for the pluggable-backend provider ABCs.
  2. Every tool-provider ABC shares the same identity + ``hermes tools`` picker surface.
  3. Concrete ABCs subclass :class:`ProviderBase` (or :class:`CatalogProviderBase` when
  4. the backend also exposes a model catalog and is available by default) and add only
  5. their domain methods. Plugins keep subclassing the concrete ABC, so ``isinstance``
  6. checks and abstract-method sets are unchanged.
  7. """
  8. from __future__ import annotations
  9. import abc
  10. from typing import Any, Dict, List, Optional
  11. class ProviderBase(abc.ABC):
  12. """Identity + picker metadata common to every provider ABC."""
  13. @property
  14. @abc.abstractmethod
  15. def name(self) -> str:
  16. """Stable short identifier used as the provider's config-key value.
  17. Lowercase, no spaces (hyphens allowed where they preserve an existing
  18. user-visible name). Registries key providers by this string.
  19. """
  20. @property
  21. def display_name(self) -> str:
  22. """Human-readable label shown in ``hermes tools``. Defaults to ``name``."""
  23. return self.name
  24. def get_setup_schema(self) -> dict[str, Any]:
  25. """Provider row for the ``hermes tools`` picker.
  26. Shape: ``{"name", "badge", "tag", "env_vars": [{"key", "prompt", "url"}, ...]}``
  27. (browser providers may add ``"post_setup"``). Override to expose API key
  28. prompts and badges.
  29. """
  30. return {"name": self.display_name, "badge": "", "tag": "", "env_vars": []}
  31. class CatalogProviderBase(ProviderBase):
  32. """Provider with a model catalog; available by default, ``display_name`` is title-cased."""
  33. @property
  34. def display_name(self) -> str:
  35. """Human-readable label shown in ``hermes tools``. Defaults to ``name.title()``."""
  36. return self.name.title()
  37. def is_available(self) -> bool:
  38. """True when this provider can service calls (API key present, SDK importable).
  39. Must NOT raise and must NOT make network calls — the picker and
  40. ``hermes setup`` call it on every paint.
  41. """
  42. return True
  43. def list_models(self) -> list[dict[str, Any]]:
  44. """Model catalog entries (``{"id": ..., "display": ...}`` + provider-specific keys)."""
  45. return []
  46. def default_model(self) -> Optional[str]:
  47. """Id of the first catalog entry, or None when the catalog is empty."""
  48. models = self.list_models()
  49. return models[0].get("id") if models else None