Files
gcp_solution_architecture_a…/app/adk/roles.py
Jonathan Boniface ef37f59bad feat: opt-in published Terraform modules from approved sources (iteration 8)
Infrastructure code is plain resources by default. An Execution may opt in
with terraform_modules; the deployment default is TERRAFORM_MODULES, off.

- A module is accepted only from the registry namespaces the provider bundle
  lists (terraform-google-modules), at one exact version. Any other source is
  refused before Terraform runs; until now nothing stopped generated code
  naming any source for terraform init to download.
- terraform_module looks up a module's inputs, outputs and submodules from
  the registry and says when it cannot be used with the pinned provider.
- skills/google-cloud-iac-modules: when a module fits, and four modules with
  examples a test validates against hashicorp/google 8.6.0.
- Opted in, the IaC author and validator get the Skill and the lookup. Not
  opted in, they get neither and a module block is refused in code.
- A Change request follows its Baseline. execution.json records the choice.
- case-07 runs case 03's request with modules opted into.

Azure (aztfm) and AWS (terraform-aws-modules) sources are recorded in the
plan for when those Cloud providers are added. No case has run with this.

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

171 lines
6.2 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.tools.modules import MODULE_TOOL
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)
if bundle.terraform_modules_skill:
for name, role in roles.items():
if MODULE_TOOL in role.tools:
roles[name] = dataclasses.replace(
role, modules_skill=bundle.terraform_modules_skill
)
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),
)