186 lines
6.8 KiB
Python
186 lines
6.8 KiB
Python
"""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"<!-- lessons:begin -->.*<!-- lessons:end -->", 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"<!-- lessons:begin -->\n{table}\n<!-- lessons:end -->", 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
|