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:
468
app/solution_architecture/workflow.py
Normal file
468
app/solution_architecture/workflow.py
Normal file
@@ -0,0 +1,468 @@
|
||||
"""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)
|
||||
Reference in New Issue
Block a user