verril-learn 0.1.0
A Surgical Machine Unlearning library for edge devices using PyTorch
Requires Python: >=3.8
Keywords: machine-learning, unlearning, privacy, pytorch, edge-devices, surgical-unlearning, fisher-information

# Verril-Learn 🧠✂️

**A Surgical Machine Unlearning Library for Edge Devices**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-1.9+-red.svg)](https://pytorch.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🎯 What is Verril-Learn?

Verril-Learn is a novel machine unlearning library designed specifically for edge devices. It enables you to **surgically remove** the influence of specific data points from a trained model **without full retraining**.

### Key Features

- **🔬 Surgical Unlearning**: Remove specific data influence using Fisher Information + Gradient Ascent
- **🎭 Data Poisoning Simulation**: Built-in tools to simulate and study data attacks
- **📱 Edge-Device Optimized**: Lightweight algorithms suitable for resource-constrained environments
- **🔒 Privacy-Compliant**: Implements concepts aligned with GDPR's "Right to be Forgotten"

## 📦 Installation

```bash
pip install -e .
```

Or install dependencies directly:

```bash
pip install -r requirements.txt
```

## 🚀 Quick Start

```python
from verril_learn import get_poisoned_mnist, SimpleCNN, surgical_unlearn

# Step 1: Load poisoned MNIST (10% of '7's mislabeled as '1's)
train_loader, test_loader, poison_indices = get_poisoned_mnist(poison_ratio=0.1)

# Step 2: Train your model (standard PyTorch training loop)
model = SimpleCNN()
# ... train the model ...

# Step 3: Surgically unlearn the poisoned data
unlearned_model = surgical_unlearn(
    model=model,
    poisoned_data=poisoned_loader,
    retain_data=clean_loader,
    fisher_weight=0.1,
    unlearn_lr=0.001,
    unlearn_steps=10
)
```

## 🧪 The Algorithm

### 1. Fisher Information Matrix (Diagonal Approximation)

Identifies which weights are **critical** for the retain data:

```
F_ii = E[(∂L/∂θ_i)²]
```

### 2. Gradient Ascent on Poisoned Data

**Maximizes** the loss to make the model "forget":

```
θ = θ + α * ∇L(θ; D_poison)
```

### 3. Fisher-Weighted Regularization

Prevents catastrophic forgetting by penalizing large changes to critical weights:

```
L_total = -L_poison + λ * Σ F_ii * (θ_i - θ_i^original)²
```

## 📁 Project Structure

```
verril-learn/
├── setup.py              # Package configuration
├── requirements.txt      # Dependencies
├── README.md             # This file
└── verril_learn/
    ├── __init__.py       # Public API
    ├── data_loader.py    # MNIST loading + poisoning
    ├── model.py          # CNN architecture
    └── core.py           # Surgical unlearning algorithm
```

## 📚 References

- [Machine Unlearning (Bourtoule et al., 2021)](https://arxiv.org/abs/1912.03817)
- [Fisher Information for Deep Learning](https://arxiv.org/abs/1711.04340)

## 📄 License

MIT License - See LICENSE file for details.

---

*Built with ❤️ for the ML Security & Privacy community*