mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-11 13:41:53 +00:00
227 lines
8.3 KiB
Python
227 lines
8.3 KiB
Python
"""Human-friendly generic gateway status phrases.
|
|
|
|
These helpers deliberately avoid relaying raw model scratch text. They turn
|
|
Hermes' long-running gateway status surface into short status lines suitable
|
|
for chat surfaces.
|
|
|
|
Built-in defaults live in ``gateway/assets/status_phrases.yaml``. Users can add
|
|
portable, profile-relative phrase catalogs under ``HERMES_HOME`` either by using
|
|
conventional paths::
|
|
|
|
~/.hermes/status_phrases.yaml
|
|
~/.hermes/status_phrases/*.yaml
|
|
|
|
or by pointing config at a relative file/directory::
|
|
|
|
display:
|
|
status_phrases:
|
|
path: status_phrases/whatsapp.yaml # relative to HERMES_HOME
|
|
mode: append # append (default) or replace
|
|
|
|
Absolute paths and ``..`` escapes are ignored on purpose so config stays
|
|
profile-portable and does not accidentally read arbitrary files.
|
|
|
|
Only configured phrase strings are used; raw tool args, commands, previews, and
|
|
reasoning text are never interpolated into the returned phrase.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import random as _random
|
|
from collections.abc import Mapping, MutableSequence
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
import yaml
|
|
|
|
from hermes_constants import get_hermes_home
|
|
|
|
# These are Hermes UI surfaces, not app/vendor/domain buckets. Keep this
|
|
# long-running-only: regular tool/thinking/interim chatter is intentionally not
|
|
# rewritten into generic placeholders because that gets noisy fast in chat.
|
|
_STATUS_SURFACES = ("status", "generic")
|
|
_MAX_CUSTOM_PHRASES_PER_SURFACE = 80
|
|
_MAX_PHRASE_CHARS = 160
|
|
_CONVENTIONAL_RELATIVE_PATHS = ("status_phrases.yaml", "status_phrases")
|
|
|
|
_FALLBACK_PHRASES: dict[str, list[str]] = {
|
|
"status": ["still on it", "still working through it", "waiting for the result"],
|
|
"generic": ["on it", "one sec", "checking that now"],
|
|
}
|
|
|
|
|
|
def _clean_phrase_list(value: Any) -> list[str]:
|
|
if not isinstance(value, list):
|
|
return []
|
|
cleaned: list[str] = []
|
|
seen: set[str] = set()
|
|
for item in value[:_MAX_CUSTOM_PHRASES_PER_SURFACE]:
|
|
phrase = str(item or "").strip()
|
|
if not phrase or len(phrase) > _MAX_PHRASE_CHARS or phrase in seen:
|
|
continue
|
|
cleaned.append(phrase)
|
|
seen.add(phrase)
|
|
return cleaned
|
|
|
|
|
|
def _merge_phrase_mapping(catalog: dict[str, list[str]], section: Mapping[str, Any], *, inherited_mode: str | None = None) -> None:
|
|
mode = str(section.get("mode") or inherited_mode or "append").strip().lower()
|
|
replace = mode == "replace"
|
|
phrase_map = section.get("phrases") if isinstance(section.get("phrases"), Mapping) else section
|
|
for surface in _STATUS_SURFACES:
|
|
phrases = _clean_phrase_list(phrase_map.get(surface) if isinstance(phrase_map, Mapping) else None)
|
|
if not phrases:
|
|
continue
|
|
catalog[surface] = phrases if replace else [*catalog.get(surface, []), *phrases]
|
|
|
|
|
|
def _merge_phrase_file(catalog: dict[str, list[str]], path: Path, *, inherited_mode: str | None = None) -> None:
|
|
try:
|
|
loaded = yaml.safe_load(path.read_text(encoding="utf-8"))
|
|
except Exception:
|
|
return
|
|
if isinstance(loaded, Mapping):
|
|
_merge_phrase_mapping(catalog, loaded, inherited_mode=inherited_mode)
|
|
|
|
|
|
def _relative_path_under(base_dir: Path, raw_path: Any) -> Path | None:
|
|
raw = str(raw_path or "").strip()
|
|
if not raw:
|
|
return None
|
|
candidate = Path(raw).expanduser()
|
|
if candidate.is_absolute() or ".." in candidate.parts:
|
|
return None
|
|
base = base_dir.resolve()
|
|
resolved = (base / candidate).resolve()
|
|
try:
|
|
resolved.relative_to(base)
|
|
except ValueError:
|
|
return None
|
|
return resolved
|
|
|
|
|
|
def _iter_phrase_files(path: Path) -> list[Path]:
|
|
if path.is_file() and path.suffix.lower() in {".yaml", ".yml"}:
|
|
return [path]
|
|
if path.is_dir():
|
|
return sorted(
|
|
child for child in path.iterdir()
|
|
if child.is_file() and child.suffix.lower() in {".yaml", ".yml"}
|
|
)
|
|
return []
|
|
|
|
|
|
def _merge_phrase_paths(
|
|
catalog: dict[str, list[str]],
|
|
paths: Any,
|
|
*,
|
|
base_dir: Path,
|
|
inherited_mode: str | None = None,
|
|
) -> None:
|
|
if paths is None:
|
|
return
|
|
raw_paths = paths if isinstance(paths, list) else [paths]
|
|
for raw_path in raw_paths:
|
|
resolved = _relative_path_under(base_dir, raw_path)
|
|
if resolved is None:
|
|
continue
|
|
for phrase_file in _iter_phrase_files(resolved):
|
|
_merge_phrase_file(catalog, phrase_file, inherited_mode=inherited_mode)
|
|
|
|
|
|
def _load_builtin_catalog() -> dict[str, list[str]]:
|
|
catalog = {surface: list(phrases) for surface, phrases in _FALLBACK_PHRASES.items()}
|
|
catalog_path = Path(__file__).resolve().parent / "assets" / "status_phrases.yaml"
|
|
_merge_phrase_file(catalog, catalog_path, inherited_mode="replace")
|
|
return catalog
|
|
|
|
|
|
_DEFAULT_PHRASES: dict[str, list[str]] = _load_builtin_catalog()
|
|
|
|
|
|
def _copy_default_catalog() -> dict[str, list[str]]:
|
|
return {surface: list(phrases) for surface, phrases in _DEFAULT_PHRASES.items()}
|
|
|
|
|
|
def _merge_phrase_config(catalog: dict[str, list[str]], section: Any, *, base_dir: Path | None = None) -> None:
|
|
"""Merge one display.status_phrases-style section into ``catalog``."""
|
|
if not isinstance(section, Mapping):
|
|
return
|
|
mode = str(section.get("mode") or "append").strip().lower()
|
|
if base_dir is not None:
|
|
_merge_phrase_paths(catalog, section.get("path"), base_dir=base_dir, inherited_mode=mode)
|
|
_merge_phrase_paths(catalog, section.get("paths"), base_dir=base_dir, inherited_mode=mode)
|
|
_merge_phrase_mapping(catalog, section)
|
|
|
|
|
|
def resolve_status_phrase_catalog(user_config: Mapping[str, Any] | None, platform_key: str | None = None) -> dict[str, list[str]]:
|
|
"""Resolve built-in + user-configured generic status phrases.
|
|
|
|
Resolution order mirrors gateway display settings: built-ins, conventional
|
|
profile-relative user files, global ``display.status_phrases`` (or legacy
|
|
alias ``generic_status_phrases``), then
|
|
``display.platforms.<platform>.status_phrases``.
|
|
"""
|
|
catalog = _copy_default_catalog()
|
|
hermes_home = get_hermes_home()
|
|
_merge_phrase_paths(catalog, list(_CONVENTIONAL_RELATIVE_PATHS), base_dir=hermes_home)
|
|
|
|
display = (user_config or {}).get("display") if isinstance(user_config, Mapping) else None
|
|
if not isinstance(display, Mapping):
|
|
return catalog
|
|
|
|
_merge_phrase_config(catalog, display.get("generic_status_phrases"), base_dir=hermes_home)
|
|
_merge_phrase_config(catalog, display.get("status_phrases"), base_dir=hermes_home)
|
|
|
|
platforms = display.get("platforms")
|
|
if platform_key and isinstance(platforms, Mapping):
|
|
platform_display = platforms.get(platform_key)
|
|
if isinstance(platform_display, Mapping):
|
|
_merge_phrase_config(catalog, platform_display.get("generic_status_phrases"), base_dir=hermes_home)
|
|
_merge_phrase_config(catalog, platform_display.get("status_phrases"), base_dir=hermes_home)
|
|
return catalog
|
|
|
|
|
|
def classify_status_context(
|
|
kind: str,
|
|
*,
|
|
tool_name: str | None = None,
|
|
preview: str | None = None,
|
|
args: Any = None,
|
|
) -> str:
|
|
"""Classify an internal gateway event into a Hermes UI-surface bucket."""
|
|
normalized = str(kind or "").strip().lower()
|
|
if normalized in {"heartbeat", "waiting", "long_running", "status"}:
|
|
return "status"
|
|
return "generic"
|
|
|
|
|
|
def choose_status_phrase(
|
|
kind: str,
|
|
*,
|
|
tool_name: str | None = None,
|
|
preview: str | None = None,
|
|
args: Any = None,
|
|
recent: MutableSequence[str] | None = None,
|
|
rng: Any = None,
|
|
catalog: Mapping[str, list[str]] | None = None,
|
|
) -> str:
|
|
"""Pick a short generic status phrase, avoiding recent repeats.
|
|
|
|
``preview`` and ``args`` are accepted for callback compatibility, but their
|
|
raw contents are never embedded in the returned phrase.
|
|
"""
|
|
phrase_catalog = catalog or _DEFAULT_PHRASES
|
|
category = classify_status_context(kind, tool_name=tool_name, preview=preview, args=args)
|
|
candidates = list(phrase_catalog.get(category) or phrase_catalog.get("generic") or _DEFAULT_PHRASES["generic"])
|
|
if recent:
|
|
recent_set = set(recent)
|
|
fresh = [phrase for phrase in candidates if phrase not in recent_set]
|
|
if fresh:
|
|
candidates = fresh
|
|
picker = rng or _random
|
|
phrase = picker.choice(candidates)
|
|
if recent is not None:
|
|
recent.append(phrase)
|
|
del recent[:-6]
|
|
return phrase
|