"""Load role files (agents/.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 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" PARTIALS_DIR = "partials" _ALLOWED_FIELDS = {"role", "deliverable", "tools", "budget", "includes"} 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, ) -> dict[str, RoleSpec]: specialists = {spec.specialist: kind for kind, spec in DEPENDENCY_GRAPH.items()} required = {ORCHESTRATOR, PILLAR_ADVISOR, REPLY_WRITER, *specialists} 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)}" ) unexpected = sorted(set(roles) - required) 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), )