model_selection_guards.py 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180
  1. """Unified selection-time guard registry for model switching surfaces.
  2. Guard modules (``model_cost_guard``, ``model_data_policy_guard``) keep their public APIs — existing
  3. tests and mock patch points remain valid; this module only aggregates them.
  4. """
  5. from __future__ import annotations
  6. from dataclasses import dataclass
  7. from typing import Iterable, List, Optional
  8. from agent.models_dev import ModelInfo
  9. @dataclass(frozen=True)
  10. class SelectionWarning:
  11. """A selection-time warning a surface must confirm before applying."""
  12. kind: str # "cost" | "data_policy" | "context_cache" | future guard kinds
  13. title: str
  14. model: str
  15. provider: str
  16. message: str
  17. @dataclass(frozen=True)
  18. class SelectionContext:
  19. """Live-session facts a surface threads into the registry. Model-only guards (cost, data-policy)
  20. ignore it; guards about the *switch itself* (context-cache) need the size of the conversation at
  21. stake and the model it is currently on. Surfaces without a live agent omit it and those guards
  22. stay silent."""
  23. context_tokens: Optional[int] = None
  24. current_model: Optional[str] = None
  25. def selection_context_for_agent(agent: object) -> Optional[SelectionContext]:
  26. """:class:`SelectionContext` from a live ``AIAgent``.
  27. Uses the compressor's measured ``last_prompt_tokens`` (what the provider billed
  28. on the latest turn). ``session_prompt_tokens`` is a lifetime sum and is not live
  29. occupancy, so it is not a fallback (#126343). ``None`` when no positive
  30. measurement exists — the guard stays silent rather than guess."""
  31. if agent is None:
  32. return None
  33. try:
  34. cc = getattr(agent, "context_compressor", None)
  35. tokens = int(getattr(cc, "last_prompt_tokens", 0) or 0) if cc else 0
  36. except Exception:
  37. tokens = 0
  38. if tokens <= 0:
  39. return None
  40. return SelectionContext(context_tokens=tokens, current_model=getattr(agent, "model", "") or None)
  41. def _wrap(kind: str, title: str, warning, model_name: str, provider: Optional[str]):
  42. """Lift a raw guard payload into a :class:`SelectionWarning` (None passes through). Duck-typed:
  43. payloads may carry only ``.message``."""
  44. if warning is None:
  45. return None
  46. return SelectionWarning(
  47. kind=kind, title=title, model=getattr(warning, "model", model_name),
  48. provider=getattr(warning, "provider", provider or ""), message=warning.message)
  49. def _cost_guard(
  50. model_name: str, provider: Optional[str], base_url: Optional[str], api_key: Optional[str],
  51. model_info: Optional[ModelInfo], ctx: Optional[SelectionContext] = None) -> Optional[SelectionWarning]:
  52. from hermes_cli.model_cost_guard import expensive_model_warning
  53. warning = expensive_model_warning(
  54. model_name, provider=provider, base_url=base_url, api_key=api_key, model_info=model_info)
  55. return _wrap("cost", "Expensive Model Warning", warning, model_name, provider)
  56. def _data_policy_guard(
  57. model_name: str, provider: Optional[str], base_url: Optional[str], api_key: Optional[str],
  58. model_info: Optional[ModelInfo], ctx: Optional[SelectionContext] = None) -> Optional[SelectionWarning]:
  59. from hermes_cli.model_data_policy_guard import data_training_warning
  60. warning = data_training_warning(model_name, provider=provider, base_url=base_url)
  61. return _wrap("data_policy", "Data-Training Tier Warning", warning, model_name, provider)
  62. # Context-token threshold above which a mid-session switch asks for confirmation: providers key
  63. # prompt caches per model, so the first call after a switch re-reads the whole context uncached.
  64. DEFAULT_CONTEXT_CACHE_SWITCH_THRESHOLD = 100_000
  65. def _context_cache_threshold() -> int:
  66. """``model.switch_context_confirm_tokens`` from config.yaml (0 disables), else the default."""
  67. try:
  68. from hermes_cli.config import load_config
  69. model_cfg = (load_config() or {}).get("model", {})
  70. raw = model_cfg.get("switch_context_confirm_tokens") if isinstance(model_cfg, dict) else None
  71. if raw is not None:
  72. return max(0, int(raw))
  73. except Exception:
  74. pass
  75. return DEFAULT_CONTEXT_CACHE_SWITCH_THRESHOLD
  76. def _context_cache_guard(
  77. model_name: str, provider: Optional[str], base_url: Optional[str], api_key: Optional[str],
  78. model_info: Optional[ModelInfo], ctx: Optional[SelectionContext] = None) -> Optional[SelectionWarning]:
  79. """Confirm a mid-session switch that abandons a large cached context. Fires only when the surface
  80. supplied live facts showing the active context at/above the threshold; smaller sessions, sessions
  81. with no measured size and same-model re-selects (cache stays warm) are silent."""
  82. if ctx is None or not ctx.context_tokens:
  83. return None
  84. target = (model_name or "").strip()
  85. current = (ctx.current_model or "").strip()
  86. if not target or (current and target == current):
  87. return None
  88. threshold = _context_cache_threshold()
  89. tokens = int(ctx.context_tokens)
  90. if threshold <= 0 or tokens < threshold:
  91. return None
  92. message = "\n".join([
  93. "!!! LARGE CONTEXT MODEL SWITCH !!!",
  94. "",
  95. f"This session holds ~{tokens:,} tokens of context.",
  96. f"Switching to {target} makes the next reply re-read all of it uncached (providers key "
  97. "prompt caches per model) — a one-time full-price input cost.",
  98. "",
  99. f"Threshold: model.switch_context_confirm_tokens (currently {threshold:,}; 0 disables this check).",
  100. "Confirm only if you intend to switch now."])
  101. return SelectionWarning(
  102. kind="context_cache", title="Large Context Switch Warning", model=target,
  103. provider=(provider or "").strip(), message=message)
  104. # Registry, evaluated in order. Add new guard classes here — never at the
  105. # individual surfaces.
  106. _GUARDS = (_cost_guard, _data_policy_guard, _context_cache_guard)
  107. def selection_warnings(
  108. model_name: str, *, provider: Optional[str] = None, base_url: Optional[str] = None,
  109. api_key: Optional[str] = None, model_info: Optional[ModelInfo] = None,
  110. include_kinds: Optional[Iterable[str]] = None,
  111. selection_context: Optional[SelectionContext] = None) -> list[SelectionWarning]:
  112. """Warnings from every registered guard (empty in the common case). ``include_kinds`` restricts
  113. which kinds are returned; ``selection_context`` carries live-session facts for switch-aware guards.
  114. Guard exceptions are swallowed — never break model selection."""
  115. wanted = set(include_kinds) if include_kinds is not None else None
  116. results: list[SelectionWarning] = []
  117. for guard in _GUARDS:
  118. try:
  119. warning = guard(model_name, provider, base_url, api_key, model_info, selection_context)
  120. except Exception:
  121. continue
  122. if warning is not None and (wanted is None or warning.kind in wanted):
  123. results.append(warning)
  124. return results
  125. def combined_message(warnings: list[SelectionWarning]) -> str:
  126. """One confirm-prompt body for several warnings (one prompt beats two sequential ones)."""
  127. return "\n\n".join(w.message for w in warnings)
  128. def combined_selection_warning(
  129. model_name: str, *, provider: Optional[str] = None, base_url: Optional[str] = None,
  130. api_key: Optional[str] = None, model_info: Optional[ModelInfo] = None,
  131. selection_context: Optional[SelectionContext] = None,
  132. ) -> Optional[SelectionWarning]:
  133. """Drop-in for ``expensive_model_warning`` call sites: ``None``, the single warning, or a merged
  134. ``kind="multiple"`` warning stacking every message."""
  135. warnings = selection_warnings(
  136. model_name, provider=provider, base_url=base_url, api_key=api_key, model_info=model_info,
  137. selection_context=selection_context)
  138. if not warnings:
  139. return None
  140. if len(warnings) == 1:
  141. return warnings[0]
  142. return SelectionWarning(
  143. kind="multiple", title="Model Selection Warning", model=warnings[0].model,
  144. provider=warnings[0].provider, message=combined_message(warnings))