zerodom 0.0.1__py3-none-any.whl

zerodom/__init__.py

@@ -0,0 +1,8 @@
+"""ZeroDOM: DOM-to-Interaction-Graph middleware for AI web agents."""
+
+from .label_linker import get_label
+from .parser import InteractionGraph, ZeroDOMParser, parse_html
+from .playwright_wrapper import ZeroDOM
+
+__version__ = "0.0.1"
+__all__ = ["ZeroDOM", "ZeroDOMParser", "InteractionGraph", "parse_html", "get_label"]

zerodom/cli.py

@@ -0,0 +1,163 @@
+"""Turn a web page into the list of things an agent can click, and count the
+savings. `zerodom <url>` for the compact graph, --find to search it."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import urllib.request
+from pathlib import Path
+
+import tiktoken
+
+from .parser import ZeroDOMParser, compact_line, find_nodes
+from .playwright_wrapper import serialize
+
+USER_AGENT = "Mozilla/5.0 (compatible; zerodom)"
+
+
+def count_tokens(text: str) -> int:
+    return len(tiktoken.get_encoding("cl100k_base").encode(text))
+
+
+def fetch(url: str, render: bool) -> tuple[str, str]:
+    """Return (html, final_url). `render` runs a real browser for JS-heavy pages."""
+    if render:
+        from playwright.sync_api import sync_playwright
+
+        with sync_playwright() as pw:
+            browser = pw.chromium.launch()
+            page = browser.new_page()
+            page.goto(url, wait_until="networkidle")
+            html, final_url = serialize(page), page.url
+            browser.close()
+            return html, final_url
+
+    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT})
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return resp.read().decode(resp.headers.get_content_charset() or "utf-8", "replace"), resp.url
+
+
+def capture(url: str, screenshot: str | None, html_path: str | None) -> tuple[str, str, str]:
+    """Load a URL once and write whichever visual artifacts were asked for.
+
+    Measuring, annotating and screenshotting all need the same live page, so they
+    share one browser session rather than one launch per artifact.
+    """
+    from playwright.sync_api import sync_playwright
+
+    from . import report
+
+    with sync_playwright() as pw:
+        browser = pw.chromium.launch()
+        page = browser.new_page(viewport={"width": 1280, "height": 900})
+        page.goto(url, wait_until="networkidle")
+        source, final_url = serialize(page), page.url
+        graph = ZeroDOMParser(source, final_url).parse()
+
+        png, layout = report.screenshot(page, graph, screenshot)
+        browser.close()
+
+    located = len(layout["boxes"])
+    notes = []
+    if screenshot:
+        notes.append(f"  Screenshot         {screenshot}  ({located}/{len(graph['nodes'])} located)")
+    if html_path:
+        with open(html_path, "w", encoding="utf-8") as fh:
+            fh.write(graph.to_html_report(png, layout))
+        notes.append(f"  HTML report        {html_path}")
+    return source, final_url, "\n".join(notes)
+
+
+def inspect(
+    url: str,
+    render: bool = False,
+    as_json: bool = False,
+    screenshot: str | None = None,
+    html_path: str | None = None,
+    find: str | None = None,
+) -> int:
+    # A local path is a perfectly good thing to inspect; both fetchers need file://.
+    if "://" not in url and Path(url).exists():
+        url = Path(url).resolve().as_uri()
+
+    extra = ""
+    if screenshot or html_path:
+        html, final_url, extra = capture(url, screenshot, html_path)
+    else:
+        html, final_url = fetch(url, render)
+    graph = ZeroDOMParser(html, final_url).parse()
+
+    raw_tokens = count_tokens(html)
+    # Measure what a model would actually be sent: compact JSON, or the text DSL.
+    payload = graph.to_json(indent=None) if as_json else graph.to_compact_text()
+    graph_tokens = count_tokens(payload)
+    savings = (1 - graph_tokens / raw_tokens) * 100 if raw_tokens else 0.0
+
+    if find:
+        hits = find_nodes(graph["nodes"], find)
+        print("\n".join(compact_line(node) for node in hits) if hits
+              else f"No node matches {find!r} among {len(graph['nodes'])} nodes.")
+    else:
+        print(graph.to_json() if as_json else graph.to_compact_text())
+    print(f"\n{'─' * 52}")
+    print(f"  URL                {final_url}")
+    print(f"  Interactive nodes  {graph['metadata']['total_interactive_nodes']}")
+    print(f"  Parsing latency    {graph['metadata']['parsing_latency_ms']} ms")
+    print(f"  Raw DOM tokens     {raw_tokens:,}")
+    print(f"  ZeroDOM tokens     {graph_tokens:,}  ({'json' if as_json else 'compact text'})")
+    print(f"  Token savings      {savings:.1f}%")
+    if extra:
+        print(extra)
+    print("─" * 52)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="zerodom", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    insp = sub.add_parser("inspect", help="parse a URL and report token savings")
+    insp.add_argument("url")
+    insp.add_argument(
+        "--render",
+        action="store_true",
+        help="fetch via headless Chromium instead of plain HTTP (for JS-rendered pages)",
+    )
+    insp.add_argument(
+        "--json",
+        dest="as_json",
+        action="store_true",
+        help="emit the full JSON graph instead of the token-dense text DSL",
+    )
+    insp.add_argument(
+        "--find",
+        metavar="QUERY",
+        help="print only the nodes whose type or label matches QUERY",
+    )
+    insp.add_argument(
+        "--screenshot",
+        metavar="OUT.png",
+        help="write a full-page screenshot with a numbered badge over every node",
+    )
+    insp.add_argument(
+        "--html",
+        dest="html_path",
+        metavar="OUT.html",
+        help="write a self-contained HTML report: graph beside the annotated page",
+    )
+
+    # `inspect` is the only verb, so requiring it is pure ceremony: `zerodom <url>`
+    # works, and the explicit form keeps working for anyone who learned it.
+    argv = sys.argv[1:] if argv is None else argv
+    if argv and argv[0] not in {"inspect", "-h", "--help"} and not argv[0].startswith("-"):
+        argv = ["inspect", *argv]
+
+    args = parser.parse_args(argv)
+    return inspect(
+        args.url, args.render, args.as_json, args.screenshot, args.html_path, args.find
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(main())

zerodom/label_linker.py

@@ -0,0 +1,119 @@
+"""Work out what a control is called, the way a person reading the page would."""
+
+from __future__ import annotations
+
+from lxml.html import HtmlElement
+
+# Attribute fallbacks, most explicit first. Split around the adjacent-text
+# scan: authored attributes beat scraped text, but scraped text beats `name`/`value`,
+# which are developer identifiers ("q") rather than anything a user reads.
+AUTHORED_ATTRS = ("aria-label", "placeholder", "alt", "title")
+IDENTIFIER_ATTRS = ("value", "name")
+
+# Controls that sit next to their caption. Buttons and links carry their own text.
+CAPTIONED_TAGS = {"input", "select", "textarea"}
+
+# Inputs whose `value` is a button caption rather than user data.
+BUTTON_INPUT_TYPES = {"submit", "button", "reset", "image"}
+
+MAX_LABEL_LEN = 80
+
+# Trailing punctuation on a caption: "Search:" -> "Search".
+CAPTION_STRIP = " \t\n\xa0:*>-–—"
+
+
+def text_of(el: HtmlElement) -> str:
+    """Visible text of an element, whitespace-collapsed and length-capped."""
+    return " ".join(el.text_content().split())[:MAX_LABEL_LEN]
+
+
+def adjacent_text(el: HtmlElement) -> str:
+    """Caption sitting immediately before an input, as in `Search: <input>`.
+
+    Reads the previous sibling's tail, or the parent's leading text when the input
+    is the first child. Only the last few words are kept — the text run before an
+    input is often a whole sentence of surrounding copy, not a caption.
+    """
+    parent = el.getparent()
+    if parent is None:
+        return ""
+    previous = el.getprevious()
+    source = previous.tail if previous is not None else parent.text
+    caption = " ".join((source or "").split()).rstrip(CAPTION_STRIP)
+    if not caption:
+        return ""
+    return " ".join(caption.split()[-6:])[:MAX_LABEL_LEN]
+
+
+class LabelLinker:
+    """Resolves labels against a pre-indexed set of <label> tags.
+
+    The parser walks the DOM once and hands over what it saw, so label lookup
+    stays O(1) per node instead of re-searching the tree for every input.
+    """
+
+    def __init__(
+        self, root: HtmlElement, labels_by_for: dict[str, HtmlElement] | None = None
+    ) -> None:
+        self.root = root
+        if labels_by_for is None:
+            labels_by_for = {}
+            for tag in root.iter("label"):
+                if (for_id := tag.get("for")) and for_id not in labels_by_for:
+                    labels_by_for[for_id] = tag
+        self.labels_by_for = labels_by_for
+
+    def label(self, element: HtmlElement, ancestor_label: HtmlElement | None = None) -> str:
+        """Resolve a human-readable label for an interactive element."""
+        # explicit <label for="...">
+        elem_id = element.get("id")
+        if elem_id and (tag := self.labels_by_for.get(elem_id)) is not None:
+            if text := text_of(tag):
+                return text
+
+        # wrapping <label>
+        if ancestor_label is None:
+            ancestor_label = next(element.iterancestors("label"), None)
+        if ancestor_label is not None and (text := text_of(ancestor_label)):
+            return text
+
+        # aria-labelledby -> referenced element's text
+        for ref_id in element.get("aria-labelledby", "").split():
+            refs = self.root.xpath("//*[@id=$ref]", ref=ref_id)
+            if refs and (text := text_of(refs[0])):
+                return text
+
+        # authored attribute fallbacks
+        for attr in AUTHORED_ATTRS:
+            if (val := element.get(attr)) and val.strip():
+                return val.strip()[:MAX_LABEL_LEN]
+
+        # On a submit/button input, `value` is the visible caption, not an identifier.
+        if element.tag == "input" and element.get("type") in BUTTON_INPUT_TYPES:
+            if (val := element.get("value")) and val.strip():
+                return val.strip()[:MAX_LABEL_LEN]
+
+        # Caption text next to the control, before falling back to identifiers
+        if element.tag in CAPTIONED_TAGS and (caption := adjacent_text(element)):
+            return caption
+
+        # Inner text (buttons, links). Skipped for captioned controls, whose contents
+        # are their value or options — a <select>'s first <option> is not its label.
+        if element.tag not in CAPTIONED_TAGS and (text := text_of(element)):
+            return text
+
+        for attr in IDENTIFIER_ATTRS:
+            if (val := element.get(attr)) and val.strip():
+                return val.strip()[:MAX_LABEL_LEN]
+
+        # Image-only links and buttons carry their label on the <img>.
+        for img in element.iterdescendants("img"):
+            if alt := (img.get("alt") or img.get("title") or "").strip():
+                return alt[:MAX_LABEL_LEN]
+
+        return "Unlabelled Element"
+
+
+def get_label(root: HtmlElement, element: HtmlElement) -> str:
+    """Standalone label lookup for a single element."""
+    return LabelLinker(root).label(element)

zerodom/mcp_server.py

@@ -0,0 +1,180 @@
+"""Model Context Protocol server: drive a browser through the interaction graph."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.server import MCPServer
+
+from .parser import ZeroDOMParser, compact_line, find_nodes
+from .playwright_wrapper import serialize_async
+
+mcp = MCPServer("zerodom", version="0.0.1")
+
+# ponytail: one global browser session — the MCP server drives a single agent.
+# Add a session_id parameter only if concurrent pages are ever needed.
+_session: dict[str, Any] = {
+    "pw": None, "browser": None, "page": None,
+    "selectors": {}, "nodes": [], "url": None,
+}
+
+
+async def _page() -> Any:
+    if _session["page"] is None:
+        from playwright.async_api import async_playwright
+
+        pw = await async_playwright().start()
+        browser = await pw.chromium.launch()
+        _session.update(pw=pw, browser=browser, page=await browser.new_page())
+    return _session["page"]
+
+
+def _selector(node_id: str) -> str:
+    """Resolve a node id to its CSS selector — the lookup map the model never sees.
+
+    Accepts both the bare index the compact graph prints (`[03]` -> "3") and the
+    full "node_03" form used in the JSON graph.
+    """
+    key = node_id if node_id.startswith("node_") else f"node_{node_id.strip('[]').zfill(2)}"
+    selector = _session["selectors"].get(key)
+    if not selector:
+        raise ValueError(f"Unknown node '{node_id}'. Call zerodom_parse_url first.")
+    return selector
+
+
+def _identity(node: dict[str, Any]) -> tuple[str, str, str]:
+    """What makes a node "the same node" across two reads. Node ids renumber on
+    every parse, so they cannot be it."""
+    return (node["type"], node["label"], node["selector"])
+
+
+def _diff(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> str | None:
+    """Only what changed, or None when a full graph would be more honest.
+
+    An agent clicking through a page re-reads the same few hundred nodes over and
+    over; on Hacker News that is ~2,350 tokens per action to say "one menu opened".
+    A wholesale change (a navigation) has no useful diff, so it falls back.
+    """
+    old, new = {_identity(n): n for n in before}, {_identity(n): n for n in after}
+    added = [n for key, n in new.items() if key not in old]
+    removed = [n for key, n in old.items() if key not in new]
+    changed = [
+        (old[key], n)
+        for key, n in new.items()
+        if key in old and n.get("value") != old[key].get("value")
+    ]
+    if not (added or removed or changed):
+        # Typing sets the DOM *property*, not the `value` attribute, so text a user
+        # entered is invisible to any serializer. The fill tool echoes it instead.
+        return "no structural change"
+    # More than half the page moved: it is a different page, so show all of it.
+    if len(added) + len(removed) > len(new) / 2:
+        return None
+
+    lines = [f"+{compact_line(n)}" for n in added]
+    lines += [f"-{compact_line(n)}" for n in removed]
+    lines += [
+        f"~{compact_line(n)}  {was.get('value', '')!r} -> {n.get('value', '')!r}"
+        for was, n in changed
+    ]
+    return "\n".join(lines)
+
+
+async def _read(verbose: bool = False, diff: bool = False) -> str:
+    """Parse the live DOM in place and refresh the selector map.
+
+    Never navigates, so form state, scroll position and cookies survive. Every
+    action re-reads through here, which is what keeps node ids pointing at the
+    page the model is actually looking at.
+    """
+    page = await _page()
+    # A click may still be navigating; content() during that raises.
+    await page.wait_for_load_state("domcontentloaded")
+    graph = ZeroDOMParser(await serialize_async(page), page.url).parse()
+    previous, url = _session["nodes"], _session["url"]
+    _session.update(
+        selectors=graph.selector_map(), nodes=graph["nodes"], url=page.url
+    )
+    if verbose:
+        return graph.to_json()
+    # A navigation invalidates every id, so a diff against the old page is noise.
+    if diff and previous and url == page.url and (delta := _diff(previous, graph["nodes"])):
+        return delta
+    return graph.to_compact_text()
+
+
+@mcp.tool()
+async def zerodom_parse_url(url: str, verbose: bool = False) -> str:
+    """Navigate to a URL and return its interaction graph.
+
+    Returns the compact text graph: `[03] button 'Sign In'`. CSS selectors are
+    kept server-side and resolved by node id, so they never cost context — pass
+    verbose=True for the full JSON including selectors.
+    """
+    page = await _page()
+    await page.goto(url, wait_until="domcontentloaded")
+    return await _read(verbose)
+
+
+@mcp.tool()
+async def zerodom_read_page(verbose: bool = False) -> str:
+    """Re-read the current page without navigating.
+
+    Use after an action changed the page, or when node ids look stale. Unlike
+    zerodom_parse_url this does not reload, so anything typed into the page stays.
+    """
+    return await _read(verbose)
+
+
+@mcp.tool()
+async def zerodom_find(query: str) -> str:
+    """Search the current page's graph for nodes matching `query`.
+
+    Case-insensitive substring match over each node's label and type. Prefer this
+    over re-reading the whole page when you already know what you are looking for:
+    "checkout" costs three lines, the full graph costs every node on the page.
+    """
+    hits = find_nodes(_session["nodes"], query)
+    if not _session["nodes"]:
+        return "No page loaded. Call zerodom_parse_url first."
+    if not hits:
+        return f"No node matches {query!r} among {len(_session['nodes'])} nodes."
+    return "\n".join(compact_line(node) for node in hits)
+
+
+@mcp.tool()
+async def zerodom_click_node(node_id: str) -> str:
+    """Click a node and return what changed on the page.
+
+    Returns a diff — `+` appeared, `-` gone, `~` value changed — because most
+    clicks alter a handful of nodes and re-listing the page would cost hundreds.
+    A navigation renumbers everything, so that returns the full graph instead.
+    """
+    page = await _page()
+    selector = _selector(node_id)
+    before = page.url
+    await page.click(selector)
+    graph = await _read(diff=True)
+    moved = f" -> {page.url}" if page.url != before else ""
+    return f"clicked [{node_id}]{moved}\n\n{graph}"
+
+
+@mcp.tool()
+async def zerodom_fill_node(node_id: str, text: str) -> str:
+    """Type text into a node and return what changed on the page.
+
+    The text is echoed back in the first line; the diff below it reports *structural*
+    change — a validation error appearing, an autocomplete list opening.
+    """
+    page = await _page()
+    selector = _selector(node_id)
+    await page.fill(selector, text)
+    return f"filled [{node_id}] with {text!r}\n\n{await _read(diff=True)}"
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()