plan_limits.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. """Usage-window plans: what a limit blocks, and what to offer instead.
  2. One rule decides everywhere, so the picker's "used up" note, the limit card's suggestion and the switch
  3. button can never disagree:
  4. * a free model is never blocked;
  5. * a full gauge with scope ``all`` (day / week / month / any new one) blocks every paid model;
  6. * a full ``top_tier`` gauge blocks the models the gateway marks top tier.
  7. Hermes never switches model on its own. When a request is refused, :func:`limit_hit` describes the
  8. limit and names up to two models from the plan's recommended list (in order) that still
  9. work. Each surface renders that as buttons where it already has them, otherwise as a sentence.
  10. Everything here reads cached data only (credits headers, the portal account snapshot, the cached
  11. catalog) and never raises: a failure means "no suggestion".
  12. """
  13. from __future__ import annotations
  14. import logging
  15. from dataclasses import dataclass
  16. from typing import Any, Iterable, Optional
  17. logger = logging.getLogger(__name__)
  18. PROVIDER = "nous"
  19. # Leave room for the reply: a suggestion must fit the conversation with this many tokens to spare.
  20. _CONTEXT_HEADROOM_TOKENS = 8_000
  21. _MAX_SUGGESTIONS = 2
  22. NOTE_FREE = "free"
  23. NOTE_INCLUDED = "included"
  24. # Past a limit, the credits step (:func:`credits_action`).
  25. USE_CREDITS = "use_credits" # Keep going off, balance: turn it on
  26. ADD_CREDITS = "add_credits" # Keep going on/unknown, no balance: top up
  27. ADD_CREDITS_AND_KEEP_GOING = "add_credits_and_keep_going" # Keep going off, no balance: both
  28. @dataclass(frozen=True)
  29. class ModelSuggestion:
  30. model: str # routed id, e.g. "example/model-a"
  31. label: str # display name ("Model A"), the id when the catalog has none
  32. note: str # NOTE_FREE | NOTE_INCLUDED
  33. provider: str = PROVIDER
  34. def to_payload(self) -> dict[str, str]:
  35. return {"model": self.model, "label": self.label, "note": self.note, "provider": self.provider}
  36. @dataclass(frozen=True)
  37. class CreditsOption:
  38. """The second way on, past a limit: spend top-up credits (the action comes from :func:`credits_action`).
  39. Interactive surfaces render it as a button; messaging points at the Portal (a chat button could spend
  40. the owner's money for anyone in the room)."""
  41. action: str # USE_CREDITS | ADD_CREDITS | ADD_CREDITS_AND_KEEP_GOING
  42. def to_payload(self) -> dict[str, str]:
  43. return {"action": self.action}
  44. @dataclass(frozen=True)
  45. class LimitHit:
  46. gauge_id: str # day | week | month | top_tier | <server id>
  47. scope: str # all | top_tier
  48. limit_name: str # "daily" / "weekly" / "monthly large-model" / the server label
  49. resets_at_ms: Optional[int]
  50. message: str # the limit sentence (the server's display_message wins)
  51. suggestions: tuple[ModelSuggestion, ...] = ()
  52. credits: Optional[CreditsOption] = None
  53. current_model: str = ""
  54. def to_payload(self) -> dict[str, Any]:
  55. return {
  56. "gauge_id": self.gauge_id, "scope": self.scope, "limit_name": self.limit_name,
  57. "resets_at_ms": self.resets_at_ms, "message": self.message,
  58. "suggestions": [s.to_payload() for s in self.suggestions],
  59. "credits": self.credits.to_payload() if self.credits else None,
  60. "current_model": self.current_model,
  61. }
  62. # ── catalog reads ────────────────────────────────────────────────────────────────────────────────
  63. def cached_pricing(base_url: str = "") -> dict:
  64. """The calling profile's own cached Nous catalog (never fetches); ``base_url`` is not needed for it. Only
  65. the profile-keyed read: a process serving several profiles holds their catalogs side by side, and a
  66. usage level (Large / Free) is per plan, so another profile's catalog must never answer."""
  67. try:
  68. from hermes_cli.models_pricing import get_pricing_for_provider
  69. return get_pricing_for_provider(PROVIDER, cached_only=True) or {}
  70. except Exception:
  71. logger.debug("Cached pricing unavailable", exc_info=True)
  72. return {}
  73. def _billed_elsewhere(model: str, pricing: Optional[dict]) -> bool:
  74. try:
  75. from hermes_cli.models import _is_subscription_billed
  76. return _is_subscription_billed((pricing or {}).get(model))
  77. except Exception:
  78. logger.debug("Subscription billing lookup failed", exc_info=True)
  79. return False
  80. def is_free(model: str, pricing: Optional[dict]) -> bool:
  81. """$0 to the plan: a ``:free`` id or a row the catalog lists as free."""
  82. if not model:
  83. return False
  84. if model.endswith(":free"):
  85. return True
  86. try:
  87. from hermes_cli.models import _is_model_free
  88. return bool(pricing) and _is_model_free(model, pricing)
  89. except Exception:
  90. logger.debug("Free-model lookup failed", exc_info=True)
  91. return False
  92. def is_top_tier(model: str, pricing: Optional[dict]) -> bool:
  93. """The gateway marks the model top tier (``usage_level: top_tier``, or an older gateway's ``top_tier:
  94. true``), read by the same rule as the picker tags. Unmarked or no catalog: not top tier."""
  95. if not model:
  96. return False
  97. try:
  98. from hermes_cli.model_picker_usage import usage_levels
  99. return usage_levels([model], pricing).get(model) == "top_tier"
  100. except Exception:
  101. logger.debug("Usage level lookup failed", exc_info=True)
  102. return False
  103. def model_label(model: str, pricing: Optional[dict]) -> str:
  104. entry = (pricing or {}).get(model)
  105. name = entry.get("name") if isinstance(entry, dict) else None
  106. return name.strip() if isinstance(name, str) and name.strip() else model
  107. # ── the one rule ─────────────────────────────────────────────────────────────────────────────────
  108. def blocking_gauge(model: str, gauges: Iterable[Any], *, free: bool, top_tier: bool) -> Optional[Any]:
  109. """The full gauge that stops *model*, or None while it still has included room. Free models are
  110. never blocked. Of several full gauges, the one that frees up last (that is when the model works)."""
  111. if free:
  112. return None
  113. from agent.usage_gauges import SCOPE_ALL, SCOPE_TOP_TIER
  114. full = [g for g in gauges
  115. if getattr(g, "full", False) and (g.scope == SCOPE_ALL or (g.scope == SCOPE_TOP_TIER and top_tier))]
  116. return max(full, key=lambda g: g.resets_at_ms or 0) if full else None
  117. def current_model_is_top_tier(agent: Any) -> Optional[bool]:
  118. """*agent*'s current model is top tier, by its own profile's cached catalog (see :func:`is_top_tier`), or
  119. None when the catalog has no row for it (cold, or its 300 s cache lapsed): the tier is unknown."""
  120. model = str(getattr(agent, "model", "") or "")
  121. return _top_tier_mark(model, cached_pricing(str(getattr(agent, "base_url", "") or "")))
  122. def _top_tier_mark(model: str, pricing: Optional[dict]) -> Optional[bool]:
  123. return is_top_tier(model, pricing) if model in (pricing or {}) or is_free(model, pricing) else None
  124. def is_blocked(model: str, gauges: Iterable[Any], pricing: Optional[dict]) -> bool:
  125. return blocking_gauge(model, gauges, free=is_free(model, pricing),
  126. top_tier=is_top_tier(model, pricing)) is not None
  127. # ── suggestions ──────────────────────────────────────────────────────────────────────────────────
  128. def _plan_usage() -> Any:
  129. # Plan shape only (featured models), so the last account snapshot at any age answers: the 60s
  130. # cache has long lapsed by the time a window runs out mid-session.
  131. try:
  132. from hermes_cli.model_picker_usage import nous_picker_usage
  133. return nous_picker_usage(any_age=True)
  134. except Exception:
  135. logger.debug("Plan usage unavailable", exc_info=True)
  136. return None
  137. def _portal_free_models() -> list[str]:
  138. """The Portal's free picks, from what this profile already holds for its own Portal (in-process,
  139. else its last copy on disk). Never fetches: this runs mid-turn."""
  140. try:
  141. from hermes_cli import models as m
  142. base = m._resolve_nous_portal_url()
  143. payload = (m._nous_recommended_cache.get((m._pricing_profile_key(), base)) or (None,))[0]
  144. if not payload:
  145. disk = m._read_nous_recommended_disk(base)
  146. payload = disk[0] if disk else None
  147. entries = payload.get("freeRecommendedModels") if isinstance(payload, dict) else None
  148. return [n for e in (entries or []) if (n := m._extract_model_name(e))]
  149. except Exception:
  150. logger.debug("Portal free models unavailable", exc_info=True)
  151. return []
  152. def _fits_context(model: str, needed_tokens: Optional[int], base_url: str) -> bool:
  153. if not needed_tokens or needed_tokens <= 0:
  154. return True
  155. try:
  156. from agent.model_metadata import get_model_context_length
  157. ctx = get_model_context_length(model, base_url=base_url, provider=PROVIDER)
  158. return not ctx or ctx >= needed_tokens + _CONTEXT_HEADROOM_TOKENS
  159. except Exception:
  160. logger.debug("Context length lookup failed", exc_info=True)
  161. return True
  162. def suggest_models(
  163. current_model: str, gauges: Iterable[Any], *, pricing: Optional[dict] = None, featured: Iterable[str] = (),
  164. needed_tokens: Optional[int] = None, base_url: str = "", limit: int = _MAX_SUGGESTIONS,
  165. ) -> tuple[ModelSuggestion, ...]:
  166. """The plan's recommended models (in order) that the full gauges do not block, then the Portal's free picks.
  167. Never the current model, only a model whose context window holds the conversation."""
  168. gauges = tuple(gauges)
  169. pool = [m for m in featured if isinstance(m, str) and m]
  170. pool += [m for m in _portal_free_models() if m not in pool]
  171. out: list[ModelSuggestion] = []
  172. for model in pool:
  173. if model == current_model or _billed_elsewhere(model, pricing):
  174. continue
  175. if is_blocked(model, gauges, pricing) or not _fits_context(model, needed_tokens, base_url):
  176. continue
  177. out.append(ModelSuggestion(model=model, label=model_label(model, pricing),
  178. note=NOTE_FREE if is_free(model, pricing) else NOTE_INCLUDED))
  179. if len(out) >= limit:
  180. break
  181. return tuple(out)
  182. def credits_action(keep_going_on_credits: Optional[bool], purchased_micros: Optional[int]) -> str:
  183. """The credits step past a limit; every surface's copy reads this one rule. With Keep going on credits
  184. off, the gateway refuses whatever the balance, so a balance alone is not enough and neither is the
  185. setting alone: off with no balance needs both steps. An unknown balance counts as none."""
  186. has_balance = int(purchased_micros or 0) > 0
  187. if keep_going_on_credits is False:
  188. return USE_CREDITS if has_balance else ADD_CREDITS_AND_KEEP_GOING
  189. return ADD_CREDITS
  190. def credits_option(state: Any) -> Optional[CreditsOption]:
  191. """How credits could carry on past the limit (see :func:`credits_action`). None while paused (a card
  192. update restores included usage; the paused copy says so)."""
  193. if state is None or getattr(state, "paused_reason", None):
  194. return None
  195. return CreditsOption(credits_action(getattr(state, "keep_going_on_credits", None),
  196. getattr(state, "purchased_micros", 0)))
  197. def limit_hit(agent: Any, *, message: str, needed_tokens: Optional[int] = None) -> Optional[LimitHit]:
  198. """After a usage-window 402: which limit stopped *agent*'s current model, when it resets, and what to
  199. offer. None when the state names no full gauge for this model (a paused plan, a stale snapshot)."""
  200. try:
  201. state = getattr(agent, "_credits_state", None)
  202. if state is None or not getattr(state, "is_usage_window", False):
  203. return None
  204. model = str(getattr(agent, "model", "") or "")
  205. base_url = str(getattr(agent, "base_url", "") or "")
  206. pricing = cached_pricing(base_url)
  207. gauges = tuple(getattr(state, "gauges", ()) or ())
  208. # A model the cached catalog has no row for may be top tier: count its full top-tier gauge too, so
  209. # the card never names an earlier reset than the one that frees it.
  210. g = blocking_gauge(model, gauges, free=is_free(model, pricing), top_tier=_top_tier_mark(model, pricing) is not False)
  211. if g is None:
  212. # The 402 says this model was refused; without a top-tier mark in the cache a full top-tier
  213. # gauge is still the only explanation.
  214. from agent.usage_gauges import top_tier_gauge
  215. top = top_tier_gauge(gauges)
  216. g = top if top is not None and top.full else None
  217. if g is None:
  218. return None
  219. from agent.usage_gauges import gauge_limit_name
  220. usage = _plan_usage()
  221. featured = tuple(getattr(usage, "featured_model_ids", ()) or ())
  222. return LimitHit(
  223. gauge_id=g.id, scope=g.scope, limit_name=gauge_limit_name(g), resets_at_ms=g.resets_at_ms,
  224. message=message, current_model=model, credits=credits_option(state),
  225. suggestions=suggest_models(model, gauges, pricing=pricing, featured=featured,
  226. needed_tokens=needed_tokens, base_url=base_url),
  227. )
  228. except Exception:
  229. logger.debug("plan limits: limit_hit failed", exc_info=True)
  230. return None
  231. # ── copy ─────────────────────────────────────────────────────────────────────────────────────────
  232. def portal_wording(text: str) -> str:
  233. """A refusal line for a surface without ``/topup`` (messaging): point its credits steps at the Portal."""
  234. return (text.replace("turn on Keep going in /topup", "turn on Keep going in the Portal")
  235. .replace("(turn on in /topup)", "(turn on in the Portal)")
  236. .replace("/topup to add credits", "add credits in the Portal")
  237. .replace("add credits in /topup", "add credits in the Portal"))
  238. def chat_refusal_wording(text: str, resets_at: Any = None) -> str:
  239. """A refusal sent to a chat: credits steps point at the Portal (:func:`portal_wording`), and the reset
  240. reads as a duration ("resets in 3h"), since the gateway's clock is not the reader's time zone."""
  241. text = portal_wording(text)
  242. if isinstance(resets_at, (int, float)) and not isinstance(resets_at, bool) and resets_at > 0:
  243. try:
  244. from agent.credits_tracker import format_window_reset
  245. from hermes_cli.model_picker_usage import compact_duration
  246. ms = round(resets_at * 1000) # the epoch seconds came from these ms: round, never truncate
  247. if left := compact_duration(ms):
  248. text = text.replace(f"resets {format_window_reset(ms)}", f"resets in {left}")
  249. except Exception:
  250. logger.debug("chat reset wording failed", exc_info=True)
  251. return text
  252. def suggestion_phrase(s: ModelSuggestion) -> str:
  253. """``Model A (free)``."""
  254. return f"{s.label} ({s.note})"
  255. def next_steps_text(hit: LimitHit, *, model_command: str = "/model", topup_command: Optional[str] = "/topup",
  256. portal: bool = False) -> str:
  257. """One line on how to keep going, for a surface without buttons. ``model_command`` is the platform's
  258. own spelling (e.g. ``!model``). ``portal``: point at the Portal for credits (messaging),
  259. instead of a command that would spend from the chat."""
  260. parts: list[str] = []
  261. if hit.suggestions:
  262. parts.append(f"Switch to {suggestion_phrase(hit.suggestions[0])} with {model_command}")
  263. else:
  264. parts.append(f"Pick another model with {model_command}")
  265. if hit.credits is not None:
  266. where = "the Portal" if portal or not topup_command else topup_command
  267. if hit.credits.action == USE_CREDITS:
  268. parts.append(f"turn on Keep going in {where} to use credits")
  269. elif hit.credits.action == ADD_CREDITS_AND_KEEP_GOING:
  270. parts.append(f"add credits and turn on Keep going in {where}")
  271. else:
  272. parts.append(f"add credits {'in' if where == 'the Portal' else 'with'} {where}")
  273. return ", or ".join(parts) + "."
  274. def limit_next_steps_from_payload(limit: dict, *, model_command: str = "/model", topup_command: Optional[str] = "/topup",
  275. portal: bool = False, markup: bool = False) -> str:
  276. """:func:`next_steps_text` for a :meth:`LimitHit.to_payload` dict (what the result carries). ``markup``
  277. bolds the commands for a Rich panel."""
  278. sug = [ModelSuggestion(model=str(s.get("model") or ""), label=str(s.get("label") or s.get("model") or ""),
  279. note=str(s.get("note") or NOTE_INCLUDED))
  280. for s in (limit.get("suggestions") or []) if isinstance(s, dict) and s.get("model")]
  281. credits = limit.get("credits") if isinstance(limit.get("credits"), dict) else None
  282. hit = LimitHit(gauge_id=str(limit.get("gauge_id") or ""), scope=str(limit.get("scope") or ""),
  283. limit_name=str(limit.get("limit_name") or ""), resets_at_ms=limit.get("resets_at_ms"),
  284. message=str(limit.get("message") or ""), suggestions=tuple(sug),
  285. credits=CreditsOption(str(credits.get("action"))) if credits and credits.get("action") else None)
  286. if markup:
  287. model_command, topup_command = f"[bold]{model_command}[/]", (f"[bold]{topup_command}[/]" if topup_command else None)
  288. return next_steps_text(hit, model_command=model_command, topup_command=topup_command, portal=portal)