session_export.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. """Shared renderers for session export commands.
  2. CLI, dashboard, and slash-command surfaces all deal with the same session-shaped data (a session
  3. dict with a ``messages`` list); filtering and human-readable rendering live here so each surface
  4. only loads sessions and writes bytes.
  5. """
  6. from __future__ import annotations
  7. from datetime import datetime, timezone, UTC
  8. from html import escape as html_escape
  9. import json
  10. from typing import Any, Dict, Iterable, Iterator, List, Literal, Optional, Tuple
  11. from hermes_cli.timefmt import coerce_epoch
  12. ExportFormat = Literal["jsonl", "markdown"]
  13. ExportOnly = Literal["user-prompts"]
  14. _EXPORT_FORMATS = {"jsonl": "jsonl", "markdown": "markdown", "md": "markdown"}
  15. _ONLY_ALIASES = {"user", "prompts", "user-prompts", "user_prompts"}
  16. def normalize_export_format(fmt: str) -> ExportFormat:
  17. """Return the canonical export format name."""
  18. value = _EXPORT_FORMATS.get((fmt or "jsonl").strip().lower())
  19. if value is None:
  20. raise ValueError(f"Unsupported session export format: {fmt}")
  21. return value # type: ignore[return-value]
  22. def normalize_export_only(only: Optional[str]) -> Optional[ExportOnly]:
  23. """Return the canonical export filter name."""
  24. if only is None:
  25. return None
  26. if only.strip().lower() in _ONLY_ALIASES:
  27. return "user-prompts"
  28. raise ValueError(f"Unsupported session export filter: {only}")
  29. def render_sessions_export(sessions: Iterable[dict[str, Any]], *, fmt: str = "jsonl", only: Optional[str] = None) -> str:
  30. """Render exported sessions in a stable, reusable format.
  31. ``fmt=jsonl`` with no filter keeps the legacy shape (one full session object per line);
  32. ``only=user-prompts`` switches the unit to one prompt record per line for piping into
  33. review / memory-ingestion / prompt-library tooling.
  34. """
  35. session_list = list(sessions)
  36. export_format = normalize_export_format(fmt)
  37. prompts_only = normalize_export_only(only) == "user-prompts"
  38. if export_format == "jsonl":
  39. rows = iter_user_prompt_records(session_list) if prompts_only else session_list
  40. lines = [json.dumps(row, ensure_ascii=False) for row in rows]
  41. return ("\n".join(lines) + "\n") if lines else ""
  42. # One session → its own H1 with body at H2; several → a shared H1, each session H2/H3.
  43. if prompts_only:
  44. multi_title, append_body = "User prompts export", _append_prompt_records
  45. headings = (lambda s: f"User prompts for session {_heading_text(_session_id(s))}",
  46. lambda s: f"Session {_heading_text(_session_id(s))}")
  47. else:
  48. multi_title, append_body = "Hermes sessions export", _append_session_messages
  49. headings = (lambda s: f"Session: {_heading_text(_session_title_or_id(s))}",) * 2
  50. lines: list[str] = []
  51. single = len(session_list) == 1
  52. if not single:
  53. lines += [f"# {multi_title}", ""]
  54. for session in session_list:
  55. level = 1 if single else 2
  56. lines += [f"{'#' * level} {headings[level - 1](session)}", *_session_metadata_lines(session), ""]
  57. append_body(lines, session, heading_level=level + 1)
  58. if prompts_only and not session_list:
  59. lines += ["_No user prompts found._", ""]
  60. while lines and lines[-1] == "":
  61. lines.pop()
  62. return "\n".join(lines) + "\n"
  63. def export_record_count(sessions: Iterable[dict[str, Any]], *, only: Optional[str] = None) -> tuple[int, str]:
  64. """Return ``(count, noun)`` for status messages after an export."""
  65. session_list = list(sessions)
  66. if normalize_export_only(only) == "user-prompts":
  67. return sum(1 for _ in iter_user_prompt_records(session_list)), "prompt"
  68. return len(session_list), "session"
  69. def iter_user_prompt_records(sessions: Iterable[dict[str, Any]]) -> Iterator[dict[str, Any]]:
  70. """Yield one normalized record for each user-authored prompt."""
  71. for session in sessions:
  72. session_id = str(session.get("id") or session.get("session_id") or "")
  73. prompts = [m for m in _messages(session) if m.get("role") == "user"]
  74. for index, message in enumerate(prompts, start=1):
  75. record: dict[str, Any] = {
  76. "session_id": session_id,
  77. "index": index,
  78. "created_at": _format_timestamp(message.get("timestamp"), session_id),
  79. "role": "user",
  80. "text": _message_text(message.get("content")),
  81. }
  82. if (message_id := message.get("id")) is not None:
  83. record["message_id"] = message_id
  84. if event_id := message.get("platform_message_id") or message.get("event_id"):
  85. record["event_id"] = event_id
  86. yield record
  87. def _append_prompt_records(lines: list[str], session: dict[str, Any], *, heading_level: int) -> None:
  88. prompts = list(iter_user_prompt_records([session]))
  89. if not prompts:
  90. lines += ["_No user prompts found._", ""]
  91. return
  92. marker = "#" * heading_level
  93. for prompt in prompts:
  94. lines.append(f"{marker} {prompt['index']}. {prompt.get('created_at') or 'timestamp unavailable'}")
  95. if (message_id := prompt.get("message_id")) is not None:
  96. lines += [f"Message ID: `{message_id}`", ""]
  97. lines += [str(prompt.get("text") or ""), ""]
  98. def _append_session_messages(lines: list[str], session: dict[str, Any], *, heading_level: int) -> None:
  99. marker = "#" * heading_level
  100. visible_messages = [message for message in _messages(session) if message.get("role") != "system"]
  101. if not visible_messages:
  102. lines += ["_No messages found._", ""]
  103. return
  104. for message in visible_messages:
  105. role = str(message.get("role") or "unknown")
  106. timestamp = _format_timestamp(message.get("timestamp"), _session_id(session))
  107. suffix = f" - {timestamp}" if timestamp else ""
  108. text = _message_text(message.get("content"))
  109. if role == "tool":
  110. tool_name = str(message.get("tool_name") or message.get("name") or "tool")
  111. lines += [
  112. f"{marker} Tool: {_heading_text(tool_name)}{suffix}", "",
  113. f"<details><summary>{html_escape(tool_name)}</summary>", "",
  114. _fenced_text(text), "", "</details>", "",
  115. ]
  116. else:
  117. label = {"user": "User", "assistant": "Assistant"}.get(role, role.title())
  118. lines += [f"{marker} {label}{suffix}", "", text, ""]
  119. def _messages(session: dict[str, Any]) -> list[dict[str, Any]]:
  120. return [message for message in session.get("messages") or [] if isinstance(message, dict)]
  121. def _message_text(content: Any) -> str:
  122. if isinstance(content, list):
  123. return "\n".join(part for part in map(_content_part_text, content) if part)
  124. return "" if content is None else _content_part_text(content)
  125. def _content_part_text(part: Any) -> str:
  126. if not isinstance(part, dict):
  127. return part if isinstance(part, str) else str(part)
  128. for key in ("text", "content"):
  129. if isinstance(value := part.get(key), str):
  130. return value
  131. return json.dumps(part, ensure_ascii=False, sort_keys=True)
  132. def _format_timestamp(value: Any, session_id: Optional[str] = None) -> Optional[str]:
  133. if value is None:
  134. return None
  135. if isinstance(value, datetime):
  136. dt = (value if value.tzinfo else value.replace(tzinfo=UTC)).astimezone(UTC)
  137. elif (ts := coerce_epoch(value, session_id=session_id)) is None:
  138. return str(value) # corrupt cell: odd-looking date, not an aborted export
  139. else:
  140. dt = datetime.fromtimestamp(ts, tz=UTC)
  141. return dt.isoformat(timespec="seconds").replace("+00:00", "Z")
  142. def _session_metadata_lines(session: dict[str, Any]) -> list[str]:
  143. lines: list[str] = [f"- Session ID: `{_session_id(session)}`"]
  144. for key, label in (("source", "Source"), ("model", "Model")):
  145. if session.get(key):
  146. lines.append(f"- {label}: `{session[key]}`")
  147. if title := session.get("title"):
  148. lines.append(f"- Title: {' '.join(str(title).splitlines()).strip()}")
  149. if started := _format_timestamp(session.get("started_at"), _session_id(session)):
  150. lines.append(f"- Started: {started}")
  151. if (message_count := session.get("message_count")) is not None:
  152. lines.append(f"- Messages: {message_count}")
  153. return lines
  154. def _session_id(session: dict[str, Any]) -> str:
  155. return str(session.get("id") or session.get("session_id") or "unknown")
  156. def _session_title_or_id(session: dict[str, Any]) -> str:
  157. return str(session.get("title") or "").strip() or _session_id(session)
  158. def _heading_text(value: str) -> str:
  159. return " ".join(str(value).splitlines()).strip() or "unknown"
  160. def _fenced_text(text: str, *, language: str = "text") -> str:
  161. fence = "```"
  162. while fence in text:
  163. fence += "`"
  164. return f"{fence}{language}\n{text}\n{fence}"
  165. # --- Current-session save helper (shared by CLI /save and gateway /save) ---
  166. SAVE_FORMATS = ("json", "md", "html")
  167. SAVE_TRANSCRIPT_FORMATS = frozenset({"md", "html"})
  168. def export_projection(transcript: bool) -> dict[str, bool]:
  169. """``export_session`` flags for an export. A transcript shows what the user sees, compaction-archived
  170. turns included. A JSON snapshot is what an import restores, so it carries every stored row with its
  171. ``active``/``compacted`` flags: live rows alone would drop every turn in-place compaction archived, and
  172. ``import_sessions`` brings the flagged rows back archived, never as live context."""
  173. return {"include_compacted": True} if transcript else {"include_inactive": True}
  174. def drop_undone_rows(export: dict[str, Any]) -> dict[str, Any]:
  175. """Keep live and compaction-archived rows in a ``/save`` JSON snapshot; rows removed by /undo, rewind
  176. or edit stay out. ``timings`` is rebuilt from the kept rows so it names no dropped row."""
  177. from hermes_state_portability import _export_timings
  178. export["messages"] = [m for m in export["messages"] if m["active"] or m["compacted"]]
  179. export["timings"] = _export_timings(export["messages"], export.get("id"))
  180. return export
  181. def load_save_snapshot(db: Any, session_id: str, fmt: str) -> Optional[dict[str, Any]]:
  182. """The stored session a ``/save <fmt>`` writes, or None when it has no row. A JSON snapshot loads every
  183. stored row in memory, so it is refused past ``sessions.max_export_messages`` (raises
  184. ``SessionExportTooLargeError``), like ``hermes sessions export``."""
  185. transcript = fmt in SAVE_TRANSCRIPT_FORMATS
  186. if not transcript:
  187. db.assert_export_safe(session_id)
  188. export = db.export_session(session_id, **export_projection(transcript))
  189. if export and not transcript:
  190. drop_undone_rows(export)
  191. return export
  192. SAVE_USAGE = """/save — export the current session to a file
  193. Usage: /save <format> [filename] [redact]
  194. Formats:
  195. json full session snapshot (canonical export shape)
  196. md readable Markdown transcript
  197. html standalone single-file HTML page (shareable, no dependencies)
  198. Options:
  199. filename optional output name/path (default: auto-named;
  200. CLI saves under ~/.hermes/sessions/saved/)
  201. redact scrub API keys, tokens, and credentials before writing
  202. Examples:
  203. /save json
  204. /save html
  205. /save md notes.md
  206. /save html session.html redact"""
  207. _SAVE_FORMAT_ALIASES = {"json": "json", "snapshot": "json", "md": "md", "markdown": "md", "html": "html"}
  208. def normalize_save_format(fmt: Optional[str]) -> str:
  209. """Map a user-typed /save format token to a canonical format."""
  210. token = (fmt or "json").strip().lower()
  211. if token not in _SAVE_FORMAT_ALIASES:
  212. raise ValueError(f"Unknown format {token!r} — expected one of: json, md, html")
  213. return _SAVE_FORMAT_ALIASES[token]
  214. def _render_html_for_save(session: dict[str, Any]) -> str:
  215. from hermes_cli.session_export_html import generate_html_export
  216. return generate_html_export(session)
  217. _SAVE_RENDERERS = {
  218. "json": lambda session: json.dumps(session, indent=2, ensure_ascii=False, default=str),
  219. "md": lambda session: render_sessions_export([session], fmt="markdown"),
  220. "html": _render_html_for_save,
  221. }
  222. def render_session_for_save(session: dict[str, Any], fmt: str) -> str:
  223. """Render one exported session dict for /save."""
  224. renderer = _SAVE_RENDERERS.get(fmt)
  225. if renderer is None:
  226. raise ValueError(f"Unknown save format: {fmt!r}")
  227. return renderer(session)
  228. def default_save_filename(session_id: str, fmt: str) -> str:
  229. """Default filename for a /save export of the given session."""
  230. safe_id = "".join(ch for ch in str(session_id) if ch.isalnum() or ch in ("-", "_")) or "session"
  231. return f"hermes_session_{safe_id}.{fmt}"