tgraphx 1.4.0__tar.gz → 1.4.2__tar.gz

{tgraphx-1.4.0/tgraphx.egg-info → tgraphx-1.4.2}/PKG-INFO

@@ -1,11 +1,12 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 1.4.0
+Version: 1.4.2
 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>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/arashsajjadi/TGraphX
+Project-URL: Homepage, https://tgraphx.com
+Project-URL: Source, https://github.com/arashsajjadi/TGraphX
 Project-URL: Repository, https://github.com/arashsajjadi/TGraphX
 Project-URL: Documentation, https://github.com/arashsajjadi/TGraphX/tree/main/docs
 Project-URL: Issues, https://github.com/arashsajjadi/TGraphX/issues
@@ -80,11 +81,13 @@ Dynamic: license-file
 
 **Preprint:** [TGraphX: Tensor-Aware Graph Neural Network for Multi-Dimensional Feature Learning](https://arxiv.org/abs/2504.03953) · *Sajjadi & Eramian, arXiv 2025*
 
-TGraphX is a **tensor-native graph intelligence framework** for research workflows that combine graph learning, graph mining, knowledge graphs, graph generation, evolutionary optimization, graph reinforcement learning, reproducibility, and dashboard-ready reporting — all in PyTorch, with no mandatory external dependencies.
+**Official website:** [https://tgraphx.com](https://tgraphx.com)
+
+TGraphX is a **tensor-native graph intelligence framework** for research workflows that combine graph learning, graph mining, knowledge graphs, graph generation, evolutionary optimization, graph reinforcement learning, reproducibility, and dashboard-ready reporting — all in PyTorch. The base package does not require PyG, DGL, OGB, PyKEEN, Stable-Baselines3, or RLlib; it depends only on the PyTorch stack and the lightweight runtime utilities declared in `pyproject.toml` (`torch`, `torchvision`, `pyyaml`).
 
 It preserves **multi-dimensional node/edge features** (`[C, H, W]`, `[C, D, H, W]`, `[D]`) through every message-passing step, supports scalable mini-batch samplers (GraphSAINT, Cluster-GCN), multimodal tensor-aware knowledge graphs, 13 graph RL algorithms, classical and neural graph generation, multi-objective evolutionary optimization, a local dashboard with offline HTML export, sklearn-like estimators, and a full benchmark + tutorial suite.
 
-**Quick links:** [Graph algorithms](docs/graph_algorithms.md) · [Graph mining](docs/graph_mining.md) · [Tensor GNNs](docs/vector_gnn.md) · [Sampling](docs/graphsaint.md) · [FeatureStore](docs/feature_store.md) · [KG](docs/knowledge_graphs.md) · [Dashboard](docs/dashboard.md) · [Easy Mode](docs/easy_mode.md) · [LLM guide](docs/llm_usage_guide.md)
+**Quick links:** [Official website](https://tgraphx.com) · [Graph algorithms](docs/graph_algorithms.md) · [Graph mining](docs/graph_mining.md) · [Tensor GNNs](docs/vector_gnn.md) · [Sampling](docs/graphsaint.md) · [FeatureStore](docs/feature_store.md) · [KG](docs/knowledge_graphs.md) · [Dashboard](docs/dashboard.md) · [Easy Mode](docs/easy_mode.md) · [LLM guide](docs/llm_usage_guide.md)
 
 ---
 
@@ -142,6 +145,57 @@ Advanced users can always drop down to PyTorch: `result.model`, `result.graph`,
 
 ---
 
+## v1.4.1: final usability hardening
+
+v1.4.1 adds one-call entry points for common workflows. All v1.4.0 and
+v1.3.x syntax is preserved.
+
+**Tensor node classification in one call.**
+```python
+result = tgx.classify_nodes(
+    x=images, edge_index=edge_index, labels=y,
+    model="tensor_gcn", seed=42, device="auto",
+)
+print(result.metrics["val_accuracy"])
+```
+
+**KG link prediction in one call.**
+```python
+result = tgx.kg_completion(
+    triples=triples, num_entities=N, num_relations=R,
+    model="transe", seed=42,
+)
+```
+
+**Graph construction from any format.**
+```python
+g = tgx.make_graph(x=x, edges=[(0,1),(1,2)], labels=y)
+g = tgx.make_graph(x=x, adjacency=adj)
+g = tgx.make_graph(networkx_graph=G)
+```
+
+**Graph generation, optimization, and RL in one call.**
+```python
+g = tgx.generate_graph("ba", num_nodes=100, m=3, node_shape=(8,), seed=42)
+
+result = tgx.optimize_graph(objective="connectivity", algorithm="ga", num_nodes=30, seed=42)
+
+rl = tgx.train_graph_rl(env="maxcut", algorithm="random", episodes=5, seed=42)
+```
+
+**Troubleshooting.**
+```python
+print(tgx.explain_error(error))  # returns actionable guidance
+```
+
+**Package readiness.**
+```bash
+python -m tgraphx readiness
+python -m tgraphx list-datasets
+```
+
+---
+
 ## v1.4.0: user-friendly tensor-native workflows
 
 v1.4.0 keeps every canonical API stable while adding **mathematically-safe**

{tgraphx-1.4.0 → tgraphx-1.4.2}/README.md

@@ -25,11 +25,13 @@
 
 **Preprint:** [TGraphX: Tensor-Aware Graph Neural Network for Multi-Dimensional Feature Learning](https://arxiv.org/abs/2504.03953) · *Sajjadi & Eramian, arXiv 2025*
 
-TGraphX is a **tensor-native graph intelligence framework** for research workflows that combine graph learning, graph mining, knowledge graphs, graph generation, evolutionary optimization, graph reinforcement learning, reproducibility, and dashboard-ready reporting — all in PyTorch, with no mandatory external dependencies.
+**Official website:** [https://tgraphx.com](https://tgraphx.com)
+
+TGraphX is a **tensor-native graph intelligence framework** for research workflows that combine graph learning, graph mining, knowledge graphs, graph generation, evolutionary optimization, graph reinforcement learning, reproducibility, and dashboard-ready reporting — all in PyTorch. The base package does not require PyG, DGL, OGB, PyKEEN, Stable-Baselines3, or RLlib; it depends only on the PyTorch stack and the lightweight runtime utilities declared in `pyproject.toml` (`torch`, `torchvision`, `pyyaml`).
 
 It preserves **multi-dimensional node/edge features** (`[C, H, W]`, `[C, D, H, W]`, `[D]`) through every message-passing step, supports scalable mini-batch samplers (GraphSAINT, Cluster-GCN), multimodal tensor-aware knowledge graphs, 13 graph RL algorithms, classical and neural graph generation, multi-objective evolutionary optimization, a local dashboard with offline HTML export, sklearn-like estimators, and a full benchmark + tutorial suite.
 
-**Quick links:** [Graph algorithms](docs/graph_algorithms.md) · [Graph mining](docs/graph_mining.md) · [Tensor GNNs](docs/vector_gnn.md) · [Sampling](docs/graphsaint.md) · [FeatureStore](docs/feature_store.md) · [KG](docs/knowledge_graphs.md) · [Dashboard](docs/dashboard.md) · [Easy Mode](docs/easy_mode.md) · [LLM guide](docs/llm_usage_guide.md)
+**Quick links:** [Official website](https://tgraphx.com) · [Graph algorithms](docs/graph_algorithms.md) · [Graph mining](docs/graph_mining.md) · [Tensor GNNs](docs/vector_gnn.md) · [Sampling](docs/graphsaint.md) · [FeatureStore](docs/feature_store.md) · [KG](docs/knowledge_graphs.md) · [Dashboard](docs/dashboard.md) · [Easy Mode](docs/easy_mode.md) · [LLM guide](docs/llm_usage_guide.md)
 
 ---
 
@@ -87,6 +89,57 @@ Advanced users can always drop down to PyTorch: `result.model`, `result.graph`,
 
 ---
 
+## v1.4.1: final usability hardening
+
+v1.4.1 adds one-call entry points for common workflows. All v1.4.0 and
+v1.3.x syntax is preserved.
+
+**Tensor node classification in one call.**
+```python
+result = tgx.classify_nodes(
+    x=images, edge_index=edge_index, labels=y,
+    model="tensor_gcn", seed=42, device="auto",
+)
+print(result.metrics["val_accuracy"])
+```
+
+**KG link prediction in one call.**
+```python
+result = tgx.kg_completion(
+    triples=triples, num_entities=N, num_relations=R,
+    model="transe", seed=42,
+)
+```
+
+**Graph construction from any format.**
+```python
+g = tgx.make_graph(x=x, edges=[(0,1),(1,2)], labels=y)
+g = tgx.make_graph(x=x, adjacency=adj)
+g = tgx.make_graph(networkx_graph=G)
+```
+
+**Graph generation, optimization, and RL in one call.**
+```python
+g = tgx.generate_graph("ba", num_nodes=100, m=3, node_shape=(8,), seed=42)
+
+result = tgx.optimize_graph(objective="connectivity", algorithm="ga", num_nodes=30, seed=42)
+
+rl = tgx.train_graph_rl(env="maxcut", algorithm="random", episodes=5, seed=42)
+```
+
+**Troubleshooting.**
+```python
+print(tgx.explain_error(error))  # returns actionable guidance
+```
+
+**Package readiness.**
+```bash
+python -m tgraphx readiness
+python -m tgraphx list-datasets
+```
+
+---
+
 ## v1.4.0: user-friendly tensor-native workflows
 
 v1.4.0 keeps every canonical API stable while adding **mathematically-safe**

{tgraphx-1.4.0 → tgraphx-1.4.2}/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.4.0"
+version = "1.4.2"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -96,7 +96,8 @@ tgraphx-doctor = "tgraphx.__main__:main"
 tgraphx-info = "tgraphx.__main__:main"
 
 [project.urls]
-Homepage = "https://github.com/arashsajjadi/TGraphX"
+Homepage = "https://tgraphx.com"
+Source = "https://github.com/arashsajjadi/TGraphX"
 Repository = "https://github.com/arashsajjadi/TGraphX"
 Documentation = "https://github.com/arashsajjadi/TGraphX/tree/main/docs"
 Issues = "https://github.com/arashsajjadi/TGraphX/issues"

{tgraphx-1.4.0 → tgraphx-1.4.2}/tests/test_advanced_notebook_workflows_v138.py

@@ -351,15 +351,30 @@ def test_nb35_mutag_workflow_with_edge_attr() -> None:
 
 def test_pyg_singleton_graph_label_normalized() -> None:
     """Regression: PyG MUTAG stores graph label as tensor([1]) (shape [1]).
-    from_pyg_data should normalize this to scalar so cross_entropy works after batching."""
+    from_pyg_data should normalize this to scalar so cross_entropy works after batching.
+
+    This test only runs when MUTAG is already cached locally; it never
+    initiates a network download from the test suite. Set the env var
+    ``TGRAPHX_TESTS_ALLOW_NETWORK=1`` to opt back in to downloads.
+    """
     import importlib
+    import os
     pyg = importlib.util.find_spec("torch_geometric")
     if pyg is None:
         pytest.skip("torch_geometric not installed")
     from tgraphx.datasets import PyGTUDatasetAdapter
+    from tgraphx.datasets.cache import resolve_dataset_root
     from tgraphx import GraphDataLoader
 
-    ds = PyGTUDatasetAdapter(name="MUTAG", download=True)
+    allow_net = os.environ.get("TGRAPHX_TESTS_ALLOW_NETWORK") == "1"
+    cached_root = resolve_dataset_root(None, "pyg/TUDataset") / "MUTAG"
+    has_raw = (cached_root / "raw").exists() or (cached_root / "processed").exists()
+    if not has_raw and not allow_net:
+        pytest.skip(
+            "MUTAG raw files not cached locally and "
+            "TGRAPHX_TESTS_ALLOW_NETWORK!=1; skipping to avoid network."
+        )
+    ds = PyGTUDatasetAdapter(name="MUTAG", download=allow_net)
     g = ds.get(0)
     # graph_label must be scalar tensor (shape []), not [1]
     assert g.graph_label.dim() == 0, (

tgraphx-1.4.2/tests/test_audit_fixes_v142.py

@@ -0,0 +1,263 @@
+"""Regression tests for the v1.4.2 audit-fix release.
+
+Each test pins down one of the validated audit findings so it cannot
+silently regress.  Tests prefer synthetic inputs and CPU-only behaviour
+so they stay deterministic and offline-safe in CI.
+"""
+from __future__ import annotations
+
+import subprocess
+import sys
+
+import pytest
+import torch
+
+import tgraphx
+from tgraphx import Graph
+
+
+# ── Codex/Composer TGX-AUDIT-002 / 001: make_graph + NetworkX  ──────────────
+
+
+def _require_nx():
+    try:
+        import networkx  # noqa: F401
+    except ImportError:
+        pytest.skip("networkx not installed")
+    import networkx as nx
+    return nx
+
+
+def test_make_graph_networkx_preserves_external_features() -> None:
+    nx = _require_nx()
+    G = nx.path_graph(3)
+    x = torch.arange(15, dtype=torch.float32).reshape(3, 5)
+    g = tgraphx.make_graph(x=x, networkx_graph=G)
+    assert g.node_features.shape == (3, 5)
+    # Original tensor content survives (no zero placeholder).
+    assert torch.equal(g.node_features, x)
+    # Topology is non-trivial (path 0-1-2, undirected => 4 directed edges).
+    assert g.num_edges == 4
+
+
+def test_make_graph_networkx_preserves_labels() -> None:
+    nx = _require_nx()
+    G = nx.path_graph(3)
+    y = torch.tensor([1, 0, 2], dtype=torch.long)
+    g = tgraphx.make_graph(x=torch.zeros(3, 4), networkx_graph=G, labels=y)
+    assert g.node_labels is not None
+    assert torch.equal(g.node_labels, y)
+
+
+def test_make_graph_networkx_rejects_shape_mismatch() -> None:
+    nx = _require_nx()
+    G = nx.path_graph(3)
+    with pytest.raises(ValueError, match="rows but NetworkX graph"):
+        tgraphx.make_graph(x=torch.zeros(4, 2), networkx_graph=G)
+
+
+# ── Codex TGX-AUDIT-001 / Composer TGX-AUDIT-005: public_api registry  ──────
+
+
+def test_public_api_registry_includes_v141_helpers() -> None:
+    expected = {
+        "classify_nodes",
+        "kg_completion",
+        "make_graph",
+        "generate_graph",
+        "optimize_graph",
+        "train_graph_rl",
+        "audit_package_readiness",
+    }
+    for name in expected:
+        # Should not raise; must report a non-empty stability level.
+        level = tgraphx.api_status(name)
+        assert level, f"api_status({name!r}) returned empty level"
+
+
+def test_public_api_registry_recognizes_v141_aliases() -> None:
+    # `build_graph` is an alias of `make_graph`; api_status must resolve it.
+    level = tgraphx.api_status("build_graph")
+    assert level, "api_status('build_graph') returned empty level"
+    aliases = tgraphx.list_aliases("make_graph")
+    assert "build_graph" in aliases, aliases
+
+
+# ── Codex TGX-AUDIT-003 / Composer TGX-AUDIT-004 / 010: top-level __all__  ──
+
+
+def test_v141_aliases_in_top_level_all() -> None:
+    expected = {
+        "generate", "graph_generation_report", "compare_generated_graphs",
+        "generation_metrics", "graph_evolution", "run_evolution", "run_rl",
+        # Composer TGX-AUDIT-010 additions
+        "KnowledgeGraph", "KGTrainer", "KGTrainingConfig",
+        "run_graph_generation", "run_evolutionary_optimization", "run_graph_rl",
+    }
+    missing = expected.difference(tgraphx.__all__)
+    assert not missing, f"Missing from tgraphx.__all__: {sorted(missing)}"
+
+
+# ── Codex TGX-AUDIT-005: no fake `tgraphx[vision]` extra  ───────────────────
+
+
+def test_optional_dependency_messages_reference_existing_extras() -> None:
+    msg = tgraphx.explain_error("missing optional torchvision")
+    assert "tgraphx[vision]" not in msg, (
+        "explain_error must not suggest a non-existing tgraphx[vision] extra "
+        "(torchvision is a mandatory dependency)."
+    )
+
+
+# ── Codex TGX-AUDIT-009: serialization preserves edge_labels & graph_features
+
+
+def test_graph_save_load_preserves_edge_labels_and_graph_features(tmp_path) -> None:
+    ei = torch.tensor([[0, 1], [1, 2]], dtype=torch.long)
+    g = Graph(
+        node_features=torch.randn(3, 4),
+        edge_index=ei,
+        edge_labels=torch.tensor([7, 9]),
+        graph_features=torch.tensor([1.0, 2.0, 3.0]),
+    )
+    p = tmp_path / "g.tgx"
+    g.save(p)
+    loaded = Graph.load(p)
+    assert torch.equal(loaded.edge_labels, g.edge_labels)
+    assert torch.equal(loaded.graph_features, g.graph_features)
+
+
+def test_graph_save_load_backward_compat_missing_new_fields(tmp_path) -> None:
+    """An old-format payload without the new keys must still load."""
+    from tgraphx.ux.serialization import _payload_to_graph
+
+    payload = {
+        "node_features": torch.zeros(2, 3),
+        "edge_index": torch.tensor([[0], [1]], dtype=torch.long),
+    }
+    g = _payload_to_graph(payload)
+    assert g.num_nodes == 2 and g.num_edges == 1
+    assert g.edge_labels is None
+    assert g.graph_features is None
+
+
+# ── Codex TGX-AUDIT-010: training _unpack_batch with edge_index=None  ───────
+
+
+def test_unpack_batch_raises_clear_error_for_none_edge_index() -> None:
+    from tgraphx.training import _unpack_batch
+    from tgraphx import Graph, GraphBatch
+
+    # Build a batch whose edge_index is None (manually patched after creation).
+    g = Graph(node_features=torch.zeros(3, 4),
+              edge_index=torch.tensor([[0, 1], [1, 2]], dtype=torch.long),
+              y=torch.tensor([0, 1, 0]))
+    batch = GraphBatch([g])
+    batch.edge_index = None
+    with pytest.raises(ValueError, match="edge_index is None"):
+        _unpack_batch(batch, torch.device("cpu"))
+
+
+# ── Codex TGX-AUDIT-011: Graph.num_classes on empty labels  ─────────────────
+
+
+def test_num_classes_empty_labels_returns_zero() -> None:
+    g = Graph(node_features=torch.zeros(0, 4),
+              edge_index=torch.zeros(2, 0, dtype=torch.long),
+              y=torch.zeros(0, dtype=torch.long))
+    assert g.num_classes == 0
+
+
+# ── Codex TGX-AUDIT-012: from_adjacency rejects non-square sparse adjacency
+
+
+def test_from_adjacency_rejects_nonsquare_sparse() -> None:
+    try:
+        import scipy.sparse as sp
+    except ImportError:
+        pytest.skip("scipy not installed")
+    adj = sp.csr_matrix([[1, 0, 0], [0, 1, 0]])  # 2x3, not square
+    with pytest.raises(ValueError, match="square"):
+        Graph.from_adjacency(adj)
+
+
+# ── Codex TGX-AUDIT-013: Graph.to() also moves masks in metadata  ───────────
+
+
+def test_graph_to_moves_masks_in_metadata() -> None:
+    g = Graph(
+        node_features=torch.zeros(3, 4),
+        edge_index=torch.tensor([[0, 1], [1, 2]], dtype=torch.long),
+        metadata={"masks": {"train": torch.tensor([True, False, True])}},
+    )
+    # CPU->CPU is the only universally-available transition; we assert that
+    # Graph.to() touches the mask without raising and the dtype/values stay.
+    g.to(torch.device("cpu"))
+    m = g.train_mask
+    assert m is not None
+    assert m.device.type == "cpu"
+    assert m.tolist() == [True, False, True]
+
+
+# ── Codex TGX-AUDIT-016: train_graph_rl forwards max_steps  ─────────────────
+
+
+def test_train_graph_rl_max_steps_is_recorded() -> None:
+    result = tgraphx.train_graph_rl(
+        env="max_cut",
+        algorithm="random",
+        episodes=2,
+        max_steps=7,
+        num_nodes=6,
+        seed=0,
+        fast_mode=False,
+    )
+    config = getattr(result, "config", None)
+    assert isinstance(config, dict)
+    assert config.get("max_steps") == 7
+
+
+# ── Composer TGX-AUDIT-003: lazy torchvision import  ────────────────────────
+
+
+def test_torchvision_not_imported_eagerly() -> None:
+    code = (
+        "import sys, tgraphx;"
+        "import json; print(json.dumps({"
+        "'torchvision': 'torchvision' in sys.modules,"
+        "'torchvision_models': 'torchvision.models' in sys.modules}))"
+    )
+    out = subprocess.check_output([sys.executable, "-c", code]).decode()
+    last = out.strip().splitlines()[-1]
+    import json
+    info = json.loads(last)
+    assert info["torchvision"] is False, (
+        "`import tgraphx` should not eagerly import torchvision."
+    )
+    assert info["torchvision_models"] is False
+
+
+# ── Composer TGX-AUDIT-007: CLI list-methods regression  ────────────────────
+
+
+def test_cli_list_methods() -> None:
+    res = subprocess.run(
+        [sys.executable, "-m", "tgraphx", "list-methods"],
+        capture_output=True, text=True, timeout=60,
+    )
+    assert res.returncode == 0, f"stderr={res.stderr}"
+    # `list-methods` enumerates graph-generation methods registered by the
+    # generation subsystem. Two stable methods we ship since v0.7 are ER and BA.
+    assert "erdos_renyi" in res.stdout, res.stdout
+    assert "barabasi_albert" in res.stdout, res.stdout
+
+
+# ── Composer TGX-AUDIT-015: readiness dependency classification  ────────────
+
+
+def test_readiness_dependency_classification() -> None:
+    report = tgraphx.audit_package_readiness()
+    assert "required_dependencies" in report
+    # torchvision must be in required, not optional, per pyproject.toml.
+    assert "torchvision" in report["required_dependencies"]
+    assert "torchvision" not in report.get("optional_dependencies", {})