Merge branch 'codex/professional-hardening'

Author: DOKOS-TAYOS

.gitignore

@@ -1,4 +1,6 @@
 .venv/
+.wheel-venv/
+.sdist-venv/
 .worktrees/
 .tmp/
 .tmp_venv_*/

CHANGELOG.md

@@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **Hide nodes in the viewer:** Option to exclude selected nodes from the interactive visualization so dense or branching tensor networks stay readable without changing the underlying graph data.
+- **Public diagnostics contract:** Added package-specific exceptions (`TensorNetworkVizError`, `VisualizationInputError`, `AxisConfigurationError`, `UnsupportedEngineError`, `TensorDataError`, `MissingOptionalDependencyError`) and a documented `tensor_network_viz` logger with a default `NullHandler`.
+
+### Changed
+
+- **Typing and controller structure:** Fixed the interactive tensor-inspector typing issue reported by `pyright`, extracted the linked tensor-inspector controller, and split tensor-element rendering/color-scaling helpers into a dedicated module to keep responsibilities narrower.
+- **Verification workflow docs:** README, guide, and contribution docs now document the `.venv`-first verification flow (`quality`, `tests`, `smoke`, `package`) used before release and CI troubleshooting.
 
 ## [1.5.2] — 2026-04-05
 

CONTRIBUTING.md

@@ -49,6 +49,24 @@ With the project venv (Windows):
 
 Add tests for new features or bug fixes. All tests must pass before opening a PR.
 
+Preferred full verification flow from the project `.venv`:
+
+```powershell
+.\.venv\Scripts\python scripts\verify.py quality
+.\.venv\Scripts\python scripts\verify.py tests
+.\.venv\Scripts\python scripts\verify.py smoke
+.\.venv\Scripts\python scripts\verify.py package
+```
+
+On Linux/macOS with the venv activated:
+
+```bash
+python scripts/verify.py quality
+python scripts/verify.py tests
+python scripts/verify.py smoke
+python scripts/verify.py package
+```
+
 ### Optional: focused smoke and performance runs
 
 Pytest markers are available for the render-specific regression checks:
@@ -149,9 +167,18 @@ python scripts/verify.py
 - **Target:** Python 3.11+
 - **Ruff rules:** E, F, I, B, UP, C4, SIM
 - **Typing:** Use type hints on public functions and modules; the codebase is `py.typed`
+- **Exceptions:** prefer `tensor_network_viz.exceptions` classes at public boundaries instead of raw `ValueError` / `ImportError` when you are surfacing user-facing library errors
+- **Logging:** use the `tensor_network_viz` logger; never call `logging.basicConfig()` from library code
 
 Run `python scripts/verify.py` before committing. If you prefer, you can still run `ruff`, `pyright`, and `pytest` individually.
 
+When you finish a Python task locally, run:
+
+```powershell
+.\.venv\Scripts\python -m ruff check . --fix
+.\.venv\Scripts\python -m ruff format .
+```
+
 ## Opening Useful Issues
 
 Use the [issue tracker](https://github.com/DOKOS-TAYOS/Tensor-Network-Visualization/issues).
@@ -210,6 +237,8 @@ Before opening a pull request, confirm:
 - `ruff check .` and `ruff format .` pass
 - `pyright` passes
 - `pytest` passes
+- `scripts/verify.py smoke` passes
+- `scripts/verify.py package` passes
 - New code has type hints and tests where appropriate
 - Documentation and examples are updated if behavior changed
 - PR description explains the change and links related issues

README.md

@@ -45,6 +45,29 @@ python -m pip install tensor-network-visualization
 
 Base dependencies are only `numpy`, `matplotlib`, and `networkx`.
 
+## Errors and Logging
+
+Public entry points now raise package-specific exceptions while remaining compatible with the
+built-in exception families they refine:
+
+- `VisualizationInputError`: unsupported or ambiguous network input.
+- `AxisConfigurationError`: incompatible `ax` / `view` combinations.
+- `UnsupportedEngineError`: unknown engine or backend name.
+- `TensorDataError`: unsupported or missing tensor data for `show_tensor_elements(...)`.
+- `MissingOptionalDependencyError`: missing optional backend dependency.
+
+All of them inherit from `TensorNetworkVizError`.
+
+The package logger name is `tensor_network_viz`. It installs a `logging.NullHandler()` by default,
+so importing the library does not change your application's logging configuration.
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("tensor_network_viz").setLevel(logging.DEBUG)
+```
+
 ### Optional extras
 
 | Need | Install |
@@ -393,6 +416,7 @@ python examples/tensor_elements_demo.py
 | Hover tooltips do nothing | Use an interactive Matplotlib backend; hover is not useful for PNG-only runs. |
 | Big graphs are slow | Set `tensor_label_refinement="never"`, reduce `layout_iterations`, or pass `positions`. |
 | `Unsupported tensor network engine` | Install the matching extra or pass the correct backend object. |
+| `AxisConfigurationError` when passing `ax` | Use a 2D axis for `view="2d"`, a 3D axis for `view="3d"`, and only pass `ax` to `show_tensor_elements(...)` for a single tensor. |
 | `show_tensor_elements(...)` fails on TensorKrowch nodes | Materialize the node tensors first; shape-only nodes do not expose element values. |
 | `show_tensor_elements(...)` fails on manual `pair_tensor(...)` lists | Use an `EinsumTrace` with live tensors instead; manual trace steps only describe contractions. |
 | Blank / duplicate Jupyter figure | Assign `fig, ax = show_tensor_network(...)` instead of leaving the tuple as the last line. |
@@ -421,3 +445,12 @@ Run the project checks:
 ```powershell
 .\.venv\Scripts\python scripts\verify.py
 ```
+
+Useful slices:
+
+```powershell
+.\.venv\Scripts\python scripts\verify.py quality
+.\.venv\Scripts\python scripts\verify.py tests
+.\.venv\Scripts\python scripts\verify.py smoke
+.\.venv\Scripts\python scripts\verify.py package
+```

docs/guide.md

@@ -66,6 +66,33 @@ show_tensor_elements(
 | `show_controls` | If `True`, add compact `group + mode` controls and, when several tensors are present, a tensor slider. |
 | `show` | If `True`, display the figure immediately. If `False`, just return `(fig, ax)`. |
 
+## Errors and Diagnostics
+
+The public API raises package-specific exceptions so callers can distinguish user-input problems
+from unrelated runtime failures without parsing error strings:
+
+- `TensorNetworkVizError`: root class for package-specific failures.
+- `VisualizationInputError`: unsupported or ambiguous network input.
+- `AxisConfigurationError`: incompatible `ax`, `view`, or figure-control setup.
+- `UnsupportedEngineError`: unknown backend name.
+- `TensorDataError`: unsupported tensor values or collections for `show_tensor_elements(...)`.
+- `MissingOptionalDependencyError`: backend requested but its dependency is not installed.
+
+These classes deliberately preserve compatibility with the built-in families they refine
+(`ValueError` or `ImportError`), so existing downstream handlers keep working.
+
+For diagnostics, enable the package logger:
+
+```python
+import logging
+
+logging.basicConfig(level=logging.DEBUG)
+logging.getLogger("tensor_network_viz").setLevel(logging.DEBUG)
+```
+
+The logger name is `tensor_network_viz`, and the library installs a `NullHandler`, so imports stay
+quiet unless your application opts in.
+
 ## `PlotConfig` in Practice
 
 `PlotConfig` is where visual behavior lives.
@@ -318,6 +345,15 @@ enough.
 Manual trace steps describe contractions, not tensor values. Use `EinsumTrace` and keep the traced
 tensors alive until you render them.
 
+### `AxisConfigurationError` appears immediately
+
+This means the plotting surface and the requested behavior disagree. Typical cases:
+
+- `show_tensor_network(..., view="3d", ax=<2D axis>)`
+- `show_tensor_network(..., view="2d", ax=<3D axis>)`
+- `show_tensor_elements(..., ax=...)` with more than one tensor selected
+- `show_tensor_elements(..., show_controls=True, ax=...)` on a figure that already has extra axes
+
 ### Jupyter shows duplicate output
 
 Prefer:

scripts/verify.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import logging
 import subprocess
 import sys
 from dataclasses import dataclass
@@ -15,6 +16,7 @@ class VerificationStep:
 
 
 VerificationGroup: TypeAlias = tuple[VerificationStep, ...]
+LOGGER = logging.getLogger("tensor_network_viz.verify")
 
 
 def _repo_root() -> Path:
@@ -65,6 +67,7 @@ def _format_command(command: tuple[str, ...]) -> str:
 
 
 def _run_step(step: VerificationStep, repo_root: Path) -> None:
+    LOGGER.debug("Running verification step '%s' in %s.", step.label, repo_root)
     print(f"[verify] {step.label}")
     print(f"[verify] $ {_format_command(step.command)}")
     subprocess.run(step.command, cwd=repo_root, check=True)
@@ -88,6 +91,7 @@ def main(argv: list[str] | None = None) -> int:
     parser = _build_parser()
     args = parser.parse_args(argv)
     repo_root = _repo_root()
+    LOGGER.debug("Starting verification mode='%s' in repo_root=%s.", args.mode, repo_root)
 
     try:
         for step in _ordered_steps(args.mode):

src/tensor_network_viz/__init__.py

@@ -5,8 +5,19 @@
 from matplotlib.figure import Figure
 from mpl_toolkits.mplot3d.axes3d import Axes3D
 
+from . import _logging as _package_logging
 from ._core.graph_cache import clear_tensor_network_graph_cache
 from .config import EngineName, PlotConfig, ViewName
+from .exceptions import (
+    AxisConfigurationError,
+    MissingOptionalDependencyError,
+    TensorDataError,
+    TensorDataTypeError,
+    TensorNetworkVizError,
+    UnsupportedEngineError,
+    VisualizationInputError,
+    VisualizationTypeError,
+)
 
 if TYPE_CHECKING:
     from .contraction_viewer import ContractionViewer2D, ContractionViewer3D
@@ -87,14 +98,22 @@ def __dir__() -> list[str]:
 
 
 __all__ = [
+    "AxisConfigurationError",
     "ContractionViewer2D",
     "ContractionViewer3D",
     "EngineName",
     "EinsumTrace",
+    "MissingOptionalDependencyError",
     "PlotConfig",
+    "TensorDataError",
+    "TensorDataTypeError",
     "TensorElementsConfig",
+    "TensorNetworkVizError",
     "TenPyTensorNetwork",
+    "UnsupportedEngineError",
     "ViewName",
+    "VisualizationInputError",
+    "VisualizationTypeError",
     "clear_tensor_network_graph_cache",
     "einsum",
     "einsum_trace_step",
@@ -103,3 +122,5 @@ def __dir__() -> list[str]:
     "show_tensor_elements",
     "show_tensor_network",
 ]
+
+_ = _package_logging

src/tensor_network_viz/_core/graph_cache.py

@@ -10,6 +10,7 @@
 from collections.abc import Callable
 from typing import Any
 
+from .._logging import package_logger
 from .graph import _GraphData
 
 _graph_weak_cache: weakref.WeakKeyDictionary[Any, dict[int, _GraphData]] = (
@@ -77,20 +78,27 @@ def _get_or_build_graph(
         if bucket is not None:
             hit = bucket.get(b_id)
             if hit is not None:
+                package_logger.debug("Graph cache hit via weak cache for builder_id=%s.", b_id)
                 return hit
     except TypeError:
         pass
 
     builtin_hit = _builtin_container_cache_get(network, builder_id=b_id)
     if builtin_hit is not None:
+        package_logger.debug("Graph cache hit via builtin container cache for builder_id=%s.", b_id)
         return builtin_hit
 
     attr_bucket = getattr(network, _CACHE_ATTR, None)
     if isinstance(attr_bucket, dict):
         hit = attr_bucket.get(b_id)
         if isinstance(hit, _GraphData):
+            package_logger.debug(
+                "Graph cache hit via object attribute cache for builder_id=%s.",
+                b_id,
+            )
             return hit
 
+    package_logger.debug("Graph cache miss for builder_id=%s; rebuilding graph.", b_id)
     graph = builder(network)
 
     try:
@@ -101,6 +109,7 @@ def _get_or_build_graph(
         bucket[b_id] = graph
     except TypeError:
         if _builtin_container_cache_put(network, builder_id=b_id, graph=graph):
+            package_logger.debug("Stored graph in builtin container cache for builder_id=%s.", b_id)
             return graph
         try:
             if not isinstance(attr_bucket, dict):
@@ -123,6 +132,7 @@ def clear_tensor_network_graph_cache(
     Call this after in-place edits to a tensor network so the next draw re-extracts the structure.
     """
     b_id = id(builder) if builder is not None else None
+    package_logger.debug("Clearing tensor network graph cache for builder_id=%s.", b_id)
     try:
         bucket = _graph_weak_cache.get(network)
         if bucket is not None:

src/tensor_network_viz/_core/renderer.py

@@ -14,6 +14,7 @@
 from matplotlib.figure import Figure
 from mpl_toolkits.mplot3d.axes3d import Axes3D
 
+from .._logging import package_logger
 from .._matplotlib_state import get_reserved_bottom
 from .._typing import PositionMapping, root_figure
 from ..config import PlotConfig
@@ -240,6 +241,9 @@ def _resolve_draw_scale(graph: _GraphData, positions: NodePositions) -> float:
     d_min = _min_contraction_edge_length(graph, positions)
     if d_min is not None:
         return _geometric_draw_scale(d_min)
+    package_logger.debug(
+        "Falling back to heuristic draw scale because no valid contraction-edge length was found."
+    )
     return _heuristic_draw_scale(graph, positions)
 
 
@@ -268,6 +272,10 @@ def _resolve_draw_scale_and_bond_curve_pad(
         if d_min is not None
         else _heuristic_draw_scale(graph, positions)
     )
+    if d_min is None:
+        package_logger.debug(
+            "Falling back to heuristic draw scale and curve padding for renderer graph."
+        )
 
     best_curve = 0.0
     for record in records: