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>
This commit is contained in:
482
app/solution_architecture/hooks.py
Normal file
482
app/solution_architecture/hooks.py
Normal file
@@ -0,0 +1,482 @@
|
||||
"""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.",
|
||||
),
|
||||
)
|
||||
Reference in New Issue
Block a user