Metadata-Version: 2.4
Name: mandala-gnn
Version: 0.1.0
Summary: A native Graph Neural Network & Knowledge Graph Analytics library with scientific journal-backed algorithms.
Author-email: Mandala-GNN Contributors <muhammadikhwanfathulloh17@gmail.com>
Project-URL: Homepage, https://github.com/Muhammad-Ikhwan-Fathulloh/Mandala-GNN
Project-URL: Bug Tracker, https://github.com/Muhammad-Ikhwan-Fathulloh/Mandala-GNN/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: networkx>=3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Dynamic: license-file

# 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

```bash
pip install mandala-gnn
```

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

---

## 🚀 Quick Start

### 1. Knowledge Graph

```python
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

```python
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

```python
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

```python
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

```python
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

```python
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](https://arxiv.org/abs/1609.02907) |
| **GAT** | Veličković et al. "Graph Attention Networks." *ICLR*. | 2018 | [arXiv:1710.10903](https://arxiv.org/abs/1710.10903) |
| **GATv2** | Brody et al. "How Attentive are Graph Attention Networks?" *ICLR*. | 2022 | [arXiv:2105.14491](https://arxiv.org/abs/2105.14491) |
| **GraphSAGE** | Hamilton et al. "Inductive Representation Learning on Large Graphs." *NeurIPS*. | 2017 | [arXiv:1706.02216](https://arxiv.org/abs/1706.02216) |
| **GIN** | Xu et al. "How Powerful are Graph Neural Networks?" *ICLR*. | 2019 | [arXiv:1810.00826](https://arxiv.org/abs/1810.00826) |
| **MPNN** | Gilmer et al. "Neural Message Passing for Quantum Chemistry." *ICML*. | 2017 | [arXiv:1704.01212](https://arxiv.org/abs/1704.01212) |
| **GPS** | Rampášek et al. "Recipe for a General, Powerful, Scalable Graph Transformer." *NeurIPS*. | 2022 | [arXiv:2205.12454](https://arxiv.org/abs/2205.12454) |
| **SignNet** | Lim et al. "Sign and Basis Invariant Networks for Spectral Graph Representation Learning." *ICLR*. | 2023 | [arXiv:2202.13013](https://arxiv.org/abs/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](https://doi.org/10.1016/S0169-7552(98)00110-X) |
| **Betweenness** | Freeman. "A set of measures of centrality based on betweenness." *Sociometry*. | 1977 | [DOI:10.2307/3033543](https://doi.org/10.2307/3033543) |
| **Closeness** | Bavelas. "Communication patterns in task-oriented groups." *JASA*. | 1950 | [DOI:10.1121/1.1906679](https://doi.org/10.1121/1.1906679) |
| **Eigenvector** | Bonacich. "Power and centrality: A family of measures." *AJS*. | 1987 | [DOI:10.1086/228631](https://doi.org/10.1086/228631) |
| **HITS** | Kleinberg. "Authoritative sources in a hyperlinked environment." *JACM*. | 1999 | [DOI:10.1145/324133.324140](https://doi.org/10.1145/324133.324140) |
| **Katz** | Katz. "A new status index derived from sociometric analysis." *Psychometrika*. | 1953 | [DOI:10.1007/BF02289026](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://books.google.com/books?id=7f5TAAAAMAAJ) |
| **Jaccard Index** | Jaccard. "Étude comparative de la distribution florale." *Bull. Soc. Vaud. Sci. Nat.* | 1901 | [DOI:10.5169/seals-266450](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://doi.org/10.1016/0377-0427(87)90125-7) |
| **Davies-Bouldin** | Davies & Bouldin. "A cluster separation measure." *IEEE TPAMI*. | 1979 | [DOI:10.1109/TPAMI.1979.4766909](https://doi.org/10.1109/TPAMI.1979.4766909) |
| **Calinski-Harabasz** | Caliński & Harabasz. "A dendrite method for cluster analysis." *Comm. in Statistics*. | 1974 | [DOI:10.1080/03610927408827101](https://doi.org/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](https://doi.org/10.1148/radiology.143.1.7063747) |
| **F1 Score** | Van Rijsbergen. *Information Retrieval*. Butterworths. | 1979 | [ISBN:0408709294](https://books.google.com/books?id=t-pTAAAAMAAJ) |
| **MCC** | Matthews. "Comparison of predicted and observed secondary structure." *BBA*. | 1975 | [DOI:10.1016/0005-2795(75)90109-9](https://doi.org/10.1016/0005-2795(75)90109-9) |
| **MRR** | Voorhees. "The TREC-8 Question Answering Track Report." | 1999 | [NIST](https://trec.nist.gov/pubs/trec8/papers/qa_report.pdf) |
| **NDCG** | Järvelin & Kekäläinen. "Cumulated gain-based evaluation of IR techniques." *ACM TOIS*. | 2002 | [DOI:10.1145/582415.582418](https://doi.org/10.1145/582415.582418) |
| **NMI** | Strehl & Ghosh. "Cluster ensembles." *JMLR*. | 2002 | [DOI:10.1162/153244303321897735](https://doi.org/10.1162/153244303321897735) |
| **ARI** | Hubert & Arabie. "Comparing partitions." *J. Classification*. | 1985 | [DOI:10.1007/BF01908075](https://doi.org/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](https://doi.org/10.1038/30918) |
| **Assortativity** | Newman. "Assortative mixing in networks." *PRL*. | 2002 | [DOI:10.1103/PhysRevLett.89.208701](https://doi.org/10.1103/PhysRevLett.89.208701) |
| **Laplacian Eigenmaps** | Belkin & Niyogi. "Laplacian eigenmaps for dimensionality reduction." *Neural Comp.* | 2003 | [DOI:10.1162/089976603321780317](https://doi.org/10.1162/089976603321780317) |
| **Spectral Clustering** | Von Luxburg. "A tutorial on spectral clustering." *Statistics and Computing*. | 2007 | [DOI:10.1007/s11222-007-9033-z](https://doi.org/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](https://doi.org/10.1007/BF01386390) |

### Machine Learning

| Algorithm | Paper | Year | Link |
|---|---|---|---|
| **K-Means** | MacQueen. "Some methods for classification of multivariate observations." *5th Berkeley Symp.* | 1967 | [PDF](https://projecteuclid.org/euclid.bsmsp/1200512992) |
| **Logistic Regression** | Cox. "The regression analysis of binary sequences." *JRSS-B*. | 1958 | [DOI:10.1111/j.2517-6161.1958.tb00292.x](https://doi.org/10.1111/j.2517-6161.1958.tb00292.x) |

---

## 📄 License

MIT License
