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>
469 lines
16 KiB
Python
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)
|