mandala-gnn 0.1.0

A native Graph Neural Network & Knowledge Graph Analytics library with scientific journal-backed algorithms.

Mandala-GNN

Native Graph Neural Network & Knowledge Graph Analytics Library

Mandala-GNN is a lightweight, pure-Python library for building knowledge graphs and running graph neural network computations without PyTorch or TensorFlow. All algorithms are implemented natively in NumPy/SciPy and backed by 35+ peer-reviewed scientific publications.

---

✨ Features

Category	Algorithms
GNN Layers	GCN, GAT, GATv2, GraphSAGE, GIN — all pure NumPy
Graph Analytics	PageRank, Betweenness, Closeness, HITS, Katz, Eigenvector centrality
Community Detection	Louvain, Label Propagation, Modularity
Similarity	Cosine, Jaccard, Adamic-Adar, Preferential Attachment, Resource Allocation
Evaluation	Accuracy, F1, AUC-ROC, AUC-PR, MCC, MRR, Hits@K, NDCG, Silhouette, R²
Embeddings	Laplacian Eigenmaps, Adjacency Spectral, Fiedler Vector
ML	K-Means + validation, Logistic Regression + CV, Link Prediction
Pathfinding	Dijkstra shortest path, all paths, topological ordering

---

📦 Installation

pip install mandala-gnn

Dependencies: Only networkx, numpy, scipy, scikit-learn. No heavy ML frameworks required.

---

🚀 Quick Start

1. Knowledge Graph

from mandala_gnn import MandalaGraph, Pathfinder

graph = MandalaGraph()
graph.add_node("algebra", content="Linear Algebra")
graph.add_node("calculus", content="Differential Calculus")
graph.add_node("ml", content="Machine Learning")

graph.add_edge("algebra", "ml")
graph.add_edge("calculus", "ml")

pf = Pathfinder(graph)
print(pf.shortest_path("algebra", "ml"))      # ['algebra', 'ml']
print(pf.ordered_prerequisites("ml"))          # ['algebra', 'calculus', 'ml']

2. Native GNN — Node Classification

from mandala_gnn import GCN
import numpy as np

# Adjacency matrix and features
A = np.array([[0,1,1,0], [1,0,1,0], [1,1,0,1], [0,0,1,0]])
X = np.random.randn(4, 8)   # 4 nodes × 8 features
y = np.array([0, 0, 1, 1])  # binary labels

gcn = GCN(in_features=8, hidden=16, n_classes=2)
gcn.fit(A, X, y, epochs=100)
predictions = gcn.predict(A, X)
print(predictions)  # [0, 0, 1, 1]

3. Graph Analytics

from mandala_gnn import CentralityAnalyzer, CommunityDetector, GraphMetrics

analyzer = CentralityAnalyzer(graph)
print(analyzer.pagerank())      # PageRank scores
print(analyzer.betweenness())   # Betweenness centrality

detector = CommunityDetector(graph)
communities = detector.louvain()
print(detector.modularity(communities))

metrics = GraphMetrics(graph)
print(metrics.summary())  # density, clustering coeff, etc.

4. Evaluation Metrics

from mandala_gnn import ClassificationMetrics, RankingMetrics

# Classification
y_true = [1, 0, 1, 1, 0]
y_pred = [1, 0, 0, 1, 0]
print(ClassificationMetrics.f1_score(y_true, y_pred))
print(ClassificationMetrics.auc_roc(y_true, [0.9, 0.1, 0.4, 0.8, 0.2]))

# Ranking (for link prediction / KG)
ranks = [1, 3, 2, 10, 1]
print(RankingMetrics.mean_reciprocal_rank(ranks))
print(RankingMetrics.hits_at_k(ranks, k=3))

5. Spectral Embeddings

from mandala_gnn import SpectralEmbedder

embedder = SpectralEmbedder(n_components=3)
embeddings, node_ids = embedder.fit_transform(graph, method="laplacian")
# embeddings.shape => (n_nodes, 3)

6. Link Prediction

from mandala_gnn import LinkPredictor

lp = LinkPredictor(graph)
lp.fit()
top_predictions = lp.predict_top_k(k=5)
for src, tgt, prob in top_predictions:
    print(f"{src} → {tgt}  (prob: {prob:.3f})")

---

🏗️ Architecture

mandala_gnn/
├── core/
│   ├── graph.py              # MandalaGraph — NetworkX DiGraph wrapper
│   └── pathfinder.py         # Dijkstra, topological sort
├── nn/                       # Native GNN (pure NumPy)
│   ├── conv.py               # GCNConv, GATConv, GATv2Conv, SAGEConv, GINConv
│   ├── pool.py               # GlobalMean/Max/Sum/Attention Pooling
│   ├── models.py             # Pre-built GCN, GAT, GraphSAGE, GIN models
│   └── functional.py         # Activations, normalization primitives
├── analytics/
│   ├── centrality.py         # PageRank, Betweenness, Closeness, HITS, Katz
│   ├── community.py          # Louvain, Label Propagation, Modularity
│   ├── similarity.py         # Cosine, Jaccard, Adamic-Adar, Pref. Attachment
│   └── metrics.py            # Density, Clustering Coeff., Assortativity
├── evaluation/
│   ├── classification.py     # Accuracy, Precision, Recall, F1, AUC-ROC, MCC
│   ├── ranking.py            # MRR, Hits@K, NDCG, MAP
│   ├── clustering_metrics.py # Silhouette, Davies-Bouldin, NMI, ARI
│   └── regression_metrics.py # MSE, RMSE, MAE, R², MAPE
├── ml/
│   ├── clustering.py         # K-Means + validation metrics
│   ├── regression.py         # Logistic Regression + cross-validation
│   └── link_prediction.py    # Structural link prediction
└── embed/
    └── spectral.py           # Laplacian Eigenmaps, Spectral Embedding

---

📚 Scientific References

All algorithms in this library are backed by peer-reviewed publications. Each function's docstring includes the relevant formula and citation.

Graph Neural Networks

Algorithm	Paper	Year	Link
GCN	Kipf & Welling. "Semi-Supervised Classification with Graph Convolutional Networks." ICLR.	2017	arXiv:1609.02907
GAT	Veličković et al. "Graph Attention Networks." ICLR.	2018	arXiv:1710.10903
GATv2	Brody et al. "How Attentive are Graph Attention Networks?" ICLR.	2022	arXiv:2105.14491
GraphSAGE	Hamilton et al. "Inductive Representation Learning on Large Graphs." NeurIPS.	2017	arXiv:1706.02216
GIN	Xu et al. "How Powerful are Graph Neural Networks?" ICLR.	2019	arXiv:1810.00826
MPNN	Gilmer et al. "Neural Message Passing for Quantum Chemistry." ICML.	2017	arXiv:1704.01212
GPS	Rampášek et al. "Recipe for a General, Powerful, Scalable Graph Transformer." NeurIPS.	2022	arXiv:2205.12454
SignNet	Lim et al. "Sign and Basis Invariant Networks for Spectral Graph Representation Learning." ICLR.	2023	arXiv:2202.13013

Centrality Measures

Algorithm	Paper	Year	Link
PageRank	Brin & Page. "The anatomy of a large-scale hypertextual web search engine." Computer Networks.	1998	DOI:10.1016/S0169-7552(98)00110-X
Betweenness	Freeman. "A set of measures of centrality based on betweenness." Sociometry.	1977	DOI:10.2307/3033543
Closeness	Bavelas. "Communication patterns in task-oriented groups." JASA.	1950	DOI:10.1121/1.1906679
Eigenvector	Bonacich. "Power and centrality: A family of measures." AJS.	1987	DOI:10.1086/228631
HITS	Kleinberg. "Authoritative sources in a hyperlinked environment." JACM.	1999	DOI:10.1145/324133.324140
Katz	Katz. "A new status index derived from sociometric analysis." Psychometrika.	1953	DOI:10.1007/BF02289026

Community Detection

Algorithm	Paper	Year	Link
Louvain	Blondel et al. "Fast unfolding of communities in large networks." JSTAT.	2008	DOI:10.1088/1742-5468/2008/10/P10008
Label Propagation	Raghavan et al. "Near linear time algorithm to detect community structures." Phys. Rev. E.	2007	DOI:10.1103/PhysRevE.76.036106
Modularity	Newman & Girvan. "Finding and evaluating community structure in networks." Phys. Rev. E.	2004	DOI:10.1103/PhysRevE.69.026113

Similarity & Link Prediction

Algorithm	Paper	Year	Link
Cosine Similarity	Salton & McGill. Introduction to Modern Information Retrieval. McGraw-Hill.	1983	ISBN:0070544840
Jaccard Index	Jaccard. "Étude comparative de la distribution florale." Bull. Soc. Vaud. Sci. Nat.	1901	DOI:10.5169/seals-266450
Adamic-Adar	Adamic & Adar. "Friends and neighbors on the Web." Social Networks.	2003	DOI:10.1016/S0378-8733(03)00009-1
Pref. Attachment	Barabási & Albert. "Emergence of scaling in random networks." Science.	1999	DOI:10.1126/science.286.5439.509
Resource Allocation	Zhou et al. "Predicting missing links via local information." EPJ B.	2009	DOI:10.1140/epjb/e2009-00335-8
Link Prediction	Liben-Nowell & Kleinberg. "The link-prediction problem for social networks." JASIST.	2007	DOI:10.1002/asi.20591

Evaluation Metrics

Metric	Paper	Year	Link
Silhouette	Rousseeuw. "Silhouettes: interpretation and validation of cluster analysis." JCAM.	1987	DOI:10.1016/0377-0427(87)90125-7
Davies-Bouldin	Davies & Bouldin. "A cluster separation measure." IEEE TPAMI.	1979	DOI:10.1109/TPAMI.1979.4766909
Calinski-Harabasz	Caliński & Harabasz. "A dendrite method for cluster analysis." Comm. in Statistics.	1974	DOI:10.1080/03610927408827101
AUC-ROC	Hanley & McNeil. "The meaning and use of the area under a ROC curve." Radiology.	1982	DOI:10.1148/radiology.143.1.7063747
F1 Score	Van Rijsbergen. Information Retrieval. Butterworths.	1979	ISBN:0408709294
MCC	Matthews. "Comparison of predicted and observed secondary structure." BBA.	1975	DOI:10.1016/0005-2795(75)90109-9
MRR	Voorhees. "The TREC-8 Question Answering Track Report."	1999	NIST
NDCG	Järvelin & Kekäläinen. "Cumulated gain-based evaluation of IR techniques." ACM TOIS.	2002	DOI:10.1145/582415.582418
NMI	Strehl & Ghosh. "Cluster ensembles." JMLR.	2002	DOI:10.1162/153244303321897735
ARI	Hubert & Arabie. "Comparing partitions." J. Classification.	1985	DOI:10.1007/BF01908075

Graph Structure & Embeddings

Algorithm	Paper	Year	Link
Clustering Coeff.	Watts & Strogatz. "Collective dynamics of 'small-world' networks." Nature.	1998	DOI:10.1038/30918
Assortativity	Newman. "Assortative mixing in networks." PRL.	2002	DOI:10.1103/PhysRevLett.89.208701
Laplacian Eigenmaps	Belkin & Niyogi. "Laplacian eigenmaps for dimensionality reduction." Neural Comp.	2003	DOI:10.1162/089976603321780317
Spectral Clustering	Von Luxburg. "A tutorial on spectral clustering." Statistics and Computing.	2007	DOI:10.1007/s11222-007-9033-z
Fiedler Vector	Fiedler. "Algebraic connectivity of graphs." Czech. Math. J.	1973	—
Dijkstra	Dijkstra. "A note on two problems in connexion with graphs." Num. Math.	1959	DOI:10.1007/BF01386390

Machine Learning

Algorithm	Paper	Year	Link
K-Means	MacQueen. "Some methods for classification of multivariate observations." 5th Berkeley Symp.	1967	PDF
Logistic Regression	Cox. "The regression analysis of binary sequences." JRSS-B.	1958	DOI:10.1111/j.2517-6161.1958.tb00292.x

---

📄 License

MIT License