"""The lessons Skill: where approved lessons are published, and retired from. A lessons Skill is an ordinary Agent Skill, per Cloud provider, that the provider bundle names. It has one reference file per Deliverable that has lessons, so a Specialist reads only the lessons for its own work. Both the reference files and the index in SKILL.md are written here, from approved proposals, and never by hand. """ from __future__ import annotations import json import re from collections.abc import Mapping from dataclasses import replace from datetime import UTC, date, datetime from pathlib import Path from execution_engine.learning.proposals import Proposal, write REFERENCES = "references" _INDEX = re.compile(r".*", re.DOTALL) _ENTRY = re.compile(r"^## (L-\d+): .*?(?=^## L-\d+: |\Z)", re.MULTILINE | re.DOTALL) class NotApproved(ValueError): """A lesson cannot be published: no person has approved its proposal.""" def reference(skill_dir: Path, deliverable: str) -> Path: return skill_dir / REFERENCES / f"{deliverable}.md" def deliverables_with_lessons(skill_dir: Path) -> list[str]: folder = skill_dir / REFERENCES if not folder.is_dir(): return [] return sorted( path.stem for path in folder.glob("*.md") if _ENTRY.search(path.read_text(encoding="utf-8")) ) def published(skill_dir: Path) -> dict[str, str]: """Lesson id -> the Deliverable whose reference holds it.""" found = {} for deliverable in deliverables_with_lessons(skill_dir): text = reference(skill_dir, deliverable).read_text(encoding="utf-8") for match in _ENTRY.finditer(text): found[match.group(1)] = deliverable return found def _entry(proposal: Proposal, today: str) -> str: return ( f"## {proposal.id}: {proposal.title}\n\n" f"**Rule.** {' '.join(proposal.rule.split())}\n\n" f"**Why.** {' '.join(proposal.reason.split())}\n\n" f"Published {today}, from lesson proposal {proposal.number:02d}.\n" ) def _write_reference(skill_dir: Path, deliverable: str, entries: list[str]) -> None: path = reference(skill_dir, deliverable) if not entries: path.unlink(missing_ok=True) return path.parent.mkdir(parents=True, exist_ok=True) title = deliverable.replace("_", " ") path.write_text( f"# Lessons: {title}\n\n" "Rules learned from earlier work. Follow every one that applies.\n\n" + "\n".join(entries), encoding="utf-8", ) def _entries(skill_dir: Path, deliverable: str) -> dict[str, str]: path = reference(skill_dir, deliverable) if not path.is_file(): return {} text = path.read_text(encoding="utf-8") return {m.group(1): m.group(0).rstrip() + "\n" for m in _ENTRY.finditer(text)} def _reindex(skill_dir: Path) -> None: """Rewrite the list of references in SKILL.md from the files that exist.""" skill = skill_dir / "SKILL.md" rows = [ f"| {name.replace('_', ' ')} | `{REFERENCES}/{name}.md` | " f"{len(_entries(skill_dir, name))} |" for name in deliverables_with_lessons(skill_dir) ] table = ( "| Deliverable | Reference | Lessons |\n| --- | --- | --- |\n" + "\n".join(rows) if rows else "No lessons have been published yet." ) text = skill.read_text(encoding="utf-8") skill.write_text( _INDEX.sub(f"\n{table}\n", text), encoding="utf-8", ) def publish( proposal: Proposal, skill_dir: Path, *, today: date | None = None ) -> Proposal: """Write an approved lesson into the Skill and mark its proposal published. Raises NotApproved for any proposal a person has not approved: nothing reaches an agent on a curator's say-so. """ if proposal.retired: raise NotApproved(f"{proposal.id} was retired on {proposal.retired}") if not proposal.approved: raise NotApproved( f"{proposal.id} is {proposal.status}; a person approves a lesson by " "setting its Status to ready-for-agent" ) if not proposal.deliverable or not proposal.rule.strip(): raise NotApproved(f"{proposal.id} has no Deliverable or no rule") stamp = (today or datetime.now(UTC).date()).isoformat() for deliverable in deliverables_with_lessons(skill_dir): if deliverable != proposal.deliverable: entries = _entries(skill_dir, deliverable) if entries.pop(proposal.id, None): # it moved to another Deliverable _write_reference(skill_dir, deliverable, list(entries.values())) entries = _entries(skill_dir, proposal.deliverable) entries[proposal.id] = _entry(proposal, stamp) ordered = [entries[key] for key in sorted(entries)] _write_reference(skill_dir, proposal.deliverable, ordered) _reindex(skill_dir) return write(replace(proposal, published=proposal.published or stamp)) # The versions of the Skills the lessons were written beside, kept in the lessons # Skill. A lesson is a correction to how agents follow those Skills, so when one # of them changes each lesson is worth a second look: it may now be said upstream, # or contradict it. UPSTREAM_FILE = "upstream.json" def upstream_reviewed(skill_dir: Path) -> dict[str, str]: """The upstream Skill versions the lessons were last reviewed against.""" path = skill_dir / UPSTREAM_FILE if not path.is_file(): return {} try: data = json.loads(path.read_text(encoding="utf-8")) except ValueError: return {} return {str(k): str(v) for k, v in data.items()} if isinstance(data, dict) else {} def mark_reviewed(skill_dir: Path, current: Mapping[str, str]) -> None: """Record that the lessons stand against these upstream Skill versions.""" (skill_dir / UPSTREAM_FILE).write_text( json.dumps(dict(sorted(current.items())), indent=2) + "\n", encoding="utf-8" ) def upstream_changes(skill_dir: Path, current: Mapping[str, str]) -> list[str]: """The upstream Skills that changed, appeared or went since the lessons were last reviewed. Empty when there are no lessons, or nothing was ever recorded.""" reviewed = upstream_reviewed(skill_dir) if not reviewed or not published(skill_dir): return [] return sorted( name for name in set(reviewed) | set(current) if reviewed.get(name) != current.get(name) ) def retire(lesson_id: str, skill_dir: Path) -> bool: """Remove a lesson from the Skill. Returns whether it was there.""" deliverable = published(skill_dir).get(lesson_id) if deliverable is None: return False entries = _entries(skill_dir, deliverable) entries.pop(lesson_id) _write_reference(skill_dir, deliverable, [entries[key] for key in sorted(entries)]) _reindex(skill_dir) return True