PrivNet.AI - Privacy-Preserving Geometric Deep Learning

Welcome to PrivNet.AI — an open-source platform combining post-quantum cryptography and geometric deep learning to enable privacy-preserving machine learning on sensitive data such as genomics, financial networks, and healthcare records.

🚀 Project Vision

Build a privacy-centric infrastructure where users can train graph-based models without ever decrypting their data.

We explore lattice-based homomorphic encryption and graph neural networks (GNNs) for structure-aware inference on encrypted data. Authenticated post-quantum communication and encrypted training remain separate future protocol work.

Current Status: The original GCN proof of concept uses EncryptionShim, an educational simulator. The separate Krylov application supports real CKKS inference on a small demonstration model. Encrypted training is not implemented. See Limitations and Krylov boundaries.

Interactive Krylov application

The Krylov lab adds client-side graph compilation, interactive predictions, and an optional real-CKKS demonstration in the browser. It implements the method from PrivNet-Krylov independently, with attribution to Ehsan Hakimian and Chiman Soltanian. The sample is a public synthetic graph; displayed accuracy is illustrative all-node accuracy.

Run the application locally with python -m applications.krylov --backend plain --output /tmp/krylov.json. For real encrypted execution, install requirements-ckks.txt and select --backend ckks. See Krylov usage and boundaries for the model, browser development, serialized key boundary and validation commands.

---

🧩 Key Technologies

• Graph Neural Networks for structured data learning (PyTorch Geometric)
• Post-Quantum Cryptography (PQC) protocol integration (planned; current module is a mock)
• Homomorphic Encryption through optional CKKS backends for the Krylov application
• PyTorch for deep learning infrastructure
• Federated Learning & Differential Privacy (planned for future integration)

---

🔧 Project Structure

📦 privnet-ai/
├── crypto/                  # Cryptographic modules
│   ├── encryption.py        # EncryptionShim (PoC simulator)
│   ├── homomorphic/         # Homomorphic encryption operations
│   ├── pqc/                 # Post-quantum cryptography (Kyber)
│   └── protocols/           # Cryptographic protocols
├── ml/                      # Machine learning modules
│   ├── models/              # GNN models (GCN, etc.)
│   ├── layers/              # Custom GNN layers
│   ├── training/            # Training utilities
│   └── geometric/           # Geometric learning components
├── core/                    # Core utilities
│   ├── config.py            # Configuration management
│   └── utils.py             # General utilities
├── data/                    # Datasets (Cora, CiteSeer, PubMed)
├── api/                     # API endpoints (FastAPI)
├── tests/                   # Test suite
├── docs/                    # Documentation
├── scripts/                 # Utility scripts
├── deployment/              # Deployment configurations
├── CONTRIBUTING.md          # How to contribute
├── CODE_OF_CONDUCT.md       # Collaboration guidelines
├── roadmap.md               # Project vision and goals
└── README.md                # This file

---

🧠 Why this project matters?

Current ML systems expose data at many points: during training, inference, or transport. This is not acceptable for sensitive data (e.g., genome sequences, health records, financial transactions).

PrivNet.AI introduces a new paradigm: Train on encrypted data. Analyze graphs with security. Scale with structure.

---

🛠️ Getting Started

Prerequisites

• Python 3.11+ (tested with 3.12+)
• pip or conda

Installation

1. Clone the repository

git clone https://github.com/chimans/privnet-ai.git
cd privnet-ai

2. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Running the Proof-of-Concept

Train a Graph Convolutional Network (GCN) on Planetoid datasets and evaluate encrypted linear operations:

# Train on Cora dataset with encrypted linear head evaluation
python main.py --dataset cora --epochs 50 --enc_eval

# Available options:
# --dataset {cora|citeseer|pubmed}  # Choose dataset (default: cora)
# --epochs N                         # Training epochs (default: 100)
# --hidden N                         # Hidden dimension (default: 64)
# --lr FLOAT                         # Learning rate (default: 0.01)
# --device {auto|cpu|cuda}          # Device selection (default: auto)
# --enc_eval                         # Enable encrypted linear head evaluation
# --enc_scale FLOAT                  # Quantization scale for EncryptionShim (default: 256.0)
# --seed N                           # Random seed (default: 42)

Example Output

Epoch 001 | loss=1.9463 | train=0.229 | val=0.138 | test=0.158
...
Epoch 050 | loss=0.5108 | train=0.979 | val=0.806 | test=0.831

=== Final ===
Device: cpu
Dataset: Cora
Train Acc: 0.979
Val   Acc: 0.810
Test  Acc: 0.827
Time (sec): 0.6
Encrypted linear head test acc: 0.492

---

📚 Documentation

• roadmap.md – Project roadmap and development phases
• Krylov application – Client-side compilation, real CKKS, and interactive GitHub Pages lab
• Research archive (10 October 2026) – 2025–2026 literature findings, numerical results, and a proposed roadmap review
• README_INSTRUCTION.md – Detailed PoC documentation
• CONTRIBUTING.md – Contribution guidelines
• CODE_OF_CONDUCT.md – Community guidelines

---

🔬 Original GCN Proof-of-Concept Details

Architecture Overview

The current PoC demonstrates:

1. GCN Training: A two-layer Graph Convolutional Network trained on Planetoid datasets (Cora, CiteSeer, PubMed)
2. Feature Extraction: Hidden representations (H) are extracted after the first GCN layer
3. Linear Head: A ridge regression-based linear classifier is trained on plaintext features
4. Encrypted Evaluation: The linear head is applied to encrypted/masked features using EncryptionShim

EncryptionShim (PoC Simulator)

The EncryptionShim is not real cryptography. It's a proof-of-concept simulator that:

• Quantizes floating-point values to fixed-point integers
• Applies random additive masking
• Supports linear operations (addition, scalar multiplication, matrix multiplication)
• Demonstrates the feasibility of linear computation on masked data

Important: This is a simulation for demonstration purposes only. Real cryptographic security requires proper homomorphic encryption schemes.

⚠️ Current Limitations

• EncryptionShim is not cryptographically secure — it's a quantization + masking simulator
• Only linear operations are supported; nonlinearities (ReLU, Softmax) cannot be executed in the masked domain
• Graph structure and node features are processed in plaintext during training
• No post-quantum resistance or zero-knowledge proofs implemented
• Feature extraction (H) happens in plaintext; only the linear head operates on masked data

See README_INSTRUCTION.md for detailed technical documentation.

---

🧪 Testing

Run the test suite to verify the installation:

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test files
pytest tests/test_encryption.py
pytest tests/test_models.py
pytest tests/test_integration.py

---

👥 How to Contribute

We welcome contributions from cryptographers, ML engineers, researchers, and developers.

Ways to contribute:

• Build core GNN modules or crypto components
• Implement real homomorphic encryption schemes (CKKS, BFV)
• Improve documentation and add examples
• Write tests and improve test coverage
• Review code and suggest improvements
• Report bugs and suggest features

📌 Contribution checklist:

1. Fork this repo
2. Create a new feature branch: git checkout -b feature/your-feature
3. Make your changes with clear commits
4. Add tests for new functionality
5. Ensure all tests pass: pytest
6. Open a pull request and fill out the PR template

Pull Request Template:

### What does this PR do?
- Clearly explain your update/fix

### Checklist:
- [ ] My code follows the project style
- [ ] I've tested this locally
- [ ] I added tests for new functionality
- [ ] I linked any related Issue

---

📍 Project Status

We’re in early development, with the original GCN simulator and a separate Krylov application offering optional real CKKS inference.

Current Phase: GCN simulator plus experimental Krylov CKKS inference Next Steps: See roadmap.md for detailed development phases

Use Issues to suggest features or Discussions to brainstorm with us.

---

🗺️ Roadmap Highlights

See roadmap.md for the complete development plan.

Completed:

• Repo bootstrapping & structure setup
• PoC with EncryptionShim and GCN on Planetoid datasets
• Basic test suite
• Independent Krylov application and interactive browser lab with optional real CKKS

In Progress / Planned:

• Broader homomorphic backend and model integration
• Full encrypted inference for the original GCN architecture
• Authenticated post-quantum communication
• Encrypted graph structure support
• Federated learning integration
• MVP deployment

---

📜 License

MIT License — free to use, modify, and contribute.

---

✨ Contact & Community

• Discord: Join our community
• GitHub Issues: Report bugs, request features, or ask questions
• Contributions: See CONTRIBUTING.md for guidelines
• Roadmap: Follow roadmap.md for development progress

Let's build privacy-native AI together.

— The PrivNet.AI team

---

🙏 Acknowledgments

Special thanks to the open-source communities behind PyTorch, PyTorch Geometric, and the cryptographic research community working on privacy-preserving machine learning.