Update README.md

README.md

@@ -1,131 +1,86 @@
----
-title: PhishGuardian AI
-emoji: 🔥
-colorFrom: yellow
-colorTo: purple
-sdk: gradio
-sdk_version: 5.0.1
-app_file: app.py
-pinned: false
-license: apache-2.0
-short_description: UDSM AI-powered tool for real-time phishing email detection.
----
-Phishing Email Detection Space
-Welcome to the Phishing Email Detection Hugging Face Space! This project provides an interactive web interface to classify emails as legitimate or phishing using a fine-tuned DistilBERT model (cybersectony/phishing-email-detection-distilbert_v2.4.1). Built with Gradio, this Space allows users to input email text and receive predictions with confidence scores and probability distributions.
-Table of Contents
-
-Overview
-Features
-How It Works
-Usage
-Installation (For Local Development)
-Model Details
-Contributing
-License
-Contact
-
-Overview
-This Space deploys a DistilBERT-based model to detect phishing emails by classifying input text into one of four categories: Legitimate Email, Phishing URL, Legitimate URL, or Phishing URL (Alt). The model is hosted on Hugging Face and integrated with a Gradio interface for easy interaction. Users can input email text and instantly view the predicted classification along with confidence scores.
-Features
-
-Interactive Interface: Input email text via a user-friendly Gradio web interface.
-Real-Time Predictions: Get immediate classification results with confidence scores.
-Detailed Output: View probabilities for all classes (Legitimate Email, Phishing URL, Legitimate URL, Phishing URL Alt).
-Lightweight Model: Uses DistilBERT for efficient inference, suitable for CPU-based environments.
-Open Source: Code and model are accessible for further customization.
-
-How It Works
-
-The user inputs email text into the Gradio interface.
-The text is tokenized using the DistilBERT tokenizer.
-The fine-tuned DistilBERT model processes the input and outputs probabilities for each class.
-The interface displays the most likely classification, confidence score, and all class probabilities.
-
-Usage
-
-Access the Space: Visit the Hugging Face Space URL (e.g., https://<your-username>-<space-name>.hf.space).
-Enter Email Text: Type or paste the email content into the provided text box.
-Get Prediction: Click the "Submit" button to view the classification results.
-Interpret Results: The output includes:
-Prediction: The most likely class (e.g., "Phishing URL").
-Confidence: The probability score for the predicted class.
-All Probabilities: Probability scores for all four classes.
-
-
-
-Example Input:
-Subject: Urgent: Verify Your Account Now
-Dear Customer, your account has been flagged. Click here to verify: [suspicious-link.com].
-
-Example Output:
-Prediction: Phishing URL
-Confidence: 0.9278
-All Probabilities:
-- Legitimate Email: 0.0123
-- Phishing URL: 0.9278
-- Legitimate URL: 0.0345
-- Phishing URL (Alt): 0.0254
-
-Installation (For Local Development)
-If you want to run this project locally or contribute to its development, follow these steps:
-
-Clone the Repository:
-git clone https://huggingface.co/spaces/<your-username>/<your-space-name>
-cd <your-space-name>
-
-
-Install Dependencies:Create a virtual environment and install the required packages:
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-pip install -r requirements.txt
+# 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
 
-Run the Application:Launch the Gradio interface locally:
+## 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
 
-Access Locally:Open the provided local URL (e.g., http://127.0.0.1:7860) in your browser.
+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
 
-Requirements (listed in requirements.txt):
-transformers
-torch
-gradio
+**Input**: Suspicious email with urgent account verification request
 
-Model Details
+**Output**:
+```
+🚨 HIGH RISK
+Primary Classification: Phishing Email
+Confidence: 92.8%
+Recommendation: Do not click any links or provide personal information.
+```
 
-Model: cybersectony/phishing-email-detection-distilbert_v2.4.1
-Architecture: DistilBERT (fine-tuned for sequence classification)
-Classes:
-Legitimate Email
-Phishing URL
-Legitimate URL
-Phishing URL (Alt)
+## 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
 
-Input: Text (max length: 512 tokens)
-Output: Probabilities for each class, with the highest probability determining the predicted class.
+## Requirements
 
-The model is hosted on Hugging Face and loaded directly in the Space. For private models, ensure you set the HF_TOKEN environment variable in your Space settings.
-Contributing
-Contributions are welcome! To contribute:
+```
+gradio>=4.0.0
+transformers>=4.21.0
+torch>=1.12.0
+```
 
-Fork the repository on Hugging Face.
-Create a new branch for your changes (git checkout -b feature/your-feature).
-Commit your changes (git commit -m "Add your feature").
-Push to your fork (git push origin feature/your-feature).
-Open a pull request on the Space’s repository.
+## Contributing
 
-Please ensure your code follows the project’s style and includes tests where applicable.
+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
-This project is licensed under the APACHE 2.0. See the LICENSE file for details.
+## License
 
-Contact
-For questions or feedback, please reach out via:
+Licensed under Apache 2.0. See [LICENSE](LICENSE) for details.
 
-Hugging Face: https://huggingface.co/MUFASA25
-Email: [email protected]
-Issues: Open an issue on the Space’s repository.
+## Contact
+
+**Developer**: MUFASA25  
+**Email**: [email protected]  
+**Institution**: University of Dar es Salaam (UDSM)  
+**Profile**: [https://huggingface.co/MUFASA25](https://huggingface.co/MUFASA25)
+
+---
 
-Thank you for using the Phishing Email Detection Space!
+⚠️ **Disclaimer**: This tool is for educational and awareness purposes. Always follow your organization's security protocols and use professional judgment when handling suspicious emails.