reasoning_effort.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. """Canonical reasoning-effort vocabulary and wire clamping.
  2. Hermes' internal effort ladder (``VALID_REASONING_EFFORTS`` plus ``none``) is wider than any
  3. single provider wire accepts; hand-rolled per-transport maps leaked new levels (``ultra``) to
  4. wires that 400 and inverted the ladder (unknown → weak default). Single source of truth:
  5. :data:`EFFORT_LADDER` (low→high), :func:`clamp_effort` (verbatim if supported, else the
  6. nearest WEAKER level; only when nothing weaker exists the weakest supported), and named
  7. wire-vocabulary constants so call sites declare data. Rules: wire shape stays local, only the
  8. vocabulary math lives here; unset stays unset (never invent an effort); when a provider
  9. rejects a level fix its declared set, never a predicate.
  10. """
  11. from __future__ import annotations
  12. import re
  13. from typing import Optional, Sequence
  14. #: Matches ``k3`` as a delimited token (``k3``, ``k3-256k``, ``kimi-k3-cot``), never K2-era names (``kimi-k2.6``).
  15. # From #76427 by @ruizanthony.
  16. _KIMI_K3_SLUG_RE = re.compile(r"(?:^|[^a-z0-9])k3(?:[^a-z0-9]|$)")
  17. # Canonical low→high ordering for nearest-level clamping. Includes "none" so an explicit
  18. # disable can be clamped when a provider publishes it as a level. ``ultra`` is Hermes-internal
  19. # (the Codex product tier): no wire accepts it, every declared set stops at ``max``.
  20. EFFORT_LADDER: tuple[str, ...] = ("none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra")
  21. #: Widest OpenAI-compatible wire vocabulary (OpenRouter, Nous Portal).
  22. OPENAI_COMPAT_WIRE_EFFORTS: tuple[str, ...] = ("none", "minimal", "low", "medium", "high", "xhigh", "max")
  23. #: OpenAI/Codex Responses per model generation (live-verified): ``minimal`` is rejected by
  24. #: both (clamps to low); ``max`` is gpt-5.6 / gpt-6-tier only (legacy = 5.5 and older).
  25. CODEX_GPT56_EFFORTS: tuple[str, ...] = ("none", "low", "medium", "high", "xhigh", "max")
  26. CODEX_LEGACY_EFFORTS: tuple[str, ...] = ("none", "low", "medium", "high", "xhigh")
  27. # GPT-6 Astra is account-gated and its Responses API accepts no disable/minimal
  28. # wire level; callers normalize those requests to ``low`` at the transport boundary.
  29. CODEX_ASTRA_EFFORTS: tuple[str, ...] = ("low", "medium", "high", "xhigh", "max")
  30. ASTRA_MODEL_IDS: frozenset[str] = frozenset({"gpt-6-astra", "gpt-6-astra-900k"})
  31. #: GPT-6 Sol/Terra/Luna (the 5.6 successors; ``-pro``/``-900k``/dated snapshots share the prefix).
  32. GPT6_TIER_PREFIXES: tuple[str, ...] = ("gpt-6-sol", "gpt-6-luna")
  33. #: GPT-6.1 Sol takes Astra's ``low..max`` ladder (``none`` 400s, live 2026-09-29) without Astra's
  34. #: account gating, so it stays in the static catalogs.
  35. NO_DISABLE_TIER_PREFIXES: tuple[str, ...] = ("gpt-6.1-sol",)
  36. DAYBREAK_MODEL_IDS: frozenset[str] = frozenset(
  37. {"gpt-daybreak-blue-latest", "gpt-daybreak-blue-latest-900k"}
  38. )
  39. #: xAI Responses — Grok 4.6+ accepts xhigh; older Grok tops out at high.
  40. XAI_GROK46_EFFORTS: tuple[str, ...] = ("low", "medium", "high", "xhigh")
  41. XAI_LEGACY_EFFORTS: tuple[str, ...] = ("low", "medium", "high")
  42. def grok_supported_efforts(model: Optional[str]) -> tuple[str, ...]:
  43. """Selectable xAI Responses levels; unknown models have no effort dial.
  44. Grok 4.7 accepts the same xhigh ladder as 4.6:
  45. https://docs.x.ai/developers/model-capabilities/text/reasoning
  46. """
  47. from agent.model_metadata import grok_supports_reasoning_effort, is_grok_46_family
  48. if not grok_supports_reasoning_effort(model or ""):
  49. return ()
  50. name = (model or "").strip().lower().rsplit("/", 1)[-1]
  51. extended = is_grok_46_family(model or "") or name == "grok-4.7" or name.startswith("grok-4.7-")
  52. return XAI_GROK46_EFFORTS if extended else XAI_LEGACY_EFFORTS
  53. #: Actual Computer relays (SGLang/vLLM).
  54. ACTUAL_RELAY_EFFORTS: tuple[str, ...] = ("none", "low", "medium", "high", "max")
  55. #: Moonshot/Kimi K3 (server default high) vs K2-era models. K3 quirks: ``high`` is K3's
  56. #: positional middle AND server default, so ``medium`` rounds to it rather than down to
  57. #: ``low``; ``xhigh`` rounds up to ``max`` (K3's top tier).
  58. KIMI_K3_EFFORTS: tuple[str, ...] = ("low", "high", "max")
  59. KIMI_K2_EFFORTS: tuple[str, ...] = ("low", "medium", "high")
  60. KIMI_K3_OVERRIDES: dict[str, str] = {"medium": "high", "xhigh": "max"}
  61. #: OpenCode "Ox Alpha" (x-preview-f-free): thinking cannot be disabled and the wire accepts
  62. #: exactly low/high/max (medium/none/xhigh 400); xhigh rounds up.
  63. OX_ALPHA_EFFORTS: tuple[str, ...] = ("low", "high", "max")
  64. OX_ALPHA_OVERRIDES: dict[str, str] = {"xhigh": "max"}
  65. #: Tencent TokenHub / Nebius Token Factory / Upstage Solar: plain three-level knobs.
  66. TOKENHUB_EFFORTS: tuple[str, ...] = ("low", "medium", "high")
  67. NEBIUS_EFFORTS: tuple[str, ...] = ("low", "medium", "high")
  68. SOLAR_EFFORTS: tuple[str, ...] = ("low", "medium", "high")
  69. #: GLM-5.2 native knob: exactly ``high`` (its minimum thinking level) and ``max``; GLM-5.3
  70. #: widens it to a graded scale (live-verified, monotonic). ``xhigh`` requests the top tier.
  71. GLM52_EFFORTS: tuple[str, ...] = ("high", "max")
  72. GLM52_OVERRIDES: dict[str, str] = {"xhigh": "max"}
  73. # : GLM-5.3 widens the knob to a graded low/medium/high/max scale — verified : live on
  74. # api.z.ai/api/coding/paas/v4 (issue #91789, 2026-08-21): every : level accepted with monotonic
  75. # reasoning-token scaling (low=4, medium=11, : high=98, max=125 on the probe prompt).
  76. GLM53_EFFORTS: tuple[str, ...] = ("low", "medium", "high", "max")
  77. GLM53_OVERRIDES: dict[str, str] = {"xhigh": "max"}
  78. #: DeepSeek V4 OpenAI-compat endpoint; ``xhigh`` requests the top tier.
  79. DEEPSEEK_V4_EFFORTS: tuple[str, ...] = ("low", "medium", "high", "max")
  80. DEEPSEEK_V4_OVERRIDES: dict[str, str] = {"xhigh": "max"}
  81. #: Ollama Cloud /v1/chat/completions: rejects ``minimal`` with HTTP 400.
  82. OLLAMA_CLOUD_EFFORTS: tuple[str, ...] = ("none", "low", "medium", "high", "max")
  83. OLLAMA_CLOUD_OVERRIDES: dict[str, str] = {"xhigh": "max"}
  84. #: Meta Model API (Muse): rejects ``none``.
  85. META_AI_EFFORTS: tuple[str, ...] = ("minimal", "low", "medium", "high", "xhigh")
  86. #: Gemini 4 (``gemini-4-argon``) ``thinkingLevel``: thinking cannot be disabled, ``minimal`` and
  87. #: ``thinkingBudget`` 400 (live on Vertex global, 2026-10-13).
  88. GEMINI4_THINKING_LEVELS: tuple[str, ...] = ("low", "medium", "high")
  89. def is_astra_model(model: Optional[str]) -> bool:
  90. """``gpt-6-astra`` or its Hermes-side ``-900k`` picker alias, with or without a ``vendor/`` prefix.
  91. The single home for the slug set: picker gating, effort vocabulary and the request sanitizer all
  92. key off it, so a new Astra alias is one edit."""
  93. return (model or "").strip().lower().rsplit("/", 1)[-1] in ASTRA_MODEL_IDS
  94. def codex_supported_efforts(model: Optional[str]) -> tuple[str, ...]:
  95. """Supported effort set for an OpenAI/Codex Responses model."""
  96. bare = (model or "").strip().lower().rsplit("/", 1)[-1]
  97. if is_astra_model(model) or bare.startswith(NO_DISABLE_TIER_PREFIXES):
  98. return CODEX_ASTRA_EFFORTS
  99. return (
  100. CODEX_GPT56_EFFORTS
  101. if "gpt-5.6" in bare or bare.startswith(GPT6_TIER_PREFIXES) or bare in DAYBREAK_MODEL_IDS
  102. else CODEX_LEGACY_EFFORTS
  103. )
  104. def kimi_supported_efforts(model: Optional[str]) -> tuple[str, ...]:
  105. """Supported effort set for a Moonshot/Kimi slug (bare ``k3``, ``k3-256k``, ``kimi-k3*`` → K3).
  106. K3 is served as the bare slug ``k3``, plan variants like ``k3-256k``, and the ``kimi-k3*`` aliases; its
  107. documented set is low/high/max. Everything earlier speaks low/medium/high. Boundary-matched so K2-era
  108. names (``kimi-k2.6``) never match (detection regex from #76427 by @ruizanthony).
  109. """
  110. m = (model or "").strip().lower().split("/")[-1]
  111. return KIMI_K3_EFFORTS if _KIMI_K3_SLUG_RE.search(m) else KIMI_K2_EFFORTS
  112. def clamp_effort(
  113. effort: Optional[str], supported: Optional[Sequence[str]], overrides: Optional[dict[str, str]] = None,
  114. ) -> Optional[str]:
  115. """Clamp a requested reasoning effort onto a wire's supported levels.
  116. ``overrides`` (a declared vendor mapping, e.g. Kimi K3 ``medium → high``) is consulted
  117. first. Otherwise the request passes through unchanged when it is supported, when the
  118. supported set is unknown/empty, or when it isn't a recognized ladder level (custom
  119. providers may use bespoke names). Else the **nearest weaker** supported level is returned
  120. so a clamp never escalates cost; when nothing weaker exists, the weakest supported level
  121. (the provider's floor is the closest honest match). Monotonic: a stronger request never
  122. resolves weaker than a weaker request would.
  123. """
  124. requested = str(effort or "").strip().lower()
  125. if not requested or not supported:
  126. return effort
  127. supported_norm = [lvl for lvl in (str(s).strip().lower() for s in supported) if lvl in EFFORT_LADDER]
  128. if not supported_norm or requested in supported_norm:
  129. return effort
  130. if overrides and overrides.get(requested) in supported_norm:
  131. return overrides[requested]
  132. if requested not in EFFORT_LADDER:
  133. return effort
  134. # "none" disables reasoning — never a degradation target for an enabled ask
  135. # (clamping "minimal" to "none" would silently switch thinking off).
  136. candidates = [level for level in supported_norm if level != "none"]
  137. if not candidates:
  138. return effort
  139. requested_idx = EFFORT_LADDER.index(requested)
  140. below = [level for level in candidates if EFFORT_LADDER.index(level) < requested_idx]
  141. return max(below, key=EFFORT_LADDER.index) if below else min(candidates, key=EFFORT_LADDER.index)
  142. def route_supported_efforts(
  143. provider: Optional[str], model: Optional[str], api_mode: Optional[str] = None,
  144. ) -> tuple[str, ...]:
  145. """Levels the (provider, model) route's ENTRY clamp accepts: the Codex/OpenAI Responses set per
  146. model generation, else the widest OpenAI-compatible vocabulary (narrower providers clamp again
  147. downstream, never upward). On the Codex app-server runtime ``ultra`` is codex's own harness mode,
  148. accepted wherever the model's ladder reaches ``max`` (codex runs it at ``max``; a model without
  149. ``max`` rejects it), so it is sent verbatim there."""
  150. if (provider or "").strip().lower() == "openai-codex":
  151. supported = codex_supported_efforts(model)
  152. return (*supported, "ultra") if api_mode == "codex_app_server" and "max" in supported else supported
  153. return OPENAI_COMPAT_WIRE_EFFORTS
  154. def effort_display_label(
  155. effort: Optional[str], provider: Optional[str] = None, model: Optional[str] = None,
  156. api_mode: Optional[str] = None,
  157. ) -> str:
  158. """Picker / ``/reasoning`` status label for a ladder level: the level itself when the route sends
  159. it verbatim, else ``"<level> (sends <clamped> on this route)"`` so a Hermes-internal step such as
  160. ``ultra`` (#61634) is never presented as a distinct wire level the route does not have."""
  161. requested = str(effort or "").strip().lower()
  162. clamped = clamp_effort(requested, route_supported_efforts(provider, model, api_mode))
  163. return requested if not requested or clamped == requested else f"{requested} (sends {clamped} on this route)"
  164. def requested_effort(reasoning_config: Optional[dict]) -> Optional[str]:
  165. """The user's explicit effort, or None (absent/malformed config, no effort, or reasoning
  166. disabled) — callers then omit the wire field."""
  167. if not isinstance(reasoning_config, dict) or reasoning_config.get("enabled") is False:
  168. return None
  169. return str(reasoning_config.get("effort") or "").strip().lower() or None
  170. def tokenhub_effort(requested: Optional[str]) -> str:
  171. """TokenHub's top-level ``reasoning_effort``: ``high`` when no level was chosen, else the
  172. request clamped to low/medium/high. Shared by the tencent-tokenhub profile and the host-based
  173. branch base_url-only agents take; callers handle thinking-off themselves."""
  174. return "high" if requested is None else clamp_effort(requested, TOKENHUB_EFFORTS)
  175. def generic_nested_reasoning(reasoning_config: Optional[dict]) -> dict:
  176. """The OpenAI-compatible ``extra_body`` fallback for a route whose profile declares no
  177. reasoning shape: ``{}`` with no config, ``{"reasoning": {"enabled": False}}`` when disabled,
  178. else ``{"reasoning": {"enabled": True, "effort": <effort or medium>}}``. Used by auxiliary
  179. calls, and by a profile hook that wants that fallback (``handles_reasoning`` skips it for any
  180. profile overriding ``build_api_kwargs_extras``)."""
  181. if not reasoning_config or not isinstance(reasoning_config, dict):
  182. return {}
  183. if reasoning_config.get("enabled") is False:
  184. return {"reasoning": {"enabled": False}}
  185. return {"reasoning": {"enabled": True, "effort": reasoning_config.get("effort") or "medium"}}
  186. def clamp_reasoning_config(reasoning_config: Optional[dict], supported: Sequence[str] = OPENAI_COMPAT_WIRE_EFFORTS) -> Optional[dict]:
  187. """Return ``reasoning_config`` with its ``effort`` clamped onto ``supported`` (non-dicts and
  188. configs without an effort pass through untouched).
  189. The entry clamp for an OpenAI-compatible chat-completions request builder: Hermes-internal
  190. ``ultra`` never reaches a wire (#89503 main transport, #112010 aux/MoA), while provider
  191. profiles with narrower vocabularies clamp again downstream. Unset stays unset.
  192. """
  193. if not isinstance(reasoning_config, dict):
  194. return reasoning_config
  195. effort = str(reasoning_config.get("effort") or "").strip().lower()
  196. clamped = clamp_effort(effort, supported) if effort else effort
  197. return {**reasoning_config, "effort": clamped} if clamped != effort else reasoning_config
  198. def thinking_toggle_extras(
  199. reasoning_config: Optional[dict],
  200. efforts: Sequence[str],
  201. overrides: Optional[dict[str, str]] = None,
  202. *,
  203. always_emit_toggle: bool = False,
  204. ) -> tuple[dict, dict]:
  205. """Translate a reasoning config onto the Moonshot/DeepSeek chat_completions wire:
  206. ``extra_body.thinking`` toggle and top-level ``reasoning_effort``.
  207. Moonshot 400s when both are sent, so by default the effort (when it lands in
  208. ``efforts``) replaces the toggle. DeepSeek instead requires the toggle on every
  209. request (an omitted toggle defaults thinking on and then demands
  210. ``reasoning_content`` echoes), hence ``always_emit_toggle``. A requested effort of
  211. ``none`` is not a level on these wires; it falls back to the plain toggle.
  212. """
  213. if isinstance(reasoning_config, dict) and reasoning_config.get("enabled") is False:
  214. return {"thinking": {"type": "disabled"}}, {}
  215. effort = requested_effort(reasoning_config)
  216. clamped = clamp_effort(None if effort == "none" else effort, efforts, overrides)
  217. if clamped in efforts:
  218. return ({"thinking": {"type": "enabled"}} if always_emit_toggle else {}), {"reasoning_effort": clamped}
  219. return {"thinking": {"type": "enabled"}}, {}
  220. # DashScope documents ``preserve_thinking`` (Qwen3.6+ and the Kimi K2.6/K2.7 it hosts) and a
  221. # top-level ``clear_thinking`` (its GLM-5.x) as the switches that make the server KEEP replayed
  222. # prior-turn ``reasoning_content``; without them the replay is accepted and dropped.
  223. # https://www.alibabacloud.com/help/en/model-studio/deep-thinking
  224. _DASHSCOPE_PRESERVE_MODELS = ("qwen3.6", "qwen3.7", "qwen3.8", "kimi-k2.6", "kimi-k2.7")
  225. def dashscope_preserve_thinking_extras(model: Optional[str]) -> dict:
  226. """``extra_body`` keys that keep replayed reasoning on a DashScope-hosted model, else ``{}``."""
  227. m = (model or "").strip().lower()
  228. if any(token in m for token in _DASHSCOPE_PRESERVE_MODELS):
  229. return {"preserve_thinking": True}
  230. if m.startswith("glm-5"):
  231. return {"clear_thinking": False}
  232. return {}
  233. def ox_alpha_reasoning_extras(reasoning_config: Optional[dict], model: Optional[str]) -> tuple[dict, dict]:
  234. """Ox Alpha (``x-preview-f-free``) ``reasoning_effort`` translation for the
  235. opencode-zen profile (low/high/max only; anything else 400s)."""
  236. if (model or "").strip().rsplit("/", 1)[-1].lower() != "x-preview-f-free":
  237. return {}, {}
  238. effort = requested_effort(reasoning_config)
  239. clamped = clamp_effort(None if effort == "none" else effort, OX_ALPHA_EFFORTS, OX_ALPHA_OVERRIDES)
  240. return ({}, {"reasoning_effort": clamped}) if clamped in OX_ALPHA_EFFORTS else ({}, {})