"""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 app.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