message_timestamps.py 5.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136
  1. """Helpers for rendering gateway message timestamps exactly once.
  2. Gateway messages need timestamps in the LLM context for temporal awareness, but
  3. persisted message content should stay clean so replay does not accumulate
  4. ``[timestamp] [timestamp] ...`` prefixes across turns.
  5. """
  6. from __future__ import annotations
  7. import errno
  8. import re
  9. import sys
  10. import time
  11. from datetime import datetime, timezone, UTC
  12. from typing import Any, Optional, Tuple
  13. from hermes_time import safe_strftime
  14. # Leading timestamp prefix, either the current human format
  15. # ``[Tue 2026-04-28 13:40:53 CEST]`` or the older ISO one
  16. # ``[2026-04-13T17:02:06+0200]`` / ``[...+02:00]`` (human tried first).
  17. _TIMESTAMP_PREFIX_RE = re.compile(
  18. r"^\[(?:"
  19. r"(?P<dow>[A-Z][a-z]{2}) "
  20. r"(?P<date>\d{4}-\d{2}-\d{2}) "
  21. r"(?P<time>\d{2}:\d{2}:\d{2})"
  22. r"(?: (?P<tz>[A-Za-z0-9_+\-/:]+))?"
  23. r"|(?P<iso>\d{4}-\d{2}-\d{2}T[^\]]+)"
  24. r")\]\s*"
  25. )
  26. def _localize(dt: datetime, tz) -> Optional[float]:
  27. """Epoch for ``dt`` in ``tz`` or the local zone; None outside platform limits."""
  28. naive_local = dt.tzinfo is None and tz is None
  29. try:
  30. if dt.tzinfo is None:
  31. dt = dt.replace(tzinfo=tz) if tz is not None else dt.astimezone()
  32. return float(dt.timestamp())
  33. except (OverflowError, ValueError):
  34. return None
  35. except OSError as exc:
  36. if not (sys.platform == "win32" and naive_local and exc.errno == errno.EINVAL):
  37. return None
  38. # Windows' fold probe can reject the first Unix day. mktime can
  39. # resolve those local wall times without changing their meaning.
  40. # Limit recovery to that fold-free interval and reject normalization.
  41. wall_time = dt.timetuple()
  42. try:
  43. epoch = time.mktime(wall_time)
  44. if 0 <= epoch < 86_400 and time.localtime(epoch)[:6] == wall_time[:6]:
  45. return float(epoch + dt.microsecond / 1_000_000)
  46. except (OSError, OverflowError, ValueError):
  47. pass
  48. return None
  49. def _parse_iso(text: str, tz=None) -> Optional[float]:
  50. """Parse an ISO-8601 string (incl. ``+0200`` offsets fromisoformat rejects)."""
  51. for parse in (datetime.fromisoformat, lambda t: datetime.strptime(t, "%Y-%m-%dT%H:%M:%S%z")):
  52. try:
  53. return _localize(parse(text), tz)
  54. except (TypeError, ValueError):
  55. continue
  56. return None
  57. def _parse_timestamp_match(match: re.Match, tz=None) -> Optional[float]:
  58. if match.group("iso"):
  59. return _parse_iso(match.group("iso"), tz)
  60. try:
  61. dt = datetime.strptime(f"{match.group('date')} {match.group('time')}", "%Y-%m-%d %H:%M:%S")
  62. except ValueError:
  63. return None
  64. return _localize(dt, tz)
  65. def coerce_message_timestamp(ts_value: Any, tz=None) -> Optional[float]:
  66. """Epoch seconds from a number, datetime, ISO string, or the gateway's bracketed
  67. format; ``None`` when uninterpretable."""
  68. if isinstance(ts_value, (int, float)):
  69. return float(ts_value)
  70. if hasattr(ts_value, "timestamp"):
  71. try:
  72. return float(ts_value.timestamp())
  73. except Exception:
  74. return None
  75. text = ts_value.strip() if isinstance(ts_value, str) else ""
  76. if not text:
  77. return None
  78. match = _TIMESTAMP_PREFIX_RE.match(text)
  79. parsed = _parse_timestamp_match(match, tz=tz) if match is not None else None
  80. if parsed is not None:
  81. return parsed
  82. try:
  83. return float(text)
  84. except (TypeError, ValueError):
  85. return _parse_iso(text, tz)
  86. def format_message_timestamp(ts_value: Any, tz=None) -> str:
  87. """Format a timestamp value as ``[Tue 2026-04-28 13:40:53 CEST]``."""
  88. epoch = coerce_message_timestamp(ts_value, tz=tz)
  89. if epoch is None:
  90. return ""
  91. try:
  92. # An early positive epoch can fall in 1969 locally. Starting from aware
  93. # UTC avoids Windows' negative-time fold probe in naive astimezone().
  94. dt = datetime.fromtimestamp(epoch, tz=tz) if tz is not None else datetime.fromtimestamp(epoch, tz=UTC).astimezone()
  95. except (OSError, OverflowError, ValueError):
  96. return ""
  97. return f"[{safe_strftime(dt, '%a %Y-%m-%d %H:%M:%S %Z')}]"
  98. def strip_leading_message_timestamps(content: str, tz=None) -> tuple[str, Optional[float]]:
  99. """Strip leading gateway timestamp prefixes → ``(clean_content, embedded_epoch)``.
  100. With several prefixes the one closest to the text wins, preserving the platform-send
  101. time of legacy rows like ``[processing time] [platform time] [sender] message``."""
  102. if not isinstance(content, str) or not content:
  103. return content, None
  104. text, embedded_epoch = content, None
  105. while (match := _TIMESTAMP_PREFIX_RE.match(text)) is not None:
  106. parsed = _parse_timestamp_match(match, tz=tz)
  107. if parsed is not None:
  108. embedded_epoch = parsed
  109. text = text[match.end():]
  110. return text, embedded_epoch
  111. def render_user_content_with_timestamp(content: str, ts_value: Any = None, tz=None) -> str:
  112. """Render a user message for LLM context with exactly one timestamp prefix; an
  113. existing prefix is stripped and its parsed time wins over ``ts_value``."""
  114. clean_content, embedded_epoch = strip_leading_message_timestamps(content, tz=tz)
  115. prefix = format_message_timestamp(ts_value if embedded_epoch is None else embedded_epoch, tz=tz)
  116. return f"{prefix} {clean_content}" if prefix and clean_content else (prefix or clean_content)