__init__.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302
  1. """Ramp Router (router.com) provider profile: Responses-only LLM gateway (verified live).
  2. ``api_mode="codex_responses"`` + the ``api.router.com`` host mandate in ``hermes_cli/providers.py``
  3. keep every path on the native wire. The catalog is account-scoped, so no ``fallback_models``
  4. (picker uses ``fetch_models()``). Router 400s on ``reasoning.effort`` levels outside a model's
  5. published vocabulary and on any reasoning field for non-reasoning models, so the efforts map
  6. from ``GET /v1/models`` is cached (memory + disk mirror, background warmer; never HTTP on the
  7. request hot path) and fed to the codex transport's clamp via ``supported_reasoning_efforts``.
  8. """
  9. import contextvars
  10. import json
  11. import logging
  12. import os
  13. import sys
  14. import threading
  15. import time
  16. from pathlib import Path
  17. from typing import Any, Optional
  18. from agent.reasoning_effort import EFFORT_LADDER
  19. from hermes_cli.version_info import hermes_user_agent
  20. from providers import register_provider
  21. from providers.base import LazyHeaders, ProviderProfile, _profile_user_agent
  22. logger = logging.getLogger(__name__)
  23. ROUTER_DEFAULT_BASE_URL = "https://api.router.com/v1"
  24. #: model id -> accepted effort levels. ``[]`` = model accepts NO reasoning
  25. #: fields; absent = unknown (callers keep their defaults).
  26. _efforts_cache: Optional[dict[str, list[str]]] = None
  27. _efforts_lock = threading.Lock()
  28. _warm_started = False
  29. _disk_checked = False
  30. class _CacheState:
  31. """Efforts cache + once-only flags for one Hermes home (same names as the module slots)."""
  32. __slots__ = ("_disk_checked", "_efforts_cache", "_warm_started")
  33. def __init__(self) -> None:
  34. self._efforts_cache: Optional[dict[str, list[str]]] = None
  35. self._warm_started = False
  36. self._disk_checked = False
  37. # The catalog is account-scoped and the disk mirror lives under each profile's home, so under a
  38. # multiplexed profile override the memory cache and its once-only flags are per home too;
  39. # otherwise profile B's clamp would be built from profile A's key (and A's warm/disk flags).
  40. _state_by_home: dict[str, _CacheState] = {}
  41. def _state() -> Any:
  42. """Holder of ``_efforts_cache``/``_warm_started``/``_disk_checked``: this module when unscoped
  43. (tests monkeypatch those slots), else the active home's ``_CacheState``."""
  44. from hermes_constants import get_hermes_home_override, hermes_home_key
  45. if get_hermes_home_override() is None:
  46. return sys.modules[__name__]
  47. with _efforts_lock:
  48. return _state_by_home.setdefault(hermes_home_key(), _CacheState())
  49. def _base_url() -> str:
  50. """Router base URL: profile ``.env`` first (scope-aware), plain os.environ as the fallback."""
  51. try:
  52. from hermes_cli.config import get_env_value_prefer_dotenv as prefer_dotenv
  53. except Exception:
  54. prefer_dotenv = None
  55. for resolve in filter(None, (prefer_dotenv, os.environ.get)):
  56. try:
  57. value = str(resolve("RAMP_ROUTER_BASE_URL") or "").strip().rstrip("/")
  58. except Exception:
  59. value = ""
  60. if value:
  61. return value
  62. return ROUTER_DEFAULT_BASE_URL
  63. def _resolve_api_key() -> str:
  64. """Router key (documented var, then alias), preferring dotenv; plain os.environ
  65. is the fallback when the dotenv resolver is unavailable or raises."""
  66. try:
  67. from hermes_cli.config import get_env_value_prefer_dotenv as prefer_dotenv
  68. except Exception:
  69. prefer_dotenv = None
  70. for resolve in filter(None, (prefer_dotenv, os.environ.get)):
  71. for var in ("RAMP_ROUTER_API_KEY", "ROUTER_API_KEY"):
  72. try:
  73. value = str(resolve(var) or "").strip()
  74. except Exception:
  75. value = ""
  76. if value:
  77. return value
  78. return ""
  79. def _dig(obj: Any, *keys: str) -> Any:
  80. """Nested dict lookup; None as soon as a level is missing or not a dict."""
  81. for key in keys:
  82. obj = obj.get(key) if isinstance(obj, dict) else None
  83. return obj
  84. def _parse_efforts(items: Any) -> Optional[dict[str, list[str]]]:
  85. """Parse a ``/v1/models`` ``data`` array into the efforts map (None if unusable).
  86. Ladder-unknown levels are dropped: clamp_effort ignores them, so an all-unknown
  87. vocabulary would pass the effort through unclamped to a Router 400. ``supported=True``
  88. with no recognized level leaves the model out (unknown -> transport default clamp).
  89. """
  90. if not isinstance(items, list):
  91. return None
  92. efforts_by_id: dict[str, list[str]] = {}
  93. for item in items:
  94. mid = str(item.get("id") or "").strip() if isinstance(item, dict) else ""
  95. reasoning = _dig(item, "router", "capabilities", "reasoning")
  96. if not mid or not isinstance(reasoning, dict):
  97. continue
  98. if reasoning.get("supported") is False:
  99. efforts_by_id[mid] = []
  100. continue
  101. values = [str(e.get("value") or "").strip() for e in reasoning.get("efforts") or [] if isinstance(e, dict)]
  102. levels = [v for v in values if v]
  103. unknown = [level for level in levels if level not in EFFORT_LADDER]
  104. if unknown:
  105. logger.info(
  106. "router: model %s publishes unrecognized reasoning effort level(s) %s; ignoring them "
  107. "(update agent/reasoning_effort EFFORT_LADDER to adopt new vendor tiers)", mid, unknown,
  108. )
  109. levels = [level for level in levels if level in EFFORT_LADDER]
  110. if levels:
  111. efforts_by_id[mid] = levels
  112. return efforts_by_id or None
  113. def _disk_path() -> Optional[Path]:
  114. try:
  115. from hermes_constants import get_hermes_home
  116. return get_hermes_home() / "cache" / "router_catalog.json"
  117. except Exception:
  118. return None
  119. def _save_disk(efforts_by_id: dict[str, list[str]]) -> None:
  120. path = _disk_path()
  121. if path is None:
  122. return
  123. try:
  124. path.parent.mkdir(parents=True, exist_ok=True)
  125. tmp = path.with_suffix(".tmp") # write-then-rename keeps readers from seeing a torn file
  126. tmp.write_text(json.dumps({"ts": time.time(), "efforts": efforts_by_id}), encoding="utf-8")
  127. tmp.replace(path)
  128. except Exception as exc:
  129. logger.debug("router: caps disk mirror write failed: %s", exc)
  130. def _load_disk() -> tuple[Optional[dict[str, list[str]]], float]:
  131. """Disk mirror -> (efforts map or None, age in seconds; TTL when ``ts`` is unparseable)."""
  132. path = _disk_path()
  133. if path is None:
  134. return None, 0.0
  135. try:
  136. data = json.loads(path.read_text(encoding="utf-8-sig"))
  137. efforts = data.get("efforts")
  138. if not isinstance(efforts, dict) or not efforts:
  139. return None, 0.0
  140. parsed = {str(mid): [str(lv) for lv in levels] for mid, levels in efforts.items() if isinstance(levels, list)}
  141. try:
  142. age = max(0.0, time.time() - float(data.get("ts") or 0))
  143. except (TypeError, ValueError):
  144. age = float(_DISK_TTL_SECONDS)
  145. return (parsed or None), age
  146. except Exception:
  147. return None, 0.0
  148. def _seed_efforts(items: Any) -> Optional[dict[str, list[str]]]:
  149. """Seed memory + disk caches from a ``/v1/models`` payload."""
  150. parsed = _parse_efforts(items)
  151. if parsed is not None:
  152. state = _state()
  153. with _efforts_lock:
  154. state._efforts_cache = parsed
  155. _save_disk(parsed)
  156. return parsed
  157. def _fetch_catalog_items(*, api_key: str = "", base_url: str = "", timeout: float = 8.0) -> Optional[list]:
  158. """Fetch the raw ``/v1/models`` ``data`` array. None on any failure."""
  159. import urllib.request
  160. from hermes_cli.urllib_security import open_credentialed_url
  161. req = urllib.request.Request((base_url or _base_url()).rstrip("/") + "/models")
  162. key = api_key or _resolve_api_key()
  163. if key:
  164. req.add_header("Authorization", f"Bearer {key}")
  165. req.add_header("Accept", "application/json")
  166. req.add_header("User-Agent", _profile_user_agent()) # Router's WAF rejects the default urllib UA
  167. try:
  168. with open_credentialed_url(req, timeout=timeout) as resp:
  169. data = json.loads(resp.read().decode())
  170. except Exception as exc:
  171. logger.debug("router: catalog fetch failed: %s", exc)
  172. return None
  173. items = data if isinstance(data, list) else data.get("data", [])
  174. return items if isinstance(items, list) else None
  175. def _efforts_cache_only() -> Optional[dict[str, list[str]]]:
  176. """Memory, else the disk mirror (checked once per home). Never HTTP (hot-path safe)."""
  177. state = _state()
  178. with _efforts_lock:
  179. cached = state._efforts_cache
  180. if cached is not None or state._disk_checked:
  181. return cached
  182. state._disk_checked = True
  183. parsed, age = _load_disk()
  184. if parsed is None:
  185. return None
  186. with _efforts_lock:
  187. if state._efforts_cache is None:
  188. state._efforts_cache = parsed
  189. cached = state._efforts_cache
  190. if age >= _DISK_TTL_SECONDS:
  191. _warm_efforts_async()
  192. return cached
  193. def _warm_efforts_async() -> None:
  194. """Refresh the efforts cache in the background, at most once per home.
  195. Skipped under pytest (a mid-suite fetch makes cache state timing-dependent)
  196. and without a key (it would 401; the first authenticated fetch_models() seeds).
  197. """
  198. if os.environ.get("PYTEST_CURRENT_TEST"):
  199. return
  200. state = _state()
  201. with _efforts_lock:
  202. if state._warm_started:
  203. return
  204. state._warm_started = True
  205. if not _resolve_api_key():
  206. return
  207. def _refresh() -> None:
  208. items = _fetch_catalog_items()
  209. if items is not None:
  210. _seed_efforts(items)
  211. try:
  212. # copy_context: the home override / secret scope are ContextVars, so a bare thread would
  213. # fetch with the launch profile's key and mirror into its cache dir.
  214. threading.Thread(
  215. target=contextvars.copy_context().run, args=(_refresh,), name="router-caps-warm", daemon=True,
  216. ).start()
  217. except Exception as exc:
  218. logger.debug("router: caps warmer failed to start: %s", exc)
  219. class RouterProfile(ProviderProfile):
  220. """Ramp Router — Responses-only gateway with catalog-declared efforts."""
  221. def fetch_models(
  222. self, *, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 8.0
  223. ) -> Optional[list[str]]:
  224. """Live, key-scoped catalog; the same payload seeds the caps cache.
  225. Deduped but not sorted: Router's listing order is deliberate presentation."""
  226. items = _fetch_catalog_items(api_key=api_key or "", base_url=base_url or "", timeout=timeout)
  227. if items is None:
  228. return None
  229. _seed_efforts(items)
  230. return list(dict.fromkeys(str(i["id"]) for i in items if isinstance(i, dict) and i.get("id"))) or None
  231. def supported_reasoning_efforts(self, model: Optional[str]) -> Optional[tuple[str, ...]]:
  232. """Catalog-declared effort vocabulary (cache-only; cold cache -> None + warm)."""
  233. mid = str(model or "").strip()
  234. if not mid:
  235. return None
  236. efforts_by_id = _efforts_cache_only()
  237. if efforts_by_id is None:
  238. _warm_efforts_async()
  239. return None
  240. return tuple(efforts_by_id[mid]) if mid in efforts_by_id else None
  241. router = RouterProfile(
  242. name="router", aliases=("ramp-router", "ramp", "router.com"), api_mode="codex_responses",
  243. display_name="Ramp Router",
  244. description="Ramp Router (router.com) — routes each request to the cheapest model that clears your quality bar",
  245. signup_url="https://app.router.com/keys",
  246. env_vars=("RAMP_ROUTER_API_KEY", "ROUTER_API_KEY", "RAMP_ROUTER_BASE_URL"), base_url=_base_url(),
  247. auth_type="api_key",
  248. # Router attributes coding-agent clients by UA prefix; its WAF rejects default UAs.
  249. default_headers=LazyHeaders({"User-Agent": lambda: hermes_user_agent("Hermes-Agent")}),
  250. supports_vision=True, default_aux_model="gpt-5.4-mini",
  251. fallback_models=(), # account-scoped IDs; the picker uses fetch_models()
  252. )
  253. register_provider(router)