learning_graph.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255
  1. """Assemble the "learning made visible" graph for desktop.
  2. Scoped to what a user actually learns over time: non-base, learned/profile
  3. skills (agent-created or used) plus ``MEMORY.md`` / ``USER.md`` chunks as
  4. first-class nodes. Skill links come from declared ``related_skills``;
  5. memory→skill links are derived from lexical overlap.
  6. """
  7. from __future__ import annotations
  8. import hashlib
  9. import json
  10. import re
  11. from collections import Counter
  12. from dataclasses import dataclass, field
  13. from datetime import datetime, timezone, UTC
  14. from pathlib import Path
  15. from typing import Any, Optional
  16. from agent.skill_utils import EXCLUDED_SKILL_DIRS
  17. from hermes_constants import get_hermes_home
  18. _USAGE_TS_KEYS = ("last_activity_at", "last_used_at", "last_viewed_at", "last_patched_at", "created_at")
  19. @dataclass
  20. class SkillNode:
  21. name: str
  22. category: str
  23. source: str = "profile"
  24. timestamp: Optional[int] = None
  25. use_count: int = 0
  26. state: str = "active"
  27. created_by: Optional[str] = None
  28. pinned: bool = False
  29. related: list[str] = field(default_factory=list)
  30. def _fm_field(fm: dict[str, Any], key: str) -> Any:
  31. """Top-level ``key`` or ``metadata.hermes.<key>``; tolerant of the string-valued
  32. frontmatter that ``parse_frontmatter``'s malformed-YAML fallback produces."""
  33. if fm.get(key):
  34. return fm[key]
  35. meta = fm.get("metadata")
  36. hermes = meta.get("hermes") if isinstance(meta, dict) else None
  37. return hermes.get(key) if isinstance(hermes, dict) else None
  38. def _related(fm: dict[str, Any]) -> list[str]:
  39. raw = _fm_field(fm, "related_skills")
  40. raw = raw.strip("[]").split(",") if isinstance(raw, str) else raw
  41. return [str(r).strip() for r in raw if str(r).strip()] if isinstance(raw, list) else []
  42. def _load_usage() -> dict[str, dict[str, Any]]:
  43. try:
  44. from tools.skill_usage import load_usage
  45. return load_usage()
  46. except Exception:
  47. try:
  48. return json.loads((get_hermes_home() / "skills" / ".usage.json").read_text(encoding="utf-8-sig"))
  49. except Exception:
  50. return {}
  51. def _to_int_ts(value: Any) -> Optional[int]:
  52. """Epoch seconds from a number, numeric string, or ISO timestamp; None otherwise."""
  53. try:
  54. if value is None or not (s := str(value).strip()):
  55. return None
  56. if isinstance(value, (int, float)):
  57. return int(value)
  58. try:
  59. return int(float(s))
  60. except ValueError:
  61. parsed = datetime.fromisoformat(s)
  62. return int((parsed if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)).timestamp())
  63. except Exception:
  64. return None
  65. def build_skill_nodes(skill_roots: list[tuple[str, Path]]) -> dict[str, SkillNode]:
  66. usage = _load_usage()
  67. nodes: dict[str, SkillNode] = {}
  68. # Tag skills mounted from skills.external_dirs so the journey graph can keep them out of
  69. # learning milestones (#108032): a mount is configured, not learned. Path-based (the common
  70. # symlink into the profile tree resolves to the external root), so a local copy of the same
  71. # name still classifies as its own source.
  72. try:
  73. from agent.skill_utils import is_external_skill_path
  74. except Exception:
  75. is_external_skill_path = None # type: ignore[assignment]
  76. for source, root in skill_roots:
  77. for skill_md in root.rglob("SKILL.md") if root.exists() else ():
  78. if EXCLUDED_SKILL_DIRS.intersection(skill_md.relative_to(root).parts):
  79. continue
  80. try:
  81. text = skill_md.read_text(encoding="utf-8-sig")[:4000]
  82. except OSError:
  83. continue
  84. try:
  85. from agent.skill_utils import parse_frontmatter
  86. fm = parse_frontmatter(text)[0] or {}
  87. except Exception:
  88. fm = {}
  89. name = str(fm.get("name") or skill_md.parent.name).strip()
  90. if not name or name in nodes:
  91. continue
  92. rec, cat, parts = usage.get(name, {}), _fm_field(fm, "category"), skill_md.parts # …/skills/<category>/<skill>/SKILL.md
  93. usage_ts = next((ts for ts in (_to_int_ts(rec.get(k)) for k in _USAGE_TS_KEYS) if ts is not None), None)
  94. # Local variable: never overwrite `source` — the loop variable must keep its
  95. # per-root value for the NEXT skill in the same root, or every skill yielded
  96. # after the first external mount inherits "external" (ext4 hash order can
  97. # interleave a symlinked mount before a local skill in one root).
  98. node_source = "external" if (is_external_skill_path is not None and is_external_skill_path(skill_md)) else source
  99. nodes[name] = SkillNode(
  100. name=name, category=str(cat) if cat else parts[-3] if len(parts) >= 3 else "general", source=node_source,
  101. timestamp=usage_ts or _to_int_ts(skill_md.stat().st_mtime),
  102. use_count=int(rec.get("use_count", 0) or 0), state=str(rec.get("state", "active") or "active"),
  103. created_by=rec.get("created_by"), pinned=bool(rec.get("pinned", False)), related=_related(fm),
  104. )
  105. return nodes
  106. def build_edges(nodes: dict[str, SkillNode]) -> list[tuple[str, str]]:
  107. """Undirected related_skills edges where BOTH endpoints exist (deduped, first-seen order)."""
  108. return list(dict.fromkeys(
  109. (min(node.name, target), max(node.name, target)) for node in nodes.values() for target in node.related if target in nodes and target != node.name
  110. ))
  111. def density_stats(nodes: dict[str, SkillNode], edges: list[tuple[str, str]]) -> dict[str, Any]:
  112. linked, cats, n = {x for edge in edges for x in edge}, Counter(x.category for x in nodes.values()), len(nodes) or 1
  113. return {
  114. "nodes": len(nodes), "related_edges": len(edges), "edges_per_node": round(len(edges) / n, 3),
  115. "linked_nodes": len(linked), "isolated_pct": round(100 * (n - len(linked)) / n, 1), "categories": len(cats),
  116. "agent_created": sum(1 for x in nodes.values() if x.created_by == "agent"),
  117. "used": sum(1 for x in nodes.values() if x.use_count > 0),
  118. "top_categories": sorted(cats.items(), key=lambda kv: -kv[1])[:8],
  119. }
  120. def memory_fingerprint(entry: str) -> str:
  121. """Short stable digest of a memory entry's TEXT, carried in the node id.
  122. A journey card is identified by what it says, not by where it sat: an earlier entry can be
  123. removed (an agent ``memory_tool`` remove mid-turn, a Journey delete without a refetch)
  124. between the graph being drawn and the user submitting an edit, and a bare index then names
  125. somebody else's card (#119668).
  126. Cards and the mutation path both read entries through ``MemoryStore._read_file``, so the
  127. same entry digests the same on both sides (a BOM'd file included).
  128. """
  129. return hashlib.sha256(entry.strip().encode("utf-8")).hexdigest()[:12]
  130. def memory_node_id(card: dict[str, Any], index: int) -> str:
  131. """``memory:<source>:<index>:<fingerprint>`` — position for the occurrence, text for identity."""
  132. return f"memory:{card['source']}:{index}:{card['fingerprint']}"
  133. def _memory_cards() -> list[dict[str, Any]]:
  134. """``MEMORY.md`` / ``USER.md`` entries as the memory tool parses them; every
  135. entry becomes one card (MEMORY.md cards first, then USER.md)."""
  136. from tools.memory_tool import MemoryStore
  137. base = get_hermes_home() / "memories"
  138. cards: list[dict[str, Any]] = []
  139. for fname, source in (("MEMORY.md", "memory"), ("USER.md", "profile")):
  140. path = base / fname
  141. try:
  142. file_ts = _to_int_ts(path.stat().st_mtime)
  143. except OSError:
  144. continue
  145. # The store's own parser (utf-8-sig, same delimiter): a hand-rolled split kept a Notepad
  146. # BOM glued to the first entry, so its fingerprint never matched the store's and the card
  147. # was "stale" forever.
  148. for chunk_idx, chunk in enumerate(MemoryStore._read_file(path)):
  149. first = chunk.splitlines()[0].strip().lstrip("# ").strip()
  150. cards.append({
  151. "source": source, "timestamp": file_ts + chunk_idx if file_ts is not None else None,
  152. "title": (first[:80] + "…") if len(first) > 80 else first, "body": chunk[:1200],
  153. # Digest the WHOLE chunk, not the truncated ``body`` a long memory renders with.
  154. "fingerprint": memory_fingerprint(chunk),
  155. })
  156. return cards
  157. def _tokenize(text: str) -> set[str]:
  158. return {t for t in re.split(r"[^a-z0-9]+", text.lower()) if len(t) >= 3}
  159. def _memory_skill_edges(memory_cards: list[dict[str, Any]], skills: list[SkillNode]) -> list[tuple[str, str]]:
  160. """Top-4 lexically overlapping skills per memory card (name hit weighs 6)."""
  161. edges: list[tuple[str, str]] = []
  162. skill_meta = [(s.name, _tokenize(s.name), s.name.lower()) for s in skills]
  163. for idx, card in enumerate(memory_cards):
  164. text = f"{card.get('title', '')}\n{card.get('body', '')}".lower()
  165. text_tokens = _tokenize(text)
  166. scored = sorted(
  167. ((score, name) for name, tokens, name_lower in skill_meta if (score := (6 if name_lower in text else 0) + len(tokens & text_tokens)) > 0),
  168. key=lambda x: (-x[0], x[1]),
  169. )
  170. edges.extend((memory_node_id(card, idx), name) for _, name in scored[:4])
  171. return edges
  172. def _has_learning_signal(node: SkillNode) -> bool:
  173. """Graph-worthy: agent-created, user-taught (/learn), or actually used.
  174. ``created_by="learn"`` is a learning-signal marker only — curator management stays keyed
  175. strictly on ``"agent"`` (see ``tools.skill_usage._is_curator_managed_record``). External
  176. mounts are never a learning milestone: they were configured by the user, not learned, so
  177. even a used external skill stays out of the journey graph (#108032).
  178. """
  179. return node.source != "external" and (node.created_by in {"agent", "learn"} or node.use_count > 0)
  180. def build_learning_graph() -> dict[str, Any]:
  181. """Full payload for the desktop learning panel: non-base skills with real
  182. learning signal (agent-created or used) plus memory chunks as graph nodes."""
  183. roots = [("base", Path(__file__).resolve().parent.parent / "skills"), ("profile", get_hermes_home() / "skills")]
  184. learned_skills = {
  185. name: node for name, node in build_skill_nodes(roots).items()
  186. if node.source != "base" and _has_learning_signal(node)
  187. }
  188. skill_edges, memory_cards = build_edges(learned_skills), _memory_cards()
  189. memory_edges = _memory_skill_edges(memory_cards, list(learned_skills.values()))
  190. clusters = Counter(node.category for node in learned_skills.values())
  191. if memory_cards:
  192. clusters["memory"] = len(memory_cards)
  193. graph_nodes = [
  194. {
  195. "id": n.name, "label": n.name, "kind": "skill", "timestamp": n.timestamp, "category": n.category,
  196. "useCount": n.use_count, "state": n.state, "createdBy": n.created_by, "pinned": n.pinned,
  197. }
  198. for n in learned_skills.values()
  199. ] + [
  200. {
  201. "id": memory_node_id(card, i), "label": card["title"], "kind": "memory",
  202. "memorySource": card["source"], "timestamp": card.get("timestamp"), "category": "memory",
  203. "useCount": 0, "state": "active", "createdBy": "memory", "pinned": False,
  204. }
  205. for i, card in enumerate(memory_cards)
  206. ]
  207. return {
  208. "nodes": graph_nodes,
  209. "edges": [{"source": a, "target": b} for a, b in skill_edges + memory_edges],
  210. "clusters": [{"category": c, "count": n} for c, n in sorted(clusters.items(), key=lambda kv: -kv[1])],
  211. "memory": memory_cards,
  212. "stats": {
  213. **density_stats(learned_skills, skill_edges),
  214. "memory_nodes": len(memory_cards), "memory_skill_edges": len(memory_edges), "learned_skills": len(learned_skills),
  215. },
  216. }