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

📦 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

Centrality Measures

Community Detection

Similarity & Link Prediction

Evaluation Metrics

Graph Structure & Embeddings

Machine Learning

📄 License

MIT License