Files
gcp_solution_architecture_a…/app/tools/pillars.py
Jonathan Boniface 844987587c feat: consult only the pillars a change affects directly (iteration 5 step 3)
A graded question per pillar (not at all, only indirectly, directly) picks
the pillar advisors to consult again on a Revision or a Change request; the
design advisor is told which, and keeps its earlier advice for the rest. As
a yes or no the answer was yes for nearly every pillar of every change.

A completed Execution now writes working.json with each pillar's advice
and checklist review, and a Change request starts from its Baseline's, so
only the pillars a change touches are consulted afresh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 15:22:57 +01:00

305 lines
11 KiB
Python

"""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 app.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
STATUSES = ("addressed", "not_applicable", "not_addressed")
_STATUS_WORDS = {
"addressed": "Addressed",
"not_applicable": "Does not apply",
"not_addressed": "Not addressed",
}
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.")
review[:] = [
{
"item": " ".join(str(entry.get("item", "")).split()),
"status": str(entry.get("status", "")),
"note": " ".join(str(entry.get("note", "")).split()),
}
for entry in checklist or ()
if isinstance(entry, Mapping)
and str(entry.get("item", "")).strip()
and entry.get("status") in STATUSES
]
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, or "
"why it does not apply to this workload.",
},
},
"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, and what does not apply and why."
),
]
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)
]
return "\n".join(parts) + "\n"