reasoning_params.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265
  1. """Provider reasoning-parameter policy for ``AIAgent``.
  2. When ``reasoning`` extra_body is safe to send, LM Studio / Ollama / endpoint-profile capability probes,
  3. ``reasoning_content`` echo families, and strict-API tool-call sanitising.
  4. Extracted from ``run_agent.py``; every method resolves through ``AIAgent``'s MRO unchanged.
  5. """
  6. import logging
  7. import time
  8. from agent.lazy_forward import forward as _forward, forward_static as _forward_static
  9. from agent.message_sanitization import matches_reasoning_echo_family
  10. from utils import base_url_host_matches
  11. # Static OpenRouter fallback when the live /v1/models capability cache is cold.
  12. _OPENROUTER_REASONING_PREFIXES = (
  13. "deepseek/", "anthropic/", "openai/", "x-ai/", "google/gemini-2", "google/gemma-4",
  14. "qwen/qwen3", "tencent/hy", "xiaomi/",
  15. )
  16. # Hosts whose reasoning gate core owns: a plugin claiming one in ``hostnames`` never replaces it.
  17. _CORE_REASONING_GATED_HOSTS = ("nousresearch.com", "ai-gateway.vercel.sh", "ollama.com")
  18. # Probe results cache per (model, base_url). Definitive values cache permanently; an
  19. # "unknown" value (empty list / None) caches 60s so a transient failure neither sticks
  20. # for the session nor round-trips every turn.
  21. _PROBE_TTL_S = 60
  22. def _cached_probe(agent, cache_attr: str, probe, unknown, definitive):
  23. """``probe(model, base_url, api_key)`` once per (model, base_url); ``unknown`` is what a raising probe
  24. yields, ``definitive(value)`` decides permanent vs 60s TTL."""
  25. cache = getattr(agent, cache_attr, None)
  26. if cache is None:
  27. cache = {}
  28. setattr(agent, cache_attr, cache)
  29. key = (agent.model, agent.base_url)
  30. cached = cache.get(key)
  31. if cached is not None:
  32. value, ts = cached
  33. if definitive(value) or (time.monotonic() - ts) < _PROBE_TTL_S:
  34. return value
  35. try:
  36. value = probe(agent.model, agent.base_url, getattr(agent, "api_key", ""))
  37. except Exception:
  38. value = unknown
  39. cache[key] = (value, time.monotonic())
  40. return value
  41. def unset_reasoning_default(agent) -> dict | None:
  42. """Reasoning config for a main-loop request whose ``agent.reasoning_effort`` is unset.
  43. Asks the active provider profile (``ProviderProfile.default_reasoning_config``; the custom /
  44. OpenAI-compatible profile answers medium) so a route's own default never silently applies —
  45. kimi-k3 behind a relay defaults to ``max``, 3x the reasoning tokens of medium. Resolved at
  46. request time, so ``/model`` and fallback activation re-evaluate it. None keeps the field off
  47. the wire: a non chat-completions transport, a profile without a default (those decide inside
  48. ``build_api_kwargs_extras``), a model the catalog / ``model_overrides`` mark
  49. ``supports_reasoning: false``, or a local Ollama model whose ``/api/show`` lacks ``thinking``.
  50. """
  51. if getattr(agent, "api_mode", None) != "chat_completions":
  52. return None
  53. provider = str(getattr(agent, "provider", "") or "")
  54. model = str(getattr(agent, "model", "") or "")
  55. try:
  56. from providers import get_provider_profile
  57. profile = get_provider_profile(provider)
  58. default = profile.default_reasoning_config(model) if profile is not None else None
  59. except Exception:
  60. return None
  61. if not default:
  62. return None
  63. try:
  64. from agent.models_dev import get_model_capabilities
  65. caps = get_model_capabilities(provider, model, allow_network=False)
  66. except Exception:
  67. caps = None
  68. if caps is not None and caps.supports_reasoning is False:
  69. return None
  70. # ``_ollama_num_ctx`` is only ever set for a server detected as Ollama (agent_init); Ollama
  71. # 400s ``reasoning_effort`` on a model pulled without the thinking capability.
  72. if getattr(agent, "_ollama_num_ctx", None) and not agent._ollama_supports_thinking_cached():
  73. return None
  74. return dict(default)
  75. class ReasoningParamsMixin:
  76. """Reasoning-parameter gating and echo policy (see module docstring)."""
  77. def _supports_reasoning_extra_body(self) -> bool:
  78. """True when reasoning extra_body is safe to send: OpenRouter forwards unknown extra_body upstream and
  79. some routes 400 on ``reasoning``, so gate to known reasoning-capable families and direct Nous Portal."""
  80. url = self._base_url_lower
  81. if base_url_host_matches(url, "nousresearch.com") or base_url_host_matches(url, "ai-gateway.vercel.sh"):
  82. return True
  83. if (profile := self._reasoning_endpoint_profile()) is not None:
  84. # A claimed endpoint gates on its own catalog: reasoning goes out iff it declares a payload.
  85. from agent.provider_route_hooks import ask_profile
  86. return ask_profile(profile, "reasoning_payload", None, self.model, None,
  87. base_url=self.base_url, scope=self) is not None
  88. if (self.provider or "").strip().lower() == "lmstudio":
  89. # "off-only" (or absent) means no real reasoning capability.
  90. return any(opt and opt != "off" for opt in self._lmstudio_reasoning_options_cached())
  91. if base_url_host_matches(url, "ollama.com"):
  92. # Ollama Cloud: /api/show capabilities are authoritative.
  93. return self._ollama_supports_thinking_cached()
  94. if not self._is_openrouter_url() or base_url_host_matches(url, "api.mistral.ai"):
  95. return False
  96. # Live-catalog metadata first (OpenRouter /v1/models supported_parameters) — the static prefix
  97. # allowlist repeatedly went stale one vendor at a time. Unknown falls back to the static list.
  98. try:
  99. from hermes_cli.models_reasoning_caps import openrouter_model_reasoning_capabilities, warm_openrouter_reasoning_caps_async
  100. caps = openrouter_model_reasoning_capabilities(self.model)
  101. if caps is None:
  102. warm_openrouter_reasoning_caps_async() # cache cold — warm in the background, never block
  103. except Exception:
  104. caps = None
  105. if caps is not None:
  106. return bool(caps.get("supports_reasoning"))
  107. model = (self.model or "").lower()
  108. return any(model.startswith(prefix) for prefix in _OPENROUTER_REASONING_PREFIXES)
  109. def _lmstudio_reasoning_options_cached(self) -> list[str]:
  110. """LM Studio's published reasoning ``allowed_options`` (gate + clamp so toggle models don't 400 on ``high``)."""
  111. try:
  112. from hermes_cli.models_local import lmstudio_model_reasoning_options
  113. except Exception:
  114. return []
  115. return _cached_probe(self, "_lm_reasoning_opts_cache", lmstudio_model_reasoning_options, [], bool)
  116. def _ollama_supports_thinking_cached(self) -> bool:
  117. """True only if Ollama's ``/api/show`` declares the ``thinking`` capability."""
  118. try:
  119. from hermes_cli.models_local import ollama_model_supports_thinking
  120. except Exception:
  121. return False
  122. return bool(_cached_probe(self, "_ollama_thinking_cache", ollama_model_supports_thinking, None, lambda v: v is not None))
  123. def _reasoning_endpoint_profile(self):
  124. """The profile claiming this endpoint (``providers.profile_for_host``) that gates its reasoning, or None.
  125. Endpoints core gates itself (Nous Portal, Vercel AI Gateway, LM Studio, Ollama Cloud, OpenRouter) keep
  126. core's gate even when a plugin claims their host for metadata or auxiliary routing."""
  127. url = self._base_url_lower
  128. if ((self.provider or "").strip().lower() == "lmstudio" or self._is_openrouter_url()
  129. or any(base_url_host_matches(url, host) for host in _CORE_REASONING_GATED_HOSTS)):
  130. return None
  131. from providers import profile_for_host
  132. return profile_for_host(str(getattr(self, "base_url", None) or ""))
  133. def _endpoint_reasoning_payload(self) -> dict | None:
  134. """``reasoning_payload`` of the profile gating this endpoint's reasoning for the agent's model and
  135. ``reasoning_config`` (``_reasoning_endpoint_profile``), or None when no profile does."""
  136. base_url = getattr(self, "base_url", None)
  137. profile = self._reasoning_endpoint_profile()
  138. if profile is None:
  139. return None
  140. from agent.provider_route_hooks import ask_profile
  141. return ask_profile(profile, "reasoning_payload", None, self.model, self.reasoning_config,
  142. base_url=str(base_url), scope=self)
  143. def _build_assistant_message(self, assistant_message, finish_reason: str) -> dict:
  144. """``build_assistant_message``; a held turn's row with visible text comes back typed hidden
  145. (``withhold_held_row``) until ``finish_text_response`` publishes it as the final."""
  146. from agent.chat_completion_helpers import build_assistant_message
  147. from agent.stream_delivery import withhold_held_row
  148. return withhold_held_row(self, build_assistant_message(self, assistant_message, finish_reason))
  149. def _reasoning_replay_route(self):
  150. """Reasoning replay decision for the active route (``message_sanitization.reasoning_replay_route``).
  151. Cached per (api_mode, provider, model, base_url, opt-in, rejected keys) — called many times
  152. per turn — and recomputed after ``switch_model()`` / fallback activation or a recorded
  153. field rejection, the only events allowed to change the replayed bytes mid-session.
  154. """
  155. from agent.message_sanitization import reasoning_replay_route, rejected_reasoning_carriers
  156. rejected = rejected_reasoning_carriers(self)
  157. key = (getattr(self, "api_mode", None), self.provider, self.model, getattr(self, "_base_url_lower", self.base_url),
  158. self._reasoning_echo_opt_in(), rejected)
  159. cached = getattr(self, "_reasoning_route_cache", None)
  160. if cached is not None and cached[0] == key:
  161. return cached[1]
  162. route = reasoning_replay_route(key[0], self.provider, self.model, self.base_url,
  163. echo_opt_in=key[4], rejected=rejected)
  164. self._reasoning_route_cache = (key, route)
  165. return route
  166. def _needs_thinking_reasoning_pad(self) -> bool:
  167. """True for the must-echo tier: DeepSeek / Kimi / MiMo thinking 400 on a replayed tool-call turn
  168. without a non-empty ``reasoning_content`` (#15250, #17400), plus a ``model.reasoning_echo`` opt-in
  169. for gateways proxying them. Never true on a route that does not read the field."""
  170. return self._reasoning_replay_route().pad
  171. def _reasoning_echo_opt_in(self) -> bool:
  172. """``model.reasoning_echo``: treat the *current* provider as must-echo (pad tool-call turns) — for
  173. gateways proxying DeepSeek/Kimi/MiMo that the host rules miss. Replay itself is on by default;
  174. fallback activation swaps the flag and ``restore_primary_runtime()`` restores it."""
  175. return bool(getattr(self, "_reasoning_echo_flag", False))
  176. @staticmethod
  177. def _read_reasoning_echo_from_config() -> bool:
  178. """Read ``model.reasoning_echo`` from config; False on any error."""
  179. try:
  180. from hermes_cli.config import load_config_readonly
  181. return bool((load_config_readonly().get("model") or {}).get("reasoning_echo"))
  182. except Exception as exc: # health: allow BLE001 -- a config failure must fall back, not fail init
  183. # Log the class, never the config value or exception traceback.
  184. logging.getLogger("run_agent").warning(
  185. "Agent configuration for model.reasoning_echo could not be loaded (%s); "
  186. "using the default reasoning echo setting. Check the active Hermes Python "
  187. "environment and dependencies; run 'hermes config check' after "
  188. "configuration imports work again.",
  189. type(exc).__name__,
  190. )
  191. return False
  192. # Echo families are host/provider-driven, not model-name-driven: aggregators re-exporting Kimi reject the
  193. # echo. Rule table: ``message_sanitization._REASONING_ECHO_RULES``. Kimi deliberately passes the raw
  194. # provider and no model (its rule matches exact provider ids + hosts only).
  195. def _needs_kimi_tool_reasoning(self) -> bool:
  196. """True when the current provider is Kimi / Moonshot thinking mode."""
  197. return matches_reasoning_echo_family("kimi", self.provider, None, self.base_url)
  198. def _needs_deepseek_tool_reasoning(self) -> bool:
  199. """True when the current provider is DeepSeek thinking mode (omitting the echo is an HTTP 400).
  200. DeepSeek V4 thinking mode requires ``reasoning_content`` on every assistant tool-call turn; omitting
  201. it causes HTTP 400 when the message is replayed in a subsequent API request (#15250).
  202. """
  203. return matches_reasoning_echo_family("deepseek", (self.provider or "").lower(), self.model, self.base_url)
  204. def _needs_mimo_tool_reasoning(self) -> bool:
  205. """True when the current provider is Xiaomi MiMo thinking mode."""
  206. return matches_reasoning_echo_family("mimo", (self.provider or "").lower(), self.model, self.base_url)
  207. _copy_reasoning_content_for_api = _forward("agent.agent_runtime_helpers", "copy_reasoning_content_for_api")
  208. _reapply_reasoning_echo_for_provider = _forward("agent.agent_runtime_helpers", "reapply_reasoning_echo_for_provider")
  209. @staticmethod
  210. def _sanitize_tool_calls_for_strict_api(api_msg: dict, model: str | None = None, *, base_url: str | None = None,
  211. provider: str | None = None) -> dict:
  212. """Strip Codex Responses fields from tool_calls for strict Chat Completions APIs (Mistral, Fireworks
  213. 400/422 on unknown fields). ``extra_content`` (Gemini thought_signature) is kept only on Gemini routes
  214. (model family, Gemini host or provider). Builds new dicts so the internal history keeps the Codex
  215. fields for a later fallback."""
  216. tool_calls = api_msg.get("tool_calls")
  217. if not isinstance(tool_calls, list):
  218. return api_msg
  219. from agent.transports.chat_completions import _model_consumes_thought_signature
  220. keep_signature = _model_consumes_thought_signature(model, base_url, provider)
  221. strip = {"call_id", "response_item_id"} | (set() if keep_signature else {"extra_content"})
  222. api_msg["tool_calls"] = [{k: v for k, v in tc.items() if k not in strip} if isinstance(tc, dict) else tc
  223. for tc in tool_calls]
  224. return api_msg
  225. _sanitize_tool_call_arguments = _forward_static("agent.agent_runtime_helpers", "sanitize_tool_call_arguments")
  226. def _should_sanitize_tool_calls(self) -> bool:
  227. """True for every non-Codex API: Codex Responses fields are not Chat Completions schema and 400 elsewhere."""
  228. return self.api_mode != "codex_responses"