trace_upload.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262
  1. """Upload a Hermes session transcript to Hugging Face as an agent trace, re-emitted in the **Claude Code
  2. JSONL** shape the HF Agent Trace Viewer auto-detects (https://huggingface.co/docs/hub/agent-traces).
  3. Deterministic, zero LLM turns. Private by default: traces can carry prompts, tool output, local paths and
  4. secrets, so the dataset is created private and every text body passes the secret redactor (``force=True``)
  5. unless ``redact=False``. :func:`upload_session_trace` never raises (returns a user-facing status string);
  6. programmatic callers use :func:`build_trace_jsonl` + :func:`_do_upload`."""
  7. from __future__ import annotations
  8. from pm import install_hint
  9. import json
  10. import logging
  11. import os
  12. import uuid
  13. from datetime import datetime, timezone, UTC
  14. from typing import Any, Dict, List, Optional, Tuple
  15. logger = logging.getLogger(__name__)
  16. DEFAULT_DATASET_NAME = "hermes-traces"
  17. _HERMES_VERSION = "hermes-agent"
  18. _REDACTION_BLOCKED_MESSAGE = (
  19. "Trace upload blocked: secret redaction failed, so the transcript may "
  20. "still contain credentials or other sensitive data. Fix the redactor or "
  21. "rerun with --no-redact only after manually reviewing the transcript."
  22. )
  23. _NO_TOKEN_MESSAGE = (
  24. "Can't upload — no Hugging Face token is available. To set it up:\n"
  25. "\n"
  26. "1. Create a token with WRITE access at https://huggingface.co/settings/tokens\n"
  27. " (New token -> type \"Write\" -> copy it).\n"
  28. "2. Add it to your environment as HF_TOKEN (e.g. in ~/.hermes/.env):\n"
  29. " HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx\n"
  30. "3. Run /upload-trace again (or `hermes trace upload`)."
  31. )
  32. _TOKEN_ENV_VARS = ("HF_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HUGGING_FACE_HUB_TOKEN", "HUGGINGFACE_TOKEN")
  33. class TraceRedactionError(RuntimeError):
  34. """Raised when a trace cannot be safely redacted before upload."""
  35. # --- Conversion: Hermes OpenAI-format messages -> Claude Code JSONL ---
  36. def _now_iso() -> str:
  37. return datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
  38. def _redact(text: Any, enabled: bool) -> Any:
  39. """Redact a string body when enabled (``force=True``: an upload scrubs even if log redaction is off)."""
  40. if not enabled or not isinstance(text, str) or not text:
  41. return text
  42. try:
  43. from agent.redact import redact_sensitive_text
  44. return redact_sensitive_text(text, force=True)
  45. except Exception as exc:
  46. logger.warning("Trace upload redaction failed; refusing upload", exc_info=True)
  47. raise TraceRedactionError(_REDACTION_BLOCKED_MESSAGE) from exc
  48. def _text_block(text: Any, redact: bool) -> dict[str, Any]:
  49. return {"type": "text", "text": _redact(text, redact)}
  50. def _part_to_block(part: Any, redact: bool) -> dict[str, Any]:
  51. if not isinstance(part, dict):
  52. return _text_block(str(part), redact)
  53. if part.get("type") == "text":
  54. return _text_block(part.get("text", ""), redact)
  55. if part.get("type") in ("image_url", "image"):
  56. return {"type": "text", "text": "[image omitted]"} # the viewer renders text turns; no base64
  57. return _text_block(json.dumps(part), redact)
  58. def _content_to_blocks(content: Any, redact: bool) -> list[dict[str, Any]]:
  59. """Normalize a message ``content`` field into Anthropic content blocks."""
  60. if isinstance(content, list):
  61. return [_part_to_block(part, redact) for part in content]
  62. return [] if content is None else [_text_block(content if isinstance(content, str) else json.dumps(content), redact)]
  63. def _parse_tool_args(raw_args: Any) -> dict[str, Any]:
  64. if not isinstance(raw_args, str):
  65. return raw_args if isinstance(raw_args, dict) else {}
  66. try:
  67. return json.loads(raw_args) if raw_args.strip() else {}
  68. except (json.JSONDecodeError, ValueError):
  69. return {"_raw": raw_args}
  70. def _tool_calls_to_blocks(tool_calls: Any, redact: bool) -> list[dict[str, Any]]:
  71. """Convert OpenAI tool_calls into Anthropic ``tool_use`` content blocks."""
  72. blocks: list[dict[str, Any]] = []
  73. for tc in tool_calls if isinstance(tool_calls, list) else ():
  74. if not isinstance(tc, dict):
  75. continue
  76. fn = tc.get("function") or {}
  77. parsed = _parse_tool_args(fn.get("arguments"))
  78. if redact:
  79. try:
  80. parsed = json.loads(_redact(json.dumps(parsed), redact))
  81. except (json.JSONDecodeError, ValueError):
  82. logger.warning("Trace upload redacted tool arguments are not valid JSON; refusing upload")
  83. raise TraceRedactionError(_REDACTION_BLOCKED_MESSAGE)
  84. blocks.append({"type": "tool_use", "id": tc.get("id") or f"toolu_{uuid.uuid4().hex[:16]}",
  85. "name": fn.get("name") or tc.get("name") or "tool", "input": parsed})
  86. return blocks
  87. def _git_branch(cwd: str) -> str:
  88. if not cwd:
  89. return ""
  90. try:
  91. import subprocess
  92. r = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"],
  93. capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=3, cwd=cwd,
  94. stdin=subprocess.DEVNULL, check=False)
  95. except Exception:
  96. return ""
  97. return r.stdout.strip() if r.returncode == 0 else ""
  98. def _assistant_message(msg: dict[str, Any], model: str, redact: bool) -> dict[str, Any]:
  99. blocks = _content_to_blocks(msg.get("content"), redact) + _tool_calls_to_blocks(msg.get("tool_calls"), redact)
  100. return {"role": "assistant", "model": model or "unknown", "content": blocks or [{"type": "text", "text": ""}]}
  101. def _tool_result_message(msg: dict[str, Any], model: str, redact: bool) -> dict[str, Any]:
  102. content = msg.get("content")
  103. return {"role": "user", "content": [{
  104. "type": "tool_result", "tool_use_id": msg.get("tool_call_id") or msg.get("tool_name") or "tool",
  105. "content": _redact(content if isinstance(content, str) else json.dumps(content), redact),
  106. }]}
  107. def _user_message(msg: dict[str, Any], model: str, redact: bool) -> dict[str, Any]:
  108. content = msg.get("content")
  109. return {"role": "user", "content": _redact(content, redact) if isinstance(content, str) else _content_to_blocks(content, redact)}
  110. # role -> (Claude Code line type, message builder). Unknown roles render as user.
  111. _ROLE_RENDERERS: dict[Any, tuple[str, Any]] = {"assistant": ("assistant", _assistant_message), "tool": ("user", _tool_result_message)}
  112. def build_trace_jsonl(messages: list[dict[str, Any]], *, session_id: str, model: str = "", cwd: str = "", redact: bool = True) -> str:
  113. """One JSONL line per non-system message: ``user``/``tool`` -> type user (tool results ride on user turns as
  114. ``tool_result`` keyed by ``tool_call_id``), ``assistant`` -> text + ``tool_use`` blocks; turns link via ``parentUuid``."""
  115. lines: list[str] = []
  116. parent: Optional[str] = None
  117. base_ts = _now_iso()
  118. git_branch = _git_branch(cwd)
  119. for msg in messages:
  120. role = msg.get("role")
  121. if role == "system":
  122. continue
  123. turn_uuid = str(uuid.uuid4())
  124. line_type, render = _ROLE_RENDERERS.get(role, ("user", _user_message))
  125. entry = { # key order is the wire order
  126. "parentUuid": parent, "isSidechain": False, "userType": "external", "cwd": cwd or os.getcwd(),
  127. "sessionId": session_id, "version": _HERMES_VERSION, "gitBranch": git_branch, "uuid": turn_uuid,
  128. "timestamp": base_ts, "type": line_type, "message": render(msg, model, redact),
  129. }
  130. lines.append(json.dumps(entry, ensure_ascii=False))
  131. parent = turn_uuid
  132. return "\n".join(lines) + ("\n" if lines else "")
  133. # --- Upload ---
  134. def _resolve_hf_token() -> Optional[str]:
  135. """Return the user's Hugging Face token from the usual env vars."""
  136. return next((val for var in _TOKEN_ENV_VARS if (val := (os.getenv(var) or "").strip())), None)
  137. def _do_upload(
  138. jsonl: str,
  139. *,
  140. token: str,
  141. session_id: str,
  142. dataset_name: str = DEFAULT_DATASET_NAME,
  143. private: bool = True,
  144. ) -> str:
  145. """Create (idempotently) the private dataset and push the trace file.
  146. Returns a user-facing status string. Never raises.
  147. """
  148. try:
  149. import pm
  150. pm.ensure_import("trace-upload")
  151. except Exception:
  152. # lazy-install unavailable — fall through to the import, which
  153. # surfaces the install hint below if the package is missing.
  154. pass
  155. try:
  156. from huggingface_hub import HfApi
  157. except ImportError:
  158. return ("Hugging Face upload needs the `huggingface_hub` package. Run: "
  159. f"{install_hint('trace-upload')}")
  160. api = HfApi(token=token)
  161. try:
  162. who = api.whoami()
  163. except Exception as e:
  164. logger.warning("HF whoami failed: %s", e)
  165. return "Your Hugging Face token was rejected (whoami failed). Make sure it has WRITE access and isn't expired."
  166. user = who.get("name") if isinstance(who, dict) else None
  167. if not user:
  168. return "Could not resolve your Hugging Face username from the token."
  169. repo_id = f"{user}/{dataset_name}"
  170. try:
  171. api.create_repo(repo_id=repo_id, repo_type="dataset", private=private, exist_ok=True)
  172. except Exception as e:
  173. logger.warning("HF create_repo failed for %s: %s", repo_id, e)
  174. return f"Could not create/access dataset {repo_id}: {e}"
  175. path_in_repo = f"sessions/{session_id}.jsonl"
  176. try:
  177. api.upload_file(path_or_fileobj=jsonl.encode("utf-8"), path_in_repo=path_in_repo, repo_id=repo_id,
  178. repo_type="dataset", commit_message=f"add session trace {session_id}")
  179. except Exception as e:
  180. logger.warning("HF upload_file failed for %s: %s", repo_id, e)
  181. return f"Upload to Hugging Face failed: {e}"
  182. return (f"Uploaded -> https://huggingface.co/datasets/{repo_id}/blob/main/{path_in_repo}\n"
  183. f"View in the trace viewer: https://huggingface.co/datasets/{repo_id}")
  184. def load_session_messages(session_id: str, db_path=None) -> tuple[list[dict[str, Any]], dict[str, Any]]:
  185. """``(messages, meta)`` from SQLite; ``meta`` is ``{}`` when the session row is missing (a live, untitled
  186. session may still have messages)."""
  187. from hermes_state_registry import acquire, release_or_close
  188. db = acquire(db_path or None)
  189. try:
  190. resolved = db.resolve_session_id(session_id) or session_id
  191. meta = db.get_session(resolved) or {}
  192. return db.get_messages_as_conversation(resolved), meta
  193. finally:
  194. release_or_close(db)
  195. def upload_session_trace(
  196. session_id: str, *, model: str = "", cwd: str = "", redact: bool = True, private: bool = True,
  197. dataset_name: str = DEFAULT_DATASET_NAME, db_path=None, token: Optional[str] = None,
  198. ) -> str:
  199. """CLI/gateway entry point: load, convert, upload to ``{user}/hermes-traces``. Status string, never raises."""
  200. if not session_id:
  201. return "No active session to upload."
  202. token = token or _resolve_hf_token()
  203. if not token:
  204. return _NO_TOKEN_MESSAGE
  205. try:
  206. messages, meta = load_session_messages(session_id, db_path=db_path)
  207. except Exception as e:
  208. logger.warning("Failed to load session %s for trace upload: %s", session_id, e)
  209. return f"Could not load session {session_id}: {e}"
  210. if not messages:
  211. return "No transcript to upload for this session yet."
  212. try:
  213. jsonl = build_trace_jsonl(messages, session_id=session_id, model=model or meta.get("model") or "", cwd=cwd, redact=redact)
  214. except TraceRedactionError:
  215. return _REDACTION_BLOCKED_MESSAGE
  216. if not jsonl.strip():
  217. return "No transcript content to upload for this session."
  218. return _do_upload(jsonl, token=token, session_id=session_id, dataset_name=dataset_name, private=private)