plot3 0.4.0__py3-none-any.whl

plot3/payload.py

@@ -0,0 +1,216 @@
+"""Serializable PlotPayload — the contract between stats and the viewer.
+
+Remote/local split:
+
+* **Data / stats side** (local or GPU) produces a ``PlotPayload`` via
+  :func:`build_payload` / :meth:`ggplot.to_payload`.
+* **Viewer side** turns that payload into HTML via :func:`render_payload`
+  or a payload-backed figure via :meth:`ggplot.from_payload`.
+
+A payload does not hold a DataFrame. It holds the already-encoded wire format
+that the three.js template consumes (JSON spec + base64 binary blobs).
+
+Schema (``kind == "figure"``)::
+
+    {
+      "v": 1,
+      "kind": "figure",
+      "spec": { ... },          # same dict as build_spec()[0]
+      "blobs": { "p0x": "<b64>", ... },
+    }
+
+Faceted figures are still assembled by :func:`plot3.build.build_doc` as a
+grid of independent figure payloads (each panel is a normal figure payload).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import os
+from pathlib import Path
+from typing import Any
+
+# Wire-format version for PlotPayload (independent of spec["v"]).
+PAYLOAD_VERSION = 1
+
+__all__ = [
+    "PAYLOAD_VERSION",
+    "build_payload",
+    "render_payload",
+    "validate_payload",
+    "payload_from_spec",
+    "payload_blobs_list",
+    "save_payload",
+    "load_payload",
+    "display_payload",
+]
+
+
+def payload_from_spec(
+    spec: dict[str, Any],
+    payloads: list[tuple[str, str]],
+) -> dict[str, Any]:
+    """Build a figure PlotPayload from :func:`plot3.build.build_spec` output."""
+    blobs = {str(pid): str(b64) for pid, b64 in payloads}
+    return {
+        "v": PAYLOAD_VERSION,
+        "kind": "figure",
+        "spec": spec,
+        "blobs": blobs,
+    }
+
+
+def payload_blobs_list(payload: dict[str, Any]) -> list[tuple[str, str]]:
+    """Restore ``build_spec``-style ``[(id, b64), ...]`` from a payload."""
+    blobs = payload.get("blobs") or {}
+    if not isinstance(blobs, dict):
+        raise TypeError("payload['blobs'] must be a dict")
+    return [(str(pid), str(b64)) for pid, b64 in blobs.items()]
+
+
+def validate_payload(payload: Any) -> dict[str, Any]:
+    """Validate a PlotPayload dict; return it on success.
+
+    Raises ``TypeError`` / ``ValueError`` with actionable messages.
+    """
+    if not isinstance(payload, dict):
+        raise TypeError(f"PlotPayload must be a dict, got {type(payload).__name__}")
+    if payload.get("v") != PAYLOAD_VERSION:
+        raise ValueError(
+            f"unsupported PlotPayload version {payload.get('v')!r}; "
+            f"expected v={PAYLOAD_VERSION}"
+        )
+    kind = payload.get("kind")
+    if kind != "figure":
+        raise ValueError(
+            f"unsupported PlotPayload kind {kind!r}; expected 'figure'"
+        )
+    spec = payload.get("spec")
+    if not isinstance(spec, dict):
+        raise TypeError("PlotPayload['spec'] must be a dict")
+    for key in ("v", "is3d", "theme", "labs", "scales", "layers"):
+        if key not in spec:
+            raise ValueError(f"PlotPayload spec missing required key {key!r}")
+    if not isinstance(spec["layers"], list):
+        raise TypeError("PlotPayload spec['layers'] must be a list")
+    blobs = payload.get("blobs")
+    if not isinstance(blobs, dict):
+        raise TypeError("PlotPayload['blobs'] must be a dict")
+    for pid, b64 in blobs.items():
+        if not isinstance(pid, str) or not isinstance(b64, str):
+            raise TypeError("PlotPayload blobs must map str id -> str base64")
+    return payload
+
+
+def build_payload(g) -> dict[str, Any]:
+    """Compute a PlotPayload for a single-panel (non-faceted) figure.
+
+    Runs stats / encoding where the data lives. Does not produce HTML.
+
+    Faceted figures (``facet_wrap``) should use :func:`plot3.build.build_doc`,
+    which builds one payload per panel. Calling this on a faceted ggplot
+    raises ``ValueError``.
+    """
+    if getattr(g, "facet", None) is not None:
+        raise ValueError(
+            "to_payload() / build_payload() do not support facet_wrap(); "
+            "use build_doc() / fig.html() which assembles panel payloads"
+        )
+    from plot3.build import build_spec
+
+    spec, payloads = build_spec(g)
+    return payload_from_spec(spec, payloads)
+
+
+def script_json(value) -> str:
+    """JSON safe inside an HTML ``<script>``: ``</script>`` or ``<!--`` in a
+    title or a category cannot end the script, so data never becomes markup."""
+    text = json.dumps(value, separators=(",", ":"))
+    return (
+        text.replace("<", "\\u003c").replace(">", "\\u003e").replace("&", "\\u0026")
+        .replace("\u2028", "\\u2028").replace("\u2029", "\\u2029")
+    )
+
+
+def render_payload(
+    payload: dict[str, Any],
+    *,
+    log: bool = True,
+) -> str:
+    """Turn a validated figure PlotPayload into a standalone HTML document.
+
+    This is the **viewer** half: no DataFrame access, only ``spec`` + ``blobs``.
+    """
+    from plot3.viewer import _DOC_TEMPLATE as DOC_TEMPLATE
+    from plot3.viewer import _KATEX_BOOT
+
+    payload = validate_payload(payload)
+    spec = payload["spec"]
+    blobs = payload["blobs"]
+
+    # Preserve insertion order from build_spec (viewer looks up by id).
+    blocks = "\n".join(
+        f'<script type="text/plain" id="{pid}">{b64}</script>'
+        for pid, b64 in blobs.items()
+    )
+    parts = {
+        "SPEC": script_json(spec),
+        "PAYLOADS": blocks,
+        "KATEX": _KATEX_BOOT if spec.get("math") else "",
+    }
+    # One pass: text from the figure (a title that says "__KATEX__") is
+    # never searched again for placeholders.
+    doc = re.sub(r"__(SPEC|PAYLOADS|KATEX)__", lambda m: parts[m.group(1)], DOC_TEMPLATE)
+    if log:
+        kb = len(doc) // 1024
+        # Sizes are opt-in (PLOT3_VERBOSE=1), so a notebook cell is just
+        # the plot.
+        if os.environ.get("PLOT3_VERBOSE", "").strip() == "1":
+            rows = sum(int(sp.get("n", 0)) for sp in spec.get("layers", []))
+            n_layers = len(spec.get("layers", []))
+            print(
+                f"plot3: {n_layers} layer(s), {rows:,} rows -> {kb:,} KB "
+                f"portable HTML{' (3D)' if spec.get('is3d') else ''}"
+            )
+            if kb > 1500:
+                print("plot3: the figure is over 1.5 MB of HTML")
+    return doc
+
+
+def save_payload(payload: dict[str, Any], path: str | Path) -> str:
+    """Write a PlotPayload to a JSON file (remote → local handoff artifact)."""
+    payload = validate_payload(payload)
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(payload, separators=(",", ":"), ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return str(path.resolve())
+
+
+def load_payload(path: str | Path) -> dict[str, Any]:
+    """Load and validate a PlotPayload JSON file."""
+    path = Path(path)
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return validate_payload(data)
+
+
+def display_payload(
+    payload: dict[str, Any],
+    *,
+    browser: bool | None = None,
+    path: str | Path | None = None,
+    height: str | int = "480px",
+    hide: bool | None = None,
+):
+    """Show a PlotPayload without a live DataFrame (local viewer half).
+
+    Builds a payload-backed :class:`~plot3.ggplot.ggplot` and calls
+    :meth:`~plot3.ggplot.ggplot.show`.
+    """
+    from plot3.ggplot import ggplot
+
+    fig = ggplot.from_payload(payload, height=height, hide=hide)
+    return fig.show(browser=browser, path=path)

plot3/remote.py

@@ -0,0 +1,220 @@
+"""CRAFT / GPU bridge: stats on the remote, render on the host.
+
+Phase D of the remote/local split.
+
+Host (SolveIt + CRAFT connected)
+    ``remote_run_`` executes Python on the GPU kernel.
+    :func:`fetch_remote_payload` runs a ggplot expression there, pulls only
+    the compact PlotPayload (via temp file + SSH), and the host calls
+    :func:`plot3.payload.display_payload` / :func:`render_payload`.
+
+Remote kernel (``%gpu`` cell body)
+    ``ggplot(...)._repr_mimebundle_`` includes
+    ``application/vnd.plot3.v1+json`` so a future host can intercept the
+    payload; HTML remains the fallback for display.
+
+Environment
+    ``PLOT3_REMOTE=1`` forces remote-kernel display behaviour (payload mime
+    preferred, lighter show path).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import uuid
+from typing import Any, Callable
+
+# Custom Jupyter mime type for PlotPayload handoff (host may ignore → HTML).
+MIME_PLOT3 = "application/vnd.plot3.v1+json"
+
+__all__ = [
+    "MIME_PLOT3",
+    "is_remote_kernel",
+    "has_craft_host",
+    "fetch_remote_payload",
+    "remote_ggplot_payload",
+    "show_remote",
+]
+
+
+def is_remote_kernel() -> bool:
+    """True when this process should act as the GPU/remote side of the bridge.
+
+    Heuristics (any match):
+
+    * ``PLOT3_REMOTE=1`` / ``true`` / ``yes``
+    * ``CRAFT_REMOTE=1`` or ``GPU_KERNEL=1``
+    * IPython ns has CRAFT remote markers but **not** host ``remote_run_``
+    """
+    for key in ("PLOT3_REMOTE", "CRAFT_REMOTE", "GPU_KERNEL"):
+        raw = (os.environ.get(key) or "").strip().lower()
+        if raw in ("1", "true", "yes", "on"):
+            return True
+    try:
+        from IPython import get_ipython
+
+        ip = get_ipython()
+        ns = (getattr(ip, "user_ns", None) or {}) if ip is not None else {}
+    except Exception:
+        ns = {}
+    # Host CRAFT always exposes remote_run_ for talking *to* the GPU.
+    if callable(ns.get("remote_run_")):
+        return False
+    # Remote kernel often has GPU-oriented markers without host helpers.
+    for key in ("_craft_remote", "IS_GPU_KERNEL", "cuda", "CUDA_VISIBLE_DEVICES"):
+        if key in ns:
+            return True
+    if os.environ.get("CUDA_VISIBLE_DEVICES") is not None and not callable(
+        ns.get("remote_run_")
+    ):
+        # Weak signal — only if explicitly on a GPU box without host CRAFT.
+        if (os.environ.get("PLOT3_ASSUME_REMOTE") or "").strip().lower() in (
+            "1",
+            "true",
+            "yes",
+        ):
+            return True
+    return False
+
+
+def has_craft_host() -> bool:
+    """True when the host IPython session can call ``remote_run_``."""
+    try:
+        from IPython import get_ipython
+
+        ip = get_ipython()
+        ns = (getattr(ip, "user_ns", None) or {}) if ip is not None else {}
+    except Exception:
+        return False
+    return callable(ns.get("remote_run_"))
+
+
+def _remote_run() -> Callable[..., str]:
+    from IPython import get_ipython
+
+    ip = get_ipython()
+    if ip is None:
+        raise RuntimeError("fetch_remote_payload requires IPython")
+    rr = (ip.user_ns or {}).get("remote_run_")
+    if not callable(rr):
+        raise RuntimeError(
+            "remote_run_ missing — load CRAFT and run %gpu on the host first"
+        )
+    return rr
+
+
+def fetch_remote_payload(
+    remote_source: str,
+    *,
+    max_chars: int = 8000,
+) -> dict[str, Any]:
+    """Execute *remote_source* on the GPU kernel and return a PlotPayload.
+
+    *remote_source* must leave a dict named ``_plot3_payload`` in scope
+    (or assign the final expression result). Implementation writes JSON to a
+    temp file on the remote and streams it back with SSH (same pattern as
+    :func:`plot3.jupyter.remote_df`), so large blobs are not limited by
+    ``remote_run_`` stdout caps.
+    """
+    from plot3.io import ssh_bytes
+    from plot3.payload import validate_payload
+
+    rr = _remote_run()
+    tmp = f"/tmp/plot3_payload_{uuid.uuid4().hex}.json"
+    # Indent remote body for the embedded script.
+    body = remote_source.strip()
+    if not body.endswith("\n"):
+        body += "\n"
+    code = f"""
+import json as _json
+from pathlib import Path as _Path
+{body}
+if "_plot3_payload" not in dir() and "_plot3_payload" not in locals():
+    raise RuntimeError(
+        "remote plot source must set _plot3_payload = fig.to_payload()"
+    )
+_p = _Path({tmp!r})
+_p.write_text(_json.dumps(_plot3_payload, separators=(",", ":")), encoding="utf-8")
+print(_p.as_posix())
+print("plot3_payload_bytes", _p.stat().st_size)
+"""
+    out = (rr(code, max_chars=max_chars) or "").strip()
+    # Path line: absolute or relative *.json written by the remote helper.
+    lines = [ln.strip() for ln in out.splitlines() if ln.strip()]
+    path_line = None
+    for ln in reversed(lines):
+        if not ln.endswith(".json"):
+            continue
+        if "plot3_payload" in ln or ln.startswith("/") or ln[1:3] == ":\\":
+            path_line = ln
+            break
+    if not path_line:
+        for ln in reversed(lines):
+            if ln.endswith(".json") and not ln.startswith("plot3_payload"):
+                path_line = ln
+                break
+    if not path_line:
+        raise RuntimeError(
+            "remote payload path not found in remote_run_ output:\n"
+            + (out[-800:] if out else "(empty)")
+        )
+    try:
+        raw = ssh_bytes("cat -- " + shlex.quote(path_line))
+    finally:
+        try:
+            ssh_bytes("rm -f -- " + shlex.quote(path_line))
+        except Exception:
+            pass
+    try:
+        data = json.loads(raw.decode("utf-8"))
+    except Exception as e:
+        raise RuntimeError(f"invalid remote PlotPayload JSON: {e}") from e
+    return validate_payload(data)
+
+
+def remote_ggplot_payload(
+    expr: str,
+    *,
+    max_chars: int = 8000,
+) -> dict[str, Any]:
+    """Evaluate a ggplot expression on the remote kernel; return PlotPayload.
+
+    Example::
+
+        payload = remote_ggplot_payload(
+            "ggplot(df, aes(x='wt', y='mpg')) + geom_point()"
+        )
+    """
+    expr = expr.strip()
+    source = f"""
+_fig = ({expr})
+if not hasattr(_fig, "to_payload"):
+    raise TypeError(
+        f"remote expression must produce a ggplot, got {{type(_fig).__name__}}"
+    )
+_plot3_payload = _fig.to_payload()
+"""
+    return fetch_remote_payload(source, max_chars=max_chars)
+
+
+def show_remote(
+    expr: str,
+    *,
+    browser: bool | None = None,
+    height: str | int = "480px",
+    hide: bool | None = None,
+    max_chars: int = 8000,
+):
+    """Run *expr* on the remote kernel and display the figure on the host.
+
+    Stats / encoding run where the data lives; only the PlotPayload crosses
+    the wire. Viewer HTML is built locally.
+    """
+    from plot3.payload import display_payload
+
+    payload = remote_ggplot_payload(expr, max_chars=max_chars)
+    return display_payload(
+        payload, browser=browser, height=height, hide=hide
+    )