moa_config.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378
  1. """Mixture-of-Agents configuration and slash-command helpers."""
  2. from __future__ import annotations
  3. import base64
  4. import json
  5. import math
  6. from copy import deepcopy
  7. from typing import Any
  8. MOA_MARKER_PREFIX = "__HERMES_MOA_TURN_V1__"
  9. DEFAULT_MOA_PRESET_NAME = "default"
  10. DEFAULT_MOA_REFERENCE_MODELS: list[dict[str, str]] = [
  11. {"provider": "openai-codex", "model": "gpt-5.5"},
  12. {"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"}]
  13. DEFAULT_MOA_AGGREGATOR: dict[str, str] = {
  14. "provider": "openrouter", "model": "anthropic/claude-opus-4.8"}
  15. DEFAULT_MOA_REFERENCE_TIMEOUT: float | None = None
  16. def _default_reference_models() -> list[dict[str, Any]]:
  17. return [{**slot, "enabled": True} for slot in deepcopy(DEFAULT_MOA_REFERENCE_MODELS)]
  18. def _coerce_number(value: Any, cast, default=None, *, positive: bool = False):
  19. """Coerce ``value`` with ``cast`` (float/int); ``default`` when unset/blank/invalid.
  20. ``int`` also accepts float-looking strings ("3.0"). With ``positive`` the result must be > 0
  21. or ``default`` is returned. Non-finite floats always fall back to ``default``."""
  22. if value is None or value == "":
  23. return default
  24. try:
  25. number = cast(value)
  26. except (TypeError, ValueError, OverflowError):
  27. if cast is not int:
  28. return default
  29. try:
  30. number = int(float(value))
  31. except (TypeError, ValueError, OverflowError):
  32. return default
  33. if (cast is float and not math.isfinite(number)) or (positive and number <= 0):
  34. return default
  35. return number
  36. def _coerce_reference_timeout(value: Any) -> float | None:
  37. """Finite positive advisor timeout, or None to inherit ``auxiliary.moa_reference.timeout``.
  38. No artificial cap: long-thinking advisor models legitimately run far beyond five minutes."""
  39. if isinstance(value, bool):
  40. return DEFAULT_MOA_REFERENCE_TIMEOUT
  41. return _coerce_number(value, float, DEFAULT_MOA_REFERENCE_TIMEOUT, positive=True)
  42. def _coerce_fanout(value: Any) -> str:
  43. """Normalize the fan-out cadence to ``per_iteration`` | ``user_turn`` | ``every_n:<N>`` (N >= 2);
  44. the mapping form ``{mode: every_n, n: N}`` becomes the string, ``every_n:1`` collapses to
  45. ``per_iteration``, anything unparseable falls back to ``user_turn`` (the cheapest cadence).
  46. The ``every_n`` cadence also accepts the mapping form ``{mode: every_n, n: N}`` from hand-edited YAML
  47. and normalizes it to the canonical string, so the rest of the pipeline (presets, flattened view,
  48. runtime) only ever sees one shape. See #67199.
  49. """
  50. def _every_n(n: int) -> str:
  51. return f"every_n:{n}" if n >= 2 else ("per_iteration" if n == 1 else "user_turn")
  52. if isinstance(value, dict):
  53. # Non-every_n mapping modes fall through to the string path (e.g. {mode: user_turn}).
  54. mode = str(value.get("mode") or "").strip().lower()
  55. if mode == "every_n":
  56. return _every_n(_coerce_number(value.get("n"), int, 0))
  57. value = mode
  58. mode = str(value or "").strip().lower()
  59. if mode in {"per_iteration", "user_turn"}:
  60. return mode
  61. if mode.startswith("every_n"):
  62. _, sep, rest = mode.partition(":")
  63. return _every_n(_coerce_number(rest.strip(), int, 0) if sep else 0)
  64. return "user_turn"
  65. def coerce_privacy_filter(value: Any) -> str:
  66. """Normalize ``moa.privacy_filter`` to '' (off, the default), 'display', or 'full'.
  67. ``false``/``None``/unknown values land on '' so a hand-edited config degrades to prior
  68. behavior. 'display' redacts user-visible surfaces only (reference blocks in the UI and saved
  69. MoA trace records).
  70. - ``''`` (empty string): filter off — the default. The aggregator still sees raw advisor text, so answer
  71. quality is unaffected. - ``'full'``: additionally redact the advisor text injected into the aggregator
  72. prompt (issue #59959's literal ask). A hand-edited boolean ``true`` maps here because the issue framed
  73. the toggle as "redact before passing to the aggregator".
  74. """
  75. if value is True:
  76. return "full"
  77. if value is None or value is False:
  78. return ""
  79. mode = str(value).strip().lower()
  80. return mode if mode in {"display", "full"} else ("full" if mode in {"true", "on", "yes", "1"} else "")
  81. def _clean_reasoning_effort(value: Any) -> str | None:
  82. """Canonical per-slot reasoning effort, or None when unset/invalid."""
  83. from hermes_constants import parse_reasoning_effort
  84. parsed = None if value is None or value is True else parse_reasoning_effort(value)
  85. if parsed is None:
  86. return None
  87. return "none" if parsed.get("enabled") is False else parsed.get("effort")
  88. def _coerce_bool(value: Any, default: bool = True) -> bool:
  89. if value is None:
  90. return default
  91. if isinstance(value, bool):
  92. return value
  93. if isinstance(value, str):
  94. text = value.strip().lower()
  95. return True if text in {"1", "true", "yes", "on"} else False if text in {"0", "false", "no", "off"} else default
  96. return bool(value)
  97. def _slot_problem(slot: Any) -> str | None:
  98. """Human-readable problem for a slot ``_clean_slot`` would drop; None when complete and valid.
  99. Mirrors ``_clean_slot`` exactly so the write-boundary validator (``validate_moa_payload``) and
  100. the tolerant runtime normalizer can never disagree about what is acceptable."""
  101. if not isinstance(slot, dict):
  102. return "must be an object with 'provider' and 'model'"
  103. provider = str(slot.get("provider") or "").strip()
  104. model = str(slot.get("model") or "").strip()
  105. if not provider and not model:
  106. return "provider and model are required"
  107. if not provider:
  108. return "provider is required"
  109. if not model:
  110. return f"model is required (provider '{provider}' has no model selected)"
  111. # MoA is a virtual provider whose presets are themselves MoA runs; allowing one as a slot
  112. # would create a recursive MoA tree that the runtime guards only catch mid-turn.
  113. if provider.lower() == "moa":
  114. return "the Mixture of Agents provider cannot be used inside a preset (recursive MoA)"
  115. return None
  116. def _clean_slot(slot: Any, *, include_enabled: bool = False) -> dict[str, Any] | None:
  117. # Any slot ``_slot_problem`` rejects is dropped, falling back to the preset's defaults.
  118. if _slot_problem(slot) is not None:
  119. return None
  120. clean: dict[str, Any] = {"provider": str(slot["provider"]).strip(), "model": str(slot["model"]).strip()}
  121. effort = _clean_reasoning_effort(slot.get("reasoning_effort"))
  122. if effort:
  123. clean["reasoning_effort"] = effort
  124. if include_enabled:
  125. clean["enabled"] = _coerce_bool(slot.get("enabled"), True)
  126. return clean
  127. def _reference_slots(raw_refs: Any) -> list:
  128. """``reference_models`` as a list: a JSON string (hand-edited config.yaml) is decoded, a single
  129. mapping is wrapped, and any other scalar / bad type degrades to ``[]`` instead of crashing."""
  130. if isinstance(raw_refs, str):
  131. try:
  132. raw_refs = json.loads(raw_refs)
  133. except (json.JSONDecodeError, ValueError):
  134. raw_refs = []
  135. if not isinstance(raw_refs, list):
  136. raw_refs = [raw_refs] if isinstance(raw_refs, dict) else []
  137. return raw_refs
  138. def validate_moa_payload(raw: Any) -> list[str]:
  139. """Return the problems ``normalize_moa_config`` would silently paper over (empty = safe to save).
  140. Read-time tolerance (a hand-edited config degrades to defaults instead of crashing) is a
  141. corruption engine at write time: a half-filled slot would silently replace the whole preset.
  142. ``normalize_moa_config`` is deliberately tolerant: at *read* time a hand-edited config must degrade to
  143. defaults rather than crash the agent. API write paths call this first and reject invalid payloads loudly
  144. instead of saving something the user never chose. See #64156.
  145. """
  146. if not isinstance(raw, dict):
  147. return ["MoA config must be an object"]
  148. presets_raw = raw.get("presets")
  149. # Legacy flat payload: the top-level object is the default preset.
  150. presets: dict[Any, Any] = presets_raw if isinstance(presets_raw, dict) and presets_raw else {DEFAULT_MOA_PRESET_NAME: raw}
  151. problems: list[str] = []
  152. for name, preset in presets.items():
  153. label = str(name or "").strip() or "(unnamed)"
  154. if not isinstance(preset, dict):
  155. problems.append(f"preset '{label}': must be an object")
  156. continue
  157. refs = preset.get("reference_models")
  158. if not isinstance(refs, list):
  159. refs = [refs] if isinstance(refs, dict) else []
  160. issues = [(index, _slot_problem(slot)) for index, slot in enumerate(refs)]
  161. problems.extend(f"preset '{label}' reference {index + 1}: {issue}" for index, issue in issues if issue)
  162. if all(issue for _, issue in issues):
  163. problems.append(f"preset '{label}': needs at least one complete reference model")
  164. agg_issue = _slot_problem(preset.get("aggregator"))
  165. if agg_issue:
  166. problems.append(f"preset '{label}' aggregator: {agg_issue}")
  167. return problems
  168. def _normalize_preset(raw: Any) -> dict[str, Any]:
  169. if not isinstance(raw, dict):
  170. raw = {}
  171. cleaned = (_clean_slot(item, include_enabled=True) for item in _reference_slots(raw.get("reference_models")))
  172. refs = [item for item in cleaned if item is not None]
  173. policy = str(raw.get("degraded_reference_policy") or "loud").strip().lower()
  174. return {
  175. "enabled": _coerce_bool(raw.get("enabled"), True),
  176. "reference_models": refs or _default_reference_models(),
  177. "aggregator": _clean_slot(raw.get("aggregator")) or deepcopy(DEFAULT_MOA_AGGREGATOR),
  178. # None means 'don't send it — provider default applies'.
  179. "reference_temperature": _coerce_number(raw.get("reference_temperature"), float),
  180. "aggregator_temperature": _coerce_number(raw.get("aggregator_temperature"), float),
  181. "reference_timeout": _coerce_reference_timeout(raw.get("reference_timeout")),
  182. # Failed-advisor disclosure policy; unknown values fail loud.
  183. "degraded_reference_policy": policy if policy in {"loud", "silent"} else "loud",
  184. # "user_turn" (default, cheapest): advisors run ONCE per user turn; "per_iteration": every
  185. # tool iteration; "every_n:<N>": first iteration of each turn and every Nth after.
  186. "fanout": _coerce_fanout(raw.get("fanout"))}
  187. _FLAT_PRESET_KEYS = (
  188. "reference_models", "aggregator", "reference_temperature", "aggregator_temperature",
  189. "reference_timeout", "degraded_reference_policy",
  190. "fanout", "enabled")
  191. # Aggregator slot fields ``_clean_slot`` reads, accepted under any preset name (the schema walk only
  192. # knows the seeded ``default`` preset's provider/model). As there, a slot left without provider or model
  193. # is dropped by the normalizer and the default aggregator applies. The ``fanout`` mapping keys keep the
  194. # notice: ``n`` only takes effect beside ``mode: every_n`` (either one alone normalizes to ``user_turn``),
  195. # and ``fanout every_n:N`` sets the cadence in one write.
  196. _AGGREGATOR_SLOT_FIELDS = frozenset({"provider", "model", "reasoning_effort"})
  197. def is_preset_field_path(parts: list[str]) -> bool:
  198. """True for a split ``moa.presets.<name>.<field>`` path whose field ``_normalize_preset`` reads, or
  199. ``moa.presets.<name>.aggregator.<slot field>``.
  200. ``<name>`` may be anything except blank or whitespace-padded: :func:`normalize_moa_config` strips
  201. names, so a ``" review "`` entry would silently replace the ``review`` preset. Such a path is
  202. not a field path and keeps the unknown-key notice.
  203. """
  204. if len(parts) not in (4, 5) or parts[:2] != ["moa", "presets"] or parts[3] not in _FLAT_PRESET_KEYS:
  205. return False
  206. if not parts[2] or parts[2] != parts[2].strip():
  207. return False
  208. return len(parts) == 4 or (parts[3] == "aggregator" and parts[4] in _AGGREGATOR_SLOT_FIELDS)
  209. # When the reference fan-out runs. "user_turn" (default) runs the advisors ONCE per user turn (the original
  210. # MoA shape, and the cheapest cadence — #67199): the aggregator gets their upfront plan-level advice, then
  211. # acts alone for the rest of the tool loop. "per_iteration" re-runs the advisors whenever the advisory view
  212. # changes — i.e. every tool iteration, so advice tracks live task state at the cost of multiplying advisor
  213. # spend by tool-loop depth. "every_n:<N>" (N >= 2) is the middle ground: advisors run on the first iteration
  214. # of each user turn and every Nth tool iteration after it; in-between iterations reuse the cached guidance
  215. # from the last advisor run. Also accepts the mapping form {mode: every_n, n: N}, normalized to the
  216. # canonical string.
  217. def normalize_moa_config(raw: Any) -> dict[str, Any]:
  218. """Return validated MoA config with named presets."""
  219. if not isinstance(raw, dict):
  220. raw = {}
  221. presets_raw = raw.get("presets")
  222. presets: dict[str, dict[str, Any]] = {}
  223. if isinstance(presets_raw, dict):
  224. for name, preset in presets_raw.items():
  225. clean_name = str(name or "").strip()
  226. if clean_name:
  227. presets[clean_name] = _normalize_preset(preset)
  228. if not presets: # Legacy flat config becomes the default preset.
  229. presets[DEFAULT_MOA_PRESET_NAME] = _normalize_preset(raw)
  230. default_name = str(raw.get("default_preset") or "").strip()
  231. if not default_name or default_name not in presets:
  232. default_name = next(iter(presets)) # never empty: legacy flat config seeds the default
  233. active_name = str(raw.get("active_preset") or "").strip()
  234. if active_name not in presets:
  235. active_name = ""
  236. return {
  237. "default_preset": default_name,
  238. "active_preset": active_name,
  239. "presets": presets,
  240. # Compatibility/flattened view for existing dashboard/desktop callers.
  241. **{key: deepcopy(presets[default_name][key]) for key in _FLAT_PRESET_KEYS},
  242. # MoA-level (not per-preset) toggle; see coerce_privacy_filter for the modes.
  243. "privacy_filter": coerce_privacy_filter(raw.get("privacy_filter"))}
  244. def resolve_moa_preset(config: Any, name: str | None = None) -> dict[str, Any]:
  245. cfg = normalize_moa_config(config)
  246. preset_name = str(name or cfg.get("default_preset") or DEFAULT_MOA_PRESET_NAME).strip()
  247. preset = cfg["presets"].get(preset_name)
  248. if preset is None:
  249. from agent.errors import MoAPresetNotFoundError
  250. available = ", ".join(cfg["presets"]) or "(none)"
  251. raise MoAPresetNotFoundError(
  252. f"MoA preset '{preset_name}' was not found. Available presets: "
  253. f"{available}. Run `hermes moa list`.")
  254. return deepcopy(preset)
  255. def skip_deep_merge(prefix: str, key: str) -> bool:
  256. """True when the generic missing-config recursion must NOT descend into this section key.
  257. ``moa.presets`` is a named map; a present-but-partial user map is authoritative
  258. (see :func:`apply_user_moa_presets`), so the new-key probe must not imply a
  259. union into it.
  260. """
  261. return prefix == "moa" and key == "presets"
  262. def apply_user_moa_presets(merged: dict[str, Any], raw: Any) -> None:
  263. """Treat an explicit user MoA preset map as authoritative.
  264. ``moa.presets`` is a named map. Generic default merging must not union the
  265. schema's built-in names into a user map, because that resurrects presets
  266. the user deleted. An omitted ``moa.presets`` key still receives defaults;
  267. an explicit empty map remains empty. Called by the config load/merge paths
  268. right after ``_deep_merge``.
  269. """
  270. raw_moa = raw.get("moa") if isinstance(raw, dict) else None
  271. if not isinstance(raw_moa, dict) or "presets" not in raw_moa:
  272. return
  273. raw_presets = raw_moa.get("presets")
  274. if not isinstance(raw_presets, dict):
  275. return
  276. merged_moa = merged.get("moa")
  277. if not isinstance(merged_moa, dict):
  278. return
  279. merged_moa["presets"] = deepcopy(raw_presets)
  280. def exact_moa_preset_name(config: Any, text: str) -> str | None:
  281. """Return the preset name iff ``text`` exactly matches an *enabled* preset.
  282. Used by the no-explicit-provider switch path for a bare ``/model <preset>``. Because the match
  283. is implicit it honors the per-preset ``enabled`` opt-out: a plain model switch that collides
  284. with a disabled preset's name must not silently pivot onto the MoA provider. Explicit
  285. ``--provider moa`` / picker selection bypasses this, so disabled presets stay reachable.
  286. See #55187.
  287. """
  288. wanted = str(text or "").strip()
  289. if not wanted:
  290. return None
  291. preset = normalize_moa_config(config)["presets"].get(wanted)
  292. return None if preset is None or not preset.get("enabled", True) else wanted
  293. def decode_moa_turn(message: Any) -> tuple[str, dict[str, Any] | None]:
  294. """Decode a hidden /moa one-shot marker."""
  295. if not isinstance(message, str) or not message.startswith(MOA_MARKER_PREFIX):
  296. return message, None
  297. encoded = message[len(MOA_MARKER_PREFIX):].strip()
  298. try:
  299. payload = json.loads(base64.urlsafe_b64decode(encoded.encode("ascii")).decode("utf-8"))
  300. except Exception:
  301. return message, None
  302. return str(payload.get("prompt") or ""), _normalize_preset(payload.get("config") or {})
  303. def moa_usage() -> str:
  304. return "Usage: /moa <prompt> (runs one prompt through the default MoA preset, then restores your model; pick a preset from the model picker to switch for the session)"