Files
gcp_solution_architecture_a…/app/learning/curator.py
Jonathan Boniface a7bc5310f3 feat: the lessons loop, and six lessons approved and published
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>
2026-10-09 15:19:32 +01:00

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