refactor: harden package structure and add tensor inspector

Author: DOKOS-TAYOS

.github/workflows/ci.yml

@@ -34,7 +34,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest]
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
 
     runs-on: ${{ matrix.os }}
 
@@ -50,12 +50,15 @@ jobs:
       - name: Install build tool
         run: python -m pip install build==1.4.2
 
-      - name: Build wheel
-        run: python scripts/verify.py wheel
+      - name: Build package artifacts
+        run: python scripts/verify.py package
 
       - name: Create wheel test venv
         run: python -m venv .wheel-venv
 
+      - name: Create sdist test venv
+        run: python -m venv .sdist-venv
+
       - name: Install wheel (Linux)
         if: runner.os != 'Windows'
         run: .wheel-venv/bin/python -m pip install dist/*.whl
@@ -73,6 +76,23 @@ jobs:
         if: runner.os == 'Windows'
         run: .wheel-venv\Scripts\python -c "import matplotlib; matplotlib.use('Agg'); import tensor_network_viz; from tensor_network_viz import PlotConfig, pair_tensor, show_tensor_network; trace=[pair_tensor('A', 'x', 'r0', 'ab,b->a')]; fig, _ = show_tensor_network(trace, engine='einsum', view='2d', config=PlotConfig(tensor_label_refinement='never'), show=False); assert fig is not None"
 
+      - name: Install sdist (Linux)
+        if: runner.os != 'Windows'
+        run: .sdist-venv/bin/python -m pip install dist/*.tar.gz
+
+      - name: Install sdist (Windows)
+        if: runner.os == 'Windows'
+        run: .sdist-venv\Scripts\python -m pip install (Get-ChildItem dist\*.tar.gz | Select-Object -First 1).FullName
+
+      - name: Smoke sdist import and render (Linux)
+        if: runner.os != 'Windows'
+        run: |
+          .sdist-venv/bin/python -c "import matplotlib; matplotlib.use('Agg'); import tensor_network_viz; from tensor_network_viz import PlotConfig, pair_tensor, show_tensor_network; trace=[pair_tensor('A', 'x', 'r0', 'ab,b->a')]; fig, _ = show_tensor_network(trace, engine='einsum', view='2d', config=PlotConfig(tensor_label_refinement='never'), show=False); assert fig is not None"
+
+      - name: Smoke sdist import and render (Windows)
+        if: runner.os == 'Windows'
+        run: .sdist-venv\Scripts\python -c "import matplotlib; matplotlib.use('Agg'); import tensor_network_viz; from tensor_network_viz import PlotConfig, pair_tensor, show_tensor_network; trace=[pair_tensor('A', 'x', 'r0', 'ab,b->a')]; fig, _ = show_tensor_network(trace, engine='einsum', view='2d', config=PlotConfig(tensor_label_refinement='never'), show=False); assert fig is not None"
+
   lint-and-test:
     strategy:
       fail-fast: false

CONTRIBUTING.md

@@ -49,6 +49,26 @@ With the project venv (Windows):
 
 Add tests for new features or bug fixes. All tests must pass before opening a PR.
 
+### Optional: focused smoke and performance runs
+
+Pytest markers are available for the render-specific regression checks:
+
+```bash
+pytest -m smoke
+pytest -m perf
+```
+
+Use `smoke` for lightweight draw sanity checks and `perf` for runtime-sensitive guards.
+For larger local comparisons outside CI, run:
+
+```bash
+python scripts/bench_render_workflows.py
+```
+
+That benchmark compares first render vs repeated render, network object vs list input,
+and static render vs interactive controls through the public `show_tensor_network(...)`
+entry point.
+
 ### Optional: manual example smoke checks
 
 Automated tests do not open interactive Matplotlib windows. After **`pytest`** passes, sanity-check **layout and drawing** by running the examples below from the **repository root** (with **`pip install -r requirements.dev.txt`** or the matching optional extras). Run **one command at a time** (each line is a separate invocation).
@@ -163,7 +183,10 @@ Adding a new engine (e.g. a new tensor-network library) requires:
   - `graph.py` — convert backend-native objects to `_GraphData` (see `_core/graph.py`)
   - `renderer.py` — implement `plot_<engine>_network_2d` and `plot_<engine>_network_3d` using the shared `_core` drawing layer
   - `__init__.py` — export the two plot functions
-2. **Registration** in `config.py` (add to `EngineName`) and `_registry.py` (add to `_ENGINE_CONFIG`).
+2. **Registration** in `config.py` / `_engine_specs.py`:
+  - add the new literal to `EngineName`
+  - add the module/function triple to `ENGINE_MODULE_MAP` in `src/tensor_network_viz/_engine_specs.py`
+  - `_registry.py` reads that map to resolve the public plotters
 3. **Optional dependency** in `pyproject.toml` under `[project.optional-dependencies]`.
 4. **Tests** in `tests/test_integration_<engine>.py` and optional `tests/test_<engine>_backend.py`.
 5. **Example script** in `examples/<engine>_demo.py` and an entry in `examples/README.md`.

examples/README.md

@@ -80,9 +80,14 @@ When `--no-show` or `--save` is used, the launcher calls
 ```bash
 python examples/run_demo.py einsum ellipsis --view 2d --scheme
 python examples/run_demo.py einsum mps --view 2d --scheme --playback
+python examples/run_demo.py einsum mps --view 2d --tensor-inspector
 python examples/run_demo.py tenpy chain --view 2d --scheme
 ```
 
+For the linked tensor inspector, use an auto-traced `EinsumTrace` example such as `mps`, `mpo`,
+`peps`, `ellipsis`, or `nway`. Manual `--from-scratch` / `--from-list` variants do not carry the
+live tensor values needed by the inspector.
+
 ## Useful Options
 
 | Option | Meaning |
@@ -95,6 +100,7 @@ python examples/run_demo.py tenpy chain --view 2d --scheme
 | `--scheme` | Draw contraction-scheme overlays when available. |
 | `--playback` | Start with contraction playback enabled. |
 | `--hover-cost` | Show contraction-cost details in the playback panel. |
+| `--tensor-inspector` | Open the linked tensor inspector for `EinsumTrace` playback. |
 | `--from-scratch` | Use the manual builder when that example supports it. |
 | `--from-list` | Pass list/iterable input when supported. |
 | `--save [PATH]` | Save the figure. If omitted, use the auto-generated path. |

examples/demo_cli.py

@@ -32,6 +32,7 @@ class ExampleCliArgs:
     scheme: bool
     playback: bool
     hover_cost: bool
+    tensor_inspector: bool
     from_scratch: bool
     from_list: bool
     save: Path | None
@@ -168,6 +169,12 @@ def build_run_demo_parser() -> argparse.ArgumentParser:
         default=False,
         help_text="Show contraction-cost details during playback; also enables scheme rendering.",
     )
+    add_bool_flag(
+        parser,
+        name="tensor-inspector",
+        default=False,
+        help_text="Open the linked tensor inspector for EinsumTrace playback examples.",
+    )
     add_bool_flag(
         parser,
         name="from-scratch",
@@ -235,6 +242,7 @@ def namespace_to_cli_args(namespace: argparse.Namespace) -> ExampleCliArgs:
         scheme=bool(namespace.scheme),
         playback=bool(namespace.playback),
         hover_cost=bool(namespace.hover_cost),
+        tensor_inspector=bool(namespace.tensor_inspector),
         from_scratch=bool(namespace.from_scratch),
         from_list=bool(namespace.from_list),
         save=namespace.save,
@@ -309,6 +317,7 @@ def finalize_demo_plot_config(
         getattr(args, "scheme", False)
         or getattr(args, "playback", False)
         or getattr(args, "hover_cost", False)
+        or getattr(args, "tensor_inspector", False)
     )
     return PlotConfig(
         show_tensor_labels=labels_nodes,
@@ -318,6 +327,7 @@ def finalize_demo_plot_config(
         contraction_scheme_by_name=scheme_tensor_names if scheme_enabled else None,
         contraction_playback=bool(getattr(args, "playback", False)),
         contraction_scheme_cost_hover=bool(getattr(args, "hover_cost", False)),
+        contraction_tensor_inspector=bool(getattr(args, "tensor_inspector", False)),
     )