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>
This commit is contained in:
2026-10-09 09:32:57 +01:00
parent d41607f505
commit 654370bb46
53 changed files with 2122 additions and 106 deletions

184
eval/calibrate_judge.py Normal file
View File

@@ -0,0 +1,184 @@
"""Calibrate the evaluation's judges against a person's labels.
A labelled set is questions about saved design recommendations, each with the
answer a person gave. This asks every judge each question several times and reports:
agreement how often the judge's answer matches the person's
stability how often the judge gives the same answer to the same question
between how often the two judges agree with each other
Stability and agreement between judges need no labels, so they can be measured
before anyone has marked the set. Agreement with a person cannot.
Usage:
.venv/bin/python -m eval.calibrate_judge [--runs 3] [--build]
--build writes eval/datasets/judge/labels.json from the documents in that folder,
with `label` left empty for a person to fill in: 1 or 0 for a yes_no question; 0,
0.33, 0.67 or 1 for a graded one. Costs model usage: run deliberately.
"""
from __future__ import annotations
import asyncio
import json
import random
import sys
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any
from app.agent import open_decider
from app.config import get_settings
from app.providers import load_provider
from eval.judge import DeciderJudge, GeminiJudge, Judge, JudgeUnavailable
from eval.scoring import QUALITY_RUBRIC, checklist_items
FOLDER = Path(__file__).resolve().parent / "datasets" / "judge"
LABELS = FOLDER / "labels.json"
GEMINI_PREFIX = "gemini/"
PER_PILLAR = 2 # checklist items sampled from each pillar, per document
TOLERANCE = 0.17 # two graded answers within half a grade count as the same
def build(seed: int = 7) -> list[dict[str, Any]]:
"""Twenty-odd questions over the saved documents, labels left for a person."""
bundle = load_provider(get_settings().CLOUD_PROVIDER)
chooser = random.Random(seed)
items: list[dict[str, Any]] = []
for document in sorted(FOLDER.glob("*.md")):
for pillar, skill in bundle.pillar_skills.items():
checklist = checklist_items(bundle.skills[skill].path / "SKILL.md")
for item in chooser.sample(checklist, min(PER_PILLAR, len(checklist))):
items.append(
{
"id": f"{document.stem}.{pillar}.{len(items)}",
"document": document.name,
"kind": "yes_no",
"text": f"Do the recommendations address this {pillar} "
"checklist item, either by recommending it or by "
f"explaining why it does not apply? {item}",
"label": None,
}
)
for key, text in QUALITY_RUBRIC.items():
items.append(
{
"id": f"{document.stem}.quality.{key}",
"document": document.name,
"kind": "graded",
"text": text,
"label": None,
}
)
return items
def same(a: float, b: float) -> bool:
return abs(a - b) <= TOLERANCE
def share(pairs: Sequence[tuple[float, float]]) -> float | None:
return round(sum(same(a, b) for a, b in pairs) / len(pairs), 2) if pairs else None
async def ask(
judge: Judge, items: Sequence[Mapping[str, Any]], runs: int
) -> dict[str, list[float]]:
"""Every question's answers, one per run, by question id."""
answers: dict[str, list[float]] = {item["id"]: [] for item in items}
documents = sorted({item["document"] for item in items})
for _ in range(runs):
for name in documents:
asked = {
item["id"]: {"kind": item["kind"], "text": item["text"]}
for item in items
if item["document"] == name
}
try:
scores = await judge.answer(
(FOLDER / name).read_text(encoding="utf-8"), asked
)
except JudgeUnavailable:
continue
for key, value in scores.items():
if key in answers:
answers[key].append(float(value))
return answers
def report(
items: Sequence[Mapping[str, Any]], by_judge: Mapping[str, dict[str, list[float]]]
) -> dict[str, Any]:
labelled = {i["id"]: float(i["label"]) for i in items if i["label"] is not None}
result: dict[str, Any] = {
"questions": len(items),
"labelled": len(labelled),
"judges": {},
}
for name, answers in by_judge.items():
first = {key: values[0] for key, values in answers.items() if values}
result["judges"][name] = {
"answered": len(first),
# Same answer on every run, per question.
"stability": share(
[
(values[0], other)
for values in answers.values()
for other in values[1:]
]
),
"agreement_with_labels": share(
[(first[key], label) for key, label in labelled.items() if key in first]
),
"mean_answer": round(sum(first.values()) / len(first), 2)
if first
else None,
}
names = list(by_judge)
if len(names) == 2:
a, b = (by_judge[name] for name in names)
result["between_judges"] = share(
[(a[key][0], b[key][0]) for key in a if a[key] and b.get(key)]
)
return result
async def main(arguments: Sequence[str]) -> int:
if "--build" in arguments:
items = build()
LABELS.write_text(json.dumps(items, indent=2, ensure_ascii=False) + "\n")
print(f"Wrote {len(items)} questions to {LABELS}; fill in each `label`.")
return 0
runs = int(arguments[arguments.index("--runs") + 1]) if "--runs" in arguments else 3
items = json.loads(LABELS.read_text(encoding="utf-8"))
settings = get_settings()
model = load_provider(settings.CLOUD_PROVIDER).models.default
by_judge: dict[str, dict[str, list[float]]] = {
"jev": {item["id"]: [] for item in items},
"gemini": {item["id"]: [] for item in items},
}
for _ in range(runs):
# A new Jev client for each run: the client caches identical requests, and a
# cached answer would make stability look perfect whatever the service does.
decider = open_decider(settings)
judges: dict[str, Judge] = {
"jev": DeciderJudge(decider, scope="judge-calibration"),
"gemini": GeminiJudge(model.removeprefix(GEMINI_PREFIX)),
}
try:
for name, judge in judges.items():
for key, values in (await ask(judge, items, 1)).items():
by_judge[name][key] += values
finally:
aclose = getattr(decider, "aclose", None)
if aclose:
await aclose()
result = {"runs": runs, **report(items, by_judge)}
(FOLDER / "calibration.json").write_text(json.dumps(result, indent=2) + "\n")
print(json.dumps(result, indent=2))
return 0
if __name__ == "__main__":
sys.exit(asyncio.run(main(sys.argv[1:])))

View File

@@ -0,0 +1,20 @@
{
"runs": 3,
"questions": 32,
"labelled": 0,
"judges": {
"jev": {
"answered": 32,
"stability": 1.0,
"agreement_with_labels": null,
"mean_answer": 0.37
},
"gemini": {
"answered": 32,
"stability": 0.92,
"agreement_with_labels": null,
"mean_answer": 0.32
}
},
"between_judges": 0.91
}

View File

@@ -0,0 +1,44 @@
# Design Recommendations
This document outlines the architectural configurations and best practices applied to the components of the high-scale data ingestion pipeline. These recommendations integrate the functional and non-functional requirements (NFRs) with guidance from the Google Cloud Well-Architected Framework pillar advisors to ensure a secure, reliable, cost-optimized, and high-performing system.
## Security, privacy, and compliance
To protect the ingestion endpoint from volumetric DDoS attacks and Layer 7 exploits, a Global External Application Load Balancer with Google Cloud Armor is deployed. This fulfills the requirement for strict perimeter isolation while serving the 10,000 RPS traffic over TLS 1.2+ (**DR-1**).
The architecture implements a zero-trust model where all internal pipeline components (Cloud Run, Pub/Sub, Cloud Storage, BigQuery) communicate privately via VPC Service Controls and direct VPC egress (**DR-3**). All processes run under dedicated, least-privilege IAM service accounts, tightly binding permissions to only the required resources (**DR-4**). To meet regulatory data protection mandates and ensure cryptographic sovereignty, all persistent data across the Pub/Sub staging buffer, Cloud Storage sink, and BigQuery quarantine store is encrypted with Customer-Managed Encryption Keys (CMEK) (**DR-2**).
## Reliability
Reliability is anchored on minimizing data loss (RPO 0) and avoiding systemic failures under heavy load. The ingestion endpoint mitigates the risk of cold-start latency spikes by maintaining a minimum instance baseline, allowing it to sustainably absorb traffic bursts without violating the 200ms p95 latency target (**DR-5**).
Within the asynchronous pipeline, downstream processing degradation is isolated from ingestion. The Pub/Sub validation subscription utilizes a dead-letter policy with bounded delivery attempts (5 retries) to redirect unparseable poison-pill messages to BigQuery, preventing queue head-of-line blocking (**DR-6**). Additionally, the valid record storage sink leverages multi-region replication and object versioning to guarantee data durability even during a regional outage or accidental deletion event (**DR-7**). Finally, the Cloud Run services utilize explicit startup and liveness probes to ensure traffic is only routed to healthy, fully-initialized containers (**DR-8**).
## Operational excellence
A foundational principle of operational excellence is reproducible, reviewable, and automated changes. Every pipeline component—from IAM bindings to Pub/Sub schemas and serverless runtimes—is defined declaratively as Infrastructure as Code (Terraform) (**DR-9**). This declarative approach acts as the primary recovery mechanism to satisfy the RTO < 60 minutes disaster recovery objective.
## Cost optimization
Cost optimizations prioritize scaling tightly with business demand. Both the Ingestion and Validation Cloud Run services are configured to allocate CPU only during request processing, meaning they incur zero compute costs when idle, perfectly matching the strict scale-to-zero requirement (**DR-10**).
Storage costs are minimized through aggressive lifecycle management. The Pub/Sub buffer retains messages only for a shortened 48-hour window, as RPO=0 durability is fulfilled by the downstream sinks (**DR-11**). The Cloud Storage bucket transitions older validated batches to Nearline storage after 30 days (**DR-12**), and the BigQuery dead-letter quarantine datasets enforce a 30-day automated partition expiration to prevent unbound storage accumulation of malformed payloads (**DR-13**).
## Performance efficiency
To sustain the 10,000 RPS throughput requirement with sub-second latencies, the pipeline leverages advanced serverless execution features. Both Cloud Run services use Execution Environment Gen 2 and Startup CPU Boost to optimize network packet processing and eliminate initialization drag (**DR-14**). The Ingestion service's concurrency is explicitly tuned to handle high parallel request volumes (e.g., 80 concurrent requests per instance), preventing excessive container scale-out thrashing (**DR-15**).
Between the buffer and the processing tier, the Validation Engine relies on a Pub/Sub push subscription to immediately invoke the validation containers, minimizing pull polling overhead and reducing end-to-end event latency (**DR-16**).
## Sustainability
To minimize the workload's carbon footprint, all services are provisioned together within a Google Cloud region boasting a high Carbon-Free Energy (CFE) score (e.g., `europe-west1` or `us-central1`) (**DR-17**).
Energy waste is further curtailed by enforcing schema compliance at the initial Pub/Sub buffer boundary, dropping malformed payloads early and preventing wasted validation compute cycles (**DR-19**). Lastly, the Quarantine Replay Processor is architected as an on-demand Cloud Run Job rather than an always-on polling consumer, aligning energy expenditure directly to actual remediation activity (**DR-18**).
## Assumptions
As this design was produced in pre-approved mode, the following assumptions were made:
- **Cloud Region Selection**: We assume the selection of a specific region (like `europe-west1` or `us-central1`) will balance the multi-zone availability requirements with the high CFE targets for sustainability.
- **Micro-batching**: We assume the Validation Engine service includes internal micro-batching logic to aggregate records before writing to Cloud Storage, avoiding excessive single-object API calls that could degrade performance.
- **Trace Sampling & Logging**: Observability costs will be governed by sampling Cloud Trace ingestion and filtering out routine Cloud Run health check (`/healthz`) logs out-of-band via standard project sinks.

View File

@@ -0,0 +1,56 @@
# Design Recommendations
## Assumptions
Since `pre_approved` is `true`, the following assumptions govern these design recommendations:
- The workload is deployed regionally in a low-carbon region (a region with CFE% >= 75%) to meet sustainability goals.
- Cloud SQL for PostgreSQL is configured in a high-availability (multi-zone) topology to meet the 99.9% uptime requirement, avoiding cross-region replication.
- Cloud Run handles the compute scaling, scaling down to 0 instances outside of business hours to optimize costs.
- The Corporate Identity Provider integrates with Identity-Aware Proxy (IAP) to authenticate users at the load balancer.
- All application and operational logs are stored in a centralized Google Cloud Storage bucket locked for 365 days.
## Security, privacy, and compliance
To enforce a zero-trust model and meet security, privacy, and compliance requirements, the architecture implements several layers of defense:
- **Identity-Aware Proxy (IAP)**: Protects the Cloud Run service by authenticating corporate users at the external load balancer before traffic reaches the application (DR-2).
- **Network Security**: The Load Balancer enforces a custom SSL policy restricting traffic to TLS 1.2+ (DR-1). The Cloud Run service itself restricts ingress to `internal-and-cloud-load-balancing` so it cannot be accessed directly via the public internet (DR-3). Outbound traffic from Cloud Run is routed strictly through the VPC using Direct VPC Egress (DR-4).
- **Least Privilege and Secrets**: Cloud Run operates using a dedicated, user-managed service account (DR-5) with permissions limited to accessing necessary secrets from Secret Manager (DR-8) and connecting to the database. These secrets are injected dynamically into the runtime environment (DR-9).
- **Database Security**: Cloud SQL is isolated from the public internet by disabling public IPv4 and connecting via Private Service Connect/VPC peering (DR-6). It enforces IAM authentication and SSL/TLS connections (DR-7).
- **Compliance Logging**: To meet the 365-day immutable audit log requirement, a Cloud Logging sink routes all audit events to a dedicated Cloud Storage bucket configured with a 365-day retention policy (DR-10).
## Reliability
High availability and disaster recovery are essential to meeting the 99.9% uptime and RTO/RPO requirements:
- **High Availability**: Cloud SQL for PostgreSQL is configured for regional high availability, maintaining a synchronous standby replica in a secondary zone to allow automatic failover during a disruption (DR-11).
- **Disaster Recovery**: Automated daily backups are retained for at least 7 days, and Point-in-Time Recovery (PITR) is enabled via Write-Ahead Logging (WAL) to guarantee an RPO of 1 hour or less (DR-12).
- **Health Checking**: The load balancer utilizes backend health checks to continuously monitor the health of the Cloud Run instances, routing traffic away from degraded containers (DR-13).
## Operational excellence
Operations are streamlined through comprehensive observability and automated alerting:
- **Monitoring and Alerting**: Cloud Monitoring captures metrics across all components. Alert policies are specifically configured to trigger when Cloud Run HTTP 5xx error rates exceed 1% over a 5-minute window, and when Cloud SQL CPU or storage utilization exceeds 80% (DR-16).
- **Centralized Logs**: All system metrics, application logs, and traces are centralized within Google Cloud's operations suite for rapid incident response.
## Cost optimization
The architecture leverages serverless characteristics to align cloud spend with active business usage:
- **Scale to Zero**: Cloud Run is configured with a minimum instance count of 0, ensuring that compute resources scale down entirely during off-hours, weekends, and periods of inactivity, drastically reducing idle costs (DR-14).
- **Right-sized Database**: While high availability is required, autoscaling storage ensures that database disk space is only paid for when consumed.
## Performance efficiency
Sub-second page loads and transactional consistency are maintained through optimized storage and networking:
- **Database Performance**: Cloud SQL is provisioned with high-throughput SSD storage and automatic storage expansion to maintain low-latency read/write operations for booking transactions without hitting IOPS ceilings (DR-15).
- **Connection Optimization**: By using VPC-native private connections and keeping all traffic within the same region, network latency between Cloud Run and Cloud SQL is minimized.
## Sustainability
Environmental impact is mitigated by selecting the right region and eliminating idle resource waste:
- **Low-Carbon Region**: All resources are deployed in a region with a Carbon-Free Energy (CFE) score of 75% or higher, directly lowering the gross carbon emissions of the workload (DR-17).
- **Dynamic Scaling**: Utilizing Cloud Run's scale-to-zero capabilities (DR-14) ensures that the application does not consume power for idle compute instances outside of business hours.

View File

@@ -0,0 +1,226 @@
[
{
"id": "case-02-design-recommendations.security.0",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Shift-left security: Are automated security scans integrated into the CI/CD pipeline?",
"label": null
},
{
"id": "case-02-design-recommendations.security.1",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Zero trust: Is Cloud Identity used as a centralized identity provider for managing user lifecycles and federation?",
"label": null
},
{
"id": "case-02-design-recommendations.reliability.2",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? Game days or chaos engineering practices are regularly held to validate failure recovery.",
"label": null
},
{
"id": "case-02-design-recommendations.reliability.3",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? The system architecture incorporates patterns like circuit breakers, retries with exponential backoff, and rate limiting to support graceful degradation.",
"label": null
},
{
"id": "case-02-design-recommendations.operational-excellence.4",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Operational readiness: A formal framework or set of criteria exists to assess operational readiness before production deployment.",
"label": null
},
{
"id": "case-02-design-recommendations.operational-excellence.5",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Culture of improvement: A documented strategy is in place for regularly reviewing and adapting cloud operations to industry advancements.",
"label": null
},
{
"id": "case-02-design-recommendations.cost-optimization.6",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Network Egress: Data transfer is minimized by keeping traffic regional, using **Cloud CDN**, and leveraging **Standard Network Tier** where appropriate. High-volume on-premises traffic uses **Direct Peering** or **Cloud Interconnect** (always verify if hybrid connectivity is involved).",
"label": null
},
{
"id": "case-02-design-recommendations.cost-optimization.7",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Granular Visibility: BigQuery billing export is enabled and used for regular cost reviews.",
"label": null
},
{
"id": "case-02-design-recommendations.performance-optimization.8",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Monitoring and continuous improvement: Automated dashboards and alerts are configured for key performance indicators (KPIs).",
"label": null
},
{
"id": "case-02-design-recommendations.performance-optimization.9",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Elasticity: The architecture leverages serverless or managed services to dynamically match capacity to load.",
"label": null
},
{
"id": "case-02-design-recommendations.sustainability.10",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Cloud sustainability: AI is used as a catalyst for profitability and resilience to streamline operations, or sustainability is integrated into the design process to create positive feedback loops.",
"label": null
},
{
"id": "case-02-design-recommendations.sustainability.11",
"document": "case-02-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Continuously measure and improve: Applications are instrumented to measure the specific carbon intensity of software features, or automated exports of Carbon Footprint data to BigQuery are configured for deep analysis.",
"label": null
},
{
"id": "case-02-design-recommendations.quality.specific",
"document": "case-02-design-recommendations.md",
"kind": "graded",
"text": "Are the recommendations specific to this workload and its stated requirements, as opposed to generic best practice that would fit any workload?",
"label": null
},
{
"id": "case-02-design-recommendations.quality.actionable",
"document": "case-02-design-recommendations.md",
"kind": "graded",
"text": "Does each recommendation name the concrete setting, feature or configuration to apply, so an engineer could act on it without more research?",
"label": null
},
{
"id": "case-02-design-recommendations.quality.trade_offs",
"document": "case-02-design-recommendations.md",
"kind": "graded",
"text": "Where pillars pull in different directions (for example cost against reliability), is the trade-off named and a resolution recommended?",
"label": null
},
{
"id": "case-02-design-recommendations.quality.traceable",
"document": "case-02-design-recommendations.md",
"kind": "graded",
"text": "Can each recommendation be traced to a requirement or constraint of the workload?",
"label": null
},
{
"id": "case-03-design-recommendations.security.16",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Zero trust: Are private connectivity methods (Cloud Interconnect, VPN) used for internal traffic?",
"label": null
},
{
"id": "case-03-design-recommendations.security.17",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this security checklist item, either by recommending it or by explaining why it does not apply? Security by design: Is defense-in-depth implemented at the network, host, and application layers?",
"label": null
},
{
"id": "case-03-design-recommendations.reliability.18",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? The architecture avoids single points of failure through cross-zone or cross-region redundancy.",
"label": null
},
{
"id": "case-03-design-recommendations.reliability.19",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this reliability checklist item, either by recommending it or by explaining why it does not apply? Application and infrastructure health checks are configured to trigger automated failovers.",
"label": null
},
{
"id": "case-03-design-recommendations.operational-excellence.20",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Resource optimization: Resource utilization is regularly reviewed using recommendations from Active Assist or performance data.",
"label": null
},
{
"id": "case-03-design-recommendations.operational-excellence.21",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this operational-excellence checklist item, either by recommending it or by explaining why it does not apply? Operational readiness: A formal framework or set of criteria exists to assess operational readiness before production deployment.",
"label": null
},
{
"id": "case-03-design-recommendations.cost-optimization.22",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Rightsizing: Resources are regularly adjusted based on rightsizing suggestions provided by Active Assist Recommender.",
"label": null
},
{
"id": "case-03-design-recommendations.cost-optimization.23",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this cost-optimization checklist item, either by recommending it or by explaining why it does not apply? Granular Visibility: BigQuery billing export is enabled and used for regular cost reviews.",
"label": null
},
{
"id": "case-03-design-recommendations.performance-optimization.24",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Elasticity: Auto-scaling rules are configured and validated to handle variable demand.",
"label": null
},
{
"id": "case-03-design-recommendations.performance-optimization.25",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this performance-optimization checklist item, either by recommending it or by explaining why it does not apply? Monitoring and continuous improvement: Distributed tracing and profiling tools are used to identify code-level bottlenecks.",
"label": null
},
{
"id": "case-03-design-recommendations.sustainability.26",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Cloud sustainability: AI is used as a catalyst for profitability and resilience to streamline operations, or sustainability is integrated into the design process to create positive feedback loops.",
"label": null
},
{
"id": "case-03-design-recommendations.sustainability.27",
"document": "case-03-design-recommendations.md",
"kind": "yes_no",
"text": "Do the recommendations address this sustainability checklist item, either by recommending it or by explaining why it does not apply? Promote a culture of sustainability: Abstract carbon metrics are transformed into tangible progress indicators in annual reports, or sustainability is treated as a first-class technical requirement (NFR) tied to KPIs and performance reviews.",
"label": null
},
{
"id": "case-03-design-recommendations.quality.specific",
"document": "case-03-design-recommendations.md",
"kind": "graded",
"text": "Are the recommendations specific to this workload and its stated requirements, as opposed to generic best practice that would fit any workload?",
"label": null
},
{
"id": "case-03-design-recommendations.quality.actionable",
"document": "case-03-design-recommendations.md",
"kind": "graded",
"text": "Does each recommendation name the concrete setting, feature or configuration to apply, so an engineer could act on it without more research?",
"label": null
},
{
"id": "case-03-design-recommendations.quality.trade_offs",
"document": "case-03-design-recommendations.md",
"kind": "graded",
"text": "Where pillars pull in different directions (for example cost against reliability), is the trade-off named and a resolution recommended?",
"label": null
},
{
"id": "case-03-design-recommendations.quality.traceable",
"document": "case-03-design-recommendations.md",
"kind": "graded",
"text": "Can each recommendation be traced to a requirement or constraint of the workload?",
"label": null
}
]

View File

@@ -57,7 +57,12 @@
"approve|confirm|proceed|look right|any changes|happy",
"Approved. Please proceed."
]
]
],
"thresholds": {
"revisions": 2,
"seconds": 3000,
"tokens": 5000000
}
},
{
"id": "case-02-high-scale-ingestion",
@@ -121,7 +126,12 @@
"approve|confirm|proceed|look right|any changes|happy",
"Approved. Please proceed."
]
]
],
"thresholds": {
"revisions": 3,
"seconds": 3600,
"tokens": 8500000
}
},
{
"id": "case-03-internal-web-app",
@@ -193,7 +203,12 @@
"approve|confirm|proceed|look right|any changes|happy",
"Approved. Please proceed."
]
]
],
"thresholds": {
"revisions": 3,
"seconds": 3200,
"tokens": 8000000
}
},
{
"id": "case-04-interactive-web-app",
@@ -207,65 +222,89 @@
"scripted_answers": [
[
"region|location|geograph",
"A single region, europe-west1 (Belgium). All users are in the EU."
"A single region, europe-west1 (Belgium). All users are in the EU.",
"requirements"
],
[
"user|staff|employee|how many|concurren|traffic|volume|scale|peak|requests per|rps",
"About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second."
"About 4,000 employees; 300 concurrent users at the 09:00 peak, around 20 requests per second.",
"requirements"
],
[
"availability|uptime|sla|rto|rpo|disaster|recover|backup",
"99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days."
"99.5% during business hours (07:00-19:00 CET). RTO 4 hours, RPO 1 hour. Daily backups kept 14 days.",
"requirements"
],
[
"latency|response time|performance",
"Pages should load within 1 second at p95."
"Pages should load within 1 second at p95.",
"requirements"
],
[
"identity|sign.?in|login|sso|auth|idp|access",
"Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group."
"Employees sign in with Google Workspace accounts; no access from outside the company. Admins are a Google group.",
"requirements"
],
[
"security|compliance|encrypt|privacy|gdpr|secret|credential|password",
"GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days."
"GDPR applies to employee names and emails. Google-managed keys are fine. Database passwords and API keys must live in a secrets store and rotate every 90 days.",
"requirements"
],
[
"data|database|schema|relational|postgres|mysql|size|storage",
"PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history."
"PostgreSQL. Under 20 GB of data in the first three years; bookings, rooms, equipment and audit history.",
"requirements"
],
[
"cost|budget|spend",
"Under 600 EUR a month; the database can be small."
"Under 600 EUR a month; the database can be small.",
"requirements"
],
[
"current|existing|today|on-prem|migrat|legacy",
"Bookings are kept in a shared spreadsheet today; there is no data to migrate."
"Bookings are kept in a shared spreadsheet today; there is no data to migrate.",
"requirements"
],
[
"depend|integrat|calendar|email|notif|downstream|upstream",
"Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one."
"Send booking confirmation emails through the existing SMTP relay; no calendar integration in phase one.",
"requirements"
],
[
"operat|monitor|logging|alert|team|support|deploy|ci|pipeline",
"Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space."
"Two developers own it, deploy containers from Cloud Build with Terraform, and want Cloud Monitoring alerts to a Google Chat space.",
"requirements"
],
[
"network|vpc|private|internet|egress|ingress",
"No public database endpoint; the database must use private IP only."
"No public database endpoint; the database must use private IP only.",
"requirements"
],
[
"sustainab|carbon",
"No specific requirement."
"No specific requirement.",
"requirements"
],
[
"retention|audit|archive|delete",
"Keep booking history 2 years, then delete; keep audit logs 1 year."
"Keep booking history 2 years, then delete; keep audit logs 1 year.",
"requirements"
],
[
"approve|confirm|proceed|look right|any changes|happy",
"Approved. Please proceed."
],
[
".",
"Approved. Please proceed.",
"^(?!requirements$)"
]
],
"interactive": true
"interactive": true,
"thresholds": {
"revisions": 2,
"seconds": 3400,
"tokens": 7500000
}
}
]

View File

@@ -71,7 +71,7 @@ class CaseSpec:
name: str
workflow_request: str
required_products: tuple[str, ...]
scripted_answers: tuple[tuple[str, 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

View File

@@ -24,7 +24,7 @@ import os
import sys
import time
from collections import Counter
from collections.abc import Sequence
from collections.abc import Callable, Sequence
from dataclasses import asdict
from datetime import UTC, datetime
from pathlib import Path
@@ -58,8 +58,12 @@ RESULTS_DIR = ROOT / "results"
class CountingRuntime:
"""Counts agent runs and their outcomes per role, with a timeline of runs."""
def __init__(self, inner: AgentRuntime) -> None:
def __init__(
self, inner: AgentRuntime, on_run: Callable[[], None] | None = None
) -> None:
self._inner = inner
# Called after every agent run, so a run cut short leaves a record behind.
self._on_run = on_run
self._started = time.monotonic()
self.runs: Counter[str] = Counter()
self.outcomes: Counter[str] = Counter()
@@ -81,6 +85,8 @@ class CountingRuntime:
"outcome": type(outcome).__name__,
}
)
if self._on_run:
self._on_run()
return outcome
@@ -145,9 +151,30 @@ async def run_case(
skill_dirs={name: meta.path for name, meta in bundle.skills.items()},
model_timeout_seconds=settings.MODEL_TIMEOUT_SECONDS,
)
runtime = CountingRuntime(adk_runtime)
recorder = InMemoryRecorder()
started = time.monotonic()
progress_path = run_dir / f"{case.id}-progress.json"
def write_progress() -> None:
"""What the run has cost so far. Overwritten after every agent run and left
in place, so an interrupted run still has its time, tokens and timeline."""
progress_path.write_text(
json.dumps(
{
"case_id": case.id,
"finished": False,
"seconds": round(time.monotonic() - started, 1),
"agent_runs": dict(runtime.runs),
"outcomes": dict(runtime.outcomes),
"tokens": token_report(adk_runtime.usage),
"timeline": runtime.timeline,
},
indent=2,
),
encoding="utf-8",
)
runtime = CountingRuntime(adk_runtime, on_run=write_progress)
recorder = InMemoryRecorder()
async with open_assembly(
settings, runtime=runtime, recorder=recorder, output_root=run_dir
) as assembly:
@@ -166,6 +193,13 @@ async def run_case(
scripted_answers=case.scripted_answers,
)
elapsed = time.monotonic() - started
write_progress()
progress_path.write_text(
progress_path.read_text(encoding="utf-8").replace(
'"finished": false', '"finished": true', 1
),
encoding="utf-8",
)
runner = TerraformRunner(
binary=settings.TERRAFORM_BINARY,