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