moa_trace.py 4.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. """Full MoA turn trace persistence (opt-in via config ``moa.save_traces``).
  2. Every MoA turn that runs the reference fan-out (a cache MISS in
  3. ``MoAChatCompletions.create``) appends one JSON line to
  4. ``<hermes_home>/moa-traces/<session_id>.jsonl``: what every model saw, said, and
  5. cost. Side-channel only: never enters the ``messages`` table, history or replay
  6. (references are advisory side-calls whose rows would corrupt role alternation).
  7. Off by default; when off the only overhead is the config read.
  8. """
  9. from __future__ import annotations
  10. import json
  11. import logging
  12. import os
  13. import time
  14. from pathlib import Path
  15. from typing import Any, Optional
  16. from hermes_constants import get_hermes_home
  17. logger = logging.getLogger(__name__)
  18. def _traces_enabled_and_dir() -> Optional[Path]:
  19. """Trace directory if ``moa.save_traces`` is on, else None. Reads config per
  20. call (once per cache-MISS turn); ``moa.trace_dir`` overrides the default."""
  21. try:
  22. from hermes_cli.config import load_config
  23. moa_cfg = (load_config() or {}).get("moa") or {}
  24. except Exception: # pragma: no cover - never break a turn over tracing
  25. return None
  26. if not moa_cfg.get("save_traces"):
  27. return None
  28. override = moa_cfg.get("trace_dir")
  29. if override:
  30. return Path(os.path.expandvars(os.path.expanduser(str(override))))
  31. return get_hermes_home() / "moa-traces"
  32. def _sanitize_session_id(session_id: Optional[str]) -> str:
  33. if not session_id:
  34. return "unknown-session"
  35. return "".join(c if (c.isalnum() or c in "-_.") else "_" for c in str(session_id))
  36. _USAGE_FIELDS = ("input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens", "reasoning_tokens")
  37. _ACCT_FIELDS = ("model", "provider", "temperature")
  38. _COST_FIELDS = ("cost_usd", "cost_status", "cost_source")
  39. def _slot_trace(acct: Any, label: str) -> dict[str, Any]:
  40. """One reference's _RefAccounting as a full trace dict, including the FULL
  41. input messages and output (not the truncated display preview)."""
  42. usage = getattr(acct, "usage", None)
  43. return {
  44. "label": label, **{f: getattr(acct, f, None) for f in _ACCT_FIELDS},
  45. "input_messages": getattr(acct, "messages", None), "output": getattr(acct, "output", None),
  46. "usage": {f: getattr(usage, f, 0) for f in _USAGE_FIELDS} if usage is not None else {},
  47. **{f: getattr(acct, f, None) for f in _COST_FIELDS},
  48. }
  49. def slot_metrics(acct: Any, label: str, output: Any = None) -> dict[str, Any]:
  50. """``_slot_trace`` minus ``input_messages`` (the bulk of a record) for
  51. observability hooks. ``output`` comes from the caller because the
  52. privacy-redacted advisor text lives alongside the accounting, not on it."""
  53. trace = _slot_trace(acct, label)
  54. trace.pop("input_messages", None)
  55. if output is not None:
  56. trace["output"] = output
  57. return trace
  58. def save_moa_turn(
  59. *, session_id: Optional[str], preset_name: str, reference_outputs: list[tuple[str, str, Any]],
  60. aggregator_label: str, aggregator_model: Optional[str], aggregator_provider: Optional[str],
  61. aggregator_temperature: Any, aggregator_input_messages: Any, aggregator_output: Optional[str],
  62. aggregator_streamed: bool,
  63. ) -> None:
  64. """Append one full MoA turn record to the session's trace JSONL, if enabled.
  65. Best-effort: failures are logged at debug and swallowed. ``aggregator_output``
  66. is captured inline on the non-streaming path and after the fact from the
  67. resolved assistant text on the streaming path; if unavailable it is None and
  68. ``output_location`` points at the session store.
  69. """
  70. base = _traces_enabled_and_dir()
  71. if base is None:
  72. return
  73. try:
  74. base.mkdir(parents=True, exist_ok=True)
  75. path = base / f"{_sanitize_session_id(session_id)}.jsonl"
  76. if not aggregator_streamed:
  77. output_location = "inline"
  78. elif aggregator_output:
  79. output_location = "inline_from_stream"
  80. else:
  81. output_location = "assistant_message_in_session_db"
  82. record = {
  83. "ts": time.time(),
  84. "session_id": session_id,
  85. "preset": preset_name,
  86. "references": [_slot_trace(acct, label) for label, _text, acct in reference_outputs],
  87. "aggregator": {
  88. "label": aggregator_label, "model": aggregator_model,
  89. "provider": aggregator_provider, "temperature": aggregator_temperature,
  90. "input_messages": aggregator_input_messages, "output": aggregator_output,
  91. "streamed": aggregator_streamed, "output_location": output_location,
  92. },
  93. }
  94. with path.open("a", encoding="utf-8") as f:
  95. f.write(json.dumps(record, ensure_ascii=False, default=str) + "\n")
  96. except Exception as exc: # pragma: no cover - tracing must never break a turn
  97. logger.debug("MoA trace write failed (session=%s): %s", session_id, exc)