suggestion_catalog.py 6.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143
  1. """Curated catalog of starter cron-job suggestions.
  2. These are the built-in automations Hermes can offer a new user out of the box — the ``catalog``
  3. source of the unified suggestion surface. Each entry is a ready-to-run ``cron.jobs.create_job`` spec
  4. wrapped as a suggestion; the user accepts via ``/suggestions``. Nothing here auto-schedules.
  5. The "important-mail monitor" entry (``classify_items.py``: poll -> LLM-score urgency -> surface
  6. above-threshold) is ONE catalog automation, not a standalone feature. New entries: append a
  7. CatalogEntry with a self-contained prompt (cron jobs run with no chat context).
  8. """
  9. from __future__ import annotations
  10. from dataclasses import dataclass
  11. from pathlib import Path
  12. from typing import Any, Callable, Dict, List, Optional
  13. __all__ = ["CATALOG", "CatalogEntry", "classify_items_script_path", "seed_catalog_suggestions"]
  14. def classify_items_script_path() -> str:
  15. """Absolute path to the urgency classifier script shipped with cron/."""
  16. return str(Path(__file__).resolve().parent / "scripts" / "classify_items.py")
  17. @dataclass(frozen=True)
  18. class CatalogEntry:
  19. """A curated starter automation offered as a suggestion."""
  20. key: str # stable dedup key (never re-offered once dismissed)
  21. title: str
  22. description: str
  23. job_spec: dict[str, Any] # kwargs for cron.jobs.create_job
  24. # The curated set. Schedules use the cron/interval syntax create_job accepts.
  25. CATALOG: list[CatalogEntry] = [
  26. CatalogEntry(
  27. key="catalog:daily-briefing",
  28. title="Daily briefing",
  29. description="Every morning at 8am, a short briefing: today's calendar, "
  30. "weather, and anything urgent waiting on you.",
  31. job_spec={
  32. "prompt": (
  33. "Produce a concise morning briefing for the user: today's "
  34. "calendar events, the local weather, and any urgent items "
  35. "(unread important email, due tasks). Keep it short and "
  36. "scannable. If you have no connected data sources, give a brief "
  37. "general good-morning with the date and offer to connect "
  38. "calendar/email."
  39. ),
  40. "schedule": "0 8 * * *",
  41. "name": "Daily briefing",
  42. "deliver": "origin",
  43. },
  44. ),
  45. CatalogEntry(
  46. key="catalog:important-mail-monitor",
  47. title="Important-mail monitor",
  48. description="Check your inbox periodically and ping you ONLY about mail "
  49. "that actually needs attention — never the newsletters.",
  50. job_spec={
  51. "prompt": (
  52. "Check the user's inbox for new messages since the last run. "
  53. "For each candidate, judge urgency against this rule: surface "
  54. "only mail that needs a reply today, is from a manager/family "
  55. "member, or mentions a deadline. Pipe candidates through the "
  56. "urgency classifier (run `python3 -m cron.scripts.classify_items "
  57. "--threshold 7 --criteria ...` from the hermes-agent install — "
  58. "resolve the script path at run time, do not assume a fixed "
  59. "location) and deliver ONLY what it returns. If nothing "
  60. "clears the bar, respond with [SILENT] so the user is not "
  61. "pinged. Requires a connected mail source; if none is "
  62. "configured, explain how to connect one and then stop."
  63. ),
  64. "schedule": "every 30m",
  65. "name": "Important-mail monitor",
  66. "deliver": "origin",
  67. },
  68. ),
  69. CatalogEntry(
  70. key="catalog:weekly-review",
  71. title="Weekly review",
  72. description="Every Sunday evening, a recap of the week: what got done, "
  73. "what's still open, and what's coming up next week.",
  74. job_spec={
  75. "prompt": (
  76. "Produce a weekly review for the user: summarize what was "
  77. "accomplished this week, list still-open items, and preview "
  78. "next week's calendar. Pull from whatever sources are connected "
  79. "(calendar, task tools, recent conversations). Keep it tight."
  80. ),
  81. "schedule": "0 18 * * 0",
  82. "name": "Weekly review",
  83. "deliver": "origin",
  84. },
  85. ),
  86. CatalogEntry(
  87. key="catalog:standup-reminder",
  88. title="Workday start reminder",
  89. description="A weekday nudge at 9am with your day's agenda and top "
  90. "priorities, so you start focused.",
  91. job_spec={
  92. "prompt": (
  93. "Give the user a brief weekday start-of-day nudge: their "
  94. "calendar for today and the 1-3 highest-priority things to "
  95. "focus on, inferred from recent context and any task tools. "
  96. "Encouraging, short, one message."
  97. ),
  98. "schedule": "0 9 * * 1-5",
  99. "name": "Workday start reminder",
  100. "deliver": "origin",
  101. },
  102. ),
  103. ]
  104. def seed_catalog_suggestions(
  105. *, add_fn: Optional[Callable[..., Optional[dict[str, Any]]]] = None,
  106. keys: Optional[list[str]] = None,
  107. ) -> list[dict[str, Any]]:
  108. """Register catalog entries as pending suggestions.
  109. ``add_fn`` defaults to ``cron.suggestions.add_suggestion`` (injectable for tests). ``keys``
  110. restricts to specific catalog entries; omit to seed all. Entries already dismissed/accepted (by
  111. dedup key) or beyond the pending cap are skipped by the store, so re-seeding is safe and
  112. idempotent. Returns the list of suggestion records actually created.
  113. """
  114. if add_fn is None:
  115. from cron.suggestions import add_suggestion as add_fn # type: ignore[assignment]
  116. wanted = set(keys) if keys else None
  117. created: list[dict[str, Any]] = []
  118. for entry in CATALOG:
  119. if wanted is not None and entry.key not in wanted:
  120. continue
  121. rec = add_fn(
  122. title=entry.title, description=entry.description, source="catalog",
  123. job_spec=dict(entry.job_spec), dedup_key=entry.key,
  124. )
  125. if rec is not None:
  126. created.append(rec)
  127. return created