recursionlens 0.1.2__py3-none-any.whl

recursionlens/__init__.py

@@ -0,0 +1,16 @@
+"""RecursionLens: recursive execution analysis for JupyterLab."""
+
+from ._model import CallNode, DAGNode
+from ._report import ComparisonReport, TraceReport
+from ._trace import trace
+
+__version__ = "0.1.2"
+
+__all__ = [
+    "CallNode",
+    "ComparisonReport",
+    "DAGNode",
+    "TraceReport",
+    "trace",
+    "__version__",
+]

recursionlens/_model.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+
+@dataclass
+class CallNode:
+    """One observed function invocation, including cache-only invocations."""
+
+    call_id: int
+    identity: str
+    signature: str
+    depth: int
+    status: str = "running"
+    result: Optional[str] = None
+    error: Optional[str] = None
+    repeated: bool = False
+    children: List["CallNode"] = field(default_factory=list)
+
+    @property
+    def cached(self) -> bool:
+        return self.status == "cached"
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "call_id": self.call_id,
+            "identity": self.identity,
+            "signature": self.signature,
+            "depth": self.depth,
+            "status": self.status,
+            "result": self.result,
+            "error": self.error,
+            "repeated": self.repeated,
+            "children": [child.to_dict() for child in self.children],
+        }
+
+
+@dataclass
+class DAGNode:
+    """All invocations with one internal argument identity, merged together."""
+
+    identity: str
+    signature: str
+    calls: int = 0
+    executed: int = 0
+    cached: int = 0
+    result: Optional[str] = None
+    children: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "identity": self.identity,
+            "signature": self.signature,
+            "calls": self.calls,
+            "executed": self.executed,
+            "cached": self.cached,
+            "result": self.result,
+            "children": list(self.children),
+        }
+
+
+def build_dag(nodes: Iterable[CallNode]) -> Tuple[List[DAGNode], List[Dict[str, str]]]:
+    """Compress a call forest into a deterministic subproblem DAG."""
+
+    merged: Dict[str, DAGNode] = {}
+    edges = set()
+
+    def visit(node: CallNode) -> None:
+        dag_node = merged.get(node.identity)
+        if dag_node is None:
+            dag_node = DAGNode(identity=node.identity, signature=node.signature)
+            merged[node.identity] = dag_node
+
+        dag_node.calls += 1
+        if node.cached:
+            dag_node.cached += 1
+        else:
+            dag_node.executed += 1
+        if dag_node.result is None and node.result is not None:
+            dag_node.result = node.result
+
+        for child in node.children:
+            if child.identity not in dag_node.children:
+                dag_node.children.append(child.identity)
+            edges.add((node.identity, child.identity))
+            visit(child)
+
+    for root in nodes:
+        visit(root)
+
+    edge_dicts = [{"source": source, "target": target} for source, target in sorted(edges)]
+    return list(merged.values()), edge_dicts

recursionlens/_render.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+import html
+import re
+from collections import defaultdict
+from typing import Dict, List, Tuple
+
+from ._model import DAGNode
+
+_CSS = """
+.rl-wrap{--rl-blue:#185fa5;--rl-blue-bg:#e6f1fb;--rl-coral:#d85a30;--rl-coral-bg:#faece7;--rl-green:#0f6e56;--rl-green-bg:#e1f5ee;--rl-text:#242424;--rl-muted:#66645f;--rl-border:#dedcd5;color:var(--rl-text);background:#fff;border:1px solid var(--rl-border);border-radius:12px;padding:18px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;line-height:1.5;box-sizing:border-box;margin:8px 0;max-width:100%;overflow:auto}
+.rl-wrap *{box-sizing:border-box}.rl-title{font-size:18px;font-weight:600;margin:0 0 4px}.rl-subtitle{color:var(--rl-muted);font-size:13px;margin:0 0 16px}.rl-metrics{display:grid;grid-template-columns:repeat(auto-fit,minmax(105px,1fr));gap:8px;margin:12px 0 18px}.rl-metric{background:#f6f5f1;border-radius:8px;padding:10px}.rl-metric-label{font-size:11px;color:var(--rl-muted)}.rl-metric-value{font-size:21px;font-weight:600;margin-top:2px}.rl-section{font-size:14px;font-weight:600;margin:18px 0 8px}.rl-tree,.rl-tree ul{list-style:none;padding-left:20px}.rl-tree{padding-left:0}.rl-tree details{margin:4px 0}.rl-tree summary{cursor:pointer;padding:5px 8px;border-radius:6px;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px}.rl-tree summary:hover{background:var(--rl-blue-bg)}.rl-result{color:var(--rl-muted);font-size:11px;margin-left:6px}.rl-badge{display:inline-block;border-radius:4px;padding:1px 5px;margin-left:5px;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;font-size:10px;font-weight:500}.rl-repeat{color:#993c1d;background:var(--rl-coral-bg)}.rl-cached{color:var(--rl-green);background:var(--rl-green-bg)}.rl-error{color:#a32d2d;background:#fcebeb}.rl-warning{color:#854f0b;background:#faeeda;border-radius:6px;padding:8px;margin:8px 0;font-size:12px}.rl-dag{max-width:100%;overflow:auto;background:#fafaf8;border-radius:8px;padding:8px}.rl-legend{font-size:11px;color:var(--rl-muted);margin:6px 0}.rl-table{border-collapse:collapse;width:100%;font-size:12px;margin:8px 0 16px}.rl-table th,.rl-table td{text-align:right;border-bottom:1px solid var(--rl-border);padding:8px}.rl-table th:first-child,.rl-table td:first-child{text-align:left}.rl-table th{color:var(--rl-muted);font-weight:500}.rl-delta-up{color:#a32d2d}.rl-delta-down{color:var(--rl-green)}.rl-columns{display:grid;grid-template-columns:repeat(auto-fit,minmax(300px,1fr));gap:12px}.rl-note{font-size:12px;color:var(--rl-muted)}.rl-expanded{max-width:100%;overflow:auto;background:#fafaf8;border-radius:8px;padding:8px}.rl-expanded svg{display:block;margin:auto}
+"""
+
+
+def esc(value: object) -> str:
+    return html.escape(str(value), quote=True)
+
+
+def short(value: str, limit: int = 34) -> str:
+    return value if len(value) <= limit else value[: limit - 3] + "..."
+
+
+def compact_call(signature: str, limit: int = 18) -> str:
+    """Remove parameter names for the compact SVG tree while keeping values."""
+
+    if "(" not in signature or not signature.endswith(")"):
+        return short(signature, limit)
+    name, arguments = signature.split("(", 1)
+    arguments = arguments[:-1]
+    arguments = re.sub(r"(^|, )([A-Za-z_]\w*)=", r"\1", arguments)
+    return short(f"{name}({arguments})", limit)
+
+
+def metric_cards(report) -> str:
+    metrics = [
+        ("Observed calls", report.total_calls),
+        ("Executed bodies", report.executed_calls),
+        ("Cache hits", report.cached_calls),
+        ("Unique subproblems", report.unique_subproblems),
+        ("Repeated calls", report.repeated_calls),
+        ("Maximum depth", report.max_depth),
+    ]
+    cards = "".join(
+        f'<div class="rl-metric"><div class="rl-metric-label">{esc(label)}</div>'
+        f'<div class="rl-metric-value">{esc(value)}</div></div>'
+        for label, value in metrics
+    )
+    return f'<div class="rl-metrics">{cards}</div>'
+
+
+def report_header(report) -> str:
+    mode = "memoized" if report.memoize else "naive"
+    if report.succeeded:
+        outcome = f"returned <code>{esc(report.result)}</code>"
+    else:
+        outcome = f"raised <code>{esc(report.error)}</code>"
+    warnings = "".join(
+        f'<div class="rl-warning">{esc(message)}</div>' for message in report.warnings
+    )
+    if report.truncated:
+        warnings += (
+            '<div class="rl-warning">The recording limit was reached. '
+            "Tree and DAG metrics only include recorded nodes; observed calls still counts every call.</div>"
+        )
+    return (
+        f'<h2 class="rl-title">RecursionLens · {esc(report.function_name)}</h2>'
+        f'<p class="rl-subtitle">{mode} run · {outcome}</p>'
+        + metric_cards(report)
+        + warnings
+    )
+
+
+def render_tree_node(node) -> str:
+    badges = ""
+    if node.repeated:
+        badges += '<span class="rl-badge rl-repeat">repeated</span>'
+    if node.cached:
+        badges += '<span class="rl-badge rl-cached">cache hit</span>'
+    if node.status == "error":
+        badges += '<span class="rl-badge rl-error">error</span>'
+
+    outcome = ""
+    if node.result is not None:
+        outcome = f'<span class="rl-result">→ {esc(short(node.result, 60))}</span>'
+    elif node.error is not None:
+        outcome = f'<span class="rl-result">{esc(short(node.error, 60))}</span>'
+
+    open_attr = " open" if node.depth <= 2 else ""
+    children = ""
+    if node.children:
+        children = "<ul>" + "".join(render_tree_node(child) for child in node.children) + "</ul>"
+    return (
+        f"<li><details{open_attr}><summary>{esc(short(node.signature, 90))}"
+        f"{badges}{outcome}</summary>{children}</details></li>"
+    )
+
+
+def render_tree(report) -> str:
+    roots = "".join(render_tree_node(root) for root in report.roots)
+    return (
+        '<h3 class="rl-section">Call tree</h3>'
+        '<div class="rl-legend">Each node is one invocation. Expand a node to inspect its children.</div>'
+        f'<ul class="rl-tree">{roots}</ul>'
+    )
+
+
+def render_expanded_tree(report, limit: int = 120) -> str:
+    """Render every selected invocation as a compact, fully visible SVG tree."""
+
+    selected = []
+    child_lists = {}
+    remaining = [limit]
+
+    def collect(node) -> bool:
+        if remaining[0] <= 0:
+            return False
+        selected.append(node)
+        remaining[0] -= 1
+        child_lists[id(node)] = []
+        for child in node.children:
+            if collect(child):
+                child_lists[id(node)].append(child)
+        return True
+
+    for root in report.roots:
+        collect(root)
+
+    positions: Dict[int, Tuple[float, float]] = {}
+    leaf_cursor = [0]
+    maximum_depth = 0
+
+    def place(node, depth: int) -> None:
+        nonlocal maximum_depth
+        maximum_depth = max(maximum_depth, depth)
+        children = child_lists[id(node)]
+        if not children:
+            x = 80 + leaf_cursor[0] * 135
+            leaf_cursor[0] += 1
+        else:
+            for child in children:
+                place(child, depth + 1)
+            first_x = positions[id(children[0])][0]
+            last_x = positions[id(children[-1])][0]
+            x = (first_x + last_x) / 2
+        positions[id(node)] = (x, 24 + depth * 72)
+
+    for root in report.roots:
+        if id(root) in child_lists:
+            place(root, 0)
+
+    tree_width = 160 + max(0, leaf_cursor[0] - 1) * 135
+    width = max(600, tree_width)
+    horizontal_shift = (width - tree_width) / 2
+    if horizontal_shift:
+        positions = {
+            node_id: (x + horizontal_shift, y)
+            for node_id, (x, y) in positions.items()
+        }
+    height = max(110, 24 + maximum_depth * 72 + 56)
+    parts = [
+        f'<svg role="img" aria-label="Fully expanded recursion tree for {esc(report.function_name)}" '
+        f'viewBox="0 0 {width} {height}" width="{width}" height="{height}" '
+        'xmlns="http://www.w3.org/2000/svg">',
+        f"<title>{esc(report.function_name)} expanded call tree</title>",
+    ]
+
+    for parent in selected:
+        parent_x, parent_y = positions[id(parent)]
+        for child in child_lists[id(parent)]:
+            child_x, child_y = positions[id(child)]
+            parts.append(
+                f'<path class="rl-expanded-edge" d="M{parent_x},{parent_y + 28} '
+                f'L{child_x},{child_y + 6}" fill="none" stroke="#a9a7a0" stroke-width="1"/>'
+            )
+
+    for node in selected:
+        x, y = positions[id(node)]
+        note = [node.signature]
+        if node.cached:
+            note.append("cache hit")
+            color = "#0f6e56"
+            decoration = ""
+        elif node.status == "error":
+            note.append(node.error or "error")
+            color = "#a32d2d"
+            decoration = ""
+        elif node.repeated:
+            note.append("repeated")
+            color = "#993c1d"
+            decoration = ' text-decoration="underline"'
+        else:
+            color = "#242424"
+            decoration = ""
+        if node.result is not None:
+            note.append(f"returned {node.result}")
+        parts.extend(
+            [
+                f'<g class="rl-expanded-node"><title>{esc(" · ".join(note))}</title>',
+                f'<text x="{x}" y="{y + 17}" text-anchor="middle" '
+                f'font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="12" '
+                f'fill="{color}"{decoration}>{esc(compact_call(node.signature))}</text></g>',
+            ]
+        )
+    parts.append("</svg>")
+
+    omitted = report.recorded_calls - len(selected)
+    notice = (
+        f'<p class="rl-note">Showing the first {limit} calls; {omitted} omitted.</p>'
+        if omitted > 0
+        else ""
+    )
+    return (
+        '<h3 class="rl-section">Expanded call tree</h3>'
+        f'<div class="rl-legend">All {len(selected)} calls are visible. '
+        "Underlined coral = repeated; green = cache hit; red = error.</div>"
+        f'<div class="rl-expanded">{"".join(parts)}</div>{notice}'
+    )
+
+
+def dag_depths(nodes: List[DAGNode]) -> Dict[str, int]:
+    children = {node.identity: node.children for node in nodes}
+    known = set(children)
+    memo: Dict[str, int] = {}
+
+    def depth(identity: str, visiting: set) -> int:
+        if identity in memo:
+            return memo[identity]
+        if identity in visiting:
+            return 0
+        next_nodes = [child for child in children.get(identity, []) if child in known]
+        value = 0 if not next_nodes else 1 + max(depth(child, visiting | {identity}) for child in next_nodes)
+        memo[identity] = value
+        return value
+
+    return {node.identity: depth(node.identity, set()) for node in nodes}
+
+
+def render_dag(report) -> str:
+    nodes = report.dag_nodes
+    omitted = max(0, len(nodes) - 40)
+    nodes = nodes[:40]
+    known = {node.identity for node in nodes}
+    depths = dag_depths(nodes)
+    layers: Dict[int, List[DAGNode]] = defaultdict(list)
+    for node in nodes:
+        layers[depths[node.identity]].append(node)
+
+    box_width, box_height = 190, 52
+    horizontal_gap, vertical_gap = 235, 74
+    positions: Dict[str, Tuple[float, float]] = {}
+    maximum_depth = max(layers, default=0)
+    for depth, layer in layers.items():
+        for index, node in enumerate(layer):
+            positions[node.identity] = (
+                20 + (maximum_depth - depth) * horizontal_gap,
+                30 + index * vertical_gap,
+            )
+
+    width = max(600, 40 + (max(layers, default=0) + 1) * horizontal_gap)
+    height = max(130, 60 + max((len(layer) for layer in layers.values()), default=1) * vertical_gap)
+    parts = [
+        f'<svg role="img" aria-label="Subproblem DAG for {esc(report.function_name)}" '
+        f'viewBox="0 0 {width} {height}" width="{width}" height="{height}" '
+        'xmlns="http://www.w3.org/2000/svg">',
+        "<defs><marker id=\"rl-arrow\" viewBox=\"0 0 10 10\" refX=\"8\" refY=\"5\" "
+        'markerWidth="6" markerHeight="6" orient="auto"><path d="M2 1L8 5L2 9" '
+        'fill="none" stroke="#888780" stroke-width="1.5"/></marker></defs>',
+    ]
+
+    for edge in report.dag_edges:
+        source, target = edge["source"], edge["target"]
+        if source not in known or target not in known:
+            continue
+        sx, sy = positions[source]
+        tx, ty = positions[target]
+        parts.append(
+            f'<path d="M{sx + box_width},{sy + box_height / 2} L{tx - 8},{ty + box_height / 2}" '
+            'fill="none" stroke="#888780" stroke-width="1" marker-end="url(#rl-arrow)"/>'
+        )
+
+    for node in nodes:
+        x, y = positions[node.identity]
+        if node.cached:
+            fill, stroke, text = "#e1f5ee", "#0f6e56", "#085041"
+        elif node.calls > 1:
+            fill, stroke, text = "#faece7", "#d85a30", "#993c1d"
+        else:
+            fill, stroke, text = "#e6f1fb", "#185fa5", "#042c53"
+        label = esc(short(node.signature, 29))
+        count = f"calls {node.calls} · executed {node.executed} · cached {node.cached}"
+        parts.extend(
+            [
+                f'<rect x="{x}" y="{y}" width="{box_width}" height="{box_height}" rx="8" '
+                f'fill="{fill}" stroke="{stroke}" stroke-width="1"/>',
+                f'<text x="{x + 10}" y="{y + 20}" font-family="monospace" font-size="11" fill="{text}">{label}</text>',
+                f'<text x="{x + 10}" y="{y + 39}" font-family="sans-serif" font-size="10" fill="{text}">{esc(count)}</text>',
+            ]
+        )
+    parts.append("</svg>")
+
+    notice = f'<p class="rl-note">Showing the first 40 subproblems; {omitted} omitted.</p>' if omitted else ""
+    return (
+        '<h3 class="rl-section">Subproblem DAG</h3>'
+        '<div class="rl-legend">Identical argument signatures are merged. Coral = repeated; green = contains cache hits.</div>'
+        f'<div class="rl-dag">{"".join(parts)}</div>{notice}'
+    )
+
+
+def render_report(report, mode: str = "tree") -> str:
+    views = {"tree": render_tree, "dag": render_dag, "expanded": render_expanded_tree}
+    if mode not in views:
+        raise ValueError("mode must be 'tree', 'dag', or 'expanded'")
+    body = views[mode](report)
+    return f'<style>{_CSS}</style><section class="rl-wrap">{report_header(report)}{body}</section>'
+
+
+def render_comparison(comparison) -> str:
+    left, right = comparison.left, comparison.right
+    left_metrics, right_metrics = left.metrics(), right.metrics()
+    rows = []
+    labels = {
+        "total_calls": "Observed calls",
+        "executed_calls": "Executed bodies",
+        "cached_calls": "Cache hits",
+        "unique_subproblems": "Unique subproblems",
+        "repeated_calls": "Repeated calls",
+        "max_depth": "Maximum depth",
+    }
+    for key, label in labels.items():
+        delta = right_metrics[key] - left_metrics[key]
+        delta_class = "rl-delta-down" if delta < 0 else "rl-delta-up" if delta > 0 else ""
+        delta_text = f"{delta:+d}"
+        rows.append(
+            f"<tr><td>{esc(label)}</td><td>{left_metrics[key]}</td>"
+            f"<td>{right_metrics[key]}</td><td class=\"{delta_class}\">{delta_text}</td></tr>"
+        )
+
+    same_result = "yes" if comparison.same_result else "no"
+    return (
+        f'<style>{_CSS}</style><section class="rl-wrap">'
+        '<h2 class="rl-title">RecursionLens · execution comparison</h2>'
+        f'<p class="rl-subtitle">{esc(comparison.labels[0])} vs {esc(comparison.labels[1])} · same returned value: {same_result}</p>'
+        '<table class="rl-table"><thead><tr><th>Metric</th>'
+        f'<th>{esc(comparison.labels[0])}</th><th>{esc(comparison.labels[1])}</th><th>Change</th>'
+        '</tr></thead><tbody>' + "".join(rows) + '</tbody></table>'
+        f'<div class="rl-compare-block"><h3 class="rl-section">{esc(comparison.labels[0])}</h3>'
+        + report_header(left)
+        + render_dag(left)
+        + '</div>'
+        f'<div class="rl-compare-block"><h3 class="rl-section">{esc(comparison.labels[1])}</h3>'
+        + report_header(right)
+        + render_dag(right)
+        + '</div></section>'
+    )
+
+
+def render_document(fragment: str) -> str:
+    return (
+        '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width,initial-scale=1">'
+        '<title>RecursionLens report</title></head><body style="margin:20px;background:#f6f5f1">'
+        + fragment
+        + "</body></html>"
+    )

recursionlens/_report.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from ._model import CallNode, DAGNode, build_dag
+
+
+@dataclass
+class TraceReport:
+    """A serializable record of one traced top-level invocation."""
+
+    function_name: str
+    value: Any
+    nodes: List[CallNode]
+    roots: List[CallNode]
+    total_calls: int
+    max_depth: int
+    memoize: bool = False
+    truncated: bool = False
+    warnings: List[str] = field(default_factory=list)
+    succeeded: bool = True
+
+    @property
+    def recorded_calls(self) -> int:
+        return len(self.nodes)
+
+    @property
+    def cached_calls(self) -> int:
+        return sum(node.cached for node in self.nodes)
+
+    @property
+    def executed_calls(self) -> int:
+        return self.recorded_calls - self.cached_calls
+
+    @property
+    def dag_nodes(self) -> List[DAGNode]:
+        return build_dag(self.roots)[0]
+
+    @property
+    def dag_edges(self) -> List[Dict[str, str]]:
+        return build_dag(self.roots)[1]
+
+    @property
+    def unique_subproblems(self) -> int:
+        return len(self.dag_nodes)
+
+    @property
+    def repeated_calls(self) -> int:
+        return self.recorded_calls - self.unique_subproblems
+
+    @property
+    def result(self) -> Optional[str]:
+        if self.roots:
+            return self.roots[0].result
+        return None
+
+    @property
+    def error(self) -> Optional[str]:
+        if self.roots:
+            return self.roots[0].error
+        return None
+
+    def metrics(self) -> Dict[str, Any]:
+        return {
+            "total_calls": self.total_calls,
+            "recorded_calls": self.recorded_calls,
+            "executed_calls": self.executed_calls,
+            "cached_calls": self.cached_calls,
+            "unique_subproblems": self.unique_subproblems,
+            "repeated_calls": self.repeated_calls,
+            "max_depth": self.max_depth,
+            "memoize": self.memoize,
+            "truncated": self.truncated,
+            "succeeded": self.succeeded,
+        }
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "schema_version": 1,
+            "function_name": self.function_name,
+            "result": self.result,
+            "error": self.error,
+            "metrics": self.metrics(),
+            "warnings": list(self.warnings),
+            "roots": [root.to_dict() for root in self.roots],
+            "dag": {
+                "nodes": [node.to_dict() for node in self.dag_nodes],
+                "edges": list(self.dag_edges),
+            },
+        }
+
+    def export_json(self, path: Union[str, Path]) -> Path:
+        destination = Path(path)
+        destination.write_text(
+            json.dumps(self.to_dict(), indent=2, ensure_ascii=False),
+            encoding="utf-8",
+        )
+        return destination
+
+    def to_html(self, mode: str = "tree") -> str:
+        from ._render import render_report
+
+        return render_report(self, mode=mode)
+
+    def export_html(self, path: Union[str, Path], mode: str = "tree") -> Path:
+        from ._render import render_document
+
+        destination = Path(path)
+        destination.write_text(render_document(self.to_html(mode=mode)), encoding="utf-8")
+        return destination
+
+    def _repr_html_(self) -> str:
+        return self.to_html()
+
+    def show(self, mode: str = "tree") -> Any:
+        html = self.to_html(mode=mode)
+        try:
+            from IPython.display import HTML, display
+        except ImportError:
+            return html
+        display(HTML(html))
+        return None
+
+    def compare(
+        self,
+        other: "TraceReport",
+        labels: Tuple[str, str] = ("naive", "memoized"),
+    ) -> "ComparisonReport":
+        return ComparisonReport(self, other, labels)
+
+
+@dataclass
+class ComparisonReport:
+    """Quantitative and visual comparison of two traced runs."""
+
+    left: TraceReport
+    right: TraceReport
+    labels: Tuple[str, str] = ("naive", "memoized")
+
+    @property
+    def same_result(self) -> bool:
+        if not self.left.succeeded or not self.right.succeeded:
+            return False
+        try:
+            return bool(self.left.value == self.right.value)
+        except Exception:
+            return False
+
+    def to_dict(self) -> Dict[str, Any]:
+        left_metrics = self.left.metrics()
+        right_metrics = self.right.metrics()
+        keys = (
+            "total_calls",
+            "executed_calls",
+            "cached_calls",
+            "unique_subproblems",
+            "repeated_calls",
+            "max_depth",
+        )
+        return {
+            "labels": list(self.labels),
+            "left": left_metrics,
+            "right": right_metrics,
+            "delta": {key: right_metrics[key] - left_metrics[key] for key in keys},
+            "same_result": self.same_result,
+        }
+
+    def to_html(self) -> str:
+        from ._render import render_comparison
+
+        return render_comparison(self)
+
+    def export_html(self, path: Union[str, Path]) -> Path:
+        from ._render import render_document
+
+        destination = Path(path)
+        destination.write_text(render_document(self.to_html()), encoding="utf-8")
+        return destination
+
+    def _repr_html_(self) -> str:
+        return self.to_html()
+
+    def show(self) -> Any:
+        html = self.to_html()
+        try:
+            from IPython.display import HTML, display
+        except ImportError:
+            return html
+        display(HTML(html))
+        return None

recursionlens/_trace.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+import itertools
+from collections import Counter
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from ._model import CallNode
+from ._report import TraceReport
+
+_ACTIVE: contextvars.ContextVar[Optional["TraceRecorder"]] = contextvars.ContextVar(
+    "recursionlens_active_recorder", default=None
+)
+_FUNCTION_IDS = itertools.count(1)
+_MAX_REPR = 160
+
+
+def full_repr(value: Any) -> str:
+    try:
+        return repr(value)
+    except Exception as error:
+        return f"<unrepresentable {type(value).__name__}: {type(error).__name__}>"
+
+
+def safe_repr(value: Any) -> str:
+    """Return a bounded representation suitable for display and JSON."""
+
+    text = full_repr(value)
+    if len(text) > _MAX_REPR:
+        return text[: _MAX_REPR - 3] + "..."
+    return text
+
+
+def safe_exception(error: BaseException) -> str:
+    try:
+        message = str(error)
+    except BaseException:
+        message = "<exception message unavailable>"
+    return f"{type(error).__name__}: {message}"
+
+
+def bind_arguments(func: Callable[..., Any], args: tuple, kwargs: dict) -> inspect.BoundArguments:
+    bound = inspect.signature(func).bind(*args, **kwargs)
+    bound.apply_defaults()
+    return bound
+
+
+def signature_for(func: Callable[..., Any], bound: inspect.BoundArguments) -> str:
+    arguments = ", ".join(
+        f"{name}={safe_repr(value)}" for name, value in bound.arguments.items()
+    )
+    return f"{func.__qualname__}({arguments})"
+
+
+def identity_for(
+    function_id: int, func: Callable[..., Any], bound: inspect.BoundArguments
+) -> str:
+    """Build an untruncated internal identity independent of display formatting."""
+
+    arguments = ", ".join(
+        f"{name}:{type(value).__module__}.{type(value).__qualname__}={full_repr(value)}"
+        for name, value in bound.arguments.items()
+    )
+    return f"{function_id}:{func.__module__}:{func.__qualname__}({arguments})"
+
+
+def cache_key_for(
+    func: Callable[..., Any], bound: inspect.BoundArguments
+) -> Optional[Tuple[Any, ...]]:
+    # Python considers 1, 1.0, and True equal with equal hashes. Types are part
+    # of this key so memoization cannot change a type-sensitive pure function.
+    key = (
+        func,
+        tuple((name, type(value), value) for name, value in bound.arguments.items()),
+    )
+    try:
+        hash(key)
+    except Exception:
+        return None
+    return key
+
+
+class TraceRecorder:
+    def __init__(self, memoize: bool, max_calls: int) -> None:
+        if max_calls < 1:
+            raise ValueError("max_calls must be at least 1")
+        self.memoize = memoize
+        self.max_calls = max_calls
+        self.nodes: List[CallNode] = []
+        self.roots: List[CallNode] = []
+        self.stack: List[Optional[CallNode]] = []
+        self.identities: Counter = Counter()
+        self.cache: Dict[Tuple[Any, ...], Any] = {}
+        self.total_calls = 0
+        self.depth = 0
+        self.max_depth = 0
+        self.truncated = False
+        self.warnings: List[str] = []
+
+    def add_node(self, identity: str, signature: str, status: str) -> Optional[CallNode]:
+        if len(self.nodes) >= self.max_calls:
+            self.truncated = True
+            return None
+
+        repeated = self.identities[identity] > 0
+        self.identities[identity] += 1
+        node = CallNode(
+            call_id=len(self.nodes),
+            identity=identity,
+            signature=signature,
+            depth=self.depth,
+            status=status,
+            repeated=repeated,
+        )
+        self.nodes.append(node)
+
+        if not self.stack:
+            self.roots.append(node)
+        elif self.stack[-1] is not None:
+            self.stack[-1].children.append(node)
+        return node
+
+    def warn_unhashable(self) -> None:
+        message = "Arguments are unhashable; this run was not memoized for those calls."
+        if message not in self.warnings:
+            self.warnings.append(message)
+
+
+def _invoke(
+    function_id: int,
+    func: Callable[..., Any],
+    args: tuple,
+    kwargs: dict,
+    recorder: TraceRecorder,
+) -> Any:
+    bound = bind_arguments(func, args, kwargs)
+    signature = signature_for(func, bound)
+    identity = identity_for(function_id, func, bound)
+    cache_key = cache_key_for(func, bound) if recorder.memoize else None
+
+    recorder.total_calls += 1
+    recorder.depth += 1
+    recorder.max_depth = max(recorder.max_depth, recorder.depth)
+
+    if recorder.memoize and cache_key is not None and cache_key in recorder.cache:
+        try:
+            value = recorder.cache[cache_key]
+            node = recorder.add_node(identity, signature, "cached")
+            if node is not None:
+                node.result = safe_repr(value)
+            return value
+        finally:
+            recorder.depth -= 1
+
+    node = recorder.add_node(identity, signature, "running")
+    recorder.stack.append(node)
+    try:
+        value = func(*args, **kwargs)
+        if node is not None:
+            node.status = "returned"
+            node.result = safe_repr(value)
+
+        if recorder.memoize:
+            if cache_key is None:
+                recorder.warn_unhashable()
+            else:
+                recorder.cache[cache_key] = value
+        return value
+    except BaseException as error:
+        if node is not None:
+            node.status = "error"
+            node.error = safe_exception(error)
+        raise
+    finally:
+        recorder.stack.pop()
+        recorder.depth -= 1
+
+
+class RunConfiguration:
+    def __init__(
+        self,
+        wrapper: Callable[..., Any],
+        func: Callable[..., Any],
+        function_id: int,
+        memoize: bool,
+        max_calls: int,
+    ) -> None:
+        self.wrapper = wrapper
+        self.func = func
+        self.function_id = function_id
+        self.memoize = memoize
+        self.max_calls = max_calls
+
+    def run(self, *args: Any, **kwargs: Any) -> TraceReport:
+        return _run(
+            self.wrapper,
+            self.func,
+            self.function_id,
+            args,
+            kwargs,
+            self.memoize,
+            self.max_calls,
+        )
+
+
+def _run(
+    wrapper: Callable[..., Any],
+    func: Callable[..., Any],
+    function_id: int,
+    args: tuple,
+    kwargs: dict,
+    memoize: bool,
+    max_calls: int,
+) -> TraceReport:
+    recorder = TraceRecorder(memoize=memoize, max_calls=max_calls)
+    token = _ACTIVE.set(recorder)
+    try:
+        value = _invoke(function_id, func, args, kwargs, recorder)
+    except BaseException:
+        wrapper.last_report = _make_report(func, recorder, None, succeeded=False)
+        raise
+    else:
+        report = _make_report(func, recorder, value, succeeded=True)
+        wrapper.last_report = report
+        return report
+    finally:
+        _ACTIVE.reset(token)
+
+
+def trace(func: Callable[..., Any]) -> Callable[..., Any]:
+    """Instrument a synchronous recursive function while preserving its call behavior."""
+
+    function_id = next(_FUNCTION_IDS)
+
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        active = _ACTIVE.get()
+        if active is not None:
+            return _invoke(function_id, func, args, kwargs, active)
+
+        recorder = TraceRecorder(memoize=False, max_calls=1000)
+        token = _ACTIVE.set(recorder)
+        try:
+            value = _invoke(function_id, func, args, kwargs, recorder)
+        except BaseException:
+            wrapper.last_report = _make_report(func, recorder, None, succeeded=False)
+            raise
+        else:
+            wrapper.last_report = _make_report(func, recorder, value, succeeded=True)
+            return value
+        finally:
+            _ACTIVE.reset(token)
+
+    def run(*args: Any, **kwargs: Any) -> TraceReport:
+        return RunConfiguration(wrapper, func, function_id, False, 1000).run(*args, **kwargs)
+
+    def with_options(*, memoize: bool = False, max_calls: int = 1000) -> RunConfiguration:
+        return RunConfiguration(wrapper, func, function_id, memoize, max_calls)
+
+    wrapper.run = run
+    wrapper.with_options = with_options
+    wrapper.last_report = None
+    wrapper.__recursionlens_original__ = func
+    return wrapper
+
+
+def _make_report(
+    func: Callable[..., Any], recorder: TraceRecorder, value: Any, succeeded: bool
+) -> TraceReport:
+    return TraceReport(
+        function_name=func.__qualname__,
+        value=value,
+        nodes=recorder.nodes,
+        roots=recorder.roots,
+        total_calls=recorder.total_calls,
+        max_depth=recorder.max_depth,
+        memoize=recorder.memoize,
+        truncated=recorder.truncated,
+        warnings=list(recorder.warnings),
+        succeeded=succeeded,
+    )

recursionlens-0.1.2.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: recursionlens
+Version: 0.1.2
+Summary: Interactive recursion tracing, subproblem DAGs, and memoization comparisons for JupyterLab.
+Author: Ziyu Jiang, Xinyue Cai, Kehan Cao, Ruoxi Lyu, Haobo Ma
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ZiyuJiang07/recursionlens
+Project-URL: Repository, https://github.com/ZiyuJiang07/recursionlens
+Project-URL: Documentation, https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/USER.md
+Project-URL: Tutorial, https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/RecursionLens_Tutorial.ipynb
+Project-URL: Changelog, https://github.com/ZiyuJiang07/recursionlens/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ZiyuJiang07/recursionlens/issues
+Keywords: recursion,jupyterlab,visualization,memoization,education
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: Jupyter
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: coverage>=7; extra == "dev"
+Dynamic: license-file
+
+# RecursionLens
+
+**See not just what recursion returns, but where the repeated work happens.**
+
+RecursionLens is a zero-runtime-dependency Python package for exploring recursive execution in JupyterLab. It turns a traced run into an expandable call tree, a compressed subproblem DAG, and a quantitative naive-versus-memoized comparison.
+
+> **JupyterLab tutorial, already executed:** [Open RecursionLens_Tutorial.ipynb](https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/RecursionLens_Tutorial.ipynb). All eight code cells have saved output. If Jupyter hides HTML/SVG from a downloaded notebook, use its **Trust** action or click **Run All Cells** once. For a zero-setup preview, download and open the [static HTML companion](https://github.com/ZiyuJiang07/recursionlens/raw/main/docs/RecursionLens_Tutorial.html).
+
+## Project team
+
+CS1302A Group 50:
+
+- Ziyu Jiang
+- Xinyue CAI
+- Kehan CAO
+- Ruoxi LYU
+- Haobo MA
+
+## Why RecursionLens?
+
+A recursive function normally exposes only its final return value or traceback. Students still have to reconstruct the execution in their heads. RecursionLens answers three different questions:
+
+1. **Call tree:** what actually happened, invocation by invocation?
+2. **Subproblem DAG:** how many distinct problems and dependencies exist after identical arguments are merged?
+3. **Execution comparison:** what changes when memoization is enabled?
+
+For `fib(5)`, that story is **15 observed calls → 6 unique subproblems → 6 executed bodies with memoization**.
+
+## Innovation beyond a call graph
+
+The existing `rcviz` package documents decorator-based recursion trees with arguments, return values, and Jupyter rendering. RecursionLens deliberately focuses on a different workflow:
+
+- transform one trace between an invocation tree and a compressed subproblem DAG;
+- show the complete call tree at once in an SVG view or keep a collapsible tree for larger runs;
+- quantify repeated calls, executed bodies, cache hits, and maximum depth;
+- compare naive and memoized runs in one report with side-by-side DAGs;
+- render self-contained HTML/SVG in JupyterLab without Graphviz, native libraries, external JavaScript, or a CDN;
+- export versioned JSON for reproducible analysis and testing.
+
+## Installation
+
+RecursionLens requires Python 3.9 or later.
+
+Install from PyPI:
+
+```bash
+python -m pip install recursionlens
+```
+
+For local development:
+
+```bash
+git clone https://github.com/ZiyuJiang07/recursionlens.git
+cd recursionlens
+python -m pip install -e ".[dev]"
+```
+
+The package has no runtime dependencies.
+
+## Quickstart in JupyterLab
+
+```python
+from recursionlens import trace
+
+@trace
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+
+naive = fib.run(5)
+naive  # expandable call tree in the notebook output area
+```
+
+Switch the same trace to the compressed subproblem DAG:
+
+```python
+naive.show(mode="dag")
+```
+
+Or show every call at once as one compact SVG tree, with no nodes collapsed:
+
+```python
+naive.show(mode="expanded")
+```
+
+Run the function again with memoization and compare the evidence:
+
+```python
+memoized = fib.with_options(memoize=True).run(5)
+comparison = naive.compare(memoized)
+comparison
+```
+
+The comparison confirms the returned values match and reports the measured changes, including **15 → 6 executed function bodies**.
+
+Normal function behavior is preserved:
+
+```python
+assert fib(5) == 5
+assert fib.last_report.total_calls == 15
+```
+
+## Export a report
+
+```python
+naive.export_html("fib-tree.html")
+naive.export_html("fib-dag.html", mode="dag")
+naive.export_json("fib-trace.json")
+comparison.export_html("fib-comparison.html")
+```
+
+HTML reports are standalone files that can be opened without a notebook server. JSON contains the tree, DAG nodes and edges, metrics, warnings, and schema version.
+
+## Supported scope
+
+Version 0.1 targets synchronous, deterministic teaching examples such as factorial, Fibonacci, and pure mathematical recursion.
+
+- Memoization requires hashable bound arguments; unhashable arguments produce a warning instead of a crash.
+- Identical arguments do not necessarily imply redundant work for functions with side effects or external state.
+- `max_calls` bounds the stored tree without changing the function's result. A truncated report explicitly marks partial tree/DAG metrics.
+- RecursionLens executes your function; it is **not a sandbox for untrusted code**.
+- Async functions, generators, automatic Big-O inference, and automatic code rewriting are non-goals for 0.1.
+
+## Documentation and demo
+
+- [Executed JupyterLab tutorial](https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/RecursionLens_Tutorial.ipynb) - setup, three views, comparison, export, troubleshooting, and a one-minute demo recipe
+- [Static HTML tutorial preview](https://github.com/ZiyuJiang07/recursionlens/raw/main/docs/RecursionLens_Tutorial.html) - the same tutorial with all visual reports rendered, no Jupyter required
+- [Runnable example notebook](https://github.com/ZiyuJiang07/recursionlens/blob/main/examples/demo.ipynb)
+- [User guide](https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/USER.md)
+- [Developer guide](https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/DEVELOPER.md)
+- [Changelog](https://github.com/ZiyuJiang07/recursionlens/blob/main/CHANGELOG.md)
+
+## Development and testing
+
+```bash
+python -m pytest tests -v
+python -m build
+python -m twine check dist/*
+```
+
+The test suite covers trace invariants, cache behavior, signatures, exceptions, truncation, JSON, HTML escaping, DAG rendering, and comparison reports. Contributions should keep the public API, tests, and user documentation synchronized.
+
+## License
+
+MIT © 2026 Ziyu Jiang, Xinyue Cai, Kehan Cao, Ruoxi Lyu, Haobo Ma.

recursionlens-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+recursionlens/__init__.py,sha256=biRR53VjQR9K6sXWQL_rzOOHDJsj4tGNzDZBEmNdBU8,326
+recursionlens/_model.py,sha256=hZTcXRQF-YO0OBkHgQU-_V-52XrhdaZ3_50EU7ev8J4,2750
+recursionlens/_render.py,sha256=a32QpaZhh6Kk_Ikc2GufBJ-iAJ_h0yLnIa3OP55jSbo,16368
+recursionlens/_report.py,sha256=6KgAr2YjPH6s0vADGv5jfLFGczl9gt9tsTq01M78gQQ,5530
+recursionlens/_trace.py,sha256=yyJ7E9mJdS5ZszQkjQbEMeVSyZccH5v2zoalWkfSV2g,8687
+recursionlens-0.1.2.dist-info/licenses/LICENSE,sha256=M86k0jXdg-CXEEced2z6uD5VXMRJbQK1GiOuQwIOWD4,1084
+recursionlens-0.1.2.dist-info/METADATA,sha256=pM-Au-a9BKRGbO0ybGfelevJn7vXFp9fGa-NmlDqt90,6994
+recursionlens-0.1.2.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+recursionlens-0.1.2.dist-info/top_level.txt,sha256=JLn475SilL45f2yU_BozOrvo2pH4gdNox8fnnG8BOtk,14
+recursionlens-0.1.2.dist-info/RECORD,,

recursionlens-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

recursionlens-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ziyu Jiang and contributors
+
+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.

recursionlens-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+recursionlens