nous_rate_guard.py 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205
  1. """Cross-session rate limit guard for Nous Portal.
  2. Writes rate limit state to a shared file so all sessions (CLI, gateway, cron,
  3. auxiliary) can check whether Nous Portal is currently rate-limited before making
  4. requests. Without it each 429 fans out into up to 9 calls per turn (3 SDK
  5. retries x 3 Hermes retries), all counted against RPH.
  6. """
  7. from __future__ import annotations
  8. import contextlib
  9. import json
  10. import logging
  11. import os
  12. import time
  13. from typing import Any, Mapping, Optional
  14. from utils import atomic_write_text
  15. from agent.retry_utils import parse_retry_after_seconds
  16. from agent.rate_limit_tracker import (
  17. _BUCKET_TAGS, _fmt_seconds, _safe_float, _safe_int, has_rate_limit_headers, lower_headers,
  18. )
  19. logger = logging.getLogger(__name__)
  20. # Reset windows shorter than this are transient upstream jitter, not a quota
  21. # exhaustion worth a cross-session breaker trip.
  22. _MIN_RESET_FOR_BREAKER_SECONDS = 60.0
  23. # The welcome tier's structured ``rate_limited`` refusal: a reset at or above this is an exhausted
  24. # allowance (stop, tell the user when it refreshes and that signing in lifts it); below it the
  25. # turn simply waits it out. The gateway's fairshare bucket names honest resets from a few seconds
  26. # up to a minute, so the split sits where a quiet wait stops being quiet.
  27. WELCOME_LONG_WAIT_SECONDS = 20.0
  28. format_remaining = _fmt_seconds
  29. def _state_path(*, anonymous: bool = False) -> str:
  30. """Path to the Nous rate limit state file."""
  31. try:
  32. from hermes_constants import get_hermes_home
  33. base = get_hermes_home()
  34. except ImportError:
  35. base = os.path.join(os.path.expanduser("~"), ".hermes")
  36. # Signing in must not inherit the anonymous allowance's cooldown (or clear it for
  37. # another anonymous session). Keep the existing named-account file unchanged.
  38. return os.path.join(base, "rate_limits", "nous-anonymous.json" if anonymous else "nous.json")
  39. def _parse_reset_seconds(headers: Optional[Mapping[str, str]]) -> Optional[float]:
  40. """Best reset estimate (seconds from now) from hourly, per-minute, then retry-after headers."""
  41. lowered = lower_headers(headers)
  42. for key in ("x-ratelimit-reset-requests-1h", "x-ratelimit-reset-requests"):
  43. val = _safe_float(lowered.get(key), 0.0)
  44. if val > 0:
  45. return val
  46. retry_after = parse_retry_after_seconds(lowered.get("retry-after"))
  47. return retry_after if retry_after else None
  48. def record_nous_rate_limit(
  49. *, headers: Optional[Mapping[str, str]] = None, error_context: Optional[dict[str, Any]] = None,
  50. default_cooldown: float = 300.0,
  51. anonymous: bool = False,
  52. ) -> None:
  53. """Record that Nous Portal is rate-limited in the shared state file.
  54. Reset time comes from ``error_context["reset_at"]`` (the 429 body's own wait), then headers, then
  55. ``default_cooldown``. The body wins: a welcome-tier refusal says when to retry (410 s), while the
  56. hourly bucket's reset header is that window's end (about an hour) even with requests left in it.
  57. """
  58. now = time.time()
  59. reset_at = None
  60. if isinstance(error_context, dict):
  61. ctx_reset = error_context.get("reset_at")
  62. if isinstance(ctx_reset, (int, float)) and ctx_reset > now:
  63. reset_at = float(ctx_reset)
  64. if reset_at is None and (header_seconds := _parse_reset_seconds(headers)) is not None:
  65. reset_at = now + header_seconds
  66. if reset_at is None:
  67. reset_at = now + default_cooldown
  68. state = {"reset_at": reset_at, "recorded_at": now, "reset_seconds": reset_at - now}
  69. try:
  70. atomic_write_text(_state_path(anonymous=anonymous), json.dumps(state))
  71. logger.info("Nous rate limit recorded: resets in %.0fs (at %.0f)", reset_at - now, reset_at)
  72. except Exception as exc:
  73. logger.debug("Failed to write Nous rate limit state: %s", exc)
  74. def nous_rate_limit_remaining(*, anonymous: bool = False) -> Optional[float]:
  75. """Seconds remaining until reset, or None if not rate-limited (expired state is removed)."""
  76. path = _state_path(anonymous=anonymous)
  77. try:
  78. with open(path, encoding="utf-8-sig") as f:
  79. state = json.load(f)
  80. remaining = state.get("reset_at", 0) - time.time()
  81. if remaining > 0:
  82. return remaining
  83. with contextlib.suppress(OSError):
  84. os.unlink(path)
  85. return None
  86. except (FileNotFoundError, json.JSONDecodeError, KeyError, TypeError):
  87. return None
  88. def clear_nous_rate_limit(*, anonymous: bool = False) -> None:
  89. """Clear the rate limit state (e.g., after a successful Nous request)."""
  90. try:
  91. os.unlink(_state_path(anonymous=anonymous))
  92. except FileNotFoundError:
  93. pass
  94. except OSError as exc:
  95. logger.debug("Failed to clear Nous rate limit state: %s", exc)
  96. def _is_exhausted(remaining: Optional[int], reset: Optional[float]) -> bool:
  97. """remaining == 0 AND a reset window long enough to be a real quota exhaustion."""
  98. return (
  99. remaining is not None
  100. and remaining <= 0
  101. and reset is not None
  102. and reset >= _MIN_RESET_FOR_BREAKER_SECONDS
  103. )
  104. def is_genuine_nous_rate_limit(
  105. *, headers: Optional[Mapping[str, str]] = None, last_known_state: Optional[Any] = None,
  106. ) -> bool:
  107. """Decide whether a 429 from Nous Portal is a real account rate limit.
  108. Nous multiplexes upstream providers behind one key, so a 429 may be one
  109. upstream model out of capacity (clears in seconds) rather than our quota;
  110. tripping the breaker on that would block every Nous model for minutes.
  111. Only an exhausted bucket (remaining == 0 with reset >= 60s) in the 429's
  112. own headers, or in the last-known-good ``RateLimitState``, is genuine.
  113. """
  114. if _has_exhausted_bucket(_parse_buckets_from_headers(headers)):
  115. return True
  116. return last_known_state is not None and _has_exhausted_bucket_in_object(last_known_state)
  117. def is_long_welcome_rate_limit(error_context: Any) -> bool:
  118. """True for a Nous welcome-tier ``rate_limited`` refusal whose reset is long enough to be an
  119. exhausted allowance (``WELCOME_LONG_WAIT_SECONDS``), as parsed into ``error_context``
  120. (``welcome_refusal`` from ``hermes_cli.anon_auth.parse_welcome_refusal``). Capacity refusals
  121. (``at_capacity`` / ``admission_closed``) are never this: they are retried in place."""
  122. if not isinstance(error_context, dict):
  123. return False
  124. refusal = error_context.get("welcome_refusal")
  125. if not isinstance(refusal, dict) or refusal.get("reason") != "rate_limited":
  126. return False
  127. return _safe_float(refusal.get("retry_after"), 0.0) >= WELCOME_LONG_WAIT_SECONDS
  128. def welcome_refusal_from_headers(
  129. headers: Optional[Mapping[str, str]], *, body_wait: Optional[float] = None,
  130. ) -> dict[str, Any]:
  131. """A free-tier 429 that carried no structured ``reason``, read from its headers (else the wait
  132. its body named) into the ``parse_welcome_refusal`` shape. Long wait or an empty bucket =
  133. ``rate_limited``; a short or unexplained one = ``at_capacity``. A missing wait stays 0 so the
  134. breaker never trips on a guess."""
  135. buckets = _parse_buckets_from_headers(headers).values()
  136. # Only an empty bucket's reset is a wait; a healthy bucket's reset is just its window end.
  137. exhausted_wait = max((reset for remaining, reset in buckets
  138. if remaining is not None and remaining <= 0 and (reset or 0) > 0), default=None)
  139. wait = (exhausted_wait or parse_retry_after_seconds(lower_headers(headers).get("retry-after"))
  140. or body_wait or 0.0)
  141. empty = any(remaining is not None and remaining <= 0 for remaining, _reset in buckets)
  142. reason = "rate_limited" if wait >= WELCOME_LONG_WAIT_SECONDS or empty else "at_capacity"
  143. return {"reason": reason, "retry_after": max(0, int(wait)), "alternates": [], "upgrade_url": ""}
  144. def _parse_buckets_from_headers(
  145. headers: Optional[Mapping[str, str]],
  146. ) -> dict[str, tuple[Optional[int], Optional[float]]]:
  147. """(remaining, reset_seconds) per bucket from x-ratelimit-* headers ({} if none)."""
  148. lowered = lower_headers(headers)
  149. if not has_rate_limit_headers(lowered):
  150. return {}
  151. result: dict[str, tuple[Optional[int], Optional[float]]] = {}
  152. for _attr, tag in _BUCKET_TAGS:
  153. remaining = _safe_int(lowered.get(f"x-ratelimit-remaining-{tag}"), None)
  154. reset = _safe_float(lowered.get(f"x-ratelimit-reset-{tag}"), None)
  155. if remaining is not None or reset is not None:
  156. result[tag] = (remaining, reset)
  157. return result
  158. def _has_exhausted_bucket(buckets: Mapping[str, tuple[Optional[int], Optional[float]]]) -> bool:
  159. return any(_is_exhausted(remaining, reset) for remaining, reset in buckets.values())
  160. def _has_exhausted_bucket_in_object(state: Any) -> bool:
  161. """Check a RateLimitState-like object (duck-typed; missing attrs are skipped)."""
  162. for attr, _tag in _BUCKET_TAGS:
  163. bucket = getattr(state, attr, None)
  164. if bucket is None or (getattr(bucket, "limit", 0) or 0) <= 0:
  165. continue
  166. remaining = getattr(bucket, "remaining", 0) or 0
  167. reset = getattr(bucket, "remaining_seconds_now", None)
  168. if reset is None:
  169. reset = getattr(bucket, "reset_seconds", 0.0) or 0.0
  170. if _is_exhausted(remaining, reset):
  171. return True
  172. return False