Files
orchestration_engine/tests/toy/workflow.py

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