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

357 lines
12 KiB
Python

"""The Target architecture: one explicit graph, established before code (ADR-0005).
Elements every component and the resource that realises it
Relationships how Elements connect
Checks the numbered, verifiable conditions each must meet, each traced
to the requirement or design recommendation it comes from
This module is pure: it parses the graph, states what is wrong with it, renders it as
a diagram and as tables a person can review, and says whether the Requirements chain
through it is complete.
"""
from __future__ import annotations
import json
import re
from collections.abc import Iterable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any
GRAPH_ATTACHMENT = "target-architecture.json"
DIAGRAM_ATTACHMENT = "architecture.mmd"
@dataclass(frozen=True)
class Element:
id: str
name: str
product: str
resource_type: str
component: str | None = None # None for a supporting Element, e.g. an identity
@dataclass(frozen=True)
class Relationship:
id: str
source: str # "from" in the data
target: str # "to" in the data
kind: str
@dataclass(frozen=True)
class Check:
id: str
applies_to: str # an Element or Relationship id
statement: str
source: str # a requirement or design recommendation id
@dataclass(frozen=True)
class NotApplicable:
recommendation: str
reason: str
@dataclass(frozen=True)
class TargetArchitecture:
elements: tuple[Element, ...]
relationships: tuple[Relationship, ...]
checks: tuple[Check, ...]
not_applicable: tuple[NotApplicable, ...] = ()
@property
def check_ids(self) -> tuple[str, ...]:
return tuple(check.id for check in self.checks)
def summary(self) -> dict[str, Any]:
"""What a user approving the design is told about the graph."""
return {
"elements": len(self.elements),
"relationships": len(self.relationships),
"checks": len(self.checks),
"not_applicable": [
{"recommendation": item.recommendation, "reason": item.reason}
for item in self.not_applicable
],
}
class GraphError(ValueError):
"""The graph is not well-formed; `problems` says how, one entry per fault."""
def __init__(self, problems: Sequence[str]) -> None:
super().__init__("; ".join(problems))
self.problems = tuple(problems)
def parse_graph(text: str) -> TargetArchitecture:
"""Parse target-architecture.json, or raise GraphError naming every fault."""
name = GRAPH_ATTACHMENT
try:
data = json.loads(text)
except ValueError as exc:
raise GraphError([f"{name}: not valid JSON ({exc})"]) from exc
if not isinstance(data, dict):
raise GraphError(
[f"{name}: must be an object with elements, relationships and checks"]
)
problems: list[str] = []
def items(key: str, required: Sequence[str]) -> list[dict[str, str]]:
raw = data.get(key, [])
if not isinstance(raw, list):
problems.append(f"{name}.{key}: must be a list")
return []
accepted = []
for index, item in enumerate(raw):
where = f"{name}.{key}[{index}]"
if not isinstance(item, dict):
problems.append(f"{where}: must be an object")
continue
missing = [
field
for field in required
if not isinstance(item.get(field), str) or not item[field].strip()
]
if missing:
problems.append(f"{where}: needs a non-empty {', '.join(missing)}")
continue
accepted.append(item)
return accepted
elements = tuple(
Element(
id=item["id"],
name=item["name"],
product=item["product"],
resource_type=item["resource_type"],
component=item.get("component") or None,
)
for item in items("elements", ("id", "name", "product", "resource_type"))
)
relationships = tuple(
Relationship(item["id"], item["from"], item["to"], item["kind"])
for item in items("relationships", ("id", "from", "to", "kind"))
)
checks = tuple(
Check(item["id"], item["applies_to"], item["statement"], item["source"])
for item in items("checks", ("id", "applies_to", "statement", "source"))
)
not_applicable = tuple(
NotApplicable(item["recommendation"], item["reason"])
for item in items("not_applicable", ("recommendation", "reason"))
)
if not elements and not problems:
problems.append(f"{name}.elements: the graph has no Elements")
seen: set[str] = set()
ids = [thing.id for group in (elements, relationships, checks) for thing in group]
for identifier in ids:
if identifier in seen:
problems.append(f"{name}: id {identifier} is used more than once")
seen.add(identifier)
element_ids = {element.id for element in elements}
for relationship in relationships:
for end, value in (("from", relationship.source), ("to", relationship.target)):
if value not in element_ids:
problems.append(
f"{name}: Relationship {relationship.id} {end} {value}, "
"which is not an Element"
)
targets = element_ids | {relationship.id for relationship in relationships}
for check in checks:
if check.applies_to not in targets:
problems.append(
f"{name}: Check {check.id} applies to {check.applies_to}, "
"which is not an Element or Relationship"
)
checked = {check.applies_to for check in checks}
for element in elements:
if element.id not in checked:
problems.append(f"{name}: Element {element.id} has no Check")
if problems:
raise GraphError(problems)
return TargetArchitecture(elements, relationships, checks, not_applicable)
# --- the Requirements chain through the graph ----------------------------------------
def chain_gaps(
graph: TargetArchitecture,
*,
requirements: Sequence[Mapping[str, Any]],
components: Sequence[Mapping[str, Any]],
products: Sequence[Mapping[str, Any]],
recommendations: Sequence[Mapping[str, Any]],
) -> tuple[str, ...]:
"""Every place the Requirements chain stops before reaching a Check.
A functional requirement is carried by a component that has an Element, or by a
Check of its own. A non-functional requirement and a design recommendation are
each a constraint, so each must be the source of a Check (a recommendation may
instead be marked not applicable, with a reason). A constraint that lists
nothing infrastructure code can show, only what lies outside it, needs none.
"""
gaps: list[str] = []
requirement_ids = {item["id"] for item in requirements}
recommendation_ids = {item["id"] for item in recommendations}
sources = {check.source for check in graph.checks}
realised = {element.component for element in graph.elements if element.component}
for check in graph.checks:
if check.source not in requirement_ids | recommendation_ids:
gaps.append(
f"Check {check.id} has source {check.source}, which is not a "
"requirement or design recommendation"
)
for element in graph.elements:
if element.component and element.component not in {c["id"] for c in components}:
gaps.append(
f"Element {element.id} realises {element.component}, "
"which is not a component"
)
for component in components:
if component["id"] not in realised:
gaps.append(f"Component {component['id']} has no Element")
for requirement in requirements:
if requirement["id"] in sources:
continue
served = any(
requirement["id"] in component.get("requirements", ())
and component["id"] in realised
for component in components
)
if requirement.get("kind") == "functional" and served:
continue
if _only_outside_code(requirement):
continue
gaps.append(f"Requirement {requirement['id']} has no Check")
for selection in products:
used = any(
element.component == selection["component"]
and element.product == selection["product"]
for element in graph.elements
)
if not used:
gaps.append(
f"Product {selection['product']} selected for "
f"{selection['component']} appears on no Element"
)
excused = {item.recommendation for item in graph.not_applicable}
for item in graph.not_applicable:
if item.recommendation not in recommendation_ids:
gaps.append(
f"not_applicable names {item.recommendation}, "
"which is not a design recommendation"
)
for recommendation in recommendations:
if recommendation["id"] not in sources | excused and not _only_outside_code(
recommendation
):
gaps.append(f"Recommendation {recommendation['id']} has no Check")
return tuple(gaps)
def _only_outside_code(item: Mapping[str, Any]) -> bool:
"""Whether a constraint says, explicitly, that nothing it asks for can be shown
by infrastructure code."""
return item.get("conditions") == [] and bool(item.get("outside_code"))
# --- the diagram is a view of the graph ----------------------------------------------
_UNSAFE = re.compile(r'["\[\]{}()<>|`#;]')
def _label(*parts: str) -> str:
return "<br/>".join(_UNSAFE.sub(" ", part).strip() for part in parts if part)
def _node_ids(ids: Iterable[str]) -> dict[str, str]:
"""Mermaid-safe node ids; the graph's own ids may hold characters Mermaid rejects."""
return {identifier: f"n{index}" for index, identifier in enumerate(ids)}
def render_mermaid(graph: TargetArchitecture) -> str:
"""The architecture diagram: every Element and Relationship, exactly once."""
nodes = _node_ids(element.id for element in graph.elements)
lines = ["flowchart LR"]
for element in graph.elements:
lines.append(
f' {nodes[element.id]}["{_label(element.name, element.product)}"]'
)
for relationship in graph.relationships:
lines.append(
f" {nodes[relationship.source]} -->|{_label(relationship.kind)}| "
f"{nodes[relationship.target]}"
)
return "\n".join(lines) + "\n"
# --- so are the tables a person reviews ----------------------------------------------
def _cell(text: str | None) -> str:
return " ".join((text or "").replace("|", "\\|").split())
def _table(
heading: str, columns: Sequence[str], rows: Iterable[Sequence[str | None]]
) -> str:
lines = [
f"## {heading}",
"",
"| " + " | ".join(columns) + " |",
"|" + "|".join(" --- " for _ in columns) + "|",
]
lines += ["| " + " | ".join(_cell(value) for value in row) + " |" for row in rows]
return "\n".join(lines)
def render_tables(graph: TargetArchitecture) -> str:
"""The graph as markdown tables: what a person approving the design reads.
Written by code, so the tables cannot disagree with the graph and no model spends
output repeating it.
"""
names = {element.id: element.name for element in graph.elements}
parts = [
_table(
"Elements",
("Id", "Name", "Product", "Resource type", "Component"),
(
(e.id, e.name, e.product, e.resource_type, e.component)
for e in graph.elements
),
),
_table(
"Relationships",
("Id", "From", "Kind", "To"),
(
(r.id, names[r.source], r.kind, names[r.target])
for r in graph.relationships
),
),
_table(
"Checks",
("Id", "Applies to", "Statement", "Source"),
((c.id, c.applies_to, c.statement, c.source) for c in graph.checks),
),
]
if graph.not_applicable:
parts.append(
_table(
"Not applicable",
("Recommendation", "Reason"),
((n.recommendation, n.reason) for n in graph.not_applicable),
)
)
return "\n\n".join(parts) + "\n"