Files
solution_architecture_agent/app/solution_architecture/workflow.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

469 lines
16 KiB
Python

"""Cloud solution architecture, as a Workflow: this agent's subject.
The graph, the data checks and the samples are the reference agent's, from its
`app/workflows/deliverables.py` and `app/adk/fake_runtime.py`, arranged into one
value by the Execution engine's example of it.
"""
from __future__ import annotations
import dataclasses
import functools
import json
from collections.abc import Mapping
from execution_engine.adk import fake_runtime
from execution_engine.workflows.deliverables import DataCheck, DeliverableSpec
from execution_engine.workflows.workflow import ValidationPolicy, Workflow
from app.solution_architecture.assessment import assess
from app.solution_architecture.chain import (
COMPONENTS_FILE,
IMPLEMENTATION_FILE,
PRODUCTS_FILE,
RECOMMENDATIONS_FILE,
REQUIREMENTS_FILE,
SCOPE_DATA_FILE,
SCOPE_FILE,
VERDICTS_FILE,
check_components,
check_implementation,
check_products,
check_recommendations,
check_requirements,
check_scope,
check_target_architecture,
check_verdicts,
graph_structure,
validation_outcome,
)
from app.solution_architecture.changes import check_requirement_changes
from app.solution_architecture.hooks import (
CARD,
CHANGES,
COVERAGE_REVIEWER,
GRAPH_SHAPE,
GUIDE_FILENAME,
MODULES_OPTION,
PILLAR_ADVISOR,
agreed,
approval_details,
approval_facts,
check_ids,
consultations,
describe_approval,
describe_design,
known_ids,
modules_option,
outputs,
pillar_hints,
prepare_role,
summary_lines,
task_entries,
unimplementable,
with_checklist_review,
with_graph_views,
with_modules_skill,
with_plan_views,
)
from app.solution_architecture.kinds import PHASE_ORDER, DeliverableKind, PhaseId
from app.solution_architecture.pillars import KEPT_FOR_CHANGES
from app.solution_architecture.presentation import to_generate_response
from app.solution_architecture.target_architecture import GRAPH_ATTACHMENT
from app.solution_architecture.work_breakdown import (
WORK_BREAKDOWN_FILE,
check_work_breakdown,
)
ABOUT = (
"I design cloud solution architectures. Tell me, at a high level, what you want "
"built, and I will work through requirements, a target architecture, "
"infrastructure code, validation and a packaged guide, asking for your approval "
"at each Phase. Nothing was started for this message."
)
_K = DeliverableKind
DEPENDENCY_GRAPH: Mapping[str, DeliverableSpec] = {
spec.kind: spec
for spec in (
DeliverableSpec(
_K.SCOPE,
PhaseId.SCOPING,
"scope-analyst",
sections=("Scope statement",),
# The completed scope spec, for people and for reuse; and what every
# later Specialist reads of it.
attachments=(SCOPE_FILE, SCOPE_DATA_FILE),
),
DeliverableSpec(
_K.REQUIREMENTS,
PhaseId.REQUIREMENTS_DISCOVERY,
"requirements-analyst",
depends_on=(_K.SCOPE,),
sections=(
"Functional requirements",
"Non-functional requirements",
"Current state",
"Dependencies",
),
attachments=(REQUIREMENTS_FILE,),
),
DeliverableSpec(
_K.TECHNICAL_DECOMPOSITION,
PhaseId.REQUIREMENTS_DISCOVERY,
"decomposer",
depends_on=(_K.REQUIREMENTS,),
sections=("Components",),
attachments=(COMPONENTS_FILE,),
),
DeliverableSpec(
_K.PRODUCT_SELECTION,
PhaseId.SOLUTION_ARCHITECTURE,
"product-selector",
depends_on=(_K.TECHNICAL_DECOMPOSITION,),
sections=("Products and features mapping",),
attachments=(PRODUCTS_FILE,),
),
DeliverableSpec(
_K.DESIGN_RECOMMENDATIONS,
PhaseId.SOLUTION_ARCHITECTURE,
"design-advisor",
depends_on=(_K.PRODUCT_SELECTION, _K.REQUIREMENTS),
sections=(
"Security, privacy, and compliance",
"Reliability",
"Operational excellence",
"Cost optimization",
"Performance efficiency",
"Sustainability",
),
attachments=(RECOMMENDATIONS_FILE,),
),
DeliverableSpec(
_K.TARGET_ARCHITECTURE,
PhaseId.SOLUTION_ARCHITECTURE,
"target-architect",
depends_on=(_K.PRODUCT_SELECTION, _K.DESIGN_RECOMMENDATIONS),
# The Specialist writes the reasoning and the graph. On submission the
# engine adds the Elements, Relationships and Checks tables to the content
# and architecture.mmd to the attachments, both rendered from the graph.
sections=("Design rationale",),
attachments=(GRAPH_ATTACHMENT,),
graph=GRAPH_SHAPE,
),
DeliverableSpec(
_K.ARCHITECTURE_DESCRIPTION,
PhaseId.SOLUTION_IMPLEMENTATION,
"describer",
depends_on=(_K.TARGET_ARCHITECTURE,),
sections=("Components", "Flow"),
# It describes the Elements and how they connect. A Revision that only
# adds or rewords Checks leaves it true.
written_from=graph_structure,
),
DeliverableSpec(
_K.DEPLOYMENT_GUIDANCE,
PhaseId.SOLUTION_IMPLEMENTATION,
"iac-author",
depends_on=(_K.TARGET_ARCHITECTURE,),
sections=(
"Deployment prerequisites",
"Step-by-step deployment instructions",
),
attachments=(
"terraform/main.tf",
"terraform/variables.tf",
IMPLEMENTATION_FILE,
),
# The graph is all the code is written from.
reads_in_full=(),
not_shown=(
_K.REQUIREMENTS,
_K.TECHNICAL_DECOMPOSITION,
_K.PRODUCT_SELECTION,
_K.DESIGN_RECOMMENDATIONS,
),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.VALIDATION_RESULTS,
PhaseId.SOLUTION_VALIDATION,
"validator",
depends_on=(_K.DEPLOYMENT_GUIDANCE,),
sections=("Deployment dry-run", "Architecture and policy analysis"),
attachments=(VERDICTS_FILE,),
# It judges the code against the Checks; the prose describing the
# design is not what it judges.
not_shown=(_K.ARCHITECTURE_DESCRIPTION,),
working_copy=_K.DEPLOYMENT_GUIDANCE,
),
DeliverableSpec(
_K.WORK_BREAKDOWN,
PhaseId.PACKAGING,
"delivery-planner",
depends_on=(_K.VALIDATION_RESULTS,),
sections=("Approach",),
attachments=(WORK_BREAKDOWN_FILE,),
# A plan covers the design and how it is built: the graph and the code.
reads_in_full=(_K.TARGET_ARCHITECTURE, _K.DEPLOYMENT_GUIDANCE),
not_shown=(
_K.REQUIREMENTS,
_K.DESIGN_RECOMMENDATIONS,
_K.ARCHITECTURE_DESCRIPTION,
),
),
DeliverableSpec(
_K.SOLUTION_GUIDE,
PhaseId.PACKAGING,
"packager",
depends_on=(_K.VALIDATION_RESULTS,),
sections=(
"Executive summary and workload overview",
"Requirements and current state",
"Technical decomposition of the workload",
"Proposed solution architecture",
"Design and configuration recommendations",
"Deployment guidance",
"Validation plan",
"References",
),
# The guide is assembled from every Deliverable's prose.
reads_in_full=tuple(_K)[:-1],
),
)
}
# What each data file along the Requirements chain must hold, checked at submission.
DATA_CHECKS: Mapping[str, tuple[str, DataCheck]] = {
_K.SCOPE: (SCOPE_DATA_FILE, check_scope),
_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirements),
_K.TECHNICAL_DECOMPOSITION: (COMPONENTS_FILE, check_components),
_K.PRODUCT_SELECTION: (PRODUCTS_FILE, check_products),
_K.DESIGN_RECOMMENDATIONS: (RECOMMENDATIONS_FILE, check_recommendations),
_K.TARGET_ARCHITECTURE: (GRAPH_ATTACHMENT, check_target_architecture),
_K.DEPLOYMENT_GUIDANCE: (IMPLEMENTATION_FILE, check_implementation),
_K.VALIDATION_RESULTS: (VERDICTS_FILE, check_verdicts),
_K.WORK_BREAKDOWN: (WORK_BREAKDOWN_FILE, check_work_breakdown),
}
# Sections code appends to a Deliverable for the person reading it. A Specialist
# working from that Deliverable has the same facts as data, and is not shown them.
FOR_READERS: Mapping[str, str] = {
_K.DESIGN_RECOMMENDATIONS: "Architecture framework checklist review",
}
# One small, coherent Requirements chain, so sample submissions pass every link.
SAMPLE_DATA: dict[str, str] = {
"scope.yaml": "engagement:\n kind: workload\nintent:\n statement: Accept events.\n",
"scope.json": json.dumps(
{
"kind": "workload",
"stated": {"intent": {"statement": "Accept events."}},
"to_decide": [],
"to_ask": [],
"not_applicable": [],
}
),
"requirements.json": json.dumps(
[
{"id": "FR-1", "kind": "functional", "text": "Accept events."},
{
"id": "NFR-1",
"kind": "non_functional",
"text": "99.9% availability.",
"conditions": ["The service stays available when one instance fails."],
},
]
),
"components.json": json.dumps(
[{"id": "C-1", "name": "Ingress", "requirements": ["FR-1", "NFR-1"]}]
),
"products.json": json.dumps([{"component": "C-1", "product": "Example Run"}]),
"recommendations.json": json.dumps(
[
{
"id": "DR-1",
"pillar": "security",
"text": "Use a dedicated identity.",
"components": ["C-1"],
"conditions": ["The service runs as an identity nothing else uses."],
}
]
),
"target-architecture.json": json.dumps(
{
"elements": [
{
"id": "E-1",
"name": "Ingress service",
"component": "C-1",
"product": "Example Run",
"resource_type": "example_run_service",
},
{
"id": "E-2",
"name": "Ingress identity",
"product": "Example IAM",
"resource_type": "example_service_account",
},
],
"relationships": [
{"id": "R-1", "from": "E-1", "to": "E-2", "kind": "runs as"}
],
"checks": [
{
"id": "K-1",
"applies_to": "E-1",
"statement": "The service runs at least two instances.",
"source": "NFR-1",
},
{
"id": "K-2",
"applies_to": "E-2",
"statement": "The identity is used by this service only.",
"source": "DR-1",
},
],
}
),
"implementation.json": json.dumps(
[
{"check": "K-1", "file": "terraform/main.tf", "address": "example.run"},
{"check": "K-2", "file": "terraform/main.tf", "address": "example.sa"},
]
),
"work-breakdown.json": json.dumps(
{
"work_packages": [
{
"id": "WP-1",
"name": "Ingress",
"parent": None,
"elements": ["E-1", "E-2"],
"scope": "The service and its identity.",
"produces": ["a running service"],
"skills": ["platform engineering"],
}
],
"activities": [
{
"id": "A-1",
"work_package": "WP-1",
"name": "Create the identity",
"days": 1,
"after": [],
},
{
"id": "A-2",
"work_package": "WP-1",
"name": "Deploy the service",
"days": 2,
"after": ["A-1"],
},
],
}
),
"verdicts.json": json.dumps(
{
"dry_run": {"verdict": "pass", "evidence": "terraform validate passed."},
"checks": [
{"check": "K-1", "verdict": "pass", "evidence": "min instances is 2."},
{"check": "K-2", "verdict": "pass", "evidence": "One binding."},
],
"proposed_additions": [],
}
),
}
def _approval_details(phase, deliverables, baseline):
return approval_details(
phase,
deliverables,
baseline,
in_phase=[
str(kind) for kind, spec in DEPENDENCY_GRAPH.items() if spec.phase == phase
],
design_phase=PhaseId.SOLUTION_ARCHITECTURE,
)
WORKFLOW = Workflow(
name="solution-architecture",
about=ABOUT,
phases=tuple(PHASE_ORDER),
deliverables=DEPENDENCY_GRAPH,
final=_K.SOLUTION_GUIDE,
data_checks=DATA_CHECKS,
baseline_checks={_K.REQUIREMENTS: (REQUIREMENTS_FILE, check_requirement_changes)},
for_readers=FOR_READERS,
spec_deliverable=_K.SCOPE,
validation=ValidationPolicy(
kind=_K.VALIDATION_RESULTS,
data_file=VERDICTS_FILE,
implementation=_K.DEPLOYMENT_GUIDANCE,
design=_K.TARGET_ARCHITECTURE,
read=validation_outcome,
check_ids=check_ids,
unimplementable=unimplementable,
known_ids=known_ids,
),
on_submit={
_K.DESIGN_RECOMMENDATIONS: with_checklist_review,
_K.WORK_BREAKDOWN: with_plan_views,
_K.TARGET_ARCHITECTURE: with_graph_views,
},
approval_details=_approval_details,
approval_facts=approval_facts,
summary_lines=summary_lines,
agreed=agreed,
changes=CHANGES,
subject="a cloud solution architecture",
describe_design=describe_design,
prepare_role=prepare_role,
task_entries=task_entries,
task_hints=pillar_hints(),
kept_for_changes=tuple(KEPT_FOR_CHANGES),
final_file=GUIDE_FILENAME,
outputs=outputs,
assess=assess,
options={MODULES_OPTION: modules_option(available=False, default=False)},
card=CARD,
done="The solution architecture is complete and approved.",
describe_approval=describe_approval,
response=to_generate_response,
roles=(PILLAR_ADVISOR,),
optional_roles=(COVERAGE_REVIEWER,),
adjust_roles=with_modules_skill,
samples=SAMPLE_DATA,
)
def with_pillars(
pillar_skills: Mapping[str, str], workflow: Workflow = WORKFLOW
) -> Workflow:
"""The Workflow for a provider bundle's pillar Skills: one advisor for each."""
return dataclasses.replace(workflow, role_tools=consultations(pillar_skills))
def with_modules(
available: bool, default: bool = False, workflow: Workflow = WORKFLOW
) -> Workflow:
"""The Workflow for a provider that does, or does not, approve module sources."""
return dataclasses.replace(
workflow, options={MODULES_OPTION: modules_option(available, default)}
)
# The Reference's tests call these as functions of its one graph.
inputs_of = WORKFLOW.inputs_of
dependencies_for = WORKFLOW.dependencies_for
shown = WORKFLOW.shown
deliverables_in = WORKFLOW.deliverables_in
check_submission = WORKFLOW.check_submission
sample_submission = functools.partial(fake_runtime.sample_submission, WORKFLOW)