blueprints.py 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215
  1. """Blueprints: shareable plain-language automations layered on skills + cron.
  2. A blueprint is NOT a new object type: it is an ordinary skill whose frontmatter declares
  3. ``metadata.hermes.blueprint`` (``schedule`` required; optional ``deliver`` [default "origin"],
  4. ``prompt``, ``no_agent``, ``model``, ``provider``, ``enabled_toolsets``), so it rides the whole
  5. skills-hub pipeline for free. This module only bridges that block to cron ``create_job()``,
  6. plus the inverse (``export_blueprint``) back to a SKILL.md.
  7. """
  8. from __future__ import annotations
  9. import logging
  10. from dataclasses import dataclass, field
  11. from pathlib import Path
  12. from typing import Any, Dict, List, Optional
  13. logger = logging.getLogger(__name__)
  14. __all__ = [
  15. "BlueprintError",
  16. "BlueprintSpec",
  17. "blueprint_spec_for_installed",
  18. "blueprint_to_job_spec",
  19. "create_blueprint_job",
  20. "export_blueprint",
  21. "parse_blueprint",
  22. "register_blueprint_suggestion",
  23. ]
  24. class BlueprintError(ValueError):
  25. """Raised when a blueprint block is present but malformed."""
  26. @dataclass
  27. class BlueprintSpec:
  28. """Parsed ``metadata.hermes.blueprint`` automation spec for a skill."""
  29. skill_name: str
  30. schedule: str
  31. deliver: str = "origin"
  32. prompt: Optional[str] = None
  33. no_agent: bool = False
  34. model: Optional[str] = None
  35. provider: Optional[str] = None
  36. enabled_toolsets: Optional[list[str]] = None
  37. raw: dict[str, Any] = field(default_factory=dict)
  38. def _split_frontmatter(text: str) -> Optional[dict[str, Any]]:
  39. """Return the parsed YAML frontmatter mapping, or None if absent/invalid."""
  40. if not isinstance(text, str):
  41. return None
  42. stripped = text.lstrip("\ufeff").lstrip() # BOM is not whitespace; strip explicitly
  43. if not stripped.startswith("---") or (end := stripped.find("\n---", 3)) == -1:
  44. return None
  45. try:
  46. import hermes_yaml as yaml
  47. data = yaml.safe_load(stripped[3:end])
  48. except Exception as e: # pragma: no cover - malformed YAML
  49. logger.debug("blueprint: frontmatter YAML parse failed: %s", e)
  50. return None
  51. return data if isinstance(data, dict) else None
  52. def parse_blueprint(skill_md_text: str) -> Optional[BlueprintSpec]:
  53. """Extract a BlueprintSpec from a SKILL.md string, or None if not a blueprint.
  54. A skill is a blueprint iff ``metadata.hermes.blueprint`` is a mapping with a
  55. non-empty ``schedule``. Raises BlueprintError if the block exists but is
  56. structurally invalid (so a typo surfaces instead of silently no-op'ing).
  57. """
  58. fm = _split_frontmatter(skill_md_text)
  59. if not fm:
  60. return None
  61. meta = fm.get("metadata")
  62. hermes = meta.get("hermes") if isinstance(meta, dict) else None
  63. blueprint = hermes.get("blueprint") if isinstance(hermes, dict) else None
  64. if blueprint is None:
  65. return None
  66. if not isinstance(blueprint, dict):
  67. raise BlueprintError("metadata.hermes.blueprint must be a mapping")
  68. schedule = str(blueprint.get("schedule", "")).strip()
  69. if not schedule:
  70. raise BlueprintError("blueprint.schedule is required and must be non-empty")
  71. prompt, model, provider = blueprint.get("prompt"), blueprint.get("model"), blueprint.get("provider")
  72. toolsets = blueprint.get("enabled_toolsets")
  73. if toolsets is not None and not isinstance(toolsets, list):
  74. raise BlueprintError("blueprint.enabled_toolsets must be a list when present")
  75. return BlueprintSpec(
  76. skill_name=str(fm.get("name", "")).strip(), schedule=schedule,
  77. deliver=str(blueprint.get("deliver", "origin")).strip() or "origin",
  78. prompt=str(prompt) if prompt is not None else None,
  79. no_agent=bool(blueprint.get("no_agent", False)),
  80. model=str(model).strip() if model else None,
  81. provider=str(provider).strip() if provider else None,
  82. enabled_toolsets=[str(t) for t in toolsets] if toolsets else None,
  83. raw=blueprint,
  84. )
  85. def blueprint_spec_for_installed(skill_name: str) -> Optional[BlueprintSpec]:
  86. """Find ``<skill_name>/SKILL.md`` anywhere in the skills tree and parse its
  87. blueprint block; None when not found or not a blueprint."""
  88. try:
  89. from tools.skills_hub import SKILLS_DIR
  90. except Exception: # pragma: no cover - import guard
  91. return None
  92. # Skills live at skills/<category>/<name>/SKILL.md or skills/<name>/SKILL.md.
  93. for path in Path(SKILLS_DIR).glob(f"**/{skill_name}/SKILL.md"):
  94. try:
  95. spec = parse_blueprint(path.read_text(encoding="utf-8-sig"))
  96. except OSError:
  97. continue
  98. if spec is not None:
  99. spec.skill_name = spec.skill_name or skill_name # frontmatter name wins over dir name
  100. return spec
  101. return None
  102. def blueprint_to_job_spec(spec: BlueprintSpec, *, name: Optional[str] = None) -> dict[str, Any]:
  103. """``cron.jobs.create_job`` kwargs for a spec — the single translation used by
  104. both ``create_blueprint_job`` and the suggestion path so they never drift."""
  105. return {
  106. "prompt": spec.prompt, "schedule": spec.schedule, "name": name or f"blueprint:{spec.skill_name}",
  107. "deliver": spec.deliver, "skills": [spec.skill_name] if spec.skill_name else None,
  108. "model": spec.model, "provider": spec.provider, "enabled_toolsets": spec.enabled_toolsets,
  109. "no_agent": spec.no_agent,
  110. }
  111. def create_blueprint_job(spec: BlueprintSpec, *, origin: Optional[dict[str, Any]] = None,
  112. name: Optional[str] = None) -> dict[str, Any]:
  113. """Create the cron job for a spec (skill preloaded via ``skills=[name]``); returns the job dict."""
  114. from cron.scheduler import create_job_with_scheduler_registration
  115. job_spec = blueprint_to_job_spec(spec, name=name)
  116. if origin is not None:
  117. job_spec["origin"] = origin
  118. return create_job_with_scheduler_registration(**job_spec)
  119. def register_blueprint_suggestion(spec: BlueprintSpec) -> Optional[dict[str, Any]]:
  120. """Register an installed blueprint as a Suggested Cron Job (never auto-scheduled;
  121. the user accepts or dismisses it). None when skipped (seen/dismissed/backlog full)."""
  122. if not spec.skill_name:
  123. return None
  124. try:
  125. from cron.suggestions import add_suggestion
  126. except Exception: # pragma: no cover - import guard
  127. return None
  128. deliver = f", delivering to {spec.deliver}" if spec.deliver and spec.deliver != "origin" else ""
  129. return add_suggestion(
  130. title=f"Schedule '{spec.skill_name}'",
  131. description=f"The '{spec.skill_name}' blueprint runs on schedule {spec.schedule}{deliver}.",
  132. source="blueprint",
  133. job_spec=blueprint_to_job_spec(spec),
  134. dedup_key=f"blueprint:{spec.skill_name}:{spec.schedule}",
  135. )
  136. def export_blueprint(job: dict[str, Any], body: str, *, blueprint_name: Optional[str] = None) -> str:
  137. """Inverse of ``create_blueprint_job``: render a cron job as a SKILL.md (with a
  138. ``metadata.hermes.blueprint`` block) ready for ``hermes skills publish``.
  139. ``body`` becomes the SKILL.md body; its first line is the description."""
  140. import hermes_yaml as yaml
  141. # Sanitize to a valid skill identifier.
  142. name = str(blueprint_name or job.get("name") or "shared-blueprint").lower()
  143. name = "".join(c if (c.isalnum() or c in "-_") else "-" for c in name).strip("-_") or "shared-blueprint"
  144. block: dict[str, Any] = {"schedule": job.get("schedule_display") or _schedule_to_string(job.get("schedule"))}
  145. if job.get("deliver") and job["deliver"] != "origin":
  146. block["deliver"] = job["deliver"]
  147. if job.get("prompt"):
  148. block["prompt"] = job["prompt"]
  149. if job.get("no_agent"):
  150. block["no_agent"] = True
  151. block.update({k: job[k] for k in ("model", "provider", "enabled_toolsets") if job.get(k)})
  152. body = body.strip()
  153. frontmatter = {
  154. "name": name, "description": body.splitlines()[0][:200] if body else "Shared automation blueprint.",
  155. "version": "1.0.0", "license": "MIT",
  156. "metadata": {"hermes": {"tags": ["blueprint", "automation"], "blueprint": block}},
  157. }
  158. fm_yaml = yaml.safe_dump(frontmatter, sort_keys=False, allow_unicode=True).strip()
  159. body_text = body or f"# {name}\n\nShared automation blueprint."
  160. return f"---\n{fm_yaml}\n---\n\n{body_text}\n"
  161. def _schedule_to_string(schedule: Any) -> str:
  162. """Best-effort render of a parsed schedule dict back to a string."""
  163. if isinstance(schedule, str):
  164. return schedule
  165. if isinstance(schedule, dict):
  166. kind = schedule.get("kind")
  167. if kind == "cron" and schedule.get("expr"):
  168. return str(schedule["expr"])
  169. if kind == "interval":
  170. # parse_schedule stores interval periods as "minutes"; tolerate a legacy/foreign "seconds" form too.
  171. if schedule.get("minutes"):
  172. mins = int(schedule["minutes"])
  173. return f"every {mins // 60}h" if mins % 60 == 0 else f"every {mins}m"
  174. if schedule.get("seconds"):
  175. secs = int(schedule["seconds"])
  176. return (f"every {secs // 3600}h" if secs % 3600 == 0
  177. else f"every {secs // 60}m" if secs % 60 == 0 else f"every {secs}s")
  178. return "0 9 * * *" # safe daily fallback