Files
solution_architecture_agent/app/solution_architecture/hooks.py
Jonathan Boniface c84dbdea20 feat: the solution architecture agent on the shared Execution engine
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>
2026-10-21 19:49:28 +01:00

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.",
),
)