"""Asynchronous execution of one immutable V8 active Routing Plan.""" from __future__ import annotations import asyncio from collections.abc import Awaitable, Callable from datetime import datetime, timezone from enum import StrEnum from typing import Generic, Self, TypeVar, cast from pydantic import AwareDatetime, model_validator from polyhedra.core.active_routing import ActiveAgentPlan, ActiveRoutingPlan from polyhedra.core.artifacts import Availability, JsonArtifactRef, TypedModel from polyhedra.core.quant_contracts import AgentName from polyhedra.services.error_sanitizer import sanitize_exception class AgentExecutionState(StrEnum): WAITING = "WAITING" RUNNING = "RUNNING" COMPLETED = "COMPLETED" FAILED = "FAILED" BLOCKED = "BLOCKED" class AgentCompletion(TypedModel): artifact_ref: JsonArtifactRef result_status: Availability class AgentExecutionRecord(TypedModel): agent: AgentName state: AgentExecutionState result_status: Availability | None = None artifact_ref: JsonArtifactRef | None = None started_at: AwareDatetime | None = None finished_at: AwareDatetime | None = None error: str | None = None blocked_by: tuple[AgentName, ...] = () @model_validator(mode="after") def coherent_state(self) -> Self: if self.state == AgentExecutionState.COMPLETED: if self.result_status is None or self.artifact_ref is None or self.finished_at is None: raise ValueError("completed execution requires a published typed result") elif self.result_status is not None or self.artifact_ref is not None: raise ValueError("only completed execution can carry a result") if self.state == AgentExecutionState.FAILED and (not self.error or self.finished_at is None): raise ValueError("failed execution requires an error and finish time") if self.state == AgentExecutionState.BLOCKED and not self.blocked_by: raise ValueError("blocked execution requires failed dependencies") return self class DependencyExecutionResult(TypedModel): run_id: str session_id: str records: tuple[AgentExecutionRecord, ...] def for_agent(self, agent: AgentName) -> AgentExecutionRecord: for record in self.records: if record.agent == agent: return record raise KeyError(agent) ActivationT = TypeVar("ActivationT") AgentRunner = Callable[[ActiveAgentPlan, ActivationT], Awaitable[AgentCompletion]] LegacyAgentRunner = Callable[[ActiveAgentPlan], Awaitable[AgentCompletion]] InputCapture = Callable[ [ActiveAgentPlan, tuple[AgentExecutionRecord, ...]], ActivationT, ] class DependencyExecutor(Generic[ActivationT]): """Activate ready agents concurrently and derive execution state from results.""" def __init__( self, plan: ActiveRoutingPlan, *, session_id: str, runner: AgentRunner[ActivationT] | LegacyAgentRunner, input_capture: InputCapture[ActivationT] | None = None, now: Callable[[], datetime] | None = None, ) -> None: if not session_id: raise ValueError("dependency executor requires a session identity") self.plan = plan self.session_id = session_id self._runner = runner self._input_capture = input_capture self._now = now or (lambda: datetime.now(tz=timezone.utc)) self._records: dict[AgentName, AgentExecutionRecord] = { item.agent: AgentExecutionRecord(agent=item.agent, state=AgentExecutionState.WAITING) for item in plan.active_agents } self._published_paths: set[str] = set() self._published_ids: set[str] = set() async def run(self) -> DependencyExecutionResult: pending = {item.agent: item for item in self.plan.active_agents} running: dict[asyncio.Task[AgentCompletion], ActiveAgentPlan] = {} while pending or running: self._block_failed_dependents(pending) ready = [ item for item in pending.values() if all( self._records[dependency.agent].state == AgentExecutionState.COMPLETED for dependency in item.required_dependencies ) ] for item in ready: pending.pop(item.agent) started = self._now() self._records[item.agent] = AgentExecutionRecord( agent=item.agent, state=AgentExecutionState.RUNNING, started_at=started, ) try: task = self._schedule(item) except Exception as exc: self._records[item.agent] = AgentExecutionRecord( agent=item.agent, state=AgentExecutionState.FAILED, started_at=started, finished_at=self._now(), error=f"{type(exc).__name__}: {exc}", ) else: running[task] = item if not running: if pending: if ready: continue raise RuntimeError("active routing plan cannot make dependency progress") break done, _ = await asyncio.wait(running, return_when=asyncio.FIRST_COMPLETED) for task in done: item = running.pop(task) await self._record_completion(item, task) ordered = tuple(self._records[item.agent] for item in self.plan.active_agents) return DependencyExecutionResult( run_id=self.plan.run_id, session_id=self.session_id, records=ordered, ) def _schedule(self, item: ActiveAgentPlan) -> asyncio.Task[AgentCompletion]: if self._input_capture is None: runner = cast(LegacyAgentRunner, self._runner) return asyncio.create_task(runner(item)) dependencies = tuple( self._records[dependency.agent] for dependency in item.required_dependencies ) if any(record.state != AgentExecutionState.COMPLETED for record in dependencies): raise RuntimeError("input capture requires completed dependency publications") snapshot = self._input_capture(item, dependencies) runner = cast(AgentRunner[ActivationT], self._runner) return asyncio.create_task(runner(item, snapshot)) async def _record_completion( self, item: ActiveAgentPlan, task: asyncio.Task[AgentCompletion], ) -> None: started = self._records[item.agent].started_at finished = self._now() try: completion = task.result() reference = completion.artifact_ref if (reference.run_id, reference.session_id, reference.producer) != ( self.plan.run_id, self.session_id, item.agent, ): raise ValueError("published artifact identity contradicts the activation") if reference.path in self._published_paths or reference.artifact_id in self._published_ids: raise ValueError("artifact was published more than once in this run") self._published_paths.add(reference.path) self._published_ids.add(reference.artifact_id) self._records[item.agent] = AgentExecutionRecord( agent=item.agent, state=AgentExecutionState.COMPLETED, result_status=completion.result_status, artifact_ref=reference, started_at=started, finished_at=finished, ) except BaseException as exc: if isinstance(exc, asyncio.CancelledError): raise self._records[item.agent] = AgentExecutionRecord( agent=item.agent, state=AgentExecutionState.FAILED, started_at=started, finished_at=finished, error=sanitize_exception(exc), ) def _block_failed_dependents(self, pending: dict[AgentName, ActiveAgentPlan]) -> None: changed = True while changed: changed = False for agent, item in list(pending.items()): blocked_by = tuple( dependency.agent for dependency in item.required_dependencies if self._records[dependency.agent].state in { AgentExecutionState.FAILED, AgentExecutionState.BLOCKED, } ) if not blocked_by: continue pending.pop(agent) self._records[agent] = AgentExecutionRecord( agent=agent, state=AgentExecutionState.BLOCKED, blocked_by=blocked_by, ) changed = True