tgraphx 0.4.3__tar.gz → 0.4.4__tar.gz

{tgraphx-0.4.3 → tgraphx-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tgraphx
-Version: 0.4.3
+Version: 0.4.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-0.4.3 → tgraphx-0.4.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 = "0.4.3"
+version = "0.4.4"
 description = "Tensor-aware graph neural networks preserving spatial node feature layouts"
 readme = "README.md"
 requires-python = ">=3.10"

tgraphx-0.4.4/tests/test_matching_coloring_flow.py

@@ -0,0 +1,178 @@
+"""Tests for matching, coloring, clique, and max-flow algorithms."""
+import pytest
+import torch
+from tgraphx.mining import (
+    greedy_maximal_matching,
+    bipartite_greedy_matching,
+    greedy_coloring,
+    welsh_powell_coloring,
+    greedy_maximal_independent_set,
+    enumerate_maximal_cliques,
+    edmonds_karp_max_flow,
+    min_cut_from_max_flow,
+    wl_isomorphism_test,
+    write_algorithm_report,
+)
+
+
+def _chain(N=4):
+    src = list(range(N-1)) + list(range(1, N))
+    dst = list(range(1, N)) + list(range(N-1))
+    return torch.tensor([src, dst], dtype=torch.long), N
+
+
+def _triangle():
+    return torch.tensor([[0,1,2,1,2,0],[1,2,0,0,1,2]], dtype=torch.long), 3
+
+
+class TestMatching:
+    def test_maximal_matching_chain(self):
+        ei, N = _chain()
+        m = greedy_maximal_matching(ei, N)
+        assert m.size(0) == 2
+        # Each node appears at most once.
+        all_nodes = m.flatten().tolist()
+        assert len(set(all_nodes)) == len(all_nodes)
+
+    def test_maximal_matching_empty(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        m = greedy_maximal_matching(ei, 4)
+        assert m.shape == (2, 0)
+
+    def test_bipartite_matching(self):
+        # Left: 0,1; Right: 2,3; edges: 0-2, 0-3, 1-2
+        ei = torch.tensor([[0, 0, 1], [2, 3, 2]], dtype=torch.long)
+        m = bipartite_greedy_matching(ei, num_nodes_left=2, num_nodes_right=2)
+        assert m.size(0) == 2
+        # At most 2 pairs.
+        assert m.size(1) <= 2
+
+
+class TestColoring:
+    def test_greedy_chain_valid(self):
+        ei, N = _chain()
+        colors, nc = greedy_coloring(ei, N)
+        # Valid coloring: no adjacent nodes have same color.
+        src, dst = ei[0].tolist(), ei[1].tolist()
+        for u, v in zip(src, dst):
+            assert colors[u].item() != colors[v].item(), f"Conflict at ({u},{v})"
+
+    def test_greedy_triangle_three_colors_max(self):
+        ei, N = _triangle()
+        colors, nc = greedy_coloring(ei, N)
+        # Triangle needs exactly 3 colors.
+        assert nc <= 3
+        src, dst = ei[0].tolist(), ei[1].tolist()
+        for u, v in zip(src, dst):
+            assert colors[u].item() != colors[v].item()
+
+    def test_welsh_powell_valid(self):
+        ei, N = _chain()
+        colors, nc = welsh_powell_coloring(ei, N)
+        src, dst = ei[0].tolist(), ei[1].tolist()
+        for u, v in zip(src, dst):
+            assert colors[u].item() != colors[v].item()
+
+    def test_empty_graph_one_color(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        colors, nc = greedy_coloring(ei, 5)
+        assert nc == 1  # all nodes get color 0
+        assert colors.tolist() == [0, 0, 0, 0, 0]
+
+
+class TestClique:
+    def test_independent_set_chain(self):
+        ei, N = _chain()
+        ind_set = greedy_maximal_independent_set(ei, N, seed=0)
+        # Valid independent set: no two adjacent members.
+        adj = set(zip(ei[0].tolist(), ei[1].tolist()))
+        members = set(ind_set.tolist())
+        for u in members:
+            for v in members:
+                assert (u, v) not in adj or u == v
+
+    def test_independent_set_triangle_size_one(self):
+        ei, N = _triangle()
+        ind_set = greedy_maximal_independent_set(ei, N, seed=0)
+        assert ind_set.size(0) == 1  # can't pick more than 1 from triangle
+
+    def test_enumerate_maximal_cliques_triangle(self):
+        ei, N = _triangle()
+        cliques = enumerate_maximal_cliques(ei, N)
+        # K3 has exactly one maximal clique: {0,1,2}.
+        assert len(cliques) == 1
+        assert cliques[0] == frozenset({0, 1, 2})
+
+    def test_enumerate_maximal_cliques_chain(self):
+        ei, N = _chain()
+        cliques = enumerate_maximal_cliques(ei, N)
+        # Chain: 0-1-2-3 → maximal cliques are edges: {0,1},{1,2},{2,3}.
+        assert len(cliques) == 3
+
+    def test_clique_enumeration_size_guard(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        with pytest.raises(ValueError, match="max_nodes"):
+            enumerate_maximal_cliques(ei, 51, max_nodes=50)
+
+
+class TestMaxFlow:
+    def test_simple_flow(self):
+        # 0 → 1 (cap 3), 0 → 2 (cap 2), 1 → 3 (cap 2), 2 → 3 (cap 3)
+        ei = torch.tensor([[0, 0, 1, 2], [1, 2, 3, 3]], dtype=torch.long)
+        cap = torch.tensor([3.0, 2.0, 2.0, 3.0])
+        flow, _ = edmonds_karp_max_flow(ei, 4, cap, 0, 3)
+        # Max flow = 4 (3+2 paths capped by sink capacities 2+3).
+        # Actually: path 0→1→3 (cap=2), path 0→2→3 (cap=2) → flow=4.
+        assert abs(flow - 4.0) < 1e-6
+
+    def test_max_flow_min_cut(self):
+        ei = torch.tensor([[0, 0, 1, 2], [1, 2, 3, 3]], dtype=torch.long)
+        cap = torch.tensor([3.0, 2.0, 2.0, 3.0])
+        flow, S, T = min_cut_from_max_flow(ei, 4, cap, 0, 3)
+        assert 0 in S and 3 in T
+        assert abs(flow - 4.0) < 1e-6
+
+    def test_negative_capacity_raises(self):
+        ei = torch.tensor([[0], [1]], dtype=torch.long)
+        cap = torch.tensor([-1.0])
+        with pytest.raises(ValueError, match="non-negative"):
+            edmonds_karp_max_flow(ei, 2, cap, 0, 1)
+
+    def test_disconnected_source_sink(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        cap = torch.zeros(0)
+        flow, _ = edmonds_karp_max_flow(ei, 3, cap, 0, 2)
+        assert flow == 0.0
+
+    def test_size_guard(self):
+        ei = torch.zeros((2, 0), dtype=torch.long)
+        cap = torch.zeros(0)
+        with pytest.raises(ValueError, match="num_nodes"):
+            edmonds_karp_max_flow(ei, 501, cap, 0, 499)
+
+
+class TestWLIsomorphism:
+    def test_identical_graphs(self):
+        ei, N = _triangle()
+        assert wl_isomorphism_test(ei, N, ei, N) is True
+
+    def test_different_sizes(self):
+        ei3, N3 = _triangle()
+        ei4, N4 = _chain(5)
+        assert wl_isomorphism_test(ei3, N3, ei4, N4) is False
+
+    def test_non_isomorphic_same_size(self):
+        # Path 4 vs Cycle 4.
+        ei_path, _ = _chain(4)
+        ei_cycle = torch.tensor([[0,1,2,3,1,2,3,0],[1,2,3,0,0,1,2,3]], dtype=torch.long)
+        # WL should distinguish these.
+        result = wl_isomorphism_test(ei_path, 4, ei_cycle, 4, num_iterations=3)
+        # Note: WL may or may not distinguish some graphs. Accept any bool.
+        assert isinstance(result, bool)
+
+    def test_write_algorithm_report(self, tmp_path):
+        p = write_algorithm_report(str(tmp_path / "algo.json"),
+                                   "greedy_coloring", num_colors=3)
+        import json; d = json.loads(open(p).read())
+        assert d["algorithm"] == "greedy_coloring"
+        assert d["num_colors"] == 3

tgraphx-0.4.4/tests/test_node2vec_kg_hypergraph.py

@@ -0,0 +1,285 @@
+"""Tests for Node2Vec, Knowledge Graph, Hypergraph, and Graph IO."""
+import json
+import os
+import tempfile
+
+import pytest
+import torch
+
+from tgraphx.mining import (
+    # Node2Vec
+    node2vec_walks, deepwalk_walks, generate_skipgram_pairs,
+    Node2VecEmbedding, train_node2vec_step, extract_node2vec_embeddings,
+    # KG
+    KnowledgeGraph, negative_triple_sampling, filtered_ranking_metrics,
+    TransE, DistMult, train_kg_step,
+    # Hypergraph
+    Hypergraph, incidence_to_bipartite_graph, clique_expansion,
+    star_expansion, hypergraph_density,
+    # IO
+    read_graph_json, write_graph_json, write_edge_list_csv, read_edge_list_csv,
+    save_graph_npz, load_graph_npz,
+)
+
+
+def _chain_ei(N=4):
+    src = list(range(N-1)) + list(range(1, N))
+    dst = list(range(1, N)) + list(range(N-1))
+    return torch.tensor([src, dst], dtype=torch.long), N
+
+
+class TestNode2Vec:
+    def test_walks_shape(self):
+        ei, N = _chain_ei()
+        walks = node2vec_walks(ei, N, walk_length=5, walks_per_node=3, seed=0)
+        assert walks.shape == (N * 3, 6)  # walk_length + 1
+
+    def test_walks_deterministic(self):
+        ei, N = _chain_ei()
+        w1 = node2vec_walks(ei, N, walk_length=5, walks_per_node=2, seed=7)
+        w2 = node2vec_walks(ei, N, walk_length=5, walks_per_node=2, seed=7)
+        assert torch.equal(w1, w2)
+
+    def test_walks_valid_nodes(self):
+        ei, N = _chain_ei()
+        walks = node2vec_walks(ei, N, walk_length=10, walks_per_node=5, seed=0)
+        assert ((walks >= 0) & (walks < N)).all()
+
+    def test_deepwalk_is_p1_q1(self):
+        ei, N = _chain_ei()
+        dw = deepwalk_walks(ei, N, walk_length=5, walks_per_node=2, seed=0)
+        n2v = node2vec_walks(ei, N, walk_length=5, walks_per_node=2, p=1.0, q=1.0, seed=0)
+        assert torch.equal(dw, n2v)
+
+    def test_biased_walks_different_from_uniform(self):
+        ei = torch.tensor([[0,0,0,0,0],[1,2,3,4,5]], dtype=torch.long)
+        N = 6
+        uniform = node2vec_walks(ei, N, walk_length=10, walks_per_node=5, p=1.0, q=1.0, seed=0)
+        biased = node2vec_walks(ei, N, walk_length=10, walks_per_node=5, p=0.5, q=2.0, seed=0)
+        # They should differ at some point (not guaranteed, but very likely for this graph).
+        # Just verify both are valid.
+        assert ((uniform >= 0) & (uniform < N)).all()
+        assert ((biased >= 0) & (biased < N)).all()
+
+    def test_skipgram_pairs(self):
+        ei, N = _chain_ei()
+        walks = node2vec_walks(ei, N, walk_length=5, walks_per_node=2, seed=0)
+        centers, contexts, negatives = generate_skipgram_pairs(walks, window_size=2, negative_ratio=3, num_nodes=N, seed=0)
+        assert centers.size(0) == contexts.size(0)
+        assert negatives.size(0) == centers.size(0) * 3
+
+    def test_node2vec_embedding_forward(self):
+        model = Node2VecEmbedding(num_nodes=10, embedding_dim=8)
+        centers = torch.randint(10, (4,))
+        contexts = torch.randint(10, (4,))
+        negatives = torch.randint(10, (8,))
+        loss = model(centers, contexts, negatives)
+        assert torch.isfinite(loss)
+
+    def test_node2vec_embedding_backward(self):
+        model = Node2VecEmbedding(num_nodes=10, embedding_dim=8)
+        opt = torch.optim.Adam(model.parameters(), lr=1e-2)
+        centers = torch.randint(10, (4,))
+        contexts = torch.randint(10, (4,))
+        negatives = torch.randint(10, (8,))
+        loss_val = train_node2vec_step(model, opt, centers, contexts, negatives)
+        assert isinstance(loss_val, float) and loss_val >= 0
+
+    def test_node2vec_loss_decreases(self):
+        torch.manual_seed(0)
+        ei, N = _chain_ei(8)
+        # Generate many walks to create reliable pairs.
+        walks = node2vec_walks(ei, N, walk_length=10, walks_per_node=20, seed=0)
+        centers, contexts, negatives = generate_skipgram_pairs(
+            walks, window_size=3, negative_ratio=5, num_nodes=N, seed=0,
+        )
+        model = Node2VecEmbedding(num_nodes=N, embedding_dim=16)
+        opt = torch.optim.Adam(model.parameters(), lr=0.02)
+        losses = []
+        for _ in range(10):
+            losses.append(train_node2vec_step(model, opt, centers, contexts, negatives))
+        assert losses[-1] < losses[0], f"Loss did not decrease: {losses[0]:.4f}→{losses[-1]:.4f}"
+
+    def test_extract_embeddings_shape(self):
+        model = Node2VecEmbedding(num_nodes=5, embedding_dim=8)
+        emb = extract_node2vec_embeddings(model)
+        assert emb.shape == (5, 8)
+        assert not emb.requires_grad
+
+
+class TestKnowledgeGraph:
+    def _kg(self):
+        triples = torch.tensor([[0,0,1],[1,0,2],[0,1,2],[2,0,0]], dtype=torch.long)
+        return KnowledgeGraph(triples)
+
+    def test_kg_creation(self):
+        kg = self._kg()
+        assert kg.num_entities == 3
+        assert kg.num_relations == 2
+        assert len(kg) == 4
+
+    def test_kg_positive_lookup(self):
+        kg = self._kg()
+        assert kg.is_positive(0, 0, 1)
+        assert not kg.is_positive(0, 0, 2)
+
+    def test_kg_split(self):
+        triples = torch.tensor([[i, 0, (i+1) % 10] for i in range(20)], dtype=torch.long)
+        kg = KnowledgeGraph(triples)
+        train, val, test = kg.train_val_test_split(ratios=(0.7, 0.15, 0.15), seed=0)
+        assert len(train) + len(val) + len(test) == 20
+
+    def test_negative_sampling_valid(self):
+        triples = torch.tensor([[0,0,1],[1,0,2]], dtype=torch.long)
+        neg = negative_triple_sampling(triples, num_entities=3, num_neg=2, seed=0)
+        assert neg.shape == (4, 3)
+        # Relations must match.
+        assert (neg[:, 1] == triples.repeat_interleave(2, dim=0)[:, 1]).all()
+
+    def test_transe_forward_backward(self):
+        kg = self._kg()
+        model = TransE(kg.num_entities, kg.num_relations, embedding_dim=8)
+        triples = kg.triples
+        neg = negative_triple_sampling(triples, kg.num_entities, seed=0)
+        opt = torch.optim.Adam(model.parameters(), lr=1e-2)
+        loss = train_kg_step(model, opt, triples, neg)
+        assert isinstance(loss, float) and loss >= 0
+
+    def test_transe_loss_decreases(self):
+        torch.manual_seed(0)
+        triples = torch.tensor([[i, 0, (i+1) % 8] for i in range(8)], dtype=torch.long)
+        kg = KnowledgeGraph(triples)
+        model = TransE(kg.num_entities, kg.num_relations, embedding_dim=16, margin=1.0)
+        opt = torch.optim.Adam(model.parameters(), lr=5e-3)
+        losses = []
+        for _ in range(20):
+            neg = negative_triple_sampling(triples, kg.num_entities, num_neg=2, seed=0)
+            losses.append(train_kg_step(model, opt, triples, neg[:8]))
+        assert losses[-1] < losses[0], f"Loss did not decrease: {losses[0]:.4f}→{losses[-1]:.4f}"
+
+    def test_distmult_forward_backward(self):
+        kg = self._kg()
+        model = DistMult(kg.num_entities, kg.num_relations, embedding_dim=8)
+        neg = negative_triple_sampling(kg.triples, kg.num_entities, seed=1)
+        opt = torch.optim.Adam(model.parameters(), lr=1e-2)
+        loss = train_kg_step(model, opt, kg.triples, neg)
+        assert isinstance(loss, float) and loss >= 0
+
+    def test_transe_score_shape(self):
+        model = TransE(5, 3, embedding_dim=8)
+        h = torch.tensor([0, 1, 2])
+        r = torch.tensor([0, 0, 1])
+        t = torch.tensor([1, 2, 3])
+        scores = model.score(h, r, t)
+        assert scores.shape == (3,)
+        assert torch.isfinite(scores).all()
+
+    def test_filtered_ranking_metrics(self):
+        torch.manual_seed(0)
+        triples = torch.tensor([[0,0,1],[1,0,2],[2,0,0]], dtype=torch.long)
+        kg = KnowledgeGraph(triples)
+        model = TransE(kg.num_entities, kg.num_relations, embedding_dim=8)
+        # Just run and check return format.
+        all_set = kg._positive_set
+        metrics = filtered_ranking_metrics(model, triples[:2], all_set, kg.num_entities)
+        assert "mrr" in metrics and "hits@1" in metrics and "hits@10" in metrics
+        assert 0 <= metrics["mrr"] <= 1
+
+
+class TestHypergraph:
+    def test_creation(self):
+        hg = Hypergraph(5, [[0,1,2],[2,3,4],[0,4]])
+        assert hg.num_nodes == 5
+        assert hg.num_hyperedges == 3
+
+    def test_node_hyperdegree(self):
+        hg = Hypergraph(5, [[0,1],[1,2],[0,2]])
+        deg = hg.node_hyperdegree()
+        assert int(deg[0]) == 2  # node 0 appears in 2 hyperedges
+        assert int(deg[1]) == 2
+        assert int(deg[3]) == 0  # isolated node
+
+    def test_hyperedge_degree(self):
+        hg = Hypergraph(4, [[0,1],[1,2,3]])
+        edge_deg = hg.hyperedge_degree()
+        assert edge_deg.tolist() == [2, 3]
+
+    def test_density(self):
+        hg = Hypergraph(4, [[0,1,2,3]])  # all nodes in one hyperedge → density 1
+        assert abs(hg.density() - 1.0) < 1e-6
+
+    def test_density_empty(self):
+        hg = Hypergraph(4, [[]])
+        assert hg.density() == 0.0
+
+    def test_incidence_to_bipartite(self):
+        hg = Hypergraph(3, [[0,1],[1,2]])
+        bi_ei, total = incidence_to_bipartite_graph(hg)
+        assert total == 5  # 3 original + 2 hyperedge nodes
+        assert bi_ei.shape[0] == 2
+
+    def test_clique_expansion(self):
+        hg = Hypergraph(3, [[0,1,2]])
+        ei, N = clique_expansion(hg)
+        assert N == 3
+        # K3 = 6 directed edges
+        assert ei.size(1) == 6
+
+    def test_star_expansion(self):
+        hg = Hypergraph(3, [[0,1,2]])
+        ei, N = star_expansion(hg)
+        assert N == 4  # 3 + 1 hyperedge node
+        assert ei.size(1) == 6  # 3 undirected connections × 2 directions
+
+    def test_invalid_node(self):
+        with pytest.raises(ValueError):
+            Hypergraph(3, [[0, 5]])  # node 5 >= 3
+
+    def test_summary(self):
+        hg = Hypergraph(5, [[0,1,2],[2,3,4]])
+        s = hg.summary()
+        assert s["num_nodes"] == 5
+        assert s["num_hyperedges"] == 2
+        import json; json.dumps(s)  # must be JSON-serializable
+
+
+class TestGraphIO:
+    def test_write_read_json_roundtrip(self, tmp_path):
+        ei = torch.tensor([[0,1,2],[1,2,3]], dtype=torch.long)
+        ew = torch.tensor([1.0, 2.0, 3.0])
+        p = write_graph_json(str(tmp_path / "g.json"), ei, 4, edge_weight=ew, metadata={"test": True})
+        result = read_graph_json(p)
+        assert torch.equal(result["edge_index"], ei)
+        assert result["num_nodes"] == 4
+        assert result["metadata"]["test"] is True
+
+    def test_write_read_csv_roundtrip(self, tmp_path):
+        ei = torch.tensor([[0,1,2],[1,2,3]], dtype=torch.long)
+        ew = torch.tensor([0.5, 1.5, 2.5])
+        p = write_edge_list_csv(str(tmp_path / "edges.csv"), ei, edge_weight=ew, header=["src","dst","w"])
+        new_ei, N, new_ew = read_edge_list_csv(p, has_header=True, weight_col=2)
+        assert new_ei.size(1) == 3
+        assert new_ew is not None
+
+    def test_csv_missing_file(self):
+        with pytest.raises(FileNotFoundError):
+            read_edge_list_csv("/nonexistent/path.csv")
+
+    def test_json_missing_file(self):
+        with pytest.raises(FileNotFoundError):
+            read_graph_json("/nonexistent/path.json")
+
+    def test_write_read_npz_roundtrip(self, tmp_path):
+        pytest.importorskip("numpy")
+        ei = torch.tensor([[0,1],[1,2]], dtype=torch.long)
+        x = torch.randn(3, 4)
+        p = save_graph_npz(str(tmp_path / "g.npz"), ei, 3, node_features=x)
+        result = load_graph_npz(p)
+        assert torch.equal(result["edge_index"], ei)
+        assert result["num_nodes"] == 3
+        assert result["node_features"].shape == (3, 4)
+
+    def test_npz_missing_file(self):
+        pytest.importorskip("numpy")
+        with pytest.raises(FileNotFoundError):
+            load_graph_npz("/nonexistent/path.npz")

{tgraphx-0.4.3 → tgraphx-0.4.4}/tgraphx/__init__.py

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

{tgraphx-0.4.3 → tgraphx-0.4.4}/tgraphx/mining/__init__.py

@@ -280,6 +280,59 @@ from .sequence_models import (
     pad_sequences,
 )
 
+# ── Matching, coloring, clique, max-flow (Beta/Experimental) ─────────────────
+from .matching_coloring import (
+    greedy_maximal_matching,
+    bipartite_greedy_matching,
+    greedy_coloring,
+    welsh_powell_coloring,
+    greedy_maximal_independent_set,
+    enumerate_maximal_cliques,
+    edmonds_karp_max_flow,
+    min_cut_from_max_flow,
+    wl_isomorphism_test,
+    write_algorithm_report,
+)
+
+# ── Node2Vec / DeepWalk (Experimental) ───────────────────────────────────────
+from .node2vec import (
+    node2vec_walks,
+    deepwalk_walks,
+    generate_skipgram_pairs,
+    Node2VecEmbedding,
+    train_node2vec_step,
+    extract_node2vec_embeddings,
+)
+
+# ── Knowledge graphs (Experimental) ─────────────────────────────────────────
+from .knowledge_graph import (
+    KnowledgeGraph,
+    negative_triple_sampling,
+    filtered_ranking_metrics,
+    TransE,
+    DistMult,
+    train_kg_step,
+)
+
+# ── Hypergraphs (Experimental) ───────────────────────────────────────────────
+from .hypergraph import (
+    Hypergraph,
+    incidence_to_bipartite_graph,
+    clique_expansion,
+    star_expansion,
+    hypergraph_density,
+)
+
+# ── Graph IO (Beta) ───────────────────────────────────────────────────────────
+from .graph_io import (
+    read_edge_list_csv,
+    write_edge_list_csv,
+    read_graph_json,
+    write_graph_json,
+    save_graph_npz,
+    load_graph_npz,
+)
+
 # ── Neural mining (Experimental) ─────────────────────────────────────────────
 from .neural import (
     PrototypeMembershipScorer,