166 lines
5.9 KiB
Python
166 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 execution_engine.adk.runtime import RoleSpec
|
|
from execution_engine.providers import ProviderBundle
|
|
from execution_engine.skills.agent_skills import SkillFormatError, split_frontmatter
|
|
from execution_engine.workflows.workflow import Workflow
|
|
|
|
ORCHESTRATOR = "orchestrator"
|
|
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,
|
|
workflow: Workflow,
|
|
*,
|
|
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 = workflow.specialists()
|
|
required = {ORCHESTRATOR, REPLY_WRITER, *specialists, *workflow.roles}
|
|
optional = {LESSON_CURATOR, *workflow.optional_roles}
|
|
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 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 workflow.adjust_roles:
|
|
roles = dict(workflow.adjust_roles(roles, bundle))
|
|
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, str],
|
|
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]
|
|
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),
|
|
)
|