Capture, distil, review, publish, retire (ADR-0004). Lesson candidates of past Executions are grouped into what recurred; a lesson-curator role, outside any Execution, proposes a lesson per group worth one; each proposal is an issue file a person approves or rejects; an approved lesson is written into the provider's lessons Skill, which a Specialist is given only once it holds lessons for that Specialist's Deliverable. LESSONS_ENABLED off runs without them, for an evaluation with and without. The curator proposed six lessons from 21 Executions. The owner approved all six on 2026-10-09 and they are published: five for the target architect, one for the IaC author. None is proved by an evaluation yet. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
165 lines
5.3 KiB
Python
165 lines
5.3 KiB
Python
"""The lesson curator: proposes a lesson for each recurring problem worth one.
|
|
|
|
It runs outside any Execution, on the evidence of many. It only proposes: every
|
|
proposal is written as an issue file for a person to decide (ADR-0004).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from collections.abc import Sequence
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
from app.adk.runtime import (
|
|
AgentRuntime,
|
|
AgentTask,
|
|
RoleSpec,
|
|
ToolResult,
|
|
ToolSpec,
|
|
TurnEnded,
|
|
)
|
|
from app.learning.evidence import Group
|
|
from app.learning.proposals import ISSUES, Proposal, load, propose
|
|
from app.workflows.deliverables import DeliverableKind
|
|
|
|
LESSON_CURATOR = "lesson-curator"
|
|
MAX_GROUPS = 25
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
def _evidence(group: Group, executions: int) -> str:
|
|
return (
|
|
f"Seen in {len(group.executions)} of {executions} Executions, "
|
|
f"{group.occurrences} times in all: {group.description}."
|
|
)
|
|
|
|
|
|
async def curate(
|
|
runtime: AgentRuntime,
|
|
role: RoleSpec,
|
|
groups: Sequence[Group],
|
|
*,
|
|
executions: int,
|
|
identifiers: set[str] = frozenset(), # type: ignore[assignment]
|
|
folder: Path = ISSUES,
|
|
) -> list[Proposal]:
|
|
"""Run the curator over the groups that have no proposal yet; return what it
|
|
proposed. Groups it judged not worth a lesson are left for the next run."""
|
|
existing = load(folder)
|
|
decided = {proposal.evidence_key for proposal in existing}
|
|
fresh = [group for group in groups if group.key not in decided][:MAX_GROUPS]
|
|
if not fresh:
|
|
return []
|
|
by_key = {group.key: group for group in fresh}
|
|
kinds = [kind.value for kind in DeliverableKind]
|
|
proposed: list[Proposal] = []
|
|
declined: dict[str, str] = {}
|
|
|
|
async def propose_lesson(
|
|
group: str, deliverable: str, title: str, rule: str, reason: str
|
|
) -> ToolResult:
|
|
if group not in by_key:
|
|
return ToolResult(f"Refused: {group} is not one of the groups given.")
|
|
if deliverable not in kinds:
|
|
return ToolResult(
|
|
f"Refused: deliverable must be one of {', '.join(kinds)}."
|
|
)
|
|
if any(p.evidence_key == group for p in proposed):
|
|
return ToolResult(f"Refused: {group} already has a proposal.")
|
|
text = f"{title} {rule} {reason}"
|
|
leaked = sorted(name for name in identifiers if name in text)
|
|
if leaked:
|
|
return ToolResult(
|
|
"Refused: a lesson carries no client or Execution detail; remove "
|
|
+ ", ".join(leaked)
|
|
)
|
|
if not (title.strip() and rule.strip() and reason.strip()):
|
|
return ToolResult("Refused: a lesson needs a title, a rule and a reason.")
|
|
proposal = propose(
|
|
title=title,
|
|
deliverable=deliverable,
|
|
rule=rule,
|
|
reason=reason,
|
|
evidence=_evidence(by_key[group], executions),
|
|
evidence_key=group,
|
|
folder=folder,
|
|
)
|
|
proposed.append(proposal)
|
|
return ToolResult(f"Proposed {proposal.id} for a person to review.")
|
|
|
|
async def no_lesson(group: str, why: str) -> ToolResult:
|
|
if group not in by_key:
|
|
return ToolResult(f"Refused: {group} is not one of the groups given.")
|
|
declined[group] = why
|
|
return ToolResult(f"Noted: no lesson for {group}.")
|
|
|
|
async def finish() -> ToolResult:
|
|
return ToolResult("Done.", TurnEnded("finish"))
|
|
|
|
text = {"type": "string"}
|
|
tools = [
|
|
ToolSpec(
|
|
"propose_lesson",
|
|
"Propose one lesson for a group. A person reviews it before any agent "
|
|
"sees it.",
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"group": text,
|
|
"deliverable": {"type": "string", "enum": kinds},
|
|
"title": text,
|
|
"rule": text,
|
|
"reason": text,
|
|
},
|
|
"required": ["group", "deliverable", "title", "rule", "reason"],
|
|
},
|
|
propose_lesson,
|
|
tier="execution",
|
|
),
|
|
ToolSpec(
|
|
"no_lesson",
|
|
"Say that a group is not worth a lesson, and why.",
|
|
{
|
|
"type": "object",
|
|
"properties": {"group": text, "why": text},
|
|
"required": ["group", "why"],
|
|
},
|
|
no_lesson,
|
|
tier="execution",
|
|
),
|
|
ToolSpec(
|
|
"finish",
|
|
"End your turn once every group has a proposal or a reason for none.",
|
|
{"type": "object", "properties": {}},
|
|
finish,
|
|
tier="execution",
|
|
),
|
|
]
|
|
context: dict[str, Any] = {
|
|
"executions": executions,
|
|
"groups": [group.as_context() for group in fresh],
|
|
"published_or_proposed": [
|
|
{
|
|
"id": p.id,
|
|
"deliverable": p.deliverable,
|
|
"rule": p.rule,
|
|
"status": p.status,
|
|
}
|
|
for p in existing
|
|
],
|
|
}
|
|
await runtime.run(
|
|
role,
|
|
AgentTask(
|
|
role=role.name,
|
|
prompt="Propose lessons from what recurred across these Executions.",
|
|
context=context,
|
|
),
|
|
tools,
|
|
)
|
|
for group, why in declined.items():
|
|
logger.info("no lesson for %s: %s", group, why)
|
|
return proposed
|