"""A toy Workflow: planning a picnic. It is here to show that the engine needs nothing of the subject it was built from (ADR-0001). Four Deliverables in three Phases: a menu, a shopping list written from it, a check that every dish can be made from the list, and the plan that puts the three together. It has no spec, no graph and no cloud, and it uses each kind of part a Workflow can supply at least once: data checks along a chain, code that adds a view on submission, a validation that reopens the list or the menu, an account of what a Change request changed, an option a caller may set, a tool of its own, and its own facts at an Approval. """ from __future__ import annotations import json from collections.abc import Mapping, MutableMapping, Sequence from pathlib import Path from typing import Any from execution_engine.adk.runtime import ToolResult, ToolSpec from execution_engine.workflows.deliverables import DeliverableSpec, Upstream from execution_engine.workflows.workflow import ( Assembling, Bench, CardText, ChangePolicy, LocalToolBuilder, OptionSpec, ValidationPolicy, Workflow, ) ROOT = Path(__file__).parent / "root" # the toy agent's own folder PLANNING, CHECKING, PACKING = "planning", "checking", "packing" MENU, SHOPPING_LIST, CHECK, PLAN = "menu", "shopping_list", "check", "plan" MENU_FILE, SHOPPING_FILE, VERDICTS_FILE = "menu.json", "shopping.json", "verdicts.json" CHANGES_FILE = "changes.json" PLAN_FILE = "picnic-plan.md" TOTALS_HEADING = "Totals" GUESTS = "guests" def _list(text: str, name: str) -> tuple[list[dict[str, Any]], list[str]]: try: data = json.loads(text) except ValueError as exc: return [], [f"{name}: not valid JSON ({exc})"] if not isinstance(data, list) or not all(isinstance(item, dict) for item in data): return [], [f"{name}: must be a JSON list of objects"] return data, [] def dishes(deliverables: Upstream | None) -> list[dict[str, Any]]: """The dishes on the menu, from its data file; none when it is not there.""" text = ((deliverables or {}).get(MENU) or {}).get("attachments", {}).get(MENU_FILE) return _list(text, MENU_FILE)[0] if text else [] def dish_ids(deliverables: Upstream | None) -> list[str]: return [str(dish.get("id")) for dish in dishes(deliverables)] def check_menu(attachments: Mapping[str, str], upstream: Upstream | None) -> list[str]: items, problems = _list(attachments[MENU_FILE], MENU_FILE) if problems: return problems if not items: return [f"{MENU_FILE}: lists no dishes"] ids = [item.get("id") for item in items] problems += [ f"{MENU_FILE}[{index}]: needs id and name" for index, item in enumerate(items) if not item.get("id") or not item.get("name") ] problems += [ f"{MENU_FILE}: dish {dish} is listed more than once" for dish in sorted({str(i) for i in ids if i and ids.count(i) > 1}) ] return problems def check_shopping( attachments: Mapping[str, str], upstream: Upstream | None ) -> list[str]: items, problems = _list(attachments[SHOPPING_FILE], SHOPPING_FILE) if problems: return problems on_menu = dish_ids(upstream) bought_for = {str(item.get("dish")) for item in items} problems += [ f"{SHOPPING_FILE}: nothing is bought for dish {dish}" for dish in on_menu if dish not in bought_for ] if upstream is not None: problems += [ f"{SHOPPING_FILE}: dish {dish} is not on the menu" for dish in sorted(bought_for - set(on_menu)) ] return problems def check_verdicts( attachments: Mapping[str, str], upstream: Upstream | None ) -> list[str]: try: data = json.loads(attachments[VERDICTS_FILE]) except ValueError as exc: return [f"{VERDICTS_FILE}: not valid JSON ({exc})"] given = { str(item.get("check")) for item in (data.get("checks") or [] if isinstance(data, dict) else []) if isinstance(item, dict) } return [ f"{VERDICTS_FILE}: dish {dish} has no verdict" for dish in dish_ids(upstream) if dish not in given ] def with_totals( bench: Bench, content: str, attachments: dict[str, str] ) -> tuple[str, dict[str, str]]: """How much is bought, counted from the list: it cannot disagree with it.""" items, _ = _list(attachments[SHOPPING_FILE], SHOPPING_FILE) content = content.split(f"\n## {TOTALS_HEADING}")[0].rstrip() content += ( f"\n\n## {TOTALS_HEADING}\n\n{len(items)} items for " f"{len(dish_ids(bench.upstream))} dishes.\n" ) return content, attachments def change_summary(before: Upstream | None, after: Upstream) -> dict[str, Any]: was, now = set(dish_ids(before)), set(dish_ids(after)) return {"added": sorted(now - was), "removed": sorted(was - now)} def changes_in_words(summary: Mapping[str, Any]) -> str: return "\n".join( [f"Dish {dish} was added." for dish in summary["added"]] + [f"Dish {dish} was removed." for dish in summary["removed"]] ) def approval_facts(phase: str, deliverables: Upstream) -> dict[str, Any]: return {"dishes": len(dishes(deliverables))} def summary_lines(phase: str, facts: Mapping[str, Any]) -> list[str]: return [f"{facts['dishes']} dishes on the menu."] def task_entries( state: Mapping[str, Any], kind: str ) -> tuple[dict[str, Any], dict[str, Any]]: # How many people the picnic is for: every Specialist is told. return {}, {GUESTS: (state.get("options") or {}).get(GUESTS)} def outputs( state: Mapping[str, Any], deliverables: Upstream, files: dict[str, str] ) -> dict[str, Any]: return {"dishes": dish_ids(deliverables)} def _guests(value: Any) -> str | None: if isinstance(value, bool) or not isinstance(value, int) or value < 1: return "guests must be a whole number of people, at least 1" return None def local_tools(given: Assembling) -> LocalToolBuilder: """`tally`: how many items the working copy of the shopping list holds.""" def build(working_copy: MutableMapping[str, str] | None) -> Sequence[ToolSpec]: async def tally() -> ToolResult: text = (working_copy or {}).get(SHOPPING_FILE, "[]") return ToolResult(f"{len(_list(text, SHOPPING_FILE)[0])} items so far.") return [ ToolSpec( "tally", "Count the items on the shopping list so far.", {"type": "object", "properties": {}}, tally, ) ] return build SAMPLES = { MENU_FILE: json.dumps( [{"id": "D-1", "name": "Sandwiches"}, {"id": "D-2", "name": "Lemonade"}] ), SHOPPING_FILE: json.dumps( [ {"dish": "D-1", "item": "bread", "quantity": 2}, {"dish": "D-1", "item": "cheese", "quantity": 1}, {"dish": "D-2", "item": "lemons", "quantity": 6}, ] ), VERDICTS_FILE: json.dumps( { "dry_run": {"verdict": "pass", "evidence": "Everything fits the basket."}, "checks": [ {"check": "D-1", "verdict": "pass", "evidence": "Bread and cheese."}, {"check": "D-2", "verdict": "pass", "evidence": "Six lemons."}, ], "proposed_additions": [], } ), } TOY = Workflow( name="picnic", about="I plan picnics: a menu, a shopping list and a check of one against the other.", phases=(PLANNING, CHECKING, PACKING), deliverables={ spec.kind: spec for spec in ( DeliverableSpec( MENU, PLANNING, "menu-writer", sections=("Dishes",), attachments=(MENU_FILE,), ), DeliverableSpec( SHOPPING_LIST, PLANNING, "shopper", depends_on=(MENU,), sections=("What to buy",), attachments=(SHOPPING_FILE,), # The list is built up in a working copy, a few lines at a time. working_copy=SHOPPING_LIST, ), DeliverableSpec( CHECK, CHECKING, "checker", depends_on=(SHOPPING_LIST,), sections=("Findings",), attachments=(VERDICTS_FILE,), ), DeliverableSpec( PLAN, PACKING, "packer", depends_on=(CHECK,), sections=("The plan",), # The plan is assembled from every Deliverable's prose. reads_in_full=(MENU, SHOPPING_LIST, CHECK), ), ) }, final=PLAN, final_file=PLAN_FILE, data_checks={ MENU: (MENU_FILE, check_menu), SHOPPING_LIST: (SHOPPING_FILE, check_shopping), CHECK: (VERDICTS_FILE, check_verdicts), }, for_readers={SHOPPING_LIST: TOTALS_HEADING}, validation=ValidationPolicy( kind=CHECK, data_file=VERDICTS_FILE, implementation=SHOPPING_LIST, design=MENU, check_ids=dish_ids, known_ids=lambda deliverables: set(dish_ids(deliverables)), ), on_submit={SHOPPING_LIST: with_totals}, approval_facts=approval_facts, summary_lines=summary_lines, agreed=lambda deliverables: json.dumps(dishes(deliverables)), changes=ChangePolicy( file=CHANGES_FILE, summary=change_summary, is_empty=lambda summary: not (summary["added"] or summary["removed"]), in_words=changes_in_words, ), subject="a picnic plan", task_entries=task_entries, outputs=outputs, options={GUESTS: OptionSpec(default=4, check=_guests)}, local_tools=local_tools, card=CardText( description="Plans a picnic with you: a menu, a shopping list and a check.", skill_id="picnic", skill_name="Picnic planning", tags=("picnic",), examples=("Plan a picnic for six in the park.",), ), done="The picnic is planned.", samples=SAMPLES, )