"""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.", ), )