hypermind 0.11.0__py3-none-any.whl

hypermind/workflow/plan.py

@@ -0,0 +1,182 @@
+"""Plan / PlanDAG — typed plan nodes with Toulmin-shape edges.
+
+A `PlanDAG` is a directed acyclic graph of `PlanNode`s. Edge kinds reuse
+the Toulmin/IBIS shape from :mod:`hypermind.consult` (``supports``,
+``rebuts``, ``undercuts``, ``qualifies``) and add ``depends_on`` for
+ordering — so a plan can both express data-flow precedence AND carry
+the deliberation argument structure that supports/rebuts each step.
+
+`Plan.to_workflow()` compiles a DAG into a runnable workflow body,
+walking the topological order and issuing one ``wf.step`` per node.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from hypermind.consult import ARGUMENT_EDGE_KINDS
+
+PlanNodeKind = Literal["goal", "action", "branch", "wait", "fanout", "fanin"]
+_VALID_PLAN_NODE_KINDS: frozenset[str] = frozenset(
+    {"goal", "action", "branch", "wait", "fanout", "fanin"}
+)
+
+# Plan edges extend Toulmin with ``depends_on`` (precedence) so the same
+# edge type carries both data-flow and argument structure.
+PlanEdgeKind = Literal["supports", "rebuts", "undercuts", "qualifies", "depends_on"]
+_VALID_PLAN_EDGE_KINDS: frozenset[str] = frozenset(set(ARGUMENT_EDGE_KINDS) | {"depends_on"})
+
+
+@dataclass
+class PlanNode:
+    node_id: str
+    kind: PlanNodeKind
+    payload: dict[str, Any] = field(default_factory=dict)
+    depends_on: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.kind not in _VALID_PLAN_NODE_KINDS:
+            raise ValueError(
+                f"unknown PlanNode kind {self.kind!r}; valid: {sorted(_VALID_PLAN_NODE_KINDS)}"
+            )
+
+
+@dataclass
+class PlanEdge:
+    src: str
+    dst: str
+    kind: PlanEdgeKind
+
+    def __post_init__(self) -> None:
+        if self.kind not in _VALID_PLAN_EDGE_KINDS:
+            raise ValueError(
+                f"unknown PlanEdge kind {self.kind!r}; valid: {sorted(_VALID_PLAN_EDGE_KINDS)}"
+            )
+
+
+@dataclass
+class PlanDAG:
+    """A directed acyclic graph of plan nodes.
+
+    Cycles are rejected by :meth:`validate` (called automatically by
+    :meth:`topological`).
+    """
+
+    nodes: dict[str, PlanNode] = field(default_factory=dict)
+    edges: list[PlanEdge] = field(default_factory=list)
+
+    def add_node(self, node: PlanNode) -> None:
+        if node.node_id in self.nodes:
+            raise ValueError(f"duplicate node id {node.node_id!r}")
+        self.nodes[node.node_id] = node
+
+    def add_edge(
+        self,
+        src: str,
+        dst: str,
+        kind: PlanEdgeKind = "depends_on",
+    ) -> None:
+        if src not in self.nodes:
+            raise KeyError(f"unknown src node {src!r}")
+        if dst not in self.nodes:
+            raise KeyError(f"unknown dst node {dst!r}")
+        edge = PlanEdge(src=src, dst=dst, kind=kind)
+        self.edges.append(edge)
+        # Mirror depends_on into the node attr for convenience.
+        if kind == "depends_on":
+            node = self.nodes[dst]
+            if src not in node.depends_on:
+                node.depends_on.append(src)
+
+    def validate(self) -> None:
+        """Detect cycles via Kahn's algorithm; raise on failure."""
+        # Use only depends_on edges for ordering (Toulmin support/rebut
+        # edges are argument structure, not data flow).
+        indeg: dict[str, int] = {nid: 0 for nid in self.nodes}
+        adj: dict[str, list[str]] = {nid: [] for nid in self.nodes}
+        for e in self.edges:
+            if e.kind != "depends_on":
+                continue
+            indeg[e.dst] += 1
+            adj[e.src].append(e.dst)
+        queue = [nid for nid, d in indeg.items() if d == 0]
+        seen = 0
+        while queue:
+            n = queue.pop(0)
+            seen += 1
+            for m in adj[n]:
+                indeg[m] -= 1
+                if indeg[m] == 0:
+                    queue.append(m)
+        if seen != len(self.nodes):
+            raise ValueError("PlanDAG has a cycle")
+
+    def topological(self) -> list[PlanNode]:
+        """Return nodes in a topological order (Kahn's, deterministic)."""
+        self.validate()
+        indeg: dict[str, int] = {nid: 0 for nid in self.nodes}
+        adj: dict[str, list[str]] = {nid: [] for nid in self.nodes}
+        for e in self.edges:
+            if e.kind != "depends_on":
+                continue
+            indeg[e.dst] += 1
+            adj[e.src].append(e.dst)
+        # Sort the zero-indegree frontier by node_id so iteration order
+        # is deterministic across runs (replay friendliness).
+        out: list[PlanNode] = []
+        queue = sorted([nid for nid, d in indeg.items() if d == 0])
+        while queue:
+            n = queue.pop(0)
+            out.append(self.nodes[n])
+            for m in sorted(adj[n]):
+                indeg[m] -= 1
+                if indeg[m] == 0:
+                    queue.append(m)
+                    queue.sort()
+        return out
+
+
+@dataclass
+class Plan:
+    """A PlanDAG plus an executor mapping (node_id → coroutine).
+
+    `to_workflow()` returns an async function whose body walks the DAG
+    in topological order and issues one ``wf.step`` per node. Callers
+    decorate the returned function with ``@workflow``.
+    """
+
+    dag: PlanDAG
+    executors: dict[str, Callable[..., Awaitable[Any]]] = field(default_factory=dict)
+    name: str = "plan"
+
+    def to_workflow(self) -> Callable[..., Awaitable[dict[str, Any]]]:
+        ordered = self.dag.topological()
+
+        async def _body(wf: Any) -> dict[str, Any]:
+            results: dict[str, Any] = {}
+            for node in ordered:
+                fn = self.executors.get(node.node_id)
+                if fn is None:
+                    # Pure structural nodes (goal/branch/wait/fanout/fanin)
+                    # without an executor become no-op steps that simply
+                    # record their payload.
+                    async def _passthrough(
+                        payload: dict[str, Any] = node.payload,
+                    ) -> dict[str, Any]:
+                        return dict(payload)
+
+                    results[node.node_id] = await wf.step(
+                        f"{node.kind}:{node.node_id}",
+                        _passthrough,
+                    )
+                else:
+                    results[node.node_id] = await wf.step(
+                        f"{node.kind}:{node.node_id}",
+                        fn,
+                    )
+            return results
+
+        _body._hm_workflow_name = self.name  # type: ignore[attr-defined]
+        return _body

hypermind/workflow/repair.py

@@ -0,0 +1,203 @@
+"""Plan-and-repair — replan a workflow when its claim is disputed.
+
+A `RepairPolicy` examines a `WorkflowState` together with a
+`DisputeOutcome` and produces a fresh `Plan` describing how to
+recover. The default policy implements the spec §26 SHOULD-clauses:
+
+* On ``UNRESOLVED_PARTITION``: retry from the last checkpoint with
+  widened evidence (re-run from the most recent successfully-completed
+  step that emitted a CHECKPOINT-marked record; if none, replan from
+  scratch).
+* On ``CLOSED`` against the workflow's claim (i.e. counter-evidence
+  prevailed): emit a compensating plan that runs ``compensate()`` for
+  every committed action.
+
+Wiring into Deliberator: :class:`RepairOnDispute` is an
+:class:`ActionPolicy` subclass that fires when the agent observes a
+``dispute_close`` event whose target_kid matches a workflow-tagged
+claim.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from hypermind.mind.policy import (
+    ActionDecision,
+    ActionKind,
+    ActionPolicy,
+    PolicyContext,
+)
+from hypermind.workflow.plan import Plan, PlanDAG, PlanNode
+
+
+class _DisputeOutcomeLike(Protocol):
+    """Structural shape — accepts the harness `DisputeOutcome`, the
+    simlab `DisputeOutcome`, or any duck-typed equivalent."""
+
+    final_state: str
+    target_kid: bytes
+
+
+@dataclass(frozen=True)
+class WorkflowDisputeContext:
+    """Bundle of inputs a repair policy reasons over."""
+
+    workflow_state: Any  # WorkflowState (avoid import cycle)
+    outcome: _DisputeOutcomeLike
+    workflow_claim_kid: bytes | None = None
+
+
+class RepairPolicy(Protocol):
+    """Decide how to recover from a workflow-affecting dispute close."""
+
+    def repair(self, ctx: WorkflowDisputeContext) -> Plan: ...
+
+
+class DefaultRepairPolicy:
+    """Spec §26 default — retry-on-partition, compensate-on-close."""
+
+    def repair(self, ctx: WorkflowDisputeContext) -> Plan:
+        outcome = ctx.outcome
+        state_name = outcome.final_state
+        wf_state = ctx.workflow_state
+
+        dag = PlanDAG()
+        if state_name == "UNRESOLVED_PARTITION":
+            # Replan: start from the last completed checkpoint.
+            checkpoint_idx = _last_checkpoint_index(wf_state)
+            dag.add_node(
+                PlanNode(
+                    node_id="replan_root",
+                    kind="goal",
+                    payload={
+                        "rule_id": "WF-REPAIR-PARTITION-RETRY",
+                        "from_step_idx": checkpoint_idx,
+                        "widen_evidence": True,
+                    },
+                )
+            )
+            dag.add_node(
+                PlanNode(
+                    node_id="resume",
+                    kind="action",
+                    payload={
+                        "rule_id": "WF-REPAIR-RESUME",
+                        "workflow_id": getattr(wf_state, "workflow_id", ""),
+                    },
+                    depends_on=["replan_root"],
+                )
+            )
+            dag.add_edge("replan_root", "resume", "depends_on")
+            return Plan(dag=dag, name=f"repair-partition-{getattr(wf_state, 'workflow_id', '')}")
+
+        if state_name == "CLOSED":
+            # Compensating plan: one node per completed step in reverse.
+            dag.add_node(
+                PlanNode(
+                    node_id="compensate_root",
+                    kind="goal",
+                    payload={"rule_id": "WF-REPAIR-COMPENSATE"},
+                )
+            )
+            prev = "compensate_root"
+            for i, step in enumerate(reversed(getattr(wf_state, "steps", []))):
+                if getattr(step, "status", "") != "COMPLETED":
+                    continue
+                node_id = f"compensate_{i}"
+                dag.add_node(
+                    PlanNode(
+                        node_id=node_id,
+                        kind="action",
+                        payload={
+                            "rule_id": "WF-REPAIR-COMPENSATE-STEP",
+                            "step_name": step.step_name,
+                            "step_id": step.step_id,
+                        },
+                        depends_on=[prev],
+                    )
+                )
+                dag.add_edge(prev, node_id, "depends_on")
+                prev = node_id
+            return Plan(dag=dag, name=f"repair-close-{getattr(wf_state, 'workflow_id', '')}")
+
+        # Unknown final state — emit a single goal node so the caller
+        # at least sees a structured plan.
+        dag.add_node(
+            PlanNode(
+                node_id="noop",
+                kind="goal",
+                payload={
+                    "rule_id": "WF-REPAIR-NOOP",
+                    "final_state": state_name,
+                },
+            )
+        )
+        return Plan(dag=dag, name="repair-noop")
+
+
+def _last_checkpoint_index(wf_state: Any) -> int:
+    """Return the index of the most recent step whose name starts with
+    ``checkpoint`` (case-insensitive). Returns 0 when none found."""
+    steps = getattr(wf_state, "steps", [])
+    for i, step in enumerate(reversed(steps)):
+        if "checkpoint" in step.step_name.lower():
+            return len(steps) - 1 - i
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# ActionPolicy hook for Deliberator
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RepairOnDispute(ActionPolicy):
+    """Emit an INTENT decision to replan when a workflow-tagged dispute closes.
+
+    The Deliberator passes a :class:`PolicyContext` whose
+    ``recent_observations`` may contain entries shaped::
+
+        {
+          "topic": ...,
+          "kind": "dispute_close",
+          "workflow_id": "abc123",
+          "final_state": "UNRESOLVED_PARTITION" | "CLOSED" | ...,
+          "target_kid": bytes,
+        }
+
+    On a match this policy returns an :class:`ActionDecision` with
+    ``kind=ActionKind.INTENT`` carrying ``rule_id="WF-REPAIR-INTENT"``
+    and the workflow_id + final_state in the payload. Downstream
+    machinery (out of scope for this policy class) is expected to call
+    :class:`DefaultRepairPolicy` to materialise the actual replan.
+    """
+
+    policy: RepairPolicy = None  # type: ignore[assignment]
+    priority: int = 70
+
+    def __post_init__(self) -> None:
+        if self.policy is None:
+            self.policy = DefaultRepairPolicy()
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        for obs in ctx.recent_observations:
+            if obs.get("kind") != "dispute_close":
+                continue
+            wid = obs.get("workflow_id")
+            if not wid:
+                continue
+            final_state = obs.get("final_state", "")
+            return ActionDecision(
+                kind=ActionKind.INTENT,
+                rule_id="WF-REPAIR-INTENT",
+                priority=self.priority,
+                payload={
+                    "workflow_id": wid,
+                    "final_state": final_state,
+                    "target_kid": obs.get("target_kid"),
+                },
+                reason=f"workflow {wid} dispute closed in {final_state!r}",
+            )
+        return None