356 lines
16 KiB
Python
356 lines
16 KiB
Python
"""Mixture-of-Agents configuration and slash-command helpers."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import base64
|
|
import json
|
|
import math
|
|
from copy import deepcopy
|
|
from typing import Any
|
|
|
|
MOA_MARKER_PREFIX = "__HERMES_MOA_TURN_V1__"
|
|
DEFAULT_MOA_PRESET_NAME = "default"
|
|
|
|
DEFAULT_MOA_REFERENCE_MODELS: list[dict[str, str]] = [
|
|
{"provider": "openai-codex", "model": "gpt-5.5"},
|
|
{"provider": "openrouter", "model": "deepseek/deepseek-v4-pro"},
|
|
]
|
|
|
|
DEFAULT_MOA_AGGREGATOR: dict[str, str] = {
|
|
"provider": "openrouter",
|
|
"model": "anthropic/claude-opus-4.8",
|
|
}
|
|
|
|
DEFAULT_MOA_REFERENCE_TIMEOUT: float | None = None
|
|
|
|
|
|
def _default_reference_models() -> list[dict[str, Any]]:
|
|
return [{**slot, "enabled": True} for slot in deepcopy(DEFAULT_MOA_REFERENCE_MODELS)]
|
|
|
|
|
|
def _coerce_number(value: Any, cast, default=None, *, positive: bool = False):
|
|
"""Coerce ``value`` with ``cast`` (float/int); ``default`` when unset/blank/invalid.
|
|
|
|
``int`` also accepts float-looking strings ("3.0"). With ``positive`` the result must be > 0
|
|
(and finite for floats) or ``default`` is returned.
|
|
"""
|
|
if value is None or value == "":
|
|
return default
|
|
try:
|
|
number = cast(value)
|
|
except (TypeError, ValueError):
|
|
if cast is not int:
|
|
return default
|
|
try:
|
|
number = int(float(value))
|
|
except (TypeError, ValueError):
|
|
return default
|
|
if positive and (number <= 0 or (cast is float and not math.isfinite(number))):
|
|
return default
|
|
return number
|
|
|
|
|
|
def _coerce_reference_timeout(value: Any) -> float | None:
|
|
"""Finite positive advisor timeout, or None to inherit ``auxiliary.moa_reference.timeout``.
|
|
|
|
No artificial cap: long-thinking advisor models legitimately run far beyond five minutes.
|
|
"""
|
|
if isinstance(value, bool):
|
|
return DEFAULT_MOA_REFERENCE_TIMEOUT
|
|
return _coerce_number(value, float, DEFAULT_MOA_REFERENCE_TIMEOUT, positive=True)
|
|
|
|
|
|
def _coerce_fanout(value: Any) -> str:
|
|
"""Normalize the fan-out cadence; unknown values fall back to default.
|
|
|
|
Canonical values are ``per_iteration``, ``user_turn``, and ``every_n:<N>`` (N >= 2); the
|
|
mapping form ``{mode: every_n, n: N}`` from hand-edited YAML is normalized to the string so the
|
|
rest of the pipeline sees one shape. ``every_n:1`` collapses to ``per_iteration``; anything
|
|
unparseable falls back to ``user_turn`` (the cheapest cadence).
|
|
"""
|
|
def _every_n(n: int) -> str:
|
|
return f"every_n:{n}" if n >= 2 else ("per_iteration" if n == 1 else "user_turn")
|
|
|
|
if isinstance(value, dict):
|
|
# Mapping form: {mode: every_n, n: 3}. Non-every_n mapping modes fall
|
|
# through to the string path below (e.g. {mode: user_turn}).
|
|
mode = str(value.get("mode") or "").strip().lower()
|
|
if mode == "every_n":
|
|
return _every_n(_coerce_number(value.get("n"), int, 0))
|
|
value = mode
|
|
mode = str(value or "").strip().lower()
|
|
if mode in {"per_iteration", "user_turn"}:
|
|
return mode
|
|
if mode.startswith("every_n"):
|
|
_, sep, rest = mode.partition(":")
|
|
return _every_n(_coerce_number(rest.strip(), int, 0) if sep else 0)
|
|
return "user_turn"
|
|
|
|
|
|
def coerce_privacy_filter(value: Any) -> str:
|
|
"""Normalize ``moa.privacy_filter`` to '' (off), 'display', or 'full'.
|
|
|
|
- ``''`` (empty string): filter off — the default. ``false``/``None``/ unknown values land here
|
|
so a hand-edited config degrades to prior behavior (tolerant-read contract). - ``'display'``:
|
|
redact user-visible surfaces only — the reference blocks shown in the UI and the saved MoA trace
|
|
records.
|
|
"""
|
|
if value is True:
|
|
return "full"
|
|
if value is None or value is False:
|
|
return ""
|
|
mode = str(value).strip().lower()
|
|
return mode if mode in {"display", "full"} else ("full" if mode in {"true", "on", "yes", "1"} else "")
|
|
|
|
|
|
def _clean_reasoning_effort(value: Any) -> str | None:
|
|
"""Return a canonical per-slot reasoning effort, or None when unset/invalid."""
|
|
from hermes_constants import parse_reasoning_effort
|
|
|
|
parsed = None if value is None or value is True else parse_reasoning_effort(value)
|
|
if parsed is None:
|
|
return None
|
|
return "none" if parsed.get("enabled") is False else parsed.get("effort")
|
|
|
|
|
|
def _coerce_bool(value: Any, default: bool = True) -> bool:
|
|
if value is None:
|
|
return default
|
|
if isinstance(value, bool):
|
|
return value
|
|
if isinstance(value, str):
|
|
text = value.strip().lower()
|
|
return True if text in {"1", "true", "yes", "on"} else False if text in {"0", "false", "no", "off"} else default
|
|
return bool(value)
|
|
|
|
|
|
def _slot_problem(slot: Any) -> str | None:
|
|
"""Return a human-readable problem for a slot ``_clean_slot`` would drop.
|
|
|
|
None means the slot is complete and valid. Mirrors ``_clean_slot`` exactly so the write-boundary
|
|
validator (``validate_moa_payload``) and the tolerant runtime normalizer can never disagree
|
|
about what is acceptable.
|
|
"""
|
|
if not isinstance(slot, dict):
|
|
return "must be an object with 'provider' and 'model'"
|
|
provider = str(slot.get("provider") or "").strip()
|
|
model = str(slot.get("model") or "").strip()
|
|
if not provider and not model:
|
|
return "provider and model are required"
|
|
if not provider:
|
|
return "provider is required"
|
|
if not model:
|
|
return f"model is required (provider '{provider}' has no model selected)"
|
|
# MoA is a virtual provider whose presets are themselves MoA runs. Allowing
|
|
# one as a reference or aggregator slot would create a recursive MoA tree
|
|
# (the runtime guards in moa_loop.py skip references / raise on aggregators,
|
|
# but that surfaces only mid-turn). Reject it here so it can never be saved.
|
|
if provider.lower() == "moa":
|
|
return "the Mixture of Agents provider cannot be used inside a preset (recursive MoA)"
|
|
return None
|
|
|
|
|
|
def _clean_slot(slot: Any, *, include_enabled: bool = False) -> dict[str, Any] | None:
|
|
# Any slot ``_slot_problem`` rejects (non-dict, missing provider/model, recursive
|
|
# ``moa`` provider) is dropped, falling back to the preset's defaults.
|
|
if _slot_problem(slot) is not None:
|
|
return None
|
|
clean: dict[str, Any] = {"provider": str(slot["provider"]).strip(), "model": str(slot["model"]).strip()}
|
|
effort = _clean_reasoning_effort(slot.get("reasoning_effort"))
|
|
if effort:
|
|
clean["reasoning_effort"] = effort
|
|
# Optional per-slot max_tokens: overrides the preset-level
|
|
# reference_max_tokens for this specific reference model. None (the
|
|
# default) = no cap, so existing slots are unaffected. Allows tuning
|
|
# each advisor's output length independently — useful when one model
|
|
# is verbose and another is terse.
|
|
slot_mt = _coerce_number(slot.get("max_tokens"), int, positive=True)
|
|
if slot_mt is not None:
|
|
clean["max_tokens"] = slot_mt
|
|
if include_enabled:
|
|
clean["enabled"] = _coerce_bool(slot.get("enabled"), True)
|
|
return clean
|
|
|
|
|
|
|
|
def validate_moa_payload(raw: Any) -> list[str]:
|
|
"""Return the problems ``normalize_moa_config`` would silently paper over.
|
|
|
|
``normalize_moa_config`` is deliberately tolerant: at *read* time a hand-edited config must
|
|
degrade to defaults rather than crash the agent. That same tolerance at *write* time is a
|
|
corruption engine — a client that sends a half-filled slot gets its whole preset silently
|
|
replaced with the hardcoded defaults (#64156).
|
|
|
|
Returns a list of human-readable problems; empty means safe to save.
|
|
"""
|
|
if not isinstance(raw, dict):
|
|
return ["MoA config must be an object"]
|
|
|
|
presets_raw = raw.get("presets")
|
|
# Legacy flat payload: the top-level object is the default preset.
|
|
presets: dict[Any, Any] = presets_raw if isinstance(presets_raw, dict) and presets_raw else {DEFAULT_MOA_PRESET_NAME: raw}
|
|
|
|
problems: list[str] = []
|
|
for name, preset in presets.items():
|
|
label = str(name or "").strip() or "(unnamed)"
|
|
if not isinstance(preset, dict):
|
|
problems.append(f"preset '{label}': must be an object")
|
|
continue
|
|
|
|
refs = preset.get("reference_models")
|
|
if not isinstance(refs, list):
|
|
refs = [refs] if isinstance(refs, dict) else []
|
|
issues = [(index, _slot_problem(slot)) for index, slot in enumerate(refs)]
|
|
problems.extend(f"preset '{label}' reference {index + 1}: {issue}" for index, issue in issues if issue)
|
|
if all(issue for _, issue in issues):
|
|
problems.append(f"preset '{label}': needs at least one complete reference model")
|
|
|
|
agg_issue = _slot_problem(preset.get("aggregator"))
|
|
if agg_issue:
|
|
problems.append(f"preset '{label}' aggregator: {agg_issue}")
|
|
|
|
return problems
|
|
|
|
|
|
def _normalize_preset(raw: Any) -> dict[str, Any]:
|
|
if not isinstance(raw, dict):
|
|
raw = {}
|
|
|
|
raw_refs = raw.get("reference_models")
|
|
# reference_models may be a JSON string (hand-edited config.yaml) or a list.
|
|
if isinstance(raw_refs, str):
|
|
try:
|
|
raw_refs = json.loads(raw_refs)
|
|
except (json.JSONDecodeError, ValueError):
|
|
raw_refs = []
|
|
if not isinstance(raw_refs, list):
|
|
# A hand-edited scalar / single mapping (or a bad type) must degrade to
|
|
# defaults instead of crashing the iteration, mirroring the tolerance
|
|
# for the scalar fields below (reference_temperature / max_tokens).
|
|
raw_refs = [raw_refs] if isinstance(raw_refs, dict) else []
|
|
refs = [item for item in (_clean_slot(item, include_enabled=True) for item in raw_refs) if item is not None]
|
|
|
|
return {
|
|
"enabled": _coerce_bool(raw.get("enabled"), True),
|
|
"reference_models": refs or _default_reference_models(),
|
|
"aggregator": _clean_slot(raw.get("aggregator")) or deepcopy(DEFAULT_MOA_AGGREGATOR),
|
|
# None means 'don't send it — provider default applies'.
|
|
"reference_temperature": _coerce_number(raw.get("reference_temperature"), float),
|
|
"aggregator_temperature": _coerce_number(raw.get("aggregator_temperature"), float),
|
|
"reference_timeout": _coerce_reference_timeout(raw.get("reference_timeout")),
|
|
# Failed-advisor disclosure policy; unknown values fail loud.
|
|
"degraded_reference_policy": policy if (policy := str(raw.get("degraded_reference_policy") or "loud").strip().lower()) in {"loud", "silent"} else "loud",
|
|
"max_tokens": _coerce_number(raw.get("max_tokens"), int, 4096),
|
|
# Optional cap on how much each reference ADVISOR may generate per turn.
|
|
# None (default) = uncapped: advisors write full-length advice, matching
|
|
# prior behavior so existing presets are unchanged. Set a value (e.g.
|
|
# 600) to make advisors give concise advice — the dominant MoA latency
|
|
# is advisor generation (turn latency correlates ~0.88 with output
|
|
# tokens), and the aggregator only needs the gist of each advisor's
|
|
# judgement, so capping roughly halves per-turn wall time. Does NOT cap
|
|
# the acting aggregator (its output is the user-visible answer).
|
|
"reference_max_tokens": _coerce_number(raw.get("reference_max_tokens"), int, positive=True),
|
|
# When the reference fan-out runs. "user_turn" (default) runs the
|
|
# advisors ONCE per user turn (the original MoA shape, and the
|
|
# cheapest cadence — #67199): the aggregator gets their upfront
|
|
# plan-level advice, then acts alone for the rest of the tool loop.
|
|
# "per_iteration" re-runs the advisors whenever the advisory view
|
|
# changes — i.e. every tool iteration, so advice tracks live task
|
|
# state at the cost of multiplying advisor spend by tool-loop depth.
|
|
# "every_n:<N>" (N >= 2) is the middle ground: advisors run on the
|
|
# first iteration of each user turn and every Nth tool iteration
|
|
# after it; in-between iterations reuse the cached guidance from the
|
|
# last advisor run. Also accepts the mapping form
|
|
# {mode: every_n, n: N}, normalized to the canonical string.
|
|
"fanout": _coerce_fanout(raw.get("fanout")),
|
|
}
|
|
|
|
|
|
_FLAT_PRESET_KEYS = (
|
|
"reference_models", "aggregator", "reference_temperature", "aggregator_temperature",
|
|
"reference_timeout", "degraded_reference_policy", "max_tokens", "reference_max_tokens",
|
|
"fanout", "enabled",
|
|
)
|
|
|
|
|
|
def normalize_moa_config(raw: Any) -> dict[str, Any]:
|
|
"""Return validated MoA config with named presets."""
|
|
if not isinstance(raw, dict):
|
|
raw = {}
|
|
|
|
presets_raw = raw.get("presets")
|
|
presets: dict[str, dict[str, Any]] = {}
|
|
if isinstance(presets_raw, dict):
|
|
for name, preset in presets_raw.items():
|
|
clean_name = str(name or "").strip()
|
|
if clean_name:
|
|
presets[clean_name] = _normalize_preset(preset)
|
|
if not presets: # Legacy flat config becomes the default preset.
|
|
presets[DEFAULT_MOA_PRESET_NAME] = _normalize_preset(raw)
|
|
|
|
default_name = str(raw.get("default_preset") or "").strip()
|
|
if not default_name or default_name not in presets:
|
|
default_name = next(iter(presets)) # never empty: legacy flat config seeds the default
|
|
|
|
active_name = str(raw.get("active_preset") or "").strip()
|
|
if active_name not in presets:
|
|
active_name = ""
|
|
|
|
return {
|
|
"default_preset": default_name,
|
|
"active_preset": active_name,
|
|
"presets": presets,
|
|
# Compatibility/flattened view for existing dashboard/desktop callers.
|
|
**{key: deepcopy(presets[default_name][key]) for key in _FLAT_PRESET_KEYS},
|
|
# MoA-level (not per-preset) toggles ride at the top level alongside
|
|
# save_traces. privacy_filter: '' (off, default) | 'display' | 'full'
|
|
# — see coerce_privacy_filter for the semantics of each mode.
|
|
"privacy_filter": coerce_privacy_filter(raw.get("privacy_filter")),
|
|
}
|
|
|
|
|
|
def resolve_moa_preset(config: Any, name: str | None = None) -> dict[str, Any]:
|
|
cfg = normalize_moa_config(config)
|
|
preset_name = str(name or cfg.get("default_preset") or DEFAULT_MOA_PRESET_NAME).strip()
|
|
preset = cfg["presets"].get(preset_name)
|
|
if preset is None:
|
|
from agent.errors import MoAPresetNotFoundError
|
|
|
|
available = ", ".join(cfg["presets"]) or "(none)"
|
|
raise MoAPresetNotFoundError(
|
|
f"MoA preset '{preset_name}' was not found. Available presets: "
|
|
f"{available}. Run `hermes moa list`."
|
|
)
|
|
return deepcopy(preset)
|
|
|
|
|
|
def exact_moa_preset_name(config: Any, text: str) -> str | None:
|
|
"""Return the preset name iff ``text`` exactly matches an *enabled* preset.
|
|
|
|
Used by the no-explicit-provider switch path to recognize a bare ``/model <preset>``. Because
|
|
the match is implicit it honors the per-preset ``enabled`` opt-out: a plain model switch that
|
|
collides with a disabled preset's name must not silently pivot onto the MoA provider. Explicit
|
|
``--provider moa`` / picker selection bypasses this, so disabled presets stay reachable.
|
|
"""
|
|
wanted = str(text or "").strip()
|
|
if not wanted:
|
|
return None
|
|
preset = normalize_moa_config(config)["presets"].get(wanted)
|
|
return None if preset is None or not preset.get("enabled", True) else wanted
|
|
|
|
|
|
def decode_moa_turn(message: Any) -> tuple[str, dict[str, Any] | None]:
|
|
"""Decode a hidden /moa one-shot marker."""
|
|
if not isinstance(message, str) or not message.startswith(MOA_MARKER_PREFIX):
|
|
return message, None
|
|
encoded = message[len(MOA_MARKER_PREFIX):].strip()
|
|
try:
|
|
payload = json.loads(base64.urlsafe_b64decode(encoded.encode("ascii")).decode("utf-8"))
|
|
except Exception:
|
|
return message, None
|
|
return str(payload.get("prompt") or ""), _normalize_preset(payload.get("config") or {})
|
|
|
|
|
|
def moa_usage() -> str:
|
|
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)"
|