feat: working orhcestration engine
This commit is contained in:
1
execution_engine/workflows/__init__.py
Normal file
1
execution_engine/workflows/__init__.py
Normal file
@@ -0,0 +1 @@
|
||||
"""The Execution graph and the dependency graph of Deliverables it runs."""
|
||||
152
execution_engine/workflows/deliverables.py
Normal file
152
execution_engine/workflows/deliverables.py
Normal file
@@ -0,0 +1,152 @@
|
||||
"""What a Workflow says about one Deliverable, and what follows from a graph of them.
|
||||
|
||||
The engine declares no Phase and no Deliverable. A Workflow does (ADR-0001), and
|
||||
these functions read whatever graph it gives. Kinds and Phase ids are strings; a
|
||||
Workflow may write them as a StrEnum of its own.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from collections.abc import Callable, Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from typing import Any
|
||||
|
||||
# The Deliverables a submission builds on, by kind: {kind: {content, attachments}}.
|
||||
Upstream = Mapping[str, Mapping[str, Any]]
|
||||
# What is wrong with a data file, one entry per fault; empty when nothing is.
|
||||
DataCheck = Callable[[Mapping[str, str], Upstream | None], list[str]]
|
||||
# The same, for a Change request: the attachments against the Baseline's version.
|
||||
BaselineCheck = Callable[[Mapping[str, str], Mapping[str, object]], list[str]]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ListShape:
|
||||
"""One list of a working graph: what each of its items must and may hold."""
|
||||
|
||||
required: tuple[str, ...]
|
||||
optional: tuple[str, ...] = ()
|
||||
key: str = "id" # the field that identifies an item
|
||||
# How the list is named when the graph's size is reported; None leaves it out.
|
||||
label: str | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class GraphShape:
|
||||
"""A Deliverable that is a graph: built a few items at a time, attached as one file."""
|
||||
|
||||
attachment: str
|
||||
lists: Mapping[str, ListShape]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class DeliverableSpec:
|
||||
kind: str
|
||||
phase: str
|
||||
specialist: str
|
||||
depends_on: tuple[str, ...] = ()
|
||||
sections: tuple[str, ...] = ()
|
||||
attachments: tuple[str, ...] = ()
|
||||
# Which earlier Deliverables the Specialist reads whole. None means the ones it
|
||||
# depends on. Every other input arrives as its data file alone: the ids the
|
||||
# chain runs through, without the prose written around them.
|
||||
reads_in_full: tuple[str, ...] | None = None
|
||||
# The Deliverable whose files this Specialist's tools work on. Its own kind: the
|
||||
# files are its working copy, kept across attempts and attached on submission.
|
||||
# Another kind: a fresh copy of that Deliverable's files on every attempt.
|
||||
working_copy: str | None = None
|
||||
# What the Deliverable is written from, as one comparable value. When a Revision
|
||||
# upstream leaves that value as it was, the last submission still stands and the
|
||||
# Specialist is not run again.
|
||||
written_from: Callable[[Upstream | None], str | None] | None = None
|
||||
# Earlier Deliverables this Specialist is not shown. They are still held for
|
||||
# the checks its submission is put through, and it can read any of them on
|
||||
# request. What a Specialist is given at the start is sent again with every
|
||||
# request it makes, so what it does not use is paid for many times over.
|
||||
not_shown: tuple[str, ...] = ()
|
||||
# Set when the Deliverable's data file is a graph the Specialist builds in its
|
||||
# working copy; the engine then gives it the tools to do so.
|
||||
graph: GraphShape | None = None
|
||||
|
||||
def contract(self) -> dict[str, list[str]]:
|
||||
"""What a submission must contain, as plain data for the Specialist's context."""
|
||||
return {
|
||||
"sections": list(self.sections),
|
||||
"attachments": list(self.attachments),
|
||||
}
|
||||
|
||||
|
||||
Graph = Mapping[str, DeliverableSpec]
|
||||
|
||||
|
||||
def deliverables_in(graph: Graph, phase: str) -> tuple[str, ...]:
|
||||
return tuple(kind for kind, spec in graph.items() if spec.phase == phase)
|
||||
|
||||
|
||||
def inputs_of(graph: Graph, phases: Sequence[str], kind: str) -> tuple[str, ...]:
|
||||
"""The Deliverables a Specialist works from, in graph order.
|
||||
|
||||
Every Deliverable in an earlier Phase (all approved by the time `kind` is ready),
|
||||
plus everything `kind` depends on, directly or not, within its own Phase.
|
||||
"""
|
||||
spec = graph[kind]
|
||||
earlier_phases = phases[: list(phases).index(spec.phase)]
|
||||
upstream: set[str] = set()
|
||||
frontier = set(spec.depends_on)
|
||||
while frontier:
|
||||
upstream |= frontier
|
||||
frontier = {
|
||||
dependency for item in frontier for dependency in graph[item].depends_on
|
||||
} - upstream
|
||||
return tuple(
|
||||
candidate
|
||||
for candidate, candidate_spec in graph.items()
|
||||
if candidate in upstream or candidate_spec.phase in earlier_phases
|
||||
)
|
||||
|
||||
|
||||
def dependents_of(graph: Graph, kind: str) -> tuple[str, ...]:
|
||||
"""Every Deliverable that depends on `kind`, directly or not, in graph order."""
|
||||
dependents: set[str] = set()
|
||||
frontier = {kind}
|
||||
while frontier:
|
||||
frontier = {
|
||||
candidate
|
||||
for candidate, spec in graph.items()
|
||||
if candidate not in dependents and frontier & set(spec.depends_on)
|
||||
}
|
||||
dependents |= frontier
|
||||
return tuple(candidate for candidate in graph if candidate in dependents)
|
||||
|
||||
|
||||
_HEADING = re.compile(r"^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$", re.MULTILINE)
|
||||
_NUMBERING = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
|
||||
_TRAILING = re.compile(r"[\s:.\-–—]+$")
|
||||
|
||||
|
||||
def _normalise(text: str) -> str:
|
||||
text = _NUMBERING.sub("", text.strip().lower())
|
||||
return " ".join(_TRAILING.sub("", text).split())
|
||||
|
||||
|
||||
def missing_from(
|
||||
spec: DeliverableSpec, content: str, attachments: Mapping[str, str]
|
||||
) -> list[str]:
|
||||
"""The sections and attachments of its contract a submission lacks.
|
||||
|
||||
A section matches a heading by suffix, so a template that numbers and prefixes
|
||||
its headings ("4.1. Google Cloud products and features mapping") still matches
|
||||
the section a Workflow names ("Products and features mapping").
|
||||
"""
|
||||
headings = [_normalise(match) for match in _HEADING.findall(content)]
|
||||
missing = []
|
||||
for section in spec.sections:
|
||||
required = _normalise(section)
|
||||
if not any(h == required or h.endswith(" " + required) for h in headings):
|
||||
missing.append(f"section: {section}")
|
||||
for name in spec.attachments:
|
||||
if name not in attachments:
|
||||
missing.append(f"attachment: {name}")
|
||||
elif not attachments[name].strip():
|
||||
missing.append(f"attachment: {name} must not be empty")
|
||||
return missing
|
||||
94
execution_engine/workflows/execution_graph.py
Normal file
94
execution_engine/workflows/execution_graph.py
Normal file
@@ -0,0 +1,94 @@
|
||||
"""The LangGraph that holds an Execution (ADR-0003).
|
||||
|
||||
START -> orchestrator_turn
|
||||
orchestrator_turn -> specialist_task x N (Send, parallel) -> orchestrator_turn
|
||||
orchestrator_turn -> await_user (interrupt) -> orchestrator_turn
|
||||
orchestrator_turn -> finalize -> END
|
||||
orchestrator_turn -> end_with_warnings -> END
|
||||
|
||||
The nodes live in app/nodes/execution_nodes.py; they route with Command and Send, so
|
||||
only the fixed edges are declared here.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Mapping
|
||||
from pathlib import Path
|
||||
from typing import Any, cast
|
||||
|
||||
from langgraph.graph import END, START, StateGraph
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
Decider,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
SubmissionReview,
|
||||
ToolFactory,
|
||||
)
|
||||
from execution_engine.nodes.execution_nodes import make_execution_nodes
|
||||
from execution_engine.nodes.router import OrchestratorPolicy
|
||||
from execution_engine.recorder import ExecutionRecorder
|
||||
from execution_engine.states.execution_state import ExecutionState
|
||||
from execution_engine.tools.scoping import Scoping
|
||||
from execution_engine.workflows.workflow import Workflow
|
||||
|
||||
|
||||
def build_execution_graph(
|
||||
*,
|
||||
workflow: Workflow,
|
||||
runtime: AgentRuntime,
|
||||
roles: Mapping[str, RoleSpec],
|
||||
recorder: ExecutionRecorder,
|
||||
output_root: Path,
|
||||
max_orchestrator_turns: int = 100,
|
||||
tool_factory: ToolFactory | None = None,
|
||||
limiter: RunLimiter | None = None,
|
||||
skill_versions: Mapping[str, str] | None = None,
|
||||
orchestrator: OrchestratorPolicy | None = None,
|
||||
submission_review: SubmissionReview | None = None,
|
||||
confirm_drafts: bool = False,
|
||||
decider: Decider | None = None,
|
||||
reworded_threshold: float = 0.25,
|
||||
guard_user_text: bool = False,
|
||||
guard_threshold: float = 0.75,
|
||||
skill_references: Mapping[str, Mapping[str, Mapping[str, str]]] | None = None,
|
||||
skill_threshold: float = 1.25,
|
||||
assess_at_end: bool = False,
|
||||
scoping: Scoping | None = None,
|
||||
) -> StateGraph:
|
||||
nodes = make_execution_nodes(
|
||||
workflow=workflow,
|
||||
runtime=runtime,
|
||||
roles=roles,
|
||||
recorder=recorder,
|
||||
output_root=output_root,
|
||||
max_orchestrator_turns=max_orchestrator_turns,
|
||||
tool_factory=tool_factory,
|
||||
limiter=limiter,
|
||||
skill_versions=skill_versions,
|
||||
orchestrator=orchestrator,
|
||||
submission_review=submission_review,
|
||||
confirm_drafts=confirm_drafts,
|
||||
decider=decider,
|
||||
reworded_threshold=reworded_threshold,
|
||||
guard_user_text=guard_user_text,
|
||||
guard_threshold=guard_threshold,
|
||||
skill_references=skill_references,
|
||||
skill_threshold=skill_threshold,
|
||||
assess_at_end=assess_at_end,
|
||||
scoping=scoping,
|
||||
)
|
||||
|
||||
graph = StateGraph(ExecutionState)
|
||||
graph.add_node("orchestrator_turn", cast(Any, nodes.orchestrator_turn))
|
||||
# Specialist tasks receive their Send payload, not the Execution state.
|
||||
graph.add_node("specialist_task", cast(Any, nodes.specialist_task))
|
||||
graph.add_node("await_user", cast(Any, nodes.await_user))
|
||||
graph.add_node("finalize", cast(Any, nodes.finalize))
|
||||
graph.add_node("end_with_warnings", cast(Any, nodes.end_with_warnings))
|
||||
graph.add_edge(START, "orchestrator_turn")
|
||||
graph.add_edge("specialist_task", "orchestrator_turn")
|
||||
graph.add_edge("finalize", END)
|
||||
graph.add_edge("end_with_warnings", END)
|
||||
return graph
|
||||
535
execution_engine/workflows/workflow.py
Normal file
535
execution_engine/workflows/workflow.py
Normal file
@@ -0,0 +1,535 @@
|
||||
"""The Workflow: everything about a subject, as one value (ADR-0001).
|
||||
|
||||
An agent is the Execution engine and one Workflow. The engine names no Deliverable,
|
||||
no Phase and no subject; it reads them from the Workflow it was assembled with.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import dataclasses
|
||||
import json
|
||||
from collections.abc import Awaitable, Callable, Mapping, MutableMapping, Sequence
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
Decider,
|
||||
RoleSpec,
|
||||
RunLimiter,
|
||||
SubmissionReview,
|
||||
ToolSpec,
|
||||
)
|
||||
from execution_engine.workflows.deliverables import (
|
||||
BaselineCheck,
|
||||
DataCheck,
|
||||
DeliverableSpec,
|
||||
Upstream,
|
||||
deliverables_in,
|
||||
dependents_of,
|
||||
inputs_of,
|
||||
missing_from,
|
||||
)
|
||||
|
||||
|
||||
class WorkflowError(ValueError):
|
||||
"""A Workflow that does not hold together; the message says where."""
|
||||
|
||||
|
||||
def validation_outcome(verdicts_text: str) -> dict[str, Any]:
|
||||
"""What a validation decided, from its data file.
|
||||
|
||||
The file gives a verdict on each Check, an overall run of whatever the Workflow
|
||||
runs (`dry_run`), and anything the validator proposes adding. A failed Check is
|
||||
a fault in what was validated. A Check that could not be verified and a proposed
|
||||
addition are gaps in the design it was validated against.
|
||||
"""
|
||||
try:
|
||||
data = json.loads(verdicts_text)
|
||||
except ValueError:
|
||||
data = {}
|
||||
if not isinstance(data, dict):
|
||||
data = {}
|
||||
checks = [item for item in data.get("checks", []) if isinstance(item, dict)]
|
||||
|
||||
def with_verdict(verdict: str) -> list[dict[str, Any]]:
|
||||
return [
|
||||
{"check": item.get("check"), "evidence": item.get("evidence")}
|
||||
for item in checks
|
||||
if item.get("verdict") == verdict
|
||||
]
|
||||
|
||||
dry_run = data.get("dry_run") if isinstance(data.get("dry_run"), dict) else {}
|
||||
return {
|
||||
"dry_run": dry_run,
|
||||
"passed": [
|
||||
item.get("check") for item in checks if item.get("verdict") == "pass"
|
||||
],
|
||||
"failed": with_verdict("fail"),
|
||||
"not_verifiable": with_verdict("not_verifiable"),
|
||||
"proposed_additions": [
|
||||
item
|
||||
for item in data.get("proposed_additions", [])
|
||||
if isinstance(item, dict)
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ValidationPolicy:
|
||||
"""Which Deliverable is validation, and what its result reopens."""
|
||||
|
||||
kind: str # the validation Deliverable
|
||||
data_file: str # its verdicts, read by `read`
|
||||
implementation: str # reopened when a Check fails
|
||||
design: str # reopened when a Check fails twice running, or a gap matters
|
||||
read: Callable[[str], dict[str, Any]] = validation_outcome
|
||||
# The ids of the Checks a validation must give a verdict on, from what it
|
||||
# builds on. Without it the validator is not told how many are left.
|
||||
check_ids: Callable[[Upstream | None], Sequence[str]] | None = None
|
||||
# Checks the implementation's author reported cannot be met as the design
|
||||
# words them, from the Deliverables: [{check, reason}]. They reopen the design.
|
||||
unimplementable: Callable[[Upstream], list[dict[str, str]]] | None = None
|
||||
# The ids a proposed addition may name as what it serves. An addition that
|
||||
# names one is a gap worth a Revision when nothing judges it.
|
||||
known_ids: Callable[[Upstream], set[str]] | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Digested:
|
||||
"""A spec read by code from the sources a caller supplied."""
|
||||
|
||||
spec: Mapping[str, Any] # the spec's fields, nested as a spec file is
|
||||
used: tuple[str, ...] = () # the sources it was read from, by name
|
||||
# What is said of a field in the completed spec: where it was read from.
|
||||
notes: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CardText:
|
||||
"""How an agent describes itself on its A2A card."""
|
||||
|
||||
description: str
|
||||
skill_id: str
|
||||
skill_name: str
|
||||
tags: tuple[str, ...] = ()
|
||||
examples: tuple[str, ...] = ()
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class OptionSpec:
|
||||
"""A choice a caller may make for one Execution, beyond what every Execution has.
|
||||
|
||||
Left unset, a Change request does as its Baseline did, and any other Execution
|
||||
takes `default`.
|
||||
"""
|
||||
|
||||
default: Any = None
|
||||
# The field of the spec that states it, such as "run.terraform_modules".
|
||||
spec_field: str | None = None
|
||||
# Why a value is refused, or None when it is allowed.
|
||||
check: Callable[[Any], str | None] | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Assembling:
|
||||
"""What an agent has been assembled from, for a Workflow to build its own parts."""
|
||||
|
||||
settings: Any
|
||||
bundle: Any # the provider bundle
|
||||
runtime: AgentRuntime
|
||||
roles: Mapping[str, RoleSpec]
|
||||
decider: Decider
|
||||
|
||||
|
||||
# The local tools, built on a working copy of files when the Deliverable has one.
|
||||
LocalToolBuilder = Callable[[MutableMapping[str, str] | None], Sequence[ToolSpec]]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ChangePolicy:
|
||||
"""What a Change request changed against its Baseline, worked out from the two
|
||||
versions' data files and never written by an agent."""
|
||||
|
||||
file: str # where the account is written, among the Execution's files
|
||||
# (the Baseline's Deliverables, this Execution's) -> what was added, changed
|
||||
# and removed.
|
||||
summary: Callable[[Upstream | None, Upstream], dict[str, Any]]
|
||||
is_empty: Callable[[Mapping[str, Any]], bool]
|
||||
# The summary's changes to what the customer asked for, in words: what a
|
||||
# Specialist started on a Change request is told its task is.
|
||||
in_words: Callable[[Mapping[str, Any]], str]
|
||||
# Tells a rewording from a change where a decision is available:
|
||||
# (decider, summary, before, after, unchanged_at, scope) -> the summary.
|
||||
settle: Callable[..., Awaitable[dict[str, Any]]] | None = None
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Hints:
|
||||
"""What a Workflow is given to judge what the Specialists being started need."""
|
||||
|
||||
state: Mapping[str, Any] # the Execution's state
|
||||
feedback: Mapping[str, Sequence[str]] # kind -> why it was revised
|
||||
deliverables: Upstream
|
||||
started: Mapping[str, int] # kind -> attempt
|
||||
decider: Decider | None
|
||||
changed: str # in a Change request, what changed, in words
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Bench:
|
||||
"""What a Workflow's own code is given when a Deliverable is submitted."""
|
||||
|
||||
kind: str
|
||||
working: MutableMapping[str, Any] # the Deliverable's working memory
|
||||
upstream: Upstream | None # the Deliverables it builds on
|
||||
baseline: Mapping[str, Any] | None # its Baseline version, in a Change request
|
||||
|
||||
|
||||
# Adds to an accepted submission what code writes from it: a view of its data that
|
||||
# must not be able to disagree with it. Returns the content and the attachments.
|
||||
SubmitHook = Callable[[Bench, str, dict[str, str]], tuple[str, dict[str, str]]]
|
||||
|
||||
# What an Approval shows beyond the Phase's summary: (phase, the Deliverables
|
||||
# submitted so far, the Baseline in a Change request) -> entries for the prompt.
|
||||
ApprovalDetails = Callable[
|
||||
[str, Mapping[str, Mapping[str, Any]], Mapping[str, Any] | None], dict[str, Any]
|
||||
]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class RoleTools:
|
||||
"""What a Workflow needs to give a role tools of its own, such as consulting
|
||||
further agents on one Deliverable."""
|
||||
|
||||
runtime: AgentRuntime
|
||||
roles: Mapping[str, RoleSpec]
|
||||
role: RoleSpec
|
||||
deliverable: str | None
|
||||
working: MutableMapping[str, Any]
|
||||
limiter: RunLimiter | None
|
||||
# A role's tools from the remote MCP servers its bundle assigns it, checked for
|
||||
# instructions addressed to the agent.
|
||||
mcp_tools: Callable[[RoleSpec], list[ToolSpec]]
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Workflow:
|
||||
name: str
|
||||
# What a caller is told this agent does, when a message starts nothing.
|
||||
about: str
|
||||
phases: tuple[str, ...]
|
||||
deliverables: Mapping[str, DeliverableSpec]
|
||||
# The Deliverable handed over as the result. It is assembled from every other
|
||||
# Deliverable, so it is shown the sections written for readers.
|
||||
final: str
|
||||
# What each data file along the chain must hold, checked at submission:
|
||||
# kind -> (the data file, its check).
|
||||
data_checks: Mapping[str, tuple[str, DataCheck]] = field(default_factory=dict)
|
||||
# In a Change request, the account of what changed: kind -> (file, check).
|
||||
baseline_checks: Mapping[str, tuple[str, BaselineCheck]] = field(
|
||||
default_factory=dict
|
||||
)
|
||||
# Sections code appends to a Deliverable for the person reading it. A Specialist
|
||||
# working from that Deliverable has the same facts as data, and is not shown them.
|
||||
for_readers: Mapping[str, str] = field(default_factory=dict)
|
||||
# The Deliverable that holds the agreed spec. It is in every Specialist's
|
||||
# context as data, so it is not shown again as a dependency.
|
||||
spec_deliverable: str | None = None
|
||||
validation: ValidationPolicy | None = None
|
||||
# What code adds to an accepted submission, by kind.
|
||||
on_submit: Mapping[str, SubmitHook] = field(default_factory=dict)
|
||||
approval_details: ApprovalDetails | None = None
|
||||
# Facts of this Workflow's own that an Approval summary is written from:
|
||||
# (phase, the Deliverables) -> facts. Data, never Deliverable prose.
|
||||
approval_facts: Callable[[str, Upstream], dict[str, Any]] | None = None
|
||||
# How those facts read when no writer is available: (phase, facts) -> sentences.
|
||||
summary_lines: Callable[[str, Mapping[str, Any]], Sequence[str]] | None = None
|
||||
# What is agreed so far, as text: shown to the decider beside a user's message,
|
||||
# so a message that restates it is not read as a change.
|
||||
agreed: Callable[[Upstream], str] | None = None
|
||||
changes: ChangePolicy | None = None
|
||||
# What the work is, to finish the sentence "the x Deliverable of ...".
|
||||
subject: str = "this work"
|
||||
# The design so far in a few lines, for judging which of a Skill's references
|
||||
# a task needs. "" when there is none yet.
|
||||
describe_design: Callable[[Upstream], str] | None = None
|
||||
# A role as one Execution runs it: (role, the Specialist's task input) -> role.
|
||||
prepare_role: Callable[[RoleSpec, Mapping[str, Any]], RoleSpec] | None = None
|
||||
# Entries of this Workflow's own in a Specialist's task: (state, kind) -> the
|
||||
# task input's entries and its context's.
|
||||
task_entries: (
|
||||
Callable[[Mapping[str, Any], str], tuple[dict[str, Any], dict[str, Any]]] | None
|
||||
) = None
|
||||
# Context for the Specialists being started that needs a judgement:
|
||||
# kind -> entries for its context.
|
||||
task_hints: Callable[[Hints], Awaitable[Mapping[str, Mapping[str, Any]]]] | None = (
|
||||
None
|
||||
)
|
||||
# Working memory kept with a completed Execution, for a Change request to start
|
||||
# from: the keys kept, of each Deliverable's working memory.
|
||||
kept_for_changes: tuple[str, ...] = ()
|
||||
# The file the final Deliverable is also written as, at the top of an
|
||||
# Execution's folder.
|
||||
final_file: str = "result.md"
|
||||
# What this Workflow adds when an Execution's files are written. It is given
|
||||
# the state, the Deliverables and the files so far, which it may add to or
|
||||
# amend, and returns its entries for the manifest.
|
||||
outputs: (
|
||||
Callable[[Mapping[str, Any], Upstream, dict[str, str]], dict[str, Any]] | None
|
||||
) = None
|
||||
# Reads a spec from sources of a kind this Workflow knows, such as another
|
||||
# agent's files: {name: content} -> the spec. It raises ValueError, naming what
|
||||
# is wrong, when the sources are of that kind and cannot be read. A source it
|
||||
# does not use is given to the Specialist that completes the spec, to read.
|
||||
digest: Callable[[Mapping[str, str]], Digested] | None = None
|
||||
card: CardText | None = None
|
||||
# What a caller is told when an Execution completes.
|
||||
done: str = "The work is complete and approved."
|
||||
# What an Approval's own details say, in the text a user reads: the entries
|
||||
# `approval_details` added -> a paragraph, ending in a blank line, or "".
|
||||
describe_approval: Callable[[Mapping[str, Any]], str] | None = None
|
||||
# The reply to a one-shot request, when it is not the engine's:
|
||||
# (the Interaction, the roles) -> the response body.
|
||||
response: Callable[[Any, Mapping[str, RoleSpec]], dict[str, Any]] | None = None
|
||||
# Choices a caller may make for one Execution, by name.
|
||||
options: Mapping[str, OptionSpec] = field(default_factory=dict)
|
||||
# The tools that run on the agent's own machine, for the roles whose files name
|
||||
# them; and what looks at a submission's meaning before it is accepted.
|
||||
local_tools: Callable[[Assembling], LocalToolBuilder] | None = None
|
||||
reviews: Callable[[Assembling], SubmissionReview | None] | None = None
|
||||
# A judgement of the finished work, kept in the Execution's record:
|
||||
# (decider, deliverables, scope) -> the record's entry.
|
||||
assess: Callable[..., Awaitable[dict[str, Any] | None]] | None = None
|
||||
# Tools a role is given beyond its role file's and its bundle's.
|
||||
role_tools: Callable[[RoleTools], Sequence[ToolSpec]] | None = None
|
||||
# Roles this Workflow needs beyond the engine's own and one per Deliverable,
|
||||
# and roles it can use when their file is present.
|
||||
roles: tuple[str, ...] = ()
|
||||
optional_roles: tuple[str, ...] = ()
|
||||
# A last change to the loaded roles from the provider bundle, such as giving
|
||||
# a Skill to every role that has a certain tool: (roles, bundle) -> roles.
|
||||
adjust_roles: (
|
||||
Callable[[Mapping[str, RoleSpec], Any], Mapping[str, RoleSpec]] | None
|
||||
) = None
|
||||
# A passing attachment by file name, for the scripted runtime's sample
|
||||
# submissions. A file with no sample is given a placeholder.
|
||||
samples: Mapping[str, str] = field(default_factory=dict)
|
||||
|
||||
def __post_init__(self) -> None:
|
||||
self._plain_names()
|
||||
problems = []
|
||||
if len(set(self.phases)) != len(self.phases):
|
||||
problems.append("a Phase is listed twice")
|
||||
specialists: dict[str, str] = {}
|
||||
for kind, spec in self.deliverables.items():
|
||||
if spec.kind != kind:
|
||||
problems.append(f"{kind}: its spec is for {spec.kind}")
|
||||
if spec.phase not in self.phases:
|
||||
problems.append(f"{kind}: Phase {spec.phase} is not listed")
|
||||
named = (
|
||||
*spec.depends_on,
|
||||
*(spec.reads_in_full or ()),
|
||||
*spec.not_shown,
|
||||
*((spec.working_copy,) if spec.working_copy else ()),
|
||||
)
|
||||
for other in named:
|
||||
if other not in self.deliverables:
|
||||
problems.append(f"{kind}: names unknown Deliverable {other}")
|
||||
if spec.specialist in specialists:
|
||||
problems.append(
|
||||
f"{kind}: {spec.specialist} already produces "
|
||||
f"{specialists[spec.specialist]}"
|
||||
)
|
||||
specialists[spec.specialist] = kind
|
||||
for phase in self.phases:
|
||||
if not deliverables_in(self.deliverables, phase):
|
||||
problems.append(f"Phase {phase} has no Deliverable")
|
||||
for kind, spec in self.deliverables.items():
|
||||
for dependency in spec.depends_on:
|
||||
other = self.deliverables.get(dependency)
|
||||
if other and self.phases.index(other.phase) > self.phases.index(
|
||||
spec.phase
|
||||
):
|
||||
problems.append(
|
||||
f"{kind}: depends on {dependency}, in a later Phase"
|
||||
)
|
||||
if self.final not in self.deliverables:
|
||||
problems.append(f"final Deliverable {self.final} is not declared")
|
||||
named_kinds = [
|
||||
*self.data_checks,
|
||||
*self.baseline_checks,
|
||||
*self.for_readers,
|
||||
*self.on_submit,
|
||||
]
|
||||
if self.spec_deliverable:
|
||||
named_kinds.append(self.spec_deliverable)
|
||||
if self.validation:
|
||||
policy = self.validation
|
||||
named_kinds += [policy.kind, policy.implementation, policy.design]
|
||||
for kind in named_kinds:
|
||||
if kind not in self.deliverables:
|
||||
problems.append(f"names unknown Deliverable {kind}")
|
||||
if problems:
|
||||
raise WorkflowError(f"Workflow {self.name}: " + "; ".join(problems))
|
||||
|
||||
def _plain_names(self) -> None:
|
||||
"""Hold every kind and Phase as a plain string.
|
||||
|
||||
A Workflow may declare them as members of a StrEnum. They go into an
|
||||
Execution's checkpointed state, which is plain data, so the engine keeps
|
||||
the strings and never the members.
|
||||
"""
|
||||
|
||||
def names(values: tuple[Any, ...] | None) -> tuple[str, ...] | None:
|
||||
return None if values is None else tuple(str(value) for value in values)
|
||||
|
||||
def keys(mapping: Mapping[Any, Any]) -> dict[str, Any]:
|
||||
return {str(key): value for key, value in mapping.items()}
|
||||
|
||||
graph = {
|
||||
str(kind): dataclasses.replace(
|
||||
spec,
|
||||
kind=str(spec.kind),
|
||||
phase=str(spec.phase),
|
||||
depends_on=names(spec.depends_on) or (),
|
||||
reads_in_full=names(spec.reads_in_full),
|
||||
not_shown=names(spec.not_shown) or (),
|
||||
working_copy=None
|
||||
if spec.working_copy is None
|
||||
else str(spec.working_copy),
|
||||
)
|
||||
for kind, spec in self.deliverables.items()
|
||||
}
|
||||
plain: dict[str, Any] = {
|
||||
"phases": names(self.phases),
|
||||
"deliverables": graph,
|
||||
"final": str(self.final),
|
||||
"data_checks": keys(self.data_checks),
|
||||
"baseline_checks": keys(self.baseline_checks),
|
||||
"for_readers": keys(self.for_readers),
|
||||
"on_submit": keys(self.on_submit),
|
||||
"spec_deliverable": None
|
||||
if self.spec_deliverable is None
|
||||
else str(self.spec_deliverable),
|
||||
}
|
||||
if self.validation:
|
||||
policy = self.validation
|
||||
plain["validation"] = dataclasses.replace(
|
||||
policy,
|
||||
kind=str(policy.kind),
|
||||
implementation=str(policy.implementation),
|
||||
design=str(policy.design),
|
||||
)
|
||||
for name, value in plain.items():
|
||||
object.__setattr__(self, name, value)
|
||||
|
||||
# --- names -------------------------------------------------------------------
|
||||
|
||||
def kind(self, value: object) -> str:
|
||||
"""`value` as one of this Workflow's Deliverable kinds; ValueError otherwise."""
|
||||
if not isinstance(value, str) or value not in self.deliverables:
|
||||
raise ValueError(f"{value!r} is not a Deliverable of {self.name}")
|
||||
return str(value)
|
||||
|
||||
def phase(self, value: object) -> str:
|
||||
"""`value` as one of this Workflow's Phases; ValueError otherwise."""
|
||||
if not isinstance(value, str) or value not in self.phases:
|
||||
raise ValueError(f"{value!r} is not a Phase of {self.name}")
|
||||
return str(value)
|
||||
|
||||
def specialists(self) -> dict[str, str]:
|
||||
"""The role that produces each Deliverable: {role: kind}."""
|
||||
return {spec.specialist: kind for kind, spec in self.deliverables.items()}
|
||||
|
||||
# --- the graph ---------------------------------------------------------------
|
||||
|
||||
def deliverables_in(self, phase: str) -> tuple[str, ...]:
|
||||
return deliverables_in(self.deliverables, phase)
|
||||
|
||||
def inputs_of(self, kind: str) -> tuple[str, ...]:
|
||||
return inputs_of(self.deliverables, self.phases, kind)
|
||||
|
||||
def dependents_of(self, kind: str) -> tuple[str, ...]:
|
||||
return dependents_of(self.deliverables, kind)
|
||||
|
||||
def dependencies_for(
|
||||
self, kind: str, deliverables: Mapping[str, Mapping[str, object]]
|
||||
) -> dict[str, dict[str, object]]:
|
||||
"""What a Specialist is given of each Deliverable it works from.
|
||||
|
||||
A Deliverable read in full arrives as submitted. Any other arrives as its data
|
||||
file alone, which is all the chain needs of it.
|
||||
"""
|
||||
spec = self.deliverables[kind]
|
||||
in_full = spec.depends_on if spec.reads_in_full is None else spec.reads_in_full
|
||||
given: dict[str, dict[str, object]] = {}
|
||||
for dependency in self.inputs_of(kind):
|
||||
deliverable = deliverables[dependency]
|
||||
if dependency in in_full or dependency not in self.data_checks:
|
||||
given[dependency] = dict(deliverable)
|
||||
continue
|
||||
name = self.data_checks[dependency][0]
|
||||
attachments = deliverable.get("attachments")
|
||||
files = attachments if isinstance(attachments, Mapping) else {}
|
||||
given[dependency] = {
|
||||
"attachments": {name: files[name]} if name in files else {}
|
||||
}
|
||||
return given
|
||||
|
||||
def shown(
|
||||
self, kind: str, given: Mapping[str, Mapping[str, object]]
|
||||
) -> dict[str, dict[str, object]]:
|
||||
"""What of `given` a Specialist is shown. Nothing it uses is left out.
|
||||
|
||||
- A Deliverable its spec lists under `not_shown` is omitted.
|
||||
- The agreed spec is in every Specialist's context as data, so it is not
|
||||
shown again as a dependency; a Specialist that reads it whole sees its prose.
|
||||
- A section written for a reader is left off, except for the final
|
||||
Deliverable, which assembles the document those sections belong in.
|
||||
"""
|
||||
spec = self.deliverables[kind]
|
||||
view: dict[str, dict[str, object]] = {}
|
||||
for name, deliverable in given.items():
|
||||
if name in spec.not_shown:
|
||||
continue
|
||||
entry = dict(deliverable)
|
||||
if name == self.spec_deliverable:
|
||||
if name not in (*spec.depends_on, *(spec.reads_in_full or ())):
|
||||
continue
|
||||
entry = {"content": entry.get("content", "")}
|
||||
heading = self.for_readers.get(name)
|
||||
content = entry.get("content")
|
||||
if heading and isinstance(content, str) and kind != self.final:
|
||||
entry["content"] = content.split(f"\n## {heading}")[0].rstrip() + "\n"
|
||||
view[name] = entry
|
||||
return view
|
||||
|
||||
def check_submission(
|
||||
self,
|
||||
kind: str,
|
||||
content: str,
|
||||
attachments: Mapping[str, str],
|
||||
upstream: Upstream | None = None,
|
||||
baseline: Mapping[str, object] | None = None,
|
||||
) -> tuple[str, ...]:
|
||||
"""Return what a submission lacks against its contract; empty means it's complete.
|
||||
|
||||
`upstream` is the Deliverables this one builds on, by kind. With it, the links
|
||||
along the chain are checked too. `baseline` is the Baseline's version of this
|
||||
Deliverable in a Change request; with it, the account of what changed is
|
||||
checked.
|
||||
"""
|
||||
if not content.strip():
|
||||
return ("content: must not be empty",)
|
||||
|
||||
missing = missing_from(self.deliverables[kind], content, attachments)
|
||||
if kind in self.data_checks:
|
||||
name, check = self.data_checks[kind]
|
||||
if attachments.get(name, "").strip():
|
||||
missing.extend(check(attachments, upstream))
|
||||
if baseline is not None and kind in self.baseline_checks and not missing:
|
||||
name, compare = self.baseline_checks[kind]
|
||||
if attachments.get(name, "").strip():
|
||||
missing.extend(compare(attachments, baseline))
|
||||
return tuple(missing)
|
||||
Reference in New Issue
Block a user