workgraph 0.3.3__py3-none-any.whl

workgraph/workflow.py

@@ -0,0 +1,263 @@
+"""Workflow discovery, loading, validation, and mermaid rendering."""
+
+import math
+import re
+import tomllib
+from pathlib import Path
+from typing import Any, NoReturn
+
+from workgraph.harness import HARNESS_NAMES
+
+END = "END"
+LIMIT = "LIMIT"
+RESERVED_NAMES = frozenset({END, LIMIT})
+AGENT_SETTINGS = ("harness", "model", "effort")
+HARNESS_SETTINGS = {"allowed_tools": "claude", "sandbox": "codex", "web_search": "codex"}
+NODE_KINDS = ("agent", "command", "map", "gate")
+TIME_KEYS = ("time_soft", "time_hard")
+BUDGET_KEYS = (*TIME_KEYS, "cost")
+DURATION_PATTERN = re.compile(r"(\d+(?:\.\d+)?)([smh]?)")
+DURATION_UNITS = {"": 1, "s": 1, "m": 60, "h": 3600}
+
+
+class WorkflowError(Exception):
+    """A workflow failed to load or validate."""
+
+
+def load_workflow(workflow_name: str) -> dict[str, Any]:
+    """Find the workflow by name, parse it, and validate every load-time rule."""
+    path = _find_workflow_file(workflow_name)
+    with path.open("rb") as file:
+        try:
+            workflow = tomllib.load(file)
+        except tomllib.TOMLDecodeError as error:
+            raise WorkflowError(f"{workflow_name}: invalid TOML: {error}") from error
+    _validate_workflow(workflow_name, workflow)
+    if "budget" in workflow:
+        workflow["budget"] = _validate_budget(workflow_name, workflow["budget"])
+    return workflow
+
+
+def parse_duration(duration: object) -> float:
+    """Return the seconds a duration denotes: a positive number, or a string with unit s, m, or h.
+
+    parse_duration raises ValueError for any other input.
+    """
+    if isinstance(duration, int | float) and not isinstance(duration, bool):
+        seconds = float(duration)
+    elif isinstance(duration, str) and (match := DURATION_PATTERN.fullmatch(duration)):
+        seconds = float(match[1]) * DURATION_UNITS[match[2]]
+    else:
+        raise ValueError(
+            f"invalid duration {duration!r}: expected seconds or a number with unit s, m, or h"
+        )
+    if seconds <= 0:
+        raise ValueError(f"invalid duration {duration!r}: must be positive")
+    return seconds
+
+
+def parse_cost(cost: object) -> float:
+    """Return the USD a cost denotes: a positive number, or its string form.
+
+    parse_cost raises ValueError for any other input.
+    """
+    message = f"invalid cost {cost!r}: expected a positive USD number"
+    if isinstance(cost, bool) or not isinstance(cost, int | float | str):
+        raise ValueError(message)
+    try:
+        usd = float(cost)
+    except ValueError:
+        raise ValueError(message) from None
+    if not usd > 0:
+        raise ValueError(message)
+    return usd
+
+
+def resolve_agent_settings(
+    node_definition: dict[str, Any], defaults: dict[str, Any]
+) -> dict[str, Any]:
+    """Return the agent settings of a node: its own value, else the default."""
+    settings = {key: node_definition.get(key, defaults.get(key)) for key in AGENT_SETTINGS}
+    settings.update(
+        (key, node_definition.get(key, defaults.get(key)))
+        for key, owner in HARNESS_SETTINGS.items()
+        if owner == settings["harness"] and (key in node_definition or key in defaults)
+    )
+    return settings
+
+
+def render_mermaid(workflow: dict[str, Any]) -> str:
+    """Render a validated workflow as a bare mermaid flowchart.
+
+    The start node is drawn as a stadium and a gate node as a hexagon so
+    every viz style (unicode, ascii, mermaid) marks them.
+    """
+    start_node = workflow["start"]
+    lines = ["flowchart TD", f"    {start_node}([{start_node}])"]
+    for node_name, node_definition in workflow["nodes"].items():
+        if "gate" in node_definition:
+            lines.append(f"    {node_name}{{{{{node_name}}}}}")
+        for fanned_out_node in node_definition.get("map", []):
+            lines.append(f"    {node_name} --> {fanned_out_node}")
+        for outcome, target in node_definition.get("transitions", {}).items():
+            lines.append(f"    {node_name} -->|{outcome}| {target}")
+    return "\n".join(lines)
+
+
+def list_definition_directories() -> tuple[Path, Path, Path]:
+    """Return where definitions resolve from, in order: invocation directory, home, package."""
+    return (
+        Path.cwd() / ".workgraph",
+        Path.home() / ".workgraph",
+        Path(__file__).parent / "definitions",
+    )
+
+
+def _find_workflow_file(workflow_name: str) -> Path:
+    for definition_directory in list_definition_directories():
+        path = definition_directory / "workflows" / f"{workflow_name}.toml"
+        if path.is_file():
+            return path
+    raise WorkflowError(
+        f"workflow '{workflow_name}' not found in a .workgraph/workflows directory of the"
+        " invocation directory or the home directory, nor among the bundled workflows"
+    )
+
+
+def _validate_workflow(workflow_name: str, workflow: dict[str, Any]) -> None:
+    nodes = workflow.get("nodes", {})
+    start_node = workflow.get("start")
+    if start_node is None:
+        raise WorkflowError(f"{workflow_name}: missing top-level 'start'")
+    if start_node not in nodes:
+        raise WorkflowError(f"{workflow_name}: start node '{start_node}' does not exist")
+    fanned_out_by = _collect_fanned_out(workflow_name, nodes)
+    if start_node in fanned_out_by:
+        raise WorkflowError(
+            f"{workflow_name}: start node '{start_node}' is fanned out by map node '{fanned_out_by[start_node]}'"
+        )
+    defaults = workflow.get("defaults", {})
+    for node_name, node_definition in nodes.items():
+        _validate_node(workflow_name, nodes, defaults, fanned_out_by, node_name, node_definition)
+
+
+def _validate_budget(workflow_name: str, budget: dict[str, Any]) -> dict[str, float]:
+    """Check the budget keys and return the time limits in seconds and the cost limit in USD."""
+    if not isinstance(budget, dict):
+        raise WorkflowError(f"{workflow_name}: [budget] must be a table")
+    limits: dict[str, float] = {}
+    for key, value in budget.items():
+        if key not in BUDGET_KEYS:
+            raise WorkflowError(f"{workflow_name}: [budget]: unknown key '{key}'")
+        try:
+            limits[key] = parse_cost(value) if key == "cost" else parse_duration(value)
+        except ValueError as error:
+            raise WorkflowError(f"{workflow_name}: [budget]: {key}: {error}") from error
+    if limits.get("time_hard", math.inf) < limits.get("time_soft", 0):
+        raise WorkflowError(f"{workflow_name}: [budget]: time_hard is below time_soft")
+    return limits
+
+
+def _collect_fanned_out(workflow_name: str, nodes: dict[str, Any]) -> dict[str, str]:
+    """Map each fanned-out node to its map node, checking the fan-out lists."""
+    fanned_out_by: dict[str, str] = {}
+    for node_name, node_definition in nodes.items():
+        for fanned_out_node in node_definition.get("map", []):
+            if fanned_out_node not in nodes:
+                raise WorkflowError(
+                    f"{workflow_name}: node '{node_name}': fanned-out node '{fanned_out_node}' does not exist"
+                )
+            for kind in ("map", "gate"):
+                if kind in nodes[fanned_out_node]:
+                    raise WorkflowError(
+                        f"{workflow_name}: node '{node_name}': fanned-out node '{fanned_out_node}'"
+                        f" is a {kind} node"
+                    )
+            if fanned_out_node in fanned_out_by:
+                raise WorkflowError(
+                    f"{workflow_name}: node '{node_name}': fanned-out node '{fanned_out_node}'"
+                    f" is already fanned out by map node '{fanned_out_by[fanned_out_node]}'"
+                )
+            fanned_out_by[fanned_out_node] = node_name
+    return fanned_out_by
+
+
+def _validate_node(
+    workflow_name: str,
+    nodes: dict[str, Any],
+    defaults: dict[str, Any],
+    fanned_out_by: dict[str, str],
+    node_name: str,
+    node_definition: dict[str, Any],
+) -> None:
+    def fail(rule: str) -> NoReturn:
+        raise WorkflowError(f"{workflow_name}: node '{node_name}': {rule}")
+
+    if node_name in RESERVED_NAMES:
+        fail(f"'{node_name}' is reserved and cannot name a node")
+    if node_name.endswith("#"):
+        fail("a node name cannot end with '#'")
+    if sum(kind in node_definition for kind in NODE_KINDS) != 1:
+        fail("declare exactly one of 'agent', 'command', 'map', or 'gate'")
+    if "agent" not in node_definition:
+        kind = next(kind for kind in NODE_KINDS if kind in node_definition)
+        if "outcomes" in node_definition:
+            fail(f"a {kind} node cannot declare 'outcomes'")
+        for setting in (*AGENT_SETTINGS, *HARNESS_SETTINGS):
+            if setting in node_definition:
+                fail(f"a {kind} node cannot declare '{setting}'")
+        if kind == "map":
+            if not node_definition["map"]:
+                fail("'map' must list at least one node")
+            if node_definition.get("resolve") not in ("any", "all"):
+                fail("'resolve' must be 'any' or 'all'")
+        if kind == "gate":
+            if not isinstance(node_definition["gate"], str) or not node_definition["gate"]:
+                fail("'gate' must be a non-empty question")
+            if "limits" in node_definition:
+                fail("a gate node cannot declare 'limits'")
+        outcomes = ["accept", "reject"] if kind == "gate" else ["pass", "fail"]
+    else:
+        outcomes = node_definition.get("outcomes", [])
+        if not outcomes:
+            fail("an agent node must declare a non-empty 'outcomes' list")
+        for outcome in outcomes:
+            if outcome in RESERVED_NAMES:
+                fail(f"'{outcome}' is reserved and cannot name an outcome")
+        settings = resolve_agent_settings(node_definition, defaults)
+        for setting in AGENT_SETTINGS:
+            if settings[setting] is None:
+                fail(f"'{setting}' is set neither on the node nor in [defaults]")
+        harness = settings["harness"]
+        if harness not in HARNESS_NAMES:
+            accepted = ", ".join(repr(name) for name in HARNESS_NAMES)
+            fail(f"harness '{harness}' is not supported; accepted: {accepted}")
+        for setting, owner in HARNESS_SETTINGS.items():
+            if setting in node_definition and harness != owner:
+                fail(f"'{setting}' belongs to harness '{owner}', but the node uses '{harness}'")
+    if node_name in fanned_out_by:
+        for field in ("transitions", "limits"):
+            if field in node_definition:
+                fail(f"a fanned-out node cannot declare '{field}'")
+        if "pass" not in outcomes:
+            fail("a fanned-out node must have 'pass' in its outcomes")
+        return
+    limits = node_definition.get("limits", {})
+    if "reset" in limits:
+        if "visits" not in limits:
+            fail("'reset' requires 'visits' in the same limits table")
+        if limits["reset"] not in outcomes:
+            fail(f"reset outcome '{limits['reset']}' is not an outcome of the node")
+    transitions = node_definition.get("transitions", {})
+    for outcome in outcomes:
+        if outcome not in transitions:
+            fail(f"missing a transition for outcome '{outcome}'")
+    for transition_key, target in transitions.items():
+        if transition_key != LIMIT and transition_key not in outcomes:
+            fail(f"transition key '{transition_key}' is not an outcome of the node")
+        if target != END and target not in nodes:
+            fail(f"transition target '{target}' does not exist")
+        if target in fanned_out_by:
+            fail(
+                f"transition target '{target}' is fanned out by map node '{fanned_out_by[target]}'"
+            )

workgraph-0.3.3.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: workgraph
+Version: 0.3.3
+Summary: Graph workflow orchestrator.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: termaid[rich]>=0.8.0
+Requires-Dist: tomlkit>=0.15.1
+Requires-Python: >=3.12
+Project-URL: Changelog, https://github.com/sylmarien/workgraph/blob/main/CHANGELOG.md
+Project-URL: Repository, https://github.com/sylmarien/workgraph
+Description-Content-Type: text/markdown
+
+# workgraph
+
+workgraph orchestrates development workflows declared as graphs. Nodes run
+agents or commands; a node's outcome selects the transition to follow. The
+developer writes the workflow once and starts a run from a harness session
+with `/workgraph`. The run prints one progress line per node. One command
+resumes a stopped run.
+
+The CLI bundles workflow and agent definitions; [Workflow
+files](docs/workflow-files.md) lists them. This repository runs the bundled
+`wg` workflow on itself:
+
+```mermaid
+flowchart TD
+    design([design])
+    design -->|done| approve-design
+    approve-design -->|accept| plan
+    approve-design -->|reject| design
+    plan -->|done| approve-plan
+    approve-plan -->|accept| implement
+    approve-plan -->|reject| plan
+    implement -->|done| test
+    test -->|pass| review
+    test -->|fail| implement
+    review --> code-review
+    review --> overengineering-review
+    review -->|pass| pr
+    review -->|fail| review-loop
+    review-loop -->|pass| implement
+    review-loop -->|fail| implement
+    review-loop -->|LIMIT| summary
+    summary -->|done| pr
+    pr -->|done| END
+```
+
+## Install
+
+As a Claude Code plugin:
+
+```
+/plugin marketplace add sylmarien/workgraph
+/plugin install workgraph@workgraph
+```
+
+Installing the plugin adds the `/workgraph` skill. The plugin's `install`
+skill installs the CLI with `uv`, and its `update` skill upgrades it. Both
+check that `uv` is on `PATH` and install nothing else.
+
+The CLI bundles workflow and agent definitions. A user's own definitions
+shadow them; see [Workflow files](docs/workflow-files.md) for the bundled
+definitions and the resolution order.
+
+As a Codex plugin:
+
+```sh
+codex plugin marketplace add sylmarien/workgraph
+codex plugin add workgraph@workgraph
+```
+
+Start a new Codex session and invoke `$workgraph <workflow> "#<issue>"`.
+The plugin shares the install, update, and run skills with the Claude Code
+plugin. The bundled workflows run nodes on the Claude harness, so they
+require `claude` and `uv` on `PATH` in Codex too.
+
+Codex reads the repository's existing marketplace at
+`.claude-plugin/marketplace.json` and its manifest at
+`.codex-plugin/plugin.json`. Both plugins ship in the same Git release.
+The patch, minor, and major release workflows update both manifests and
+the CLI to the same version. See the
+[Codex packaging documentation](https://developers.openai.com/plugins/build/plugins).
+
+Without the plugin:
+
+```sh
+uv tool install workgraph
+```
+
+`pip install workgraph` installs the same package from PyPI.
+`uv tool upgrade workgraph` upgrades it. Requires Python 3.12+. An agent
+node additionally requires the CLI of its harness on `PATH`: `claude` for
+`harness = "claude"`, `codex` for `harness = "codex"`.
+
+## Example
+
+```sh
+workgraph run wg "#12"
+```
+
+```
+design: done
+approve-design: parked
+parked at approve-design: Plan from this design? · spent 1m20s · $0.15
+Review material from design:
+https://github.com/sylmarien/workgraph/issues/12#issuecomment-5550441682
+```
+
+```sh
+workgraph resume --decision accept
+```
+
+```
+approve-design: accept
+plan: done
+approve-plan: parked
+parked at approve-plan: Implement this plan? · spent 4m05s · $0.42
+Review material from plan:
+<the plan>
+```
+
+`workgraph resume --decision accept` delivers the decision and resumes the
+run.
+
+## Reference
+
+- [Commands](docs/commands.md)
+- [Workflow files](docs/workflow-files.md)
+- [Agent definitions](docs/agent-definitions.md)
+
+## Development
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run mypy && uv run pytest
+```
+
+The dogfood workflow runs the same gate: `workgraph run wg "#<issue>"`.

workgraph-0.3.3.dist-info/RECORD

@@ -0,0 +1,23 @@
+workgraph/__init__.py,sha256=-98aA3TsgzNO0jLI6qXojt-dAKhg0jJJxHAgMgoaqCo,35
+workgraph/claude.py,sha256=I6Beld-t8AfNl1K1QY9WA9RHzlM5Gi4uEWb3lkBoenY,3841
+workgraph/cli.py,sha256=bRXDLmZMelm-RCb-XUuzMMmIharVyOFTabBv9j68PYo,12872
+workgraph/codex.py,sha256=6AG2rQtY31oH4iivbxTnrRwA4882wYEPQozs9wazgbI,9589
+workgraph/definitions/agents/wg_code-review.md,sha256=q5mX_DIkOr_KfmnJH6BXYAm-1ME76RAHCSRUiabMJus,576
+workgraph/definitions/agents/wg_design.md,sha256=mbNULWzJFtkhJ1JLCMui0YePyFsBFnygpdUYOnbd0cU,2960
+workgraph/definitions/agents/wg_implement.md,sha256=ZhhKkmrta9hweXRp1BadAlrx4nk9QG6fHvbvmAediH0,1576
+workgraph/definitions/agents/wg_overengineering-review.md,sha256=tBhBTygGQvHW5eA592GGmp586WAyHFsjZ1dcNU6RzVc,508
+workgraph/definitions/agents/wg_plan.md,sha256=GZq-2isG-en2fZ1eKTVDVE5zJiOIBYQvs3NT3XmqBWo,3798
+workgraph/definitions/agents/wg_pr.md,sha256=oNGkLbdTehraFUEV_htbKdpCJA2q7GUMuUAll6OB7M4,1664
+workgraph/definitions/agents/wg_summarize-review.md,sha256=17Qe-3fBEyjTavaCtGDNACrYxQn3Cushu2_2dPDeFRg,451
+workgraph/definitions/workflows/wg.toml,sha256=kzSY_6qoetRHxpV1NwkE1U6k-HoDycVJlxoSBz3XL48,1751
+workgraph/definitions/workflows/wg_codex.toml,sha256=O3UVY0_G_UNz5IpFZu_dOhqDRIcrgoJHapUzMSLwGgc,1873
+workgraph/graph.py,sha256=sm6oZAHhNyCQ77Xb3FnjIaUEYpH16mReTjqHnNK1Ya0,14332
+workgraph/harness.py,sha256=xa2_lYXWkWpzcTwrJdBzpRBmzFUtIDY09pVhnIu9JQQ,3993
+workgraph/run.py,sha256=tD_8RKbKYmkl0vxaX69rN9D8ZU4Z9b286F5du5G3zkk,36316
+workgraph/show.py,sha256=PJP7CnjUjSSFySztZQej7XMGOtlo6fGlXXkIsZpYC7w,29516
+workgraph/workflow.py,sha256=1kvBqkjwN8_O-byaf68IQ35gRYHTVVUxs-uI_AJXz6A,11575
+workgraph-0.3.3.dist-info/licenses/LICENSE,sha256=Giuyc4C51f_S6HrS6dHoqObZR76kzgYkqYbmNe7_wGg,1071
+workgraph-0.3.3.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+workgraph-0.3.3.dist-info/entry_points.txt,sha256=Tjt1r5Q4yUb4AkbmXj8A-wNQAT6WcxtcXEiFu9lofc4,50
+workgraph-0.3.3.dist-info/METADATA,sha256=rmzHmAzAfG50TXjG1i0EQ_850qp-NDIVZwhtV4W5uqI,4030
+workgraph-0.3.3.dist-info/RECORD,,

workgraph-0.3.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.24
+Root-Is-Purelib: true
+Tag: py3-none-any

workgraph-0.3.3.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+workgraph = workgraph.cli:main
+

workgraph-0.3.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxime Schmitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.