flow-xray 0.2.0__py3-none-any.whl

flow_xray/__init__.py

@@ -0,0 +1,38 @@
+"""
+flow-xray — execution graph debugger.
+
+Primary API: ``trace`` (decorator + runner for capturing execution DAGs).
+
+Also includes scalar Value autodiff core + inspection exports.
+"""
+
+from flow_xray.trace import TraceNode, TraceResult, trace
+
+from flow_xray.debugger import GraphDebugger, TwoStepDebugger, iter_backward_steps
+from flow_xray.export_dot import value_graph_to_dot, write_dot
+from flow_xray.export_html import standalone_viewer_html, write_standalone_viewer_html
+from flow_xray.ir import graph_to_ir, ir_to_json
+from flow_xray.value import Value, backward_from, topological_order, zero_grad
+
+__all__ = [
+    # execution tracing (primary)
+    "trace",
+    "TraceNode",
+    "TraceResult",
+    # scalar autodiff
+    "Value",
+    "backward_from",
+    "topological_order",
+    "zero_grad",
+    "value_graph_to_dot",
+    "write_dot",
+    "standalone_viewer_html",
+    "write_standalone_viewer_html",
+    "TwoStepDebugger",
+    "GraphDebugger",
+    "iter_backward_steps",
+    "graph_to_ir",
+    "ir_to_json",
+]
+
+__version__ = "0.2.0"

flow_xray/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m flow_xray run|dot …``"""
+
+from flow_xray.cli import main
+
+raise SystemExit(main())

flow_xray/cli.py

@@ -0,0 +1,149 @@
+"""
+CLI entry points.
+
+``flow-xray run``   — execute a script with @trace, export HTML execution graph.
+``flow-xray dot``   — scalar-Value DOT/HTML export (demo / from script).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# gtype run  (execution tracing)
+# ---------------------------------------------------------------------------
+
+def cmd_run(args: argparse.Namespace) -> int:
+    from flow_xray.trace import TraceResult, _TraceSession, _count_all
+
+    path = Path(args.script)
+    if not path.is_file():
+        print(f"error: not a file: {path}", file=sys.stderr)
+        return 2
+    # Use a non-__main__ name so scripts' `if __name__ == "__main__"` blocks
+    # are skipped; @trace-decorated functions are captured by the CLI session.
+    ns: dict[str, Any] = {"__name__": "__flow_xray_run__", "__file__": str(path)}
+    session = _TraceSession()
+    with session:
+        exec(compile(path.read_text(encoding="utf-8"), str(path), "exec"), ns, ns)
+    result = TraceResult(session.roots)
+    html_path = args.html or path.stem + "_trace.html"
+    result.to_html(html_path, title=args.title or f"Trace: {path.name}")
+    total, errs = _count_all(result.roots)
+    print(f"Wrote {html_path}  ({total} nodes, {errs} errors)", file=sys.stderr)
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# gtype dot  (scalar Value graph — legacy)
+# ---------------------------------------------------------------------------
+
+def _demo_root() -> Any:
+    from flow_xray.value import Value
+    a = Value(2.0, label="a")
+    b = Value(-3.0, label="b")
+    c = Value(10.0, label="c")
+    L = ((a * b) + c).relu().tanh()
+    L.label = "L"
+    return L
+
+
+def cmd_demo(args: argparse.Namespace) -> int:
+    from flow_xray.export_dot import value_graph_to_dot, write_dot
+    from flow_xray.export_html import write_standalone_viewer_html
+    root = _demo_root()
+    forward = value_graph_to_dot(root, show_grad=False)
+    root.backward()
+    backward = value_graph_to_dot(root, show_grad=True)
+    if args.output_dir:
+        out = Path(args.output_dir)
+        out.mkdir(parents=True, exist_ok=True)
+        write_dot(str(out / "forward.dot"), forward)
+        write_dot(str(out / "backward.dot"), backward)
+        print(f"Wrote {out / 'forward.dot'} and {out / 'backward.dot'}", file=sys.stderr)
+        return 0
+    if args.html:
+        dot = backward if args.which == "backward" else forward
+        title = f"flow-xray demo ({args.which})"
+        write_standalone_viewer_html(args.html, dot, title=title)
+        print(f"Wrote {args.html} — open in browser (no dot/PNG).", file=sys.stderr)
+        return 0
+    if args.which == "backward":
+        sys.stdout.write(backward)
+    else:
+        sys.stdout.write(forward)
+    return 0
+
+
+def cmd_export(args: argparse.Namespace) -> int:
+    from flow_xray.export_dot import value_graph_to_dot, write_dot
+    from flow_xray.export_html import write_standalone_viewer_html
+    from flow_xray.value import Value
+    path = Path(args.script)
+    ns: dict[str, Any] = {"__name__": "__main__", "__file__": str(path)}
+    exec(compile(path.read_text(encoding="utf-8"), str(path), "exec"), ns, ns)
+    root = ns.get("root")
+    if root is None:
+        print("error: script must define variable `root` (a Value)", file=sys.stderr)
+        return 2
+    if not isinstance(root, Value):
+        print("error: `root` must be a flow_xray.Value", file=sys.stderr)
+        return 2
+    forward = value_graph_to_dot(root, show_grad=False)
+    if args.backward:
+        root.backward()
+        dot = value_graph_to_dot(root, show_grad=True)
+    else:
+        dot = forward
+    if args.html:
+        title = "flow-xray graph" + (" (backward)" if args.backward else " (forward)")
+        write_standalone_viewer_html(args.html, dot, title=title)
+        print(f"Wrote {args.html} — open in browser.", file=sys.stderr)
+        return 0
+    out_path = args.output
+    if out_path:
+        write_dot(out_path, dot)
+        print(out_path, file=sys.stderr)
+    else:
+        sys.stdout.write(dot)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+    p = argparse.ArgumentParser(prog="flow-xray", description="flow-xray — execution graph debugger")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    # -- gtype run -------------------------------------------------------
+    r = sub.add_parser("run", help="run a script with @trace, export HTML execution graph")
+    r.add_argument("script", help="path to Python file using @trace")
+    r.add_argument("--html", metavar="FILE.html", help="output path (default: <script>_trace.html)")
+    r.add_argument("--title", metavar="TEXT", help="title shown in the viewer")
+    r.set_defaults(func=cmd_run)
+
+    # -- gtype dot demo --------------------------------------------------
+    d = sub.add_parser("dot", help="scalar-Value DOT subcommands")
+    dot_sub = d.add_subparsers(dest="dot_cmd", required=True)
+    dd = dot_sub.add_parser("demo", help="built-in (a*b+c).relu().tanh() graph")
+    dd.add_argument("which", nargs="?", default="forward", choices=("forward", "backward"))
+    dd.add_argument("--output-dir", metavar="DIR")
+    dd.add_argument("--html", metavar="FILE.html")
+    dd.set_defaults(func=cmd_demo)
+
+    de = dot_sub.add_parser("export", help="run .py that defines `root` (Value)")
+    de.add_argument("script")
+    de.add_argument("-o", "--output", metavar="FILE.dot")
+    de.add_argument("--backward", action="store_true")
+    de.add_argument("--html", metavar="FILE.html")
+    de.set_defaults(func=cmd_export)
+
+    args = p.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

flow_xray/debugger.py

@@ -0,0 +1,119 @@
+"""
+Stepping / snapshot debugger — delivery hooks on top of core + export.
+
+Stepping model
+--------------
+
+1. **Two-phase (global)** — ``TwoStepDebugger``:
+   - Phase A: export DOT with ``data`` only (``show_grad=False``).
+   - Phase B: after ``backward()`` (or ``backward_from``), export DOT with ``grad`` on each node.
+
+2. **Per-node backward** — ``iter_backward_steps`` / ``GraphDebugger.backward_trace``:
+   - Start from ``zero_grad``, set ``root.grad = 1``, walk reverse topological order,
+     calling ``_backward()`` on **one** node at a time. After each call, partial gradients
+     are filled only along edges that have already been processed; later steps add more.
+   - This is for *inspection* of the backward schedule, not a separate math semantics.
+
+3. **Named snapshots** — ``GraphDebugger.named_snapshots`` returns strings (DOT) keyed by
+   ``forward``, ``after_backward``, and ``backward_step_{k}`` (k = 0..n-1 in reverse topo).
+
+**Rewind:** not supported; re-build the expression or keep a copy if you need replay.
+
+Double backward is not supported as a product guarantee; use ``zero_grad`` + single ``backward``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from flow_xray.export_dot import value_graph_to_dot
+from flow_xray.ir import graph_to_ir
+from flow_xray.value import Value, topological_order, zero_grad
+
+
+class TwoStepDebugger:
+    """
+    Two global phases: forward DOT (data only), backward DOT (data + grad).
+
+    Usage::
+
+        dbg = TwoStepDebugger(y)
+        dot1 = dbg.step_forward_dot()
+        y.backward()
+        dot2 = dbg.step_backward_dot()
+    """
+
+    __slots__ = ("_root",)
+
+    def __init__(self, root: Value) -> None:
+        self._root = root
+
+    def step_forward_dot(self) -> str:
+        return value_graph_to_dot(self._root, show_grad=False)
+
+    def step_backward_dot(self) -> str:
+        return value_graph_to_dot(self._root, show_grad=True)
+
+
+def iter_backward_steps(root: Value, *, seed: float = 1.0) -> Iterator[Value]:
+    """
+    Yield each ``Value`` in reverse topological order as its ``_backward`` is applied.
+
+    Mutates ``root`` subgraph gradients. Starts from a clean slate (zeros then seed).
+    """
+    zero_grad(root)
+    root.grad = float(seed)
+    for v in reversed(topological_order(root)):
+        v._backward()
+        yield v
+
+
+class GraphDebugger:
+    """
+    Captures DOT (+ optional IR) for forward, each backward micro-step, and final state.
+    """
+
+    __slots__ = ("root",)
+
+    def __init__(self, root: Value) -> None:
+        self.root = root
+
+    def dot_forward(self) -> str:
+        return value_graph_to_dot(self.root, show_grad=False)
+
+    def dot_backward(self) -> str:
+        return value_graph_to_dot(self.root, show_grad=True)
+
+    def ir_forward(self) -> dict[str, Any]:
+        return graph_to_ir(self.root, include_grad=False)
+
+    def ir_backward(self) -> dict[str, Any]:
+        return graph_to_ir(self.root, include_grad=True)
+
+    def named_snapshots(
+        self,
+        *,
+        seed: float = 1.0,
+        include_step_dots: bool = True,
+    ) -> dict[str, str]:
+        """
+        Return DOT strings. Keys: ``forward``, optional ``backward_step_0``..``n-1``,
+        ``after_backward``.
+
+        Runs backward on ``self.root`` (mutating grads). Caller should not rely on pre-backward
+        grad state after this returns.
+        """
+        out: dict[str, str] = {"forward": self.dot_forward()}
+        zero_grad(self.root)
+        self.root.grad = float(seed)
+        rev = list(reversed(topological_order(self.root)))
+        if include_step_dots:
+            for k, v in enumerate(rev):
+                v._backward()
+                out[f"backward_step_{k}"] = value_graph_to_dot(self.root, show_grad=True)
+        else:
+            for v in rev:
+                v._backward()
+        out["after_backward"] = value_graph_to_dot(self.root, show_grad=True)
+        return out

flow_xray/export_dot.py

@@ -0,0 +1,50 @@
+"""DOT export adapter — inspection layer; does not mutate the graph."""
+
+from __future__ import annotations
+
+from flow_xray.value import Value, topological_order
+
+
+def _dot_escape(s: str) -> str:
+    return s.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def value_graph_to_dot(root: Value, *, show_grad: bool = False) -> str:
+    """
+    Emit Graphviz DOT for the DAG rooted at ``root``.
+
+    Node DOT ids use ``Value.node_id`` (stable for object lifetime).
+    """
+    nodes = topological_order(root)
+    lines = [
+        "digraph G {",
+        '  rankdir="BT";',
+        "  node [shape=box, fontname=Helvetica];",
+        "  edge [fontname=Helvetica, fontsize=10];",
+    ]
+    for v in nodes:
+        nid = v.node_id
+        title = _dot_escape(v.display_name)
+        parts = [title]
+        if v._op:
+            parts.append(f"op: {_dot_escape(v._op)}")
+        parts.append(f"data: {v.data:g}")
+        if show_grad:
+            parts.append(f"grad: {v.grad:g}")
+        label = "\\n".join(parts)
+        lines.append(f'  {nid} [label="{label}"];')
+
+    for v in nodes:
+        child_id = v.node_id
+        for p in v._prev:
+            pid = p.node_id
+            op_lbl = _dot_escape(v._op or "")
+            lines.append(f'  {pid} -> {child_id} [label="{op_lbl}"];')
+
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def write_dot(path: str, dot: str) -> None:
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(dot)

flow_xray/export_html.py

@@ -0,0 +1,219 @@
+"""Single-file HTML viewer: embedded DOT + WASM Graphviz (no local ``dot``, no server)."""
+
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+
+
+def standalone_viewer_html(dot: str, *, title: str = "flow-xray graph") -> str:
+    """
+    Return one HTML document that inlines ``dot`` as JSON so ``file://`` works.
+
+    Rendering uses ``@hpcc-js/wasm-graphviz`` from jsDelivr (needs network once).
+    If WASM fails, the raw DOT is shown in a ``<pre>``.
+    """
+    dot_js = json.dumps(dot)
+    safe_title = html.escape(title, quote=True)
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>{safe_title}</title>
+  <style>
+    body {{ font-family: system-ui, sans-serif; margin: 1rem; }}
+    #host {{ overflow: auto; border: 1px solid #ccc; padding: 0.5rem; min-height: 200px; }}
+    #fallback {{ white-space: pre-wrap; font-size: 12px; display: none; }}
+    .err {{ color: #b00; }}
+  </style>
+</head>
+<body>
+  <h1>{safe_title}</h1>
+  <p id="status">Rendering…</p>
+  <div id="host"></div>
+  <pre id="fallback"></pre>
+  <script type="module">
+    const status = document.getElementById("status");
+    const host = document.getElementById("host");
+    const fallback = document.getElementById("fallback");
+    const dot = {dot_js};
+    async function run() {{
+      try {{
+        const {{ Graphviz }} = await import(
+          "https://cdn.jsdelivr.net/npm/@hpcc-js/wasm-graphviz@1.6.1/+esm"
+        );
+        const gv = await Graphviz.load();
+        const svg = gv.dot(dot);
+        host.innerHTML = svg;
+        status.textContent = "Rendered (WASM Graphviz). Opened as local HTML — no PNG/dot CLI.";
+      }} catch (e) {{
+        status.innerHTML =
+          "<span class='err'>WASM render failed (offline or blocked CDN).</span> DOT below.";
+        console.error(e);
+        fallback.style.display = "block";
+        fallback.textContent = dot;
+      }}
+    }}
+    run();
+  </script>
+</body>
+</html>
+"""
+
+
+def write_standalone_viewer_html(path: str | Path, dot: str, *, title: str = "flow-xray graph") -> None:
+    Path(path).write_text(standalone_viewer_html(dot, title=title), encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Execution-trace viewer (dark theme, interactive)
+# ---------------------------------------------------------------------------
+
+def trace_to_standalone_html(
+    trace_result: object,
+    *,
+    title: str = "flow-xray trace",
+) -> str:
+    """
+    Return a self-contained HTML document that renders a ``TraceResult``
+    as an interactive execution DAG (dark theme, Graphviz WASM, click-to-inspect).
+    """
+    trace_json = json.dumps(trace_result.to_dict(), ensure_ascii=False)  # type: ignore[union-attr]
+    safe_title = html.escape(title, quote=True)
+    return _TRACE_HTML_TEMPLATE.replace("__TITLE__", safe_title).replace("__TRACE_JSON__", trace_json)
+
+
+_TRACE_HTML_TEMPLATE = r"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>__TITLE__</title>
+<style>
+*{box-sizing:border-box;margin:0;padding:0}
+body{background:#0d1117;color:#c9d1d9;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Helvetica,Arial,sans-serif;display:flex;flex-direction:column;height:100vh}
+header{padding:10px 20px;background:#161b22;border-bottom:1px solid #30363d;display:flex;align-items:center;gap:18px;flex-shrink:0}
+header h1{font-size:15px;font-weight:600}
+.st{font-size:13px;color:#8b949e}.st b{color:#c9d1d9}.st b.err{color:#f85149}
+#main{display:flex;flex:1;overflow:hidden}
+#graph{flex:1;overflow:auto;display:flex;align-items:center;justify-content:center;padding:20px}
+#graph svg{max-width:100%;height:auto;cursor:grab}
+#det{width:370px;background:#161b22;border-left:1px solid #30363d;overflow-y:auto;padding:16px;font-size:13px;flex-shrink:0}
+.dt{font-size:14px;font-weight:600;margin-bottom:10px;color:#f0f6fc}
+.ds{margin-bottom:14px}
+.dl{font-size:10px;text-transform:uppercase;color:#8b949e;margin-bottom:3px;letter-spacing:.5px}
+.dv{background:#0d1117;border:1px solid #30363d;border-radius:6px;padding:8px 10px;font-family:'SF Mono','Fira Code',monospace;font-size:12px;white-space:pre-wrap;word-break:break-all;max-height:220px;overflow-y:auto;color:#c9d1d9}
+.ok{color:#3fb950}.er{color:#f85149}.warn{color:#d29922}
+#graph .node{cursor:pointer}
+#graph .node:hover polygon{stroke:#58a6ff!important;stroke-width:2}
+#graph .selected polygon{stroke:#58a6ff!important;stroke-width:2.5}
+#graph .edge path{stroke:#30363d!important}
+#graph .edge polygon{fill:#30363d!important;stroke:#30363d!important}
+#graph text{fill:#fff!important}
+#hint{color:#484f58;text-align:center;padding:40px 20px;line-height:1.6}
+#fb{white-space:pre-wrap;font-size:12px;color:#8b949e;padding:20px;display:none}
+</style>
+</head>
+<body>
+<header>
+ <h1>__TITLE__</h1>
+ <span class="st">Nodes: <b id="sn">-</b></span>
+ <span class="st">Total: <b id="stm">-</b></span>
+ <span class="st">Errors: <b id="se" class="err">-</b></span>
+ <span class="st" id="stok" style="display:none">Tokens: <b id="stokv">-</b></span>
+ <span class="st" id="scost" style="display:none">Cost: <b id="scostv" class="warn">-</b></span>
+</header>
+<div id="main">
+ <div id="graph"><div id="hint">Rendering graph…</div></div>
+ <div id="det"><div id="hint">Click a node to inspect</div></div>
+</div>
+<pre id="fb"></pre>
+<script type="module">
+const TRACE=__TRACE_JSON__;
+function flat(roots,pid){let r=[];(roots||[]).forEach(n=>{r.push({...n,pid});r=r.concat(flat(n.children,n.id))});return r}
+const nodes=flat(TRACE.nodes,null);
+const byId=Object.fromEntries(nodes.map(n=>[n.id,n]));
+document.getElementById("sn").textContent=nodes.length;
+const errs=nodes.filter(n=>n.error).length;
+document.getElementById("se").textContent=errs;
+const total=TRACE.nodes.reduce((s,n)=>s+n.latency_ms,0);
+document.getElementById("stm").textContent=total.toFixed(1)+"ms";
+let sumTok=0,sumCost=0;
+nodes.forEach(n=>{if(n.meta){if(n.meta.total_tokens)sumTok+=n.meta.total_tokens;if(n.meta.estimated_cost_usd)sumCost+=n.meta.estimated_cost_usd}});
+if(sumTok){document.getElementById("stok").style.display="";document.getElementById("stokv").textContent=sumTok}
+if(sumCost){document.getElementById("scost").style.display="";document.getElementById("scostv").textContent="$"+sumCost.toFixed(6)}
+
+function mkDot(){
+  let d='digraph G {\n  rankdir="TB";\n  bgcolor="transparent";\n';
+  d+='  node [shape=box,style="rounded,filled",fontname="Helvetica",fontsize=11,margin="0.3,0.15"];\n';
+  d+='  edge [color="#30363d",arrowsize=0.7];\n';
+  for(const n of nodes){
+    const c=n.error?"#da3633":n.latency_ms>1000?"#9e6a03":"#238636";
+    const ms=n.latency_ms<1?n.latency_ms.toFixed(2):n.latency_ms<100?n.latency_ms.toFixed(1):Math.round(n.latency_ms);
+    let lb=n.name+"\\n"+ms+"ms";
+    if(n.meta&&n.meta.total_tokens)lb+="\\n"+n.meta.total_tokens+" tok";
+    d+=`  ${n.id} [label="${lb}",fillcolor="${c}",fontcolor="white",tooltip="${n.id}"];\n`;
+  }
+  for(const n of nodes){if(n.pid)d+=`  ${n.pid} -> ${n.id};\n`}
+  d+='}';return d;
+}
+
+const det=document.getElementById("det");
+function showDet(n){
+  if(!n){det.innerHTML='<div id="hint">Click a node to inspect</div>';return}
+  const st=n.error?`<span class="er">ERROR</span>`:`<span class="ok">OK</span>`;
+  const ms=n.latency_ms.toFixed(2);
+  let h=`<div class="dt">${esc(n.name)}</div>`;
+  h+=`<div class="ds"><div class="dl">Status</div><div class="dv">${st}</div></div>`;
+  h+=`<div class="ds"><div class="dl">Latency</div><div class="dv">${ms} ms</div></div>`;
+  if(n.error)h+=`<div class="ds"><div class="dl">Error</div><div class="dv er">${esc(n.error)}</div></div>`;
+  const inp=Object.entries(n.inputs||{});
+  if(inp.length){h+=`<div class="ds"><div class="dl">Input</div>`;inp.forEach(([k,v])=>{h+=`<div class="dv"><b>${esc(k)}</b>: ${esc(v)}</div>`});h+=`</div>`}
+  if(n.output!=null)h+=`<div class="ds"><div class="dl">Output</div><div class="dv">${esc(String(n.output))}</div></div>`;
+  if(n.meta){
+    const m=n.meta;
+    if(m.model)h+=`<div class="ds"><div class="dl">Model</div><div class="dv">${esc(m.model)}</div></div>`;
+    const toks=[];
+    if(m.prompt_tokens!=null)toks.push("prompt: "+m.prompt_tokens);
+    if(m.completion_tokens!=null)toks.push("completion: "+m.completion_tokens);
+    if(m.total_tokens!=null)toks.push("total: "+m.total_tokens);
+    if(toks.length)h+=`<div class="ds"><div class="dl">Tokens</div><div class="dv">${esc(toks.join("  ·  "))}</div></div>`;
+    if(m.estimated_cost_usd!=null)h+=`<div class="ds"><div class="dl">Est. cost</div><div class="dv warn">$${m.estimated_cost_usd.toFixed(6)}</div></div>`;
+    const extra=Object.entries(m).filter(([k])=>!["model","prompt_tokens","completion_tokens","total_tokens","estimated_cost_usd"].includes(k));
+    if(extra.length){h+=`<div class="ds"><div class="dl">Meta</div>`;extra.forEach(([k,v])=>{h+=`<div class="dv"><b>${esc(k)}</b>: ${esc(JSON.stringify(v))}</div>`});h+=`</div>`}
+  }
+  det.innerHTML=h;
+}
+function esc(s){const d=document.createElement('div');d.textContent=String(s);return d.innerHTML}
+
+async function render(){
+  const dot=mkDot();
+  const gc=document.getElementById("graph");
+  try{
+    const {Graphviz}=await import("https://cdn.jsdelivr.net/npm/@hpcc-js/wasm-graphviz@1.6.1/+esm");
+    const gv=await Graphviz.load();
+    const svg=gv.dot(dot);
+    gc.innerHTML=svg;
+    gc.querySelectorAll('.node').forEach(el=>{
+      const title=el.querySelector('title');
+      if(!title)return;
+      const nid=title.textContent.trim();
+      el.addEventListener('click',()=>{
+        gc.querySelectorAll('.selected').forEach(s=>s.classList.remove('selected'));
+        el.classList.add('selected');
+        showDet(byId[nid]);
+      });
+    });
+  }catch(e){
+    console.error(e);
+    gc.innerHTML='<div id="hint" style="color:#f85149">WASM render failed. DOT below.</div>';
+    const fb=document.getElementById("fb");fb.style.display="block";fb.textContent=dot;
+  }
+}
+render();
+</script>
+</body>
+</html>
+"""

flow_xray/ir.py

@@ -0,0 +1,39 @@
+"""JSON-serializable graph IR — stable ids, no Python object identity in payload."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from flow_xray.value import Value, topological_order
+
+
+def graph_to_ir(root: Value, *, include_grad: bool = True) -> dict[str, Any]:
+    """
+    Build a normalized dict suitable for viewers, CLI, and regression tests.
+
+    Schema version 1:
+      version, root_id, nodes[{id, op, label, data, grad?, parents: [id,...]}]
+    """
+    nodes = topological_order(root)
+    payload: dict[str, Any] = {
+        "version": 1,
+        "root_id": root.node_id,
+        "nodes": [],
+    }
+    for v in nodes:
+        entry: dict[str, Any] = {
+            "id": v.node_id,
+            "op": v._op,
+            "label": v.label,
+            "data": v.data,
+            "parents": [p.node_id for p in v._prev],
+        }
+        if include_grad:
+            entry["grad"] = v.grad
+        payload["nodes"].append(entry)
+    return payload
+
+
+def ir_to_json(root: Value, *, include_grad: bool = True, indent: int | None = 2) -> str:
+    return json.dumps(graph_to_ir(root, include_grad=include_grad), indent=indent)

flow_xray/static/viewer.html

@@ -0,0 +1,52 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>flow-xray graph viewer</title>
+  <style>
+    body { font-family: system-ui, sans-serif; margin: 1rem; }
+    #host { overflow: auto; border: 1px solid #ccc; padding: 0.5rem; min-height: 200px; }
+    #fallback { white-space: pre-wrap; font-size: 12px; display: none; }
+    .err { color: #b00; }
+  </style>
+</head>
+<body>
+  <h1>flow-xray graph</h1>
+  <p id="status">Loading DOT…</p>
+  <div id="host"></div>
+  <pre id="fallback"></pre>
+  <script type="module">
+    const status = document.getElementById("status");
+    const host = document.getElementById("host");
+    const fallback = document.getElementById("fallback");
+    async function run() {
+      let dot;
+      try {
+        const r = await fetch("/graph.dot");
+        dot = await r.text();
+      } catch (e) {
+        status.textContent = "Could not load /graph.dot";
+        status.className = "err";
+        return;
+      }
+      try {
+        const { Graphviz } = await import(
+          "https://cdn.jsdelivr.net/npm/@hpcc-js/wasm-graphviz@1.6.1/+esm"
+        );
+        const gv = await Graphviz.load();
+        const svg = gv.dot(dot);
+        host.innerHTML = svg;
+        status.textContent = "Rendered (WASM Graphviz).";
+      } catch (e) {
+        status.innerHTML =
+          "<span class='err'>WASM render failed (offline or blocked CDN).</span> DOT below.";
+        console.error(e);
+        fallback.style.display = "block";
+        fallback.textContent = dot;
+      }
+    }
+    run();
+  </script>
+</body>
+</html>