flow-xray 0.2.0__tar.gz

flow_xray-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+
+# secrets
+.env
+
+# generated artifacts (re-create with flow-xray run / python graph_debug.py)
+*.png
+!assets/*.png
+agent_trace.html
+forward.html
+backward.html

flow_xray-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kirillostapenko
+
+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.

flow_xray-0.2.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: flow-xray
+Version: 0.2.0
+Summary: Execution graph debugger — see what your agent / pipeline actually does.
+Project-URL: Homepage, https://github.com/kroq86/flow-xray
+Project-URL: Repository, https://github.com/kroq86/flow-xray
+Project-URL: Issues, https://github.com/kroq86/flow-xray/issues
+Author-email: KirillOstapenko <djkroq@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: DAG,LLM,agent,debugger,execution-graph,observability,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.png" alt="flow-xray" width="100%">
+</p>
+
+<p align="center">
+  <b>See what your agent actually does.</b><br>
+  One decorator, one HTML file — a visual execution graph instead of logs.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/flow-xray/"><img src="https://img.shields.io/pypi/v/flow-xray?color=blue" alt="PyPI"></a>
+  <a href="https://github.com/kroq86/flow-xray/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
+</p>
+
+---
+
+```python
+from flow_xray import trace
+
+@trace
+def call_llm(prompt):
+    return openai.chat(prompt)
+
+@trace
+def agent(query):
+    plan = call_llm(f"plan: {query}")
+    return call_llm(f"answer based on: {plan}")
+
+result = trace.run(agent, "weather in Tokyo?")
+result.to_html("trace.html")
+```
+
+<p align="center">
+  <img src="assets/demo.png" alt="flow-xray trace viewer" width="100%">
+</p>
+
+Open `trace.html` — you get a **DAG** of every traced step with inputs, outputs, latency, tokens, cost, and errors. Click a node to inspect. No server, no account, no log viewer — one local file.
+
+## Install
+
+```bash
+pip install flow-xray
+```
+
+## Usage
+
+### Decorator + `trace.run`
+
+```python
+from flow_xray import trace
+
+@trace
+def step_a(x):
+    return x + 1
+
+@trace
+def pipeline(x):
+    return step_a(x) * 2
+
+result = trace.run(pipeline, 5)
+result.to_html("pipeline.html")
+```
+
+### CLI
+
+```bash
+flow-xray run my_agent.py --html trace.html
+```
+
+The script must use `@trace` on the functions you want captured. The CLI provides the session; just call your functions normally.
+
+### Token / cost tracking
+
+Token usage and estimated cost are auto-extracted from OpenAI response objects, or you can set them manually:
+
+```python
+@trace
+def call_llm(prompt):
+    resp = openai.chat.completions.create(...)
+    trace.meta(model=resp.model,
+               prompt_tokens=resp.usage.prompt_tokens,
+               completion_tokens=resp.usage.completion_tokens)
+    return resp.choices[0].message.content
+```
+
+### What you see
+
+- **Nodes** = function calls (name + latency + tokens)
+- **Edges** = caller → callee
+- **Green** = OK, **Red** = error, **Yellow** = slow (>1s)
+- **Header** = total nodes, latency, tokens, estimated cost
+- **Click a node** → side panel shows inputs, output, error, timing, model, tokens, cost
+
+## Why this exists
+
+Langfuse, Helicone, LangSmith — they give you **timelines and logs**.
+
+But when your agent pipeline branches, retries, or chains 6 tools — you don't need another table. You need a **graph**.
+
+flow-xray is **not** an agent framework. It's the layer **below** them — like Chrome DevTools is to browsers.
+
+## How it works
+
+`@trace` wraps functions. When called inside a `trace.run()` session (or `flow-xray run` CLI), it records:
+- function name
+- bound arguments
+- return value or exception
+- wall-clock latency
+- token usage and estimated cost (auto or manual)
+- parent/child relationships (call stack → DAG)
+
+`result.to_html()` embeds the trace as JSON in a self-contained HTML page that renders via WASM Graphviz (CDN, works offline after first load).
+
+## Also included
+
+Scalar autodiff core (micrograd-style `Value` graph with DOT/JSON export and stepping debugger) lives under `flow-xray dot` CLI and `from flow_xray import Value`. See `examples/` and `plan.md`.
+
+## License
+
+MIT

flow_xray-0.2.0/README.md

@@ -0,0 +1,121 @@
+<p align="center">
+  <img src="assets/banner.png" alt="flow-xray" width="100%">
+</p>
+
+<p align="center">
+  <b>See what your agent actually does.</b><br>
+  One decorator, one HTML file — a visual execution graph instead of logs.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/flow-xray/"><img src="https://img.shields.io/pypi/v/flow-xray?color=blue" alt="PyPI"></a>
+  <a href="https://github.com/kroq86/flow-xray/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <img src="https://img.shields.io/badge/python-3.10+-blue" alt="Python">
+</p>
+
+---
+
+```python
+from flow_xray import trace
+
+@trace
+def call_llm(prompt):
+    return openai.chat(prompt)
+
+@trace
+def agent(query):
+    plan = call_llm(f"plan: {query}")
+    return call_llm(f"answer based on: {plan}")
+
+result = trace.run(agent, "weather in Tokyo?")
+result.to_html("trace.html")
+```
+
+<p align="center">
+  <img src="assets/demo.png" alt="flow-xray trace viewer" width="100%">
+</p>
+
+Open `trace.html` — you get a **DAG** of every traced step with inputs, outputs, latency, tokens, cost, and errors. Click a node to inspect. No server, no account, no log viewer — one local file.
+
+## Install
+
+```bash
+pip install flow-xray
+```
+
+## Usage
+
+### Decorator + `trace.run`
+
+```python
+from flow_xray import trace
+
+@trace
+def step_a(x):
+    return x + 1
+
+@trace
+def pipeline(x):
+    return step_a(x) * 2
+
+result = trace.run(pipeline, 5)
+result.to_html("pipeline.html")
+```
+
+### CLI
+
+```bash
+flow-xray run my_agent.py --html trace.html
+```
+
+The script must use `@trace` on the functions you want captured. The CLI provides the session; just call your functions normally.
+
+### Token / cost tracking
+
+Token usage and estimated cost are auto-extracted from OpenAI response objects, or you can set them manually:
+
+```python
+@trace
+def call_llm(prompt):
+    resp = openai.chat.completions.create(...)
+    trace.meta(model=resp.model,
+               prompt_tokens=resp.usage.prompt_tokens,
+               completion_tokens=resp.usage.completion_tokens)
+    return resp.choices[0].message.content
+```
+
+### What you see
+
+- **Nodes** = function calls (name + latency + tokens)
+- **Edges** = caller → callee
+- **Green** = OK, **Red** = error, **Yellow** = slow (>1s)
+- **Header** = total nodes, latency, tokens, estimated cost
+- **Click a node** → side panel shows inputs, output, error, timing, model, tokens, cost
+
+## Why this exists
+
+Langfuse, Helicone, LangSmith — they give you **timelines and logs**.
+
+But when your agent pipeline branches, retries, or chains 6 tools — you don't need another table. You need a **graph**.
+
+flow-xray is **not** an agent framework. It's the layer **below** them — like Chrome DevTools is to browsers.
+
+## How it works
+
+`@trace` wraps functions. When called inside a `trace.run()` session (or `flow-xray run` CLI), it records:
+- function name
+- bound arguments
+- return value or exception
+- wall-clock latency
+- token usage and estimated cost (auto or manual)
+- parent/child relationships (call stack → DAG)
+
+`result.to_html()` embeds the trace as JSON in a self-contained HTML page that renders via WASM Graphviz (CDN, works offline after first load).
+
+## Also included
+
+Scalar autodiff core (micrograd-style `Value` graph with DOT/JSON export and stepping debugger) lives under `flow-xray dot` CLI and `from flow_xray import Value`. See `examples/` and `plan.md`.
+
+## License
+
+MIT

flow_xray-0.2.0/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-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-0.2.0/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-0.2.0/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-0.2.0/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)