302 lines
9.9 KiB
Python
302 lines
9.9 KiB
Python
"""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,
|
|
)
|