PyAGC: Attributed Graph Clustering Benchmark

• PyAGC is a comprehensive benchmark and library for unsupervised clustering of attributed graphs, emphasizing scalability and realistic industrial applications.
• It standardizes diverse AGC methods under a modular Encode–Cluster–Optimize framework, enabling controlled comparison and rapid prototyping.
• The system advances mini-batch scalability and robust structural evaluation, addressing key limitations of traditional full-batch methods in graph analytics.

Searching arXiv for the PyAGC paper and a few named related AGC methods for supporting citations. PyAGC is a comprehensive, production-ready benchmark and PyTorch-based library for Attributed Graph Clustering (AGC), created to close academia–industry gaps in data realism, scalability, and evaluation (Liu et al., 9 Feb 2026). In this setting, AGC is the unsupervised partitioning of graph nodes into $K$ clusters by leveraging both graph structure $A$ and node attributes $X$. Given an attributed graph $G=(V,E,X)$ with adjacency $A \in \{0,1\}^{N\times N}$ and features $X \in \mathbb{R}^{N\times D}$, PyAGC adopts the formulation in which a mapping $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$ produces a soft assignment matrix $P \in [0,1]^{N\times K}$, where $P_{ik}$ is the probability that node $i$ belongs to cluster $A$0. Its stated purpose is not only to benchmark AGC methods beyond the small, homophilous citation-graph regime, but also to provide memory-efficient, mini-batch implementations and a holistic evaluation protocol that emphasizes unsupervised structural quality and efficiency alongside conventional supervised metrics.

1. Problem formulation and motivating gaps

PyAGC is organized around a diagnosis of three deficiencies in prevailing AGC practice. The first is the “Cora-fication of datasets”: many AGC studies evaluate on small, textual, homophilous citation graphs such as Cora, CiteSeer, and PubMed, even though industrial graphs are large, heterophilous, noisy, and frequently equipped with tabular features rather than sparse text indicators. The second is non-scalable training. Many AGC methods rely on full-batch operations such as full adjacency reconstruction or pairwise contrast, which incur $A$1 memory and time costs and fail on graphs beyond approximately $A$2 nodes. The third is the “supervised metric paradox”: AGC is unlabeled, yet evaluation is often dominated by supervised alignment scores such as ACC, NMI, and ARI, which can encourage agreement with human labels rather than discovery of intrinsic graph communities (Liu et al., 9 Feb 2026).

The industrial motivation is explicit. PyAGC is positioned for fraud ring discovery and anti-money laundering, user segmentation and personalization, and social or web community detection. The corresponding graphs are described as low-homophily, large-scale, and populated by heterogeneous categorical and numeric metadata. This framing is significant because it shifts AGC from a citation-network proxy task toward label-scarce deployment settings in which structural density, separability, and efficiency are first-order constraints. A plausible implication is that PyAGC treats AGC less as a narrowly academic clustering problem and more as an engineering discipline for unsupervised graph analytics under operational constraints.

2. Encode–Cluster–Optimize as the organizing abstraction

PyAGC standardizes AGC methods under a modular Encode-Cluster-Optimize (E-C-O) framework. The encoder stage learns node embeddings

$A$3

The cluster projection stage maps these embeddings to cluster assignments,

$A$4

The optimization stage combines representation learning and clustering objectives,

$A$5

This abstraction is used to align methods that are otherwise heterogeneous in architecture, training objective, and clustering mechanism (Liu et al., 9 Feb 2026).

Within this scheme, PyAGC supports graph autoencoders with feature and structure reconstruction losses,

$A$6

contrastive or self-supervised encoders with InfoNCE-style objectives, and non-parametric encoders based on fixed or adaptive smoothing filters such as SSGC, AGC, and NAFS. Cluster heads include discrete or post-hoc procedures such as KMeans, Spectral, and Subspace/SNEM, as well as differentiable heads such as softmax pooling for MinCut, DMoN, and Neuromap, or prototype-based assignments for DAEGC and DinkNet. PyAGC also states the two-way Normalized Cut objective,

$A$7

and identifies structure-aware objectives including modularity maximization, cut minimization, map equation, and dilation-plus-shrink losses.

The benchmark implements 17 representative algorithms. The categories given are: Traditional methods KMeans and Node2Vec; Non-parametric decoupled methods SSGC, SAGSC, and MS2CAG; Deep decoupled methods GAE, DGI, CCASSG, S3GC, NS4GC, and MAGI; and Deep joint methods DAEGC, DinkNet, MinCut, DMoN, and Neuromap. PyAGC further supports optimized GCN, GraphSAGE, GAT, and GIN encoders, graph transformers such as SGFormer and Polynormer via PyTorch Geometric, GPU-accelerated KMeans, spectral or subspace heads, and differentiable pooling or prototype heads. The importance of this unification is methodological: it enables swapping encoders, cluster heads, and loss terms without changing the surrounding benchmark logic, which makes controlled ablation and cross-method comparison materially easier.

3. Dataset atlas and evaluation protocol

PyAGC curates 12 datasets spanning Tiny to Massive scales, from $A$8 to $A$9 nodes, and explicitly includes industrial graphs with tabular features and low homophily (Liu et al., 9 Feb 2026). The benchmark emphasizes HM, Pokec, and WebTopic as industrial datasets with low homophily and large or dense connectivity profiles.

Dataset	Scale / domain	Key properties
Cora	Tiny / Citation	2,708 nodes; 10,556 edges; 1,433 textual features; $X$0; $X$1; $X$2
Photo	Tiny / Co-purchase	7,650 nodes; 238,162 edges; 745 textual features; $X$3; $X$4; $X$5
Physics	Small / Co-author	34,493 nodes; 495,924 edges; 8,415 textual features; $X$6; $X$7; $X$8
HM	Small / E-commerce, co-purchase; industrial	46,563 nodes; 21,461,990 edges; 120 tabular features; $X$9; Avg. degree 460.9; $G=(V,E,X)$0; $G=(V,E,X)$1
Flickr	Small / Social	89,250 nodes; 899,756 edges; 500 textual features; $G=(V,E,X)$2; $G=(V,E,X)$3; $G=(V,E,X)$4
ArXiv	Medium / Citation	169,343 nodes; 1,166,243 edges; 128 textual features; $G=(V,E,X)$5; $G=(V,E,X)$6; $G=(V,E,X)$7
Reddit	Medium / Social	232,965 nodes; 23,213,838 edges; 602 textual features; $G=(V,E,X)$8; $G=(V,E,X)$9; $A \in \{0,1\}^{N\times N}$0; Avg. degree $A \in \{0,1\}^{N\times N}$1
MAG	Medium / Citation	736,389 nodes; 10,792,672 edges; 128 textual features; $A \in \{0,1\}^{N\times N}$2; $A \in \{0,1\}^{N\times N}$3; $A \in \{0,1\}^{N\times N}$4
Pokec	Large / Social; industrial	1,632,803 nodes; 44,603,928 edges; 56 tabular features; $A \in \{0,1\}^{N\times N}$5; $A \in \{0,1\}^{N\times N}$6; $A \in \{0,1\}^{N\times N}$7
Products	Large / Co-purchase	2,449,029 nodes; 61,859,140 edges; 100 textual features; $A \in \{0,1\}^{N\times N}$8; $A \in \{0,1\}^{N\times N}$9; $X \in \mathbb{R}^{N\times D}$0
WebTopic	Large / Web; industrial	2,890,331 nodes; 24,754,822 edges; 528 tabular features; $X \in \mathbb{R}^{N\times D}$1; $X \in \mathbb{R}^{N\times D}$2; $X \in \mathbb{R}^{N\times D}$3
Papers100M	Massive / Citation	111,059,956 nodes; 1,615,685,872 edges; 128 textual features; $X \in \mathbb{R}^{N\times D}$4; $X \in \mathbb{R}^{N\times D}$5; $X \in \mathbb{R}^{N\times D}$6 on the labeled 1.5M-node subset

The evaluation protocol is explicitly holistic. Supervised metrics are reported but not treated as sufficient. Clustering Accuracy is defined as

$X \in \mathbb{R}^{N\times D}$7

and NMI as

$X \in \mathbb{R}^{N\times D}$8

ARI and Macro-F1 are also reported. PyAGC mandates unsupervised structural metrics: Modularity,

$X \in \mathbb{R}^{N\times D}$9

and average Conductance,

$F:(A,X)\rightarrow \mathbb{R}^{N\times K}$0

Efficiency profiling reports total training plus clustering time and peak GPU memory on a single 32GB V100.

The benchmark’s stance on labels is central. For industrial datasets such as WebTopic, the reported labels are only one semantic view; low ACC or NMI may coexist with high modularity or separability. This directly challenges the common misconception that weak label alignment necessarily implies weak clustering. In PyAGC’s framing, structural quality may be the more relevant signal for fraud detection or community discovery.

4. Mini-batch systems design and scalability

PyAGC’s principal systems contribution is the refactoring of full-batch AGC algorithms into memory-efficient mini-batch variants. It uses neighbor sampling in the GraphSAGE style, subgraph sampling in the GraphSAINT style, and random-walk neighborhoods for contrastive positives in S3GC. The total loss is approximated on sampled subgraphs as

$F:(A,X)\rightarrow \mathbb{R}^{N\times K}$1

thereby decoupling GPU memory from $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$2 while preserving informative neighborhoods (Liu et al., 9 Feb 2026).

The engineering stack also includes GPU-accelerated KMeans implemented with PyTorch and Triton, which is presented as important for $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$3, and mini-batch refactoring of methods such as DAEGC and NS4GC to avoid adjacency-wide $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$4 operations. PyAGC summarizes the resulting complexity contrast as follows: full-batch adjacency reconstruction and all-pairs contrast hit $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$5 bottlenecks, whereas mini-batch variants reduce the footprint roughly to $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$6 per step, with additional sampling overhead $F:(A,X)\rightarrow \mathbb{R}^{N\times K}$7.

The benchmark reports a concrete hardware profile: a single NVIDIA Tesla V100 32GB GPU, Intel Xeon Platinum 8163 CPU, 480GB RAM, and Linux. On Papers100M, deep methods were trained in under approximately two hours on a single V100. The examples given are NS4GC with peak GPU approximately 13.97 GB and time approximately 1.24 h; GAE with peak GPU approximately 7.58 GB and time approximately 0.67 h for one epoch on Papers100M by protocol; DAEGC with peak GPU approximately 15.96 GB and time approximately 1.40 h; and MAGI with peak GPU approximately 29.28 GB and time approximately 6.04 h. For medium and large graphs, the reported figures include Reddit with NS4GC at 10.90 GB and 12.84 m and DAEGC at 31.20 GB and 14.28 m; Products with NS4GC at 24.10 GB and 37.24 m, GAE at 13.33 GB and 26.12 m, and MAGI at 31.08 GB and 375.99 m; and WebTopic with DMoN at 28.27 GB and 6.75 m, Neuromap at 28.27 GB and 4.97 m, and NS4GC at 8.95 GB and 30.75 m.

The practical importance of these numbers is that PyAGC treats single-GPU execution as a design target rather than an afterthought. This suggests that the benchmark is as much about implementation discipline and systems comparability as about clustering methodology.

5. Empirical behavior across homophily regimes

PyAGC reports a sharp contrast between performance in the “academic comfort zone” and performance on industrial graphs. On high-homophily small graphs such as Cora, Photo, and Physics, most methods achieve high supervised scores; one example given is NS4GC with NMI at least 72% on Photo and 75% on Physics. On heterophilous and tabular graphs such as HM, Pokec, and WebTopic, many deep methods’ supervised metrics drop sharply; on Pokec, most deep methods have NMI at most approximately 6%, whereas SAGSC reaches NMI approximately 38.33% (Liu et al., 9 Feb 2026).

Two specific observations structure the paper’s interpretation of these outcomes. First, structural and semantic objectives can diverge. On Products, SAGSC delivers top structural quality, with Modularity approximately 84.56% and Conductance approximately 12.62%, yet lower NMI than NS4GC. The stated conclusion is that ground-truth labels need not coincide with dense communities. Second, methods optimized for structural objectives may remain useful where supervised scores are mediocre. On HM, DMoN attains the best structural quality with Modularity approximately 12.54%, even though its supervised scores are not highlighted as strong. In both cases, structural metrics are presented as revealing utility that label-based metrics may obscure.

PyAGC also draws methodological conclusions about training paradigms. Deep decoupled methods such as NS4GC, MAGI, and S3GC are characterized as robust and consistent across domains, with pretraining mitigating clustering collapse common in joint training. Non-parametric methods such as MS2CAG are described as extremely fast on medium graphs—for example, Reddit at 0.16 min—but not scalable to 100M-plus nodes, whereas mini-batch deep models scale linearly with sampling overhead. The benchmark further states that PyAGC has been battle-tested in workflows for Fraud Detection, Anti-Money Laundering, and User Profiling at Ant Group. This suggests that the observed trade-offs are not merely benchmark artifacts but are tied to deployment-oriented constraints.

6. Software organization, interfaces, and reproducibility

PyAGC is distributed through GitHub, PyPI, and hosted documentation: https://github.com/Cloudy1225/PyAGC, https://pypi.org/project/pyagc, and https://pyagc.readthedocs.io (Liu et al., 9 Feb 2026). Installation is given as pip install pyagc. The software exposes programmatic APIs for dataset loading, encoders, clustering heads, model composition, fitting, clustering, and evaluation, and it also supports configuration-driven execution through YAML files and the CLI command pyagc-run --config benchmark/NS4GC/train.conf.yaml.

The library is organized into core modules. pyagc.encoders includes GCN, GraphSAGE, GAT, GIN, graph transformers, and non-parametric filters. pyagc.clusters includes GPU KMeans, spectral, subspace, SNEM, and differentiable pooling or prototype heads. pyagc.models covers decoupled variants such as GAE, DGI, NS4GC, MAGI, S3GC, and CCASSG, and joint variants such as DAEGC, DinkNet, MinCut, DMoN, and Neuromap. pyagc.eval provides supervised metrics including ACC, NMI, ARI, and F1, structural metrics including Modularity and Conductance, and experiment logging. Dataset loaders provide unified interfaces for Cora, Photo, Physics, HM, Flickr, ArXiv, Reddit, MAG, Pokec, Products, WebTopic, and Papers100M, with on-the-fly neighbor and subgraph samplers.

Reproducibility is YAML-managed. The paper reports means and standard deviations over five runs, and uses a single epoch on Papers100M by design due to size. The license is not specified in the paper text; the stated guidance is to consult the GitHub repository for the current license. From an encyclopedic standpoint, PyAGC’s reproducibility model is notable because it links benchmark specification, hardware assumptions, hyperparameter control, and evaluation reporting in one software surface.

7. Limitations, open problems, and nomenclature

PyAGC identifies several unresolved issues. Metric coverage remains incomplete: Modularity and Conductance are mandated, while other structure-aware metrics such as map equation code length, density-based measures, and multi-way Normalized Cut are described as possible expansions. Domain coverage is broad but does not include biological PPI-scale clustering or bipartite industrial settings beyond those in GraphLand. Industrial label scarcity remains a model-selection problem: reliable unsupervised model selection criteria are still open. The paper also notes that many GNN encoders still over-smooth on heterophilous graphs and struggle with tabular features, and that additional acceleration such as multi-GPU sampling, fused kernels, and richer profiling could be added. The benchmark reports time and peak memory, but not GPU utilization percentages (Liu et al., 9 Feb 2026).

A likely source of confusion is nomenclature. PyAGC denotes the attributed-graph-clustering benchmark and library described above. It should not be conflated with the similarly named PyTorch implementation sketch “PyAGGC” associated with “Adaptive Group-wise Gradient Clipping” for stabilizing LLM training, which is a distinct system concerned with functional group partitioning of model parameters, EMA-based regulation of gradient norms, and post-training pipelines for models such as LLaMA 2-7B, Mistral-7B, and Gemma-7B rather than graph clustering (Li et al., 17 Jan 2026). This suggests that the near-homonym reflects naming similarity rather than technical overlap.

In aggregate, PyAGC’s significance lies in its attempt to redefine AGC benchmarking around realistic graphs, mini-batch scalability, and structural evaluation. Rather than assuming that homophilous citation networks and label-alignment metrics are adequate proxies for practice, it formalizes a broader view in which clustering quality, system efficiency, and deployment realism are evaluated together.