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:
7
app/solution_architecture/__init__.py
Normal file
7
app/solution_architecture/__init__.py
Normal file
@@ -0,0 +1,7 @@
|
||||
"""Cloud solution architecture, as a Workflow on the Execution engine.
|
||||
|
||||
Brought from the engine's own example of this subject
|
||||
(`orchestration_engine/tests/reference_workflow`), itself taken from the reference
|
||||
agent `gcp_solution_architecture_agent` at commit 8b397cd. This copy is the agent's;
|
||||
the engine's stays as the test of its seam (the engine's ADR-0001).
|
||||
"""
|
||||
86
app/solution_architecture/assembly.py
Normal file
86
app/solution_architecture/assembly.py
Normal file
@@ -0,0 +1,86 @@
|
||||
"""The Reference's Workflow for one deployment: its settings and its provider bundle.
|
||||
|
||||
In the Reference this is the body of `open_assembly` in `app/agent.py`: the
|
||||
Terraform runner, the local tools built on it, and the reviews of a design before
|
||||
it is submitted.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import SubmissionReview
|
||||
from execution_engine.tools.jev import JevDecider
|
||||
from execution_engine.workflows.workflow import Assembling, LocalToolBuilder, Workflow
|
||||
|
||||
from app.solution_architecture.coverage import CoverageReview
|
||||
from app.solution_architecture.design_review import DesignCoverageReview
|
||||
from app.solution_architecture.hooks import (
|
||||
COVERAGE_REVIEWER,
|
||||
MODULES_OPTION,
|
||||
consultations,
|
||||
modules_option,
|
||||
pillar_hints,
|
||||
)
|
||||
from app.solution_architecture.local import TerraformRunner, local_tools
|
||||
from app.solution_architecture.requirements_review import RequirementsReview
|
||||
from app.solution_architecture.schema_review import Reviews, SchemaReview
|
||||
from app.solution_architecture.workflow import WORKFLOW
|
||||
|
||||
|
||||
def _runner(given: Assembling) -> TerraformRunner:
|
||||
settings, bundle = given.settings, given.bundle
|
||||
return TerraformRunner(
|
||||
binary=settings.TERRAFORM_BINARY,
|
||||
timeout_seconds=settings.TERRAFORM_TIMEOUT_SECONDS,
|
||||
plugin_cache_dir=settings.terraform_plugin_cache(),
|
||||
providers=bundle.terraform_providers,
|
||||
module_namespaces=bundle.terraform_module_namespaces,
|
||||
)
|
||||
|
||||
|
||||
def local(given: Assembling) -> LocalToolBuilder:
|
||||
runner = _runner(given)
|
||||
offered = [name for names in given.bundle.tools.values() for name in names]
|
||||
return lambda working_copy: local_tools(offered, runner, working_copy)
|
||||
|
||||
|
||||
def reviews(given: Assembling) -> SubmissionReview | None:
|
||||
"""What is looked at in a design before it is submitted. Each raises what it
|
||||
finds once and never blocks."""
|
||||
settings, bundle, decider = given.settings, given.bundle, given.decider
|
||||
found: list[SubmissionReview] = []
|
||||
if bundle.terraform_providers:
|
||||
# In code: every setting a Check names exists on its resource type.
|
||||
found.append(SchemaReview(_runner(given)))
|
||||
if settings.JEV_REQUIREMENTS_REVIEW and isinstance(decider, JevDecider):
|
||||
# Optional, and off by default: Jev says whether a requirement names a product.
|
||||
found.append(
|
||||
RequirementsReview(decider, act=settings.JEV_REQUIREMENTS_THRESHOLD)
|
||||
)
|
||||
if settings.DESIGN_COVERAGE_REVIEW and COVERAGE_REVIEWER in given.roles:
|
||||
# A model reads the requirements against the Checks, once, before the
|
||||
# design is approved: the reading the validator would make after the code.
|
||||
found.append(
|
||||
DesignCoverageReview(given.runtime, given.roles[COVERAGE_REVIEWER])
|
||||
)
|
||||
if settings.JEV_COVERAGE_REVIEW and isinstance(decider, JevDecider):
|
||||
# Optional, and off by default: Jev says which Check verifies each condition.
|
||||
found.append(CoverageReview(decider, none_at=settings.JEV_COVERAGE_THRESHOLD))
|
||||
return Reviews(found) if found else None
|
||||
|
||||
|
||||
def workflow_for(settings: Any, bundle: Any) -> Workflow:
|
||||
return dataclasses.replace(
|
||||
WORKFLOW,
|
||||
role_tools=consultations(bundle.pillar_skills),
|
||||
task_hints=pillar_hints(settings.JEV_PILLAR_THRESHOLD),
|
||||
options={
|
||||
MODULES_OPTION: modules_option(
|
||||
bool(bundle.terraform_module_namespaces), settings.TERRAFORM_MODULES
|
||||
)
|
||||
},
|
||||
local_tools=local,
|
||||
reviews=reviews,
|
||||
)
|
||||
81
app/solution_architecture/assessment.py
Normal file
81
app/solution_architecture/assessment.py
Normal file
@@ -0,0 +1,81 @@
|
||||
"""Every Execution judged as it ends (ADR-0007, iteration 5 step 19).
|
||||
|
||||
The evaluation scores benchmark cases. This asks the same graded questions of a live
|
||||
Execution's design recommendations when it ends, and keeps the answers with its
|
||||
record. It reports; it never stops or changes an Execution.
|
||||
|
||||
Without a decision an Execution carries no assessment.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Mapping
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import Decider, Question
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
GRADES = ("not at all", "weakly", "mostly", "fully")
|
||||
QUALITY_BAR = 0.67 # mean of the graded rubric: "mostly" or better
|
||||
QUALITY_RUBRIC: Mapping[str, str] = {
|
||||
"specific": "Are the recommendations specific to this workload and its stated "
|
||||
"requirements, as opposed to generic best practice that would fit any workload?",
|
||||
"actionable": "Does each recommendation name the concrete setting, feature or "
|
||||
"configuration to apply, so an engineer could act on it without more research?",
|
||||
"trade_offs": "Where pillars pull in different directions (for example cost "
|
||||
"against reliability), is the trade-off named and a resolution recommended?",
|
||||
"traceable": "Can each recommendation be traced to a requirement or constraint "
|
||||
"of the workload?",
|
||||
}
|
||||
_JUDGED = "design_recommendations"
|
||||
|
||||
|
||||
def checklist_question(pillar: str, item: str) -> str:
|
||||
"""Whether the recommendations account for one item of a pillar's checklist.
|
||||
|
||||
An item is accounted for in three ways. The third matters: a customer's request
|
||||
seldom says enough to settle every item, and what it leaves unsaid is a
|
||||
question for them, not a fault in the design (the owner, 2026-10-10).
|
||||
"""
|
||||
return (
|
||||
f"Do the recommendations account for this {pillar} checklist item in any "
|
||||
"of these ways: by recommending it, by explaining why it does not apply, "
|
||||
"or by recording it as something to confirm with the customer? "
|
||||
f"{item}"
|
||||
)
|
||||
|
||||
|
||||
async def assess(
|
||||
decider: Decider,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
*,
|
||||
scope: str = "",
|
||||
) -> dict[str, Any] | None:
|
||||
"""The rubric's scores for the design recommendations, each from 0 to 1, with
|
||||
their mean and whether it meets the bar. None when there is nothing to judge or
|
||||
no decision."""
|
||||
document = str((deliverables.get(_JUDGED) or {}).get("content", ""))
|
||||
if not document.strip():
|
||||
return None
|
||||
answers = await decider.decide(
|
||||
document,
|
||||
{key: Question("score", text, GRADES) for key, text in QUALITY_RUBRIC.items()},
|
||||
scope=scope,
|
||||
)
|
||||
if answers is None:
|
||||
return None
|
||||
top = len(GRADES) - 1
|
||||
scores = {
|
||||
key: round(min(1.0, max(0.0, float(answers[key].value) / top)), 2)
|
||||
for key in QUALITY_RUBRIC
|
||||
}
|
||||
mean = round(sum(scores.values()) / len(scores), 2)
|
||||
if mean < QUALITY_BAR:
|
||||
logger.warning("[%s] design recommendations judged at %.2f", scope, mean)
|
||||
return {
|
||||
"recommendations_quality": scores,
|
||||
"mean": mean,
|
||||
"meets_bar": mean >= QUALITY_BAR,
|
||||
}
|
||||
546
app/solution_architecture/chain.py
Normal file
546
app/solution_architecture/chain.py
Normal file
@@ -0,0 +1,546 @@
|
||||
"""The data files along the Requirements chain, and what each must hold (ADR-0005).
|
||||
|
||||
requirements.json requirements with ids
|
||||
components.json components, and the requirements each serves
|
||||
products.json the product selected for each component
|
||||
recommendations.json design recommendations with ids
|
||||
target-architecture.json the graph (see target_architecture.py)
|
||||
implementation.json which code satisfies each Check
|
||||
verdicts.json the validation verdict on each Check
|
||||
|
||||
Each checker returns what is wrong, one entry per fault, so a Specialist can fix it
|
||||
and submit again. `upstream` is the Deliverables a submission builds on, by kind; a
|
||||
link to one of them is checked only when it is there.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from app.solution_architecture.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
TargetArchitecture,
|
||||
chain_gaps,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
REQUIREMENTS_FILE = "requirements.json"
|
||||
COMPONENTS_FILE = "components.json"
|
||||
PRODUCTS_FILE = "products.json"
|
||||
RECOMMENDATIONS_FILE = "recommendations.json"
|
||||
IMPLEMENTATION_FILE = "implementation.json"
|
||||
VERDICTS_FILE = "verdicts.json"
|
||||
SCOPE_FILE = "scope.yaml" # the completed scope spec
|
||||
SCOPE_DATA_FILE = "scope.json" # what every Specialist reads of it
|
||||
|
||||
REQUIREMENT_KINDS = ("functional", "non_functional")
|
||||
VERDICTS = ("pass", "fail", "not_verifiable")
|
||||
DRY_RUN_VERDICTS = ("pass", "fail", "not_run")
|
||||
|
||||
Upstream = Mapping[str, Mapping[str, Any]]
|
||||
|
||||
|
||||
def read_list(upstream: Upstream | None, kind: str, name: str) -> list[dict[str, Any]]:
|
||||
"""An upstream data file as a list of objects; empty when absent or unreadable.
|
||||
|
||||
An entry a Change request marked removed is left out: it stays in the file as
|
||||
the record of what was dropped, and asks nothing of what follows.
|
||||
"""
|
||||
text = ((upstream 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) and item.get("change") != "removed"
|
||||
]
|
||||
if isinstance(data, list)
|
||||
else []
|
||||
)
|
||||
|
||||
|
||||
def read_graph(upstream: Upstream | None) -> TargetArchitecture | None:
|
||||
text = (
|
||||
((upstream or {}).get("target_architecture") or {})
|
||||
.get("attachments", {})
|
||||
.get(GRAPH_ATTACHMENT, "")
|
||||
)
|
||||
try:
|
||||
return parse_graph(text)
|
||||
except GraphError:
|
||||
return None
|
||||
|
||||
|
||||
def graph_structure(upstream: Upstream | None) -> str | None:
|
||||
"""The Target architecture's Elements and Relationships, as one comparable value.
|
||||
|
||||
What a Deliverable written from the shape of the design, and not from its
|
||||
Checks, was written from. None when there is no readable graph.
|
||||
"""
|
||||
graph = read_graph(upstream)
|
||||
if graph is None:
|
||||
return None
|
||||
return json.dumps(
|
||||
{
|
||||
"elements": [
|
||||
[e.id, e.name, e.product, e.resource_type, e.component]
|
||||
for e in graph.elements
|
||||
],
|
||||
"relationships": [
|
||||
[r.id, r.source, r.target, r.kind] for r in graph.relationships
|
||||
],
|
||||
},
|
||||
sort_keys=True,
|
||||
)
|
||||
|
||||
|
||||
def _objects(
|
||||
text: str, name: str, strings: Sequence[str], lists: Sequence[str] = ()
|
||||
) -> tuple[list[dict[str, Any]], list[str]]:
|
||||
"""The file's objects that have every required field, and what is wrong with it."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return [], [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, list):
|
||||
return [], [f"{name}: must be a JSON list"]
|
||||
accepted, problems = [], []
|
||||
for index, item in enumerate(data):
|
||||
where = f"{name}[{index}]"
|
||||
if not isinstance(item, dict):
|
||||
problems.append(f"{where}: must be an object")
|
||||
continue
|
||||
missing = [
|
||||
field
|
||||
for field in strings
|
||||
if not isinstance(item.get(field), str) or not item[field].strip()
|
||||
]
|
||||
missing += [
|
||||
field
|
||||
for field in lists
|
||||
if not isinstance(item.get(field), list)
|
||||
or not all(isinstance(value, str) for value in item[field])
|
||||
]
|
||||
if missing:
|
||||
problems.append(f"{where}: needs {', '.join(missing)}")
|
||||
continue
|
||||
accepted.append(item)
|
||||
return accepted, problems
|
||||
|
||||
|
||||
def _repeated(
|
||||
items: Sequence[Mapping[str, Any]], name: str, key: str = "id"
|
||||
) -> list[str]:
|
||||
seen: set[str] = set()
|
||||
problems = []
|
||||
for item in items:
|
||||
if item[key] in seen:
|
||||
problems.append(f"{name}: {key} {item[key]} is used more than once")
|
||||
seen.add(item[key])
|
||||
return problems
|
||||
|
||||
|
||||
def conditions_of(item: Mapping[str, Any]) -> tuple[str, ...]:
|
||||
"""The separate things a requirement or recommendation asks for.
|
||||
|
||||
Each is one statement that a Check can verify on its own. An item written before
|
||||
conditions were listed is read as one condition: its whole text.
|
||||
"""
|
||||
listed = item.get("conditions")
|
||||
if isinstance(listed, list):
|
||||
conditions = tuple(
|
||||
c.strip() for c in listed if isinstance(c, str) and c.strip()
|
||||
)
|
||||
if conditions:
|
||||
return conditions
|
||||
text = item.get("text")
|
||||
return (text.strip(),) if isinstance(text, str) and text.strip() else ()
|
||||
|
||||
|
||||
OUTSIDE_CODE = "outside_code"
|
||||
|
||||
|
||||
def outside_code_of(item: Mapping[str, Any]) -> tuple[str, ...]:
|
||||
"""What a requirement asks for that infrastructure code cannot show: an outcome
|
||||
measured in operation, application behaviour, or a process people follow."""
|
||||
listed = item.get(OUTSIDE_CODE)
|
||||
if not isinstance(listed, list):
|
||||
return ()
|
||||
return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip())
|
||||
|
||||
|
||||
def _lacking_conditions(items: Sequence[Mapping[str, Any]], name: str) -> list[str]:
|
||||
"""A constraint must say, one by one, what would have to be true for it to be met:
|
||||
under `conditions` what infrastructure code can show, under `outside_code` what
|
||||
it cannot. At least one of the two has an entry."""
|
||||
problems = []
|
||||
for item in items:
|
||||
listed = item.get("conditions")
|
||||
outside = item.get(OUTSIDE_CODE, [])
|
||||
well_formed = all(
|
||||
isinstance(group, list)
|
||||
and all(isinstance(c, str) and c.strip() for c in group)
|
||||
for group in (listed, outside)
|
||||
)
|
||||
if not well_formed or not (listed or outside):
|
||||
problems.append(
|
||||
f"{name}: {item['id']} needs `conditions`: a list with one entry "
|
||||
"for each separate thing it asks for that infrastructure code can "
|
||||
f"show (and `{OUTSIDE_CODE}` for what it cannot)"
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def check_requirements(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = REQUIREMENTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("id", "kind", "text"))
|
||||
problems += _repeated(items, name)
|
||||
problems += [
|
||||
f"{name}: {item['id']} kind must be one of {', '.join(REQUIREMENT_KINDS)}"
|
||||
for item in items
|
||||
if item["kind"] not in REQUIREMENT_KINDS
|
||||
]
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no requirements")
|
||||
problems += _lacking_conditions(
|
||||
[item for item in items if item["kind"] == "non_functional"], name
|
||||
)
|
||||
problems += _carries_the_scope(items, name, upstream)
|
||||
return problems
|
||||
|
||||
|
||||
def agreed_scope(upstream: Upstream | None) -> dict[str, Any]:
|
||||
"""The agreed scope, as every Specialist reads it; empty when there is none."""
|
||||
text = (
|
||||
((upstream or {}).get("scope") or {})
|
||||
.get("attachments", {})
|
||||
.get(SCOPE_DATA_FILE, "")
|
||||
)
|
||||
try:
|
||||
data = json.loads(text) if text else {}
|
||||
except ValueError:
|
||||
return {}
|
||||
return data if isinstance(data, dict) else {}
|
||||
|
||||
|
||||
def sources_of(item: Mapping[str, Any]) -> tuple[str, ...]:
|
||||
"""What a requirement comes from: the customer's own requirement ids and the
|
||||
scope spec's fields, as its `from` lists them."""
|
||||
listed = item.get("from")
|
||||
return tuple(str(s) for s in listed) if isinstance(listed, list) else ()
|
||||
|
||||
|
||||
def _carries_the_scope(
|
||||
items: Sequence[Mapping[str, Any]], name: str, upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
"""What the customer stated has to reach the requirements, by name (ADR-0008).
|
||||
|
||||
Each requirement the customer wrote, and each choice they stated that a design
|
||||
must honour, is named in the `from` of a requirement. A choice is carried by a
|
||||
non-functional requirement with a condition, so the Target architecture owes it
|
||||
a Check. Before this a stated topology could be named in a design and not built:
|
||||
case 08 on 2026-10-11 passed all 101 Checks with no Check asking for it.
|
||||
"""
|
||||
scope = agreed_scope(upstream)
|
||||
if not scope:
|
||||
return []
|
||||
stated = scope.get("stated") or {}
|
||||
theirs = [
|
||||
str(entry.get("id"))
|
||||
for entry in ((stated.get("intent") or {}).get("requirements") or [])
|
||||
if isinstance(entry, Mapping) and entry.get("id")
|
||||
]
|
||||
binding = [str(path) for path in scope.get("binding") or []]
|
||||
cited = {source for item in items for source in sources_of(item)}
|
||||
problems = [
|
||||
f"{name}: the customer's requirement {reference} is covered by no "
|
||||
"requirement; name it in the `from` of the one that covers it"
|
||||
for reference in theirs
|
||||
if reference not in cited
|
||||
]
|
||||
problems += [
|
||||
f"{name}: the customer stated {path} and no requirement carries it; add a "
|
||||
f"non-functional requirement whose `from` names {path}, with the condition "
|
||||
"that shows it was honoured"
|
||||
for path in binding
|
||||
if path not in cited
|
||||
]
|
||||
for item in items:
|
||||
carried = [source for source in sources_of(item) if source in binding]
|
||||
if carried and (
|
||||
item.get("kind") != "non_functional" or not conditions_of_listed(item)
|
||||
):
|
||||
problems.append(
|
||||
f"{name}: {item.get('id')} carries {', '.join(carried)}, a choice "
|
||||
"the customer stated; it must be non_functional with at least one "
|
||||
"entry in `conditions`, so the design is checked against it"
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def conditions_of_listed(item: Mapping[str, Any]) -> tuple[str, ...]:
|
||||
"""The conditions a requirement lists outright, with no fallback to its text."""
|
||||
listed = item.get("conditions")
|
||||
if not isinstance(listed, list):
|
||||
return ()
|
||||
return tuple(c.strip() for c in listed if isinstance(c, str) and c.strip())
|
||||
|
||||
|
||||
def check_components(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = COMPONENTS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "name"), ("requirements",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no components")
|
||||
requirements = read_list(upstream, "requirements", REQUIREMENTS_FILE)
|
||||
if requirements:
|
||||
known = {item["id"] for item in requirements}
|
||||
served: set[str] = set()
|
||||
for item in items:
|
||||
served.update(item["requirements"])
|
||||
problems += [
|
||||
f"{name}: {item['id']} serves {reference}, which is not a requirement"
|
||||
for reference in item["requirements"]
|
||||
if reference not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: functional requirement {item['id']} is served by no component"
|
||||
for item in requirements
|
||||
if item.get("kind") == "functional" and item["id"] not in served
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_products(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = PRODUCTS_FILE
|
||||
items, problems = _objects(attachments[name], name, ("component", "product"))
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
chosen = {item["component"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {item['component']} is not a component"
|
||||
for item in items
|
||||
if item["component"] not in known
|
||||
]
|
||||
problems += [
|
||||
f"{name}: component {identifier} has no product selected"
|
||||
for identifier in sorted(known - chosen)
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_recommendations(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = RECOMMENDATIONS_FILE
|
||||
items, problems = _objects(
|
||||
attachments[name], name, ("id", "pillar", "text"), ("components",)
|
||||
)
|
||||
problems += _repeated(items, name)
|
||||
if not items and not problems:
|
||||
problems.append(f"{name}: lists no recommendations")
|
||||
problems += _lacking_conditions(items, name)
|
||||
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
|
||||
if components:
|
||||
known = {item["id"] for item in components}
|
||||
problems += [
|
||||
f"{name}: {item['id']} names {reference}, which is not a component"
|
||||
for item in items
|
||||
for reference in item["components"]
|
||||
if reference not in known
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def check_target_architecture(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
try:
|
||||
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
except GraphError as exc:
|
||||
return list(exc.problems)
|
||||
if upstream is None:
|
||||
return []
|
||||
return list(
|
||||
chain_gaps(
|
||||
graph,
|
||||
requirements=read_list(upstream, "requirements", REQUIREMENTS_FILE),
|
||||
components=read_list(upstream, "technical_decomposition", COMPONENTS_FILE),
|
||||
products=read_list(upstream, "product_selection", PRODUCTS_FILE),
|
||||
recommendations=read_list(
|
||||
upstream, "design_recommendations", RECOMMENDATIONS_FILE
|
||||
),
|
||||
)
|
||||
)
|
||||
|
||||
|
||||
def _covers_every_check(
|
||||
items: Sequence[Mapping[str, Any]], name: str, graph: TargetArchitecture | None
|
||||
) -> list[str]:
|
||||
problems = _repeated(items, name, "check")
|
||||
if graph is None:
|
||||
return problems
|
||||
given = {item["check"] for item in items}
|
||||
problems += [
|
||||
f"{name}: {identifier} is not a Check in the Target architecture"
|
||||
for identifier in sorted(given - set(graph.check_ids))
|
||||
]
|
||||
problems += [
|
||||
f"{name}: Check {identifier} is not accounted for"
|
||||
for identifier in graph.check_ids
|
||||
if identifier not in given
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def _split_implementation(text: str, name: str) -> tuple[str, str]:
|
||||
"""The entries that say where a Check is met, and those that say it cannot be."""
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError:
|
||||
return text, "[]"
|
||||
if not isinstance(data, list):
|
||||
return text, "[]"
|
||||
cannot = [
|
||||
item for item in data if isinstance(item, dict) and "unimplementable" in item
|
||||
]
|
||||
met = [item for item in data if item not in cannot]
|
||||
return json.dumps(met), json.dumps(cannot)
|
||||
|
||||
|
||||
def check_scope(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]:
|
||||
"""The scope a Specialist reads: what the customer stated, what was left to the
|
||||
agent, and what is unknown."""
|
||||
name = SCOPE_DATA_FILE
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict) or not isinstance(data.get("stated"), dict):
|
||||
return [f"{name}: must be an object with what the customer stated"]
|
||||
return []
|
||||
|
||||
|
||||
def check_implementation(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = IMPLEMENTATION_FILE
|
||||
met_text, cannot_text = _split_implementation(attachments[name], name)
|
||||
met, problems = _objects(met_text, name, ("check", "file", "address"))
|
||||
cannot, faults = _objects(cannot_text, name, ("check", "unimplementable"))
|
||||
problems += faults
|
||||
problems += _covers_every_check([*met, *cannot], name, read_graph(upstream))
|
||||
problems += [
|
||||
f"{name}: {item['check']} names {item['file']}, which is not attached"
|
||||
for item in met
|
||||
if item["file"] not in attachments
|
||||
]
|
||||
return problems
|
||||
|
||||
|
||||
def unimplementable_checks(implementation_text: str) -> list[dict[str, str]]:
|
||||
"""The Checks the code's author found cannot be met as written, with the reason.
|
||||
|
||||
Each is a fault in the Target architecture, not in the code: the Check names
|
||||
something the resource does not have.
|
||||
"""
|
||||
_, cannot_text = _split_implementation(implementation_text, IMPLEMENTATION_FILE)
|
||||
cannot, _ = _objects(cannot_text, IMPLEMENTATION_FILE, ("check", "unimplementable"))
|
||||
return [
|
||||
{"check": item["check"], "reason": item["unimplementable"]} for item in cannot
|
||||
]
|
||||
|
||||
|
||||
def check_verdicts(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = VERDICTS_FILE
|
||||
try:
|
||||
data = json.loads(attachments[name])
|
||||
except ValueError as exc:
|
||||
return [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, dict):
|
||||
return [
|
||||
f"{name}: must be an object with dry_run, checks and proposed_additions"
|
||||
]
|
||||
problems: list[str] = []
|
||||
dry_run = data.get("dry_run")
|
||||
if (
|
||||
not isinstance(dry_run, dict)
|
||||
or dry_run.get("verdict") not in DRY_RUN_VERDICTS
|
||||
or not isinstance(dry_run.get("evidence"), str)
|
||||
or not dry_run["evidence"].strip()
|
||||
):
|
||||
problems.append(
|
||||
f"{name}.dry_run: needs a verdict ({', '.join(DRY_RUN_VERDICTS)}) and evidence"
|
||||
)
|
||||
items, faults = _objects(
|
||||
json.dumps(data.get("checks", [])),
|
||||
f"{name}.checks",
|
||||
("check", "verdict", "evidence"),
|
||||
)
|
||||
problems += faults
|
||||
problems += [
|
||||
f"{name}.checks: {item['check']} verdict must be one of {', '.join(VERDICTS)}"
|
||||
for item in items
|
||||
if item["verdict"] not in VERDICTS
|
||||
]
|
||||
problems += _covers_every_check(items, f"{name}.checks", read_graph(upstream))
|
||||
_, faults = _objects(
|
||||
json.dumps(data.get("proposed_additions", [])),
|
||||
f"{name}.proposed_additions",
|
||||
("statement", "applies_to", "reason"),
|
||||
)
|
||||
return problems + faults
|
||||
|
||||
|
||||
def validation_outcome(verdicts_text: str) -> dict[str, Any]:
|
||||
"""What a validation decided, for routing a Revision and for scoring.
|
||||
|
||||
Failed Checks are faults in the code. A Check that could not be verified and a
|
||||
proposed addition are gaps in the Target architecture.
|
||||
"""
|
||||
try:
|
||||
data = json.loads(verdicts_text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
checks = [item for item in data.get("checks", []) if isinstance(item, dict)]
|
||||
|
||||
def with_verdict(verdict: str) -> list[dict[str, Any]]:
|
||||
return [
|
||||
{"check": item.get("check"), "evidence": item.get("evidence")}
|
||||
for item in checks
|
||||
if item.get("verdict") == verdict
|
||||
]
|
||||
|
||||
dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {}
|
||||
return {
|
||||
"dry_run": dry_run,
|
||||
"passed": [
|
||||
item.get("check") for item in checks if item.get("verdict") == "pass"
|
||||
],
|
||||
"failed": with_verdict("fail"),
|
||||
"not_verifiable": with_verdict("not_verifiable"),
|
||||
"proposed_additions": [
|
||||
item
|
||||
for item in data.get("proposed_additions", [])
|
||||
if isinstance(item, dict)
|
||||
],
|
||||
}
|
||||
326
app/solution_architecture/changes.py
Normal file
326
app/solution_architecture/changes.py
Normal file
@@ -0,0 +1,326 @@
|
||||
"""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
|
||||
171
app/solution_architecture/coverage.py
Normal file
171
app/solution_architecture/coverage.py
Normal file
@@ -0,0 +1,171 @@
|
||||
"""A review of the Target architecture's coverage, before it is submitted.
|
||||
|
||||
The structural check knows that every non-functional requirement and every design
|
||||
recommendation is the source of a Check. It cannot know whether those Checks verify
|
||||
everything the text asks for: a requirement with three conditions and a Check for one
|
||||
passes it. The validator finds the rest later, a few at a time, and each finding
|
||||
costs a Revision of the design, the code and the validation.
|
||||
|
||||
Requirements and recommendations list their conditions one by one. For each
|
||||
condition this asks the decider (ADR-0007) which of the source's Checks verifies it,
|
||||
with "none" as an answer. A condition answered "none" is raised.
|
||||
|
||||
Two things make the question answerable, found by measurement on 2026-10-07 (see
|
||||
.agents/plans/iter-05-jev-decisions/steps/step-4.md). It is about one explicit
|
||||
condition, not a whole requirement; and it is a choice among the Checks, not a yes or
|
||||
no. Asked the broad way, a complete design and an incomplete one scored alike.
|
||||
|
||||
It never blocks: with no decision, the submission stands on its structure.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import Decider, Question
|
||||
|
||||
from app.solution_architecture.chain import (
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
Upstream,
|
||||
conditions_of,
|
||||
read_list,
|
||||
)
|
||||
from app.solution_architecture.kinds import DeliverableKind
|
||||
from app.solution_architecture.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
Check,
|
||||
GraphError,
|
||||
TargetArchitecture,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
NONE = "none"
|
||||
|
||||
|
||||
def _described(graph: TargetArchitecture) -> str:
|
||||
lines = ["Elements of the Target architecture:"]
|
||||
lines += [
|
||||
f"- {e.id} {e.name} ({e.product}, {e.resource_type})"
|
||||
+ (f", realises component {e.component}" if e.component else "")
|
||||
for e in graph.elements
|
||||
]
|
||||
lines.append("Relationships:")
|
||||
lines += [f"- {r.id}: {r.source} {r.kind} {r.target}" for r in graph.relationships]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _constraints(upstream: Upstream, graph: TargetArchitecture) -> list[dict[str, Any]]:
|
||||
"""What must be covered: every non-functional requirement, and every design
|
||||
recommendation that applies."""
|
||||
excused = {item.recommendation for item in graph.not_applicable}
|
||||
return [
|
||||
item
|
||||
for item in read_list(upstream, "requirements", REQUIREMENTS_FILE)
|
||||
if item.get("kind") == "non_functional"
|
||||
] + [
|
||||
item
|
||||
for item in read_list(upstream, "design_recommendations", RECOMMENDATIONS_FILE)
|
||||
if item.get("id") not in excused
|
||||
]
|
||||
|
||||
|
||||
def coverage_questions(
|
||||
graph: TargetArchitecture, constraints: Sequence[Mapping[str, Any]]
|
||||
) -> dict[str, tuple[str, str, Question]]:
|
||||
"""One question per condition: (source id, the condition, the question).
|
||||
|
||||
A source with no Check is the structural check's to report, so it is not asked
|
||||
about here.
|
||||
"""
|
||||
names = {element.id: element.name for element in graph.elements}
|
||||
names.update(
|
||||
{
|
||||
r.id: f"{names[r.source]} {r.kind} {names[r.target]}"
|
||||
for r in graph.relationships
|
||||
}
|
||||
)
|
||||
by_source: dict[str, list[Check]] = {}
|
||||
for check in graph.checks:
|
||||
by_source.setdefault(check.source, []).append(check)
|
||||
|
||||
questions: dict[str, tuple[str, str, Question]] = {}
|
||||
for item in constraints:
|
||||
source = item.get("id")
|
||||
checks = by_source.get(source, []) if isinstance(source, str) else []
|
||||
if not checks:
|
||||
continue
|
||||
listed = "\n".join(
|
||||
f"- {check.id} on {names[check.applies_to]}: {check.statement}"
|
||||
for check in checks
|
||||
)
|
||||
for number, condition in enumerate(conditions_of(item), start=1):
|
||||
questions[f"{source}#{number}"] = (
|
||||
str(source),
|
||||
condition,
|
||||
Question(
|
||||
"choice",
|
||||
f'Condition: "{condition}".\nChecks:\n{listed}\n'
|
||||
"Which one Check verifies this condition? Answer none when "
|
||||
"no Check does.",
|
||||
(*(check.id for check in checks), NONE),
|
||||
),
|
||||
)
|
||||
return questions
|
||||
|
||||
|
||||
class CoverageReview:
|
||||
def __init__(self, decider: Decider, *, none_at: float = 0.6) -> None:
|
||||
self._decider = decider
|
||||
# How likely "none" must be before a condition is raised. Below it the
|
||||
# answer is too uncertain to send work back on.
|
||||
self._none_at = none_at
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: DeliverableKind,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]:
|
||||
"""The conditions no Check appears to verify, each as a line for the
|
||||
Specialist. Empty when coverage looks complete or was not judged."""
|
||||
if kind != DeliverableKind.TARGET_ARCHITECTURE or not upstream:
|
||||
return ()
|
||||
try:
|
||||
graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, ""))
|
||||
except GraphError:
|
||||
return ()
|
||||
asked = coverage_questions(graph, _constraints(upstream, graph))
|
||||
if not asked:
|
||||
return ()
|
||||
answers = await self._decider.decide(
|
||||
_described(graph),
|
||||
{key: question for key, (_, _, question) in asked.items()},
|
||||
scope=scope,
|
||||
)
|
||||
if not answers:
|
||||
return ()
|
||||
concerns = []
|
||||
for key, (source, condition, question) in asked.items():
|
||||
answer = answers.get(key)
|
||||
if answer is None or answer.value != NONE:
|
||||
continue
|
||||
if answer.probabilities.get(NONE, answer.confidence) < self._none_at:
|
||||
continue
|
||||
checks = ", ".join(question.options[:-1])
|
||||
concerns.append(
|
||||
f'{source}: no Check verifies "{condition}" (its Checks: {checks})'
|
||||
)
|
||||
if concerns:
|
||||
logger.info(
|
||||
"[%s] coverage review raised %d of %d conditions",
|
||||
scope,
|
||||
len(concerns),
|
||||
len(asked),
|
||||
)
|
||||
return tuple(concerns)
|
||||
156
app/solution_architecture/design_review.py
Normal file
156
app/solution_architecture/design_review.py
Normal file
@@ -0,0 +1,156 @@
|
||||
"""A review of a design's coverage by a model, before anyone approves it.
|
||||
|
||||
The validator reads the requirements and recommendations against the Checks and
|
||||
proposes one for each condition nothing verifies. That reading needs no code, but it
|
||||
used to happen only after the code was written: in the runs of 2026-10-09 it sent
|
||||
the Target architecture back in four of seven, each time costing a Revision of the
|
||||
design, the code and the validation (iteration 6 step 12).
|
||||
|
||||
This is the same reading, made when the Target architecture is first submitted and
|
||||
returned to its author. It is a review like the others: what it raises is returned
|
||||
once and never blocks, and when it fails the submission stands.
|
||||
|
||||
It runs once in an Execution. A Revision is asked for by the validator or the user,
|
||||
who have just read the design; reviewing it again would pay for the same reading.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
RoleSpec,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
from app.solution_architecture.chain import (
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
Upstream,
|
||||
read_list,
|
||||
)
|
||||
from app.solution_architecture.kinds import DeliverableKind
|
||||
from app.solution_architecture.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
MAX_GAPS = 12
|
||||
|
||||
|
||||
class DesignCoverageReview:
|
||||
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
|
||||
self._runtime = runtime
|
||||
self._role = role
|
||||
self._reviewed: set[str] = set()
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: DeliverableKind,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]:
|
||||
"""The conditions the reviewer finds no Check verifies, each as a line for
|
||||
the target architect. Empty when it finds none or could not review."""
|
||||
if kind != DeliverableKind.TARGET_ARCHITECTURE or not upstream:
|
||||
return ()
|
||||
text = attachments.get(GRAPH_ATTACHMENT, "")
|
||||
try:
|
||||
graph = parse_graph(text)
|
||||
except GraphError:
|
||||
return ()
|
||||
if scope in self._reviewed:
|
||||
return ()
|
||||
self._reviewed.add(scope)
|
||||
|
||||
constraints = [
|
||||
item
|
||||
for item in read_list(upstream, "requirements", REQUIREMENTS_FILE)
|
||||
if item.get("kind") == "non_functional"
|
||||
] + read_list(upstream, "design_recommendations", RECOMMENDATIONS_FILE)
|
||||
known = {str(item.get("id")) for item in constraints}
|
||||
applies_to = {element.id for element in graph.elements} | {
|
||||
relationship.id for relationship in graph.relationships
|
||||
}
|
||||
|
||||
async def report_gaps(gaps: Any = None) -> ToolResult:
|
||||
if not isinstance(gaps, list):
|
||||
return ToolResult("Not recorded: `gaps` is a list; empty when none.")
|
||||
return ToolResult("Recorded.", Submitted(json.dumps(gaps)))
|
||||
|
||||
tool = ToolSpec(
|
||||
"report_gaps",
|
||||
"Give every gap you found, in one call. An empty list when the Checks "
|
||||
"verify every condition. Ends your turn.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"gaps": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"source": {
|
||||
"type": "string",
|
||||
"description": "The requirement or recommendation id",
|
||||
},
|
||||
"applies_to": {
|
||||
"type": "string",
|
||||
"description": "The Element or Relationship id",
|
||||
},
|
||||
"statement": {
|
||||
"type": "string",
|
||||
"description": "The Check that is missing",
|
||||
},
|
||||
},
|
||||
"required": ["source", "applies_to", "statement"],
|
||||
},
|
||||
}
|
||||
},
|
||||
"required": ["gaps"],
|
||||
},
|
||||
report_gaps,
|
||||
tier="execution",
|
||||
)
|
||||
task = AgentTask(
|
||||
role=self._role.name,
|
||||
prompt="Review whether the Target architecture's Checks verify every "
|
||||
"condition of the requirements and recommendations.",
|
||||
context={
|
||||
"constraints": constraints,
|
||||
"target_architecture": json.loads(text),
|
||||
},
|
||||
)
|
||||
outcome = await self._runtime.run(self._role, task, [tool])
|
||||
if not isinstance(outcome, Submitted):
|
||||
logger.info("[%s] design coverage review gave no answer", scope)
|
||||
return ()
|
||||
try:
|
||||
reported = json.loads(outcome.content)
|
||||
except ValueError:
|
||||
return ()
|
||||
concerns = []
|
||||
for gap in reported if isinstance(reported, list) else []:
|
||||
if not isinstance(gap, Mapping):
|
||||
continue
|
||||
source, where = str(gap.get("source", "")), str(gap.get("applies_to", ""))
|
||||
statement = " ".join(str(gap.get("statement", "")).split())
|
||||
# A gap must be about something that exists: an invented id is dropped.
|
||||
if source not in known or where not in applies_to or not statement:
|
||||
continue
|
||||
concerns.append(f"{source}: no Check verifies this on {where}: {statement}")
|
||||
logger.info(
|
||||
"[%s] design coverage review raised %d gap(s)", scope, len(concerns)
|
||||
)
|
||||
return tuple(concerns[:MAX_GAPS])
|
||||
482
app/solution_architecture/hooks.py
Normal file
482
app/solution_architecture/hooks.py
Normal file
@@ -0,0 +1,482 @@
|
||||
"""Where the Reference's own code runs inside the engine.
|
||||
|
||||
In the Reference these are branches inside its engine: `app/tools/execution.py` adds
|
||||
views to three Deliverables as they are submitted and adds to an Approval,
|
||||
`app/tools/toolkit.py` gives the design advisor its pillar consultation, and
|
||||
`app/adk/roles.py` gives the modules Skill to roles with the module tool. Here each
|
||||
is a function the Workflow names.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import Decider, RoleSpec, ToolSpec
|
||||
from execution_engine.workflows.deliverables import GraphShape, ListShape, Upstream
|
||||
from execution_engine.workflows.workflow import (
|
||||
Bench,
|
||||
CardText,
|
||||
ChangePolicy,
|
||||
Hints,
|
||||
OptionSpec,
|
||||
RoleTools,
|
||||
)
|
||||
|
||||
from app.solution_architecture.chain import (
|
||||
IMPLEMENTATION_FILE,
|
||||
RECOMMENDATIONS_FILE,
|
||||
REQUIREMENTS_FILE,
|
||||
read_graph,
|
||||
read_list,
|
||||
unimplementable_checks,
|
||||
)
|
||||
from app.solution_architecture.changes import (
|
||||
CHANGES_FILE,
|
||||
change_summary,
|
||||
changes_for,
|
||||
is_empty,
|
||||
)
|
||||
from app.solution_architecture.changes import _graph as changes_graph
|
||||
from app.solution_architecture.meaning import settle_meaning
|
||||
from app.solution_architecture.modules import MODULE_TOOL, MODULES_OPTED_IN
|
||||
from app.solution_architecture.pillars import (
|
||||
ADVICE_KEY,
|
||||
QUESTIONS_HEADING,
|
||||
REVIEW_HEADING,
|
||||
customer_questions,
|
||||
pillar_consultation_tool,
|
||||
pillars_touched,
|
||||
render_checklist_review,
|
||||
)
|
||||
from app.solution_architecture.presentation import (
|
||||
_describe_changes,
|
||||
_describe_target_architecture,
|
||||
)
|
||||
from app.solution_architecture.target_architecture import (
|
||||
DIAGRAM_ATTACHMENT,
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
parse_graph,
|
||||
render_mermaid,
|
||||
render_tables,
|
||||
)
|
||||
from app.solution_architecture.work_breakdown import (
|
||||
DICTIONARY_HEADING,
|
||||
TIMELINE_FILE,
|
||||
)
|
||||
from app.solution_architecture.work_breakdown import mermaid as plan_mermaid
|
||||
from app.solution_architecture.work_breakdown import render as render_plan
|
||||
from app.solution_architecture.work_breakdown import summary as plan_summary
|
||||
|
||||
PILLAR_ADVISOR = "pillar-advisor"
|
||||
COVERAGE_REVIEWER = "coverage-reviewer" # reviews a design before its Approval
|
||||
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
||||
TARGET_ARCHITECTURE = "target_architecture"
|
||||
WORK_BREAKDOWN = "work_breakdown"
|
||||
MODULES_OPTION = "terraform_modules"
|
||||
GUIDE_FILENAME = "solution-architecture-guide.md"
|
||||
QUESTIONS_FILENAME = "customer-questions.md" # what to ask the customer
|
||||
|
||||
# The Target architecture, as the Specialist builds it in its working copy.
|
||||
GRAPH_SHAPE = GraphShape(
|
||||
attachment=GRAPH_ATTACHMENT,
|
||||
lists={
|
||||
"elements": ListShape(
|
||||
("id", "name", "product", "resource_type"),
|
||||
optional=("component",),
|
||||
label="Elements",
|
||||
),
|
||||
"relationships": ListShape(("id", "from", "to", "kind"), label="Relationships"),
|
||||
"checks": ListShape(
|
||||
("id", "applies_to", "statement", "source"), label="Checks"
|
||||
),
|
||||
"not_applicable": ListShape(("recommendation", "reason"), key="recommendation"),
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
def check_ids(upstream: Upstream | None) -> Sequence[str]:
|
||||
graph = read_graph(upstream)
|
||||
return graph.check_ids if graph else ()
|
||||
|
||||
|
||||
def with_checklist_review(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
# The pillar advisors' checklist reviews, written from what they recorded. A
|
||||
# Revision replaces the section, never stacks a second.
|
||||
checklist_review = render_checklist_review(bench.working)
|
||||
content = content.split(f"\n## {REVIEW_HEADING}")[0].rstrip() + "\n"
|
||||
if checklist_review:
|
||||
content += "\n" + checklist_review
|
||||
return content, attachments
|
||||
|
||||
|
||||
def with_plan_views(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
# The dictionary, the sequence and the timeline are views of the plan, computed
|
||||
# and written here: they cannot disagree with it.
|
||||
views = render_plan(attachments, bench.upstream)
|
||||
content = content.split(f"\n## {DICTIONARY_HEADING}")[0].rstrip() + "\n"
|
||||
if views:
|
||||
content += "\n" + views
|
||||
chart = plan_mermaid(attachments, bench.upstream)
|
||||
if chart:
|
||||
attachments[TIMELINE_FILE] = chart
|
||||
return content, attachments
|
||||
|
||||
|
||||
def with_graph_views(
|
||||
bench: Bench, content: str, attachments: dict[str, str]
|
||||
) -> tuple[str, dict[str, str]]:
|
||||
# The tables and the diagram are views of the graph, so code writes them: they
|
||||
# cannot disagree with it.
|
||||
graph = parse_graph(attachments[GRAPH_ATTACHMENT])
|
||||
content = content.rstrip() + "\n\n" + render_tables(graph)
|
||||
attachments[DIAGRAM_ATTACHMENT] = render_mermaid(graph)
|
||||
return content, attachments
|
||||
|
||||
|
||||
def approval_details(
|
||||
phase: str,
|
||||
deliverables: Mapping[str, Mapping[str, Any]],
|
||||
baseline: Mapping[str, Any] | None,
|
||||
*,
|
||||
in_phase: Sequence[str],
|
||||
design_phase: str,
|
||||
) -> dict[str, Any]:
|
||||
details: dict[str, Any] = {}
|
||||
if baseline:
|
||||
# Worked out from the ids, not written by an agent: what this Phase's
|
||||
# Deliverables add, change and remove against the Baseline.
|
||||
details["changes"] = changes_for(
|
||||
change_summary(baseline.get("deliverables"), deliverables), list(in_phase)
|
||||
)
|
||||
target = deliverables.get(TARGET_ARCHITECTURE)
|
||||
if target and phase == design_phase:
|
||||
try:
|
||||
graph = parse_graph(target.get("attachments", {})[GRAPH_ATTACHMENT])
|
||||
except (KeyError, GraphError):
|
||||
return details
|
||||
# What the user is approving before any code is written.
|
||||
details["target_architecture"] = graph.summary()
|
||||
return details
|
||||
|
||||
|
||||
def consultations(pillar_skills: Mapping[str, str]):
|
||||
"""The design advisor's pillar consultation, for a bundle's pillar Skills."""
|
||||
|
||||
def role_tools(given: RoleTools) -> Sequence[ToolSpec]:
|
||||
advisor = given.roles.get(PILLAR_ADVISOR)
|
||||
if not (
|
||||
pillar_skills and advisor and given.deliverable == DESIGN_RECOMMENDATIONS
|
||||
):
|
||||
return ()
|
||||
# Pillar advisors can't ask for permission, so they get general-tier tools only.
|
||||
advisor_tools = [
|
||||
tool for tool in given.mcp_tools(advisor) if tool.tier == "general"
|
||||
]
|
||||
return (
|
||||
pillar_consultation_tool(
|
||||
given.runtime,
|
||||
advisor,
|
||||
pillar_skills,
|
||||
extra_tools=advisor_tools,
|
||||
memory=given.working,
|
||||
limiter=given.limiter,
|
||||
),
|
||||
)
|
||||
|
||||
return role_tools
|
||||
|
||||
|
||||
def with_modules_skill(
|
||||
roles: Mapping[str, RoleSpec], bundle: Any
|
||||
) -> Mapping[str, RoleSpec]:
|
||||
if not bundle.terraform_modules_skill:
|
||||
return roles
|
||||
return {
|
||||
name: dataclasses.replace(role, modules_skill=bundle.terraform_modules_skill)
|
||||
if MODULE_TOOL in role.tools
|
||||
else role
|
||||
for name, role in roles.items()
|
||||
}
|
||||
|
||||
|
||||
# --- what the router and the Execution's nodes read ------------------------------------
|
||||
|
||||
|
||||
def unimplementable(deliverables: Upstream) -> list[dict[str, str]]:
|
||||
"""Checks the code's author reported cannot be met as the design words them."""
|
||||
return unimplementable_checks(
|
||||
(deliverables.get("deployment_guidance") or {})
|
||||
.get("attachments", {})
|
||||
.get(IMPLEMENTATION_FILE, "")
|
||||
)
|
||||
|
||||
|
||||
def known_ids(deliverables: Upstream) -> set[str]:
|
||||
return {
|
||||
item["id"]
|
||||
for name, kind in (
|
||||
(REQUIREMENTS_FILE, "requirements"),
|
||||
(RECOMMENDATIONS_FILE, DESIGN_RECOMMENDATIONS),
|
||||
)
|
||||
for item in read_list(deliverables, kind, name)
|
||||
if "id" in item
|
||||
}
|
||||
|
||||
|
||||
def agreed(deliverables: Upstream) -> str:
|
||||
return str(
|
||||
(deliverables.get("requirements") or {})
|
||||
.get("attachments", {})
|
||||
.get(REQUIREMENTS_FILE, "")
|
||||
)
|
||||
|
||||
|
||||
def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]:
|
||||
facts: dict[str, Any] = {}
|
||||
counts = {
|
||||
"requirements": len(read_list(deliverables, "requirements", REQUIREMENTS_FILE)),
|
||||
"recommendations": len(
|
||||
read_list(deliverables, DESIGN_RECOMMENDATIONS, RECOMMENDATIONS_FILE)
|
||||
),
|
||||
}
|
||||
facts["counts"] = {name: count for name, count in counts.items() if count}
|
||||
plan = deliverables.get(WORK_BREAKDOWN)
|
||||
if plan and phase == "packaging":
|
||||
# How long the build is planned to take, and whether that fits.
|
||||
facts["delivery_plan"] = plan_summary(plan.get("attachments", {}), deliverables)
|
||||
graph = read_graph(deliverables)
|
||||
if graph is not None:
|
||||
facts["target_architecture"] = graph.summary()
|
||||
return facts
|
||||
|
||||
|
||||
def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]:
|
||||
lines = []
|
||||
counts = facts.get("counts") or {}
|
||||
if counts:
|
||||
lines.append(
|
||||
", ".join(f"{count} {name}" for name, count in counts.items()) + "."
|
||||
)
|
||||
plan = facts.get("delivery_plan")
|
||||
if plan:
|
||||
fits = plan.get("within_window")
|
||||
lines.append(
|
||||
f"Delivery plan: {plan['activities']} activities in "
|
||||
f"{plan['work_packages']} work packages, {plan['weeks']} weeks with a "
|
||||
f"team of {plan['team_size']}"
|
||||
+ (
|
||||
""
|
||||
if fits is None
|
||||
else f", {'inside' if fits else 'over'} the "
|
||||
f"{plan['window_weeks']}-week window"
|
||||
)
|
||||
+ "."
|
||||
)
|
||||
graph = facts.get("target_architecture")
|
||||
if graph:
|
||||
lines.append(
|
||||
f"Target architecture: {graph['elements']} Elements, "
|
||||
f"{graph['relationships']} Relationships, {graph['checks']} Checks."
|
||||
)
|
||||
return lines
|
||||
|
||||
|
||||
def changes_in_words(summary: Mapping[str, Any]) -> str:
|
||||
return "\n".join(
|
||||
f"Requirement {item['id']} {item['change']}: {item['text']} ({item['reason']})"
|
||||
for item in summary["requirements"]
|
||||
)
|
||||
|
||||
|
||||
async def settle(
|
||||
decider: Decider,
|
||||
summary: dict[str, Any],
|
||||
before: Upstream | None,
|
||||
after: Upstream,
|
||||
*,
|
||||
unchanged_at: float,
|
||||
scope: str,
|
||||
) -> dict[str, Any]:
|
||||
return await settle_meaning(
|
||||
decider, summary, before, after, unchanged_at=unchanged_at, scope=scope
|
||||
)
|
||||
|
||||
|
||||
CHANGES = ChangePolicy(
|
||||
file=CHANGES_FILE,
|
||||
summary=change_summary,
|
||||
is_empty=is_empty,
|
||||
in_words=changes_in_words,
|
||||
settle=settle,
|
||||
)
|
||||
|
||||
|
||||
def describe_design(deliverables: Upstream) -> str:
|
||||
design = "\n".join(
|
||||
f"- {item.get('name', item.get('id', ''))} ({item.get('product', '')}, "
|
||||
f"{item.get('resource_type', '')})"
|
||||
for item in changes_graph(deliverables)["elements"]
|
||||
)
|
||||
return f"Elements of the Target architecture:\n{design}" if design else ""
|
||||
|
||||
|
||||
def prepare_role(role: RoleSpec, task_input: Mapping[str, Any]) -> RoleSpec:
|
||||
opted_in = bool(task_input.get(MODULES_OPTION))
|
||||
MODULES_OPTED_IN.set(opted_in)
|
||||
if opted_in and role.modules_skill:
|
||||
return dataclasses.replace(role, skills=(*role.skills, role.modules_skill))
|
||||
if MODULE_TOOL in role.tools:
|
||||
# Plain resources: no modules Skill and no module lookup.
|
||||
return dataclasses.replace(
|
||||
role, tools=tuple(tool for tool in role.tools if tool != MODULE_TOOL)
|
||||
)
|
||||
return role
|
||||
|
||||
|
||||
def task_entries(
|
||||
state: Mapping[str, Any], kind: str
|
||||
) -> tuple[dict[str, Any], dict[str, Any]]:
|
||||
# Whether this Execution opted into published Terraform modules. False:
|
||||
# infrastructure code is plain resources. True: a published module may be used
|
||||
# where the modules Skill says one fits.
|
||||
opted_in = bool((state.get("options") or {}).get(MODULES_OPTION))
|
||||
return {MODULES_OPTION: opted_in}, {
|
||||
MODULES_OPTION: opted_in,
|
||||
# The pillars a change touches, when that could be judged: the design
|
||||
# advisor consults those and keeps its earlier advice for the rest.
|
||||
"pillars_to_consult": None,
|
||||
}
|
||||
|
||||
|
||||
def pillar_hints(threshold: float = 1.5):
|
||||
"""Which pillars the design advisor should consult again, when it is being
|
||||
started on a Revision or a Change request and advice from before exists."""
|
||||
|
||||
async def task_hints(given: Hints) -> Mapping[str, Mapping[str, Any]]:
|
||||
kind = DESIGN_RECOMMENDATIONS
|
||||
if given.decider is None or kind not in given.started:
|
||||
return {}
|
||||
state = given.state
|
||||
baseline = state.get("baseline") or {}
|
||||
remembered = state.get("working", {}).get(kind, {}).get(
|
||||
ADVICE_KEY
|
||||
) or baseline.get("working", {}).get(kind, {}).get(ADVICE_KEY)
|
||||
if not remembered:
|
||||
return {} # a first consultation: every pillar
|
||||
change = "\n".join(given.feedback.get(kind, ())) or given.changed
|
||||
chosen = await pillars_touched(
|
||||
given.decider,
|
||||
list(remembered),
|
||||
change,
|
||||
threshold=threshold,
|
||||
scope=str(state["execution_id"]),
|
||||
)
|
||||
# None: no decision, so no hint and every pillar. An empty list is an answer.
|
||||
return {} if chosen is None else {kind: {"pillars_to_consult": chosen}}
|
||||
|
||||
return task_hints
|
||||
|
||||
|
||||
def outputs(
|
||||
state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str]
|
||||
) -> dict[str, Any]:
|
||||
"""The Reference's own files and manifest entries."""
|
||||
questions = customer_questions(
|
||||
state.get("working", {}).get(DESIGN_RECOMMENDATIONS, {})
|
||||
)
|
||||
if questions:
|
||||
# What the request did not say enough to settle, as questions to put to
|
||||
# the customer. Missing information, not a fault in the design.
|
||||
files[QUESTIONS_FILENAME] = "\n".join(
|
||||
[
|
||||
f"# {QUESTIONS_HEADING}",
|
||||
"",
|
||||
(
|
||||
"The request did not say enough to settle these. Each answer "
|
||||
"may change a recommendation."
|
||||
),
|
||||
"",
|
||||
*(
|
||||
f"- **{item['pillar']}**, {item['item']} {item['question']}"
|
||||
for item in questions
|
||||
),
|
||||
"",
|
||||
]
|
||||
)
|
||||
plan = deliverables.get(WORK_BREAKDOWN)
|
||||
plan_record: dict[str, Any] | None = None
|
||||
guide = GUIDE_FILENAME in files
|
||||
if plan:
|
||||
plan_record = plan_summary(plan.get("attachments", {}), deliverables) or None
|
||||
timeline = str(plan.get("content", "")).partition("\n## Timeline\n")[2]
|
||||
if guide and timeline:
|
||||
# The guide and the plan are written side by side, so neither holds the
|
||||
# other. The plan's timeline is added to the guide here, from the plan.
|
||||
appendix = (
|
||||
"\n\n## Delivery plan\n\n"
|
||||
f"From the work breakdown structure (`deliverables/"
|
||||
f"{WORK_BREAKDOWN}.md`), which has the work "
|
||||
"packages and the full activity sequence.\n\n" + timeline.strip() + "\n"
|
||||
)
|
||||
files[GUIDE_FILENAME] = files[GUIDE_FILENAME].rstrip() + appendix
|
||||
guide_document = "deliverables/solution_guide.md"
|
||||
files[guide_document] = files[guide_document].rstrip() + appendix
|
||||
return {
|
||||
# Whether its infrastructure code was allowed published modules.
|
||||
MODULES_OPTION: bool((state.get("options") or {}).get(MODULES_OPTION)),
|
||||
# The plan in a few numbers: its length, and whether it fits the window.
|
||||
"delivery_plan": plan_record,
|
||||
"solution_guide": GUIDE_FILENAME if guide else None,
|
||||
# Questions the request left open, for the customer; None when there are none.
|
||||
"customer_questions": QUESTIONS_FILENAME if questions else None,
|
||||
}
|
||||
|
||||
|
||||
def modules_option(available: bool, default: bool) -> OptionSpec:
|
||||
"""Whether an Execution may use published Terraform modules: off unless the
|
||||
deployment says otherwise, and refused when the provider approves no sources."""
|
||||
|
||||
def check(value: Any) -> str | None:
|
||||
if not isinstance(value, bool):
|
||||
return "terraform_modules must be true or false"
|
||||
if value and not available:
|
||||
return (
|
||||
"terraform_modules: this Cloud provider has no approved module sources"
|
||||
)
|
||||
return None
|
||||
|
||||
return OptionSpec(
|
||||
default=default and available,
|
||||
spec_field="run.terraform_modules",
|
||||
check=check,
|
||||
)
|
||||
|
||||
|
||||
def describe_approval(approval: Mapping[str, Any]) -> str:
|
||||
return _describe_changes(approval) + _describe_target_architecture(
|
||||
approval.get("target_architecture")
|
||||
)
|
||||
|
||||
|
||||
CARD = CardText(
|
||||
description=(
|
||||
"Designs a cloud solution architecture with you: requirements discovery, "
|
||||
"grounded product selection, diagram, design recommendations, "
|
||||
"infrastructure-as-code and dry-run validation, packaged as a solution "
|
||||
"guide."
|
||||
),
|
||||
skill_id="solution-architecture",
|
||||
skill_name="Cloud solution architecture",
|
||||
tags=("architecture", "cloud", "terraform"),
|
||||
examples=(
|
||||
"Design a regional event ingestion platform on Google Cloud.",
|
||||
"Migrate our on-premises order service to managed services.",
|
||||
),
|
||||
)
|
||||
35
app/solution_architecture/kinds.py
Normal file
35
app/solution_architecture/kinds.py
Normal file
@@ -0,0 +1,35 @@
|
||||
"""The Reference's Phases and Deliverable kinds, from its `app/workflows/deliverables.py`."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from enum import StrEnum
|
||||
|
||||
|
||||
class PhaseId(StrEnum):
|
||||
# Scoping: what the customer wants and the facts a design depends on, agreed
|
||||
# before requirements are derived from it (ADR-0008).
|
||||
SCOPING = "scoping"
|
||||
REQUIREMENTS_DISCOVERY = "requirements_discovery"
|
||||
# Design: ends with the Target architecture, approved before any code is written.
|
||||
SOLUTION_ARCHITECTURE = "solution_architecture"
|
||||
SOLUTION_IMPLEMENTATION = "solution_implementation"
|
||||
SOLUTION_VALIDATION = "solution_validation"
|
||||
PACKAGING = "packaging"
|
||||
|
||||
|
||||
PHASE_ORDER: tuple[PhaseId, ...] = tuple(PhaseId)
|
||||
|
||||
|
||||
class DeliverableKind(StrEnum):
|
||||
SCOPE = "scope"
|
||||
REQUIREMENTS = "requirements"
|
||||
TECHNICAL_DECOMPOSITION = "technical_decomposition"
|
||||
PRODUCT_SELECTION = "product_selection"
|
||||
DESIGN_RECOMMENDATIONS = "design_recommendations"
|
||||
TARGET_ARCHITECTURE = "target_architecture"
|
||||
ARCHITECTURE_DESCRIPTION = "architecture_description"
|
||||
DEPLOYMENT_GUIDANCE = "deployment_guidance"
|
||||
VALIDATION_RESULTS = "validation_results"
|
||||
# The plan for building what was designed and validated (iteration 10).
|
||||
WORK_BREAKDOWN = "work_breakdown"
|
||||
SOLUTION_GUIDE = "solution_guide"
|
||||
788
app/solution_architecture/local.py
Normal file
788
app/solution_architecture/local.py
Normal file
@@ -0,0 +1,788 @@
|
||||
"""Local tools: a Mermaid syntax check and Terraform checks in a scratch directory.
|
||||
|
||||
Terraform runs only fmt, init -backend=false, validate, plan and providers schema. No
|
||||
command that changes cloud resources is ever constructed.
|
||||
|
||||
A Specialist with a working copy (app/tools/workspace.py) runs the checks on it and
|
||||
passes no files; `terraform_fmt` formats the working copy in place. That is what
|
||||
keeps a fix cheap: the model changes a line and validates, without sending every file
|
||||
again on each call.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import difflib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import tempfile
|
||||
from collections.abc import (
|
||||
Awaitable,
|
||||
Callable,
|
||||
Iterable,
|
||||
Mapping,
|
||||
MutableMapping,
|
||||
Sequence,
|
||||
)
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path, PurePosixPath
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
FILES_SCHEMA,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
files_from_argument,
|
||||
)
|
||||
|
||||
from app.solution_architecture.modules import (
|
||||
ModuleLookup,
|
||||
allowed_namespaces,
|
||||
check_module_sources,
|
||||
)
|
||||
|
||||
_MAX_OUTPUT = 8_000
|
||||
_MAX_OUTLINE = 4_000 # one resource type, when several are looked up together
|
||||
_MAX_TYPES = 20 # resource types in one lookup
|
||||
_TERRAFORM_SUFFIXES = (".tf", ".tfvars", ".tf.json")
|
||||
_VARIABLE_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_-]*$")
|
||||
_MERMAID_TYPES = (
|
||||
"flowchart",
|
||||
"graph",
|
||||
"sequenceDiagram",
|
||||
"classDiagram",
|
||||
"stateDiagram",
|
||||
"stateDiagram-v2",
|
||||
"erDiagram",
|
||||
"C4Context",
|
||||
"C4Container",
|
||||
"C4Component",
|
||||
"C4Deployment",
|
||||
"architecture-beta",
|
||||
"block-beta",
|
||||
)
|
||||
_BRACKETS = {"]": "[", ")": "(", "}": "{"}
|
||||
|
||||
|
||||
async def mermaid_check(diagram: str) -> ToolResult:
|
||||
"""A basic structural check; it does not render the diagram."""
|
||||
problems = []
|
||||
lines = [
|
||||
line.strip()
|
||||
for line in diagram.splitlines()
|
||||
if line.strip() and not line.strip().startswith("%%")
|
||||
]
|
||||
if not diagram.strip():
|
||||
problems.append("the diagram is empty")
|
||||
elif not lines or lines[0].split()[0] not in _MERMAID_TYPES:
|
||||
problems.append(
|
||||
"the first line must declare a diagram type, such as 'flowchart TD'"
|
||||
)
|
||||
for number, line in enumerate(diagram.splitlines(), start=1):
|
||||
stack: list[str] = []
|
||||
in_quotes = False
|
||||
for char in line:
|
||||
if char == '"':
|
||||
in_quotes = not in_quotes
|
||||
elif in_quotes:
|
||||
continue
|
||||
elif char in "[({":
|
||||
stack.append(char)
|
||||
elif char in _BRACKETS and (not stack or stack.pop() != _BRACKETS[char]):
|
||||
stack.append("!")
|
||||
break
|
||||
if stack:
|
||||
problems.append(f"Unbalanced brackets on line {number}: {line.strip()}")
|
||||
if problems:
|
||||
return ToolResult("Mermaid check failed: " + "; ".join(problems))
|
||||
return ToolResult("Mermaid check passed (structure only; not rendered).")
|
||||
|
||||
|
||||
@dataclass
|
||||
class TerraformRunner:
|
||||
binary: str = "terraform"
|
||||
timeout_seconds: float = 300
|
||||
# Providers are downloaded here once and reused by every later check. Without it,
|
||||
# each validate or plan downloads its providers again into a scratch directory.
|
||||
plugin_cache_dir: str | None = None
|
||||
# The providers the schema lookup answers for, as the provider bundle pins them:
|
||||
# {local name: {"source": ..., "version": ...}}.
|
||||
providers: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
|
||||
# Registry namespaces a `module` may come from, as the provider bundle lists
|
||||
# them. `terraform init` downloads and evaluates whatever a source names, so
|
||||
# with none listed every module call is refused.
|
||||
module_namespaces: tuple[str, ...] = ()
|
||||
# Terraform's plugin cache is not safe for concurrent installs.
|
||||
_init_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
|
||||
_schema_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
|
||||
# resource type -> (provider label, the resource's schema block)
|
||||
_schemas: dict[str, tuple[str, dict[str, Any]]] | None = field(
|
||||
default=None, repr=False
|
||||
)
|
||||
|
||||
async def formatted(self, files: Mapping[str, str]) -> dict[str, str] | ToolResult:
|
||||
"""The files formatting changes, with their new content; or why it failed."""
|
||||
refusal = _check_files(files)
|
||||
if refusal:
|
||||
return refusal
|
||||
with tempfile.TemporaryDirectory(prefix="tf-fmt-") as tmp:
|
||||
root = _write(Path(tmp), files)
|
||||
code, output = await self._run(
|
||||
[self.binary, "fmt", "-recursive", "-list=true"], root
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(f"terraform fmt failed:\n{output}")
|
||||
return {
|
||||
name: (root / name).read_text()
|
||||
for name in files
|
||||
if (root / name).read_text() != files[name]
|
||||
}
|
||||
|
||||
async def fmt(self, files: Mapping[str, str]) -> ToolResult:
|
||||
changed = await self.formatted(files)
|
||||
if isinstance(changed, ToolResult):
|
||||
return changed
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
formatted = "\n\n".join(
|
||||
f"--- {name}\n{content}" for name, content in changed.items()
|
||||
)
|
||||
return ToolResult(
|
||||
_clip(f"terraform fmt reformatted {len(changed)} file(s):\n\n{formatted}")
|
||||
)
|
||||
|
||||
async def validate(self, files: Mapping[str, str]) -> ToolResult:
|
||||
refusal = (
|
||||
_check_files(files)
|
||||
or check_providers(files, self.providers)
|
||||
or check_module_sources(files, allowed_namespaces(self.module_namespaces))
|
||||
)
|
||||
if refusal:
|
||||
return refusal
|
||||
with tempfile.TemporaryDirectory(prefix="tf-validate-") as tmp:
|
||||
root = _write(Path(tmp), files) / _module_dir(files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
code, output = await self._run([self.binary, "validate", "-no-color"], root)
|
||||
verdict = "passed" if code == 0 else "failed"
|
||||
return ToolResult(_clip(f"terraform validate {verdict}:\n{output}"))
|
||||
|
||||
async def plan(
|
||||
self, files: Mapping[str, str], variables: Mapping[str, str] | None = None
|
||||
) -> ToolResult:
|
||||
refusal = (
|
||||
_check_files(files)
|
||||
or check_providers(files, self.providers)
|
||||
or check_module_sources(files, allowed_namespaces(self.module_namespaces))
|
||||
)
|
||||
if refusal:
|
||||
return refusal
|
||||
variables = dict(variables or {})
|
||||
bad = [name for name in variables if not _VARIABLE_NAME.match(name)]
|
||||
if bad:
|
||||
return ToolResult(f"Refused: invalid variable names {', '.join(bad)}")
|
||||
with tempfile.TemporaryDirectory(prefix="tf-plan-") as tmp:
|
||||
root = _write(Path(tmp), files) / _module_dir(files)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
args = [
|
||||
self.binary,
|
||||
"plan",
|
||||
"-no-color",
|
||||
"-input=false",
|
||||
"-lock=false",
|
||||
"-refresh=true",
|
||||
*(f"-var={name}={value}" for name, value in variables.items()),
|
||||
]
|
||||
code, output = await self._run(args, root)
|
||||
verdict = "completed" if code == 0 else "failed"
|
||||
return ToolResult(
|
||||
_clip(f"terraform plan {verdict} (nothing was applied):\n{output}")
|
||||
)
|
||||
|
||||
async def schema(
|
||||
self,
|
||||
resource_type: str = "",
|
||||
block: str = "",
|
||||
find: str = "",
|
||||
resource_types: Sequence[str] = (),
|
||||
) -> ToolResult:
|
||||
"""What a resource type accepts, from the pinned provider's own schema.
|
||||
|
||||
Several resource types at once come back as outlines: every argument and
|
||||
block each accepts, by name. That is one call for a whole design, where one
|
||||
call per type or per setting is what used up a Specialist's budget.
|
||||
"""
|
||||
loaded = await self._load_schemas()
|
||||
if isinstance(loaded, ToolResult):
|
||||
return loaded
|
||||
wanted = list(
|
||||
dict.fromkeys(
|
||||
name
|
||||
for name in [*resource_types, *re.split(r"[,\s]+", resource_type)]
|
||||
if name
|
||||
)
|
||||
)
|
||||
if not wanted:
|
||||
return ToolResult("Refused: name at least one resource type.")
|
||||
if len(wanted) > 1:
|
||||
parts = []
|
||||
for name in wanted[:_MAX_TYPES]:
|
||||
if name not in loaded:
|
||||
close = difflib.get_close_matches(name, loaded, n=3, cutoff=0.6)
|
||||
hint = f" Close matches: {', '.join(close)}." if close else ""
|
||||
parts.append(
|
||||
f"{name}: not a resource type of {self._provider_labels()}."
|
||||
f"{hint}"
|
||||
)
|
||||
continue
|
||||
parts.append(_outline_only(name, loaded[name][1]))
|
||||
if len(wanted) > _MAX_TYPES:
|
||||
parts.append(
|
||||
f"[{len(wanted) - _MAX_TYPES} more not shown: ask for at most "
|
||||
f"{_MAX_TYPES} at a time]"
|
||||
)
|
||||
return ToolResult(
|
||||
f"{self._provider_labels()}. * marks a required argument.\n\n"
|
||||
+ "\n\n".join(parts)
|
||||
)
|
||||
resource_type = wanted[0]
|
||||
if resource_type not in loaded:
|
||||
close = difflib.get_close_matches(resource_type, loaded, n=5, cutoff=0.6)
|
||||
hint = f" Close matches: {', '.join(close)}." if close else ""
|
||||
return ToolResult(
|
||||
f"No resource type {resource_type} in {self._provider_labels()}.{hint}"
|
||||
)
|
||||
label, root = loaded[resource_type]
|
||||
title = f"{resource_type} ({label})"
|
||||
if find:
|
||||
# Several names in one call: one answer each, and one model request.
|
||||
names = [name for name in re.split(r"[,\s]+", find) if name]
|
||||
return ToolResult(
|
||||
_clip("\n".join(_find_in_schema(title, root, name) for name in names))
|
||||
)
|
||||
node = root
|
||||
for step in [part for part in block.split(".") if part]:
|
||||
nested = node.get("block_types", {}).get(step)
|
||||
if nested is None:
|
||||
inside = ", ".join(sorted(node.get("block_types", {}))) or "none"
|
||||
return ToolResult(
|
||||
f"{title} has no block {block!r}: {step!r} is not a block there. "
|
||||
f"Blocks at that level: {inside}."
|
||||
)
|
||||
node = nested["block"]
|
||||
heading = f"{title}, block {block}" if block else title
|
||||
rendered = _render_schema(heading, node)
|
||||
if len(rendered) > _MAX_OUTPUT:
|
||||
rendered = (
|
||||
rendered[:_MAX_OUTPUT]
|
||||
+ "\n[cut short: use `block` or `find` for what is missing]"
|
||||
)
|
||||
return ToolResult(rendered)
|
||||
|
||||
def _provider_labels(self) -> str:
|
||||
return (
|
||||
", ".join(
|
||||
f"{pin['source']} {pin['version']}" for pin in self.providers.values()
|
||||
)
|
||||
or "no pinned provider"
|
||||
)
|
||||
|
||||
async def _load_schemas(self) -> dict[str, tuple[str, dict[str, Any]]] | ToolResult:
|
||||
async with self._schema_lock:
|
||||
if self._schemas is not None:
|
||||
return self._schemas
|
||||
if not self.providers:
|
||||
return ToolResult(
|
||||
"Schema lookup is unavailable: the Cloud provider bundle pins no "
|
||||
"Terraform provider."
|
||||
)
|
||||
required = "\n".join(
|
||||
f' {name} = {{ source = "{pin["source"]}", '
|
||||
f'version = "{pin["version"]}" }}'
|
||||
for name, pin in self.providers.items()
|
||||
)
|
||||
with tempfile.TemporaryDirectory(prefix="tf-schema-") as tmp:
|
||||
root = Path(tmp)
|
||||
(root / "versions.tf").write_text(
|
||||
f"terraform {{\n required_providers {{\n{required}\n }}\n}}\n"
|
||||
)
|
||||
failure = await self._init(root)
|
||||
if failure:
|
||||
return failure
|
||||
code, output = await self._run(
|
||||
[self.binary, "providers", "schema", "-json"], root
|
||||
)
|
||||
if code != 0:
|
||||
return ToolResult(
|
||||
_clip(f"terraform providers schema failed:\n{output}")
|
||||
)
|
||||
try:
|
||||
data = json.loads(output)
|
||||
except ValueError:
|
||||
return ToolResult("terraform providers schema returned no JSON.")
|
||||
labels = {pin["source"]: pin["version"] for pin in self.providers.values()}
|
||||
schemas: dict[str, tuple[str, dict[str, Any]]] = {}
|
||||
for address, provider in (data.get("provider_schemas") or {}).items():
|
||||
source = address.split("/", 1)[-1] # drop the registry host
|
||||
label = f"{source} {labels.get(source, '')}".strip()
|
||||
for name, resource in (provider.get("resource_schemas") or {}).items():
|
||||
schemas[name] = (label, resource.get("block") or {})
|
||||
self._schemas = schemas
|
||||
return schemas
|
||||
|
||||
async def _init(self, root: Path) -> ToolResult | None:
|
||||
command = [self.binary, "init", "-backend=false", "-input=false", "-no-color"]
|
||||
if self.plugin_cache_dir:
|
||||
async with self._init_lock:
|
||||
code, output = await self._run(command, root)
|
||||
else:
|
||||
code, output = await self._run(command, root)
|
||||
if code != 0:
|
||||
return ToolResult(_clip(f"terraform init failed:\n{output}"))
|
||||
return None
|
||||
|
||||
async def _run(
|
||||
self, args: list[str], cwd: Path, env: Mapping[str, str] | None = None
|
||||
) -> tuple[int, str]:
|
||||
environment = {**os.environ, "TF_IN_AUTOMATION": "1", **(env or {})}
|
||||
if self.plugin_cache_dir:
|
||||
cache = Path(self.plugin_cache_dir).expanduser().resolve()
|
||||
cache.mkdir(parents=True, exist_ok=True)
|
||||
environment["TF_PLUGIN_CACHE_DIR"] = str(cache)
|
||||
# Each check runs in a scratch directory with no dependency lock file.
|
||||
# Without this, Terraform downloads a cached provider again to verify it.
|
||||
environment["TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE"] = "true"
|
||||
try:
|
||||
process = await asyncio.create_subprocess_exec(
|
||||
*args,
|
||||
cwd=cwd,
|
||||
env=environment,
|
||||
stdout=asyncio.subprocess.PIPE,
|
||||
stderr=asyncio.subprocess.STDOUT,
|
||||
)
|
||||
except FileNotFoundError:
|
||||
return 127, f"{self.binary} is not installed or not on PATH."
|
||||
try:
|
||||
stdout, _ = await asyncio.wait_for(
|
||||
process.communicate(), timeout=self.timeout_seconds
|
||||
)
|
||||
except TimeoutError:
|
||||
process.kill()
|
||||
await process.wait()
|
||||
return 124, f"{' '.join(args[:2])} timed out after {self.timeout_seconds}s."
|
||||
return process.returncode or 0, stdout.decode(errors="replace")
|
||||
|
||||
|
||||
_BLOCK_TYPE = re.compile(
|
||||
r'^\s*(?:resource|data)\s+"([a-z0-9]+)_[a-z0-9_]*"', re.MULTILINE
|
||||
)
|
||||
_PROVIDER_SOURCE = re.compile(r'^\s*source\s*=\s*"([\w.-]+/[\w.-]+)"\s*$', re.MULTILINE)
|
||||
# Built into Terraform itself: terraform_data and the terraform_remote_state source.
|
||||
_BUILT_IN = frozenset({"terraform"})
|
||||
|
||||
|
||||
def check_providers(
|
||||
files: Mapping[str, str], pinned: Mapping[str, Mapping[str, str]]
|
||||
) -> ToolResult | None:
|
||||
"""Refuse code that uses a provider the bundle does not pin.
|
||||
|
||||
`terraform init` downloads whatever provider the code names, at whatever
|
||||
version is current. A design with a source repository in it brought the GitHub
|
||||
provider into generated code that way on 2026-10-11. With nothing pinned there
|
||||
is nothing to hold code to, and it passes.
|
||||
"""
|
||||
if not pinned:
|
||||
return None
|
||||
names = set(pinned) | _BUILT_IN
|
||||
sources = {pin["source"] for pin in pinned.values()}
|
||||
code = "\n".join(text for name, text in files.items() if name.endswith(".tf"))
|
||||
foreign = sorted({m.group(1) for m in _BLOCK_TYPE.finditer(code)} - names)
|
||||
undeclared = sorted({m.group(1) for m in _PROVIDER_SOURCE.finditer(code)} - sources)
|
||||
if not foreign and not undeclared:
|
||||
return None
|
||||
found = [f"resources of the {name} provider" for name in foreign]
|
||||
found += [f"the provider {source}" for source in undeclared]
|
||||
return ToolResult(
|
||||
"Refused: the code uses "
|
||||
+ ", ".join(found)
|
||||
+ ". Only these providers may be used: "
|
||||
+ ", ".join(sorted(sources))
|
||||
+ ". Write resources of those alone, and describe anything outside them in "
|
||||
"the deployment guidance as a step the user takes."
|
||||
)
|
||||
|
||||
|
||||
def _check_files(files: Mapping[str, str]) -> ToolResult | None:
|
||||
if not files:
|
||||
return ToolResult("Refused: provide at least one Terraform file.")
|
||||
bad = []
|
||||
for name in files:
|
||||
path = PurePosixPath(name)
|
||||
if (
|
||||
path.is_absolute()
|
||||
or ".." in path.parts
|
||||
or not name.endswith(_TERRAFORM_SUFFIXES)
|
||||
):
|
||||
bad.append(name)
|
||||
if bad:
|
||||
return ToolResult(
|
||||
"Refused: file names must be relative .tf, .tf.json or .tfvars paths "
|
||||
f"without '..': {', '.join(bad)}"
|
||||
)
|
||||
directories = {str(PurePosixPath(name).parent) for name in files}
|
||||
if len(directories) > 1:
|
||||
return ToolResult(
|
||||
"Refused: put all files in one directory (one root module), for example "
|
||||
f"terraform/main.tf and terraform/variables.tf; got {', '.join(sorted(directories))}"
|
||||
)
|
||||
return None
|
||||
|
||||
|
||||
def _module_dir(files: Mapping[str, str]) -> str:
|
||||
"""The one directory holding the files; Terraform runs there."""
|
||||
return str(PurePosixPath(next(iter(files))).parent)
|
||||
|
||||
|
||||
def _write(root: Path, files: Mapping[str, str]) -> Path:
|
||||
for name, content in files.items():
|
||||
target = root / name
|
||||
target.parent.mkdir(parents=True, exist_ok=True)
|
||||
target.write_text(content, encoding="utf-8")
|
||||
return root
|
||||
|
||||
|
||||
def _clip(text: str) -> str:
|
||||
return text if len(text) <= _MAX_OUTPUT else text[:_MAX_OUTPUT] + "\n[truncated]"
|
||||
|
||||
|
||||
def _type(value: Any) -> str:
|
||||
if isinstance(value, str):
|
||||
return value
|
||||
if isinstance(value, list) and len(value) == 2 and value[0] != "object":
|
||||
return f"{value[0]} of {_type(value[1])}"
|
||||
return "object"
|
||||
|
||||
|
||||
def _use(attribute: Mapping[str, Any]) -> str:
|
||||
if attribute.get("required"):
|
||||
return "required"
|
||||
return "optional" if attribute.get("optional") else "read-only"
|
||||
|
||||
|
||||
def _arguments(node: Mapping[str, Any]) -> dict[str, Mapping[str, Any]]:
|
||||
"""The arguments code may set: everything but the read-only ones."""
|
||||
return {
|
||||
name: attribute
|
||||
for name, attribute in sorted((node.get("attributes") or {}).items())
|
||||
if _use(attribute) != "read-only"
|
||||
}
|
||||
|
||||
|
||||
def _block_note(nested: Mapping[str, Any]) -> str:
|
||||
notes = [str(nested.get("nesting_mode", "block"))]
|
||||
if nested.get("min_items"):
|
||||
notes.append(f"at least {nested['min_items']}")
|
||||
if nested.get("max_items"):
|
||||
notes.append(f"at most {nested['max_items']}")
|
||||
return ", ".join(notes)
|
||||
|
||||
|
||||
def _render_schema(heading: str, node: Mapping[str, Any]) -> str:
|
||||
"""One level in full, and the blocks beneath it as an outline of names."""
|
||||
lines = [heading, "", "Arguments:"]
|
||||
arguments = _arguments(node)
|
||||
for name, attribute in arguments.items():
|
||||
described = " ".join(str(attribute.get("description") or "").split())[:160]
|
||||
deprecated = " DEPRECATED" if attribute.get("deprecated") else ""
|
||||
lines.append(
|
||||
f" {name} ({_type(attribute.get('type'))}, {_use(attribute)})"
|
||||
f"{deprecated}" + (f": {described}" if described else "")
|
||||
)
|
||||
if not arguments:
|
||||
lines.append(" none")
|
||||
|
||||
def outline(parent: Mapping[str, Any], depth: int) -> None:
|
||||
for name, nested in sorted((parent.get("block_types") or {}).items()):
|
||||
inner = nested.get("block") or {}
|
||||
names = ", ".join(
|
||||
f"{argument}*" if attribute.get("required") else argument
|
||||
for argument, attribute in _arguments(inner).items()
|
||||
)
|
||||
lines.append(
|
||||
f"{' ' * depth}{name} {{ }} ({_block_note(nested)}): {names or '-'}"
|
||||
)
|
||||
outline(inner, depth + 1)
|
||||
|
||||
lines += ["", "Blocks (* marks a required argument):"]
|
||||
before = len(lines)
|
||||
outline(node, 1)
|
||||
if len(lines) == before:
|
||||
lines.append(" none")
|
||||
lines += ["", "Pass `block`, such as a.b, for one block's arguments in full."]
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def _outline_only(resource_type: str, root: Mapping[str, Any]) -> str:
|
||||
"""One resource type as names alone: its arguments on a line, then every block
|
||||
with its arguments. Enough to see whether a setting exists and where."""
|
||||
lines = [resource_type, " " + (_names_line(root) or "-")]
|
||||
|
||||
def outline(parent: Mapping[str, Any], depth: int) -> None:
|
||||
for name, nested in sorted((parent.get("block_types") or {}).items()):
|
||||
inner = nested.get("block") or {}
|
||||
lines.append(f"{' ' * depth}{name} {{ }}: {_names_line(inner) or '-'}")
|
||||
outline(inner, depth + 1)
|
||||
|
||||
outline(root, 1)
|
||||
text = "\n".join(lines)
|
||||
if len(text) > _MAX_OUTLINE:
|
||||
text = text[:_MAX_OUTLINE] + "\n [cut short: look this type up alone]"
|
||||
return text
|
||||
|
||||
|
||||
def _names_line(node: Mapping[str, Any]) -> str:
|
||||
return ", ".join(
|
||||
f"{name}*" if attribute.get("required") else name
|
||||
for name, attribute in _arguments(node).items()
|
||||
)
|
||||
|
||||
|
||||
def _find_in_schema(title: str, root: Mapping[str, Any], wanted: str) -> str:
|
||||
"""Every argument or block whose name contains `wanted`, with where it sits."""
|
||||
needle = wanted.lower()
|
||||
found: list[str] = []
|
||||
|
||||
def search(node: Mapping[str, Any], path: str) -> None:
|
||||
for name, attribute in sorted((node.get("attributes") or {}).items()):
|
||||
if needle in name.lower():
|
||||
where = f"{path}.{name}" if path else name
|
||||
found.append(
|
||||
f" {where} ({_type(attribute.get('type'))}, {_use(attribute)})"
|
||||
)
|
||||
for name, nested in sorted((node.get("block_types") or {}).items()):
|
||||
where = f"{path}.{name}" if path else name
|
||||
if needle in name.lower():
|
||||
found.append(f" {where} {{ }} ({_block_note(nested)})")
|
||||
search(nested.get("block") or {}, where)
|
||||
|
||||
search(root, "")
|
||||
if not found:
|
||||
return (
|
||||
f"{title} has no argument or block named like {wanted!r}. It cannot be "
|
||||
"set on this resource type."
|
||||
)
|
||||
return f"{title}: {wanted!r} is found at\n" + "\n".join(found)
|
||||
|
||||
|
||||
_FILES_SCHEMA: dict[str, Any] = {
|
||||
**FILES_SCHEMA,
|
||||
"description": "Terraform files in one directory, e.g. terraform/main.tf",
|
||||
}
|
||||
|
||||
|
||||
def _with_files(
|
||||
method: Callable[..., Awaitable[ToolResult]],
|
||||
working_copy: MutableMapping[str, str] | None = None,
|
||||
) -> Callable[..., Awaitable[ToolResult]]:
|
||||
"""Adapt a runner method to take the FILES_SCHEMA argument.
|
||||
|
||||
With a working copy, the files are the Terraform files in it and the argument is
|
||||
optional: files passed anyway are written to the working copy first.
|
||||
"""
|
||||
|
||||
async def handler(files: Any = None, **kwargs: Any) -> ToolResult:
|
||||
try:
|
||||
converted = files_from_argument(files)
|
||||
except TypeError as exc:
|
||||
return ToolResult(f"Refused: files: {exc}")
|
||||
if working_copy is None:
|
||||
return await method(converted, **kwargs)
|
||||
working_copy.update(converted)
|
||||
return await method(_terraform_files(working_copy), **kwargs)
|
||||
|
||||
return handler
|
||||
|
||||
|
||||
def _terraform_files(files: Mapping[str, str]) -> dict[str, str]:
|
||||
return {
|
||||
name: content
|
||||
for name, content in files.items()
|
||||
if name.endswith(_TERRAFORM_SUFFIXES)
|
||||
}
|
||||
|
||||
|
||||
def _fmt_in_place(
|
||||
runner: TerraformRunner, working_copy: MutableMapping[str, str]
|
||||
) -> Callable[..., Awaitable[ToolResult]]:
|
||||
async def format_working_copy(files: Mapping[str, str]) -> ToolResult:
|
||||
changed = await runner.formatted(files)
|
||||
if isinstance(changed, ToolResult):
|
||||
return changed
|
||||
working_copy.update(changed)
|
||||
if not changed:
|
||||
return ToolResult("terraform fmt: all files are already formatted.")
|
||||
return ToolResult(
|
||||
f"terraform fmt reformatted {len(changed)} file(s) in your working "
|
||||
f"copy: {', '.join(sorted(changed))}."
|
||||
)
|
||||
|
||||
return _with_files(format_working_copy, working_copy)
|
||||
|
||||
|
||||
LOCAL_TOOLS: dict[str, tuple[str, str]] = {
|
||||
"mermaid_check": ("general", "Check a Mermaid diagram's basic structure."),
|
||||
"terraform_fmt": ("general", "Format Terraform files and return any that changed."),
|
||||
"terraform_validate": (
|
||||
"general",
|
||||
"Validate Terraform files offline (init -backend=false, validate).",
|
||||
),
|
||||
"terraform_plan": (
|
||||
"cloud_read",
|
||||
"Preview Terraform against the live cloud environment with a plan. Never applies.",
|
||||
),
|
||||
"terraform_module": (
|
||||
"general",
|
||||
(
|
||||
"Look up a published Terraform module: its inputs, outputs and "
|
||||
"submodules, and whether it works with the pinned provider. Give "
|
||||
"`source` as <namespace>/<name>/<provider>, with //modules/<name> for "
|
||||
"a submodule. `version` is optional and defaults to the latest. `find` "
|
||||
"narrows the inputs to those matching the words given."
|
||||
),
|
||||
),
|
||||
"terraform_schema": (
|
||||
"general",
|
||||
(
|
||||
"Look up what a Terraform resource type accepts, from the provider's own "
|
||||
"schema. With `resource_types`, a list: an outline of every argument "
|
||||
"and block each one accepts, in one call. With `resource_type` alone: "
|
||||
"the same for one type, with descriptions. `block` gives one block in "
|
||||
"full. `find` says where named settings sit, or that the resource type "
|
||||
"has none."
|
||||
),
|
||||
),
|
||||
}
|
||||
|
||||
_ON_WORKING_COPY = " Runs on your working copy; pass no files."
|
||||
|
||||
|
||||
def local_tools(
|
||||
names: Iterable[str],
|
||||
runner: TerraformRunner,
|
||||
working_copy: MutableMapping[str, str] | None = None,
|
||||
) -> list[ToolSpec]:
|
||||
"""The named tools. With a `working_copy`, the Terraform checks run on it."""
|
||||
files_required = [] if working_copy is not None else ["files"]
|
||||
suffix = _ON_WORKING_COPY if working_copy is not None else ""
|
||||
|
||||
def checks(name: str, method: Callable[..., Awaitable[ToolResult]]) -> ToolSpec:
|
||||
properties: dict[str, Any] = {"files": _FILES_SCHEMA}
|
||||
if name == "terraform_plan":
|
||||
properties["variables"] = {
|
||||
"type": "object",
|
||||
"additionalProperties": {"type": "string"},
|
||||
}
|
||||
tier, description = LOCAL_TOOLS[name]
|
||||
return ToolSpec(
|
||||
name,
|
||||
description + suffix,
|
||||
{
|
||||
"type": "object",
|
||||
"properties": properties,
|
||||
"required": files_required,
|
||||
},
|
||||
method,
|
||||
tier=tier,
|
||||
)
|
||||
|
||||
builders = {
|
||||
"mermaid_check": lambda: ToolSpec(
|
||||
"mermaid_check",
|
||||
LOCAL_TOOLS["mermaid_check"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {"diagram": {"type": "string"}},
|
||||
"required": ["diagram"],
|
||||
},
|
||||
mermaid_check,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_fmt": lambda: checks(
|
||||
"terraform_fmt",
|
||||
_fmt_in_place(runner, working_copy)
|
||||
if working_copy is not None
|
||||
else _with_files(runner.fmt),
|
||||
),
|
||||
"terraform_validate": lambda: checks(
|
||||
"terraform_validate", _with_files(runner.validate, working_copy)
|
||||
),
|
||||
"terraform_plan": lambda: checks(
|
||||
"terraform_plan", _with_files(runner.plan, working_copy)
|
||||
),
|
||||
"terraform_module": lambda: ToolSpec(
|
||||
"terraform_module",
|
||||
LOCAL_TOOLS["terraform_module"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"source": {
|
||||
"type": "string",
|
||||
"description": (
|
||||
"For example terraform-google-modules/network/google"
|
||||
),
|
||||
},
|
||||
"version": {"type": "string", "description": "Such as 18.3.1"},
|
||||
"find": {
|
||||
"type": "string",
|
||||
"description": "Words to look for in input names, comma-separated",
|
||||
},
|
||||
},
|
||||
"required": ["source"],
|
||||
},
|
||||
ModuleLookup(
|
||||
namespaces=runner.module_namespaces,
|
||||
pinned={name: pin["version"] for name, pin in runner.providers.items()},
|
||||
).describe,
|
||||
tier="general",
|
||||
),
|
||||
"terraform_schema": lambda: ToolSpec(
|
||||
"terraform_schema",
|
||||
LOCAL_TOOLS["terraform_schema"][1],
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"resource_type": {
|
||||
"type": "string",
|
||||
"description": "For example google_cloud_run_v2_service",
|
||||
},
|
||||
"resource_types": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"description": (
|
||||
"Several resource types in one call: each comes back "
|
||||
"as an outline of every argument and block it accepts"
|
||||
),
|
||||
},
|
||||
"block": {
|
||||
"type": "string",
|
||||
"description": "A nested block, such as template.containers",
|
||||
},
|
||||
"find": {
|
||||
"type": "string",
|
||||
"description": (
|
||||
"Argument or block names to look for; separate several "
|
||||
"with commas to check them in one call"
|
||||
),
|
||||
},
|
||||
},
|
||||
"required": [],
|
||||
},
|
||||
runner.schema,
|
||||
tier="general",
|
||||
),
|
||||
}
|
||||
return [builders[name]() for name in names]
|
||||
112
app/solution_architecture/meaning.py
Normal file
112
app/solution_architecture/meaning.py
Normal file
@@ -0,0 +1,112 @@
|
||||
"""Changed, or only reworded? (ADR-0007, iteration 5 step 15)
|
||||
|
||||
A Specialist revising from a Baseline rewords things it was not asked to change.
|
||||
Compared as text, every rewording is a change; ignoring text would miss a dropped
|
||||
restriction, such as "only" removed from a Check. For each item whose text differs
|
||||
from the Baseline's, this asks the decider whether the new text changes what must be
|
||||
true. An item it is confident did not is listed as reworded, not changed.
|
||||
|
||||
Without a decision an item stays changed: that is the safe reading.
|
||||
|
||||
Measured against live Jev on 2026-10-09 with nine pairs: three rewordings scored 0.10
|
||||
to 0.22 and a renamed Element 0.30; five real changes scored 0.41 (a Check moved to
|
||||
another Element), 0.61 (a dropped "only"), and 0.90 to 0.96. At 0.25 no real change
|
||||
was read as a rewording.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import copy
|
||||
import json
|
||||
import logging
|
||||
from collections.abc import Mapping
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import Decider, Question
|
||||
|
||||
from app.solution_architecture.chain import RECOMMENDATIONS_FILE
|
||||
from app.solution_architecture.changes import CHANGED, _graph, _items
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
REWORDED = "reworded"
|
||||
_TEXT_OF = {
|
||||
"checks": ("statement", "applies_to", "source"),
|
||||
"elements": ("name", "product", "resource_type", "component"),
|
||||
"relationships": ("from", "kind", "to"),
|
||||
"recommendations": ("text", "components"),
|
||||
}
|
||||
|
||||
|
||||
def _described(item: Mapping[str, Any], part: str) -> str:
|
||||
return json.dumps(
|
||||
{name: item.get(name) for name in _TEXT_OF[part] if item.get(name) is not None},
|
||||
ensure_ascii=False,
|
||||
)
|
||||
|
||||
|
||||
def _by_id(deliverables: Mapping[str, Any] | None, part: str) -> dict[str, dict]:
|
||||
items = (
|
||||
_items(deliverables, "design_recommendations", RECOMMENDATIONS_FILE)
|
||||
if part == "recommendations"
|
||||
else _graph(deliverables)[part]
|
||||
)
|
||||
return {str(item.get("id")): item for item in items}
|
||||
|
||||
|
||||
async def settle_meaning(
|
||||
decider: Decider,
|
||||
summary: Mapping[str, Any],
|
||||
baseline: Mapping[str, Any] | None,
|
||||
current: Mapping[str, Any] | None,
|
||||
*,
|
||||
unchanged_at: float = 0.25,
|
||||
scope: str = "",
|
||||
) -> dict[str, Any]:
|
||||
"""The change summary with items that were only reworded listed as such.
|
||||
|
||||
An item moves from `changed` to `reworded` when the probability that its new
|
||||
text changes what must be true is at or below `unchanged_at`. Each decision is
|
||||
recorded under `meaning`, by id.
|
||||
"""
|
||||
settled = copy.deepcopy(dict(summary))
|
||||
questions: dict[str, Question] = {}
|
||||
where: dict[str, str] = {}
|
||||
for part in _TEXT_OF:
|
||||
old, new = _by_id(baseline, part), _by_id(current, part)
|
||||
for identifier in settled.get(part, {}).get(CHANGED, []):
|
||||
if identifier not in old or identifier not in new:
|
||||
continue
|
||||
questions[identifier] = Question(
|
||||
"noul",
|
||||
f"Before: {_described(old[identifier], part)}\n"
|
||||
f"After: {_described(new[identifier], part)}\n"
|
||||
"Does the new text change what must be true of the system, as "
|
||||
"opposed to saying the same thing in other words?",
|
||||
)
|
||||
where[identifier] = part
|
||||
if not questions:
|
||||
return settled
|
||||
answers = await decider.decide(
|
||||
"Two versions of one item of a cloud solution architecture.",
|
||||
questions,
|
||||
scope=scope,
|
||||
)
|
||||
if not answers:
|
||||
return settled
|
||||
meaning: dict[str, float] = {}
|
||||
for identifier, part in where.items():
|
||||
answer = answers.get(identifier)
|
||||
if answer is None or not isinstance(answer.value, (int, float)):
|
||||
continue
|
||||
meaning[identifier] = round(float(answer.value), 3)
|
||||
if answer.value <= unchanged_at:
|
||||
settled[part][CHANGED].remove(identifier)
|
||||
settled[part].setdefault(REWORDED, []).append(identifier)
|
||||
unrequested = settled.get("unrequested", {}).get(part)
|
||||
if unrequested and identifier in unrequested:
|
||||
unrequested.remove(identifier)
|
||||
if not unrequested:
|
||||
del settled["unrequested"][part]
|
||||
settled["meaning"] = meaning
|
||||
return settled
|
||||
299
app/solution_architecture/modules.py
Normal file
299
app/solution_architecture/modules.py
Normal file
@@ -0,0 +1,299 @@
|
||||
"""Terraform modules from a public registry (iteration 8).
|
||||
|
||||
Generated code may call a published module where one replaces several resources that
|
||||
must be wired together. Two things keep that safe and checkable, and neither names a
|
||||
Cloud provider: the provider bundle does.
|
||||
|
||||
- **Which modules.** `terraform init` downloads whatever a `source` names and
|
||||
Terraform then evaluates it. So a module is accepted only from a registry
|
||||
namespace the bundle lists, at one exact version. Anything else, a Git URL, a
|
||||
local path or a version range, is refused before Terraform runs.
|
||||
- **What a module accepts.** A module hides the resources a Check is about. The
|
||||
lookup returns a module's inputs, outputs and submodules from the registry, and
|
||||
says whether its provider requirements admit the version the bundle pins.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import contextvars
|
||||
import json
|
||||
import logging
|
||||
import re
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
import httpx
|
||||
from execution_engine.adk.runtime import ToolResult
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
REGISTRY = "https://registry.terraform.io/v1/modules"
|
||||
MODULE_TOOL = "terraform_module"
|
||||
# Whether the Execution a Specialist is running in opted into modules. Set when a
|
||||
# Specialist starts. Unset, outside an Execution, the runner's own list applies.
|
||||
MODULES_OPTED_IN: contextvars.ContextVar[bool | None] = contextvars.ContextVar(
|
||||
"terraform_modules_opted_in", default=None
|
||||
)
|
||||
NOT_OPTED_IN = (
|
||||
"Refused: this Execution writes plain resources. Published modules are used "
|
||||
"only when the Execution opts into them. Write the resources directly."
|
||||
)
|
||||
|
||||
|
||||
def allowed_namespaces(configured: Sequence[str]) -> tuple[str, ...]:
|
||||
"""The namespaces a module may come from, here and now: none when the Execution
|
||||
did not opt in."""
|
||||
return () if MODULES_OPTED_IN.get() is False else tuple(configured)
|
||||
|
||||
|
||||
_MODULE = re.compile(r'^\s*module\s+"([^"]+)"\s*\{', re.MULTILINE)
|
||||
_SOURCE = re.compile(r'^\s*source\s*=\s*"([^"]*)"', re.MULTILINE)
|
||||
_VERSION = re.compile(r'^\s*version\s*=\s*"([^"]*)"', re.MULTILINE)
|
||||
_EXACT = re.compile(r"^\d+\.\d+\.\d+$")
|
||||
# namespace/name/provider, with an optional //path/to/submodule
|
||||
_REGISTRY_SOURCE = re.compile(
|
||||
r"^([A-Za-z0-9_-]+)/([A-Za-z0-9_-]+)/([a-z0-9]+)(?://([\w./-]+))?$"
|
||||
)
|
||||
_MAX_INPUTS = 80
|
||||
_DESCRIPTION = 140
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ModuleCall:
|
||||
name: str
|
||||
source: str
|
||||
version: str
|
||||
|
||||
|
||||
def module_calls(files: Mapping[str, str]) -> list[ModuleCall]:
|
||||
"""Every `module` block in the files, with the source and version it names."""
|
||||
calls = []
|
||||
for text in files.values():
|
||||
for match in _MODULE.finditer(text):
|
||||
body = _block(text, match.end())
|
||||
source = _SOURCE.search(body)
|
||||
version = _VERSION.search(body)
|
||||
calls.append(
|
||||
ModuleCall(
|
||||
match.group(1),
|
||||
source.group(1) if source else "",
|
||||
version.group(1) if version else "",
|
||||
)
|
||||
)
|
||||
return calls
|
||||
|
||||
|
||||
def _block(text: str, start: int) -> str:
|
||||
"""The text of a block whose opening brace ends at `start`, nested blocks
|
||||
removed, so only its own arguments are read."""
|
||||
depth, own, index = 1, [], start
|
||||
while index < len(text) and depth:
|
||||
char = text[index]
|
||||
if char == "{":
|
||||
depth += 1
|
||||
elif char == "}":
|
||||
depth -= 1
|
||||
elif depth == 1:
|
||||
own.append(char)
|
||||
index += 1
|
||||
return "".join(own)
|
||||
|
||||
|
||||
def check_module_sources(
|
||||
files: Mapping[str, str], namespaces: Sequence[str]
|
||||
) -> ToolResult | None:
|
||||
"""Refuse a module that is not from an allowed registry namespace at one exact
|
||||
version. None when every module call is acceptable, or there are none."""
|
||||
if any(
|
||||
name.endswith(".tf.json") and '"module"' in text for name, text in files.items()
|
||||
):
|
||||
return ToolResult("Refused: write module calls in .tf files, not .tf.json.")
|
||||
calls = module_calls(files)
|
||||
if calls and MODULES_OPTED_IN.get() is False:
|
||||
return ToolResult(NOT_OPTED_IN)
|
||||
problems = []
|
||||
for call in calls:
|
||||
parsed = _REGISTRY_SOURCE.match(call.source)
|
||||
if not parsed or parsed.group(1) not in namespaces:
|
||||
allowed = ", ".join(namespaces) or "none are configured"
|
||||
problems.append(
|
||||
f'module "{call.name}": source "{call.source}" is not allowed. A '
|
||||
"module comes only from these registry namespaces, as "
|
||||
f"<namespace>/<name>/<provider>: {allowed}"
|
||||
)
|
||||
elif not _EXACT.match(call.version):
|
||||
problems.append(
|
||||
f'module "{call.name}": set `version` to one exact version, such '
|
||||
f'as "1.2.3"; got "{call.version}"'
|
||||
)
|
||||
if problems:
|
||||
return ToolResult("Refused: " + "; ".join(problems) + ".")
|
||||
return None
|
||||
|
||||
|
||||
# --- what a module accepts --------------------------------------------------------------
|
||||
|
||||
|
||||
def admits(constraint: str, version: str) -> bool:
|
||||
"""Whether a Terraform version constraint, such as ">= 6.2, < 8", admits an
|
||||
exact version. An unreadable term is taken to admit it."""
|
||||
wanted = _numbers(version)
|
||||
for term in constraint.split(","):
|
||||
match = re.match(r"^\s*(>=|<=|>|<|=|!=|~>)?\s*v?([\d.]+)", term)
|
||||
if not match:
|
||||
continue
|
||||
operator, bound = match.group(1) or "=", _numbers(match.group(2))
|
||||
if operator == "~>":
|
||||
# ~> 3.0 admits 3.x; ~> 3.1.2 admits 3.1.x from 3.1.2.
|
||||
upper = [*bound[:-1]]
|
||||
if upper:
|
||||
upper[-1] += 1
|
||||
ok = wanted >= bound and (not upper or wanted < upper)
|
||||
else:
|
||||
ok = {
|
||||
">=": wanted >= bound,
|
||||
"<=": wanted <= bound,
|
||||
">": wanted > bound,
|
||||
"<": wanted < bound,
|
||||
"=": wanted[: len(bound)] == bound,
|
||||
"!=": wanted[: len(bound)] != bound,
|
||||
}[operator]
|
||||
if not ok:
|
||||
return False
|
||||
return True
|
||||
|
||||
|
||||
def _numbers(version: str) -> list[int]:
|
||||
return [int(part) for part in version.split(".") if part.isdigit()]
|
||||
|
||||
|
||||
@dataclass
|
||||
class ModuleLookup:
|
||||
"""Reads a module's inputs and outputs from the registry."""
|
||||
|
||||
namespaces: tuple[str, ...] = ()
|
||||
# The provider versions generated code is pinned to: {local name: version}.
|
||||
pinned: Mapping[str, str] = field(default_factory=dict)
|
||||
timeout_seconds: float = 20
|
||||
_cache: dict[str, dict[str, Any]] = field(default_factory=dict, repr=False)
|
||||
|
||||
async def describe(
|
||||
self, source: str = "", version: str = "", find: str = ""
|
||||
) -> ToolResult:
|
||||
parsed = _REGISTRY_SOURCE.match(source.strip())
|
||||
if not parsed or parsed.group(1) not in self.namespaces:
|
||||
allowed = ", ".join(self.namespaces) or "none are configured"
|
||||
return ToolResult(
|
||||
f'Refused: "{source}" is not a module from an allowed registry '
|
||||
f"namespace. Give <namespace>/<name>/<provider>, optionally with "
|
||||
f"//modules/<submodule>. Allowed namespaces: {allowed}."
|
||||
)
|
||||
namespace, name, provider, path = parsed.groups()
|
||||
if version and not _EXACT.match(version):
|
||||
return ToolResult(
|
||||
'Refused: `version` is one exact version, such as "1.2.3".'
|
||||
)
|
||||
data = await self._fetch(f"{namespace}/{name}/{provider}", version)
|
||||
if isinstance(data, ToolResult):
|
||||
return data
|
||||
part = data.get("root") or {}
|
||||
if path:
|
||||
wanted = path.strip("/")
|
||||
part = next(
|
||||
(
|
||||
item
|
||||
for item in data.get("submodules") or []
|
||||
if item.get("path", "").strip("/") == wanted
|
||||
),
|
||||
None,
|
||||
)
|
||||
if part is None:
|
||||
listed = ", ".join(
|
||||
item.get("path", "") for item in data.get("submodules") or []
|
||||
)
|
||||
return ToolResult(
|
||||
f"{namespace}/{name}/{provider} {data.get('version')} has no "
|
||||
f"submodule at {path}. Its submodules: {listed or 'none'}."
|
||||
)
|
||||
return ToolResult(self._render(data, part, source, find))
|
||||
|
||||
async def _fetch(self, module: str, version: str) -> dict[str, Any] | ToolResult:
|
||||
key = f"{module}/{version}" if version else module
|
||||
if key in self._cache:
|
||||
return self._cache[key]
|
||||
try:
|
||||
async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
|
||||
response = await client.get(f"{REGISTRY}/{key}")
|
||||
except httpx.HTTPError as exc:
|
||||
return ToolResult(
|
||||
f"The module registry could not be reached ({type(exc).__name__}). "
|
||||
"Write the resources directly, from the patterns and the schema."
|
||||
)
|
||||
if response.status_code == 404:
|
||||
return ToolResult(f"The registry has no module {module} {version}.".strip())
|
||||
if response.status_code != 200:
|
||||
return ToolResult(
|
||||
f"The module registry answered {response.status_code} for {module}."
|
||||
)
|
||||
try:
|
||||
data = response.json()
|
||||
except json.JSONDecodeError:
|
||||
return ToolResult(f"The registry's answer for {module} was not readable.")
|
||||
self._cache[key] = data
|
||||
return data
|
||||
|
||||
def _render(
|
||||
self,
|
||||
data: Mapping[str, Any],
|
||||
part: Mapping[str, Any],
|
||||
source: str,
|
||||
find: str,
|
||||
) -> str:
|
||||
version = data.get("version", "")
|
||||
lines = [f'{source} version "{version}"']
|
||||
for dependency in part.get("provider_dependencies") or []:
|
||||
name, constraint = dependency.get("name", ""), dependency.get("version", "")
|
||||
pin = self.pinned.get(name)
|
||||
if pin and constraint and not admits(constraint, pin):
|
||||
lines.append(
|
||||
f"NOT USABLE: it requires {name} {constraint}, and the code is "
|
||||
f"pinned to {name} {pin}. Write the resources directly."
|
||||
)
|
||||
elif not pin and name:
|
||||
lines.append(
|
||||
f"It also uses the {name} provider ({constraint or 'any version'});"
|
||||
" Terraform installs it."
|
||||
)
|
||||
inputs = sorted(
|
||||
part.get("inputs") or [],
|
||||
key=lambda item: (not item.get("required"), item.get("name", "")),
|
||||
)
|
||||
if find:
|
||||
wanted = [word.strip().lower() for word in find.split(",") if word.strip()]
|
||||
inputs = [
|
||||
item
|
||||
for item in inputs
|
||||
if any(
|
||||
word
|
||||
in f"{item.get('name', '')} {item.get('description', '')}".lower()
|
||||
for word in wanted
|
||||
)
|
||||
]
|
||||
lines.append(f"Inputs matching {find}: {len(inputs) or 'none'}")
|
||||
else:
|
||||
lines.append(f"Inputs ({len(inputs)}; required first):")
|
||||
for item in inputs[:_MAX_INPUTS]:
|
||||
need = "required" if item.get("required") else "optional"
|
||||
kind = " ".join(str(item.get("type", "")).split())[:60]
|
||||
about = " ".join(str(item.get("description", "")).split())[:_DESCRIPTION]
|
||||
lines.append(f"- {item.get('name')} ({need}, {kind}): {about}")
|
||||
if len(inputs) > _MAX_INPUTS:
|
||||
lines.append(f"[{len(inputs) - _MAX_INPUTS} more; use `find`]")
|
||||
outputs = [item.get("name", "") for item in part.get("outputs") or []]
|
||||
if outputs and not find:
|
||||
lines.append("Outputs: " + ", ".join(outputs))
|
||||
submodules = [item.get("path", "") for item in data.get("submodules") or []]
|
||||
if submodules and not find:
|
||||
lines.append("Submodules: " + ", ".join(submodules))
|
||||
return "\n".join(lines)
|
||||
374
app/solution_architecture/pillars.py
Normal file
374
app/solution_architecture/pillars.py
Normal file
@@ -0,0 +1,374 @@
|
||||
"""The design advisor's fan-out to one advisor per architecture-framework pillar.
|
||||
|
||||
Pillar advice is working material for the design recommendations Deliverable, not a
|
||||
Deliverable itself, so it never touches the Ledger. It is kept in that Deliverable's
|
||||
working memory, so a Revision re-consults only the pillars its feedback touches.
|
||||
|
||||
Each advisor also returns its review of the pillar's own checklist: for every item,
|
||||
whether its advice addresses it, or why it does not apply. The reviews are kept
|
||||
beside the advice and written into the Deliverable by code when it is submitted, so
|
||||
an architect sees the whole checklist accounted for and no model spends output
|
||||
copying it.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import dataclasses
|
||||
from collections.abc import Mapping, MutableMapping, Sequence
|
||||
from contextlib import AsyncExitStack
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
Decider,
|
||||
Question,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
|
||||
CONSULT_TOOL = "consult_pillar_advisors"
|
||||
NO_GUIDANCE = "No guidance"
|
||||
ADVICE_KEY = "pillar_advice" # working memory: pillar -> the advice last given
|
||||
CHECKLIST_KEY = "pillar_checklists" # working memory: pillar -> its checklist review
|
||||
REVIEW_HEADING = "Architecture framework checklist review"
|
||||
# What a Change request carries over from its Baseline's working memory.
|
||||
KEPT_FOR_CHANGES = (ADVICE_KEY, CHECKLIST_KEY)
|
||||
_CHANGE_LIMIT = 6_000
|
||||
NEEDS_CUSTOMER = "needs_customer_input"
|
||||
STATUSES = ("addressed", "not_applicable", NEEDS_CUSTOMER, "not_addressed")
|
||||
_STATUS_WORDS = {
|
||||
"addressed": "Addressed",
|
||||
"not_applicable": "Does not apply",
|
||||
# The item applies, and the customer's request does not say what would settle
|
||||
# it. That is missing information, not a fault in the design: it is reported
|
||||
# with the question to put to the customer.
|
||||
NEEDS_CUSTOMER: "To confirm with the customer",
|
||||
"not_addressed": "Not addressed",
|
||||
}
|
||||
QUESTIONS_HEADING = "Questions for the customer"
|
||||
|
||||
|
||||
AFFECTED = ("not at all", "only indirectly", "directly")
|
||||
|
||||
|
||||
async def pillars_touched(
|
||||
decider: Decider,
|
||||
pillars: Sequence[str],
|
||||
change: str,
|
||||
*,
|
||||
threshold: float = 1.5,
|
||||
scope: str = "",
|
||||
) -> list[str] | None:
|
||||
"""The pillars whose recommendations a change affects directly (ADR-0007).
|
||||
|
||||
One graded question per pillar: not at all, only indirectly, directly. A pillar
|
||||
at `threshold` or above, on that scale of 0 to 2, is consulted again. An empty
|
||||
list means the change touches none of them. None means no decision was
|
||||
available, and every pillar is consulted.
|
||||
|
||||
Asked as a yes or no ("does this change call for revisiting ...?") the answer
|
||||
was yes for nearly every pillar of every change; measured on 2026-10-09.
|
||||
"""
|
||||
if not change.strip() or not pillars:
|
||||
return None
|
||||
answers = await decider.decide(
|
||||
f"A change to a cloud solution architecture:\n{change[:_CHANGE_LIMIT]}",
|
||||
{
|
||||
pillar: Question(
|
||||
"score",
|
||||
f"How directly does this change affect the {pillar} "
|
||||
"recommendations for the workload?",
|
||||
AFFECTED,
|
||||
)
|
||||
for pillar in pillars
|
||||
},
|
||||
scope=scope,
|
||||
)
|
||||
if not answers:
|
||||
return None
|
||||
return [
|
||||
pillar
|
||||
for pillar in pillars
|
||||
if (answer := answers.get(pillar)) is not None
|
||||
and isinstance(answer.value, (int, float))
|
||||
and answer.value >= threshold
|
||||
]
|
||||
|
||||
|
||||
def pillar_consultation_tool(
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar_skills: Mapping[str, str],
|
||||
extra_tools: Sequence[ToolSpec] = (),
|
||||
memory: MutableMapping[str, Any] | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
) -> ToolSpec:
|
||||
"""A tool that runs one pillar advisor per pillar, in parallel, each with its Skill.
|
||||
|
||||
With `memory`, advice is remembered: naming `pillars` re-consults only those and
|
||||
returns the remembered advice for the rest.
|
||||
"""
|
||||
|
||||
async def advise(pillar: str, brief: str) -> tuple[str, list[dict[str, str]]]:
|
||||
async with AsyncExitStack() as stack:
|
||||
if limiter:
|
||||
await stack.enter_async_context(limiter.slot())
|
||||
return await _advise(
|
||||
runtime, advisor, pillar, pillar_skills[pillar], brief, extra_tools
|
||||
)
|
||||
|
||||
async def consult(brief: str, pillars: Sequence[str] | None = None) -> ToolResult:
|
||||
# No `pillars` consults them all; an empty list consults none, and returns
|
||||
# what was said before.
|
||||
chosen = list(pillar_skills) if pillars is None else list(pillars)
|
||||
unknown = [pillar for pillar in chosen if pillar not in pillar_skills]
|
||||
if unknown:
|
||||
return ToolResult(
|
||||
f"Refused: unknown pillars {', '.join(unknown)}; "
|
||||
f"choose from {', '.join(pillar_skills)}"
|
||||
)
|
||||
async with AsyncExitStack() as stack:
|
||||
if limiter:
|
||||
# The calling Specialist only waits here, so its slot goes to advisors.
|
||||
await stack.enter_async_context(limiter.lend())
|
||||
fresh = dict(
|
||||
zip(
|
||||
chosen,
|
||||
await asyncio.gather(*(advise(pillar, brief) for pillar in chosen)),
|
||||
)
|
||||
)
|
||||
remembered: dict[str, str] = (
|
||||
dict(memory.get(ADVICE_KEY, {})) if memory is not None else {}
|
||||
)
|
||||
reviews: dict[str, list[dict[str, str]]] = (
|
||||
dict(memory.get(CHECKLIST_KEY, {})) if memory is not None else {}
|
||||
)
|
||||
sections = []
|
||||
for pillar in pillar_skills:
|
||||
if pillar in fresh:
|
||||
advice, review = fresh[pillar]
|
||||
if not advice.startswith(NO_GUIDANCE):
|
||||
remembered[pillar] = advice
|
||||
reviews[pillar] = review
|
||||
sections.append(f"## {pillar}\n\n{advice}")
|
||||
elif pillar in remembered:
|
||||
sections.append(
|
||||
f"## {pillar} (from your earlier consultation)\n\n"
|
||||
f"{remembered[pillar]}"
|
||||
)
|
||||
if memory is not None:
|
||||
memory[ADVICE_KEY] = remembered
|
||||
memory[CHECKLIST_KEY] = reviews
|
||||
return ToolResult("\n\n".join(sections))
|
||||
|
||||
return ToolSpec(
|
||||
CONSULT_TOOL,
|
||||
"Get guidance from one advisor per architecture-framework pillar, in parallel. "
|
||||
"Give a brief with the workload, its requirements and the selected products. "
|
||||
"Omit `pillars` to consult every pillar afresh. Name `pillars` to re-consult "
|
||||
"only those; advice already given for the others is returned unchanged. An "
|
||||
"empty list consults none and returns the advice already given.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"brief": {"type": "string"},
|
||||
"pillars": {
|
||||
"type": "array",
|
||||
"items": {"type": "string", "enum": list(pillar_skills)},
|
||||
},
|
||||
},
|
||||
"required": ["brief"],
|
||||
},
|
||||
consult,
|
||||
)
|
||||
|
||||
|
||||
async def _advise(
|
||||
runtime: AgentRuntime,
|
||||
advisor: RoleSpec,
|
||||
pillar: str,
|
||||
skill: str,
|
||||
brief: str,
|
||||
extra_tools: Sequence[ToolSpec],
|
||||
) -> tuple[str, list[dict[str, str]]]:
|
||||
"""One advisor's advice, and its review of the pillar's checklist."""
|
||||
role = dataclasses.replace(advisor, skills=(skill,))
|
||||
task = AgentTask(
|
||||
role=advisor.name,
|
||||
prompt=f"Advise on the {pillar} pillar for this workload.",
|
||||
context={"pillar": pillar, "brief": brief},
|
||||
)
|
||||
review: list[dict[str, str]] = []
|
||||
try:
|
||||
outcome = await runtime.run(
|
||||
role, task, [_submit_advice_tool(review), *extra_tools]
|
||||
)
|
||||
except Exception as exc: # noqa: BLE001 - one failed advisor must not lose the others
|
||||
return f"{NO_GUIDANCE}: the advisor failed ({exc}).", []
|
||||
if isinstance(outcome, Submitted):
|
||||
return outcome.content.strip(), review
|
||||
return f"{NO_GUIDANCE}: the advisor ended with {type(outcome).__name__}.", []
|
||||
|
||||
|
||||
def _submit_advice_tool(review: list[dict[str, str]]) -> ToolSpec:
|
||||
"""`review` receives the checklist review the advisor submits with its advice."""
|
||||
|
||||
async def submit_advice(content: str, checklist: Sequence[Any] = ()) -> ToolResult:
|
||||
if not content.strip():
|
||||
return ToolResult("Not submitted: the advice is empty.")
|
||||
entries = [
|
||||
{
|
||||
"item": " ".join(str(entry.get("item", "")).split()),
|
||||
"status": str(entry.get("status", "")),
|
||||
"note": " ".join(str(entry.get("note", "")).split()),
|
||||
"question": " ".join(str(entry.get("question") or "").split()),
|
||||
}
|
||||
for entry in checklist or ()
|
||||
if isinstance(entry, Mapping)
|
||||
and str(entry.get("item", "")).strip()
|
||||
and entry.get("status") in STATUSES
|
||||
]
|
||||
unasked = [
|
||||
entry["item"]
|
||||
for entry in entries
|
||||
if entry["status"] == NEEDS_CUSTOMER and not entry["question"]
|
||||
]
|
||||
if unasked:
|
||||
return ToolResult(
|
||||
"Not submitted: an item to confirm with the customer needs the "
|
||||
"`question` to put to them. Missing for: " + "; ".join(unasked)
|
||||
)
|
||||
review[:] = entries
|
||||
return ToolResult("Advice submitted.", Submitted(content))
|
||||
|
||||
text = {"type": "string"}
|
||||
return ToolSpec(
|
||||
"submit_advice",
|
||||
"Submit your pillar recommendations as markdown, with your review of the "
|
||||
"pillar's checklist. Ends your turn.",
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"content": text,
|
||||
"checklist": {
|
||||
"type": "array",
|
||||
"description": "One entry for every item of the Skill's "
|
||||
"validation checklist.",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"item": text,
|
||||
"status": {"type": "string", "enum": list(STATUSES)},
|
||||
"note": {
|
||||
"type": "string",
|
||||
"description": "How your advice addresses it, why "
|
||||
"it does not apply to this workload, or what the "
|
||||
"request leaves unsaid.",
|
||||
},
|
||||
"question": {
|
||||
"type": "string",
|
||||
"description": "For needs_customer_input only: "
|
||||
"the question to put to the customer, answerable "
|
||||
"by someone who knows their organisation.",
|
||||
},
|
||||
},
|
||||
"required": ["item", "status", "note"],
|
||||
},
|
||||
},
|
||||
},
|
||||
"required": ["content"],
|
||||
},
|
||||
submit_advice,
|
||||
tier="execution",
|
||||
)
|
||||
|
||||
|
||||
def render_checklist_review(working: Mapping[str, Any]) -> str:
|
||||
"""The advisors' checklist reviews as one section of markdown tables, or "" when
|
||||
there are none. Written by code from what the advisors recorded."""
|
||||
reviews = working.get(CHECKLIST_KEY)
|
||||
if not isinstance(reviews, Mapping) or not any(reviews.values()):
|
||||
return ""
|
||||
parts = [
|
||||
f"## {REVIEW_HEADING}",
|
||||
"",
|
||||
(
|
||||
"Each pillar advisor's review of its pillar's checklist for this "
|
||||
"workload: what its advice addresses, what does not apply and why, and "
|
||||
"what the request does not say enough to settle."
|
||||
),
|
||||
]
|
||||
for pillar, entries in reviews.items():
|
||||
if not entries:
|
||||
continue
|
||||
parts += [
|
||||
"",
|
||||
f"### {pillar}",
|
||||
"",
|
||||
"| Checklist item | Review | How, or why not |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
parts += [
|
||||
"| "
|
||||
+ " | ".join(
|
||||
str(value).replace("|", "\\|")
|
||||
for value in (
|
||||
entry.get("item", ""),
|
||||
_STATUS_WORDS.get(str(entry.get("status")), ""),
|
||||
entry.get("note", ""),
|
||||
)
|
||||
)
|
||||
+ " |"
|
||||
for entry in entries
|
||||
if isinstance(entry, Mapping)
|
||||
]
|
||||
questions = customer_questions(working)
|
||||
if questions:
|
||||
parts += [
|
||||
"",
|
||||
f"### {QUESTIONS_HEADING}",
|
||||
"",
|
||||
(
|
||||
"The request does not say enough to settle these. They are not "
|
||||
"faults in the design: each is something to ask the customer, and "
|
||||
"the answer may change a recommendation."
|
||||
),
|
||||
"",
|
||||
"| Pillar | About | Question |",
|
||||
"| --- | --- | --- |",
|
||||
]
|
||||
parts += [
|
||||
"| "
|
||||
+ " | ".join(
|
||||
value.replace("|", "\\|")
|
||||
for value in (item["pillar"], item["item"], item["question"])
|
||||
)
|
||||
+ " |"
|
||||
for item in questions
|
||||
]
|
||||
return "\n".join(parts) + "\n"
|
||||
|
||||
|
||||
def customer_questions(working: Mapping[str, Any]) -> list[dict[str, str]]:
|
||||
"""What the advisors found the request does not say: each checklist item that
|
||||
needs the customer's answer, with the question to put to them."""
|
||||
reviews = working.get(CHECKLIST_KEY)
|
||||
if not isinstance(reviews, Mapping):
|
||||
return []
|
||||
return [
|
||||
{
|
||||
"pillar": str(pillar),
|
||||
"item": str(entry.get("item", "")),
|
||||
"question": str(entry.get("question", "")),
|
||||
}
|
||||
for pillar, entries in reviews.items()
|
||||
for entry in entries or ()
|
||||
if isinstance(entry, Mapping)
|
||||
and entry.get("status") == NEEDS_CUSTOMER
|
||||
and entry.get("question")
|
||||
]
|
||||
173
app/solution_architecture/presentation.py
Normal file
173
app/solution_architecture/presentation.py
Normal file
@@ -0,0 +1,173 @@
|
||||
"""Presenting an Execution to callers: prompt text and the /generate response shape."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import RoleSpec
|
||||
from execution_engine.agent import Interaction
|
||||
from execution_engine.presentation import describe_prompt as _describe_prompt
|
||||
|
||||
|
||||
def describe_prompt(prompt: Mapping[str, Any]) -> str:
|
||||
"""What the user is asked, with what this Workflow's Approvals commit to."""
|
||||
return _describe_prompt(
|
||||
prompt,
|
||||
lambda approval: (
|
||||
_describe_changes(approval)
|
||||
+ _describe_target_architecture(approval.get("target_architecture"))
|
||||
),
|
||||
)
|
||||
|
||||
|
||||
_CHANGE_WORDS = {"added": "Added", "changed": "Changed", "removed": "Removed"}
|
||||
|
||||
|
||||
def _describe_changes(approval: Mapping[str, Any]) -> str:
|
||||
"""In a Change request: what this Phase changes against the Baseline. It comes
|
||||
from the ids in the two versions, not from an agent's account."""
|
||||
if "changes" not in approval:
|
||||
return ""
|
||||
changes = approval["changes"]
|
||||
lines = [f"This changes the architecture delivered in {approval.get('baseline')}."]
|
||||
if not changes:
|
||||
lines.append("Nothing in this Phase differs from it.")
|
||||
for item in changes.get("requirements", []):
|
||||
lines.append(
|
||||
f"- Requirement {item['id']} {item['change']}: {item['text']} "
|
||||
f"({item['reason']})"
|
||||
)
|
||||
for part in (
|
||||
"components",
|
||||
"recommendations",
|
||||
"elements",
|
||||
"relationships",
|
||||
"checks",
|
||||
):
|
||||
for change, word in _CHANGE_WORDS.items():
|
||||
ids = changes.get(part, {}).get(change)
|
||||
if ids:
|
||||
lines.append(f"- {word} {part}: {', '.join(ids)}")
|
||||
for part, ids in changes.get("unrequested", {}).items():
|
||||
lines.append(
|
||||
f"- Changed without being asked for ({part}): {', '.join(ids)}. No "
|
||||
"changed requirement reaches these."
|
||||
)
|
||||
return "\n".join(lines) + "\n\n"
|
||||
|
||||
|
||||
def _describe_target_architecture(summary: Mapping[str, Any] | None) -> str:
|
||||
"""What the design Approval commits to: no code is written until it is granted."""
|
||||
if not summary:
|
||||
return ""
|
||||
text = (
|
||||
f"The Target architecture has {summary['elements']} Elements, "
|
||||
f"{summary['relationships']} Relationships and {summary['checks']} Checks. "
|
||||
"No infrastructure code is written until you approve it; the code is then "
|
||||
"validated against those Checks.\n\n"
|
||||
)
|
||||
for item in summary.get("not_applicable", []):
|
||||
text += (
|
||||
f"Recommendation {item['recommendation']} is treated as not applicable: "
|
||||
f"{item['reason']}\n"
|
||||
)
|
||||
return text + ("\n" if summary.get("not_applicable") else "")
|
||||
|
||||
|
||||
def to_generate_response(
|
||||
interaction: Interaction, roles: Mapping[str, RoleSpec]
|
||||
) -> dict[str, Any]:
|
||||
"""Map an Execution onto the legacy /generate response keys."""
|
||||
from app.solution_architecture.workflow import DeliverableKind
|
||||
|
||||
state = interaction.state
|
||||
deliverables: Mapping[str, Mapping[str, Any]] = state.get("deliverables", {})
|
||||
ledger = state.get("ledger", {})
|
||||
|
||||
def content(kind: str) -> str | None:
|
||||
item = deliverables.get(kind)
|
||||
return item["content"] if item else None
|
||||
|
||||
def attachment(kind: str, name: str) -> str | None:
|
||||
item = deliverables.get(kind)
|
||||
return item.get("attachments", {}).get(name) if item else None
|
||||
|
||||
requirements = content(DeliverableKind.REQUIREMENTS)
|
||||
revisions = sum(
|
||||
d.get("revisions", 0) for d in ledger.get("deliverables", {}).values()
|
||||
)
|
||||
submitted = [kind for kind in DeliverableKind if kind in deliverables]
|
||||
skills = _skills_used(submitted, roles)
|
||||
status = {
|
||||
"completed": "success",
|
||||
"completed_with_warnings": "completed_with_warnings",
|
||||
}.get(interaction.status, interaction.status)
|
||||
|
||||
return {
|
||||
"execution_id": interaction.execution_id,
|
||||
"session_id": state.get("session_id"),
|
||||
"status": status,
|
||||
"validation_passed": interaction.status == "completed",
|
||||
"total_loop_iterations": revisions + 1,
|
||||
"current_phase": _current_phase(ledger),
|
||||
"artifacts": {
|
||||
"source_discovery_doc": _section(requirements, "Current state"),
|
||||
"source_mermaid_diagram": None,
|
||||
"requirements_doc": requirements,
|
||||
"architecture_doc": content(DeliverableKind.ARCHITECTURE_DESCRIPTION),
|
||||
"mermaid_diagram": attachment(
|
||||
DeliverableKind.TARGET_ARCHITECTURE, "architecture.mmd"
|
||||
),
|
||||
"terraform_code": attachment(
|
||||
DeliverableKind.DEPLOYMENT_GUIDANCE, "terraform/main.tf"
|
||||
),
|
||||
"validation_results": content(DeliverableKind.VALIDATION_RESULTS),
|
||||
"solution_guide": content(DeliverableKind.SOLUTION_GUIDE),
|
||||
},
|
||||
"active_skills": skills,
|
||||
"warnings": list(state.get("warnings", [])),
|
||||
}
|
||||
|
||||
|
||||
def _skills_used(submitted: Sequence[str], roles: Mapping[str, RoleSpec]) -> list[str]:
|
||||
from app.solution_architecture.workflow import DEPENDENCY_GRAPH
|
||||
|
||||
names: list[str] = []
|
||||
for kind in submitted:
|
||||
role = roles.get(DEPENDENCY_GRAPH[kind].specialist)
|
||||
for skill in role.skills if role else ():
|
||||
if skill not in names:
|
||||
names.append(skill)
|
||||
return names
|
||||
|
||||
|
||||
def _current_phase(ledger: Mapping[str, Any]) -> str | None:
|
||||
phases: Mapping[str, str] = ledger.get("phases", {})
|
||||
for phase, status in phases.items():
|
||||
if status != "approved":
|
||||
return phase
|
||||
return list(phases)[-1] if phases else None
|
||||
|
||||
|
||||
def _section(markdown: str | None, heading: str) -> str | None:
|
||||
"""The body under a heading (any level, numbering ignored), up to the next heading."""
|
||||
if not markdown:
|
||||
return None
|
||||
lines = markdown.splitlines()
|
||||
pattern = re.compile(
|
||||
rf"^#{{1,6}}\s+(?:\d+(?:\.\d+)*\.?\s+)?{re.escape(heading)}\s*$", re.IGNORECASE
|
||||
)
|
||||
for index, line in enumerate(lines):
|
||||
if pattern.match(line.strip()):
|
||||
level = len(line.strip()) - len(line.strip().lstrip("#"))
|
||||
body = []
|
||||
for following in lines[index + 1 :]:
|
||||
stripped = following.strip()
|
||||
hashes = len(stripped) - len(stripped.lstrip("#"))
|
||||
if stripped.startswith("#") and hashes <= level:
|
||||
break
|
||||
body.append(following)
|
||||
return "\n".join(body).strip() or None
|
||||
return None
|
||||
79
app/solution_architecture/requirements_review.py
Normal file
79
app/solution_architecture/requirements_review.py
Normal file
@@ -0,0 +1,79 @@
|
||||
"""A review of the requirements: they describe the problem, not the solution.
|
||||
|
||||
Requirements discovery is kept apart from solutioning, so a requirement names no
|
||||
product. That rule was an instruction the engine could not enforce; the evaluation
|
||||
checked it only afterwards, against a list of product names. This asks the decider
|
||||
(ADR-0007), once per requirement, whether it names a cloud product or managed
|
||||
service. It never blocks: what it raises is returned to the Specialist once.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import Decider, Question
|
||||
|
||||
from app.solution_architecture.chain import REQUIREMENTS_FILE, read_list
|
||||
from app.solution_architecture.kinds import DeliverableKind
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_TEXT = 200
|
||||
|
||||
|
||||
class RequirementsReview:
|
||||
def __init__(self, decider: Decider, *, act: float = 0.3) -> None:
|
||||
self._decider = decider
|
||||
# Lower than the router's threshold, from measurement on 2026-10-08: across
|
||||
# 61 requirements from three passed runs the highest answer was 0.10, and
|
||||
# requirements written to name a product scored 0.34, 0.61 and 0.93.
|
||||
self._act = act
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: DeliverableKind,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]:
|
||||
"""The requirements that name a product, each as a line for the Specialist."""
|
||||
if kind != DeliverableKind.REQUIREMENTS:
|
||||
return ()
|
||||
items = [
|
||||
item
|
||||
for item in read_list(
|
||||
{"requirements": {"attachments": attachments}},
|
||||
"requirements",
|
||||
REQUIREMENTS_FILE,
|
||||
)
|
||||
if isinstance(item.get("id"), str) and isinstance(item.get("text"), str)
|
||||
]
|
||||
if not items:
|
||||
return ()
|
||||
answers = await self._decider.decide(
|
||||
"Requirements for a workload, written before any product is chosen.",
|
||||
{
|
||||
item["id"]: Question(
|
||||
"noul",
|
||||
f'Requirement: "{item["text"]}". Does it name a specific cloud '
|
||||
"provider's product or managed service, as opposed to "
|
||||
"describing what is needed?",
|
||||
)
|
||||
for item in items
|
||||
},
|
||||
scope=scope,
|
||||
)
|
||||
if not answers:
|
||||
return ()
|
||||
raised = [
|
||||
f'{item["id"]} names a product or service: "{item["text"][:_TEXT]}". '
|
||||
"Say what is needed, not what to use"
|
||||
for item in items
|
||||
if (answer := answers.get(item["id"])) is not None
|
||||
and answer.is_yes(self._act)
|
||||
]
|
||||
if raised:
|
||||
logger.info("[%s] requirements review raised %d", scope, len(raised))
|
||||
return tuple(raised)
|
||||
169
app/solution_architecture/schema_review.py
Normal file
169
app/solution_architecture/schema_review.py
Normal file
@@ -0,0 +1,169 @@
|
||||
"""A review of the Target architecture against the provider's schema, in code.
|
||||
|
||||
A Check that names a setting its Element's resource type does not have cannot be met
|
||||
by any code. Left alone it costs a whole Revision: the code's author finds it, the
|
||||
design is reopened, and everything after it is done again. In the run of 2026-10-07
|
||||
that happened twice, with a schema lookup available to the Specialist that wrote the
|
||||
Checks.
|
||||
|
||||
This reads the settings each Check names and looks them up, so the design is told
|
||||
before it is submitted. It is a review, not a rule: a Check is prose, and a word that
|
||||
looks like a setting may be a value. What it raises is returned once.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import difflib
|
||||
import logging
|
||||
import re
|
||||
from collections.abc import Mapping, Sequence
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import ToolResult
|
||||
|
||||
from app.solution_architecture.kinds import DeliverableKind
|
||||
from app.solution_architecture.local import TerraformRunner
|
||||
from app.solution_architecture.target_architecture import (
|
||||
GRAPH_ATTACHMENT,
|
||||
GraphError,
|
||||
parse_graph,
|
||||
)
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_QUOTED = re.compile(r"\"[^\"]*\"|'[^']*'")
|
||||
_CODE = re.compile(r"`([^`]+)`")
|
||||
# snake_case with at least one underscore, or a dotted path of lower-case names.
|
||||
_NAME = re.compile(
|
||||
r"(?<![\w/.\-])"
|
||||
r"([a-z][a-z0-9]*(?:_[a-z0-9]+)+(?:\.[a-z][a-z0-9_]*)*"
|
||||
r"|[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+)"
|
||||
r"(?![\w/\-])"
|
||||
)
|
||||
_PATH = re.compile(r"^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*$")
|
||||
# Values a Check may put in backticks. `true` and `false` were raised as missing
|
||||
# settings in a run of 2026-10-10.
|
||||
_LITERALS = frozenset({"true", "false", "null", "none"})
|
||||
|
||||
|
||||
def named_settings(statement: str) -> tuple[str, ...]:
|
||||
"""The settings a Check's statement names, as written.
|
||||
|
||||
Anything in backticks that reads as a name or a dotted path, and bare
|
||||
snake_case names and dotted paths. Quoted text is a value, so it is skipped,
|
||||
as are paths such as roles/x.y.
|
||||
"""
|
||||
found: list[str] = []
|
||||
for span in _CODE.findall(statement):
|
||||
candidate = span.strip().split("=")[0].strip()
|
||||
if _PATH.match(candidate) and candidate not in _LITERALS:
|
||||
found.append(candidate)
|
||||
bare = _QUOTED.sub(" ", _CODE.sub(" ", statement))
|
||||
found += [match.group(1).rstrip(".") for match in _NAME.finditer(bare)]
|
||||
return tuple(dict.fromkeys(found))
|
||||
|
||||
|
||||
def _names(block: Mapping[str, Any]) -> set[str]:
|
||||
"""Every argument and block name anywhere in a resource type's schema."""
|
||||
names = set(block.get("attributes") or {})
|
||||
for name, nested in (block.get("block_types") or {}).items():
|
||||
names.add(name)
|
||||
names |= _names(nested.get("block") or {})
|
||||
return names
|
||||
|
||||
|
||||
def _is_missing(setting: str, known: set[str]) -> bool:
|
||||
"""Whether a name a Check uses is a setting the resource type lacks.
|
||||
|
||||
A path is judged by the setting at its end, and only when it starts at a name
|
||||
the type has. One that does not start there is a value written with dots, such
|
||||
as a database flag (`cloudsql.iam_authentication`) or a service
|
||||
(`run.googleapis.com`): both were raised as missing settings on 2026-10-09.
|
||||
"""
|
||||
first, _, rest = setting.partition(".")
|
||||
if rest and first not in known:
|
||||
return False
|
||||
return setting.split(".")[-1] not in known
|
||||
|
||||
|
||||
class SchemaReview:
|
||||
def __init__(self, runner: TerraformRunner) -> None:
|
||||
self._runner = runner
|
||||
self._names: dict[str, set[str]] = {}
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: DeliverableKind,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]:
|
||||
"""Resource types the provider does not have, and Checks naming a setting
|
||||
their Element's resource type does not have."""
|
||||
if kind != DeliverableKind.TARGET_ARCHITECTURE:
|
||||
return ()
|
||||
try:
|
||||
graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, ""))
|
||||
except GraphError:
|
||||
return ()
|
||||
schemas = await self._runner._load_schemas()
|
||||
if isinstance(schemas, ToolResult):
|
||||
logger.info("Schema review skipped: %s", schemas.message[:120])
|
||||
return ()
|
||||
|
||||
concerns: list[str] = []
|
||||
types = {element.id: element.resource_type for element in graph.elements}
|
||||
for element in graph.elements:
|
||||
if element.resource_type not in schemas:
|
||||
close = difflib.get_close_matches(
|
||||
element.resource_type, schemas, n=3, cutoff=0.6
|
||||
)
|
||||
hint = f" Close matches: {', '.join(close)}." if close else ""
|
||||
concerns.append(
|
||||
f"Element {element.id}: {element.resource_type} is not a "
|
||||
f"resource type of the provider.{hint}"
|
||||
)
|
||||
for check in graph.checks:
|
||||
resource_type = types.get(check.applies_to)
|
||||
if resource_type not in schemas:
|
||||
continue # a Check on a Relationship, or a type already raised
|
||||
known = self._names.setdefault(
|
||||
resource_type, _names(schemas[resource_type][1])
|
||||
)
|
||||
missing = [
|
||||
setting
|
||||
for setting in named_settings(check.statement)
|
||||
if setting not in schemas and _is_missing(setting, known)
|
||||
]
|
||||
if missing:
|
||||
concerns.append(
|
||||
f"Check {check.id}: {resource_type} has no setting named "
|
||||
f"{', '.join(missing)}, so no code can meet it there. Put the "
|
||||
"Check on the Element whose resource type has that setting, "
|
||||
"or reword it. Leave it if that word is a value, not a setting"
|
||||
)
|
||||
if concerns:
|
||||
logger.info("[%s] schema review raised %d item(s)", scope, len(concerns))
|
||||
return tuple(concerns)
|
||||
|
||||
|
||||
class Reviews:
|
||||
"""Several reviews as one: everything any of them raises."""
|
||||
|
||||
def __init__(self, reviews: Sequence[Any]) -> None:
|
||||
self._reviews = tuple(reviews)
|
||||
|
||||
async def __call__(
|
||||
self,
|
||||
kind: Any,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Mapping[str, Mapping[str, Any]] | None,
|
||||
scope: str = "",
|
||||
) -> Sequence[str]:
|
||||
raised: list[str] = []
|
||||
for review in self._reviews:
|
||||
try:
|
||||
raised += await review(kind, attachments, upstream, scope)
|
||||
except Exception: # one review failing must not lose the others
|
||||
logger.exception("A submission review failed; continuing")
|
||||
return tuple(raised)
|
||||
356
app/solution_architecture/target_architecture.py
Normal file
356
app/solution_architecture/target_architecture.py
Normal file
@@ -0,0 +1,356 @@
|
||||
"""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"
|
||||
559
app/solution_architecture/work_breakdown.py
Normal file
559
app/solution_architecture/work_breakdown.py
Normal file
@@ -0,0 +1,559 @@
|
||||
"""The work breakdown structure: a plan for building the Target architecture.
|
||||
|
||||
A Specialist divides the build into work packages and activities and estimates each
|
||||
activity's days. Everything after that is code, as it is for the architecture
|
||||
diagram: the plan is checked against the design, the schedule is computed from the
|
||||
days and the dependencies, and the three views a reader sees are written from the
|
||||
result. So the timeline cannot disagree with the plan, and no part of the design can
|
||||
be left out of it.
|
||||
|
||||
work packages a hierarchy; each delivers named Elements, and is done when the
|
||||
Checks on those Elements pass
|
||||
activities what is done, in which work package, for how many days, after
|
||||
which other activities, and by whom
|
||||
schedule each activity's start and finish day, on a relative axis from
|
||||
Day 0, with no more of the team's activities at once than the
|
||||
team has people; and the critical path
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import datetime as dt
|
||||
import json
|
||||
import math
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
from app.solution_architecture.chain import Upstream, agreed_scope, read_graph
|
||||
|
||||
WORK_BREAKDOWN_FILE = "work-breakdown.json"
|
||||
TIMELINE_FILE = "timeline.mmd"
|
||||
DICTIONARY_HEADING = "WBS dictionary"
|
||||
TEAM, CUSTOMER = "team", "customer"
|
||||
OWNERS = (TEAM, CUSTOMER)
|
||||
DEFAULT_TEAM_SIZE = 2
|
||||
DEFAULT_WEEK = 5
|
||||
MAX_DAYS = 120 # one activity; anything longer is a work package, not an activity
|
||||
_CHART_WIDTH = 60
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Scheduled:
|
||||
id: str
|
||||
start: float
|
||||
finish: float
|
||||
critical: bool
|
||||
|
||||
|
||||
def _text(value: Any) -> str:
|
||||
return " ".join(str(value or "").split())
|
||||
|
||||
|
||||
def _list(value: Any) -> list[str]:
|
||||
return [str(item) for item in value] if isinstance(value, list) else []
|
||||
|
||||
|
||||
def parse(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[str]]:
|
||||
"""(work packages, activities, problems) from the data file."""
|
||||
name = WORK_BREAKDOWN_FILE
|
||||
try:
|
||||
data = json.loads(text)
|
||||
except ValueError as exc:
|
||||
return [], [], [f"{name}: not valid JSON ({exc})"]
|
||||
if not isinstance(data, Mapping):
|
||||
return [], [], [f"{name}: must be an object with work_packages and activities"]
|
||||
packages = [p for p in data.get("work_packages") or [] if isinstance(p, Mapping)]
|
||||
activities = [a for a in data.get("activities") or [] if isinstance(a, Mapping)]
|
||||
return [dict(p) for p in packages], [dict(a) for a in activities], []
|
||||
|
||||
|
||||
def check_work_breakdown(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> list[str]:
|
||||
name = WORK_BREAKDOWN_FILE
|
||||
packages, activities, problems = parse(attachments.get(name, ""))
|
||||
if problems:
|
||||
return problems
|
||||
if not packages:
|
||||
return [f"{name}: lists no work packages"]
|
||||
if not activities:
|
||||
return [f"{name}: lists no activities"]
|
||||
|
||||
ids = [str(p.get("id", "")) for p in packages]
|
||||
problems += [f"{name}: a work package has no id"] if "" in ids else []
|
||||
problems += [
|
||||
f"{name}: work package id {dup} is used more than once"
|
||||
for dup in sorted({i for i in ids if i and ids.count(i) > 1})
|
||||
]
|
||||
known = set(ids)
|
||||
parents = {str(p.get("id")): p.get("parent") for p in packages}
|
||||
for package in packages:
|
||||
ident, parent = str(package.get("id")), package.get("parent")
|
||||
if not _text(package.get("name")):
|
||||
problems.append(f"{name}: {ident} has no name")
|
||||
if parent is not None and str(parent) not in known:
|
||||
problems.append(
|
||||
f"{name}: {ident} has parent {parent}, which does not exist"
|
||||
)
|
||||
seen, node = {ident}, parent
|
||||
while node is not None and str(node) in parents:
|
||||
if str(node) in seen:
|
||||
problems.append(f"{name}: {ident} is its own ancestor")
|
||||
break
|
||||
seen.add(str(node))
|
||||
node = parents[str(node)]
|
||||
|
||||
graph = read_graph(upstream)
|
||||
if graph is not None:
|
||||
elements = {element.id for element in graph.elements}
|
||||
covered: set[str] = set()
|
||||
for package in packages:
|
||||
listed = _list(package.get("elements"))
|
||||
covered.update(listed)
|
||||
problems += [
|
||||
f"{name}: {package.get('id')} delivers {element}, which is not an "
|
||||
"Element of the Target architecture"
|
||||
for element in listed
|
||||
if element not in elements
|
||||
]
|
||||
left = sorted(elements - covered)
|
||||
if left:
|
||||
problems.append(
|
||||
f"{name}: no work package delivers {', '.join(left)}; every Element "
|
||||
"of the Target architecture belongs to one"
|
||||
)
|
||||
|
||||
activity_ids = [str(a.get("id", "")) for a in activities]
|
||||
problems += [
|
||||
f"{name}: activity id {dup} is used more than once"
|
||||
for dup in sorted({i for i in activity_ids if i and activity_ids.count(i) > 1})
|
||||
]
|
||||
known_activities = set(activity_ids)
|
||||
with_work = set()
|
||||
for activity in activities:
|
||||
ident = str(activity.get("id", ""))
|
||||
if not ident or not _text(activity.get("name")):
|
||||
problems.append(f"{name}: an activity needs an id and a name")
|
||||
continue
|
||||
within = str(activity.get("work_package", ""))
|
||||
if within not in known:
|
||||
problems.append(f"{name}: {ident} is in {within}, not a work package")
|
||||
with_work.add(within)
|
||||
days = activity.get("days")
|
||||
if isinstance(days, bool) or not isinstance(days, (int, float)) or days <= 0:
|
||||
problems.append(f"{name}: {ident} needs `days`, a number above 0")
|
||||
elif days > MAX_DAYS:
|
||||
problems.append(
|
||||
f"{name}: {ident} is {days} days; split anything over {MAX_DAYS}"
|
||||
)
|
||||
problems += [
|
||||
f"{name}: {ident} comes after {before}, which is not an activity"
|
||||
for before in _list(activity.get("after"))
|
||||
if before not in known_activities
|
||||
]
|
||||
if activity.get("owner", TEAM) not in OWNERS:
|
||||
problems.append(f"{name}: {ident} owner must be one of {', '.join(OWNERS)}")
|
||||
has_children = {str(parent) for parent in parents.values() if parent is not None}
|
||||
problems += [
|
||||
f"{name}: {ident} has no activity and no work package beneath it"
|
||||
for ident in ids
|
||||
if ident and ident not in with_work and ident not in has_children
|
||||
]
|
||||
if not problems and _cycle(activities):
|
||||
problems.append(
|
||||
f"{name}: activities depend on each other in a circle: "
|
||||
+ " -> ".join(_cycle(activities))
|
||||
)
|
||||
return problems
|
||||
|
||||
|
||||
def _cycle(activities: Sequence[Mapping[str, Any]]) -> list[str]:
|
||||
"""Activities that depend on each other in a circle; empty when none do."""
|
||||
after = {str(a["id"]): _list(a.get("after")) for a in activities}
|
||||
state: dict[str, int] = {}
|
||||
|
||||
def visit(node: str, path: list[str]) -> list[str]:
|
||||
state[node] = 1
|
||||
for before in after.get(node, ()):
|
||||
if state.get(before) == 1:
|
||||
return (
|
||||
[*path[path.index(before) :], before]
|
||||
if before in path
|
||||
else [before, node]
|
||||
)
|
||||
if state.get(before, 0) == 0:
|
||||
found = visit(before, [*path, before])
|
||||
if found:
|
||||
return found
|
||||
state[node] = 2
|
||||
return []
|
||||
|
||||
for node in after:
|
||||
if state.get(node, 0) == 0:
|
||||
found = visit(node, [node])
|
||||
if found:
|
||||
return found
|
||||
return []
|
||||
|
||||
|
||||
def schedule(
|
||||
activities: Sequence[Mapping[str, Any]], team_size: int = DEFAULT_TEAM_SIZE
|
||||
) -> dict[str, Scheduled]:
|
||||
"""Each activity's start and finish day, from Day 0.
|
||||
|
||||
An activity starts when everything it comes after has finished. The team's own
|
||||
activities also wait for a free person: no more run at once than `team_size`.
|
||||
What the customer owns, such as a supplier's lead time, takes nobody from the
|
||||
team. The critical path is every activity with no slack: delay it and the end
|
||||
moves.
|
||||
"""
|
||||
team_size = max(1, int(team_size))
|
||||
by_id = {str(a["id"]): a for a in activities}
|
||||
after = {ident: _list(a.get("after")) for ident, a in by_id.items()}
|
||||
days = {ident: float(a["days"]) for ident, a in by_id.items()}
|
||||
# The longest chain of work that follows an activity: what to start first when
|
||||
# people are short.
|
||||
followers: dict[str, list[str]] = {ident: [] for ident in by_id}
|
||||
for ident, befores in after.items():
|
||||
for before in befores:
|
||||
followers[before].append(ident)
|
||||
tail: dict[str, float] = {}
|
||||
|
||||
def remaining(ident: str) -> float:
|
||||
if ident not in tail:
|
||||
tail[ident] = days[ident] + max(
|
||||
(remaining(f) for f in followers[ident]), default=0.0
|
||||
)
|
||||
return tail[ident]
|
||||
|
||||
start: dict[str, float] = {}
|
||||
finish: dict[str, float] = {}
|
||||
busy: list[tuple[float, float]] = [] # the team's activities already placed
|
||||
pending = set(by_id)
|
||||
while pending:
|
||||
ready = [i for i in pending if all(b in finish for b in after[i])]
|
||||
ready.sort(key=lambda i: (-remaining(i), i))
|
||||
ident = min(
|
||||
ready,
|
||||
key=lambda i: (
|
||||
max((finish[b] for b in after[i]), default=0.0),
|
||||
-remaining(i),
|
||||
i,
|
||||
),
|
||||
)
|
||||
earliest = max((finish[b] for b in after[ident]), default=0.0)
|
||||
if by_id[ident].get("owner", TEAM) == TEAM:
|
||||
candidates = sorted({earliest, *(end for _, end in busy if end > earliest)})
|
||||
for moment in candidates:
|
||||
overlapping = sum(
|
||||
1 for s, e in busy if s < moment + days[ident] and e > moment
|
||||
)
|
||||
if overlapping < team_size:
|
||||
earliest = moment
|
||||
break
|
||||
busy.append((earliest, earliest + days[ident]))
|
||||
start[ident], finish[ident] = earliest, earliest + days[ident]
|
||||
pending.discard(ident)
|
||||
|
||||
end = max(finish.values(), default=0.0)
|
||||
latest: dict[str, float] = {}
|
||||
|
||||
def latest_finish(ident: str) -> float:
|
||||
if ident not in latest:
|
||||
latest[ident] = min(
|
||||
(latest_finish(f) - days[f] for f in followers[ident]), default=end
|
||||
)
|
||||
return latest[ident]
|
||||
|
||||
return {
|
||||
ident: Scheduled(
|
||||
ident,
|
||||
start[ident],
|
||||
finish[ident],
|
||||
critical=latest_finish(ident) - finish[ident] < 1e-6,
|
||||
)
|
||||
for ident in by_id
|
||||
}
|
||||
|
||||
|
||||
# --- what the plan is checked against, from the agreed scope ----------------------------
|
||||
|
||||
|
||||
def _scoped(scope: Mapping[str, Any], path: str) -> Any:
|
||||
"""A field of the agreed scope, stated or assumed; None when it is neither."""
|
||||
node: Any = scope.get("stated") or {}
|
||||
for part in path.split("."):
|
||||
node = node.get(part) if isinstance(node, Mapping) else None
|
||||
if node is not None:
|
||||
return node
|
||||
for item in scope.get("assumed") or []:
|
||||
if isinstance(item, Mapping) and item.get("field") == path:
|
||||
return item.get("value")
|
||||
return None
|
||||
|
||||
|
||||
def delivery_terms(upstream: Upstream | None) -> dict[str, Any]:
|
||||
"""Team size, working week, window and start date, from the agreed scope."""
|
||||
scope = agreed_scope(upstream)
|
||||
|
||||
def number(path: str, default: int) -> int:
|
||||
value = _scoped(scope, path)
|
||||
ok = (
|
||||
isinstance(value, (int, float))
|
||||
and not isinstance(value, bool)
|
||||
and value > 0
|
||||
)
|
||||
return int(value) if ok else default
|
||||
|
||||
window = _scoped(scope, "delivery.window_weeks")
|
||||
start = _scoped(scope, "delivery.target_start_date")
|
||||
try:
|
||||
start_date = dt.date.fromisoformat(str(start)) if start else None
|
||||
except ValueError:
|
||||
start_date = None
|
||||
return {
|
||||
"team_size": number("delivery.team_size", DEFAULT_TEAM_SIZE),
|
||||
"team_size_stated": _scoped(scope, "delivery.team_size") is not None,
|
||||
"week": number("delivery.working_days_per_week", DEFAULT_WEEK),
|
||||
"window_weeks": window if isinstance(window, (int, float)) else None,
|
||||
"start": start_date,
|
||||
}
|
||||
|
||||
|
||||
# --- the three views --------------------------------------------------------------------
|
||||
|
||||
|
||||
def _day(value: float) -> str:
|
||||
return str(int(value)) if float(value).is_integer() else f"{value:.1f}"
|
||||
|
||||
|
||||
def _calendar(start: dt.date, day: float, week: int) -> dt.date:
|
||||
"""The calendar date of a working day counted from `start`."""
|
||||
weeks, days = divmod(math.floor(day), week)
|
||||
return start + dt.timedelta(days=weeks * 7 + days)
|
||||
|
||||
|
||||
def render(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
|
||||
"""The WBS dictionary, the activity sequence and the timeline, as markdown
|
||||
written from the data file. "" when the file cannot be read."""
|
||||
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
|
||||
if problems or not packages or not activities:
|
||||
return ""
|
||||
terms = delivery_terms(upstream)
|
||||
plan = schedule(activities, terms["team_size"])
|
||||
graph = read_graph(upstream)
|
||||
checks: dict[str, list[str]] = {}
|
||||
for check in graph.checks if graph else ():
|
||||
checks.setdefault(check.applies_to, []).append(check.id)
|
||||
|
||||
parents = {str(p["id"]): p.get("parent") for p in packages}
|
||||
|
||||
def depth(ident: str) -> int:
|
||||
level, node = 0, parents.get(ident)
|
||||
while node is not None and str(node) in parents and level < 10:
|
||||
level, node = level + 1, parents.get(str(node))
|
||||
return level
|
||||
|
||||
effort: dict[str, float] = {}
|
||||
for activity in activities:
|
||||
effort[str(activity["work_package"])] = effort.get(
|
||||
str(activity["work_package"]), 0.0
|
||||
) + float(activity["days"])
|
||||
|
||||
def cell(value: Any) -> str:
|
||||
return _text(value).replace("|", "\\|") or "-"
|
||||
|
||||
lines = [
|
||||
f"## {DICTIONARY_HEADING}",
|
||||
"",
|
||||
"Each work package, what it delivers, and the Checks that say it is done.",
|
||||
"",
|
||||
"| Id | Work package | Scope | Produces | Elements | Done when these pass | Skills | Days |",
|
||||
"| --- | --- | --- | --- | --- | --- | --- | --- |",
|
||||
]
|
||||
for package in packages:
|
||||
ident = str(package["id"])
|
||||
elements = _list(package.get("elements"))
|
||||
accepted = [c for element in elements for c in checks.get(element, [])]
|
||||
lines.append(
|
||||
"| "
|
||||
+ " | ".join(
|
||||
[
|
||||
ident,
|
||||
(" " * depth(ident)) + cell(package.get("name")),
|
||||
cell(package.get("scope")),
|
||||
cell("; ".join(_list(package.get("produces")))),
|
||||
cell(", ".join(elements)),
|
||||
cell(", ".join(accepted)),
|
||||
cell(", ".join(_list(package.get("skills")))),
|
||||
_day(effort[ident]) if ident in effort else "-",
|
||||
]
|
||||
)
|
||||
+ " |"
|
||||
)
|
||||
|
||||
ordered = sorted(activities, key=lambda a: (plan[str(a["id"])].start, str(a["id"])))
|
||||
dated = terms["start"] is not None
|
||||
lines += [
|
||||
"",
|
||||
"## Activity sequence",
|
||||
"",
|
||||
"| Id | Activity | Work package | Days | After | Start | Finish |"
|
||||
+ (" Dates |" if dated else "")
|
||||
+ " Owner | Critical |",
|
||||
"| --- | --- | --- | --- | --- | --- | --- |"
|
||||
+ (" --- |" if dated else "")
|
||||
+ " --- | --- |",
|
||||
]
|
||||
for activity in ordered:
|
||||
item = plan[str(activity["id"])]
|
||||
row = [
|
||||
str(activity["id"]),
|
||||
cell(activity.get("name")),
|
||||
str(activity.get("work_package")),
|
||||
_day(float(activity["days"])),
|
||||
cell(", ".join(_list(activity.get("after")))),
|
||||
f"Day {_day(item.start)}",
|
||||
f"Day {_day(item.finish)}",
|
||||
]
|
||||
if dated:
|
||||
begins = _calendar(terms["start"], item.start, terms["week"])
|
||||
ends = _calendar(terms["start"], max(item.finish - 1e-9, 0), terms["week"])
|
||||
row.append(f"{begins.isoformat()} to {ends.isoformat()}")
|
||||
row += [str(activity.get("owner", TEAM)), "yes" if item.critical else ""]
|
||||
lines.append("| " + " | ".join(row) + " |")
|
||||
|
||||
total = max(item.finish for item in plan.values())
|
||||
weeks = total / terms["week"]
|
||||
lines += [
|
||||
"",
|
||||
"## Timeline",
|
||||
"",
|
||||
"```text",
|
||||
*_chart(ordered, plan, total),
|
||||
"```",
|
||||
"",
|
||||
]
|
||||
summary = (
|
||||
f"{_day(total)} working days, about {weeks:.1f} weeks, with a team of "
|
||||
f"{terms['team_size']}"
|
||||
+ (
|
||||
""
|
||||
if terms["team_size_stated"]
|
||||
else " (assumed; the scope gives no team size)"
|
||||
)
|
||||
+ f" and a {terms['week']}-day week."
|
||||
)
|
||||
lines.append(summary)
|
||||
window = terms["window_weeks"]
|
||||
if window is not None:
|
||||
if weeks <= window + 1e-9:
|
||||
lines.append(
|
||||
f"That is inside the {window}-week delivery window, with "
|
||||
f"{window - weeks:.1f} weeks to spare."
|
||||
)
|
||||
else:
|
||||
path = [str(a["id"]) for a in ordered if plan[str(a["id"])].critical]
|
||||
lines.append(
|
||||
f"**That is {weeks - window:.1f} weeks over the {window}-week delivery "
|
||||
f"window.** The critical path is {' -> '.join(path)}: only shortening "
|
||||
"or removing work on it, or adding people where it waits for them, "
|
||||
"brings the end in."
|
||||
)
|
||||
theirs = [a for a in ordered if a.get("owner", TEAM) == CUSTOMER]
|
||||
if theirs:
|
||||
lines += ["", "The customer owns these, and the plan waits on them:"]
|
||||
lines += [
|
||||
f"- {a['id']} {_text(a.get('name'))}: {_day(float(a['days']))} days"
|
||||
+ (f". {_text(a.get('assumption'))}" if _text(a.get("assumption")) else "")
|
||||
for a in theirs
|
||||
]
|
||||
lines += [
|
||||
"",
|
||||
(
|
||||
"Durations are estimates made without knowing the team, and are "
|
||||
"indicative. Days are working days counted from Day 0, the day work "
|
||||
"starts; each of the team's activities takes one person."
|
||||
),
|
||||
]
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def _chart(
|
||||
ordered: Sequence[Mapping[str, Any]], plan: Mapping[str, Scheduled], total: float
|
||||
) -> list[str]:
|
||||
"""The timeline as text: one row per activity along a relative day axis."""
|
||||
scale = min(1.0, _CHART_WIDTH / total) if total else 1.0
|
||||
labels = [f"{a['id']} {_text(a.get('name'))}"[:38] for a in ordered]
|
||||
width = max(len(label) for label in labels) + 2
|
||||
step = max(1, math.ceil(total / 6 / 5.0) * 5)
|
||||
axis = [" "] * (int(total * scale) + 8)
|
||||
for day in range(0, int(total) + 1, step):
|
||||
mark = str(day)
|
||||
at = int(day * scale)
|
||||
axis[at : at + len(mark)] = mark
|
||||
rows = [" " * width + "Day " + "".join(axis).rstrip()]
|
||||
for label, activity in zip(labels, ordered, strict=True):
|
||||
item = plan[str(activity["id"])]
|
||||
begin = round(item.start * scale)
|
||||
length = max(1, round((item.finish - item.start) * scale))
|
||||
block = "░" if activity.get("owner", TEAM) == CUSTOMER else "█"
|
||||
flag = " *" if item.critical else ""
|
||||
rows.append(f"{label.ljust(width)} {' ' * begin}{block * length}{flag}")
|
||||
rows += ["", "█ the team ░ the customer * on the critical path"]
|
||||
return rows
|
||||
|
||||
|
||||
def mermaid(attachments: Mapping[str, str], upstream: Upstream | None) -> str:
|
||||
"""A Mermaid Gantt chart on calendar dates, when the scope gives a start date.
|
||||
"" otherwise: a relative plan has no dates to draw."""
|
||||
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
|
||||
terms = delivery_terms(upstream)
|
||||
if problems or not activities or terms["start"] is None:
|
||||
return ""
|
||||
plan = schedule(activities, terms["team_size"])
|
||||
names = {str(p["id"]): _text(p.get("name")) for p in packages}
|
||||
lines = ["gantt", " dateFormat YYYY-MM-DD", " excludes weekends"]
|
||||
for package in packages:
|
||||
own = [
|
||||
a for a in activities if str(a.get("work_package")) == str(package["id"])
|
||||
]
|
||||
if not own:
|
||||
continue
|
||||
lines.append(f" section {names[str(package['id'])].replace(':', ' ')}")
|
||||
for activity in sorted(own, key=lambda a: plan[str(a["id"])].start):
|
||||
item = plan[str(activity["id"])]
|
||||
begins = _calendar(terms["start"], item.start, terms["week"])
|
||||
tag = "crit, " if item.critical else ""
|
||||
label = _text(activity.get("name")).replace(":", " ")
|
||||
lines.append(
|
||||
f" {label} :{tag}{activity['id']}, {begins.isoformat()}, "
|
||||
f"{max(1, math.ceil(float(activity['days'])))}d"
|
||||
)
|
||||
return "\n".join(lines) + "\n"
|
||||
|
||||
|
||||
def summary(
|
||||
attachments: Mapping[str, str], upstream: Upstream | None
|
||||
) -> dict[str, Any]:
|
||||
"""The plan in a few numbers, for an Approval and for the Execution's record."""
|
||||
packages, activities, problems = parse(attachments.get(WORK_BREAKDOWN_FILE, ""))
|
||||
if problems or not activities:
|
||||
return {}
|
||||
terms = delivery_terms(upstream)
|
||||
plan = schedule(activities, terms["team_size"])
|
||||
total = max(item.finish for item in plan.values())
|
||||
weeks = round(total / terms["week"], 1)
|
||||
return {
|
||||
"work_packages": len(packages),
|
||||
"activities": len(activities),
|
||||
"working_days": round(total, 1),
|
||||
"weeks": weeks,
|
||||
"team_size": terms["team_size"],
|
||||
"window_weeks": terms["window_weeks"],
|
||||
"within_window": None
|
||||
if terms["window_weeks"] is None
|
||||
else weeks <= terms["window_weeks"],
|
||||
"critical_path": [i for i, item in plan.items() if item.critical],
|
||||
}
|
||||
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