tgraphx 0.2.2__tar.gz → 0.2.7__tar.gz

{tgraphx-0.2.2 → tgraphx-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 0.2.2
+Version: 0.2.7
 Summary: Tensor-aware graph neural networks preserving spatial node feature layouts
 Author-email: Arash Sajjadi <arash.sajjadi@usask.ca>
 Maintainer-email: Arash Sajjadi <arash.sajjadi@usask.ca>
@@ -41,6 +41,8 @@ Requires-Dist: psutil>=5.9; extra == "monitoring"
 Requires-Dist: pynvml>=11.0; extra == "monitoring"
 Provides-Extra: tracking
 Requires-Dist: tensorboard>=2.11; extra == "tracking"
+Provides-Extra: mlflow
+Requires-Dist: mlflow>=2.0; extra == "mlflow"
 Dynamic: license-file
 
 <p align="center">
@@ -119,28 +121,46 @@ drop-in clones of PyTorch Geometric's vector-feature implementations.
 | Dataset & loader | `GraphDataset`, `GraphDataLoader` | — | Wraps `torch.utils.data` |
 | Utilities | `load_config`, `get_device` | — | YAML/JSON config; CUDA→MPS→CPU |
 
-## What is NOT yet implemented
-
-- **Graph Transformers** (global attention with positional encodings).
-- **Per-channel and per-pixel attention** for `TensorGATLayer`. Currently only scalar attention per `(edge, head)` is supported (the default safer choice).
-- **Spatial edge features in `TensorGATLayer`** are accepted as `[E, edge_dim, H, W]` and **mean-pooled** to a vector before the per-`(edge, head)` attention bias projection. This keeps GAT in the scalar-attention regime (no per-pixel attention). `TensorGraphSAGELayer` and `TensorGINLayer` use the full spatial tensor directly (selected via `edge_features_kind="spatial"`).
-- **Per-voxel and per-pixel attention.** `TensorGATLayer` keeps scalar attention per `(edge, head)` even in 3-D mode. Volumetric edge tensors `[E, C_e, D, H, W]` are mean-pooled over `(D, H, W)` before the bias projection — there is no per-voxel attention.
-- **Arbitrary-rank tensor support.** TGraphX supports vector `[N, D]`, 2-D spatial `[N, C, H, W]`, and 3-D volumetric `[N, C, D, H, W]` node features for the listed layers. It does not claim arbitrary-rank tensor support.
-- **Heterogeneous and temporal graphs.**
-- **MLflowLogger.** Not implemented.  Use the `mlflow` client directly.
-  `pip install mlflow`.
-- **GAT / SAGE / GIN chunked forward.** Deferred (GAT's destination-wise
-  softmax requires all edge scores; SAGE/GIN chunking deferred for scope).
-  `ConvMessagePassing` supports `chunk_size` for `sum` / `mean` aggregation.
-- **Hardware-monitoring extras.** CPU/RAM/GPU metrics in the dashboard
-  require optional packages: `pip install tgraphx[monitoring]`.
-- **torch.compile / AMP.** `torch.compile` is available in PyTorch ≥ 2.0
-  and may improve throughput for large graphs; compile overhead dominates
-  for small ones.  Some GNN ops (e.g. `index_add_` in GAT) require matching
-  dtypes and do not work transparently under float16 autocast; bfloat16 or
-  full-precision inference is recommended.
-- **Profiling / logging.** No profiling, hardware polling, or file writes
-  are enabled by default.  All are opt-in.
+## Current scope and boundaries
+
+TGraphX is a focused library for tensor-aware patch-graph GNNs.  Here is
+what is stable, what is experimental, and what is intentionally out of scope.
+Full details are in [docs/limitations.md](docs/limitations.md) and
+[docs/roadmap.md](docs/roadmap.md).
+
+### Optional and experimental features (v0.2.4)
+
+| Feature | Status | Install / usage |
+|---------|:------:|---------|
+| `TensorGATLayer(attention_mode="channel")` | 🧪 Experimental | Constructor argument |
+| `TensorGATLayer(chunk_size=K)` forward | ✅ Stable | `forward(chunk_size=K)` |
+| `GraphTransformerLayer` (vector features only) | 🧪 Experimental | `from tgraphx.layers.graph_transformer import GraphTransformerLayer` |
+| `HeteroGraph` container | 🧪 Experimental | `from tgraphx.core.hetero_graph import HeteroGraph` |
+| `TemporalGraphSequence` container | 🧪 Experimental | `from tgraphx.core.temporal import TemporalGraphSequence` |
+| `MLflowLogger` | ✅ Opt-in | `pip install mlflow` or `pip install "tgraphx[mlflow]"` |
+| PyG / DGL converters | ✅ Opt-in | `from tgraphx.interop import to_pyg_data, to_dgl_graph, …` |
+| Learned graph helpers | ✅ Stable | `from tgraphx.learned_graph import soft_adjacency_from_embeddings, EdgeScorer, …` |
+| Patch helper `padding="auto"` | ✅ Stable | `image_to_patches(imgs, ps, padding="auto")` |
+| Hardware monitoring dashboard | 🔒 Opt-in | `pip install "tgraphx[monitoring]"` |
+| TensorBoard logging | 🔒 Opt-in | `pip install "tgraphx[tracking]"` |
+
+### Scope boundaries (design decisions, not bugs)
+
+- **Spatial / volumetric node features:** `[N, D]`, `[N, C, H, W]`, and
+  `[N, C, D, H, W]` are the supported shapes.  Arbitrary-rank tensors
+  (rank ≥ 5 node features) are out of scope.
+- **GAT per-pixel / per-voxel attention:** score tensors would be
+  `O(E × K × H × W)` — prohibitive for typical spatial GNN workloads.
+  Planned for a future release after memory analysis.
+- **Full hetero/temporal GNN layers:** `HeteroGraph` and
+  `TemporalGraphSequence` are *containers*, not GNN implementations.
+- **PyG/DGL drop-in compatibility:** TGraphX is not a replacement.
+  The optional converters transfer data only; APIs differ.
+- **Neighbor sampling, distributed training, multi-GPU:** out of scope
+  for the current release.
+- **Profiling and file writes:** disabled by default; all are opt-in.
+
+See [docs/roadmap.md](docs/roadmap.md) for the v0.2.5+ planned items.
 
 ---
 
@@ -216,8 +236,8 @@ out = layer(x, edge_index, chunk_size=512)
 ```
 
 Supported aggregations: `"sum"` and `"mean"`.  `"max"` falls back to the
-standard path with a warning.  GAT, SAGE, and GIN chunking are deferred
-(softmax and custom scatter make them more complex).
+standard path with a warning.  SAGE and GIN also support `chunk_size`; GAT
+uses a two-pass algorithm — all four layers accept `chunk_size` in `forward()`.
 
 ### Hardware compatibility
 
@@ -291,7 +311,15 @@ with TensorBoardLogger("runs/tb") as tb:
 ```
 
 Nothing is written unless you explicitly pass a logger.
-`MLflowLogger` is not implemented — use the `mlflow` client directly.
+
+### MLflow logging (optional)
+
+```python
+from tgraphx.tracking import MLflowLogger   # pip install mlflow
+
+with MLflowLogger(run_name="my_run", experiment="gnn") as mlf:
+    history = fit(model, train_loader, logger=mlf, ...)
+```
 
 ---
 
@@ -1182,7 +1210,7 @@ batch.to(device)
 | ✅ Stable | Tested in CI; API is stable |
 | 🧪 Experimental | Available but not yet guaranteed-stable |
 | ⚠️ Best-effort | Works in practice; known constraints documented |
-| ⏳ Planned | On roadmap; not yet implemented |
+| ⏳ Planned | On roadmap for a future release |
 | ❌ Not supported | Out of scope for the current release |
 | 🔒 Opt-in | Disabled by default; explicitly enabled by the user |
 
@@ -1216,12 +1244,12 @@ batch.to(device)
 | Vector edge features `[E, D_e]` | ✅ Stable | GAT, SAGE, GIN |
 | Spatial edge features `[E, C_e, H, W]` | ⚠️ Best-effort | ConvMP (concat); GAT (mean-pooled); SAGE/GIN (full) |
 | Volumetric edge features `[E, C_e, D, H, W]` | ⚠️ Best-effort | Same as spatial; `spatial_rank=3` |
-| Graph Transformer | ❌ Not supported | ⏳ Planned v0.2.5 feasibility study |
-| Heterogeneous graphs | ❌ Not supported | ⏳ Planned v0.2.5+ |
-| Temporal graphs | ❌ Not supported | ⏳ Planned v0.2.5+ |
-| Learned graph construction | ❌ Not supported | `edge_index` is always user-supplied |
-| PyG/DGL converters | ❌ Not supported | ⏳ Planned v0.2.5 |
-| MLflowLogger | ❌ Not supported | Use `mlflow` client directly |
+| Graph Transformer (vector node features only) | 🧪 Experimental | `tgraphx.layers.graph_transformer.GraphTransformerLayer`; tensor-aware variant ⏳ planned |
+| Heterogeneous graphs (container + batch + HeteroConv + classifiers) | 🧪 Experimental | `HeteroGraph`, `HeteroGraphBatch`, `HeteroConv`, `HeteroGraphClassifier`, `HeteroNodeClassifier`; vector node features only |
+| Temporal graphs (container + batch + readout + classifier) | 🧪 Experimental | `TemporalGraphSequence`, `TemporalGraphBatch`, `temporal_readout`, `TemporalGraphClassifier`/`Regressor`; snapshot-loop pattern, no recurrent memory module |
+| Learned graph construction (soft adjacency, edge scorer) | ✅ Stable | `tgraphx.learned_graph` — discrete top-k is non-differentiable |
+| PyG / DGL converters | ✅ Opt-in | `tgraphx.interop` — data converters only, not API replacement |
+| MLflowLogger | ✅ Opt-in | Lazy `mlflow` import; `pip install "tgraphx[mlflow]"` |
 | Dashboard | 🔒 Opt-in | Launch explicitly; zero overhead when off |
 | Offline dashboard export | ✅ Stable | `--export-html` or `export_dashboard_html()` |
 | Multi-run dashboard | ✅ Stable | Point `--logdir` at parent directory |
@@ -1233,15 +1261,19 @@ batch.to(device)
 | Feature | Status | Notes |
 |---------|:------:|-------|
 | `ConvMessagePassing` chunked forward | ✅ Stable | `aggr="sum"` / `"mean"`; max falls back with warning |
-| `TensorGraphSAGELayer` chunked forward | ⏳ Planned v0.2.3 | Deferred |
-| `TensorGINLayer` chunked forward | ⏳ Planned v0.2.3 | Deferred |
-| `TensorGATLayer` chunked forward | ⏳ Planned v0.2.3+ | Destination-wise softmax makes chunking complex |
+| `TensorGraphSAGELayer` chunked forward | ✅ Stable | v0.2.3; mean and max; pass `chunk_size=K` to `forward()` |
+| `TensorGINLayer` chunked forward | ✅ Stable | v0.2.3; sum aggregation; pass `chunk_size=K` to `forward()` |
+| `TensorGATLayer` chunked forward | ⏳ Planned v0.2.4 | Requires two-pass algorithm for destination-wise softmax |
 | `build_grid_graph` / `build_grid_graph_3d` | ✅ Stable | O(E) — scales well |
 | `build_random_graph` | ✅ Stable | O(E) — scales well |
-| `build_knn_graph` / `build_radius_graph` | ⚠️ Best-effort | O(N²) via `torch.cdist`; N > 10 000 emits a warning |
-| `build_fully_connected_graph` / `build_iou_graph` | ⚠️ Best-effort | O(N²) edges; N > 5 000 emits a warning |
-| Dashboard metrics API | ✅ Stable | Incremental `?since_row=N`; `--max-metric-rows` cap |
-| Large `metrics.csv` tail-read | ⏳ Planned v0.2.3 | Current: mtime cache + full re-parse on miss |
+| `build_knn_graph` / `build_radius_graph` | ⚠️ Best-effort | O(N²) time; `chunk_size=K` reduces peak memory to O(K×N) |
+| `build_fully_connected_graph` | ⚠️ Best-effort | O(N²) edges; N > 5 000 emits warning |
+| `build_iou_graph` | ⚠️ Best-effort | O(N²) IoU; `chunk_size=K` reduces peak memory to O(K×N) |
+| `build_random_graph` | ✅ Stable | `algorithm="sample"` uses O(num_edges) memory for large N |
+| Dashboard metrics API | ✅ Stable | Incremental `?since_row=N`; `--max-metric-rows` cap; byte-seek tail-read (v0.2.3) |
+| Large `metrics.csv` tail-read | ✅ Stable | v0.2.3: byte-seek on append; full reparse on rotation/truncation |
+| Subgraph / k-hop / neighbour sampling | ✅ Stable v0.2.6 | `tgraphx.sampling` + `SubgraphDataLoader` / `NeighborSamplerLoader` |
+| Distributed helpers (rank-zero, barrier) | ✅ Stable v0.2.6 | `tgraphx.distributed`; never auto-initialises DDP |
 
 > ⚠️ **Scalability warning:** `build_knn_graph`, `build_radius_graph`, `build_fully_connected_graph`,
 > and `build_iou_graph` use pairwise `torch.cdist` or enumerate all pairs.  Memory and time grow as
@@ -1287,10 +1319,12 @@ batch.to(device)
 | 3-D / volumetric node features | ✅ `ConvMessagePassing`, `TensorGATLayer`, `TensorGraphSAGELayer`, `TensorGINLayer` | ✅ | `[N, C, D, H, W]`; pass `spatial_rank=3` to GAT/SAGE/GIN, or `(C, D, H, W)` `in_shape` to `ConvMessagePassing`. `DeepCNNAggregator` is rank-aware. `LinearMessagePassing` covers vector `[N, D]` and is unaffected. |
 | Edge-conditioned MP (vector) | ✅ `TensorGATLayer`, `TensorGraphSAGELayer`, `TensorGINLayer` | ✅ | edge features `[E, D_e]`; `edge_features_kind="vector"` |
 | `aggr="sum"\|"mean"\|"max"` base | ✅ all three modes | ✅ hand-computed + backward | `ConvMessagePassing` `aggr="max"` routes through `scatter_max` |
-| Graph Transformer | ❌ | — | not implemented |
-| Heterogeneous graphs | ❌ | — | not supported |
-| Temporal / spatiotemporal graphs | ❌ | — | not supported |
-| Learned graph construction | ❌ | — | `edge_index` is always user-supplied |
+| Graph Transformer (vector features) | 🧪 `GraphTransformerLayer` | ✅ | global multi-head self-attention `[N, D]`; O(N²); tensor-aware variant ⏳ planned |
+| Heterogeneous graphs | 🧪 `HeteroGraph`, `HeteroGraphBatch`, `HeteroConv`, `HeteroGraphClassifier`, `HeteroNodeClassifier` | ✅ | vector features; relation-dispatch wrapper + per-type classifier; full PyG-style layer zoo ⏳ planned |
+| Temporal graphs | 🧪 `TemporalGraphSequence`, `TemporalGraphBatch`, `temporal_readout`, `TemporalGraphClassifier`/`Regressor` | ✅ | snapshot loop + readout pattern; TGN/TGAT-style memory module ⏳ planned |
+| Learned graph construction | ✅ `tgraphx.learned_graph` | ✅ | soft adjacency, EdgeScorer (differentiable); top-k discrete (non-diff) |
+| PyG / DGL converters | ✅ `tgraphx.interop` | ✅ | data converters only (lazy imports); not an API replacement |
+| MLflowLogger | ✅ `tgraphx.tracking.MLflowLogger` | ✅ | lazy mlflow import; opt-in via `tgraphx[mlflow]` extra |
 | Arbitrary-rank tensor support beyond rank 0 / 2 / 3 | ❌ | — | only vector, 2-D, and 3-D shapes are supported |
 
 ---

{tgraphx-0.2.2 → tgraphx-0.2.7}/README.md

@@ -74,28 +74,46 @@ drop-in clones of PyTorch Geometric's vector-feature implementations.
 | Dataset & loader | `GraphDataset`, `GraphDataLoader` | — | Wraps `torch.utils.data` |
 | Utilities | `load_config`, `get_device` | — | YAML/JSON config; CUDA→MPS→CPU |
 
-## What is NOT yet implemented
-
-- **Graph Transformers** (global attention with positional encodings).
-- **Per-channel and per-pixel attention** for `TensorGATLayer`. Currently only scalar attention per `(edge, head)` is supported (the default safer choice).
-- **Spatial edge features in `TensorGATLayer`** are accepted as `[E, edge_dim, H, W]` and **mean-pooled** to a vector before the per-`(edge, head)` attention bias projection. This keeps GAT in the scalar-attention regime (no per-pixel attention). `TensorGraphSAGELayer` and `TensorGINLayer` use the full spatial tensor directly (selected via `edge_features_kind="spatial"`).
-- **Per-voxel and per-pixel attention.** `TensorGATLayer` keeps scalar attention per `(edge, head)` even in 3-D mode. Volumetric edge tensors `[E, C_e, D, H, W]` are mean-pooled over `(D, H, W)` before the bias projection — there is no per-voxel attention.
-- **Arbitrary-rank tensor support.** TGraphX supports vector `[N, D]`, 2-D spatial `[N, C, H, W]`, and 3-D volumetric `[N, C, D, H, W]` node features for the listed layers. It does not claim arbitrary-rank tensor support.
-- **Heterogeneous and temporal graphs.**
-- **MLflowLogger.** Not implemented.  Use the `mlflow` client directly.
-  `pip install mlflow`.
-- **GAT / SAGE / GIN chunked forward.** Deferred (GAT's destination-wise
-  softmax requires all edge scores; SAGE/GIN chunking deferred for scope).
-  `ConvMessagePassing` supports `chunk_size` for `sum` / `mean` aggregation.
-- **Hardware-monitoring extras.** CPU/RAM/GPU metrics in the dashboard
-  require optional packages: `pip install tgraphx[monitoring]`.
-- **torch.compile / AMP.** `torch.compile` is available in PyTorch ≥ 2.0
-  and may improve throughput for large graphs; compile overhead dominates
-  for small ones.  Some GNN ops (e.g. `index_add_` in GAT) require matching
-  dtypes and do not work transparently under float16 autocast; bfloat16 or
-  full-precision inference is recommended.
-- **Profiling / logging.** No profiling, hardware polling, or file writes
-  are enabled by default.  All are opt-in.
+## Current scope and boundaries
+
+TGraphX is a focused library for tensor-aware patch-graph GNNs.  Here is
+what is stable, what is experimental, and what is intentionally out of scope.
+Full details are in [docs/limitations.md](docs/limitations.md) and
+[docs/roadmap.md](docs/roadmap.md).
+
+### Optional and experimental features (v0.2.4)
+
+| Feature | Status | Install / usage |
+|---------|:------:|---------|
+| `TensorGATLayer(attention_mode="channel")` | 🧪 Experimental | Constructor argument |
+| `TensorGATLayer(chunk_size=K)` forward | ✅ Stable | `forward(chunk_size=K)` |
+| `GraphTransformerLayer` (vector features only) | 🧪 Experimental | `from tgraphx.layers.graph_transformer import GraphTransformerLayer` |
+| `HeteroGraph` container | 🧪 Experimental | `from tgraphx.core.hetero_graph import HeteroGraph` |
+| `TemporalGraphSequence` container | 🧪 Experimental | `from tgraphx.core.temporal import TemporalGraphSequence` |
+| `MLflowLogger` | ✅ Opt-in | `pip install mlflow` or `pip install "tgraphx[mlflow]"` |
+| PyG / DGL converters | ✅ Opt-in | `from tgraphx.interop import to_pyg_data, to_dgl_graph, …` |
+| Learned graph helpers | ✅ Stable | `from tgraphx.learned_graph import soft_adjacency_from_embeddings, EdgeScorer, …` |
+| Patch helper `padding="auto"` | ✅ Stable | `image_to_patches(imgs, ps, padding="auto")` |
+| Hardware monitoring dashboard | 🔒 Opt-in | `pip install "tgraphx[monitoring]"` |
+| TensorBoard logging | 🔒 Opt-in | `pip install "tgraphx[tracking]"` |
+
+### Scope boundaries (design decisions, not bugs)
+
+- **Spatial / volumetric node features:** `[N, D]`, `[N, C, H, W]`, and
+  `[N, C, D, H, W]` are the supported shapes.  Arbitrary-rank tensors
+  (rank ≥ 5 node features) are out of scope.
+- **GAT per-pixel / per-voxel attention:** score tensors would be
+  `O(E × K × H × W)` — prohibitive for typical spatial GNN workloads.
+  Planned for a future release after memory analysis.
+- **Full hetero/temporal GNN layers:** `HeteroGraph` and
+  `TemporalGraphSequence` are *containers*, not GNN implementations.
+- **PyG/DGL drop-in compatibility:** TGraphX is not a replacement.
+  The optional converters transfer data only; APIs differ.
+- **Neighbor sampling, distributed training, multi-GPU:** out of scope
+  for the current release.
+- **Profiling and file writes:** disabled by default; all are opt-in.
+
+See [docs/roadmap.md](docs/roadmap.md) for the v0.2.5+ planned items.
 
 ---
 
@@ -171,8 +189,8 @@ out = layer(x, edge_index, chunk_size=512)
 ```
 
 Supported aggregations: `"sum"` and `"mean"`.  `"max"` falls back to the
-standard path with a warning.  GAT, SAGE, and GIN chunking are deferred
-(softmax and custom scatter make them more complex).
+standard path with a warning.  SAGE and GIN also support `chunk_size`; GAT
+uses a two-pass algorithm — all four layers accept `chunk_size` in `forward()`.
 
 ### Hardware compatibility
 
@@ -246,7 +264,15 @@ with TensorBoardLogger("runs/tb") as tb:
 ```
 
 Nothing is written unless you explicitly pass a logger.
-`MLflowLogger` is not implemented — use the `mlflow` client directly.
+
+### MLflow logging (optional)
+
+```python
+from tgraphx.tracking import MLflowLogger   # pip install mlflow
+
+with MLflowLogger(run_name="my_run", experiment="gnn") as mlf:
+    history = fit(model, train_loader, logger=mlf, ...)
+```
 
 ---
 
@@ -1137,7 +1163,7 @@ batch.to(device)
 | ✅ Stable | Tested in CI; API is stable |
 | 🧪 Experimental | Available but not yet guaranteed-stable |
 | ⚠️ Best-effort | Works in practice; known constraints documented |
-| ⏳ Planned | On roadmap; not yet implemented |
+| ⏳ Planned | On roadmap for a future release |
 | ❌ Not supported | Out of scope for the current release |
 | 🔒 Opt-in | Disabled by default; explicitly enabled by the user |
 
@@ -1171,12 +1197,12 @@ batch.to(device)
 | Vector edge features `[E, D_e]` | ✅ Stable | GAT, SAGE, GIN |
 | Spatial edge features `[E, C_e, H, W]` | ⚠️ Best-effort | ConvMP (concat); GAT (mean-pooled); SAGE/GIN (full) |
 | Volumetric edge features `[E, C_e, D, H, W]` | ⚠️ Best-effort | Same as spatial; `spatial_rank=3` |
-| Graph Transformer | ❌ Not supported | ⏳ Planned v0.2.5 feasibility study |
-| Heterogeneous graphs | ❌ Not supported | ⏳ Planned v0.2.5+ |
-| Temporal graphs | ❌ Not supported | ⏳ Planned v0.2.5+ |
-| Learned graph construction | ❌ Not supported | `edge_index` is always user-supplied |
-| PyG/DGL converters | ❌ Not supported | ⏳ Planned v0.2.5 |
-| MLflowLogger | ❌ Not supported | Use `mlflow` client directly |
+| Graph Transformer (vector node features only) | 🧪 Experimental | `tgraphx.layers.graph_transformer.GraphTransformerLayer`; tensor-aware variant ⏳ planned |
+| Heterogeneous graphs (container + batch + HeteroConv + classifiers) | 🧪 Experimental | `HeteroGraph`, `HeteroGraphBatch`, `HeteroConv`, `HeteroGraphClassifier`, `HeteroNodeClassifier`; vector node features only |
+| Temporal graphs (container + batch + readout + classifier) | 🧪 Experimental | `TemporalGraphSequence`, `TemporalGraphBatch`, `temporal_readout`, `TemporalGraphClassifier`/`Regressor`; snapshot-loop pattern, no recurrent memory module |
+| Learned graph construction (soft adjacency, edge scorer) | ✅ Stable | `tgraphx.learned_graph` — discrete top-k is non-differentiable |
+| PyG / DGL converters | ✅ Opt-in | `tgraphx.interop` — data converters only, not API replacement |
+| MLflowLogger | ✅ Opt-in | Lazy `mlflow` import; `pip install "tgraphx[mlflow]"` |
 | Dashboard | 🔒 Opt-in | Launch explicitly; zero overhead when off |
 | Offline dashboard export | ✅ Stable | `--export-html` or `export_dashboard_html()` |
 | Multi-run dashboard | ✅ Stable | Point `--logdir` at parent directory |
@@ -1188,15 +1214,19 @@ batch.to(device)
 | Feature | Status | Notes |
 |---------|:------:|-------|
 | `ConvMessagePassing` chunked forward | ✅ Stable | `aggr="sum"` / `"mean"`; max falls back with warning |
-| `TensorGraphSAGELayer` chunked forward | ⏳ Planned v0.2.3 | Deferred |
-| `TensorGINLayer` chunked forward | ⏳ Planned v0.2.3 | Deferred |
-| `TensorGATLayer` chunked forward | ⏳ Planned v0.2.3+ | Destination-wise softmax makes chunking complex |
+| `TensorGraphSAGELayer` chunked forward | ✅ Stable | v0.2.3; mean and max; pass `chunk_size=K` to `forward()` |
+| `TensorGINLayer` chunked forward | ✅ Stable | v0.2.3; sum aggregation; pass `chunk_size=K` to `forward()` |
+| `TensorGATLayer` chunked forward | ⏳ Planned v0.2.4 | Requires two-pass algorithm for destination-wise softmax |
 | `build_grid_graph` / `build_grid_graph_3d` | ✅ Stable | O(E) — scales well |
 | `build_random_graph` | ✅ Stable | O(E) — scales well |
-| `build_knn_graph` / `build_radius_graph` | ⚠️ Best-effort | O(N²) via `torch.cdist`; N > 10 000 emits a warning |
-| `build_fully_connected_graph` / `build_iou_graph` | ⚠️ Best-effort | O(N²) edges; N > 5 000 emits a warning |
-| Dashboard metrics API | ✅ Stable | Incremental `?since_row=N`; `--max-metric-rows` cap |
-| Large `metrics.csv` tail-read | ⏳ Planned v0.2.3 | Current: mtime cache + full re-parse on miss |
+| `build_knn_graph` / `build_radius_graph` | ⚠️ Best-effort | O(N²) time; `chunk_size=K` reduces peak memory to O(K×N) |
+| `build_fully_connected_graph` | ⚠️ Best-effort | O(N²) edges; N > 5 000 emits warning |
+| `build_iou_graph` | ⚠️ Best-effort | O(N²) IoU; `chunk_size=K` reduces peak memory to O(K×N) |
+| `build_random_graph` | ✅ Stable | `algorithm="sample"` uses O(num_edges) memory for large N |
+| Dashboard metrics API | ✅ Stable | Incremental `?since_row=N`; `--max-metric-rows` cap; byte-seek tail-read (v0.2.3) |
+| Large `metrics.csv` tail-read | ✅ Stable | v0.2.3: byte-seek on append; full reparse on rotation/truncation |
+| Subgraph / k-hop / neighbour sampling | ✅ Stable v0.2.6 | `tgraphx.sampling` + `SubgraphDataLoader` / `NeighborSamplerLoader` |
+| Distributed helpers (rank-zero, barrier) | ✅ Stable v0.2.6 | `tgraphx.distributed`; never auto-initialises DDP |
 
 > ⚠️ **Scalability warning:** `build_knn_graph`, `build_radius_graph`, `build_fully_connected_graph`,
 > and `build_iou_graph` use pairwise `torch.cdist` or enumerate all pairs.  Memory and time grow as
@@ -1242,10 +1272,12 @@ batch.to(device)
 | 3-D / volumetric node features | ✅ `ConvMessagePassing`, `TensorGATLayer`, `TensorGraphSAGELayer`, `TensorGINLayer` | ✅ | `[N, C, D, H, W]`; pass `spatial_rank=3` to GAT/SAGE/GIN, or `(C, D, H, W)` `in_shape` to `ConvMessagePassing`. `DeepCNNAggregator` is rank-aware. `LinearMessagePassing` covers vector `[N, D]` and is unaffected. |
 | Edge-conditioned MP (vector) | ✅ `TensorGATLayer`, `TensorGraphSAGELayer`, `TensorGINLayer` | ✅ | edge features `[E, D_e]`; `edge_features_kind="vector"` |
 | `aggr="sum"\|"mean"\|"max"` base | ✅ all three modes | ✅ hand-computed + backward | `ConvMessagePassing` `aggr="max"` routes through `scatter_max` |
-| Graph Transformer | ❌ | — | not implemented |
-| Heterogeneous graphs | ❌ | — | not supported |
-| Temporal / spatiotemporal graphs | ❌ | — | not supported |
-| Learned graph construction | ❌ | — | `edge_index` is always user-supplied |
+| Graph Transformer (vector features) | 🧪 `GraphTransformerLayer` | ✅ | global multi-head self-attention `[N, D]`; O(N²); tensor-aware variant ⏳ planned |
+| Heterogeneous graphs | 🧪 `HeteroGraph`, `HeteroGraphBatch`, `HeteroConv`, `HeteroGraphClassifier`, `HeteroNodeClassifier` | ✅ | vector features; relation-dispatch wrapper + per-type classifier; full PyG-style layer zoo ⏳ planned |
+| Temporal graphs | 🧪 `TemporalGraphSequence`, `TemporalGraphBatch`, `temporal_readout`, `TemporalGraphClassifier`/`Regressor` | ✅ | snapshot loop + readout pattern; TGN/TGAT-style memory module ⏳ planned |
+| Learned graph construction | ✅ `tgraphx.learned_graph` | ✅ | soft adjacency, EdgeScorer (differentiable); top-k discrete (non-diff) |
+| PyG / DGL converters | ✅ `tgraphx.interop` | ✅ | data converters only (lazy imports); not an API replacement |
+| MLflowLogger | ✅ `tgraphx.tracking.MLflowLogger` | ✅ | lazy mlflow import; opt-in via `tgraphx[mlflow]` extra |
 | Arbitrary-rank tensor support beyond rank 0 / 2 / 3 | ❌ | — | only vector, 2-D, and 3-D shapes are supported |
 
 ---

{tgraphx-0.2.2 → tgraphx-0.2.7}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "tgraphx"
 # Keep this in sync with tgraphx/__init__.py::__version__
-version = "0.2.2"
+version = "0.2.7"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -62,11 +62,13 @@ monitoring = [
     "pynvml>=11.0",
 ]
 # TensorBoard integration (TensorBoardLogger uses torch.utils.tensorboard)
-# MLflow is intentionally excluded: MLflowLogger is not implemented in TGraphX.
-# Install mlflow separately if you use it: pip install mlflow
 tracking = [
     "tensorboard>=2.11",
 ]
+# MLflow integration (MLflowLogger uses lazy mlflow import)
+mlflow = [
+    "mlflow>=2.0",
+]
 
 [project.scripts]
 tgraphx-dashboard = "tgraphx.dashboard.app:main"

tgraphx-0.2.7/tests/test_backward_compatibility.py

@@ -0,0 +1,153 @@
+"""Backward-compatibility regression tests (v0.2 → v0.3 prep).
+
+Covers the stable public surface listed in ``docs/deprecation_policy.md``
+and ``docs/migration_v0_2_to_v0_3.md``.
+"""
+from __future__ import annotations
+
+import inspect
+
+import pytest
+import torch
+
+
+# ── Stable top-level exports ─────────────────────────────────────────────────
+
+def test_stable_imports_work():
+    from tgraphx import (
+        Graph, GraphBatch, GraphDataLoader, GraphDataset,
+        build_model, build_model_from_config, make_layer,
+        fit, train_epoch, evaluate, set_seed,
+        save_checkpoint, load_checkpoint,
+        CSVLogger, TensorBoardLogger,
+        env_report, recommended_device, estimate_message_memory,
+        GraphClassifier, NodeClassifier, EdgePredictor,
+        NodeRegressor, GraphRegressor,
+        ConvMessagePassing, TensorGATLayer, TensorGraphSAGELayer,
+        TensorGINLayer, LinearMessagePassing,
+        AttentionMessagePassing,
+        build_grid_graph, build_grid_graph_3d,
+        build_fully_connected_graph, build_knn_graph, build_radius_graph,
+        build_iou_graph, build_random_graph,
+        image_to_patches, volume_to_patches,
+        induced_subgraph, k_hop_subgraph, neighbor_sample,
+        SubgraphDataLoader, NeighborSamplerLoader,
+        write_graph_stats,
+    )
+    # If we reach here, all stable imports succeeded.
+    assert True
+
+
+def test_stable_graph_constructor_signature():
+    """Old keyword args must still work."""
+    import torch
+    from tgraphx import Graph
+    x = torch.randn(3, 4)
+    ei = torch.tensor([[0, 1], [1, 2]], dtype=torch.long)
+    ew = torch.tensor([1.0, 0.5])
+    ef = torch.randn(2, 3)
+    nl = torch.tensor([0, 1, 2])
+    el = torch.tensor([0, 1])
+    gl = torch.tensor(7)
+    g = Graph(
+        node_features=x,
+        edge_index=ei,
+        edge_weight=ew,
+        edge_features=ef,
+        node_labels=nl,
+        edge_labels=el,
+        graph_label=gl,
+        metadata={"k": "v"},
+    )
+    assert g.num_nodes == 3
+    assert g.num_edges == 2
+
+
+def test_stable_layer_constructors():
+    """All four spatial layers + LinearMessagePassing keep working."""
+    from tgraphx.layers import (
+        ConvMessagePassing, TensorGATLayer, TensorGraphSAGELayer,
+        TensorGINLayer, LinearMessagePassing,
+    )
+    cm = ConvMessagePassing((4, 4, 4), (4, 4, 4))
+    gat = TensorGATLayer(4, 4, num_heads=2)
+    sage = TensorGraphSAGELayer(4, 4)
+    gin = TensorGINLayer(4, 4)
+    lin = LinearMessagePassing((4,), (4,))
+    for m in (cm, gat, sage, gin, lin):
+        assert hasattr(m, "forward")
+
+
+def test_stable_factory_signatures():
+    from tgraphx import make_layer, build_model
+    # Old-style factory calls.
+    l = make_layer("gat", in_shape=(4, 4, 4), out_shape=(4, 4, 4), heads=2)
+    assert l is not None
+    m = build_model(
+        task="graph_classification",
+        layer="gat",
+        in_shape=(4, 4, 4), hidden_shape=(8, 4, 4),
+        num_layers=2, num_classes=3, heads=2, pooling="mean",
+    )
+    assert hasattr(m, "forward")
+
+
+def test_stable_training_helpers():
+    from tgraphx import set_seed, fit, train_epoch, evaluate
+    assert callable(set_seed)
+    assert callable(fit)
+    assert callable(train_epoch)
+    assert callable(evaluate)
+
+
+def test_stable_logger_classes():
+    from tgraphx import CSVLogger, TensorBoardLogger
+    assert inspect.isclass(CSVLogger)
+    assert inspect.isclass(TensorBoardLogger)
+
+
+# ── Experimental imports — should still be available ─────────────────────────
+
+def test_experimental_imports_available():
+    from tgraphx import (
+        HeteroGraph, HeteroGraphBatch,
+        TemporalGraphSequence, TemporalGraphBatch,
+        MLflowLogger,
+    )
+    assert all(inspect.isclass(c) for c in (
+        HeteroGraph, HeteroGraphBatch,
+        TemporalGraphSequence, TemporalGraphBatch,
+        MLflowLogger,
+    ))
+
+
+def test_experimental_modules_importable():
+    import tgraphx.interop  # noqa: F401
+    import tgraphx.learned_graph  # noqa: F401
+    import tgraphx.distributed  # noqa: F401
+    import tgraphx.sampling  # noqa: F401
+    import tgraphx.sampling_loaders  # noqa: F401
+    from tgraphx.layers.hetero import HeteroConv  # noqa: F401
+    from tgraphx.layers.graph_transformer import GraphTransformerLayer  # noqa: F401
+
+
+# ── No optional heavy import on package import ───────────────────────────────
+
+def test_no_eager_optional_imports():
+    """Importing tgraphx must not pull in mlflow/torch_geometric/dgl/tensorboard."""
+    import subprocess, sys
+    code = (
+        "import tgraphx, sys; "
+        "for m in ('mlflow', 'torch_geometric', 'dgl', 'tensorboard'): "
+        "    assert m not in sys.modules, f'eager import: {m}'"
+    )
+    # Multi-line in subprocess via -c is awkward with for; use exec-friendly.
+    code = (
+        "import tgraphx, sys\n"
+        "for m in ('mlflow', 'torch_geometric', 'dgl', 'tensorboard'):\n"
+        "    assert m not in sys.modules, f'eager import: {m}'\n"
+        "print('OK')\n"
+    )
+    result = subprocess.run([sys.executable, "-c", code],
+                            capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr