Files
gcp_solution_architecture_a…/app/adk/roles.py
Jonathan Boniface e5e1647ff1
Some checks failed
validation / verify (push) Failing after 13s
feat: prove the lessons, check overlays in evaluation, and settle the cost steps
- Schema review: a dotted path is judged only when it starts at a name the
  resource type has, so a database flag or a service name is no longer read
  as a missing setting. Lesson L-04, which worked around that, is retired.
- Skill routing: in a Change request the question says what changed.
- Evaluation: a case may list code_standards the infrastructure code must
  meet; case 06 checks its overlay's regions, naming and labels.
- Model tiers (iteration 5 step 6): a lighter model for a role's first
  attempt, named in the provider bundle. Measured on case 03 and left off:
  Flash saved five cents on the IaC author and took twice the requests.
- Steps 7 and 9 decided against on the numbers, recorded in the plans.
- Plans: the runs of cases 05 and 06, and the first proof of the lessons on
  case 03 (no Revision, 22 minutes against 28, quality held).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 21:27:09 +01:00

164 lines
5.9 KiB
Python

"""Load role files (agents/<role>.md) into RoleSpecs for one Cloud provider.
Role files are framework- and provider-neutral: frontmatter names the role, the
Deliverable it owns, the local tools it uses, an optional budget and shared partials to
include. The provider bundle supplies each role's Skills, MCP servers and model.
"""
from __future__ import annotations
import dataclasses
from pathlib import Path
from app.adk.runtime import RoleSpec
from app.providers import ProviderBundle
from app.skills.agent_skills import SkillFormatError, split_frontmatter
from app.workflows.deliverables import DEPENDENCY_GRAPH, DeliverableKind
ORCHESTRATOR = "orchestrator"
PILLAR_ADVISOR = "pillar-advisor"
REPLY_WRITER = "reply-writer"
LESSON_CURATOR = "lesson-curator" # runs outside any Execution
PARTIALS_DIR = "partials"
_ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"}
def _deliverables_with_lessons(bundle: ProviderBundle) -> set[str]:
if not bundle.lessons_skill:
return set()
folder = bundle.skills[bundle.lessons_skill].path / "references"
return {path.stem for path in folder.glob("*.md")} if folder.is_dir() else set()
class RoleConfigError(ValueError):
"""A role file is missing or invalid."""
def load_roles(
agents_dir: Path,
bundle: ProviderBundle,
*,
orchestrator_budget: int = 40,
specialist_budget: int = 15,
include_preview_mcp: bool = True,
lessons: bool = True,
model_tiers: bool = False,
) -> dict[str, RoleSpec]:
"""`lessons` off leaves the lessons Skill out of every role, so an evaluation
can run with and without what has been learned. `model_tiers` on gives a role
the lighter model the bundle names for its first attempt."""
specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()}
required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists}
optional = {LESSON_CURATOR}
learned = _deliverables_with_lessons(bundle) if lessons else set()
roles = {}
for path in sorted(agents_dir.glob("*.md")):
role = _load_role(
path,
agents_dir,
bundle,
specialists,
orchestrator_budget if path.stem == ORCHESTRATOR else specialist_budget,
include_preview_mcp,
)
roles[role.name] = role
missing = sorted(required - set(roles))
if missing:
raise RoleConfigError(
f"{agents_dir}: missing role files for {', '.join(missing)}"
)
for name, kind in specialists.items():
if kind.value in learned and bundle.lessons_skill:
# Only a Specialist whose Deliverable has lessons is given the Skill.
roles[name] = dataclasses.replace(
roles[name], skills=(*roles[name].skills, bundle.lessons_skill)
)
if model_tiers:
for name, model in bundle.models.first_attempt.items():
if name not in roles:
raise RoleConfigError(
f"'models.first_attempt' names {name!r}, which is not a role"
)
roles[name] = dataclasses.replace(roles[name], first_attempt_model=model)
unexpected = sorted(set(roles) - required - optional)
if unexpected:
raise RoleConfigError(
f"{agents_dir}: unexpected role files {', '.join(unexpected)}"
)
return roles
def _load_role(
path: Path,
agents_dir: Path,
bundle: ProviderBundle,
specialists: dict[str, DeliverableKind],
default_budget: int,
include_preview_mcp: bool,
) -> RoleSpec:
try:
frontmatter, body = split_frontmatter(path.read_text(encoding="utf-8"), path)
except SkillFormatError as exc:
raise RoleConfigError(str(exc)) from exc
def fail(message: str) -> RoleConfigError:
return RoleConfigError(f"{path}: {message}")
unknown = sorted(set(frontmatter) - _ALLOWED_FIELDS)
if unknown:
raise fail(
f"unsupported fields {', '.join(unknown)}; skills, MCP servers and models "
"come from the provider bundle"
)
name = frontmatter.get("role")
if name != path.stem:
raise fail(f"'role' {name!r} must match the file name {path.stem!r}")
deliverable = frontmatter.get("deliverable")
if name in specialists:
expected = specialists[name].value
if deliverable != expected:
raise fail(f"'deliverable' must be {expected!r}, not {deliverable!r}")
elif deliverable is not None:
raise fail(f"role {name!r} owns no Deliverable, but names {deliverable!r}")
tools = tuple(frontmatter.get("tools") or ())
offered = {name for names in bundle.tools.values() for name in names}
unknown_tools = [tool for tool in tools if tool not in offered]
if unknown_tools:
raise fail(
f"'tools' {', '.join(unknown_tools)} are not offered by the "
f"{bundle.name} provider bundle"
)
budget = frontmatter.get("budget", default_budget)
if not isinstance(budget, int) or budget < 1:
raise fail("'budget' must be a positive integer")
sections = [body.strip()]
for include in frontmatter.get("includes") or ():
partial = agents_dir / PARTIALS_DIR / f"{include}.md"
if not partial.is_file():
raise fail(f"include {include!r} not found at {partial}")
sections.append(partial.read_text(encoding="utf-8").strip())
if not sections[0]:
raise fail("instructions (the body after the frontmatter) must not be empty")
return RoleSpec(
name=name,
instructions="\n\n".join(sections),
budget=budget,
skills=tuple(bundle.role_skills.get(name, ())),
tools=tools,
mcp_servers=tuple(
server.id
for server in bundle.mcp_servers_for_role(name, include_preview_mcp)
),
model=bundle.models.for_role(name),
model_timeout_seconds=bundle.models.timeout_for(name),
)