Files
orchestration_engine/execution_engine/nodes/router.py

861 lines
34 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""The Orchestrator as a router (ADR-0007): readings, a disposition, then a playbook.
1. Readings facts about the turn. Most come from the Ledger; the ones that need
judgement (what is the user asking for? does this gap matter?) are
typed answers from the decision model.
2. Disposition code turns a judged reading into act, queue or close, by threshold.
3. Playbook ordered groups. The first group that applies is taken, and within
it the strongest action whose conditions hold. When no group
applies, escalate to the user.
The decision model reads and never acts: every action goes through the Orchestrator's
tools, so the Ledger refuses anything that is not allowed, whatever was decided.
"""
from __future__ import annotations
import json
import logging
import re
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass, field
from typing import Any, Protocol
from execution_engine.adk.runtime import (
AgentRuntime,
AgentTask,
Decider,
Outcome,
Question,
RoleSpec,
Stopped,
Submitted,
ToolResult,
ToolSpec,
)
from execution_engine.states.ledger import DeliverableStatus, Ledger, PhaseStatus
from execution_engine.tools.scoping import SCOPE_DATA_FILE
from execution_engine.workflows.workflow import ValidationPolicy, Workflow
logger = logging.getLogger(__name__)
ORCHESTRATOR = "orchestrator"
REPLY_WRITER = "reply-writer"
MAX_STEPS = 12 # actions in one turn; a turn that needs more is not making progress
ACT, QUEUE, CLOSE = "act", "queue", "close"
@dataclass(frozen=True)
class Thresholds:
"""Where a probability becomes a disposition."""
act: float = 0.75 # at or above: do it
close: float = 0.15 # at or below: there is nothing to do
confidence: float = 0.6 # a choice below this is not relied on
def disposition(self, probability: float) -> str:
if probability >= self.act:
return ACT
if probability <= self.close:
return CLOSE
return QUEUE
@dataclass(frozen=True)
class TurnView:
"""What one Orchestrator turn can see."""
execution_id: str
pre_approved: bool
ledger: Ledger
deliverables: Mapping[str, Mapping[str, Any]]
pending_questions: Sequence[Mapping[str, Any]]
outcomes: Sequence[Mapping[str, Any]]
last_reply: Mapping[str, Any] | None = None # the user's message, not yet routed
pending_change: Mapping[str, Any] | None = None # a change we asked them to confirm
awaiting_gap_decision: bool = False
validation_settled: int = 0 # the validation attempt already decided on
# The user's reply answers "this Deliverable reached its Revision limit".
awaiting_limit_decision: bool = False
# Deliverables at their Revision limit that the user has been told about.
revision_limit_asked: Sequence[str] = ()
context: Mapping[str, Any] = field(default_factory=dict) # for a model Orchestrator
@dataclass
class TurnResult:
outcome: Outcome
decisions: list[dict[str, Any]] = field(default_factory=list)
updates: dict[str, Any] = field(default_factory=dict)
class OrchestratorPolicy(Protocol):
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult: ...
class ReplyWriter(Protocol):
async def approval_summary(
self, phase: str, facts: Mapping[str, Any]
) -> str | None: ...
# --- readings ------------------------------------------------------------------------
@dataclass
class Readings:
"""Everything the playbook decides from."""
# From the Ledger and the Execution's data.
questions_waiting: bool = False
phases_ready: tuple[str, ...] = ()
phases_awaiting: tuple[str, ...] = () # asked for Approval, not yet decided
ready_work: tuple[str, ...] = ()
can_finish: bool = False
validation_attempt: int = 0 # 0 when no validation stands undecided
failed: list[dict[str, Any]] = field(default_factory=list)
repeat_failed: list[dict[str, Any]] = field(default_factory=list)
unverifiable: list[dict[str, Any]] = field(default_factory=list)
additions: list[dict[str, Any]] = field(default_factory=list)
dry_run_failed: bool = False
# Checks the code's author reported cannot be met as the Target architecture
# words them.
unimplementable: list[dict[str, str]] = field(default_factory=list)
# Judged: what the user's message asks for.
change: str = CLOSE # act | queue | close
change_target: str | None = None
change_reason: str = ""
# Judged: whether a gap in the Target architecture is worth a Revision.
gap: str = CLOSE
judged: dict[str, Any] = field(default_factory=dict) # what the decider answered
# How much of the agreed requirements is shown to the decider with a user's message.
_AGREED_LIMIT = 24_000
# The actions that reopen a Deliverable, and which one.
_REOPENS = (
"revise_requested",
"revise_code",
"revise_target_architecture",
"revise_unimplementable",
)
def _reopened_by(action: str, readings: Readings, workflow: Workflow) -> str | None:
if action == "revise_requested":
return readings.change_target
validation = workflow.validation
if validation is None:
return None
if action == "revise_code":
return validation.implementation
if action in {"revise_target_architecture", "revise_unimplementable"}:
return validation.design
return None
def _attempt(ledger: Ledger, kind: str) -> int:
return int(ledger.to_dict()["deliverables"][str(kind)].get("attempt", 0))
def _submitted(ledger: Ledger) -> list[str]:
return [
kind
for kind in ledger.workflow.deliverables
if ledger.status(kind) is DeliverableStatus.SUBMITTED
]
def _mentioned(text: str, candidates: Sequence[str]) -> list[str]:
"""Deliverables named outright in a message, as `deployment_guidance` or in words."""
lowered = re.sub(r"[\s_\-]+", " ", text.lower())
return [kind for kind in candidates if str(kind).replace("_", " ") in lowered]
def _failed_before(
outcomes: Sequence[Mapping[str, Any]], validation: ValidationPolicy
) -> set[str]:
"""Check ids that failed in the validation before the one that stands now."""
validations = [
record
for record in outcomes
if record.get("type") == "submitted" and record.get("kind") == validation.kind
]
if len(validations) < 2:
return set()
previous = validation.read(
validations[-2].get("attachments", {}).get(validation.data_file, "")
)
return {item["check"] for item in previous["failed"]}
class Router:
"""Decides an Orchestrator turn from readings and a playbook, with no language
model choosing the action. A model, when one is given, only writes what the user
reads."""
def __init__(
self,
decider: Decider,
writer: ReplyWriter | None = None,
thresholds: Thresholds | None = None,
) -> None:
self._decider = decider
self._writer = writer
self._thresholds = thresholds or Thresholds()
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
by_name = {tool.name: tool for tool in tools}
result = TurnResult(Stopped("The router took no action."))
# A user message is routed once; a confirmation we asked for is consumed.
result.updates = {
"last_reply": None,
"pending_change": None,
"awaiting_gap_decision": False,
"awaiting_limit_decision": False,
}
readings = await self._read(view, result)
blocked: set[str] = set()
settled = view.validation_settled
# Told once, the user is not asked again: a Deliverable at its limit is no
# longer reopened, and the Execution carries on with it as it stands.
at_limit = set(view.revision_limit_asked)
async def call(tool: str, **arguments: Any) -> ToolResult:
return await by_name[tool].handler(**arguments)
for _ in range(MAX_STEPS):
barred = blocked | {
name
for name in _REOPENS
if (kind := _reopened_by(name, readings, view.ledger.workflow))
and str(kind) in at_limit
}
group, action = self._choose(view, readings, barred, settled)
result.decisions.append(
{"group": group, "action": action, "judged": dict(readings.judged)}
)
readings.judged = {}
reply = await self._perform(action, view, readings, call, result)
if action == "proceed":
settled = readings.validation_attempt
result.updates["validation_settled"] = settled
self._read_ledger(view, readings, settled)
continue
if reply is None:
return result
if reply.outcome is not None:
result.outcome = reply.outcome
return result
if "revision limit" in reply.message and not view.pre_approved:
# Past the Revision limit the user is told, once. Their reply is
# read as the answer to this, never as a new request for changes.
kind = _reopened_by(action, readings, view.ledger.workflow)
if kind:
at_limit.add(str(kind))
result.updates["revision_limit_asked"] = sorted(at_limit)
result.updates["awaiting_limit_decision"] = True
limit = await call(
"ask_user",
questions=[
reply.message.split(" Use ")[0]
+ " It will not be revised again in this Execution; I will "
"carry on with it as it stands. Reply to continue."
],
)
if limit.outcome is not None:
result.outcome = limit.outcome
return result
if reply.message.startswith("Refused") or "revision limit" in reply.message:
# Permission is the Ledger's: take the next action that is allowed.
blocked.add(action)
# The action changed the Execution; read the Ledger's facts again.
self._read_ledger(view, readings, settled)
if action in {"revise_requested", "confirm_change"}:
readings.change = CLOSE
result.outcome = Stopped("The router made no progress in this turn.")
return result
# --- readings ---------------------------------------------------------------------
async def _read(self, view: TurnView, result: TurnResult) -> Readings:
readings = Readings()
self._read_ledger(view, readings, view.validation_settled)
await self._read_message(view, readings)
await self._read_gap(view, readings)
return readings
def _read_ledger(self, view: TurnView, readings: Readings, settled: int) -> None:
ledger = view.ledger
readings.questions_waiting = bool(view.pending_questions)
readings.phases_ready = ledger.phases_ready_for_approval()
readings.phases_awaiting = tuple(
phase
for phase in ledger.workflow.phases
if ledger.phase_status(phase) is PhaseStatus.AWAITING_APPROVAL
)
readings.ready_work = ledger.ready_work()
readings.can_finish = ledger.can_finish()
readings.validation_attempt = 0
readings.failed, readings.repeat_failed = [], []
readings.unverifiable, readings.additions = [], []
readings.dry_run_failed = False
readings.unimplementable = []
policy = ledger.workflow.validation
if policy is None:
return
if (
policy.unimplementable
and ledger.status(policy.implementation) is DeliverableStatus.SUBMITTED
):
readings.unimplementable = policy.unimplementable(view.deliverables)
validation = policy.kind
phase = ledger.workflow.deliverables[validation].phase
attempt = _attempt(ledger, validation)
if (
ledger.status(validation) is not DeliverableStatus.SUBMITTED
or ledger.phase_status(phase) is PhaseStatus.APPROVED
or attempt == settled
):
return
outcome = policy.read(
view.deliverables.get(validation, {})
.get("attachments", {})
.get(policy.data_file, "")
)
before = _failed_before(view.outcomes, policy)
readings.validation_attempt = attempt
readings.failed = outcome["failed"]
readings.repeat_failed = [f for f in outcome["failed"] if f["check"] in before]
readings.unverifiable = outcome["not_verifiable"]
readings.additions = outcome["proposed_additions"]
readings.dry_run_failed = outcome["dry_run"].get("verdict") == "fail"
async def _read_message(self, view: TurnView, readings: Readings) -> None:
"""Triage of the user's message: is it asking for a change, to what, and how
clearly?"""
reply = view.last_reply
if not reply or view.awaiting_gap_decision or view.awaiting_limit_decision:
return
text = str(reply.get("text", "")).strip()
pending = view.pending_change
if pending:
text = f"{pending.get('text', '')}\nThe user then said: {text}"
candidates = _submitted(view.ledger)
if not text or not candidates:
return
readings.change_reason = text
asked = [str(question) for question in reply.get("asked") or ()]
# A structured request for changes is known to be one, and so is the reply to
# our own question about a change they already asked for.
structured = reply.get("kind") == "changes" or bool(pending)
workflow = view.ledger.workflow
agreed = (
""
if structured or not workflow.agreed
else workflow.agreed(view.deliverables)[:_AGREED_LIMIT]
)
questions = {
"change_target": Question(
"choice",
"Which submitted Deliverable would have to change first to do what "
"the user asks?",
tuple(str(kind) for kind in candidates),
),
"change_clarity": Question(
"score",
"How specific is the user about what should change?",
("vague", "partial", "specific"),
),
}
if not structured:
questions["asks_change"] = Question(
"noul",
"Is the user asking for a change to work that has already been "
"submitted, as opposed to answering a question or adding information?",
)
if agreed:
# Someone who restates what is already agreed is answering, however
# much it sounds like a requirement.
questions["already_agreed"] = Question(
"noul",
"Does the user's message only confirm or repeat what the agreed "
"requirements above already say, asking for nothing different?",
)
state = (
f"Submitted Deliverables: {', '.join(str(kind) for kind in candidates)}.\n"
+ (f"The agreed requirements:\n{agreed}\n" if agreed else "")
+ f"Questions waiting for the user: {len(view.pending_questions)}.\n"
# What we asked is background. Only the user's own words are their
# message: our question echoed back is not something they said.
+ (
"The user was replying to these questions from the agents:\n"
+ "\n".join(f"- {question}" for question in asked)
+ "\n"
if asked
else ""
)
+ f"The user's message: {text}"
)
answers = await self._decider.decide(state, questions, scope=view.execution_id)
named = _mentioned(text, candidates)
if answers is None:
# No judgement available: act only on what is certain.
if structured:
target = (
candidates[0]
if len(candidates) == 1
else named[0]
if len(named) == 1
else None
)
readings.change = ACT if target else QUEUE
readings.change_target = target
return
readings.judged = {
name: {"value": answer.value, "confidence": answer.confidence}
for name, answer in answers.items()
}
probability = 1.0 if structured else float(answers["asks_change"].value)
disposition = self._thresholds.disposition(probability)
restated = answers.get("already_agreed")
if restated is not None and restated.is_yes(self._thresholds.act):
# It restates what is agreed: an answer, not a change.
disposition = CLOSE
target_answer = answers["change_target"]
target = view.ledger.workflow.kind(str(target_answer.value))
readings.change_target = target
if disposition == ACT and (
target_answer.confidence < self._thresholds.confidence
or float(answers["change_clarity"].value) < 0.5
):
# They want a change, but which, or what, is not clear enough to act on.
disposition = QUEUE
if disposition == QUEUE and pending:
# Asked once already: act if they named it, otherwise let it go.
disposition = ACT if len(named) == 1 else CLOSE
readings.change_target = named[0] if named else target
readings.change = disposition
async def _read_gap(self, view: TurnView, readings: Readings) -> None:
"""Whether a gap in the Target architecture is worth revising it for."""
if (
readings.failed
or readings.dry_run_failed
or not readings.validation_attempt
):
return
if not (readings.additions or readings.unverifiable):
return
items = "\n".join(
[
f"- proposed addition on {item.get('applies_to')}: "
f"{item.get('statement')} (serves {item.get('reason')})"
for item in readings.additions
]
+ [
f"- Check {item.get('check')} could not be verified: "
f"{item.get('evidence')}"
for item in readings.unverifiable
]
)
reply = view.last_reply if view.awaiting_gap_decision else None
if reply:
question = Question(
"noul",
"Is the user asking for the Target architecture to be revised to "
"close these gaps?",
)
state = f"Gaps found by validation:\n{items}\nThe user's reply: {reply.get('text', '')}"
name = "wants_revision"
else:
question = Question(
"noul",
"Would leaving these gaps open mean a stated requirement or design "
"recommendation is not met?",
)
state = f"Gaps found by validation:\n{items}"
name = "gap_material"
answers = await self._decider.decide(
state, {name: question}, scope=view.execution_id
)
if answers is None:
readings.gap = self._gap_by_rule(view, readings) if not reply else CLOSE
return
readings.judged[name] = {
"value": answers[name].value,
"confidence": answers[name].confidence,
}
disposition = self._thresholds.disposition(float(answers[name].value))
if reply and disposition == QUEUE:
disposition = CLOSE # asked once already; an unclear answer means go on
readings.gap = disposition
@staticmethod
def _gap_by_rule(view: TurnView, readings: Readings) -> str:
"""Without a judgement: a Check that cannot be verified must be fixed, and an
addition counts when it names a real requirement or recommendation."""
if readings.unverifiable:
return ACT
policy = view.ledger.workflow.validation
known = (
policy.known_ids(view.deliverables)
if policy and policy.known_ids
else set()
)
for item in readings.additions:
words = set(re.findall(r"[A-Za-z]+-\d+", str(item.get("reason", ""))))
if words & known:
return ACT
return CLOSE
# --- the playbook -----------------------------------------------------------------
def _choose(
self, view: TurnView, r: Readings, blocked: set[str], settled: int
) -> tuple[str, str]:
"""The first group that applies, and within it the strongest action whose
conditions hold. No group applies: escalate."""
interactive = not view.pre_approved
playbook: list[tuple[str, bool, list[tuple[str, bool]]]] = [
(
"the user asked for a change",
r.change in {ACT, QUEUE},
[
(
"revise_requested",
r.change == ACT and r.change_target is not None,
),
("confirm_change", r.change == QUEUE and interactive),
],
),
(
"questions are waiting",
r.questions_waiting,
[("relay_questions", True)],
),
(
# Known as soon as the code is submitted, so no validation is spent
# on a Check that cannot pass.
"the code cannot meet a Check",
bool(r.unimplementable),
[("revise_unimplementable", True)],
),
(
"validation decided",
bool(r.validation_attempt),
[
(
"revise_target_architecture",
bool(r.repeat_failed) or (not r.failed and r.gap == ACT),
),
("revise_code", bool(r.failed) or r.dry_run_failed),
("ask_about_gaps", r.gap == QUEUE and interactive),
("proceed", True),
],
),
(
"a Phase is complete",
bool(r.phases_ready or r.phases_awaiting),
# An Approval is granted only by a structured decision, so a Phase
# still awaiting one is asked for again.
[("request_approval", True)],
),
("work is ready", bool(r.ready_work), [("delegate", True)]),
("packaging is approved", r.can_finish, [("finish", True)]),
]
for group, applies, actions in playbook:
if not applies:
continue
for action, holds in actions:
if holds and action not in blocked:
return group, action
return "no group applies", "escalate"
async def _perform(
self,
action: str,
view: TurnView,
r: Readings,
call: Callable[..., Awaitable[ToolResult]],
result: TurnResult,
) -> ToolResult | None:
workflow = view.ledger.workflow
if action == "proceed":
return ToolResult("Proceeding.")
if action == "revise_requested":
assert r.change_target is not None
return await call(
"reopen", kind=str(r.change_target), reason=r.change_reason
)
if action == "confirm_change":
guess = str(r.change_target) if r.change_target else None
result.updates["pending_change"] = {"text": r.change_reason, "guess": guess}
options = ", ".join(str(kind) for kind in _submitted(view.ledger))
question = (
f"Do you want {guess} changed? Reply naming the Deliverable to change "
f"and what should be different. Submitted so far: {options}."
if guess
else "Which Deliverable should change, and what should be different? "
f"Submitted so far: {options}."
)
return await call("ask_user", questions=[question])
if action == "relay_questions":
return await call("ask_user", questions=[])
if action == "revise_code":
items = r.failed or [
{"check": "dry-run", "evidence": "the deployment dry-run failed"}
]
reason = "; ".join(f"{i['check']} failed: {i['evidence']}" for i in items)
return await call(
"reopen", kind=str(_reopened_by(action, r, workflow)), reason=reason
)
if action == "revise_unimplementable":
reason = " ".join(
f"Check {item['check']} cannot be implemented as written "
f"({item['reason']}). Rewrite it so it can be met, or remove it with "
"a reason."
for item in r.unimplementable
)
# In the run of 2026-10-09 a second Check with the same fault came back
# one Revision later, for the same reason word for word.
reason += (
" The same fault may be in other Checks: read every Check against "
"each reason given here and correct every one it applies to."
)
return await call(
"reopen", kind=str(_reopened_by(action, r, workflow)), reason=reason
)
if action == "revise_target_architecture":
return await call(
"reopen",
kind=str(_reopened_by(action, r, workflow)),
reason=_graph_reason(r),
)
if action == "ask_about_gaps":
result.updates["awaiting_gap_decision"] = True
listed = "; ".join(
[str(i.get("statement")) for i in r.additions]
+ [
f"Check {i.get('check')} could not be verified"
for i in r.unverifiable
]
)
question = (
"Validation passed every Check it could, and found gaps in the "
f"Target architecture: {listed}. Should the Target architecture "
"be revised to close them, or shall I proceed as it stands?"
)
return await call("ask_user", questions=[question])
if action == "request_approval":
phase = (r.phases_ready or r.phases_awaiting)[0]
return await call(
"request_approval",
phase=str(phase),
summary=await self._summary(phase, view, r),
)
if action == "delegate":
return await call("delegate", kinds=[str(kind) for kind in r.ready_work])
if action == "finish":
return await call("finish")
# escalate: no group applies.
if view.pre_approved:
result.outcome = Stopped(
"No next step applies and no user is available to decide."
)
return None
return await call(
"ask_user",
questions=["I have no next step to take. What would you like me to do?"],
)
async def _summary(self, phase: str, view: TurnView, r: Readings) -> str:
facts = approval_facts(phase, view, r)
if self._writer is not None:
try:
written = await self._writer.approval_summary(str(phase), facts)
except Exception: # a summary must never stop an Approval
logger.exception("The reply writer failed; using the assembled summary")
written = None
if written and written.strip():
return written.strip()
return assembled_summary(phase, facts, view.ledger.workflow)
def _graph_reason(r: Readings) -> str:
parts = [
f"Check {item['check']} failed in two validations in a row and may not be "
f"implementable as written ({item['evidence']}). Rewrite it so it can be met, "
"or remove it with a reason."
for item in r.repeat_failed
]
if not r.repeat_failed:
parts += [
f"Check {item.get('check')} could not be verified from the code "
f"({item.get('evidence')}). Rewrite it so it can be."
for item in r.unverifiable
]
parts += [
f"Add a Check on {item.get('applies_to')}: {item.get('statement')} "
f"(serves {item.get('reason')})."
for item in r.additions
]
return " ".join(parts)
def approval_facts(phase: str, view: TurnView, r: Readings) -> dict[str, Any]:
"""What an Approval summary is written from: data, never Deliverable prose."""
workflow = view.ledger.workflow
kinds = workflow.deliverables_in(phase)
facts: dict[str, Any] = {
"phase": str(phase),
"deliverables": [str(kind) for kind in kinds],
"revisions": {
str(kind): view.ledger.revisions(kind)
for kind in kinds
if view.ledger.revisions(kind)
},
}
if workflow.approval_facts:
facts.update(workflow.approval_facts(phase, view.deliverables))
spec = workflow.spec_deliverable
scope = (view.deliverables.get(spec) or {}).get("attachments", {}) if spec else {}
if (
spec
and phase == workflow.deliverables[spec].phase
and scope.get(SCOPE_DATA_FILE)
):
# What approving the spec commits to: how much the customer stated, how
# much was assumed for them, and what is still unknown.
try:
agreed = json.loads(scope[SCOPE_DATA_FILE])
except ValueError:
agreed = {}
facts["scope"] = {
"kind": agreed.get("kind"),
"assumed": [item.get("field") for item in agreed.get("assumed", [])],
"left_to_decide": [
item.get("field") for item in agreed.get("to_decide", [])
],
"unknown": [item.get("field") for item in agreed.get("to_ask", [])],
}
policy = workflow.validation
validation = view.deliverables.get(policy.kind) if policy else None
if policy and validation and phase == workflow.deliverables[policy.kind].phase:
outcome = policy.read(
validation.get("attachments", {}).get(policy.data_file, "")
)
facts["validation"] = {
"passed": len(outcome["passed"]),
"failed": [item["check"] for item in outcome["failed"]],
"not_verifiable": [item["check"] for item in outcome["not_verifiable"]],
"open_gaps": [
item.get("statement") for item in outcome["proposed_additions"]
],
}
return facts
def assembled_summary(
phase: str, facts: Mapping[str, Any], workflow: Workflow | None = None
) -> str:
"""An Approval summary from the facts alone, used when no writer is available."""
lines = [
(f"The {phase} Phase is ready: {', '.join(facts['deliverables'])} submitted.")
]
if workflow and workflow.summary_lines:
lines += list(workflow.summary_lines(phase, facts))
scope = facts.get("scope")
if scope:
lines.append(
f"Scope of a {scope.get('kind') or 'workload'}: "
f"{len(scope['assumed'])} fields assumed, "
f"{len(scope['unknown'])} still unknown. Requirements are derived "
"from it once you approve."
)
validation = facts.get("validation")
if validation:
lines.append(
f"Validation: {validation['passed']} Checks passed, "
f"{len(validation['failed'])} failed, "
f"{len(validation['not_verifiable'])} not verifiable."
)
if validation["open_gaps"]:
lines.append(
"Open gaps: " + "; ".join(map(str, validation["open_gaps"])) + "."
)
if facts.get("revisions"):
lines.append(
"Revised: "
+ ", ".join(
f"{kind} × {count}" for kind, count in facts["revisions"].items()
)
+ "."
)
return " ".join(lines)
# --- the two ways an Orchestrator turn can be driven ---------------------------------
class ModelOrchestrator:
"""The Orchestrator as a reasoning agent: a language model chooses the tool calls.
Kept so the Ledger's rules can be driven in any order by a scripted runtime in
tests, and so an evaluation can compare it with the router.
"""
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
self._runtime = runtime
self._role = role
async def turn(self, view: TurnView, tools: Sequence[ToolSpec]) -> TurnResult:
task = AgentTask(
role=ORCHESTRATOR,
prompt="Decide the next step for this Execution using your tools.",
context=view.context,
)
return TurnResult(await self._runtime.run(self._role, task, tools))
class RuntimeReplyWriter:
"""Writes what the user reads, on a language model. It is given a decision that
has already been made and the facts, and it decides nothing."""
def __init__(self, runtime: AgentRuntime, role: RoleSpec) -> None:
self._runtime = runtime
self._role = role
async def approval_summary(
self, phase: str, facts: Mapping[str, Any]
) -> str | None:
async def write_reply(text: str) -> ToolResult:
if not text.strip():
return ToolResult("Not submitted: the reply is empty.")
return ToolResult("Written.", Submitted(text))
tool = ToolSpec(
"write_reply",
"Give the text the user will read. Ends your turn.",
{
"type": "object",
"properties": {"text": {"type": "string"}},
"required": ["text"],
},
write_reply,
tier="execution",
)
task = AgentTask(
role=REPLY_WRITER,
prompt=f"Write the summary the user will approve the {phase} Phase from.",
context={"phase": phase, "facts": dict(facts)},
)
outcome = await self._runtime.run(self._role, task, [tool])
return outcome.content if isinstance(outcome, Submitted) else None