ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/operator_ui/sheet.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The answer sheet: what the operator answered and ww has not applied yet.
+
+Answers are operator input the engine has not acted on, so they stay out of
+the task's state.  They live in a file of their own under
+``.ww/operator-ui/``, keyed by run and item, written the moment they are
+given and removed once applied.  The file remembers when the task was
+created; a sheet left behind by a reset task is discarded, not applied to
+the task that reuses the ID.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ww.storage import Storage
+
+_FORMAT = "ww.operator-ui"
+
+
+@dataclass(frozen=True)
+class Answer:
+    """One pending answer: the pick, when the stage offers choices, a comment,
+    and when it was given."""
+
+    choice: str | None
+    comment: str
+    at: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {"choice": self.choice, "comment": self.comment, "at": self.at}
+
+    @classmethod
+    def from_dict(cls, data: Any) -> Answer:
+        if not isinstance(data, dict):
+            raise ValueError("an answer must be a mapping")
+        choice = data.get("choice")
+        comment = data.get("comment", "")
+        at = data.get("at")
+        if (
+            (choice is not None and not isinstance(choice, str))
+            or not isinstance(comment, str)
+            or not isinstance(at, str)
+        ):
+            raise ValueError("an answer has a choice or null, a comment, and a time")
+        return cls(choice, comment, at)
+
+
+class AnswerSheet:
+    """The per-task file of answers waiting to be applied."""
+
+    def __init__(self, storage: Storage, task_id: str, task_created_at: str) -> None:
+        self.storage = storage
+        self.task_id = task_id
+        self.task_created_at = task_created_at
+
+    @property
+    def path(self) -> Path:
+        return self.storage.runtime_path / "operator-ui" / f"{self.task_id}.json"
+
+    def read(self, run_id: str | None) -> dict[str, Answer]:
+        """The pending answers of one run, by item ID."""
+        run = self._load().get(run_id or "-", {})
+        return {item_id: Answer.from_dict(value) for item_id, value in run.items()}
+
+    def record(self, run_id: str | None, item_id: str, answer: Answer) -> None:
+        """Record or replace one item's answer in one atomic file replacement."""
+        runs = self._load()
+        runs.setdefault(run_id or "-", {})[item_id] = answer.to_dict()
+        self._save(runs)
+
+    def remove(self, run_id: str | None, item_id: str) -> None:
+        runs = self._load()
+        runs.get(run_id or "-", {}).pop(item_id, None)
+        self._save(runs)
+
+    def _load(self) -> dict[str, dict[str, Any]]:
+        if not self.path.is_file():
+            return {}
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict) or data.get("format") != _FORMAT:
+            raise ValueError(f"{self.path} is not an operator page answer sheet")
+        if data.get("task_created_at") != self.task_created_at:
+            # Left behind by a task that was reset; it belongs to nothing now.
+            return {}
+        runs = data.get("runs", {})
+        if not isinstance(runs, dict) or not all(
+            isinstance(run, dict) for run in runs.values()
+        ):
+            raise ValueError(f"{self.path} has invalid runs")
+        return runs
+
+    def _save(self, runs: dict[str, dict[str, Any]]) -> None:
+        document = {
+            "format": _FORMAT,
+            "task_created_at": self.task_created_at,
+            "runs": runs,
+        }
+        self.storage.locks.atomic_write(
+            self.path, json.dumps(document, indent=2) + "\n"
+        )

ww/operator_ui/view.py

@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The sheet as seen against the plan: what each answer applies to.
+
+A pending answer waits in the answer sheet.  The stage it applies to is the
+plan item with ``ui`` set for that work item, and the answer counts as
+applied once that stage's record is completed.  An applied answer is read
+back from what the engine recorded: the stage's ``chosen`` field and the
+operator's entries for that stage in the interactions file.  One item flow
+may declare one ``ui`` stage, so the pairing is unambiguous.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from ww.execution_models import ExecutionState, PlanItemExecution
+from ww.interactions import InteractionEntry
+from ww.items import WorkItem
+from ww.plan import PlanItem, WorkflowPlan
+
+from .sheet import Answer
+
+
+@dataclass(frozen=True)
+class SheetRow:
+    """One work item on the sheet: its stage, that stage's record, the answer
+    waiting for it, and the answer the engine already recorded."""
+
+    work: WorkItem
+    stage: PlanItem | None
+    record: PlanItemExecution | None
+    pending: Answer | None
+    applied: Answer | None
+
+    @property
+    def processed(self) -> bool:
+        return self.record is not None and self.record.status == "completed"
+
+    @property
+    def answered(self) -> bool:
+        return self.processed or self.pending is not None
+
+    @property
+    def status(self) -> str:
+        if self.processed:
+            return "processed"
+        return "answered" if self.pending is not None else "open"
+
+    def to_dict(self) -> dict[str, object]:
+        shown = self.applied if self.processed else self.pending
+        return {
+            **self.work.to_dict(),
+            "status": self.status,
+            "answer": shown.choice if shown else None,
+            "answer_comment": shown.comment if shown else "",
+            "answered_at": shown.at if shown else None,
+        }
+
+
+def ui_stage(plan: WorkflowPlan) -> PlanItem | None:
+    """The stage whose choices the sheet offers: any ``ui`` stage of the plan."""
+    return next((entry for entry in plan.items if entry.ui), None)
+
+
+def sheet_rows(
+    plan: WorkflowPlan,
+    state: ExecutionState,
+    items: tuple[WorkItem, ...],
+    answers: Mapping[str, Answer],
+    entries: tuple[InteractionEntry, ...],
+) -> tuple[SheetRow, ...]:
+    records = {
+        record.plan_item_id: record
+        for record in (*state.execution_history, *state.item_executions)
+    }
+    stages = {
+        entry.item_id: entry for entry in plan.items if entry.ui and entry.item_id
+    }
+    rows = []
+    for work in items:
+        stage = stages.get(work.id)
+        record = records.get(stage.id) if stage else None
+        applied = (
+            _applied(stage, record, state.run_id, entries)
+            if stage and record and record.status == "completed"
+            else None
+        )
+        rows.append(SheetRow(work, stage, record, answers.get(work.id), applied))
+    return tuple(rows)
+
+
+def _applied(
+    stage: PlanItem,
+    record: PlanItemExecution,
+    run_id: str | None,
+    entries: tuple[InteractionEntry, ...],
+) -> Answer:
+    """What the engine recorded for a completed stage, read back as an answer."""
+    own = [
+        entry
+        for entry in entries
+        if (entry.run_id, entry.step, entry.item_id, entry.speaker)
+        == (run_id, stage.name, stage.item_id, "operator")
+        and not entry.text.startswith("Choice: ")
+    ]
+    comment = own[-1].text if own else ""
+    at = own[-1].at if own else (record.completed_at or "")
+    return Answer(record.chosen, comment, at)

ww/output.py

@@ -0,0 +1,339 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Presentation helpers for command-line workflow results."""
+
+from __future__ import annotations
+
+import json
+import shutil
+import textwrap
+
+from ww import BETA_NOTICE
+from ww.actions import InstructionContent, InstructionContext, PlannedAction, actions
+from ww.instructions import Instruction
+from ww.operations import ChildWorkflowRun, LoopBoundary, WorkflowHandoff
+from ww.output_adapters import (
+    JsonOutputAdapter,
+    MarkdownOutputAdapter,
+    OutputAdapter,
+)
+from ww.output_adapters.markdown import requested_setting_lines
+from ww.plan import PlanItem, WorkflowPlan
+from ww.results import InitializationResult, ItemUpdateResult, ResetResult, TaskStatus
+
+_MARKDOWN = MarkdownOutputAdapter()
+_JSON = JsonOutputAdapter()
+
+
+def _adapter_for(json_output: bool) -> OutputAdapter:
+    """Choose the built-in output adapter for a CLI invocation."""
+    return _JSON if json_output else _MARKDOWN
+
+
+def render(instruction: Instruction, json_output: bool) -> str:
+    """Render an instruction using the selected adapter."""
+    return _adapter_for(json_output).render_instruction(instruction)
+
+
+def render_status(status: TaskStatus, json_output: bool) -> str:
+    """Render the small status projection for people or machines."""
+    if json_output:
+        return json.dumps(status.to_dict(), indent=2)
+    values = status.to_dict()
+    return (
+        "\n".join(f"{key.replace('_', ' ')}: {value}" for key, value in values.items())
+        + "\n"
+    )
+
+
+def render_reset(result: ResetResult, json_output: bool) -> str:
+    """Render a reset outcome using the selected adapter."""
+    return _adapter_for(json_output).render_reset(result)
+
+
+def render_initialization(result: InitializationResult, json_output: bool) -> str:
+    """Render an initialization outcome using the selected adapter."""
+    return _adapter_for(json_output).render_initialization(result)
+
+
+# The wordmark is 101 columns wide. Below that a terminal wraps every row of
+# it into unreadable halves, so a narrow one gets a compact mark instead.
+WORDMARK_COLUMNS = 101
+COMPACT_WELCOME = (
+    "  ██  ██   ██  ██\n  ██  ██   ██  ██   ww · agentic workflows\n  ░█████░ ░█████░\n"
+)
+
+
+def render_initialization_welcome(json_output: bool, columns: int | None = None) -> str:
+    """Render the interactive init welcome before collecting project choices."""
+    if json_output:
+        return ""
+    width = columns if columns is not None else shutil.get_terminal_size((80, 24))[0]
+    if width < WORDMARK_COLUMNS:
+        return COMPACT_WELCOME + "\n" + _beta_notice(width)
+    return _WORDMARK + _beta_notice(width)
+
+
+def _beta_notice(width: int) -> str:
+    """The beta notice under the welcome, wrapped to the terminal."""
+    lines = textwrap.wrap(
+        BETA_NOTICE,
+        max(40, width - 2),
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+    return "\n".join(lines) + "\n\n"
+
+
+_WORDMARK = (
+    "█░░░█ █░░░█\n"
+    "█░░░█ █░░░█\n"
+    "█░░░█ █░░░█\n"
+    "█░█░█ █░█░█\n"
+    "█░█░█ █░█░█\n"
+    "█░█░█ █░█░█\n"
+    "░█░█░ ░█░█░\n\n"
+    "░███░ ░████ █████ █░░░█ █████ █████ ░████ ░░░░░ "
+    "█░░░█ ░███░ ████░ █░░░█ █████ █░░░░ ░███░ █░░░█ ░████\n"
+    "█░░░█ █░░░░ █░░░░ ██░░█ ░░█░░ ░░█░░ █░░░░ ░░░░░ "
+    "█░░░█ █░░░█ █░░░█ █░░█░ █░░░░ █░░░░ █░░░█ █░░░█ █░░░░\n"
+    "█░░░█ █░░░░ █░░░░ ██░░█ ░░█░░ ░░█░░ █░░░░ ░░░░░ "
+    "█░░░█ █░░░█ █░░░█ █░█░░ █░░░░ █░░░░ █░░░█ █░░░█ █░░░░\n"
+    "█████ █░███ ████░ █░█░█ ░░█░░ ░░█░░ █░░░░ ░░░░░ "
+    "█░█░█ █░░░█ ████░ ██░░░ ████░ █░░░░ █░░░█ █░█░█ ░███░\n"
+    "█░░░█ █░░░█ █░░░░ █░░██ ░░█░░ ░░█░░ █░░░░ ░░░░░ "
+    "█░█░█ █░░░█ █░█░░ █░█░░ █░░░░ █░░░░ █░░░█ █░█░█ ░░░░█\n"
+    "█░░░█ █░░░█ █░░░░ █░░██ ░░█░░ ░░█░░ █░░░░ ░░░░░ "
+    "█░█░█ █░░░█ █░░█░ █░░█░ █░░░░ █░░░░ █░░░█ █░█░█ ░░░░█\n"
+    "█░░░█ ░████ █████ █░░░█ ░░█░░ █████ ░████ ░░░░░ "
+    "░█░█░ ░███░ █░░░█ █░░░█ █░░░░ █████ ░███░ ░█░█░ ████░\n\n"
+)
+
+
+def render_item_update(result: ItemUpdateResult, json_output: bool) -> str:
+    """Render an item update acknowledgement and its immediate next action."""
+    if json_output:
+        return json.dumps(
+            {
+                "item": result.item.to_dict(),
+                "continuation_command": result.continuation_command,
+            },
+            indent=2,
+        )
+    lines = [f"> Item `{result.item.id}` updated successfully."]
+    if result.continuation_command:
+        lines.extend(
+            [
+                "",
+                "### Continue with completion",
+                "",
+                "Run:",
+                "",
+                "```console",
+                result.continuation_command,
+                "```",
+            ]
+        )
+    return "\n".join(lines) + "\n"
+
+
+def render_plan(plan: WorkflowPlan, json_output: bool) -> str:
+    """Render a compiled plan for either people or programmatic consumers."""
+    if json_output:
+        return json.dumps(plan.to_dict(), indent=2) + "\n"
+    lines = [f"# Workflow plan — `{plan.workflow}`", ""]
+    if plan.workflow_description:
+        lines.extend([f"> {plan.workflow_description}", ""])
+    context = [f"**Agent:** `{plan.agent}`"]
+    if plan.task_id:
+        context.append(f"**Task ID:** `{plan.task_id}`")
+    if plan.modes:
+        context.append("**Modes:** " + ", ".join(f"`{mode}`" for mode in plan.modes))
+    lines.extend([" · ".join(context), ""])
+    if plan.handoff:
+        lines.extend(
+            [
+                "> **Handoff workflow:** its final workflow transition starts the "
+                "next workflow and does not return here.",
+                "",
+            ]
+        )
+    for item in plan.items:
+        lines.extend([f"## {item.position}. {item.name}", ""])
+        lines.extend(
+            [
+                f"**Stage:** {_stage_label(item.phase)}  ",
+                f"**Workflow step:** `{item.step}`  ",
+                f"**Owner:** `{item.owner}`  ",
+                f"**Execution:** `{item.execution}`",
+                "",
+            ]
+        )
+        if item.explicit and item.owner == "agent":
+            lines.extend(["**Explicit work guidance:** enabled", ""])
+        if item.parent:
+            lines.extend([f"**Parent step:** `{item.parent}`", ""])
+        if item.owner == "ww" and item.execution == "automatic":
+            if not item.requires_agent_input:
+                lines.extend(
+                    [
+                        "> **Fully automated by ww:** ww executes this operation "
+                        "without asking the agent to act. Commands below are shown "
+                        "for inspection.",
+                        "",
+                    ]
+                )
+            failure_instruction = (
+                "ww explicitly assigns the agent to fix the cause, then ww retries "
+                "the command."
+                if item.on_failure == "fix"
+                else "ww explicitly instructs the agent to hand over to the operator."
+            )
+            lines.extend([f"> **On failure:** {failure_instruction}", ""])
+        lines.extend(_item_flow_lines(item))
+        lines.extend(
+            [
+                "**Requested execution settings**",
+                "",
+                f"- Agent: `{item.requested_agent or plan.agent}`",
+                *requested_setting_lines(
+                    item.requested_model, item.requested_reasoning
+                ),
+                "",
+            ]
+        )
+        if item.owner == "ww" and not item.requires_agent_input:
+            lines.extend(
+                [
+                    "> Execution settings are retained for inspection and ignored "
+                    "for this ww-owned operation.",
+                    "",
+                ]
+            )
+        if isinstance(item.operation, PlannedAction):
+            implementation = (
+                actions.get(item.operation.identifier)
+                if actions.contains(item.operation.identifier)
+                else None
+            )
+            content = (
+                implementation.instruction(
+                    item.operation.payload,
+                    InstructionContext(item.description, item.name, {}),
+                )
+                if implementation is not None
+                else InstructionContent(
+                    item.description or item.name,
+                    (
+                        f"**Unavailable action:** `{item.operation.identifier}`",
+                        "",
+                        "**Saved payload**",
+                        "",
+                        *(
+                            "    " + line
+                            for line in json.dumps(
+                                item.operation.payload, indent=2, sort_keys=True
+                            ).splitlines()
+                        ),
+                        "",
+                    ),
+                )
+            )
+        else:
+            markdown: tuple[str, ...]
+            if isinstance(item.operation, LoopBoundary):
+                markdown = (
+                    "**Loop control**",
+                    "",
+                    f"- Boundary: `{item.operation.boundary}`",
+                    f"- Maximum rounds: `{item.operation.max_times}`",
+                    "",
+                )
+            elif isinstance(item.operation, WorkflowHandoff):
+                markdown = ("**Start workflow**", "", f"`{item.operation.target}`", "")
+            elif isinstance(item.operation, ChildWorkflowRun):
+                markdown = (
+                    "**Child workflow**",
+                    "",
+                    f"`{item.operation.workflow}`",
+                    "",
+                )
+            else:  # pragma: no cover - PlanItem validates the union
+                markdown = ()
+            content = InstructionContent(item.description or item.name, markdown)
+        if item.description and content.show_context:
+            lines.extend(["**Context**", "", item.description, ""])
+        lines.extend(content.markdown or ("**Prompt**", "", "", ""))
+        if item.provide:
+            heading = (
+                "**Required input from the agent**"
+                if item.requires_agent_input
+                else "**Required input**"
+            )
+            lines.extend([heading, ""])
+            lines.extend(
+                f"- `{value.name}`"
+                + (f" — {value.description}" if value.description else "")
+                for value in item.provide
+            )
+            lines.append("")
+            if item.requires_agent_input:
+                lines.extend(
+                    [
+                        "> ww runs this command automatically after these values are "
+                        "supplied through the completion flow.",
+                        "",
+                    ]
+                )
+        if item.save_metadata:
+            scopes = {value.scope for value in item.save_metadata}
+            scope_label = (
+                f"{next(iter(scopes)).title()} metadata"
+                if len(scopes) == 1
+                else "Task and project metadata"
+            )
+            lines.extend([f"**{scope_label} to preserve**", ""])
+            lines.extend(
+                f"- `{'project_metadata' if value.scope == 'project' else 'metadata'}"
+                f".{value.key}`"
+                + (f" — {value.description}" if value.description else "")
+                for value in item.save_metadata
+            )
+            lines.append("")
+        lines.extend(content.after_shared)
+    return "\n".join(lines) + "\n"
+
+
+def _stage_label(phase: str) -> str:
+    return {
+        "before_start_workflow": "Before the workflow starts",
+        "before_start": "Before this step starts",
+        "step": "Perform this workflow step",
+        "before_complete": "Before this step is completed",
+        "after_complete": "After this step is completed",
+        "before_complete_workflow": "Before the workflow is completed",
+    }[phase]
+
+
+def _item_flow_lines(item: PlanItem) -> list[str]:
+    """Describe an item's role in an ``items`` step, if it has one."""
+    if item.item_operation == "collect":
+        lines = ["**Item collection:** splits the work into items"]
+        if item.split_instruction:
+            lines[0] += "  "
+            lines.append(f"**Splitting guidance:** {item.split_instruction}")
+        return [*lines, ""]
+    if item.child_operation == "collect" and item.phase == "step":
+        lines = ["**Child collection:** splits the work into child tasks"]
+        if item.split_instruction:
+            lines[0] += "  "
+            lines.append(f"**Splitting guidance:** {item.split_instruction}")
+        return [*lines, ""]
+    if item.item_template and item.child_stage is not None:
+        return ["**Per-child stage:** repeats for every collected child, in turn", ""]
+    if item.item_template:
+        return [
+            "**Per-item stage:** repeats for every collected item  ",
+            f"**Item assignment:** `{item.item_assignment}`",
+            "",
+        ]
+    return []

ww/output_adapters/__init__.py

@@ -0,0 +1,12 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Output adapters bundled with ww."""
+
+from ww.output_adapters.base import OutputAdapter
+from ww.output_adapters.json_adapter import JsonOutputAdapter
+from ww.output_adapters.markdown import MarkdownOutputAdapter
+
+__all__ = [
+    "JsonOutputAdapter",
+    "MarkdownOutputAdapter",
+    "OutputAdapter",
+]

ww/output_adapters/base.py

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Contracts for rendering ww command results."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ww.instructions import Instruction
+from ww.results import InitializationResult, ResetResult
+
+
+class OutputAdapter(ABC):
+    """Render workflow results for one output representation."""
+
+    @abstractmethod
+    def render_instruction(self, instruction: Instruction) -> str:
+        """Render an instruction."""
+
+    @abstractmethod
+    def render_reset(self, result: ResetResult) -> str:
+        """Render a reset outcome."""
+
+    @abstractmethod
+    def render_initialization(self, result: InitializationResult) -> str:
+        """Render an initialization outcome."""

ww/output_adapters/json_adapter.py

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""JSON output adapter."""
+
+from __future__ import annotations
+
+import json
+
+from ww.instructions import Instruction
+from ww.output_adapters.base import OutputAdapter
+from ww.results import INITIALIZATION_NEXT_STEP, InitializationResult, ResetResult
+
+
+class JsonOutputAdapter(OutputAdapter):
+    """Render stable JSON for programmatic consumers."""
+
+    def render_instruction(self, instruction: Instruction) -> str:
+        return json.dumps(instruction.to_dict(), indent=2)
+
+    def render_reset(self, result: ResetResult) -> str:
+        return json.dumps(
+            {"task_id": result.task_id, "removed": result.removed}, indent=2
+        )
+
+    def render_initialization(self, result: InitializationResult) -> str:
+        return json.dumps(
+            {
+                "root": result.root,
+                "workflow_config": "ww.yaml",
+                "project_config": "ww.json",
+                "launcher": "ww",
+                "created": list(result.created),
+                "preserved": list(result.preserved),
+                "manual_actions": list(result.actions),
+                "next_steps": [INITIALIZATION_NEXT_STEP],
+            },
+            indent=2,
+        )