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

327 lines
12 KiB
Python

"""What a Change request changed against its Baseline (ADR-0006).
Ids are stable from one version of a Customer case's architecture to the next: a
requirement, component, recommendation, Element, Relationship or Check that still
holds keeps its id. That is what lets code, with no model, say what was added, what
changed and what was removed; trace from each changed requirement to everything it
reaches; and list apart anything that changed without being reached. Nobody asked
for those, so a reader should see them as such.
This module is pure: data in, data out.
"""
from __future__ import annotations
import json
from collections.abc import Mapping, Sequence
from typing import Any
from app.solution_architecture.chain import (
COMPONENTS_FILE,
RECOMMENDATIONS_FILE,
REQUIREMENTS_FILE,
)
from app.solution_architecture.target_architecture import GRAPH_ATTACHMENT
CHANGES_FILE = "changes.json"
UNCHANGED, ADDED, CHANGED, REMOVED = "unchanged", "added", "changed", "removed"
CHANGE_KINDS = (UNCHANGED, ADDED, CHANGED, REMOVED)
Deliverables = Mapping[str, Mapping[str, Any]]
def _items(deliverables: Deliverables | None, kind: str, name: str) -> list[dict]:
"""A data file as a list of objects, removed requirements included."""
text = ((deliverables or {}).get(kind) or {}).get("attachments", {}).get(name, "")
try:
data = json.loads(text)
except ValueError:
return []
return (
[item for item in data if isinstance(item, dict)]
if isinstance(data, list)
else []
)
def _graph(deliverables: Deliverables | None) -> dict[str, list[dict]]:
text = (
((deliverables or {}).get("target_architecture") or {})
.get("attachments", {})
.get(GRAPH_ATTACHMENT, "")
)
try:
data = json.loads(text)
except ValueError:
data = {}
if not isinstance(data, dict):
data = {}
return {
key: [item for item in data.get(key, []) if isinstance(item, dict)]
for key in ("elements", "relationships", "checks")
}
# --- the requirements say what changed --------------------------------------------------
def check_requirement_changes(
attachments: Mapping[str, str], baseline: Mapping[str, Any] | None
) -> list[str]:
"""What is wrong with a Change request's requirements.json against the Baseline's.
Every requirement carries a `change`. One that still holds keeps its id and is
`unchanged`, with its text as it was. One that differs is `changed`; one no
longer wanted stays in the list as `removed`; a new one takes a new id and is
`added`. Everything but `unchanged` says why.
"""
name = REQUIREMENTS_FILE
before = {
item["id"]: item
for item in _items({"requirements": baseline or {}}, "requirements", name)
if isinstance(item.get("id"), str) and item.get("change") != REMOVED
}
revised = _items(
{"requirements": {"attachments": attachments}}, "requirements", name
)
problems: list[str] = []
seen = set()
for item in revised:
identifier = item.get("id")
if not isinstance(identifier, str):
continue
seen.add(identifier)
change = item.get("change")
if change not in CHANGE_KINDS:
problems.append(
f"{name}: {identifier} needs a `change`: one of "
f"{', '.join(CHANGE_KINDS)}"
)
continue
reason = item.get("reason")
if change != UNCHANGED and not (isinstance(reason, str) and reason.strip()):
problems.append(f"{name}: {identifier} is {change} and needs a `reason`")
if change == ADDED and identifier in before:
problems.append(
f"{name}: {identifier} is marked added, but the Baseline has that "
"id; a new requirement takes a new id"
)
if change != ADDED and identifier not in before:
problems.append(
f"{name}: {identifier} is marked {change}, but the Baseline has no "
"such requirement; mark a new one added"
)
if (
change == UNCHANGED
and identifier in before
and _text(item) != _text(before[identifier])
):
problems.append(
f"{name}: {identifier} is marked unchanged, but its text differs "
"from the Baseline's; restore it or mark it changed"
)
problems += [
f"{name}: Baseline requirement {identifier} is missing; keep it, or keep it "
"marked removed with the reason"
for identifier in before
if identifier not in seen
]
if revised and all(item.get("change") == UNCHANGED for item in revised):
problems.append(
f"{name}: nothing is marked added, changed or removed; a Change request "
"changes at least one requirement"
)
return problems
def _text(item: Mapping[str, Any]) -> str:
return " ".join(str(item.get("text", "")).split())
def requirement_changes(deliverables: Deliverables | None) -> list[dict[str, str]]:
"""The requirements a Change request added, changed or removed, with the reason."""
return [
{
"id": str(item.get("id")),
"change": str(item["change"]),
"reason": str(item.get("reason", "")),
"text": str(item.get("text", "")),
}
for item in _items(deliverables, "requirements", REQUIREMENTS_FILE)
if item.get("change") in (ADDED, CHANGED, REMOVED)
]
# --- comparing two versions -------------------------------------------------------------
def _compare(
before: Sequence[Mapping[str, Any]],
after: Sequence[Mapping[str, Any]] | None,
key: str = "id",
ignore: Sequence[str] = ("change", "reason"),
) -> dict[str, list[str]]:
"""Ids added, changed and removed between two lists of objects.
`after` is None while the revised Deliverable has not been produced: nothing
has changed yet, which is not the same as everything having been removed.
"""
if after is None:
return {ADDED: [], CHANGED: [], REMOVED: []}
def body(item: Mapping[str, Any]) -> dict[str, Any]:
return {name: value for name, value in item.items() if name not in ignore}
old = {str(item.get(key)): body(item) for item in before if item.get(key)}
new = {str(item.get(key)): body(item) for item in after if item.get(key)}
return {
ADDED: [identifier for identifier in new if identifier not in old],
CHANGED: [
identifier
for identifier in new
if identifier in old and new[identifier] != old[identifier]
],
REMOVED: [identifier for identifier in old if identifier not in new],
}
def reach(
changed: Sequence[str],
components: Sequence[Mapping[str, Any]],
recommendations_changed: Sequence[str],
graph: Mapping[str, Sequence[Mapping[str, Any]]],
) -> set[str]:
"""The Elements, Relationships and Checks a set of changed requirements reaches.
A changed requirement reaches the components that serve it, the Elements that
realise those components, the Relationships at those Elements, and every Check
on any of them or with the requirement as its source. A recommendation that
changed reaches the Checks that come from it and what they apply to.
"""
sources = set(changed) | set(recommendations_changed)
served = {
str(component.get("id"))
for component in components
if set(component.get("requirements") or ()) & set(changed)
}
reached = {
str(element.get("id"))
for element in graph.get("elements", ())
if element.get("component") in served
}
for check in graph.get("checks", ()):
if check.get("source") in sources:
reached.add(str(check.get("id")))
reached.add(str(check.get("applies_to")))
reached |= {
str(relationship.get("id"))
for relationship in graph.get("relationships", ())
if relationship.get("from") in reached or relationship.get("to") in reached
}
reached |= {
str(check.get("id"))
for check in graph.get("checks", ())
if check.get("applies_to") in reached
}
return reached
def change_summary(
baseline: Deliverables | None, current: Deliverables | None
) -> dict[str, Any]:
"""What a Change request changed, as changes.json holds it.
Requirements carry their own account. Everything else is compared by id. What
changed inside the reach of the changed requirements is listed as requested;
anything else that changed is listed apart as unrequested.
"""
requirements = requirement_changes(current)
changed_ids = [item["id"] for item in requirements]
produced = current or {}
recommendations = _compare(
_items(baseline, "design_recommendations", RECOMMENDATIONS_FILE),
_items(current, "design_recommendations", RECOMMENDATIONS_FILE)
if "design_recommendations" in produced
else None,
)
components = _compare(
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
_items(current, "technical_decomposition", COMPONENTS_FILE)
if "technical_decomposition" in produced
else None,
)
old_graph, new_graph = _graph(baseline), _graph(current)
designed = "target_architecture" in produced
# Reach is traced through both versions: what a requirement used to touch can
# change or go, as well as what it touches now.
touched_recommendations = recommendations[ADDED] + recommendations[CHANGED]
reached = reach(
changed_ids,
_items(current, "technical_decomposition", COMPONENTS_FILE),
touched_recommendations,
new_graph,
) | reach(
changed_ids,
_items(baseline, "technical_decomposition", COMPONENTS_FILE),
touched_recommendations + recommendations[REMOVED],
old_graph,
)
graph: dict[str, dict[str, list[str]]] = {}
unrequested: dict[str, list[str]] = {}
for part in ("elements", "relationships", "checks"):
compared = _compare(old_graph[part], new_graph[part] if designed else None)
graph[part] = compared
outside = [
identifier
for change in (ADDED, CHANGED, REMOVED)
for identifier in compared[change]
if identifier not in reached
]
if outside:
unrequested[part] = outside
return {
"requirements": requirements,
"components": components,
"recommendations": recommendations,
**graph,
# Changed without being reached by any changed requirement.
"unrequested": unrequested,
}
def is_empty(summary: Mapping[str, Any]) -> bool:
return not summary.get("requirements") and not any(
summary.get(part, {}).get(change)
for part in (
"components",
"recommendations",
"elements",
"relationships",
"checks",
)
for change in (ADDED, CHANGED, REMOVED)
)
# What an Approval of each kind of Deliverable shows of the change.
_SHOWN_WITH = {
"requirements": ("requirements",),
"technical_decomposition": ("components",),
"design_recommendations": ("recommendations",),
"target_architecture": ("elements", "relationships", "checks", "unrequested"),
}
def changes_for(summary: Mapping[str, Any], kinds: Sequence[str]) -> dict[str, Any]:
"""The part of a change summary that belongs to the Deliverables being approved,
with the parts that hold nothing left out."""
shown: dict[str, Any] = {}
for kind in kinds:
for part in _SHOWN_WITH.get(kind, ()):
value = summary.get(part)
if isinstance(value, Mapping):
value = {name: ids for name, ids in value.items() if ids}
if value:
shown[part] = value
return shown