The reference agent's subject, cloud solution architecture, as an agent in the operating model agent's pattern: the Execution engine (from orchestration_engine) and one Workflow in app/solution_architecture, built for the settings and provider bundle by assembly.workflow_for. Copied from gcp_solution_architecture_agent at 8b397cd without its own engine: its role files, Skills, provider bundle, ADRs, vocabulary, scripts and evaluation datasets. The image takes the engine from a named build context and installs Terraform. It is called through the Orchestration engine, and its files are what the operating model agent digests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
483 lines
17 KiB
Python
483 lines
17 KiB
Python
"""Where the Reference's own code runs inside the engine.
|
|
|
|
In the Reference these are branches inside its engine: `app/tools/execution.py` adds
|
|
views to three Deliverables as they are submitted and adds to an Approval,
|
|
`app/tools/toolkit.py` gives the design advisor its pillar consultation, and
|
|
`app/adk/roles.py` gives the modules Skill to roles with the module tool. Here each
|
|
is a function the Workflow names.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import dataclasses
|
|
from collections.abc import Mapping, Sequence
|
|
from typing import Any
|
|
|
|
from execution_engine.adk.runtime import Decider, RoleSpec, ToolSpec
|
|
from execution_engine.workflows.deliverables import GraphShape, ListShape, Upstream
|
|
from execution_engine.workflows.workflow import (
|
|
Bench,
|
|
CardText,
|
|
ChangePolicy,
|
|
Hints,
|
|
OptionSpec,
|
|
RoleTools,
|
|
)
|
|
|
|
from app.solution_architecture.chain import (
|
|
IMPLEMENTATION_FILE,
|
|
RECOMMENDATIONS_FILE,
|
|
REQUIREMENTS_FILE,
|
|
read_graph,
|
|
read_list,
|
|
unimplementable_checks,
|
|
)
|
|
from app.solution_architecture.changes import (
|
|
CHANGES_FILE,
|
|
change_summary,
|
|
changes_for,
|
|
is_empty,
|
|
)
|
|
from app.solution_architecture.changes import _graph as changes_graph
|
|
from app.solution_architecture.meaning import settle_meaning
|
|
from app.solution_architecture.modules import MODULE_TOOL, MODULES_OPTED_IN
|
|
from app.solution_architecture.pillars import (
|
|
ADVICE_KEY,
|
|
QUESTIONS_HEADING,
|
|
REVIEW_HEADING,
|
|
customer_questions,
|
|
pillar_consultation_tool,
|
|
pillars_touched,
|
|
render_checklist_review,
|
|
)
|
|
from app.solution_architecture.presentation import (
|
|
_describe_changes,
|
|
_describe_target_architecture,
|
|
)
|
|
from app.solution_architecture.target_architecture import (
|
|
DIAGRAM_ATTACHMENT,
|
|
GRAPH_ATTACHMENT,
|
|
GraphError,
|
|
parse_graph,
|
|
render_mermaid,
|
|
render_tables,
|
|
)
|
|
from app.solution_architecture.work_breakdown import (
|
|
DICTIONARY_HEADING,
|
|
TIMELINE_FILE,
|
|
)
|
|
from app.solution_architecture.work_breakdown import mermaid as plan_mermaid
|
|
from app.solution_architecture.work_breakdown import render as render_plan
|
|
from app.solution_architecture.work_breakdown import summary as plan_summary
|
|
|
|
PILLAR_ADVISOR = "pillar-advisor"
|
|
COVERAGE_REVIEWER = "coverage-reviewer" # reviews a design before its Approval
|
|
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
|
TARGET_ARCHITECTURE = "target_architecture"
|
|
WORK_BREAKDOWN = "work_breakdown"
|
|
MODULES_OPTION = "terraform_modules"
|
|
GUIDE_FILENAME = "solution-architecture-guide.md"
|
|
QUESTIONS_FILENAME = "customer-questions.md" # what to ask the customer
|
|
|
|
# The Target architecture, as the Specialist builds it in its working copy.
|
|
GRAPH_SHAPE = GraphShape(
|
|
attachment=GRAPH_ATTACHMENT,
|
|
lists={
|
|
"elements": ListShape(
|
|
("id", "name", "product", "resource_type"),
|
|
optional=("component",),
|
|
label="Elements",
|
|
),
|
|
"relationships": ListShape(("id", "from", "to", "kind"), label="Relationships"),
|
|
"checks": ListShape(
|
|
("id", "applies_to", "statement", "source"), label="Checks"
|
|
),
|
|
"not_applicable": ListShape(("recommendation", "reason"), key="recommendation"),
|
|
},
|
|
)
|
|
|
|
|
|
def check_ids(upstream: Upstream | None) -> Sequence[str]:
|
|
graph = read_graph(upstream)
|
|
return graph.check_ids if graph else ()
|
|
|
|
|
|
def with_checklist_review(
|
|
bench: Bench, content: str, attachments: dict[str, str]
|
|
) -> tuple[str, dict[str, str]]:
|
|
# The pillar advisors' checklist reviews, written from what they recorded. A
|
|
# Revision replaces the section, never stacks a second.
|
|
checklist_review = render_checklist_review(bench.working)
|
|
content = content.split(f"\n## {REVIEW_HEADING}")[0].rstrip() + "\n"
|
|
if checklist_review:
|
|
content += "\n" + checklist_review
|
|
return content, attachments
|
|
|
|
|
|
def with_plan_views(
|
|
bench: Bench, content: str, attachments: dict[str, str]
|
|
) -> tuple[str, dict[str, str]]:
|
|
# The dictionary, the sequence and the timeline are views of the plan, computed
|
|
# and written here: they cannot disagree with it.
|
|
views = render_plan(attachments, bench.upstream)
|
|
content = content.split(f"\n## {DICTIONARY_HEADING}")[0].rstrip() + "\n"
|
|
if views:
|
|
content += "\n" + views
|
|
chart = plan_mermaid(attachments, bench.upstream)
|
|
if chart:
|
|
attachments[TIMELINE_FILE] = chart
|
|
return content, attachments
|
|
|
|
|
|
def with_graph_views(
|
|
bench: Bench, content: str, attachments: dict[str, str]
|
|
) -> tuple[str, dict[str, str]]:
|
|
# The tables and the diagram are views of the graph, so code writes them: they
|
|
# cannot disagree with it.
|
|
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
|
content = content.rstrip() + "\n\n" + render_tables(graph)
|
|
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph)
|
|
return content, attachments
|
|
|
|
|
|
def approval_details(
|
|
phase: str,
|
|
deliverables: Mapping[str, Mapping[str, Any]],
|
|
baseline: Mapping[str, Any] | None,
|
|
*,
|
|
in_phase: Sequence[str],
|
|
design_phase: str,
|
|
) -> dict[str, Any]:
|
|
details: dict[str, Any] = {}
|
|
if baseline:
|
|
# Worked out from the ids, not written by an agent: what this Phase's
|
|
# Deliverables add, change and remove against the Baseline.
|
|
details["changes"] = changes_for(
|
|
change_summary(baseline.get("deliverables"), deliverables), list(in_phase)
|
|
)
|
|
target = deliverables.get(TARGET_ARCHITECTURE)
|
|
if target and phase == design_phase:
|
|
try:
|
|
graph = parse_graph(target.get("attachments", {})[GRAPH_ATTACHMENT])
|
|
except (KeyError, GraphError):
|
|
return details
|
|
# What the user is approving before any code is written.
|
|
details["target_architecture"] = graph.summary()
|
|
return details
|
|
|
|
|
|
def consultations(pillar_skills: Mapping[str, str]):
|
|
"""The design advisor's pillar consultation, for a bundle's pillar Skills."""
|
|
|
|
def role_tools(given: RoleTools) -> Sequence[ToolSpec]:
|
|
advisor = given.roles.get(PILLAR_ADVISOR)
|
|
if not (
|
|
pillar_skills and advisor and given.deliverable == DESIGN_RECOMMENDATIONS
|
|
):
|
|
return ()
|
|
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
|
advisor_tools = [
|
|
tool for tool in given.mcp_tools(advisor) if tool.tier == "general"
|
|
]
|
|
return (
|
|
pillar_consultation_tool(
|
|
given.runtime,
|
|
advisor,
|
|
pillar_skills,
|
|
extra_tools=advisor_tools,
|
|
memory=given.working,
|
|
limiter=given.limiter,
|
|
),
|
|
)
|
|
|
|
return role_tools
|
|
|
|
|
|
def with_modules_skill(
|
|
roles: Mapping[str, RoleSpec], bundle: Any
|
|
) -> Mapping[str, RoleSpec]:
|
|
if not bundle.terraform_modules_skill:
|
|
return roles
|
|
return {
|
|
name: dataclasses.replace(role, modules_skill=bundle.terraform_modules_skill)
|
|
if MODULE_TOOL in role.tools
|
|
else role
|
|
for name, role in roles.items()
|
|
}
|
|
|
|
|
|
# --- what the router and the Execution's nodes read ------------------------------------
|
|
|
|
|
|
def unimplementable(deliverables: Upstream) -> list[dict[str, str]]:
|
|
"""Checks the code's author reported cannot be met as the design words them."""
|
|
return unimplementable_checks(
|
|
(deliverables.get("deployment_guidance") or {})
|
|
.get("attachments", {})
|
|
.get(IMPLEMENTATION_FILE, "")
|
|
)
|
|
|
|
|
|
def known_ids(deliverables: Upstream) -> set[str]:
|
|
return {
|
|
item["id"]
|
|
for name, kind in (
|
|
(REQUIREMENTS_FILE, "requirements"),
|
|
(RECOMMENDATIONS_FILE, DESIGN_RECOMMENDATIONS),
|
|
)
|
|
for item in read_list(deliverables, kind, name)
|
|
if "id" in item
|
|
}
|
|
|
|
|
|
def agreed(deliverables: Upstream) -> str:
|
|
return str(
|
|
(deliverables.get("requirements") or {})
|
|
.get("attachments", {})
|
|
.get(REQUIREMENTS_FILE, "")
|
|
)
|
|
|
|
|
|
def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]:
|
|
facts: dict[str, Any] = {}
|
|
counts = {
|
|
"requirements": len(read_list(deliverables, "requirements", REQUIREMENTS_FILE)),
|
|
"recommendations": len(
|
|
read_list(deliverables, DESIGN_RECOMMENDATIONS, RECOMMENDATIONS_FILE)
|
|
),
|
|
}
|
|
facts["counts"] = {name: count for name, count in counts.items() if count}
|
|
plan = deliverables.get(WORK_BREAKDOWN)
|
|
if plan and phase == "packaging":
|
|
# How long the build is planned to take, and whether that fits.
|
|
facts["delivery_plan"] = plan_summary(plan.get("attachments", {}), deliverables)
|
|
graph = read_graph(deliverables)
|
|
if graph is not None:
|
|
facts["target_architecture"] = graph.summary()
|
|
return facts
|
|
|
|
|
|
def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]:
|
|
lines = []
|
|
counts = facts.get("counts") or {}
|
|
if counts:
|
|
lines.append(
|
|
", ".join(f"{count} {name}" for name, count in counts.items()) + "."
|
|
)
|
|
plan = facts.get("delivery_plan")
|
|
if plan:
|
|
fits = plan.get("within_window")
|
|
lines.append(
|
|
f"Delivery plan: {plan['activities']} activities in "
|
|
f"{plan['work_packages']} work packages, {plan['weeks']} weeks with a "
|
|
f"team of {plan['team_size']}"
|
|
+ (
|
|
""
|
|
if fits is None
|
|
else f", {'inside' if fits else 'over'} the "
|
|
f"{plan['window_weeks']}-week window"
|
|
)
|
|
+ "."
|
|
)
|
|
graph = facts.get("target_architecture")
|
|
if graph:
|
|
lines.append(
|
|
f"Target architecture: {graph['elements']} Elements, "
|
|
f"{graph['relationships']} Relationships, {graph['checks']} Checks."
|
|
)
|
|
return lines
|
|
|
|
|
|
def changes_in_words(summary: Mapping[str, Any]) -> str:
|
|
return "\n".join(
|
|
f"Requirement {item['id']} {item['change']}: {item['text']} ({item['reason']})"
|
|
for item in summary["requirements"]
|
|
)
|
|
|
|
|
|
async def settle(
|
|
decider: Decider,
|
|
summary: dict[str, Any],
|
|
before: Upstream | None,
|
|
after: Upstream,
|
|
*,
|
|
unchanged_at: float,
|
|
scope: str,
|
|
) -> dict[str, Any]:
|
|
return await settle_meaning(
|
|
decider, summary, before, after, unchanged_at=unchanged_at, scope=scope
|
|
)
|
|
|
|
|
|
CHANGES = ChangePolicy(
|
|
file=CHANGES_FILE,
|
|
summary=change_summary,
|
|
is_empty=is_empty,
|
|
in_words=changes_in_words,
|
|
settle=settle,
|
|
)
|
|
|
|
|
|
def describe_design(deliverables: Upstream) -> str:
|
|
design = "\n".join(
|
|
f"- {item.get('name', item.get('id', ''))} ({item.get('product', '')}, "
|
|
f"{item.get('resource_type', '')})"
|
|
for item in changes_graph(deliverables)["elements"]
|
|
)
|
|
return f"Elements of the Target architecture:\n{design}" if design else ""
|
|
|
|
|
|
def prepare_role(role: RoleSpec, task_input: Mapping[str, Any]) -> RoleSpec:
|
|
opted_in = bool(task_input.get(MODULES_OPTION))
|
|
MODULES_OPTED_IN.set(opted_in)
|
|
if opted_in and role.modules_skill:
|
|
return dataclasses.replace(role, skills=(*role.skills, role.modules_skill))
|
|
if MODULE_TOOL in role.tools:
|
|
# Plain resources: no modules Skill and no module lookup.
|
|
return dataclasses.replace(
|
|
role, tools=tuple(tool for tool in role.tools if tool != MODULE_TOOL)
|
|
)
|
|
return role
|
|
|
|
|
|
def task_entries(
|
|
state: Mapping[str, Any], kind: str
|
|
) -> tuple[dict[str, Any], dict[str, Any]]:
|
|
# Whether this Execution opted into published Terraform modules. False:
|
|
# infrastructure code is plain resources. True: a published module may be used
|
|
# where the modules Skill says one fits.
|
|
opted_in = bool((state.get("options") or {}).get(MODULES_OPTION))
|
|
return {MODULES_OPTION: opted_in}, {
|
|
MODULES_OPTION: opted_in,
|
|
# The pillars a change touches, when that could be judged: the design
|
|
# advisor consults those and keeps its earlier advice for the rest.
|
|
"pillars_to_consult": None,
|
|
}
|
|
|
|
|
|
def pillar_hints(threshold: float = 1.5):
|
|
"""Which pillars the design advisor should consult again, when it is being
|
|
started on a Revision or a Change request and advice from before exists."""
|
|
|
|
async def task_hints(given: Hints) -> Mapping[str, Mapping[str, Any]]:
|
|
kind = DESIGN_RECOMMENDATIONS
|
|
if given.decider is None or kind not in given.started:
|
|
return {}
|
|
state = given.state
|
|
baseline = state.get("baseline") or {}
|
|
remembered = state.get("working", {}).get(kind, {}).get(
|
|
ADVICE_KEY
|
|
) or baseline.get("working", {}).get(kind, {}).get(ADVICE_KEY)
|
|
if not remembered:
|
|
return {} # a first consultation: every pillar
|
|
change = "\n".join(given.feedback.get(kind, ())) or given.changed
|
|
chosen = await pillars_touched(
|
|
given.decider,
|
|
list(remembered),
|
|
change,
|
|
threshold=threshold,
|
|
scope=str(state["execution_id"]),
|
|
)
|
|
# None: no decision, so no hint and every pillar. An empty list is an answer.
|
|
return {} if chosen is None else {kind: {"pillars_to_consult": chosen}}
|
|
|
|
return task_hints
|
|
|
|
|
|
def outputs(
|
|
state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str]
|
|
) -> dict[str, Any]:
|
|
"""The Reference's own files and manifest entries."""
|
|
questions = customer_questions(
|
|
state.get("working", {}).get(DESIGN_RECOMMENDATIONS, {})
|
|
)
|
|
if questions:
|
|
# What the request did not say enough to settle, as questions to put to
|
|
# the customer. Missing information, not a fault in the design.
|
|
files[QUESTIONS_FILENAME] = "\n".join(
|
|
[
|
|
f"# {QUESTIONS_HEADING}",
|
|
"",
|
|
(
|
|
"The request did not say enough to settle these. Each answer "
|
|
"may change a recommendation."
|
|
),
|
|
"",
|
|
*(
|
|
f"- **{item['pillar']}**, {item['item']} {item['question']}"
|
|
for item in questions
|
|
),
|
|
"",
|
|
]
|
|
)
|
|
plan = deliverables.get(WORK_BREAKDOWN)
|
|
plan_record: dict[str, Any] | None = None
|
|
guide = GUIDE_FILENAME in files
|
|
if plan:
|
|
plan_record = plan_summary(plan.get("attachments", {}), deliverables) or None
|
|
timeline = str(plan.get("content", "")).partition("\n## Timeline\n")[2]
|
|
if guide and timeline:
|
|
# The guide and the plan are written side by side, so neither holds the
|
|
# other. The plan's timeline is added to the guide here, from the plan.
|
|
appendix = (
|
|
"\n\n## Delivery plan\n\n"
|
|
f"From the work breakdown structure (`deliverables/"
|
|
f"{WORK_BREAKDOWN}.md`), which has the work "
|
|
"packages and the full activity sequence.\n\n" + timeline.strip() + "\n"
|
|
)
|
|
files[GUIDE_FILENAME] = files[GUIDE_FILENAME].rstrip() + appendix
|
|
guide_document = "deliverables/solution_guide.md"
|
|
files[guide_document] = files[guide_document].rstrip() + appendix
|
|
return {
|
|
# Whether its infrastructure code was allowed published modules.
|
|
MODULES_OPTION: bool((state.get("options") or {}).get(MODULES_OPTION)),
|
|
# The plan in a few numbers: its length, and whether it fits the window.
|
|
"delivery_plan": plan_record,
|
|
"solution_guide": GUIDE_FILENAME if guide else None,
|
|
# Questions the request left open, for the customer; None when there are none.
|
|
"customer_questions": QUESTIONS_FILENAME if questions else None,
|
|
}
|
|
|
|
|
|
def modules_option(available: bool, default: bool) -> OptionSpec:
|
|
"""Whether an Execution may use published Terraform modules: off unless the
|
|
deployment says otherwise, and refused when the provider approves no sources."""
|
|
|
|
def check(value: Any) -> str | None:
|
|
if not isinstance(value, bool):
|
|
return "terraform_modules must be true or false"
|
|
if value and not available:
|
|
return (
|
|
"terraform_modules: this Cloud provider has no approved module sources"
|
|
)
|
|
return None
|
|
|
|
return OptionSpec(
|
|
default=default and available,
|
|
spec_field="run.terraform_modules",
|
|
check=check,
|
|
)
|
|
|
|
|
|
def describe_approval(approval: Mapping[str, Any]) -> str:
|
|
return _describe_changes(approval) + _describe_target_architecture(
|
|
approval.get("target_architecture")
|
|
)
|
|
|
|
|
|
CARD = CardText(
|
|
description=(
|
|
"Designs a cloud solution architecture with you: requirements discovery, "
|
|
"grounded product selection, diagram, design recommendations, "
|
|
"infrastructure-as-code and dry-run validation, packaged as a solution "
|
|
"guide."
|
|
),
|
|
skill_id="solution-architecture",
|
|
skill_name="Cloud solution architecture",
|
|
tags=("architecture", "cloud", "terraform"),
|
|
examples=(
|
|
"Design a regional event ingestion platform on Google Cloud.",
|
|
"Migrate our on-premises order service to managed services.",
|
|
),
|
|
)
|