{"id":34109184,"url":"https://github.com/shashuat/unlearun","last_synced_at":"2026-04-09T04:32:15.351Z","repository":{"id":296541448,"uuid":"993720652","full_name":"shashuat/unlearun","owner":"shashuat","description":"Machine Unlearning in Large Language Models for PyTorch","archived":false,"fork":false,"pushed_at":"2026-01-12T17:12:25.000Z","size":46,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T05:24:33.856Z","etag":null,"topics":["machine-learning","machine-unlearning"],"latest_commit_sha":null,"homepage":"https://unlea.run","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shashuat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-31T11:28:31.000Z","updated_at":"2026-01-13T21:06:39.000Z","dependencies_parsed_at":"2025-06-01T00:44:06.519Z","dependency_job_id":null,"html_url":"https://github.com/shashuat/unlearun","commit_stats":null,"previous_names":["shashuat/unlearun"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shashuat/unlearun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashuat%2Funlearun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashuat%2Funlearun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashuat%2Funlearun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashuat%2Funlearun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shashuat","download_url":"https://codeload.github.com/shashuat/unlearun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shashuat%2Funlearun/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31586403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["machine-learning","machine-unlearning"],"created_at":"2025-12-14T18:27:50.126Z","updated_at":"2026-04-09T04:32:15.343Z","avatar_url":"https://github.com/shashuat.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Unlearun: Machine Unlearning for Fine-tuned LLMs\n\nA comprehensive Python package for machine unlearning in large language models, enabling efficient removal of unwanted knowledge while preserving model utility.\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n---\n\n## 🎯 Overview\n\n**Unlearun** addresses the critical need to remove specific knowledge from trained language models without expensive retraining. This is essential for:\n\n- **Privacy Compliance**: GDPR \"right to be forgotten\" requirements\n- **Copyright Protection**: Removing copyrighted content from models\n- **AI Safety**: Eliminating harmful or dangerous knowledge\n- **Model Correction**: Fixing outdated or incorrect information\n\n## ✨ Key Features\n\n- **5 State-of-the-Art Methods**: GradAscent, GradDiff, DPO, RMU, SimNPO\n- **Simple High-Level API**: Get started with just a few lines of code\n- **Comprehensive Evaluation**: Built-in metrics for forget quality, utility preservation, and privacy\n- **Flexible Data Loading**: Support for JSON, JSONL, HuggingFace datasets, and Python lists\n- **Production Ready**: Extensive test coverage and benchmarking\n- **HuggingFace Integration**: Seamless integration with `transformers` and `accelerate`\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\npip install unlearun\n```\n\nOr install from source:\n\n```bash\ngit clone https://github.com/shashuat/unlearun.git\ncd unlearun\npip install -e .\n```\n\n### Basic Usage\n\n```python\nfrom unlearun import Unlearning\n\n# Initialize unlearner with RMU method\nunlearner = Unlearning(\n    method=\"rmu\",\n    model=\"gpt2-medium\",\n    output_dir=\"./unlearned_model\"\n)\n\n# Load your data\nforget_data = [\n    {\"question\": \"What is the capital of France?\", \"answer\": \"Paris\"},\n    {\"question\": \"Who wrote Romeo and Juliet?\", \"answer\": \"Shakespeare\"}\n]\n\nretain_data = [\n    {\"question\": \"What is the capital of Germany?\", \"answer\": \"Berlin\"},\n    {\"question\": \"Who painted the Mona Lisa?\", \"answer\": \"Leonardo da Vinci\"}\n]\n\nunlearner.load_data(\n    forget_data=forget_data,\n    retain_data=retain_data,\n    max_length=128\n)\n\n# Run unlearning\nunlearner.run(\n    batch_size=4,\n    learning_rate=5e-5,\n    num_epochs=3\n)\n\n# Evaluate results\nresults = unlearner.evaluate(\n    metrics=[\"perplexity\", \"forget_quality\", \"model_utility\"]\n)\n\nprint(f\"Forget Quality: {results['forget_quality']:.4f}\")\nprint(f\"Model Utility: {results['model_utility']:.4f}\")\n```\n\n## 📚 Supported Methods\n\n| Method | Description | Reference Model | Best For |\n|--------|-------------|----------------|----------|\n| **RMU** | Representation Misdirection for Unlearning | Required | Safety-critical applications, robust forgetting |\n| **GradDiff** | Gradient Difference (ascent on forget, descent on retain) | Optional | Balanced forget/retain trade-off |\n| **DPO** | Direct Preference Optimization | Required | Preference-based unlearning with alternate answers |\n| **SimNPO** | Simple Negative Preference Optimization | Not required | Stable unlearning without reference model |\n| **GradAscent** | Gradient Ascent on forget set | Not required | Simple baseline, quick experiments |\n\n### Method Selection Guide\n\n```python\n# For safety-critical unlearning (e.g., removing hazardous knowledge)\nunlearner = Unlearning(method=\"rmu\", model=\"model_name\", adaptive=True)\n\n# For balanced forgetting with good retain data\nunlearner = Unlearning(method=\"grad_diff\", model=\"model_name\", \n                       gamma=1.0, alpha=1.0)\n\n# When you have alternate acceptable answers\nunlearner = Unlearning(method=\"dpo\", model=\"model_name\", beta=1.0)\n\n# For simple, stable unlearning\nunlearner = Unlearning(method=\"simnpo\", model=\"model_name\")\n\n# Quick baseline for experiments\nunlearner = Unlearning(method=\"grad_ascent\", model=\"model_name\")\n```\n\n## 📖 Detailed Examples\n\n### Example 1: RMU with Adaptive Steering\n\n```python\nfrom unlearun import Unlearning\n\n# RMU is the most robust method for safety-critical unlearning\nunlearner = Unlearning(\n    method=\"rmu\",\n    model=\"gpt2\",\n    output_dir=\"./rmu_model\",\n    # RMU-specific parameters\n    steering_coeff=1.0,  # Steering strength\n    target_layer=8,      # Which transformer layer to steer\n    adaptive=True        # Use adaptive coefficient (recommended)\n)\n\n# Load data from JSON files\nunlearner.load_data(\n    forget_data=\"forget_set.json\",\n    retain_data=\"retain_set.json\",\n    max_length=128\n)\n\n# Configure training\nunlearner.run(\n    batch_size=4,\n    learning_rate=1e-5,\n    num_epochs=3,\n    gradient_accumulation_steps=2,\n    warmup_steps=100,\n    logging_steps=10\n)\n\n# Comprehensive evaluation\nresults = unlearner.evaluate(\n    metrics=[\n        \"perplexity\",\n        \"forget_quality\", \n        \"model_utility\",\n        \"rouge\",\n        \"verbatim_memorization\",\n        \"mia\"\n    ]\n)\n```\n\n### Example 2: Gradient Difference with KL Regularization\n\n```python\nfrom unlearun import Unlearning\n\n# GradDiff with KL divergence for smoother retain preservation\nunlearner = Unlearning(\n    method=\"grad_diff\",\n    model=\"gpt2-medium\",\n    output_dir=\"./graddiff_model\",\n    # GradDiff-specific parameters\n    gamma=1.0,              # Weight for forget loss\n    alpha=1.0,              # Weight for retain loss\n    retain_loss_type=\"KL\"   # Use KL divergence (requires ref model)\n)\n\nunlearner.load_data(\n    forget_data=\"forget.json\",\n    retain_data=\"retain.json\"\n)\n\nunlearner.run(\n    batch_size=2,\n    learning_rate=5e-5,\n    num_epochs=5\n)\n```\n\n### Example 3: Loading from HuggingFace Dataset\n\n```python\nfrom datasets import load_dataset\nfrom unlearun import Unlearning\n\n# Load from HuggingFace Hub\nforget_dataset = load_dataset(\"your_username/forget_dataset\", split=\"train\")\nretain_dataset = load_dataset(\"your_username/retain_dataset\", split=\"train\")\n\nunlearner = Unlearning(\n    method=\"simnpo\",\n    model=\"meta-llama/Llama-2-7b-hf\",\n    output_dir=\"./unlearned_llama\"\n)\n\nunlearner.load_data(\n    forget_data=forget_dataset,\n    retain_data=retain_dataset,\n    question_key=\"prompt\",  # Specify your column names\n    answer_key=\"completion\",\n    max_length=512\n)\n\nunlearner.run(batch_size=1, num_epochs=3)\n```\n\n### Example 4: Custom Evaluation\n\n```python\nfrom unlearun import Unlearning\nfrom unlearun.evaluation import (\n    compute_perplexity,\n    compute_verbatim_memorization,\n    compute_mia\n)\n\n# After training\nunlearner = Unlearning(method=\"rmu\", model=\"gpt2\", output_dir=\"./model\")\nunlearner.load_data(forget_data=\"forget.json\", retain_data=\"retain.json\")\nunlearner.run(batch_size=2, num_epochs=3)\n\n# Custom evaluation with specific parameters\nforget_ppl = compute_perplexity(\n    model=unlearner.model,\n    dataset=unlearner.forget_dataset,\n    tokenizer=unlearner.tokenizer,\n    batch_size=4\n)\n\n# Check for verbatim memorization\nverbatim_score = compute_verbatim_memorization(\n    model=unlearner.model,\n    forget_dataset=unlearner.forget_dataset,\n    tokenizer=unlearner.tokenizer,\n    prefix_length=50,\n    max_new_tokens=100,\n    num_samples=100\n)\n\n# Membership inference attack\nmia_score = compute_mia(\n    model=unlearner.model,\n    forget_dataset=unlearner.forget_dataset,\n    retain_dataset=unlearner.retain_dataset,\n    tokenizer=unlearner.tokenizer,\n    batch_size=4\n)\n\nprint(f\"Forget Perplexity: {forget_ppl:.2f}\")\nprint(f\"Verbatim Memorization: {verbatim_score:.4f}\")\nprint(f\"MIA AUROC: {mia_score:.4f}\")\n```\n\n## 📊 Evaluation Metrics\n\nThe package includes comprehensive evaluation metrics:\n\n### Forget Quality Metrics\n- **Perplexity**: Measures how \"forgotten\" the data is (higher = better)\n- **Verbatim Memorization**: ROUGE score between generated and ground truth\n- **Knowledge Retention**: QA accuracy on forget topics\n\n### Utility Preservation Metrics\n- **Model Utility**: Performance on retain set\n- **General Knowledge**: Evaluation on holdout data\n- **Task Performance**: Accuracy on downstream tasks\n\n### Privacy Metrics\n- **Membership Inference Attack (MIA)**: Resistance to privacy attacks\n- **Extraction Attack**: Difficulty of extracting forgotten data\n\n## 🏗️ Project Structure\n\n```\nunlearun/\n├── unlearun/\n│   ├── __init__.py           # Package entry point\n│   ├── core.py               # High-level Unlearning class\n│   ├── methods/              # Unlearning methods\n│   │   ├── grad_ascent.py\n│   │   ├── grad_diff.py\n│   │   ├── dpo.py\n│   │   ├── rmu.py\n│   │   └── simnpo.py\n│   ├── data/                 # Data handling\n│   │   ├── dataset.py\n│   │   └── collators.py\n│   ├── trainer/              # Custom trainer\n│   │   └── trainer.py\n│   ├── utils/                # Utilities\n│   │   ├── losses.py\n│   │   └── helpers.py\n│   └── evaluation/           # Evaluation metrics\n│       └── metrics.py\n├── tests/                    # Test suite\n│   └── test_unlearning.py\n├── pyproject.toml            # Package configuration\n├── requirements.txt          # Dependencies\n└── README.md                 # This file\n```\n\n## 🧪 Testing\n\nRun the test suite:\n\n```bash\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ --cov=unlearun --cov-report=html\n\n# Skip slow tests\npytest tests/ -v -m \"not slow\"\n```\n\n## 📋 Requirements\n\n- Python ≥ 3.8\n- PyTorch ≥ 2.0.0\n- Transformers ≥ 4.30.0\n- Datasets ≥ 2.12.0\n- Accelerate ≥ 0.20.0\n\nSee `requirements.txt` for full dependency list.\n\n## 🎓 Benchmarks\n\nThe package is compatible with standard unlearning benchmarks:\n\n- **TOFU** (Task of Fictitious Unlearning for LLMs)\n- **WMDP** (Weapons of Mass Destruction Proxy)\n- **MUSE** (Machine Unlearning Six-Way Evaluation)\n\n```python\n# Example: Evaluate on TOFU benchmark\nfrom datasets import load_dataset\n\ntofu_forget = load_dataset(\"locuslab/TOFU\", \"forget01\", split=\"train\")\ntofu_retain = load_dataset(\"locuslab/TOFU\", \"retain99\", split=\"train\")\n\nunlearner = Unlearning(method=\"rmu\", model=\"phi-1.5\")\nunlearner.load_data(forget_data=tofu_forget, retain_data=tofu_retain)\nunlearner.run(batch_size=2, num_epochs=3)\n\nresults = unlearner.evaluate()\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`pytest tests/`)\n6. Format code (`black unlearun/ tests/`)\n7. Commit changes (`git commit -m 'Add amazing feature'`)\n8. Push to branch (`git push origin feature/amazing-feature`)\n9. Open a Pull Request\n\n### Development Setup\n\n```bash\ngit clone https://github.com/shashuat/unlearun.git\ncd unlearun\npip install -e \".[dev]\"\npre-commit install  # Optional: for automatic formatting\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 📚 Citation\n\nIf you use Unlearun in your research, please cite:\n\n```bibtex\n@software{unlearun2025,\n  title = {Unlearun: Machine Unlearning for Fine-tuned LLMs},\n  author = {Your Name},\n  year = {2025},\n  url = {https://github.com/shashuat/unlearun},\n  version = {0.1.0}\n}\n```\n\n### Key References\n\nThis package implements methods from:\n\n```bibtex\n@inproceedings{li2024wmdp,\n  title={The WMDP Benchmark: Measuring and Reducing Malicious Use with Unlearning},\n  author={Li, Nathaniel and Pan, Alexander and others},\n  booktitle={ICML},\n  year={2024}\n}\n\n@inproceedings{rafailov2023dpo,\n  title={Direct Preference Optimization: Your Language Model is Secretly a Reward Model},\n  author={Rafailov, Rafael and Sharma, Archit and others},\n  booktitle={NeurIPS},\n  year={2023}\n}\n\n@inproceedings{maini2024tofu,\n  title={TOFU: A Task of Fictitious Unlearning for LLMs},\n  author={Maini, Pratyush and Feng, Zhili and others},\n  booktitle={COLM},\n  year={2024}\n}\n```\n\n## 🙏 Acknowledgments\n\n- Built on [HuggingFace Transformers](https://github.com/huggingface/transformers)\n- Inspired by research from CMU, Stanford, and other leading institutions\n- Thanks to the machine unlearning research community\n\n## 📞 Support\n\n- **Issues**: [GitHub Issues](https://github.com/shashuat/unlearun/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/shashuat/unlearun/discussions)\n- **Email**: your.email@example.com\n\n## 🔗 Links\n\n- **Documentation**: [Full Documentation](https://unlearun.readthedocs.io)\n- **PyPI**: [Package on PyPI](https://pypi.org/project/unlearun/)\n- **Paper**: [arXiv](https://arxiv.org/abs/xxxx.xxxxx) (coming soon)\n- **WMDP Benchmark**: https://www.wmdp.ai/\n- **TOFU Benchmark**: https://github.com/locuslab/tofu\n\n---\n\n**Status**: Active Development | **Version**: 0.1.0 | **Last Updated**: October 2025\n\nMade with ❤️ for AI Safety and Privacy","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshashuat%2Funlearun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshashuat%2Funlearun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshashuat%2Funlearun/lists"}