Files
gcp_solution_architecture_a…/app/nodes/execution_nodes.py
Jonathan Boniface 7ee49ab352
Some checks failed
validation / verify (push) Failing after 10s
latest refactoring
2026-10-06 20:22:37 +01:00

561 lines
21 KiB
Python

"""The nodes of the Execution graph (ADR-0003); app/workflows/execution_graph.py wires them.
Only orchestrator_turn and await_user change the Ledger; parallel Specialist tasks
append outcomes that the next Orchestrator turn applies in order.
"""
from __future__ import annotations
import logging
import re
import time
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass
from pathlib import Path
from typing import Any
from langgraph.types import Command, Send, interrupt
from app.adk.runtime import (
AgentRuntime,
AgentTask,
BudgetExhausted,
NeedsInput,
Outcome,
RoleSpec,
Stopped,
Submitted,
ToolFactory,
ToolSpec,
TurnEnded,
)
from app.recorder import ExecutionRecorder
from app.states.execution_state import ExecutionState
from app.states.ledger import Ledger, LedgerRefusal
from app.tools.execution import ORCHESTRATOR, OrchestratorToolbox, specialist_tools
from app.workflows.deliverables import (
DEPENDENCY_GRAPH,
PHASE_ORDER,
DeliverableKind,
inputs_of,
)
logger = logging.getLogger(__name__)
NO_USER_REPLY = (
"No user is available. State your assumption, record it in the Deliverable under "
"'Assumptions', and proceed."
)
GUIDE_FILENAME = "solution-architecture-guide.md"
def _no_tools(role: RoleSpec, deliverable: str | None) -> Sequence[ToolSpec]:
return ()
@dataclass(frozen=True)
class ExecutionNodes:
"""The node functions of one Execution graph, bound to its runtime and recorder."""
orchestrator_turn: Callable[[ExecutionState], Awaitable[Command]]
# Receives its Send payload, not the Execution state.
specialist_task: Callable[[dict[str, Any]], Awaitable[dict[str, Any]]]
await_user: Callable[[ExecutionState], Awaitable[Command]]
finalize: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
end_with_warnings: Callable[[ExecutionState], Awaitable[dict[str, Any]]]
def make_execution_nodes(
*,
runtime: AgentRuntime,
roles: Mapping[str, RoleSpec],
recorder: ExecutionRecorder,
output_root: Path,
max_orchestrator_turns: int = 100,
tool_factory: ToolFactory | None = None,
) -> ExecutionNodes:
tool_factory = tool_factory or _no_tools
async def record_progress(
state: ExecutionState, ledger: Ledger, status: str | None = None
) -> int:
recorded = state.get("events_recorded", 0)
for event in ledger.events[recorded:]:
logger.info(
"[%s] ledger %s %s by %s%s",
state["execution_id"],
event.type,
event.subject,
event.actor,
f" ({event.detail})" if event.detail else "",
)
await recorder.record_events(state["execution_id"], ledger.events[recorded:])
if status:
await recorder.record_status(
state["execution_id"],
session_id=state["session_id"],
workflow_request=state["workflow_request"],
status=status,
current_phase=_current_phase(ledger),
details={
"revisions": sum(
ledger.revisions(kind) for kind in DEPENDENCY_GRAPH
),
"warnings": state.get("warnings", []),
},
)
return len(ledger.events)
async def orchestrator_turn(state: ExecutionState) -> Command:
ledger = Ledger.from_dict(state["ledger"])
deliverables = dict(state.get("deliverables", {}))
pending_questions = list(state.get("pending_questions", []))
notes = list(state.get("notes", []))
pending_permission = state.get("pending_permission")
warnings = list(state.get("warnings", []))
outcomes = state.get("outcomes", [])
for record in outcomes[state.get("outcomes_applied", 0) :]:
kind = DeliverableKind(record["kind"])
try:
if record["type"] == "submitted":
ledger.submit(kind, record["attempt"], actor=record["role"])
deliverables[kind.value] = {
"content": record["content"],
"attachments": record["attachments"],
}
await recorder.record_submission(
state["execution_id"],
kind.value,
record["content"],
record["attachments"],
)
continue
ledger.release(kind, record["attempt"], reason=record["type"])
except LedgerRefusal as exc:
notes.append(f"Discarded a superseded result for {kind}: {exc}")
continue
if record["type"] == "needs_input" and record.get("permission"):
if state.get("allow_cloud_read") is None:
requested = (pending_permission or {}).get("requested_by", [])
pending_permission = {
"tier": record["permission"],
"requested_by": [*requested, kind.value],
}
continue
questions = record.get("questions") or [
(
f"The {record['role']} stopped: {record['summary']} "
"How should it proceed?"
)
]
pending_questions.append({"kind": kind.value, "questions": questions})
turns = state.get("turns", 0) + 1
update: dict[str, Any] = {
"deliverables": deliverables,
"pending_questions": pending_questions,
"pending_permission": pending_permission,
"outcomes_applied": len(outcomes),
"turns": turns,
}
def finish_with(goto: str, **extra: Any) -> Command:
return Command(
update={**update, "ledger": ledger.to_dict(), "notes": notes, **extra},
goto=goto,
)
if pending_permission and not state.get("pre_approved"):
update["events_recorded"] = await record_progress(
state, ledger, "awaiting_user"
)
return finish_with("await_user", prompt={"permission": pending_permission})
if turns > max_orchestrator_turns:
warnings.append(
f"Stopped after {max_orchestrator_turns} Orchestrator turns without "
"finishing."
)
return finish_with("end_with_warnings", warnings=warnings)
toolbox = OrchestratorToolbox(ledger, deliverables, pending_questions)
task = AgentTask(
role=ORCHESTRATOR,
prompt="Decide the next step for this Execution using your tools.",
context=_orchestrator_context(state, ledger, pending_questions, notes),
)
started = time.monotonic()
outcome = await runtime.run(roles[ORCHESTRATOR], task, toolbox.tools())
logger.info(
"[%s] orchestrator turn %d (%s phase) ended in %.0fs: %s",
state["execution_id"],
turns,
_current_phase(ledger),
time.monotonic() - started,
_summarise_outcome(outcome),
)
notes = []
pre_approved = bool(state.get("pre_approved"))
conversation = list(state.get("conversation", []))
def ask(prompt: dict[str, Any], **extra: Any) -> Command:
conversation.append({"from": ORCHESTRATOR, "text": _render_prompt(prompt)})
return finish_with(
"await_user", prompt=prompt, conversation=conversation, **extra
)
if isinstance(outcome, TurnEnded) and outcome.tool == "delegate":
sends = [
Send(
"specialist_task",
_specialist_input(state, ledger, deliverables, kind, attempt),
)
for kind, attempt in toolbox.started.items()
]
update["events_recorded"] = await record_progress(state, ledger)
return Command(
update={**update, "ledger": ledger.to_dict(), "notes": notes},
goto=sends,
)
if isinstance(outcome, TurnEnded) and outcome.tool == "finish":
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("finalize")
if isinstance(outcome, TurnEnded) and outcome.tool == "escalate":
warnings.append(toolbox.escalation or "Escalated without detail.")
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("end_with_warnings", warnings=warnings)
if isinstance(outcome, TurnEnded) and outcome.tool == "request_approval":
update["events_recorded"] = await record_progress(
state, ledger, None if pre_approved else "awaiting_user"
)
return ask({"approval": toolbox.approval})
if isinstance(outcome, TurnEnded) and outcome.tool == "ask_user":
update["events_recorded"] = await record_progress(
state, ledger, None if pre_approved else "awaiting_user"
)
return ask(
{"questions": toolbox.questions},
pending_questions=[],
awaiting_questions=pending_questions,
)
message = _describe_unfinished(outcome)
if pre_approved:
warnings.append(f"The Orchestrator could not continue: {message}")
update["events_recorded"] = await record_progress(state, ledger)
return finish_with("end_with_warnings", warnings=warnings)
update["events_recorded"] = await record_progress(
state, ledger, "awaiting_user"
)
return ask({"questions": [{"from": ORCHESTRATOR, "question": message}]})
async def specialist_task(task_input: dict[str, Any]) -> dict[str, Any]:
role = roles[task_input["role"]]
kind = DeliverableKind(task_input["kind"])
tools = specialist_tools(
kind,
extra=tool_factory(role, kind.value),
allow_cloud_read=task_input["allow_cloud_read"],
)
task = AgentTask(
role=role.name,
prompt=f"Produce the {kind} Deliverable.",
context=task_input["context"],
deliverable=kind.value,
)
logger.info(
"[%s] %s started %s (attempt %d)",
task_input["execution_id"],
role.name,
kind,
task_input["attempt"],
)
started = time.monotonic()
try:
outcome: Outcome = await runtime.run(role, task, tools)
except Exception as exc:
logger.exception("Specialist %s failed on %s", role.name, kind)
outcome = Stopped(f"it failed with {type(exc).__name__}: {exc}")
logger.info(
"[%s] %s finished %s in %.0fs: %s",
task_input["execution_id"],
role.name,
kind,
time.monotonic() - started,
_summarise_outcome(outcome),
)
return {
"outcomes": [
_outcome_record(role.name, kind, task_input["attempt"], outcome)
]
}
async def await_user(state: ExecutionState) -> Command:
prompt = state["prompt"] or {}
if state.get("pre_approved"):
reply = _automatic_reply(prompt, state.get("scripted_answers", []))
else:
reply = interrupt(prompt)
ledger = Ledger.from_dict(state["ledger"])
conversation = list(state.get("conversation", []))
update: dict[str, Any] = {"prompt": None}
if "approval" in prompt:
phase = prompt["approval"]["phase"]
decision = reply.get("approval") if isinstance(reply, Mapping) else None
if (
isinstance(decision, Mapping)
and decision.get("phase") == phase
and decision.get("decision") in {"approve", "changes"}
):
phase_id = next(p for p in PHASE_ORDER if p.value == phase)
if decision["decision"] == "approve":
ledger.approve(phase_id, actor="user")
text = f"Approved {phase}."
else:
feedback = str(decision.get("feedback", ""))
ledger.request_changes(phase_id, feedback, actor="user")
text = f"Requested changes to {phase}: {feedback}"
conversation.append({"from": "user", "text": text})
else:
conversation.append({"from": "user", "text": _reply_text(reply)})
elif "permission" in prompt:
tier = prompt["permission"]["tier"]
permission = reply.get("permission") if isinstance(reply, Mapping) else None
grant = permission.get(tier) if isinstance(permission, Mapping) else None
if isinstance(grant, bool):
update["allow_cloud_read"] = grant
update["pending_permission"] = None
verdict = "granted" if grant else "denied"
conversation.append(
{
"from": "user",
"text": f"Permission to use {tier} tools {verdict}.",
}
)
else:
conversation.append({"from": "user", "text": _reply_text(reply)})
else:
text = _reply_text(reply)
conversation.append({"from": "user", "text": text})
answers = {
kind: list(items) for kind, items in state.get("answers", {}).items()
}
for asked in state.get("awaiting_questions", []):
answers.setdefault(asked["kind"], []).append(
{"questions": list(asked["questions"]), "reply": text}
)
update.update(answers=answers, awaiting_questions=[])
update["events_recorded"] = await record_progress(state, ledger)
update.update(ledger=ledger.to_dict(), conversation=conversation)
return Command(update=update, goto="orchestrator_turn")
async def finalize(state: ExecutionState) -> dict[str, Any]:
ledger = Ledger.from_dict(state["ledger"])
_write_outputs(
output_root / "deliverables" / "executions" / state["execution_id"],
state.get("deliverables", {}),
)
await record_progress(state, ledger, "completed")
return {"status": "completed"}
async def end_with_warnings(state: ExecutionState) -> dict[str, Any]:
ledger = Ledger.from_dict(state["ledger"])
await record_progress(state, ledger, "completed_with_warnings")
return {"status": "completed_with_warnings"}
return ExecutionNodes(
orchestrator_turn=orchestrator_turn,
specialist_task=specialist_task,
await_user=await_user,
finalize=finalize,
end_with_warnings=end_with_warnings,
)
# --- helpers ---------------------------------------------------------------------------
def _summarise_outcome(outcome: Outcome) -> str:
if isinstance(outcome, TurnEnded):
return f"called {outcome.tool}"
if isinstance(outcome, Submitted):
return f"submitted ({len(outcome.content)} chars)"
if isinstance(outcome, NeedsInput):
return f"needs input ({len(outcome.questions)} questions)"
if isinstance(outcome, BudgetExhausted):
return f"budget exhausted: {outcome.summary[:200]}"
return f"stopped: {outcome.message[:200]}"
def _current_phase(ledger: Ledger) -> str:
for phase in PHASE_ORDER:
if ledger.phase_status(phase).value != "approved":
return phase.value
return PHASE_ORDER[-1].value
def _orchestrator_context(
state: ExecutionState,
ledger: Ledger,
pending_questions: Sequence[Mapping[str, Any]],
notes: Sequence[str],
) -> dict[str, Any]:
return {
"workflow_request": state["workflow_request"],
"pre_approved": bool(state.get("pre_approved")),
"allow_cloud_read": state.get("allow_cloud_read"),
"deliverables": {
kind.value: {
"phase": spec.phase.value,
"status": ledger.status(kind).value,
"revisions": ledger.revisions(kind),
"feedback": list(ledger.feedback(kind)),
}
for kind, spec in DEPENDENCY_GRAPH.items()
},
"phases": {
phase.value: ledger.phase_status(phase).value for phase in PHASE_ORDER
},
"ready_work": [kind.value for kind in ledger.ready_work()],
"phases_ready_for_approval": [
p.value for p in ledger.phases_ready_for_approval()
],
"pending_questions": list(pending_questions),
"conversation": list(state.get("conversation", []))[-20:],
"notes": list(notes),
}
def _specialist_input(
state: ExecutionState,
ledger: Ledger,
deliverables: Mapping[str, Mapping[str, Any]],
kind: DeliverableKind,
attempt: int,
) -> dict[str, Any]:
spec = DEPENDENCY_GRAPH[kind]
return {
"execution_id": state["execution_id"],
"role": spec.specialist,
"kind": kind.value,
"attempt": attempt,
"allow_cloud_read": state.get("allow_cloud_read"),
"context": {
"workflow_request": state["workflow_request"],
"pre_approved": bool(state.get("pre_approved")),
"dependencies": {
dependency.value: dict(deliverables[dependency.value])
for dependency in inputs_of(kind)
},
"feedback": list(ledger.feedback(kind)),
"answers": list(state.get("answers", {}).get(kind.value, [])),
"attempt": attempt,
},
}
def _outcome_record(
role: str, kind: DeliverableKind, attempt: int, outcome: Outcome
) -> dict[str, Any]:
base = {"role": role, "kind": kind.value, "attempt": attempt}
if isinstance(outcome, Submitted):
return {
**base,
"type": "submitted",
"content": outcome.content,
"attachments": dict(outcome.attachments),
}
if isinstance(outcome, NeedsInput):
return {
**base,
"type": "needs_input",
"questions": list(outcome.questions),
"permission": outcome.permission,
}
if isinstance(outcome, BudgetExhausted):
return {**base, "type": "budget_exhausted", "summary": outcome.summary}
return {**base, "type": "stopped", "summary": _describe_unfinished(outcome)}
def _describe_unfinished(outcome: Outcome) -> str:
if isinstance(outcome, BudgetExhausted):
return f"I paused: {outcome.summary} How should I proceed?"
if isinstance(outcome, Stopped):
return outcome.message
if isinstance(outcome, NeedsInput):
return " ".join(outcome.questions)
return f"Ended with an unexpected outcome: {type(outcome).__name__}."
def _automatic_reply(
prompt: Mapping[str, Any], scripted_answers: Sequence[Sequence[str]] = ()
) -> dict[str, Any]:
"""The reply in a pre-approved Execution: approve, deny cloud reads, and answer
questions from scripted (pattern, answer) pairs where one matches."""
if "approval" in prompt:
return {
"approval": {"phase": prompt["approval"]["phase"], "decision": "approve"}
}
if "permission" in prompt:
return {"permission": {prompt["permission"]["tier"]: False}}
lines = []
unanswered = False
for item in prompt.get("questions", []):
answer = next(
(
scripted
for pattern, scripted in scripted_answers
if re.search(pattern, item["question"], re.IGNORECASE)
),
None,
)
if answer is None:
unanswered = True
else:
lines.append(f"Q: {item['question']}\nA: {answer}")
if unanswered or not lines:
lines.append(NO_USER_REPLY)
return {"reply": "\n\n".join(lines)}
def _reply_text(reply: object) -> str:
if isinstance(reply, str):
return reply
if isinstance(reply, Mapping) and isinstance(reply.get("reply"), str):
return reply["reply"]
return str(reply)
def _render_prompt(prompt: Mapping[str, Any]) -> str:
if "approval" in prompt:
approval = prompt["approval"]
return f"Please approve {approval['phase']}: {approval['summary']}"
if "permission" in prompt:
return f"May I use {prompt['permission']['tier']} tools?"
return "\n".join(item["question"] for item in prompt.get("questions", []))
def _write_outputs(
out_dir: Path, deliverables: Mapping[str, Mapping[str, Any]]
) -> None:
out_dir.mkdir(parents=True, exist_ok=True)
guide = deliverables.get(DeliverableKind.SOLUTION_GUIDE.value)
if guide:
(out_dir / GUIDE_FILENAME).write_text(guide["content"], encoding="utf-8")
for kind, deliverable in deliverables.items():
path = out_dir / "deliverables" / f"{kind}.md"
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(deliverable["content"], encoding="utf-8")
for name, content in deliverable.get("attachments", {}).items():
attachment = out_dir / name
attachment.parent.mkdir(parents=True, exist_ok=True)
attachment.write_text(content, encoding="utf-8")