README.md

metadata

title: 𝐒𝐩𝐚𝐦𝐃𝐞𝐱 𝐀𝐈 - 𝐔𝐬𝐞𝐫 𝐈𝐧𝐭𝐞𝐫𝐟𝐚𝐜𝐞
emoji: 🚨
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
license: mit

🧠 SpamDex Web - AI-Powered Spam Detection

A beautiful, fully-functional web application for spam detection powered by Naive Bayes + TF-IDF machine learning model from Hugging Face.

🌟 Features

• ✨ Beautiful UI - Glassmorphism design with dark/light mode
• 🚀 Real-time Analysis - Instant spam detection
• 🎨 Responsive Design - Works on all devices (mobile, tablet, desktop)
• 🔥 Smooth Animations - Enhanced user experience
• 🤖 AI-Powered - Using state-of-the-art ML model
• 🔌 REST API - Easy integration with other apps
• ⚡ Fast & Lightweight - Optimized performance

---

🚀 Quick Start (Local Development)

Prerequisites

• Python 3.8+
• pip

Installation

1. Clone the repository

git clone <your-repo-url>
cd spamdex-web

2. Install dependencies

pip install -r requirements.txt

3. Run the application

uvicorn app:app --host 0.0.0.0 --port 7860 --reload

4. Open in browser

http://localhost:7860

---

🌐 Deploy to Hugging Face Spaces

Step 1: Create a Space

1. Go to Hugging Face
2. Click on your profile → New Space
3. Fill in the details:
   • Name: spamdex-web (or your choice)
   • License: MIT
   • SDK: Gradio (will change to custom)
   • Hardware: Free CPU (sufficient for this model)

Step 2: Prepare Files

Create these files in your Space:

your-space/
├── app.py                 # Backend server
├── requirements.txt       # Python dependencies
├── index.html            # Frontend UI
├── README.md             # Documentation
└── .gitignore            # Git ignore file

Step 3: Upload Files

Option A: Via Web Interface

1. Click "Files and versions" in your Space
2. Click "Add file" → "Upload files"
3. Upload all files listed above

Option B: Via Git

git clone https://huggingface.co/spaces/YOUR-USERNAME/spamdex-web
cd spamdex-web

# Add all files
git add .
git commit -m "Initial commit"
git push

Step 4: Configure Space Settings

1. Go to Settings in your Space
2. Under Space SDK, select: Docker
3. Create a Dockerfile (optional, or use default)

Step 5: Wait for Build

• Hugging Face will automatically build and deploy your Space
• Check the logs for any errors
• Once built, your Space will be live!

---

📁 File Structure

spamdex-web/
│
├── app.py                 # FastAPI backend with ML model
│   ├── /api/predict       # POST endpoint for predictions
│   ├── /api/info          # GET endpoint for model info
│   └── /health            # Health check endpoint
│
├── index.html             # Complete React frontend
│   ├── React components
│   ├── Tailwind CSS
│   └── API integration
│
├── requirements.txt       # Python dependencies
│   ├── fastapi
│   ├── uvicorn
│   ├── huggingface-hub
│   ├── scikit-learn
│   └── joblib
│
└── README.md             # This file

---

🔌 API Documentation

Endpoint: /api/predict

Method: POST

Request Body:

{
  "text": "Congratulations! You won $1000!"
}

Response:

{
  "prediction": "spam",
  "label": 1,
  "confidence": 95.67,
  "cleaned_text": "congratulations you won"
}

Status Codes:

• 200 - Success
• 400 - Bad request (empty text)
• 500 - Server error
• 503 - Model not loaded

Endpoint: /api/info

Method: GET

Response:

{
  "model_name": "SpamDex v1.0",
  "algorithm": "Naive Bayes (MultinomialNB)",
  "vectorization": "TF-IDF",
  "developer": "DarkNeuronAI",
  "huggingface_repo": "DarkNeuron-AI/darkneuron-spamdex-v1",
  "labels": {
    "0": "Ham (Not Spam)",
    "1": "Spam"
  }
}

Example Usage (Python)

import requests

# API endpoint
url = "http://localhost:7860/api/predict"

# Text to analyze
data = {
    "text": "FREE iPhone! Click here to claim your prize!!!"
}

# Make request
response = requests.post(url, json=data)
result = response.json()

print(f"Prediction: {result['prediction']}")
print(f"Confidence: {result['confidence']}%")

Example Usage (JavaScript)

const analyzeText = async (text) => {
  const response = await fetch('/api/predict', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ text })
  });
  
  const result = await response.json();
  console.log('Prediction:', result.prediction);
  console.log('Confidence:', result.confidence);
};

analyzeText("Win $1000 now!");

---

🎨 UI Features

Dark/Light Mode Toggle

• Smooth transition animations
• Persistent across sessions
• Automatic theme detection

Responsive Design

• Mobile-first approach
• Breakpoints: sm, md, lg, xl
• Flexible grid layouts

Interactive Elements

• Hover effects on all cards
• Smooth scaling animations
• Glassmorphism design
• Floating background particles

---

🧪 Model Information

• Model: Naive Bayes (MultinomialNB)
• Vectorization: TF-IDF
• Training Data: Real-world email dataset
• Accuracy: ~95%+
• Repository: DarkNeuron-AI/darkneuron-spamdex-v1

Prediction Labels

• 0: Ham (Not Spam)
• 1: Spam

---

🛠️ Troubleshooting

Issue: Model not loading

Solution:

# Check if files are downloaded
from huggingface_hub import hf_hub_download
vectorizer_path = hf_hub_download(
    "DarkNeuron-AI/darkneuron-spamdex-v1", 
    "spam_detection_vectorizer.pkl"
)
print(f"Vectorizer loaded from: {vectorizer_path}")

Issue: CORS errors

Solution:

• Check if CORS middleware is enabled in app.py
• Ensure allow_origins=["*"] is set

Issue: Port already in use

Solution:

# Use a different port
uvicorn app:app --host 0.0.0.0 --port 8000

---

📊 Performance

• Average Response Time: < 200ms
• Model Size: ~2MB
• Memory Usage: ~50MB
• Concurrent Requests: 100+

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

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

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Developer

DarkNeuronAI

• GitHub: @Madara369Uchiha
• Hugging Face: DarkNeuron-AI

---

🙏 Acknowledgments

• Model trained using scikit-learn
• UI built with React and Tailwind CSS
• Backend powered by FastAPI
• Hosted on Hugging Face Spaces

---

📞 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Contact via Hugging Face
• Email: [[email protected]]

---

Crafted with ❤️ and passion by @Madara369Uchiha

⭐ Star this project if you find it helpful!