relay_plugin_migrate.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250
  1. """Migrate legacy ``HERMES_NEMO_RELAY_ATIF_*`` / ``ATOF_*`` exporter vars into a Relay ``plugins.toml``.
  2. The Relay cutover (Aug 2026) stopped honouring the legacy exporter variables. This module turns
  3. those variables into ``<profile home>/relay-plugins.toml`` (built from the
  4. ``nemo_relay.observability`` dataclasses so the file is exactly what Relay validates), points
  5. ``HERMES_NEMO_RELAY_PLUGINS_TOML`` at it, and comments the legacy lines out. It runs from
  6. ``hermes update`` for every profile home and from ``hermes migrate relay`` for the active one.
  7. """
  8. from __future__ import annotations
  9. import logging
  10. from dataclasses import dataclass, field
  11. from pathlib import Path
  12. from typing import Any, Mapping, Optional
  13. from hermes_cli.relay_plugin_cutover import (
  14. LEGACY_RELAY_EXPORT_ENV_VARS, RELAY_PLUGINS_CONFIG_ENV, configured_legacy_relay_env_vars)
  15. logger = logging.getLogger(__name__)
  16. RELAY_PLUGINS_TOML_NAME = "relay-plugins.toml"
  17. _TRUE = {"1", "true", "yes", "on"}
  18. @dataclass
  19. class RelayMigrationResult:
  20. home: Path
  21. toml_path: Optional[Path] = None
  22. migrated_vars: tuple[str, ...] = ()
  23. skipped_reason: Optional[str] = None
  24. validation_error: Optional[str] = None
  25. diagnostics: list = field(default_factory=list)
  26. @property
  27. def migrated(self) -> bool:
  28. return self.toml_path is not None and self.skipped_reason is None
  29. def _truthy(value: Any) -> bool:
  30. return str(value or "").strip().lower() in _TRUE
  31. def _s(env: Mapping[str, Any], name: str, default: str = "") -> str:
  32. return str(env.get(name) or "").strip() or default
  33. def relay_plugin_payload_from_legacy_env(env: Mapping[str, Any]) -> dict[str, Any]:
  34. """The plugins.toml document (as a dict) equivalent to the legacy exporter variables. Defaults
  35. mirror the removed ``plugins/observability/nemo_relay`` plugin so a migrated user keeps the
  36. same files in the same places. Built through ``nemo_relay.observability`` so the sink
  37. discriminator (``type = "file"``) and every field name are the ones Relay validates."""
  38. from nemo_relay import observability as obs
  39. atif = atof = None
  40. if _truthy(env.get("HERMES_NEMO_RELAY_ATIF_ENABLED")):
  41. kwargs: dict[str, Any] = {
  42. "enabled": True,
  43. "agent_name": _s(env, "HERMES_NEMO_RELAY_ATIF_AGENT_NAME", "Hermes Agent"),
  44. "model_name": _s(env, "HERMES_NEMO_RELAY_ATIF_MODEL_NAME", "unknown"),
  45. "filename_template": _s(env, "HERMES_NEMO_RELAY_ATIF_FILENAME_TEMPLATE", "hermes-atif-{session_id}.json"),
  46. }
  47. if _s(env, "HERMES_NEMO_RELAY_ATIF_OUTPUT_DIRECTORY"):
  48. kwargs["output_directory"] = _s(env, "HERMES_NEMO_RELAY_ATIF_OUTPUT_DIRECTORY")
  49. if _s(env, "HERMES_NEMO_RELAY_ATIF_AGENT_VERSION"):
  50. kwargs["agent_version"] = _s(env, "HERMES_NEMO_RELAY_ATIF_AGENT_VERSION")
  51. atif = obs.AtifConfig(**kwargs)
  52. if _truthy(env.get("HERMES_NEMO_RELAY_ATOF_ENABLED")):
  53. mode = _s(env, "HERMES_NEMO_RELAY_ATOF_MODE", "append").lower()
  54. sink = obs.AtofFileSinkConfig(
  55. output_directory=_s(env, "HERMES_NEMO_RELAY_ATOF_OUTPUT_DIRECTORY") or None,
  56. filename=_s(env, "HERMES_NEMO_RELAY_ATOF_FILENAME", "hermes-atof.jsonl"),
  57. mode="overwrite" if mode == "overwrite" else "append",
  58. )
  59. atof = obs.AtofConfig(enabled=True, sinks=[sink])
  60. # Relay 0.10 auto-exports gen_ai traces (prompt/response content) to any OTEL_EXPORTER_OTLP_*
  61. # endpoint in the process env; the legacy vars never exported OTLP, so keep that off.
  62. otel_off = obs.OpenTelemetrySectionConfig(enabled=False)
  63. spec = obs.ComponentSpec(config=obs.ObservabilityConfig(atif=atif, atof=atof, opentelemetry=otel_off))
  64. return {"version": 1, "components": [spec.to_dict()]}
  65. def _toml_scalar(value: Any) -> str:
  66. if isinstance(value, bool):
  67. return "true" if value else "false"
  68. if isinstance(value, (int, float)):
  69. return repr(value)
  70. text = str(value).replace("\\", "\\\\").replace('"', '\\"')
  71. return f'"{text}"'
  72. def _emit_table(lines: list[str], path: str, table: Mapping[str, Any], *, array_item: bool = False) -> None:
  73. """Minimal TOML emitter for the nested-dict/list-of-dict shape ``to_dict()`` produces."""
  74. scalars = {k: v for k, v in table.items() if not isinstance(v, (dict, list))}
  75. nested = {k: v for k, v in table.items() if isinstance(v, (dict, list))}
  76. if path:
  77. lines.append(f"[[{path}]]" if array_item else f"[{path}]")
  78. for key, value in scalars.items():
  79. if value is not None:
  80. lines.append(f"{key} = {_toml_scalar(value)}")
  81. for key, value in nested.items():
  82. child = f"{path}.{key}" if path else key
  83. if isinstance(value, dict):
  84. lines.append("")
  85. _emit_table(lines, child, value)
  86. else:
  87. for item in value:
  88. if isinstance(item, dict):
  89. lines.append("")
  90. _emit_table(lines, child, item, array_item=True)
  91. else:
  92. raise ValueError(f"unsupported TOML array item at {child}: {item!r}")
  93. def dumps_toml(document: Mapping[str, Any]) -> str:
  94. """Serialize via ``tomli_w`` when installed, else the minimal emitter above (nested tables + arrays
  95. of tables only — exactly the ``ComponentSpec.to_dict()`` shape)."""
  96. try:
  97. import tomli_w # type: ignore
  98. return tomli_w.dumps(dict(document))
  99. except ImportError:
  100. lines: list[str] = []
  101. _emit_table(lines, "", document)
  102. return "\n".join(lines).strip() + "\n"
  103. def validate_relay_plugin_payload(payload: Mapping[str, Any]) -> list:
  104. """Run the payload through Relay's own validator; returns the warnings (empty = clean).
  105. Raises when Relay rejects the document, including by error-level diagnostics."""
  106. from nemo_relay import plugin
  107. # validate() would layer the payload over the ambient user config; the runtime never does.
  108. diagnostics = list(plugin.validate_exact(dict(payload))["config"]["diagnostics"])
  109. # Relay 0.8's initialize() raised on these; 0.9's validator only reports them.
  110. if errors := [d for d in diagnostics if d.get("level") == "error"]:
  111. raise ValueError("; ".join(str(d.get("message") or d.get("code") or d) for d in errors))
  112. return diagnostics
  113. def _comment_out_legacy_lines(lines: list[str], names: set[str]) -> list[str]:
  114. from hermes_cli.config import _env_line_defines_key
  115. out = []
  116. for line in lines:
  117. if any(_env_line_defines_key(line, name) for name in names):
  118. out.append(f"# migrated to {RELAY_PLUGINS_TOML_NAME}: {line.rstrip()}\n")
  119. else:
  120. out.append(line)
  121. return out
  122. def migrate_profile_relay_env(home: Path, *, validate: bool = True) -> RelayMigrationResult:
  123. """Migrate ONE profile home's ``.env``. Never raises for a no-op; a Relay import/validation failure
  124. leaves ``.env`` untouched and is reported in ``validation_error``."""
  125. from hermes_cli.config import _env_line_defines_key, _quote_env_value, _read_env_lines, _write_env_lines
  126. result = RelayMigrationResult(home=home)
  127. env_path = home / ".env"
  128. if not env_path.is_file():
  129. result.skipped_reason = "no .env"
  130. return result
  131. lines = _read_env_lines(env_path)
  132. env: dict[str, str] = {}
  133. for line in lines:
  134. stripped = line.strip()
  135. if not stripped or stripped.startswith("#") or "=" not in stripped:
  136. continue
  137. key, _, value = stripped.removeprefix("export ").partition("=")
  138. env[key.strip()] = value.strip().strip("'\"")
  139. legacy = configured_legacy_relay_env_vars(env)
  140. if not legacy:
  141. result.skipped_reason = "no legacy exporter variables"
  142. return result
  143. if env.get(RELAY_PLUGINS_CONFIG_ENV, "").strip():
  144. result.skipped_reason = f"{RELAY_PLUGINS_CONFIG_ENV} already set"
  145. return result
  146. if not (_truthy(env.get("HERMES_NEMO_RELAY_ATIF_ENABLED")) or _truthy(env.get("HERMES_NEMO_RELAY_ATOF_ENABLED"))):
  147. result.skipped_reason = "no exporter enabled by the legacy variables"
  148. return result
  149. try:
  150. payload = relay_plugin_payload_from_legacy_env(env)
  151. if validate:
  152. result.diagnostics = validate_relay_plugin_payload(payload)
  153. except Exception as exc: # nemo_relay missing or rejecting the payload: leave .env alone
  154. result.validation_error = f"{type(exc).__name__}: {exc}"
  155. return result
  156. toml_path = home / RELAY_PLUGINS_TOML_NAME
  157. header = (
  158. "# NeMo Relay plugin configuration for Hermes (selected via "
  159. f"{RELAY_PLUGINS_CONFIG_ENV} in .env).\n"
  160. "# Generated by `hermes update` from the legacy HERMES_NEMO_RELAY_ATIF_*/ATOF_* variables,\n"
  161. "# which Relay no longer reads. Edit this file to change exporters.\n"
  162. )
  163. toml_path.write_text(header + dumps_toml(payload), encoding="utf-8")
  164. new_lines = _comment_out_legacy_lines(lines, set(LEGACY_RELAY_EXPORT_ENV_VARS))
  165. if not any(_env_line_defines_key(line, RELAY_PLUGINS_CONFIG_ENV) for line in new_lines):
  166. if new_lines and not new_lines[-1].endswith("\n"):
  167. new_lines[-1] += "\n"
  168. new_lines.append(f"{RELAY_PLUGINS_CONFIG_ENV}={_quote_env_value(str(toml_path))}\n")
  169. _write_env_lines(env_path, new_lines, preserve_mode=True)
  170. result.toml_path = toml_path
  171. result.migrated_vars = legacy
  172. return result
  173. def migrate_all_profile_relay_envs(*, validate: bool = True) -> list[RelayMigrationResult]:
  174. """Default home + every live named profile (multiplex: each profile keeps its own TOML)."""
  175. from hermes_cli.profiles import _get_default_hermes_home, _iter_named_profile_dirs
  176. homes = [_get_default_hermes_home(), *_iter_named_profile_dirs()]
  177. return [migrate_profile_relay_env(home, validate=validate) for home in homes]
  178. def print_relay_migration_report(results: list[RelayMigrationResult]) -> None:
  179. """Loud, actionable notice for `hermes update` / `hermes migrate relay`."""
  180. migrated = [r for r in results if r.migrated]
  181. failed = [r for r in results if r.validation_error]
  182. if not migrated and not failed:
  183. return
  184. print()
  185. if migrated:
  186. print("\033[1;33m⚠ NeMo Relay exporter configuration migrated\033[0m")
  187. print(" Relay no longer reads the legacy HERMES_NEMO_RELAY_ATIF_*/ATOF_* variables.")
  188. print(" Each profile below now has a generated relay-plugins.toml selected by")
  189. print(f" {RELAY_PLUGINS_CONFIG_ENV} in its .env (legacy lines commented out, not deleted):")
  190. for r in migrated:
  191. extra = f" ({len(r.diagnostics)} Relay diagnostic(s))" if r.diagnostics else ""
  192. label = r.home.name if r.home.parent.name == "profiles" else "default"
  193. print(f" • {label}: {r.toml_path}{extra}")
  194. print(" Restart the gateway to apply the migrated exporter settings. Review the file and adjust paths if needed.")
  195. for r in failed:
  196. print(f" ✗ {r.home}: could not migrate Relay exporter vars — {r.validation_error}")
  197. print(f" Write {r.home / RELAY_PLUGINS_TOML_NAME} by hand and set {RELAY_PLUGINS_CONFIG_ENV}.")
  198. def run_relay_migration_after_update() -> None:
  199. """`hermes update` hook: migrate every profile home, print the notice. Best-effort by contract."""
  200. print_relay_migration_report(migrate_all_profile_relay_envs())
  201. def cmd_migrate_relay(args) -> None:
  202. """``hermes migrate relay [--all-profiles] [--no-validate]``."""
  203. from hermes_constants import get_hermes_home
  204. validate = not getattr(args, "no_validate", False)
  205. if getattr(args, "all_profiles", False):
  206. results = migrate_all_profile_relay_envs(validate=validate)
  207. else:
  208. results = [migrate_profile_relay_env(get_hermes_home(), validate=validate)]
  209. print_relay_migration_report(results)
  210. for r in results:
  211. if not r.migrated and not r.validation_error:
  212. print(f" {r.home}: nothing to migrate ({r.skipped_reason}).")