Files
gcp_solution_architecture_a…/eval/scoring.py
Jonathan Boniface 654370bb46 feat: all four evaluation cases pass; intake, checklist review, thresholds
Case 04 (interactive)
- A scripted answer may name who it is for, so facts written for
  requirements discovery are not given to a Specialist confirming a draft.
- A reply that restates what the agreed requirements already say is read
  as an answer, not a request for changes.
- With a user present, a first submission is refused until the user has
  been shown a draft of that Deliverable (CONFIRM_DRAFTS).

Routing and reviews
- Intake: a message that starts something is read first. A question is
  answered and starts nothing; a change to delivered work starts as a new
  request with a note, until Change requests are built.
- Requirements and recommendations list what infrastructure code can show
  (conditions) apart from what it cannot (outside_code); the latter needs
  no Check and validation proposes nothing for it.
- A requirements review, "names no products", behind its own switch (off).
- Each pillar advisor reviews its pillar's checklist; the engine writes the
  reviews into the design recommendations. The judged checklist check went
  from 9-45% a pillar to 100% in one run of case 04.

Evaluation
- Per-case thresholds for Revisions, seconds and tokens, set from every
  completed run on this build.
- A progress file after every agent run, so an interrupted run keeps its
  time and tokens.
- eval/calibrate_judge.py with a 32-question set awaiting a person's
  labels. Unlabelled: Jev stable at 1.00, Gemini 0.92, agreeing on 0.91.

Smaller
- An Execution that ends with warnings writes its Deliverables, with the
  warnings and each status in the manifest.
- CI installs the application's dependencies before linting and testing.
- A load-balancer pattern in the IaC patterns Skill.

Plans record nine runs of 2026-10-08. Iteration 6 is complete.

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

438 lines
15 KiB
Python

"""Score a finished Execution against a benchmark case.
Each check is a small, explainable rule tied to the upstream Skill's requirements.
A case passes when its score reaches PASS_THRESHOLD.
Structural checks always run. Judged checks (pillar checklist coverage, recommendation
quality) run when a judge is given, and are what lets a better or worse Skill move the
score. Thresholds on revisions, seconds and tokens turn a slower or costlier run into a
reported regression without changing the score.
"""
from __future__ import annotations
import json
import re
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from app.adk.runtime import ToolResult
from app.agent import Interaction
from app.tools.local import mermaid_check
from app.workflows.chain import (
COMPONENTS_FILE,
PRODUCTS_FILE,
RECOMMENDATIONS_FILE,
REQUIREMENTS_FILE,
VERDICTS_FILE,
read_graph,
read_list,
validation_outcome,
)
from app.workflows.deliverables import DeliverableKind
from app.workflows.target_architecture import (
DIAGRAM_ATTACHMENT,
GRAPH_ATTACHMENT,
GraphError,
chain_gaps,
parse_graph,
render_mermaid,
)
from eval.judge import Judge, JudgeUnavailable
PASS_THRESHOLD = 0.8
CHECKLIST_COVERAGE = 0.7 # share of a pillar Skill's checklist the design must address
QUALITY_BAR = 0.67 # mean of the graded rubric: "mostly" or better
THRESHOLD_METRICS = ("revisions", "seconds", "tokens")
# What a reviewer would ask of design recommendations, graded 0 to 1 each.
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?",
}
TerraformValidate = Callable[[Mapping[str, str]], Awaitable[ToolResult]]
_HEADING = re.compile(r"^(#{2,6})\s+(.+?)\s*$", re.MULTILINE)
_NUMBERING = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
_DOC_LINK = re.compile(r"https://(?:docs\.)?cloud\.google\.com/\S+")
@dataclass(frozen=True)
class CaseSpec:
id: str
name: str
workflow_request: str
required_products: tuple[str, ...]
scripted_answers: tuple[tuple[str, ...], ...] # (pattern, answer[, asker])
# Run with a user in the loop (scripted): Approvals and questions are answered
# turn by turn, and Specialists are checked for asking before they submit.
interactive: bool = False
# Upper bounds for "revisions", "seconds" and "tokens"; exceeding one is a regression.
thresholds: Mapping[str, float] = field(default_factory=dict)
@dataclass(frozen=True)
class Check:
name: str
passed: bool
detail: str = ""
@dataclass(frozen=True)
class CaseResult:
case_id: str
status: str
checks: tuple[Check, ...]
details: Mapping[str, Any] = field(default_factory=dict)
@property
def score(self) -> float:
return (
sum(c.passed for c in self.checks) / len(self.checks)
if self.checks
else 0.0
)
@property
def passed(self) -> bool:
return self.score >= PASS_THRESHOLD
def load_cases(path: Path) -> list[CaseSpec]:
return [
CaseSpec(
id=item["id"],
name=item["name"],
workflow_request=item["workflow_request"],
required_products=tuple(item["required_products"]),
scripted_answers=tuple(
tuple(pair) for pair in item.get("scripted_answers", [])
),
interactive=bool(item.get("interactive", False)),
thresholds=dict(item.get("thresholds", {})),
)
for item in json.loads(path.read_text(encoding="utf-8"))
]
def template_headings(template: Path) -> list[str]:
"""Section headings (level 2+) of a solution-guide template, placeholders removed."""
return [
heading
for _, heading in _HEADING.findall(template.read_text(encoding="utf-8"))
if "[" not in heading
]
def checklist_items(skill_file: Path) -> list[str]:
"""The bullet items under a pillar Skill's "Validation checklist" heading."""
text = skill_file.read_text(encoding="utf-8")
match = re.search(
r"^##\s+Validation checklist\s*$(.*?)(?=^##\s|\Z)",
text,
re.MULTILINE | re.DOTALL,
)
if not match:
return []
# Bullets may nest: a bullet with deeper bullets under it is a category, and the
# items to check are the leaves, each prefixed with its category.
bullets: list[tuple[int, str]] = []
for line in match.group(1).splitlines():
bullet = re.match(r"^(\s*)[-*]\s+(.*)$", line)
if bullet:
text = re.sub(r"^\[[ xX]?\]\s*", "", bullet.group(2).strip())
bullets.append((len(bullet.group(1)), text.replace("**", "")))
elif bullets and line.startswith(" ") and line.strip():
indent, text = bullets[-1]
bullets[-1] = (indent, f"{text} {line.strip()}")
items: list[str] = []
category = ""
for index, (indent, text) in enumerate(bullets):
has_children = index + 1 < len(bullets) and bullets[index + 1][0] > indent
if has_children:
category = text.rstrip(":").strip()
elif indent == 0:
category = ""
items.append(text)
else:
items.append(f"{category}: {text}" if category else text)
return items
def regressions(case: CaseSpec, measured: Mapping[str, float | None]) -> list[str]:
"""Each threshold the run exceeded, as "metric: measured > limit"."""
over = []
for metric in THRESHOLD_METRICS:
limit = case.thresholds.get(metric)
value = measured.get(metric)
if limit is not None and value is not None and value > limit:
over.append(f"{metric}: {value:g} > {limit:g}")
return over
def _normalise(text: str) -> str:
return " ".join(_NUMBERING.sub("", text.strip().lower()).split())
def _mentions(text: str, product: str) -> bool:
return (
re.search(rf"(?<![\w/]){re.escape(product.lower())}(?![\w/])", text.lower())
is not None
)
async def score_execution(
case: CaseSpec,
interaction: Interaction,
headings: Sequence[str],
terraform_validate: TerraformValidate,
*,
judge: Judge | None = None,
pillar_checklists: Mapping[str, Sequence[str]] | None = None,
timeline: Sequence[Mapping[str, Any]] = (),
) -> CaseResult:
deliverables: Mapping[str, Mapping[str, Any]] = interaction.state.get(
"deliverables", {}
)
def content(kind: DeliverableKind) -> str:
item = deliverables.get(kind.value)
return item["content"] if item else ""
def attachments(kind: DeliverableKind) -> Mapping[str, str]:
item = deliverables.get(kind.value)
return item.get("attachments", {}) if item else {}
checks: list[Check] = []
checks.append(
Check(
"completed",
interaction.status == "completed",
"; ".join(interaction.state.get("warnings", [])) or interaction.status,
)
)
guide = content(DeliverableKind.SOLUTION_GUIDE)
guide_headings = {_normalise(h) for _, h in _HEADING.findall(guide)}
missing_sections = [h for h in headings if _normalise(h) not in guide_headings]
checks.append(
Check(
"guide_follows_template",
bool(guide) and not missing_sections,
"missing: " + "; ".join(missing_sections) if missing_sections else "",
)
)
selection = content(DeliverableKind.PRODUCT_SELECTION)
selected_text = selection + "\n" + guide
missing_products = [
p for p in case.required_products if not _mentions(selected_text, p)
]
checks.append(
Check(
"required_products_selected",
bool(selection) and not missing_products,
"missing: " + ", ".join(missing_products) if missing_products else "",
)
)
lowered = selection.lower()
checks.append(
Check(
"selection_has_alternatives",
"alternative" in lowered and "pros" in lowered and "cons" in lowered,
)
)
checks.append(
Check(
"selection_cites_documentation",
bool(_DOC_LINK.search(selection)),
)
)
requirements = content(DeliverableKind.REQUIREMENTS)
leaked = [
product
for product in case.required_products
if _mentions(requirements, product)
and not _mentions(case.workflow_request, product)
]
checks.append(
Check(
"requirements_name_no_products",
bool(requirements) and not leaked,
"names: " + ", ".join(leaked) if leaked else "",
)
)
diagram = attachments(DeliverableKind.TARGET_ARCHITECTURE).get(
"architecture.mmd", ""
)
mermaid = await mermaid_check(diagram)
checks.append(
Check(
"diagram_is_valid_mermaid",
bool(diagram) and mermaid.message.startswith("Mermaid check passed"),
mermaid.message,
)
)
terraform_files = {
name.removeprefix("terraform/"): text
for name, text in attachments(DeliverableKind.DEPLOYMENT_GUIDANCE).items()
if name.endswith((".tf", ".tfvars", ".tf.json"))
}
if terraform_files:
validation = await terraform_validate(terraform_files)
terraform_ok = validation.message.startswith("terraform validate passed")
terraform_detail = validation.message[:1500]
else:
terraform_ok, terraform_detail = False, "no Terraform files attached"
checks.append(Check("terraform_validates", terraform_ok, terraform_detail))
checks.append(_chain_check(deliverables))
checks.append(_verdicts_check(attachments(DeliverableKind.VALIDATION_RESULTS)))
checks.append(
_diagram_matches_graph(attachments(DeliverableKind.TARGET_ARCHITECTURE))
)
if case.interactive:
checks.append(_asks_before_submitting(timeline))
if judge is not None:
recommendations = content(DeliverableKind.DESIGN_RECOMMENDATIONS)
checks.append(
await _checklist_coverage(judge, recommendations, pillar_checklists or {})
)
checks.append(await _quality(judge, recommendations))
return CaseResult(case.id, interaction.status, tuple(checks))
def _chain_check(deliverables: Mapping[str, Mapping[str, Any]]) -> Check:
"""The Requirements chain holds end to end: every requirement reaches a Check,
directly or through a component's Element, and nothing along it is missing."""
name = "requirements_chain_complete"
graph = read_graph(deliverables)
if graph is None:
return Check(name, False, "no well-formed Target architecture")
gaps = chain_gaps(
graph,
requirements=read_list(deliverables, "requirements", REQUIREMENTS_FILE),
components=read_list(deliverables, "technical_decomposition", COMPONENTS_FILE),
products=read_list(deliverables, "product_selection", PRODUCTS_FILE),
recommendations=read_list(
deliverables, "design_recommendations", RECOMMENDATIONS_FILE
),
)
return Check(name, not gaps, "; ".join(gaps))
def _verdicts_check(attachments: Mapping[str, str]) -> Check:
"""Validation ended with every Check passed and the dry-run not failed."""
name = "every_check_passes"
text = attachments.get(VERDICTS_FILE)
if text is None:
return Check(name, False, f"no {VERDICTS_FILE}")
outcome = validation_outcome(text)
open_checks = [f"{item['check']} failed" for item in outcome["failed"]] + [
f"{item['check']} not verifiable" for item in outcome["not_verifiable"]
]
if outcome["dry_run"].get("verdict") == "fail":
open_checks.append("dry-run failed")
if not outcome["passed"] and not open_checks:
open_checks.append("no verdicts")
return Check(name, not open_checks, "; ".join(open_checks))
def _diagram_matches_graph(attachments: Mapping[str, str]) -> Check:
name = "diagram_matches_graph"
try:
graph = parse_graph(attachments.get(GRAPH_ATTACHMENT, ""))
except GraphError as exc:
return Check(name, False, exc.problems[0])
matches = attachments.get(DIAGRAM_ATTACHMENT) == render_mermaid(graph)
return Check(name, matches, "" if matches else "the diagram is not the graph's")
def _asks_before_submitting(timeline: Sequence[Mapping[str, Any]]) -> Check:
"""In an interactive Execution every Specialist confirms with the user before its
first submission (spec risk D32)."""
asked: set[str] = set()
silent: list[str] = []
seen: set[str] = set()
for run in timeline:
deliverable = run.get("deliverable")
if not deliverable:
continue
if run.get("outcome") == "NeedsInput":
asked.add(deliverable)
elif run.get("outcome") == "Submitted" and deliverable not in seen:
seen.add(deliverable)
if deliverable not in asked:
silent.append(deliverable)
return Check(
"specialists_ask_before_submitting",
bool(seen) and not silent,
"submitted without asking: " + ", ".join(silent) if silent else "",
)
async def _checklist_coverage(
judge: Judge, recommendations: str, checklists: Mapping[str, Sequence[str]]
) -> Check:
name = "pillar_checklists_covered"
questions = {
f"{pillar}.{index}": {
"kind": "yes_no",
"text": f"Do the recommendations address this {pillar} checklist item, "
f"either by recommending it or by explaining why it does not apply? {item}",
}
for pillar, items in checklists.items()
for index, item in enumerate(items)
}
if not recommendations or not questions:
return Check(name, False, "no design recommendations or no checklists")
try:
scores = await judge.answer(recommendations, questions)
except JudgeUnavailable as exc:
return Check(name, False, f"judge unavailable: {exc}")
per_pillar = {
pillar: sum(scores.get(f"{pillar}.{i}", 0) for i in range(len(items)))
/ len(items)
for pillar, items in checklists.items()
if items
}
weakest = min(per_pillar.values())
detail = ", ".join(f"{pillar} {share:.0%}" for pillar, share in per_pillar.items())
return Check(name, weakest >= CHECKLIST_COVERAGE, detail)
async def _quality(judge: Judge, recommendations: str) -> Check:
name = "recommendations_quality"
if not recommendations:
return Check(name, False, "no design recommendations")
try:
scores = await judge.answer(
recommendations,
{
key: {"kind": "graded", "text": text}
for key, text in QUALITY_RUBRIC.items()
},
)
except JudgeUnavailable as exc:
return Check(name, False, f"judge unavailable: {exc}")
mean = sum(scores.values()) / len(QUALITY_RUBRIC)
detail = ", ".join(f"{key} {scores.get(key, 0):.2f}" for key in QUALITY_RUBRIC)
return Check(name, mean >= QUALITY_BAR, f"mean {mean:.2f}: {detail}")