recursionlens 0.1.2__tar.gz

recursionlens-0.1.2/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,146 @@
+# 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/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "recursionlens"
+version = "0.1.2"
+description = "Interactive recursion tracing, subproblem DAGs, and memoization comparisons for JupyterLab."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Ziyu Jiang" },
+  { name = "Xinyue Cai" },
+  { name = "Kehan Cao" },
+  { name = "Ruoxi Lyu" },
+  { name = "Haobo Ma" },
+]
+keywords = ["recursion", "jupyterlab", "visualization", "memoization", "education"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Framework :: Jupyter",
+]
+
+[project.urls]
+Homepage = "https://github.com/ZiyuJiang07/recursionlens"
+Repository = "https://github.com/ZiyuJiang07/recursionlens"
+Documentation = "https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/USER.md"
+Tutorial = "https://github.com/ZiyuJiang07/recursionlens/blob/main/docs/RecursionLens_Tutorial.ipynb"
+Changelog = "https://github.com/ZiyuJiang07/recursionlens/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ZiyuJiang07/recursionlens/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "coverage>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

recursionlens-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

recursionlens-0.1.2/src/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-0.1.2/src/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