tgraphx 1.3.3__tar.gz → 1.3.4__tar.gz

{tgraphx-1.3.3/tgraphx.egg-info → tgraphx-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 1.3.3
+Version: 1.3.4
 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>

{tgraphx-1.3.3 → tgraphx-1.3.4}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "tgraphx"
 # Keep this in sync with tgraphx/__init__.py::__version__
-version = "1.3.3"
+version = "1.3.4"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.10"

tgraphx-1.3.4/tests/test_colab_regressions_v134.py

@@ -0,0 +1,417 @@
+"""Colab regression tests (v1.3.4).
+
+One test per public snippet that was reported as broken from a Colab / PyPI install.
+These tests pin the exact user-facing code patterns so they can never silently regress.
+
+All tests must:
+- Use only public APIs (importable after `pip install tgraphx`).
+- Run on CPU without network.
+- Be fast (< 30 seconds each).
+- Fail with a clear message if the bug reappears.
+"""
+from __future__ import annotations
+
+import json
+import math
+import tempfile
+from pathlib import Path
+
+import pytest
+import torch
+import torch.nn.functional as F
+
+
+# ── Bug A — Easy Mode deterministic reproducibility ───────────────────────────
+
+
+class TestReproducibilityDetministicCPU:
+    """Same seed + deterministic=True + device=cpu must give identical final loss."""
+
+    def _run_once(self):
+        import tgraphx as tgx
+        from tgraphx.reproducibility import set_seed
+
+        set_seed(42, deterministic=True)
+        data = tgx.easy.synthetic_tensor_node_classification(
+            num_nodes=64, node_shape=(4, 4, 4), num_classes=3,
+            num_edges=200, seed=42,
+        )
+        r = tgx.easy.train_node_classifier(
+            data, epochs=2, batch_size=16, fanouts=[5, 3],
+            verbose=False, seed=42, deterministic=True, device="cpu",
+        )
+        return r
+
+    def test_deterministic_cpu_exact_match(self):
+        r1 = self._run_once()
+        r2 = self._run_once()
+        diff = abs(r1.metrics["loss"] - r2.metrics["loss"])
+        assert diff < 1e-7, f"CPU deterministic loss diff too large: {diff:.2e}"
+
+    def test_synthetic_data_reproducible(self):
+        import tgraphx as tgx
+        d1 = tgx.easy.synthetic_tensor_node_classification(num_nodes=32, seed=7)
+        d2 = tgx.easy.synthetic_tensor_node_classification(num_nodes=32, seed=7)
+        assert torch.equal(d1.node_features, d2.node_features)
+        assert torch.equal(d1.edge_index, d2.edge_index)
+
+    def test_set_seed_returns_state_dict(self):
+        from tgraphx.reproducibility import set_seed
+        state = set_seed(42, deterministic=True)
+        assert isinstance(state, dict)
+        assert state["seed"] == 42
+        assert state["deterministic"] is True
+        assert "torch_version" in state
+
+    def test_train_stores_reproducibility_state(self):
+        r = self._run_once()
+        state = r.config.get("reproducibility_state", {})
+        assert state.get("seed") == 42
+        assert state.get("deterministic") is True
+
+    def test_exact_user_colab_snippet(self):
+        """Exact snippet from the reproducibility bug report."""
+        import tgraphx as tgx
+        from tgraphx.reproducibility import set_seed
+
+        results = []
+        for _ in range(2):
+            set_seed(42, deterministic=True)
+            data = tgx.easy.synthetic_tensor_node_classification(
+                num_nodes=64, node_shape=(4, 4, 4), num_classes=3,
+                num_edges=200, seed=42,
+            )
+            r = tgx.easy.train_node_classifier(
+                data, epochs=2, batch_size=16, fanouts=[5, 3],
+                verbose=False, seed=42, deterministic=True, device="cpu",
+            )
+            results.append(r.metrics["loss"])
+
+        diff = abs(results[0] - results[1])
+        assert diff < 1e-7, diff
+
+
+# ── Bug B — NSGA-II composite_fitness misuse ──────────────────────────────────
+
+
+class TestNSGAIIOptimizer:
+    """NSGAIIOptimizer requires a list of objectives, not composite_fitness directly."""
+
+    def _genome(self, seed=0):
+        from tgraphx.evolutionary import GraphGenome
+        torch.manual_seed(seed)
+        return GraphGenome(edge_index=torch.randint(0, 8, (2, 10)), num_nodes=8)
+
+    def test_nsga_with_list_of_objectives(self):
+        from tgraphx.evolutionary import NSGAIIOptimizer, EvolutionConfig, connectivity_fitness
+        objectives = [connectivity_fitness, connectivity_fitness]
+        config = EvolutionConfig(population_size=6, n_generations=4, seed=0)
+        pop = [self._genome(i) for i in range(6)]
+        r = NSGAIIOptimizer(config, objectives).optimize(pop)
+        assert r.pareto_front is not None
+        assert r.best_fitness >= 0.0
+        assert len(r.history) == 4
+
+    def test_ga_history_works(self):
+        from tgraphx.evolutionary import (
+            GeneticAlgorithmOptimizer, GeneticAlgorithmConfig, connectivity_fitness,
+        )
+        config = GeneticAlgorithmConfig(population_size=6, n_generations=5, seed=42)
+        pop = [self._genome(i) for i in range(6)]
+        r = GeneticAlgorithmOptimizer(config, connectivity_fitness).optimize(pop)
+        assert len(r.history) == 5
+        assert "generation" in r.history[0]
+        assert "best_fitness" in r.history[0]
+
+    def test_nsga_history_works(self):
+        from tgraphx.evolutionary import NSGAIIOptimizer, EvolutionConfig, connectivity_fitness
+        config = EvolutionConfig(population_size=4, n_generations=3, seed=0)
+        pop = [self._genome(i) for i in range(4)]
+        r = NSGAIIOptimizer(config, [connectivity_fitness]).optimize(pop)
+        assert len(r.history) == 3
+
+    def test_evolution_result_to_dict_json_serializable(self):
+        from tgraphx.evolutionary import (
+            GeneticAlgorithmOptimizer, GeneticAlgorithmConfig, connectivity_fitness,
+        )
+        config = GeneticAlgorithmConfig(population_size=4, n_generations=3, seed=0)
+        pop = [self._genome(i) for i in range(4)]
+        r = GeneticAlgorithmOptimizer(config, connectivity_fitness).optimize(pop)
+        d = r.to_dict()
+        json.dumps(d)  # must not raise
+
+
+# ── Bug C — GraphML exception handling ───────────────────────────────────────
+
+
+class TestGraphMLExceptionHandling:
+    """ValueError from write_graphml must be formatted with str(e), not e[:120]."""
+
+    def test_str_exception_not_slice(self, tmp_path):
+        """Ensures str(e)[:120] works; e[:120] would TypeError in real code."""
+        from tgraphx import Graph
+        from tgraphx.io import write_graphml
+
+        x_spatial = torch.randn(4, 3, 8, 8)
+        g = Graph(node_features=x_spatial,
+                  edge_index=torch.tensor([[0, 1], [1, 2]]))
+
+        caught = None
+        try:
+            write_graphml(g, tmp_path / "test.graphml", include_tensor_features=True)
+        except ValueError as e:
+            caught = e
+            msg = str(e)[:120]  # must not raise TypeError
+            assert "multi-dimensional" in msg or "rank" in msg or "shape" in msg or "tensor" in msg.lower()
+
+        assert caught is not None, "Expected ValueError for [N,C,H,W] tensor features"
+
+    def test_1d_features_round_trip(self, tmp_path):
+        """1-D node features must round-trip through GraphML without error."""
+        from tgraphx import Graph
+        from tgraphx.io import write_graphml, read_graphml
+
+        x = torch.tensor([[0.5], [1.0], [0.25]])
+        ei = torch.tensor([[0, 1], [1, 2]], dtype=torch.long)
+        g = Graph(node_features=x, edge_index=ei)
+        path = tmp_path / "roundtrip.graphml"
+        write_graphml(g, path, include_tensor_features=True)
+        g2 = read_graphml(path)
+        assert g2.num_nodes == 3
+        assert g2.num_edges == 2
+
+
+# ── Bug D — motif_profile / graph_summary import ─────────────────────────────
+
+
+class TestMiningImports:
+    def test_motif_profile_importable(self):
+        from tgraphx.mining import motif_profile
+        assert callable(motif_profile)
+
+    def test_graph_summary_importable(self):
+        from tgraphx.mining import graph_summary
+        assert callable(graph_summary)
+
+    def test_graph_summary_returns_expected_keys(self):
+        from tgraphx.mining import graph_summary
+        ei = torch.tensor([[0, 1, 2, 3, 4], [1, 2, 3, 4, 0]], dtype=torch.long)
+        s = graph_summary(ei, num_nodes=5)
+        for key in ("num_nodes", "num_edges"):
+            assert key in s, f"Missing key: {key}"
+        assert s["num_nodes"] == 5
+
+    def test_motif_profile_returns_dict_with_triangles(self):
+        from tgraphx.mining import motif_profile
+        # Triangle graph
+        ei = torch.tensor([[0, 1, 2, 1, 2, 0], [1, 2, 0, 0, 1, 2]], dtype=torch.long)
+        m = motif_profile(ei, num_nodes=3)
+        assert isinstance(m, dict)
+        # There is at least one triangle
+        assert m.get("triangles", 0) > 0 or "triangles" in str(m)
+
+    def test_degree_statistics_importable(self):
+        from tgraphx.mining import degree_statistics
+        ei = torch.tensor([[0, 0, 0, 0], [1, 2, 3, 4]], dtype=torch.long)
+        s = degree_statistics(ei, num_nodes=5)
+        assert isinstance(s, dict)
+
+    def test_notebook_20_smoke(self):
+        """Exact imports from notebook 20."""
+        from tgraphx.mining import motif_profile, graph_summary
+        from tgraphx.mining.matching_coloring import enumerate_maximal_cliques
+        import torch
+        N = 5
+        ei = torch.tensor([[0, 1, 2, 3, 4], [1, 2, 3, 4, 0]], dtype=torch.long)
+        summary = graph_summary(ei, num_nodes=N)
+        assert isinstance(summary, dict)
+        profile = motif_profile(ei, num_nodes=N)
+        assert isinstance(profile, dict)
+        cliques = enumerate_maximal_cliques(ei, num_nodes=N, max_nodes=50)
+        assert isinstance(cliques, list)
+
+
+# ── Bug E — wl_subtree_kernel import ─────────────────────────────────────────
+
+
+class TestWLSubtreeKernel:
+    def test_importable(self):
+        from tgraphx.mining import wl_subtree_kernel
+        assert callable(wl_subtree_kernel)
+
+    def test_identical_graphs_higher_than_different(self):
+        from tgraphx.mining import wl_subtree_kernel
+        ei_ring5 = torch.tensor([[0, 1, 2, 3, 4], [1, 2, 3, 4, 0]], dtype=torch.long)
+        ei_ring3 = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.long)
+        k_self = wl_subtree_kernel(ei_ring5, 5, ei_ring5, 5, h=3)
+        k_cross = wl_subtree_kernel(ei_ring5, 5, ei_ring3, 3, h=3)
+        assert k_self >= k_cross
+
+    def test_symmetry(self):
+        from tgraphx.mining import wl_subtree_kernel
+        ei_a = torch.tensor([[0, 1], [1, 2]], dtype=torch.long)
+        ei_b = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.long)
+        k_ab = wl_subtree_kernel(ei_a, 3, ei_b, 3, h=2)
+        k_ba = wl_subtree_kernel(ei_b, 3, ei_a, 3, h=2)
+        assert abs(k_ab - k_ba) < 1e-6
+
+    def test_normalize_finite(self):
+        from tgraphx.mining import wl_subtree_kernel
+        ei = torch.tensor([[0, 1], [1, 0]], dtype=torch.long)
+        k = wl_subtree_kernel(ei, 2, ei, 2, h=2, normalize=True)
+        assert math.isfinite(k)
+
+    def test_notebook_21_smoke(self):
+        """Exact import from notebook 21."""
+        from tgraphx.mining.kernels import wl_subtree_kernel
+        # Must work through kernels module too via alias; check from mining
+        from tgraphx.mining import wl_subtree_kernel as wl_sk
+        ei5 = torch.tensor([[0, 1, 2, 3, 4], [1, 2, 3, 4, 0]], dtype=torch.long)
+        ei3 = torch.tensor([[0, 1, 2], [1, 2, 0]], dtype=torch.long)
+        k = wl_sk(ei5, 5, ei3, 3, h=3)
+        assert k >= 0
+
+
+# ── Bug F — centrality_summary import ────────────────────────────────────────
+
+
+class TestCentralitySummary:
+    def test_importable(self):
+        from tgraphx.mining import centrality_summary
+        assert callable(centrality_summary)
+
+    def test_star_center_is_top(self):
+        from tgraphx.mining import centrality_summary
+        # Star graph: node 0 is center
+        star_ei = torch.tensor([[0, 0, 0, 0, 1, 2, 3, 4],
+                                 [1, 2, 3, 4, 0, 0, 0, 0]], dtype=torch.long)
+        cs = centrality_summary(star_ei, num_nodes=5)
+        assert cs["top_degree_nodes"][0][0] == 0, "Star center must be top"
+
+    def test_returns_expected_keys(self):
+        from tgraphx.mining import centrality_summary
+        ei = torch.tensor([[0, 1], [1, 2]], dtype=torch.long)
+        cs = centrality_summary(ei, num_nodes=3)
+        for key in ("num_nodes", "num_edges", "top_degree_nodes"):
+            assert key in cs
+
+    def test_notebook_22_smoke(self):
+        """Exact imports from notebook 22."""
+        from tgraphx.mining import degree_statistics, centrality_summary
+        star_ei = torch.tensor([[0, 0, 0, 0, 1, 2, 3, 4],
+                                  [1, 2, 3, 4, 0, 0, 0, 0]], dtype=torch.long)
+        ds = degree_statistics(star_ei, num_nodes=5)
+        cs = centrality_summary(star_ei, num_nodes=5)
+        assert isinstance(ds, dict)
+        assert isinstance(cs, dict)
+
+
+# ── Bug G — Package-level benchmark suite ────────────────────────────────────
+
+
+class TestPackageBenchmarkSuite:
+    def test_importable_from_package(self):
+        from tgraphx.benchmarks import run_v13_benchmark_suite
+        assert callable(run_v13_benchmark_suite)
+
+    def test_runs_outside_repo_tree(self, tmp_path):
+        """Simulate running from outside repo: use package API, not repo script."""
+        import subprocess, sys
+        result = subprocess.run(
+            [sys.executable, "-c",
+             "from tgraphx.benchmarks import run_v13_benchmark_suite;"
+             "data = run_v13_benchmark_suite(small=True, return_dict=True);"
+             "assert 'benchmarks' in data;"
+             "print('OK', len(data['benchmarks']))"],
+            capture_output=True, text=True, timeout=120,
+            cwd=str(tmp_path),  # Run from an empty temp dir, not repo
+        )
+        assert result.returncode == 0, f"STDERR: {result.stderr[:300]}"
+        assert "OK" in result.stdout
+
+    def test_returns_expected_schema(self):
+        from tgraphx.benchmarks import run_v13_benchmark_suite
+        data = run_v13_benchmark_suite(small=True, return_dict=True)
+        assert "suite" in data
+        assert "benchmarks" in data
+        for row in data["benchmarks"]:
+            assert "name" in row
+            assert "status" in row
+
+    def test_json_serializable(self):
+        from tgraphx.benchmarks import run_v13_benchmark_suite
+        data = run_v13_benchmark_suite(small=True, return_dict=True)
+        json.dumps(data, default=str)
+
+    def test_python_m_cli(self, tmp_path):
+        """python -m tgraphx.benchmarks.run_v13_benchmark_suite --small --json"""
+        import subprocess, sys
+        out_file = tmp_path / "out.json"
+        result = subprocess.run(
+            [sys.executable, "-m", "tgraphx.benchmarks.run_v13_benchmark_suite",
+             "--small", "--out", str(out_file)],
+            capture_output=True, text=True, timeout=120,
+            cwd=str(tmp_path),
+        )
+        assert result.returncode == 0, f"STDERR: {result.stderr[:300]}"
+        data = json.loads(out_file.read_text())
+        assert "benchmarks" in data
+
+
+# ── Bug H — ConvMessagePassing / NeighborLoader seed-node loss ───────────────
+
+
+class TestConvMessagePassingNeighborLoader:
+    def test_seed_logits_no_unsafe_slicing(self):
+        """batch.seed_logits(logits) must work; logits[:batch_size] would be wrong."""
+        from tgraphx import Graph, NeighborLoader
+        import torch.nn as nn
+
+        torch.manual_seed(0)
+        N, D = 50, 8
+        x = torch.randn(N, D)
+        ei = torch.randint(0, N, (2, 200))
+        y = torch.randint(0, 3, (N,))
+        g = Graph(node_features=x, edge_index=ei, y=y)
+
+        loader = NeighborLoader(g, fanouts=[5, 3], batch_size=8, seed=0)
+        linear = nn.Linear(D, 3)
+        opt = torch.optim.Adam(linear.parameters(), lr=1e-2)
+
+        batch = next(iter(loader))
+        logits = linear(batch.node_features)
+        # Correct API: batch.seed_logits extracts supervision-node logits.
+        seed_logits = batch.seed_logits(logits)
+        assert seed_logits.shape[0] == batch.batch_size
+        loss = F.cross_entropy(seed_logits, batch.seed_y)
+        loss.backward()
+        assert torch.isfinite(loss)
+
+
+# ── Bug I — Feature-aware KG regression (v1.3.1 fix) ────────────────────────
+
+
+class TestFeatureAwareKGRegression:
+    def test_entity_features_score_triples(self):
+        """Exact snippet from v1.3.1 Colab bug report."""
+        from tgraphx.kg import KnowledgeGraph, TransEModel
+
+        torch.manual_seed(0)
+        N_e, N_r, N_t = 10, 3, 30
+        heads = torch.randint(0, N_e, (N_t,))
+        rels = torch.randint(0, N_r, (N_t,))
+        tails = torch.randint(0, N_e, (N_t,))
+        entity_features = {"visual": torch.randn(N_e, 32)}
+
+        kg = KnowledgeGraph.from_hrt(
+            heads, rels, tails,
+            num_entities=N_e, num_relations=N_r,
+            entity_features=entity_features,
+        )
+
+        model = TransEModel(N_e, N_r, embedding_dim=16, entity_feature_dim=32)
+        triples = torch.stack([heads, rels, tails], dim=1)
+        scores = model.score_triples(triples, entity_features=kg.entity_features["visual"])
+        assert scores.shape == (N_t,)
+        scores.mean().backward()
+        assert model.entity_proj.proj.weight.grad is not None

{tgraphx-1.3.3 → tgraphx-1.3.4}/tests/test_notebooks_v130.py

@@ -1,6 +1,14 @@
-"""Notebook structural tests (v1.3).
+"""Notebook structural tests (v1.3 / v1.3.4+).
 
 Validates every notebook/*.ipynb without executing code.
+
+The notebooks/ folder is NOT tracked in git (it is gitignored as of v1.3.4).
+These tests skip gracefully when notebooks/ is absent so that CI remains
+green in the absence of locally generated notebooks.
+
+To run locally, first generate notebooks with::
+
+    python tools/generate_notebooks.py
 """
 from __future__ import annotations
 
@@ -11,26 +19,36 @@ from pathlib import Path
 import pytest
 
 NOTEBOOKS_DIR = Path("notebooks")
-NOTEBOOKS = sorted(NOTEBOOKS_DIR.glob("*.ipynb"))
+_NOTEBOOKS_PRESENT = NOTEBOOKS_DIR.exists() and bool(list(NOTEBOOKS_DIR.glob("*.ipynb")))
+NOTEBOOKS = sorted(NOTEBOOKS_DIR.glob("*.ipynb")) if NOTEBOOKS_DIR.exists() else []
 
 _PRIVATE_PATH_RE = re.compile(r"/home/[a-zA-Z0-9_]+|/Users/[a-zA-Z0-9_]+")
 _SECRET_RE = re.compile(r"(?i)(token\s*=|password\s*=|api_key\s*=)['\"]?\w{8,}")
 
+_skip_if_absent = pytest.mark.skipif(
+    not _NOTEBOOKS_PRESENT,
+    reason="notebooks/ not found locally; generate with: python tools/generate_notebooks.py",
+)
+
 
 @pytest.fixture(scope="module")
 def all_notebooks():
-    assert NOTEBOOKS_DIR.exists(), f"notebooks/ directory not found: {NOTEBOOKS_DIR}"
-    assert len(NOTEBOOKS) > 0, f"No .ipynb files in {NOTEBOOKS_DIR}"
+    if not _NOTEBOOKS_PRESENT:
+        pytest.skip("notebooks/ not found")
     return {nb.name: json.loads(nb.read_text(encoding="utf-8")) for nb in NOTEBOOKS}
 
 
 class TestNotebooksExist:
-    def test_notebooks_dir_exists(self):
+    def test_notebooks_dir_exists_or_skips(self):
+        if not _NOTEBOOKS_PRESENT:
+            pytest.skip("notebooks/ not found locally — OK in CI without local notebooks")
         assert NOTEBOOKS_DIR.exists()
 
+    @_skip_if_absent
     def test_at_least_7_notebooks(self):
         assert len(NOTEBOOKS) >= 7, f"Expected >=7 notebooks, found {len(NOTEBOOKS)}"
 
+    @_skip_if_absent
     @pytest.mark.parametrize("name", [
         "01_easy_tensor_node_classification.ipynb",
         "02_image_patch_tensor_graph.ipynb",
@@ -106,6 +124,7 @@ class TestNotebookContent:
 
 
 class TestNotebookValidationTool:
+    @_skip_if_absent
     def test_validate_notebooks_passes(self):
         import subprocess, sys
         result = subprocess.run(

{tgraphx-1.3.3 → tgraphx-1.3.4}/tgraphx/__init__.py

@@ -10,7 +10,7 @@ Common one-liner imports::
 """
 
 # Keep this in sync with [project].version in pyproject.toml.
-__version__ = "1.3.3"
+__version__ = "1.3.4"
 
 # ── Core data structures ──────────────────────────────────────────────────────
 from .core.graph import Graph, GraphBatch

{tgraphx-1.3.3 → tgraphx-1.3.4}/tgraphx/benchmarks/__init__.py

@@ -1,11 +1,17 @@
-"""Public-benchmark integration helpers (OGB / TGB).
+"""Public-benchmark integration helpers (OGB / TGB) and v1.3 benchmark suite.
 
 Optional, dependency-light evaluator wrappers around the official
 benchmark packages.  Importing this module never triggers a network
 call; callers must explicitly download datasets via the upstream
 packages.
 
-Stability: Beta (v0.5.0+).
+The v1.3 benchmark suite is available as a package-level function so it
+can be called without a cloned repository::
+
+    from tgraphx.benchmarks import run_v13_benchmark_suite
+    results = run_v13_benchmark_suite(small=True, return_dict=True)
+
+Stability: Beta (v0.5.0+). ``run_v13_benchmark_suite`` — Beta (v1.3.4+).
 """
 from __future__ import annotations
 
@@ -15,10 +21,12 @@ from .public import (
     OGBGraphEvaluator,
     TGBLinkEvaluator,
 )
+from .suite import run_v13_benchmark_suite
 
 __all__ = [
     "OGBNodeEvaluator",
     "OGBLinkEvaluator",
     "OGBGraphEvaluator",
     "TGBLinkEvaluator",
+    "run_v13_benchmark_suite",
 ]

tgraphx-1.3.4/tgraphx/benchmarks/run_v13_benchmark_suite.py

@@ -0,0 +1,51 @@
+"""CLI entry point for the v1.3 benchmark suite.
+
+Usage::
+
+    python -m tgraphx.benchmarks.run_v13_benchmark_suite --small --json
+    python -m tgraphx.benchmarks.run_v13_benchmark_suite --out out.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .suite import run_v13_benchmark_suite
+
+
+def main():
+    p = argparse.ArgumentParser(description="TGraphX v1.3 benchmark suite")
+    p.add_argument("--small", action="store_true", help="Use tiny configs (CI-safe).")
+    p.add_argument("--device", default="cpu", choices=["cpu", "cuda"])
+    p.add_argument("--seed", type=int, default=42)
+    p.add_argument("--out", default=None, help="JSON output path.")
+    p.add_argument("--repeat", type=int, default=1, help="Repeats per benchmark.")
+    p.add_argument("--json", action="store_true", help="Print JSON to stdout.")
+    args = p.parse_args()
+
+    data = run_v13_benchmark_suite(
+        small=args.small,
+        device=args.device,
+        seed=args.seed,
+        repeat=args.repeat,
+        return_dict=True,
+        out=args.out,
+    )
+
+    if args.out:
+        print(f"[v13-suite] wrote {args.out}")
+
+    if args.json or args.out is None:
+        print(json.dumps(data, indent=2))
+
+    failed = [r for r in data["benchmarks"] if r["status"] == "failed"]
+    if failed:
+        print(f"\n[v13-suite] {len(failed)} failed:", file=sys.stderr)
+        for r in failed:
+            print(f"  - {r['name']}: {r.get('error', '')}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()