openadapt-flow 0.1.0__py3-none-any.whl

openadapt_flow/__init__.py

@@ -0,0 +1,17 @@
+"""openadapt-flow: record once, compile, replay deterministically, heal on drift."""
+
+__version__ = "0.1.0"
+
+from openadapt_flow.ir import (  # noqa: F401
+    ActionKind,
+    Anchor,
+    HealEvent,
+    Landmark,
+    Postcondition,
+    PostconditionKind,
+    Resolution,
+    RunReport,
+    Step,
+    StepResult,
+    Workflow,
+)

openadapt_flow/__main__.py

@@ -0,0 +1,349 @@
+"""openadapt-flow CLI.
+
+Subcommands (thin wrappers over the module APIs; sibling modules are
+imported lazily inside each handler so ``--help`` always works):
+
+- ``demo-record`` — serve MockMed locally and record the canonical demo.
+- ``compile`` — compile a recording directory into a workflow bundle.
+- ``replay`` — replay a bundle; serves the bundled MockMed demo app when no
+  ``--url`` is given (with optional ``--drift`` to demonstrate healing).
+- ``bench`` — replay a bundle N times against MockMed and aggregate.
+- ``emit-skill`` — emit an Agent Skills folder for a bundle.
+- ``emit-mcp`` — emit a standalone MCP ``server.py`` for a bundle.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+_VIEWPORT = {"width": 1280, "height": 800}
+
+
+def _parse_params(pairs: Sequence[str] | None) -> dict[str, str]:
+    """Parse repeated ``--param k=v`` flags into a dict."""
+    params: dict[str, str] = {}
+    for pair in pairs or []:
+        if "=" not in pair:
+            raise SystemExit(f"--param expects k=v, got {pair!r}")
+        key, value = pair.split("=", 1)
+        params[key] = value
+    return params
+
+
+def _with_drift(url: str, drift: str | None) -> str:
+    """Append a ``?drift=...`` query to a MockMed base URL."""
+    if not drift:
+        return url
+    return f"{url.rstrip('/')}/?drift={drift}"
+
+
+def _cmd_demo_record(args: argparse.Namespace) -> int:
+    from openadapt_flow.demo_driver import record_triage_demo
+    from openadapt_flow.mockmed.server import serve
+
+    url, stop = serve(port=0)
+    try:
+        url = _with_drift(url, args.drift)
+        out = record_triage_demo(
+            url,
+            Path(args.out),
+            note_text=args.note_text,
+            param_name=args.param_name,
+            headed=args.headed,
+        )
+        print(f"Recording written to {out}")
+    finally:
+        stop()
+    return 0
+
+
+def _cmd_compile(args: argparse.Namespace) -> int:
+    from openadapt_flow.compiler import compile_recording
+
+    workflow = compile_recording(
+        Path(args.recording), Path(args.out), name=args.name
+    )
+    print(
+        f"Compiled {len(workflow.steps)} steps into {args.out} "
+        f"(workflow: {workflow.name!r})"
+    )
+    return 0
+
+
+def _default_run_dir() -> Path:
+    """Timestamped default run directory under ``runs/``."""
+    from datetime import datetime, timezone
+
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    return Path("runs") / f"replay-{stamp}"
+
+
+def _cmd_replay(args: argparse.Namespace) -> int:
+    from playwright.sync_api import sync_playwright
+
+    from openadapt_flow.backends.playwright_backend import PlaywrightBackend
+    from openadapt_flow.ir import Workflow
+    from openadapt_flow.report import render_run_report
+    from openadapt_flow.runtime import Replayer
+
+    bundle = Path(args.bundle)
+    run_dir = Path(args.run_dir) if args.run_dir else _default_run_dir()
+    workflow = Workflow.load(bundle)
+    params = _parse_params(args.param)
+
+    if args.url and args.drift:
+        raise SystemExit(
+            "--drift only applies to the bundled MockMed demo app; "
+            "omit --url to use it (drift your own app for real)."
+        )
+
+    stop = None
+    url = args.url
+    if url is None:
+        from openadapt_flow.mockmed.server import serve
+
+        url, stop = serve(port=0)
+        url = _with_drift(url, args.drift)
+        drift_note = f" (drift: {args.drift})" if args.drift else ""
+        print(f"No --url given; replaying against bundled MockMed{drift_note}")
+
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=not args.headed)
+            page = browser.new_page(viewport=_VIEWPORT)
+            page.goto(url)
+            try:
+                backend = PlaywrightBackend(page)
+                report = Replayer(backend).run(
+                    workflow,
+                    params=params,
+                    bundle_dir=bundle,
+                    run_dir=run_dir,
+                    save_healed_to=(
+                        Path(args.save_healed_to)
+                        if args.save_healed_to
+                        else None
+                    ),
+                )
+            finally:
+                browser.close()
+    finally:
+        if stop is not None:
+            stop()
+
+    report_md = render_run_report(run_dir)
+    outcome = "success" if report.success else "FAILED"
+    print(f"Replay {outcome}: {report_md}")
+    return 0 if report.success else 1
+
+
+def _cmd_bench(args: argparse.Namespace) -> int:
+    from contextlib import contextmanager
+
+    from openadapt_flow.bench import run_bench
+    from openadapt_flow.mockmed.server import serve
+    from openadapt_flow.report import render_bench_report
+
+    url, stop = serve(port=0)
+    target_url = _with_drift(url, args.drift)
+
+    @contextmanager
+    def backend_factory():
+        from playwright.sync_api import sync_playwright
+
+        from openadapt_flow.backends.playwright_backend import (
+            PlaywrightBackend,
+        )
+
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=not args.headed)
+            page = browser.new_page(viewport=_VIEWPORT)
+            page.goto(target_url)
+            try:
+                yield PlaywrightBackend(page)
+            finally:
+                browser.close()
+
+    run_root = Path(args.run_root)
+    try:
+        result = run_bench(
+            Path(args.bundle),
+            backend_factory,
+            args.n,
+            params=_parse_params(args.param),
+            run_root=run_root,
+        )
+    finally:
+        stop()
+
+    report_md = render_bench_report(
+        run_root / "bench.json", run_root / "BENCH.md"
+    )
+    print(
+        f"Bench: {result['success_count']}/{result['n']} succeeded "
+        f"(p50 {result['total_ms_p50']:.0f} ms) — {report_md}"
+    )
+    return 0 if result["success_count"] == result["n"] else 1
+
+
+def _cmd_emit_skill(args: argparse.Namespace) -> int:
+    from openadapt_flow.emit.skill import emit_skill
+
+    skill_dir = emit_skill(Path(args.bundle), Path(args.out))
+    print(f"Skill written to {skill_dir}")
+    return 0
+
+
+def _cmd_emit_mcp(args: argparse.Namespace) -> int:
+    from openadapt_flow.emit.mcp_tool import emit_mcp_server
+
+    server_path = emit_mcp_server(Path(args.bundle), Path(args.out))
+    print(f"MCP server written to {server_path}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="openadapt-flow",
+        description=(
+            "Record a workflow once, compile it into a deterministic "
+            "vision-anchored script, replay it locally, heal it on drift."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser(
+        "demo-record",
+        help="Serve MockMed and record the canonical triage demo",
+    )
+    p.add_argument("--out", required=True, help="Recording output directory")
+    p.add_argument(
+        "--note-text",
+        default="Follow-up in 2 weeks; BP recheck.",
+        help="Note text typed during the demo (recorded as a parameter)",
+    )
+    p.add_argument(
+        "--param-name", default="note", help="Parameter name for the note"
+    )
+    p.add_argument(
+        "--drift", default=None, help="Comma-separated MockMed drift modes"
+    )
+    p.add_argument(
+        "--headed", action="store_true", help="Run the browser headed"
+    )
+    p.set_defaults(func=_cmd_demo_record)
+
+    p = sub.add_parser(
+        "compile", help="Compile a recording into a workflow bundle"
+    )
+    p.add_argument("recording", help="Recording directory")
+    p.add_argument("--out", required=True, help="Output bundle directory")
+    p.add_argument("--name", required=True, help="Workflow name")
+    p.set_defaults(func=_cmd_compile)
+
+    p = sub.add_parser(
+        "replay",
+        help=(
+            "Replay a bundle (serves the bundled MockMed demo app when "
+            "no --url is given)"
+        ),
+    )
+    p.add_argument("bundle", help="Workflow bundle directory")
+    p.add_argument(
+        "--url",
+        default=None,
+        help=(
+            "URL of the target app (default: serve the bundled MockMed "
+            "demo app)"
+        ),
+    )
+    p.add_argument(
+        "--drift",
+        default=None,
+        help=(
+            "Comma-separated MockMed drift modes (theme,move,rename,modal) "
+            "to demonstrate self-healing; only valid without --url"
+        ),
+    )
+    p.add_argument(
+        "--run-dir",
+        default=None,
+        help=(
+            "Run output directory "
+            "(default: runs/replay-<UTC timestamp> under the current "
+            "directory)"
+        ),
+    )
+    p.add_argument(
+        "--param",
+        action="append",
+        metavar="K=V",
+        help="Parameter substitution (repeatable)",
+    )
+    p.add_argument(
+        "--save-healed-to",
+        default=None,
+        help="Write the healed bundle to this directory",
+    )
+    p.add_argument(
+        "--headed", action="store_true", help="Run the browser headed"
+    )
+    p.set_defaults(func=_cmd_replay)
+
+    p = sub.add_parser(
+        "bench", help="Replay a bundle N times against MockMed and aggregate"
+    )
+    p.add_argument("bundle", help="Workflow bundle directory")
+    p.add_argument("--n", type=int, default=3, help="Number of iterations")
+    p.add_argument(
+        "--drift",
+        default=None,
+        help="Comma-separated drift modes forwarded to the MockMed URL",
+    )
+    p.add_argument(
+        "--run-root", required=True, help="Directory for per-iteration runs"
+    )
+    p.add_argument(
+        "--param",
+        action="append",
+        metavar="K=V",
+        help="Parameter substitution (repeatable)",
+    )
+    p.add_argument(
+        "--headed", action="store_true", help="Run the browser headed"
+    )
+    p.set_defaults(func=_cmd_bench)
+
+    p = sub.add_parser(
+        "emit-skill", help="Emit an Agent Skills folder for a bundle"
+    )
+    p.add_argument("bundle", help="Workflow bundle directory")
+    p.add_argument(
+        "--out", required=True, help="Parent directory for the skill folder"
+    )
+    p.set_defaults(func=_cmd_emit_skill)
+
+    p = sub.add_parser(
+        "emit-mcp", help="Emit a standalone MCP server.py for a bundle"
+    )
+    p.add_argument("bundle", help="Workflow bundle directory")
+    p.add_argument(
+        "--out", required=True, help="Path for the generated server.py"
+    )
+    p.set_defaults(func=_cmd_emit_mcp)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """CLI entry point. Returns a process exit code."""
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openadapt_flow/backend.py

@@ -0,0 +1,33 @@
+"""Backend protocol: the only interface the runtime uses to touch a GUI.
+
+The runtime is vision-only by construction — it sees PNG bytes and emits
+clicks/keys at pixel coordinates. Anything that can screenshot and inject
+input can be a backend: a Playwright page (reference/test backend), a native
+OS layer (pyautogui/Quartz), or an RDP session.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Backend(Protocol):
+    @property
+    def viewport(self) -> tuple[int, int]:
+        """(width, height) of the screen surface in pixels."""
+        ...
+
+    def screenshot(self) -> bytes:
+        """Return the current frame as PNG bytes."""
+        ...
+
+    def click(self, x: int, y: int, *, double: bool = False) -> None: ...
+
+    def type_text(self, text: str) -> None:
+        """Type text into the currently focused element."""
+        ...
+
+    def press(self, key: str) -> None:
+        """Press a key or chord, e.g. 'Enter', 'Tab', 'Meta+a'."""
+        ...

openadapt_flow/backends/__init__.py

@@ -0,0 +1,24 @@
+"""Backend implementations of the `openadapt_flow.backend.Backend` protocol.
+
+`PlaywrightBackend` is re-exported lazily so that importing this package does
+not require playwright unless the backend is actually used.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from openadapt_flow.backends.playwright_backend import PlaywrightBackend
+
+__all__ = ["PlaywrightBackend"]
+
+
+def __getattr__(name: str) -> object:
+    if name == "PlaywrightBackend":
+        from openadapt_flow.backends.playwright_backend import (
+            PlaywrightBackend,
+        )
+
+        return PlaywrightBackend
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openadapt_flow/backends/playwright_backend.py

@@ -0,0 +1,152 @@
+"""Playwright-driven reference backend (sync API, chromium, headless-capable).
+
+Implements the `openadapt_flow.backend.Backend` protocol against a Playwright
+`Page`: full-viewport PNG screenshots, mouse clicks at pixel coordinates,
+keyboard typing, and key/chord presses. Viewport is fixed at 1280x800 with
+deviceScaleFactor=1 so CSS pixels equal screenshot pixels.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Callable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from playwright.sync_api import Page
+
+VIEWPORT: tuple[int, int] = (1280, 800)
+
+_MODIFIER_ALIASES = {
+    "meta": "Meta",
+    "cmd": "Meta",
+    "command": "Meta",
+    "ctrl": "Control",
+    "control": "Control",
+    "alt": "Alt",
+    "option": "Alt",
+    "shift": "Shift",
+}
+
+_NAMED_KEYS = {
+    "enter": "Enter",
+    "return": "Enter",
+    "tab": "Tab",
+    "escape": "Escape",
+    "esc": "Escape",
+    "backspace": "Backspace",
+    "delete": "Delete",
+    "space": "Space",
+    "home": "Home",
+    "end": "End",
+    "pageup": "PageUp",
+    "pagedown": "PageDown",
+    "arrowup": "ArrowUp",
+    "arrowdown": "ArrowDown",
+    "arrowleft": "ArrowLeft",
+    "arrowright": "ArrowRight",
+}
+
+
+def _normalize_chord(key: str) -> str:
+    """Normalize a key or chord like ``'Meta+a'`` to Playwright's format.
+
+    Modifier aliases (``ctrl``, ``cmd``, ...) are canonicalized; common named
+    keys are case-corrected; single characters pass through unchanged.
+
+    Args:
+        key: Key name or ``+``-joined chord (e.g. ``'Enter'``, ``'Meta+a'``).
+
+    Returns:
+        The Playwright-compatible key/chord string.
+    """
+    parts = [p for p in key.split("+") if p]
+    normalized: list[str] = []
+    for part in parts:
+        lower = part.lower()
+        if lower in _MODIFIER_ALIASES:
+            normalized.append(_MODIFIER_ALIASES[lower])
+        elif lower in _NAMED_KEYS:
+            normalized.append(_NAMED_KEYS[lower])
+        else:
+            normalized.append(part)
+    return "+".join(normalized)
+
+
+class PlaywrightBackend:
+    """`Backend` implementation over a Playwright sync-API `Page`.
+
+    Attributes:
+        page: The underlying Playwright page (public so record-time helpers
+            such as the demo driver may use locators; replay never does).
+    """
+
+    def __init__(self, page: "Page") -> None:
+        """Wrap an existing Playwright page.
+
+        Args:
+            page: A page created with viewport 1280x800, deviceScaleFactor=1.
+        """
+        self.page = page
+
+    @property
+    def viewport(self) -> tuple[int, int]:
+        """(width, height) of the page viewport in pixels."""
+        size = self.page.viewport_size
+        if size is None:  # pragma: no cover - viewport always set by launch()
+            return VIEWPORT
+        return (size["width"], size["height"])
+
+    def screenshot(self) -> bytes:
+        """Return the current full-viewport frame as PNG bytes."""
+        return self.page.screenshot(type="png", full_page=False)
+
+    def click(self, x: int, y: int, *, double: bool = False) -> None:
+        """Click (or double-click) at pixel coordinates via the mouse."""
+        if double:
+            self.page.mouse.dblclick(x, y)
+        else:
+            self.page.mouse.click(x, y)
+
+    def type_text(self, text: str) -> None:
+        """Type text into the currently focused element."""
+        self.page.keyboard.type(text)
+
+    def press(self, key: str) -> None:
+        """Press a key or chord, e.g. ``'Enter'`` or ``'Meta+a'``."""
+        self.page.keyboard.press(_normalize_chord(key))
+
+    @classmethod
+    def launch(
+        cls, url: str, headless: bool = True
+    ) -> tuple["PlaywrightBackend", Callable[[], None]]:
+        """Start Playwright + chromium, open ``url``, and return a backend.
+
+        Args:
+            url: URL to navigate the new page to.
+            headless: Whether to launch chromium headless.
+
+        Returns:
+            ``(backend, close)`` where ``close()`` shuts down the browser and
+            the Playwright driver.
+        """
+        from playwright.sync_api import sync_playwright
+
+        pw = sync_playwright().start()
+        try:
+            browser = pw.chromium.launch(headless=headless)
+        except Exception:
+            pw.stop()
+            raise
+        page = browser.new_page(
+            viewport={"width": VIEWPORT[0], "height": VIEWPORT[1]},
+            device_scale_factor=1,
+        )
+        page.goto(url)
+        backend = cls(page)
+
+        def close() -> None:
+            try:
+                browser.close()
+            finally:
+                pw.stop()
+
+        return backend, close