README.md

---
license: apache-2.0
title: PhishGuardian AI
sdk: gradio
emoji: ⚡
colorFrom: red
colorTo: yellow
pinned: false
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/6838c79ebfdc8508f8fdead2/Y8nN6RWVuCMaJNmLG5X-A.png
short_description: UDSM AI-powered tool for real-time phishing email detection.
---
# PhishGuardian AI 🛡️

AI-powered phishing email detection using DistilBERT for real-time security analysis.

## Overview

PhishGuardian AI is an intelligent email security tool that classifies emails as legitimate or phishing using a fine-tuned DistilBERT model. Built for the University of Dar es Salaam (UDSM) community, it provides instant threat assessment through an intuitive web interface.

## Features

- **Real-time Detection**: Instant email classification with confidence scoring
- **Advanced AI Model**: Fine-tuned DistilBERT (`cybersectony/phishing-email-detection-distilbert_v2.4.1`)
- **User-friendly Interface**: Clean Gradio web interface with visual risk indicators
- **Comprehensive Analysis**: Detailed probability breakdown for all threat categories
- **Educational Tool**: Built-in examples and security recommendations

## Quick Start

### Online Access
Visit the deployed Space: `https://huggingface.co/spaces/MUFASA25/phishguardian-ai`

### Local Development
```bash
git clone https://huggingface.co/spaces/MUFASA25/phishguardian-ai
cd phishguardian-ai
pip install -r requirements.txt
python app.py
```

## Usage

1. **Input**: Paste email content into the text area
2. **Analyze**: Click "Analyze Email" for instant results
3. **Review**: Examine risk level, confidence score, and detailed analysis
4. **Act**: Follow provided security recommendations

### Example Analysis

**Input**: Suspicious email with urgent account verification request

**Output**:
```
🚨 HIGH RISK
Primary Classification: Phishing Email
Confidence: 92.8%
Recommendation: Do not click any links or provide personal information.
```

## Technical Specifications

- **Model**: DistilBERT-base fine-tuned for sequence classification
- **Input Limit**: 512 tokens
- **Classes**: Legitimate Email, Phishing Email, Suspicious Content, Other
- **Framework**: Transformers, PyTorch, Gradio
- **Deployment**: Hugging Face Spaces

## Requirements

```
gradio>=4.0.0
transformers>=4.21.0
torch>=1.12.0
```

## Contributing

1. Fork the repository
2. Create feature branch (`git checkout -b feature/enhancement`)
3. Commit changes (`git commit -m 'Add enhancement'`)
4. Push to branch (`git push origin feature/enhancement`)
5. Open Pull Request

## License

Licensed under Apache 2.0. See [LICENSE](LICENSE) for details.

## Contact

**Developer**: MUFASA25  
**Email**: [email protected]  
**Institution**: University of Dar es Salaam (UDSM)  
**Profile**: [https://huggingface.co/MUFASA25](https://huggingface.co/MUFASA25)

---

⚠️ **Disclaimer**: This tool is for educational and awareness purposes. Always follow your organization's security protocols and use professional judgment when handling suspicious emails.