feat: working orhcestration engine
This commit is contained in:
254
execution_engine/nodes/intake.py
Normal file
254
execution_engine/nodes/intake.py
Normal file
@@ -0,0 +1,254 @@
|
||||
"""Intake: what a message that starts something is asking for (ADR-0007).
|
||||
|
||||
Inside an Execution the router reads the user's replies. This is the same reading
|
||||
one step earlier, for a message that arrives with no Execution in progress:
|
||||
|
||||
new request design this workload start an Execution
|
||||
change request change what was delivered name the Baseline to change (ADR-0006)
|
||||
question what can you do, how long... answer; start nothing
|
||||
why did you choose X? answer from what was delivered
|
||||
|
||||
A change is never started from earlier work on a guess: the caller chooses the
|
||||
Baseline. So a message read as a change is answered with the Execution it would
|
||||
change and how to name it, and starts nothing.
|
||||
|
||||
Without a decision, and whenever the reading is not confident, the message is taken
|
||||
as a new request: that is what every message was before, and starting work nobody
|
||||
asked for is cheaper to put right than refusing work somebody did.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from collections.abc import Mapping, Sequence
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.adk.runtime import (
|
||||
AgentRuntime,
|
||||
AgentTask,
|
||||
Decider,
|
||||
Question,
|
||||
RoleSpec,
|
||||
Submitted,
|
||||
ToolResult,
|
||||
ToolSpec,
|
||||
)
|
||||
from execution_engine.baseline import BaselineError, load_baseline
|
||||
from execution_engine.customer_case import IN_PROGRESS, read_history
|
||||
from execution_engine.states.execution_state import UNASSIGNED_CASE
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
NEW_REQUEST = "new_request"
|
||||
CHANGE_REQUEST = "change_request"
|
||||
QUESTION = "question"
|
||||
|
||||
|
||||
def change_note(baseline: str) -> str:
|
||||
"""What a caller is told when their message reads as a change to delivered work."""
|
||||
return (
|
||||
"This reads as a change to the work already delivered for this "
|
||||
f"Customer case, in Execution {baseline}. Nothing was started. To change "
|
||||
f'that work from where it stood, send this again with "baseline" '
|
||||
f'set to "{baseline}". To start it as new work instead, send it again '
|
||||
'with "new_request" set to true.'
|
||||
)
|
||||
|
||||
|
||||
def no_answer_note(execution_id: str) -> str:
|
||||
"""What a caller is told when a question about delivered work went unanswered."""
|
||||
return (
|
||||
"I could not answer that from the documents delivered in Execution "
|
||||
f"{execution_id}. Its final document and Deliverables hold what was "
|
||||
"decided and why. Nothing was started for this message."
|
||||
)
|
||||
|
||||
|
||||
_MESSAGE_LIMIT = 8_000
|
||||
# How much of the delivered guide the answer is written from.
|
||||
_GUIDE_LIMIT = 80_000
|
||||
_EARLIER_SHOWN = 5
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class IntakeReading:
|
||||
kind: str # new_request | change_request | question
|
||||
confidence: float = 0.0
|
||||
judged: bool = False # False when no decision was available
|
||||
earlier: int = 0 # finished Executions of the same Customer case
|
||||
latest: str | None = None # the most recent of them: what a change would change
|
||||
# A question about what was delivered, as opposed to about the service.
|
||||
about_delivered: bool = False
|
||||
|
||||
|
||||
def finished_intents(output_root: Path, customer_case: str) -> list[Mapping[str, Any]]:
|
||||
"""The case's earlier statements of intent whose Executions delivered something."""
|
||||
if not customer_case or customer_case == UNASSIGNED_CASE:
|
||||
return []
|
||||
return [
|
||||
item
|
||||
for item in read_history(output_root, customer_case)["intents"]
|
||||
if isinstance(item, Mapping)
|
||||
and str(item.get("status", IN_PROGRESS)).startswith("completed")
|
||||
]
|
||||
|
||||
|
||||
class Intake:
|
||||
def __init__(
|
||||
self,
|
||||
decider: Decider,
|
||||
output_root: Path,
|
||||
*,
|
||||
act: float = 0.75,
|
||||
about_delivered_at: float = 0.6,
|
||||
) -> None:
|
||||
self._decider = decider
|
||||
self._output_root = output_root
|
||||
# How sure the reading must be before anything but a new Execution is done.
|
||||
self._act = act
|
||||
# How likely a question must be about delivered work to be answered from
|
||||
# it. Measured on 2026-10-10: six such questions scored 0.37 to 0.96, five
|
||||
# of them 0.73 or more; six about the service scored 0.07 to 0.16 and one
|
||||
# ambiguous one ("is my data stored anywhere?") 0.74. A wrong yes costs an
|
||||
# answer that says the documents do not cover it.
|
||||
self._about_delivered_at = about_delivered_at
|
||||
|
||||
async def read(
|
||||
self, message: str, customer_case: str | None = None, scope: str = ""
|
||||
) -> IntakeReading:
|
||||
earlier = finished_intents(self._output_root, customer_case or "")
|
||||
text = message.strip()
|
||||
if not text:
|
||||
return IntakeReading(NEW_REQUEST, earlier=len(earlier))
|
||||
answers = await self._decider.decide(
|
||||
_state(text, earlier),
|
||||
{
|
||||
"intake": Question(
|
||||
"choice",
|
||||
"What is the user's message? new_request: they describe "
|
||||
"something they want done. change_request: they "
|
||||
"ask to change or extend work already delivered to "
|
||||
"them. question: they ask about the service or about earlier "
|
||||
"work, and want an answer, not new work.",
|
||||
(NEW_REQUEST, CHANGE_REQUEST, QUESTION),
|
||||
)
|
||||
},
|
||||
scope=scope,
|
||||
)
|
||||
answer = (answers or {}).get("intake")
|
||||
if answer is None:
|
||||
return IntakeReading(NEW_REQUEST, earlier=len(earlier))
|
||||
kind, confidence = str(answer.value), float(answer.confidence)
|
||||
if kind != NEW_REQUEST and confidence < self._act:
|
||||
kind = NEW_REQUEST # not sure enough to do anything but start
|
||||
if kind == CHANGE_REQUEST and not earlier:
|
||||
kind = NEW_REQUEST # there is nothing delivered to change
|
||||
logger.info("[%s] intake: %s (%.2f)", scope, kind, confidence)
|
||||
latest = str(earlier[-1].get("execution_id")) if earlier else None
|
||||
about = (
|
||||
await self._about_delivered(text, earlier, scope)
|
||||
if kind == QUESTION and latest
|
||||
else False
|
||||
)
|
||||
return IntakeReading(
|
||||
kind,
|
||||
confidence,
|
||||
judged=True,
|
||||
earlier=len(earlier),
|
||||
latest=latest,
|
||||
about_delivered=about,
|
||||
)
|
||||
|
||||
async def _about_delivered(
|
||||
self, text: str, earlier: Sequence[Mapping[str, Any]], scope: str
|
||||
) -> bool:
|
||||
answers = await self._decider.decide(
|
||||
_state(text, earlier),
|
||||
{
|
||||
"about_delivered": Question(
|
||||
"noul",
|
||||
"Is the user asking about work already delivered to "
|
||||
"them: what it contains, why something was chosen, or what "
|
||||
"validation found? Answer no when they ask what this service "
|
||||
"does or how it works in general.",
|
||||
)
|
||||
},
|
||||
scope=scope,
|
||||
)
|
||||
answer = (answers or {}).get("about_delivered")
|
||||
return answer is not None and float(answer.value) >= self._about_delivered_at
|
||||
|
||||
|
||||
def _state(message: str, earlier: Sequence[Mapping[str, Any]]) -> str:
|
||||
lines = [f"Architectures already delivered to this user: {len(earlier)}."]
|
||||
for item in list(earlier)[-_EARLIER_SHOWN:]:
|
||||
request = " ".join(str(item.get("workflow_request", "")).split())[:300]
|
||||
lines.append(f"- {request}")
|
||||
lines.append(f"The user's message: {message[:_MESSAGE_LIMIT]}")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
class DeliveredAnswers:
|
||||
"""Answers a question about delivered work from its documents, on the reply
|
||||
writer. It reads one Execution's files and starts nothing."""
|
||||
|
||||
def __init__(
|
||||
self, runtime: AgentRuntime, role: RoleSpec, output_root: Path, final: str
|
||||
) -> None:
|
||||
self._runtime = runtime
|
||||
self._role = role
|
||||
self._output_root = output_root
|
||||
# The Workflow's final Deliverable: the document an answer is written from.
|
||||
self._final = final
|
||||
|
||||
async def answer(
|
||||
self, question: str, customer_case: str, execution_id: str
|
||||
) -> str | None:
|
||||
"""The answer, or None when the documents could not be read or the writer
|
||||
gave none."""
|
||||
try:
|
||||
delivered = load_baseline(self._output_root, customer_case, execution_id)
|
||||
except BaselineError:
|
||||
return None
|
||||
guide = str(
|
||||
(delivered["deliverables"].get(self._final) or {}).get("content", "")
|
||||
)
|
||||
if not guide.strip():
|
||||
return 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=self._role.name,
|
||||
prompt="Answer the user's question about the work delivered to them.",
|
||||
context={
|
||||
"question": question[:_MESSAGE_LIMIT],
|
||||
"delivered": {
|
||||
"execution_id": execution_id,
|
||||
"request": delivered.get("workflow_request", ""),
|
||||
"final_document": guide[:_GUIDE_LIMIT],
|
||||
},
|
||||
},
|
||||
)
|
||||
try:
|
||||
outcome = await self._runtime.run(self._role, task, [tool])
|
||||
except Exception: # a question must still get a reply
|
||||
logger.exception("Answering from delivered work failed")
|
||||
return None
|
||||
return outcome.content if isinstance(outcome, Submitted) else None
|
||||
Reference in New Issue
Block a user