feat: working orhcestration engine
This commit is contained in:
302
execution_engine/states/ledger.py
Normal file
302
execution_engine/states/ledger.py
Normal file
@@ -0,0 +1,302 @@
|
||||
"""The Ledger: every rule code owns about Deliverable progress, Approvals and Revisions.
|
||||
|
||||
Pure and synchronous: no I/O, no framework types. Invalid requests raise
|
||||
LedgerRefusal and leave the Ledger unchanged; tools turn refusals into messages
|
||||
the agent can act on.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections.abc import Iterable
|
||||
from dataclasses import asdict, dataclass, field
|
||||
from enum import StrEnum
|
||||
from typing import Any
|
||||
|
||||
from execution_engine.workflows.workflow import Workflow
|
||||
|
||||
PRE_APPROVED_ACTOR = "pre-approved"
|
||||
|
||||
|
||||
class DeliverableStatus(StrEnum):
|
||||
PENDING = "pending"
|
||||
IN_PROGRESS = "in_progress"
|
||||
SUBMITTED = "submitted"
|
||||
|
||||
|
||||
class PhaseStatus(StrEnum):
|
||||
OPEN = "open"
|
||||
AWAITING_APPROVAL = "awaiting_approval"
|
||||
APPROVED = "approved"
|
||||
|
||||
|
||||
class LedgerRefusal(Exception):
|
||||
"""A request the Ledger's rules don't allow. Nothing was changed."""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LedgerEvent:
|
||||
sequence: int
|
||||
type: str # started | released | submitted | approval_requested | approved |
|
||||
# changes_requested | reopened | reset | approval_withdrawn | escalated
|
||||
subject: str # a Deliverable kind or a Phase id
|
||||
actor: str
|
||||
detail: str = ""
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReopenResult:
|
||||
reset: tuple[str, ...]
|
||||
withdrawn_approvals: tuple[str, ...]
|
||||
escalation: str | None = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class _DeliverableRecord:
|
||||
status: DeliverableStatus = DeliverableStatus.PENDING
|
||||
attempt: int = 0
|
||||
revisions: int = 0
|
||||
feedback: list[str] = field(default_factory=list)
|
||||
|
||||
|
||||
class Ledger:
|
||||
def __init__(
|
||||
self, workflow: Workflow, pre_approved: bool = False, max_revisions: int = 3
|
||||
) -> None:
|
||||
self.workflow = workflow
|
||||
self.pre_approved = pre_approved
|
||||
self.max_revisions = max_revisions
|
||||
self._graph = workflow.deliverables
|
||||
self._deliverables = {kind: _DeliverableRecord() for kind in self._graph}
|
||||
self._phases = {phase: PhaseStatus.OPEN for phase in workflow.phases}
|
||||
self._events: list[LedgerEvent] = []
|
||||
|
||||
# --- queries -----------------------------------------------------------------
|
||||
|
||||
@property
|
||||
def events(self) -> tuple[LedgerEvent, ...]:
|
||||
return tuple(self._events)
|
||||
|
||||
def status(self, kind: str) -> DeliverableStatus:
|
||||
return self._deliverables[kind].status
|
||||
|
||||
def phase_status(self, phase: str) -> PhaseStatus:
|
||||
return self._phases[phase]
|
||||
|
||||
def revisions(self, kind: str) -> int:
|
||||
return self._deliverables[kind].revisions
|
||||
|
||||
def feedback(self, kind: str) -> tuple[str, ...]:
|
||||
return tuple(self._deliverables[kind].feedback)
|
||||
|
||||
def dependencies_met(self, kind: str) -> bool:
|
||||
spec = self._graph[kind]
|
||||
for dependency in spec.depends_on:
|
||||
dependency_phase = self._graph[dependency].phase
|
||||
if dependency_phase == spec.phase:
|
||||
if self.status(dependency) is not DeliverableStatus.SUBMITTED:
|
||||
return False
|
||||
elif self._phases[dependency_phase] is not PhaseStatus.APPROVED:
|
||||
return False
|
||||
return True
|
||||
|
||||
def ready_work(self) -> tuple[str, ...]:
|
||||
return tuple(
|
||||
kind
|
||||
for kind in self._graph
|
||||
if self.status(kind) is DeliverableStatus.PENDING
|
||||
and self.dependencies_met(kind)
|
||||
)
|
||||
|
||||
def phases_ready_for_approval(self) -> tuple[str, ...]:
|
||||
return tuple(
|
||||
phase
|
||||
for phase in self.workflow.phases
|
||||
if self._phases[phase] is PhaseStatus.OPEN and not self._unsubmitted(phase)
|
||||
)
|
||||
|
||||
def can_finish(self) -> bool:
|
||||
return self._phases[self.workflow.phases[-1]] is PhaseStatus.APPROVED
|
||||
|
||||
# --- delegation and submission -----------------------------------------------
|
||||
|
||||
def start(self, kinds: Iterable[str], actor: str) -> dict[str, int]:
|
||||
"""Move ready Deliverables in progress; returns the attempt number for each."""
|
||||
kinds = list(dict.fromkeys(kinds))
|
||||
ready = set(self.ready_work())
|
||||
not_ready = [kind for kind in kinds if kind not in ready]
|
||||
if not_ready:
|
||||
raise LedgerRefusal(
|
||||
"Not ready to start: "
|
||||
+ ", ".join(self._describe_unready(k) for k in not_ready)
|
||||
)
|
||||
attempts = {}
|
||||
for kind in kinds:
|
||||
record = self._deliverables[kind]
|
||||
record.status = DeliverableStatus.IN_PROGRESS
|
||||
record.attempt += 1
|
||||
attempts[kind] = record.attempt
|
||||
self._record("started", kind, actor, f"attempt {record.attempt}")
|
||||
return attempts
|
||||
|
||||
def submit(self, kind: str, attempt: int, actor: str) -> None:
|
||||
"""Accept the current attempt. Any later start, release or reopen supersedes it."""
|
||||
self._require_current_attempt(kind, attempt)
|
||||
self._deliverables[kind].status = DeliverableStatus.SUBMITTED
|
||||
self._record("submitted", kind, actor, f"attempt {attempt}")
|
||||
|
||||
def release(self, kind: str, attempt: int, reason: str) -> None:
|
||||
"""Return in-progress work to pending (e.g. the Specialist needs input)."""
|
||||
self._require_current_attempt(kind, attempt)
|
||||
record = self._deliverables[kind]
|
||||
record.status = DeliverableStatus.PENDING
|
||||
self._record("released", kind, self._graph[kind].specialist, reason)
|
||||
|
||||
# --- approvals ---------------------------------------------------------------
|
||||
|
||||
def request_approval(self, phase: str, actor: str) -> None:
|
||||
if self._phases[phase] is not PhaseStatus.OPEN:
|
||||
raise LedgerRefusal(f"Phase {phase} is {self._phases[phase]}, not open")
|
||||
unsubmitted = self._unsubmitted(phase)
|
||||
if unsubmitted:
|
||||
raise LedgerRefusal(
|
||||
f"Phase {phase} has unsubmitted Deliverables: {', '.join(unsubmitted)}"
|
||||
)
|
||||
self._phases[phase] = PhaseStatus.AWAITING_APPROVAL
|
||||
self._record("approval_requested", phase, actor)
|
||||
if self.pre_approved:
|
||||
self.approve(phase, actor=PRE_APPROVED_ACTOR)
|
||||
|
||||
def approve(self, phase: str, actor: str) -> None:
|
||||
self._require_awaiting(phase)
|
||||
self._phases[phase] = PhaseStatus.APPROVED
|
||||
self._record("approved", phase, actor)
|
||||
|
||||
def request_changes(self, phase: str, feedback: str, actor: str) -> None:
|
||||
self._require_awaiting(phase)
|
||||
self._phases[phase] = PhaseStatus.OPEN
|
||||
self._record("changes_requested", phase, actor, feedback)
|
||||
|
||||
# --- revisions ---------------------------------------------------------------
|
||||
|
||||
def reopen(
|
||||
self,
|
||||
kind: str,
|
||||
reason: str,
|
||||
actor: str,
|
||||
override_cap: bool = False,
|
||||
) -> ReopenResult:
|
||||
record = self._deliverables[kind]
|
||||
if record.status is not DeliverableStatus.SUBMITTED:
|
||||
raise LedgerRefusal(
|
||||
f"Only submitted Deliverables can be reopened; {kind} is {record.status}"
|
||||
)
|
||||
if record.revisions >= self.max_revisions and not override_cap:
|
||||
escalation = (
|
||||
f"{kind} has reached its revision limit ({self.max_revisions}). "
|
||||
f"Requested change: {reason}. Ask the user whether to revise it again "
|
||||
"or accept it as it stands."
|
||||
)
|
||||
self._record("escalated", kind, actor, reason)
|
||||
return ReopenResult(reset=(), withdrawn_approvals=(), escalation=escalation)
|
||||
|
||||
record.status = DeliverableStatus.PENDING
|
||||
record.revisions += 1
|
||||
record.feedback.append(reason)
|
||||
self._record("reopened", kind, actor, reason)
|
||||
reset = [kind]
|
||||
|
||||
for dependent in self.workflow.dependents_of(kind):
|
||||
dependent_record = self._deliverables[dependent]
|
||||
if dependent_record.status is DeliverableStatus.PENDING:
|
||||
continue
|
||||
dependent_record.status = DeliverableStatus.PENDING
|
||||
dependent_record.feedback.append(f"Dependency {kind} was revised: {reason}")
|
||||
self._record("reset", dependent, actor, f"dependency {kind} reopened")
|
||||
reset.append(dependent)
|
||||
|
||||
withdrawn = []
|
||||
for phase in self.workflow.phases:
|
||||
affected = any(self._graph[k].phase == phase for k in reset)
|
||||
if affected and self._phases[phase] is not PhaseStatus.OPEN:
|
||||
self._phases[phase] = PhaseStatus.OPEN
|
||||
self._record("approval_withdrawn", phase, actor, f"{kind} reopened")
|
||||
withdrawn.append(phase)
|
||||
|
||||
return ReopenResult(reset=tuple(reset), withdrawn_approvals=tuple(withdrawn))
|
||||
|
||||
# --- persistence -------------------------------------------------------------
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"pre_approved": self.pre_approved,
|
||||
"max_revisions": self.max_revisions,
|
||||
"deliverables": {
|
||||
str(kind): {
|
||||
"status": record.status.value,
|
||||
"attempt": record.attempt,
|
||||
"revisions": record.revisions,
|
||||
"feedback": list(record.feedback),
|
||||
}
|
||||
for kind, record in self._deliverables.items()
|
||||
},
|
||||
"phases": {
|
||||
str(phase): status.value for phase, status in self._phases.items()
|
||||
},
|
||||
"events": [asdict(event) for event in self._events],
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, workflow: Workflow, data: dict[str, Any]) -> Ledger:
|
||||
ledger = cls(
|
||||
workflow,
|
||||
pre_approved=data["pre_approved"],
|
||||
max_revisions=data["max_revisions"],
|
||||
)
|
||||
for kind_value, record in data["deliverables"].items():
|
||||
ledger._deliverables[workflow.kind(kind_value)] = _DeliverableRecord(
|
||||
status=DeliverableStatus(record["status"]),
|
||||
attempt=record["attempt"],
|
||||
revisions=record["revisions"],
|
||||
feedback=list(record["feedback"]),
|
||||
)
|
||||
for phase_value, status in data["phases"].items():
|
||||
ledger._phases[workflow.phase(phase_value)] = PhaseStatus(status)
|
||||
ledger._events = [LedgerEvent(**event) for event in data["events"]]
|
||||
return ledger
|
||||
|
||||
# --- internals ---------------------------------------------------------------
|
||||
|
||||
def _record(self, type_: str, subject: str, actor: str, detail: str = "") -> None:
|
||||
self._events.append(
|
||||
LedgerEvent(len(self._events) + 1, type_, str(subject), actor, detail)
|
||||
)
|
||||
|
||||
def _unsubmitted(self, phase: str) -> list[str]:
|
||||
return [
|
||||
kind
|
||||
for kind in self.workflow.deliverables_in(phase)
|
||||
if self.status(kind) is not DeliverableStatus.SUBMITTED
|
||||
]
|
||||
|
||||
def _describe_unready(self, kind: str) -> str:
|
||||
status = self.status(kind)
|
||||
if status is not DeliverableStatus.PENDING:
|
||||
return f"{kind} ({status})"
|
||||
return f"{kind} (dependencies not met)"
|
||||
|
||||
def _require_current_attempt(self, kind: str, attempt: int) -> None:
|
||||
record = self._deliverables[kind]
|
||||
if (
|
||||
record.status is not DeliverableStatus.IN_PROGRESS
|
||||
or attempt != record.attempt
|
||||
):
|
||||
raise LedgerRefusal(
|
||||
f"{kind} is {record.status}, not in_progress with attempt {attempt}; "
|
||||
"this attempt is not current"
|
||||
)
|
||||
|
||||
def _require_awaiting(self, phase: str) -> None:
|
||||
if self._phases[phase] is not PhaseStatus.AWAITING_APPROVAL:
|
||||
raise LedgerRefusal(
|
||||
f"Phase {phase} is {self._phases[phase]}, not awaiting_approval"
|
||||
)
|
||||
Reference in New Issue
Block a user