You can deploy this model and start earning money today!

M-Arjun/
SpamShield

M-Arjun/SpamShield-Datasets

mit

Views

No views yet

SpamShield: Multilingual Spam Detection & Category Classification

License: MIT

High-performance multilingual spam detection with precise category classification. Dual-model architecture: Binary spam detection + 6-category classification. Lightweight, ultra-fast ONNX inference.

Quick Start • Models • Categories • Performance • Usage

Live Demo on Hugging Face Spaces

📋 Overview

SpamShield is a production-grade machine learning model for accurate spam detection and intelligent categorization across multiple languages. It uses a dual-model architecture:

Binary Model: Spam vs. Ham classification
Category Model: Multi-class spam categorization (6 categories)

Built with ONNX for maximum performance, it powers moderation systems in numerous production deployments.

Key Features

✅ Binary + Category Classification: Detects spam AND identifies the type
✅ 6 Spam Categories: Phishing, Job Scams, Cryptocurrency, Adult Content, Giveaway Scams, Marketing
✅ ONNX-Powered: 3-5x faster than sklearn, runs everywhere
✅ Minimal Footprint: Models 3-5MB each, <15MB total RAM usage
✅ Sub-5ms Inference: Production-grade latency
✅ Multilingual: 8 languages supported
✅ 93%+ Accuracy: Category-level precision
✅ Smart Heuristics: Context-aware rules + ML for robust detection

🚀 Quick Start

Installation

bash

# Core dependencies
pip install numpy onnxruntime

# Optional: for preprocessing
pip install scikit-learn

30-Second Example

python

import numpy as np
import onnxruntime as ort

# Load ONNX models
binary_model = ort.InferenceSession('binary_model.onnx', 
                                    providers=['CPUExecutionProvider'])
category_model = ort.InferenceSession('category_model.onnx', 
                                      providers=['CPUExecutionProvider'])

# Classify a message
text = "Congratulations! You've won a free iPhone. Click here to claim!"

# For simplicity, assume text is vectorized to numpy array
# In production, use the vectorizer to prepare input
# This example shows the inference pattern
input_array = np.array([[text]], dtype=object)

# Binary prediction (spam or not)
binary_output = binary_model.run(None, {'input': input_array})
is_spam = binary_output[0][0]  # 0 or 1
confidence = float(binary_output[1][0].get(1, 0.0))

if is_spam:
    # Category prediction
    category_output = category_model.run(None, {'input': input_array})
    category = category_output[0][0]
else:
    category = "normal"

print(f"🚨 SPAM: {is_spam} | Category: {category} | Confidence: {confidence:.2f}")

Output:

🚨 SPAM: True | Category: giveaway | Confidence: 0.94

🎯 Model Architecture

SpamShield uses a two-stage prediction pipeline:

Stage 1: Binary Classification

Determines if a message is spam or legitimate (ham).

Models:

v0.4 (Full): 10K word + 5K char n-gram features
v0.4-lite (Optimized): 3K word + 2K char n-gram features

Model	ONNX Size	RAM	Speed	Accuracy
v0.4	3-4 MB	12 MB	3-5ms	97.2%
v0.4-lite	1-2 MB	5 MB	1-3ms	94.3%

Output:

python

{
    "is_spam": bool,
    "confidence": float  # 0.0 to 1.0
}

Stage 2: Category Classification

If spam is detected, classifies into one of 6 categories.

Same model versions as Stage 1 (same dataset, different training targets)

Model	ONNX Size	RAM	Speed	Accuracy
v0.4	3-4 MB	12 MB	2-4ms	93.6%
v0.4-lite	1-2 MB	5 MB	1-2ms	80.2%

Output:

python

{
    "category": "phishing" | "job_scam" | "crypto" | "adult" | "giveaway" | "marketing"
}

🏷️ Spam Categories

SpamShield classifies spam into 6 distinct categories:

1. Phishing 🎣

Credential harvesting, fake login pages, account verification scams.

Keywords: verify, confirm, account, password, urgent, click, suspicious activity
Examples: "Your account has been compromised. Click here to verify."

2. Job Scams 💼

Employment fraud, remote work scams, get-rich-quick employment offers.

Keywords: earn, work from home, $, per day, no experience needed
Examples: "Earn $5000/week from home! No experience needed!"

3. Cryptocurrency 💰

Crypto promotions, NFT scams, blockchain investment fraud.

Keywords: crypto, bitcoin, NFT, airdrop, crypto coin, blockchain
Examples: "Free Bitcoin airdrop! Claim your free crypto now!"

4. Adult Content 🔞

Explicit content promotion, adult services, dating spam.

Keywords: adult, dating, meet, explicit, +18
Examples: "Meet hot singles in your area right now!"

5. Giveaway Scams 🎁

Fake prize/lottery/raffle scams, "you've won" fraud.

Keywords: won, winner, prize, claim reward, lottery, jackpot, free iPhone
Examples: "Congratulations! You won a free iPhone. Claim now!"

6. Marketing/Promotional 📢

Unsolicited marketing, spam advertisements, promotional campaigns.

Keywords: offer, limited time, discount, buy now, act now
Examples: "Limited time offer! 50% off everything. Buy now!"

🔮 ONNX-Powered Inference

SpamShield is ONNX-native, meaning both models are available exclusively in ONNX format for maximum performance:

Why ONNX?

Feature	ONNX	Sklearn
Speed	⚡⚡⚡ 3-5x faster	⚡ Baseline
File Size	🎯 30-40% smaller	📦 Full size
Cross-Platform	✅ iOS, Android, Web, Linux, Windows	❌ Python only
Deployment	🚀 Edge, Mobile, Browser	🖥️ Server only
Dependencies	📦 Minimal (ONNX Runtime)	📚 Heavy (scikit-learn)
RAM Usage	💨 <15MB	🐘 20-30MB

ONNX Inference Examples

Python with ONNX Runtime

python

import onnxruntime as ort
import numpy as np

# Load models
binary_sess = ort.InferenceSession('binary_model.onnx')
category_sess = ort.InferenceSession('category_model.onnx')

# Prepare text (vectorized)
text = "Free money click here!!!"
input_array = np.array([[text]], dtype=object)

# Binary prediction
binary_out = binary_sess.run(None, {'input': input_array})
is_spam = binary_out[0][0] == 1
spam_confidence = float(binary_out[1][0].get(1, 0.0))

# Category prediction (if spam)
if is_spam:
    category_out = category_sess.run(None, {'input': input_array})
    category = category_out[0][0]
else:
    category = "normal"

print(f"Spam: {is_spam}, Category: {category}, Confidence: {spam_confidence:.4f}")

JavaScript (ONNX.js in Browser)

javascript

const ort = require('onnxruntime-web');

async function detectSpam(text) {
    const binarySession = await ort.InferenceSession.create('binary_model.onnx');
    const categorySession = await ort.InferenceSession.create('category_model.onnx');
    
    // Prepare input
    const input = new ort.Tensor('string', [[text]], [1, 1]);
    
    // Run inference
    const binaryResult = await binarySession.run({ input });
    const isSpam = binaryResult.output0.data[0] === 1;
    
    if (isSpam) {
        const categoryResult = await categorySession.run({ input });
        const category = categoryResult.output0.data[0];
        return { isSpam, category, confidence: 0.95 };
    }
    
    return { isSpam: false, category: 'normal' };
}

Mobile (iOS/Android)

swift

// iOS with Core ML (converted from ONNX)
import CoreML

let model = try! BinaryModel_onnx(configuration: MLModelConfiguration())
let input = BinaryModel_onnxInput(input: "message text here")
let output = try! model.prediction(input: input)
let isSpam = output.output0 == 1

📊 Datasets

Data Composition

Training data combines curated open-source datasets with synthetic augmentation for comprehensive coverage:

Dataset Statistics

Language	Total Messages	Normal (Ham)	Spam	Spam %
English	119,105	59,903	59,202	49.7%
Spanish	16,595	7,683	8,912	53.7%
Chinese	13,442	7,549	5,893	43.8%
Arabic	2,642	993	1,649	62.4%
Hinglish	2,385	1,368	1,017	42.6%
German	2,115	928	1,187	56.1%
Russian	1,235	635	600	48.6%
French	1,116	550	566	50.7%
🎯 TOTAL	158,635	79,609	79,026	49.8%

Data Sources & Attribution

Primary Open-Source Datasets

The model is trained on carefully curated data from multiple open-source datasets combined with extensive synthetic augmentation:

Open-Source Components:

Multiple public spam/ham message datasets
Community-contributed multilingual spam corpora
Research-backed offensive language and spam detection datasets
Email and SMS spam classification datasets

Synthetic Data Generation (35-40% of Training Set):

Extensive synthetic data was generated to ensure:

Balanced category representation: All 6 spam types equally represented
Comprehensive coverage: Edge cases, variations, and emerging spam patterns
Privacy compliance: No real personal data in synthetic samples
Realistic patterns: Generated data follows observed spam tactics

Synthesis Techniques:

Paraphrasing & variation of base patterns
Contextual generation based on category-specific tactics
Multilingual translation & back-translation
Character-level variations (leet speak, spacing, unicode tricks)
Domain-specific synthesis for each spam category

Category-Specific Synthesis:

Phishing: Account verification attempts, fake bank alerts, credential requests
Job Scams: Remote work offers, get-rich-quick employment, commission-based jobs
Crypto: Airdrop claims, NFT promotions, trading bot ads, coin pump schemes
Adult Content: Dating/escort promotions, explicit content links
Giveaway: Prize winner notifications, free device claims, lottery scams
Marketing: Product promotions, discount codes, time-limited offers

Data Quality Assurance

All datasets underwent rigorous preprocessing:

✅ Unicode normalization (NFD)
✅ Language-specific tokenization
✅ Duplicate and near-duplicate removal (Jaccard > 0.95)
✅ PII scrubbing (emails, phone numbers, credit cards)
✅ Balanced class sampling (50/50 spam-ham target)
✅ Metadata validation and spot-checking

Category Distribution (Spam Only)

Category	% of Spam
Phishing	18%
Job Scams	14%
Cryptocurrency	16%
Adult Content	12%
Giveaway Scams	22%
Marketing	18%

📈 Performance Metrics

Binary Classification (Spam vs. Ham)

By Language

Language	Precision	Recall	F1-Score	Accuracy
English	98.0%	96.7%	97.4%	97.2%
Spanish	94.2%	92.1%	93.1%	92.8%
Chinese	91.3%	89.5%	90.4%	90.1%
Arabic	92.8%	90.6%	91.7%	91.2%
Hinglish	89.1%	86.8%	87.9%	87.5%
German	93.5%	91.8%	92.6%	92.3%
Russian	90.4%	88.7%	89.5%	89.1%
French	92.1%	90.3%	91.2%	90.8%

Category Classification (Multi-Class)

v0.4 Model:

Overall Accuracy: 93.6%
Weighted F1: 0.9435
Per-Category F1 Scores:
- Phishing: 95.2%
- Job Scam: 93.1%
- Crypto: 94.8%
- Adult: 92.3%
- Giveaway: 91.7%
- Marketing: 88.9%

v0.4-lite Model:

Overall Accuracy: 80.2%
Weighted F1: 0.8434
Optimized for speed (1-2ms inference)

Inference Performance Benchmarks

Model	Task	ONNX Size	RAM	Speed	Accuracy
v0.4 Binary	Spam/Ham	3-4 MB	12 MB	3-5ms	97.2%
v0.4 Category	6-class	3-4 MB	12 MB	2-4ms	93.6%
v0.4-lite Binary	Spam/Ham	1-2 MB	5 MB	1-3ms	94.3%
v0.4-lite Category	6-class	1-2 MB	5 MB	1-2ms	80.2%

Threshold Settings

Config	Threshold	Use Case
Default	0.49	Balanced precision/recall
High Precision	0.65+	Minimize false positives
High Recall	0.35	Catch more spam
Short Text	0.77	<35 words
Very Short	0.85	<10 words

💻 Usage

Complete Example: Full Pipeline

python

import numpy as np
import onnxruntime as ort
from sklearn.feature_extraction.text import TfidfVectorizer
import pickle

# Load models
binary_model = ort.InferenceSession('binary_model.onnx')
category_model = ort.InferenceSession('category_model.onnx')

# Load vectorizer (trained during model creation)
with open('vectorizer.pkl', 'rb') as f:
    vectorizer = pickle.load(f)

def detect_spam(text, threshold=0.49):
    """Complete spam detection with category"""
    
    # Preprocess and vectorize
    X = vectorizer.transform([text]).astype(np.float32)
    
    # Binary prediction
    binary_inputs = {binary_model.get_inputs()[0].name: X.toarray()}
    binary_outputs = binary_model.run(None, binary_inputs)
    
    spam_prob = float(binary_outputs[1][0].get(1, 0.0))
    is_spam = spam_prob >= threshold
    
    result = {
        'text': text,
        'is_spam': is_spam,
        'confidence': round(spam_prob, 4),
    }
    
    # Category prediction (if spam)
    if is_spam:
        category_inputs = {category_model.get_inputs()[0].name: X.toarray()}
        category_outputs = category_model.run(None, category_inputs)
        result['category'] = category_outputs[0][0]
    else:
        result['category'] = 'normal'
    
    return result

# Test
messages = [
    "Hey, how are you doing?",
    "Congratulations! You won a free iPhone!",
    "Click here to verify your account",
    "Work from home and earn $5000/week",
]

for msg in messages:
    result = detect_spam(msg)
    print(f"{msg:<45} => {result['is_spam']:>5} | {result['category']:<12} ({result['confidence']:.2f})")

Output:

Hey, how are you doing?                    =>  False | normal       (0.12)
Congratulations! You won a free iPhone!    =>   True | giveaway     (0.94)
Click here to verify your account          =>   True | phishing     (0.91)
Work from home and earn $5000/week         =>   True | job_scam     (0.88)

Batch Processing with Pandas

python

import pandas as pd
import numpy as np
import onnxruntime as ort
import pickle

# Load models and vectorizer
binary_model = ort.InferenceSession('binary_model.onnx')
category_model = ort.InferenceSession('category_model.onnx')

with open('vectorizer.pkl', 'rb') as f:
    vectorizer = pickle.load(f)

# Load data
df = pd.read_csv('messages.csv')  # columns: 'text'

# Vectorize all messages
X = vectorizer.transform(df['text']).astype(np.float32)

# Binary predictions
binary_inputs = {binary_model.get_inputs()[0].name: X.toarray()}
binary_outputs = binary_model.run(None, binary_inputs)

df['spam_prob'] = [float(p.get(1, 0.0)) for p in binary_outputs[1]]
df['is_spam'] = df['spam_prob'] >= 0.49

# Category predictions (for spam messages only)
spam_mask = df['is_spam']
df['category'] = 'normal'

category_inputs = {category_model.get_inputs()[0].name: X[spam_mask].toarray()}
category_outputs = category_model.run(None, category_inputs)
df.loc[spam_mask, 'category'] = category_outputs[0]

# Save results
df.to_csv('messages_classified.csv', index=False)
print(df.head())

FastAPI Server

python

from fastapi import FastAPI
import onnxruntime as ort
import numpy as np
import pickle

app = FastAPI(title="SpamShield API")

# Load at startup
binary_model = ort.InferenceSession('binary_model.onnx')
category_model = ort.InferenceSession('category_model.onnx')

with open('vectorizer.pkl', 'rb') as f:
    vectorizer = pickle.load(f)

@app.post("/detect")
async def detect_spam(text: str, threshold: float = 0.49):
    """Detect spam and classify category"""
    
    X = vectorizer.transform([text]).astype(np.float32)
    
    # Binary
    binary_inputs = {binary_model.get_inputs()[0].name: X.toarray()}
    binary_outputs = binary_model.run(None, binary_inputs)
    spam_prob = float(binary_outputs[1][0].get(1, 0.0))
    is_spam = spam_prob >= threshold
    
    # Category
    if is_spam:
        category_inputs = {category_model.get_inputs()[0].name: X.toarray()}
        category_outputs = category_model.run(None, category_inputs)
        category = category_outputs[0][0]
    else:
        category = 'normal'
    
    return {
        'text': text,
        'is_spam': is_spam,
        'category': category,
        'confidence': round(spam_prob, 4),
        'threshold_used': threshold
    }

# Run: uvicorn app:app --reload
# Test: curl -X POST "http://localhost:8000/detect?text=Free+money+click+here"

Flask Server

python

from flask import Flask, request, jsonify
import onnxruntime as ort
import numpy as np
import pickle

app = Flask(__name__)

# Load models
binary_model = ort.InferenceSession('binary_model.onnx')
category_model = ort.InferenceSession('category_model.onnx')

with open('vectorizer.pkl', 'rb') as f:
    vectorizer = pickle.load(f)

@app.route('/detect', methods=['POST'])
def detect():
    data = request.json
    text = data.get('text', '')
    threshold = data.get('threshold', 0.49)
    
    X = vectorizer.transform([text]).astype(np.float32)
    
    # Binary
    binary_inputs = {binary_model.get_inputs()[0].name: X.toarray()}
    binary_outputs = binary_model.run(None, binary_inputs)
    spam_prob = float(binary_outputs[1][0].get(1, 0.0))
    is_spam = spam_prob >= threshold
    
    # Category
    if is_spam:
        category_inputs = {category_model.get_inputs()[0].name: X.toarray()}
        category_outputs = category_model.run(None, category_inputs)
        category = category_outputs[0][0]
    else:
        category = 'normal'
    
    return jsonify({
        'is_spam': is_spam,
        'category': category,
        'confidence': round(spam_prob, 4)
    })

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Advanced: Custom Thresholds by Category

python

# Different thresholds for different categories
CATEGORY_THRESHOLDS = {
    'phishing': 0.60,      # High precision for phishing
    'job_scam': 0.55,      # Phishing-adjacent
    'crypto': 0.65,        # Very strict
    'adult': 0.50,         # Standard
    'giveaway': 0.45,      # More permissive
    'marketing': 0.40,     # Most permissive
}

def detect_with_category_threshold(text):
    X = vectorizer.transform([text]).astype(np.float32)
    
    # Get initial prediction
    binary_inputs = {binary_model.get_inputs()[0].name: X.toarray()}
    binary_outputs = binary_model.run(None, binary_inputs)
    spam_prob = float(binary_outputs[1][0].get(1, 0.0))
    
    # Get category
    category_inputs = {category_model.get_inputs()[0].name: X.toarray()}
    category_outputs = category_model.run(None, category_inputs)
    category = category_outputs[0][0]
    
    # Apply category-specific threshold
    threshold = CATEGORY_THRESHOLDS.get(category, 0.49)
    is_spam = spam_prob >= threshold
    
    return {
        'is_spam': is_spam,
        'category': category,
        'confidence': spam_prob,
        'threshold_used': threshold
    }

⚙️ Technical Details

Model Architecture

Framework: ONNX (Open Neural Network Exchange)
Base Algorithm: Logistic Regression
Feature Extraction: TF-IDF Vectorizer
Language Support: 8 languages

Training Configuration

python

# Vectorizer
TfidfVectorizer(
    max_features=10000,        # v0.4 / 3000 for lite
    ngram_range=(1, 2),        # Unigrams + bigrams
    analyzer='char_wb',        # Character-based
    sublinear_tf=True,
    strip_accents='unicode',
    lowercase=True,
    norm='l2'
)

# Classifier
SGDClassifier(
    loss='log_loss',          # Logistic regression
    penalty='l2',             # L2 regularization
    alpha=1e-4,
    max_iter=1000,
    random_state=42,
    class_weight='balanced',
    solver='saga',
    n_jobs=-1
)

ONNX Model Specification

Both binary and category models are ONNX-native:

json

{
  "input_type": "string",
  "input_shape": [null, 1],
  "output_format": "int64 label + probability dictionary",
  "vectorization": "embedded in ONNX graph",
  "conversion_method": "skl2onnx pipeline",
  "providers": ["CPUExecutionProvider"]
}

⚠️ Limitations

Known Constraints

Language Coverage: Best on English; varies for low-resource languages
Context: Cannot understand sarcasm, humor, or cultural references
Domain Shift: Performance degrades on completely unseen domains
Adversarial: Vulnerable to intentional obfuscation and adversarial text
False Positives: Legitimate promotional messages may be flagged
False Negatives: Sophisticated spam may evade detection
Temporal Drift: Spam patterns evolve; retraining recommended every 3-6 months

Ethical Usage Guidelines

SpamShield should be used responsibly:

⚠️ Human Review Required: Never use for autonomous enforcement without human review
⚠️ Monitor for Bias: Regularly audit predictions across user groups
⚠️ Transparency: Inform users that automated moderation is active
⚠️ Appeal Mechanism: Provide clear paths for users to contest decisions
⚠️ Compliance: Ensure usage complies with GDPR, CCPA, and local laws
⚠️ No Autonomous Banning: Always maintain human-in-the-loop for enforcement

Recommended Safeguards

python

# For production: High confidence threshold + human review
ENFORCEMENT_THRESHOLD = 0.75

if spam_confidence >= ENFORCEMENT_THRESHOLD:
    # Flag for human moderator review
    flag_for_review(message, category, confidence)
else:
    # For borderline cases, always require human review
    if 0.5 <= spam_confidence < ENFORCEMENT_THRESHOLD:
        flag_for_review(message, category, confidence)

🏆 Attribution & Credits

Development & Maintenance

Arjun-M (@Arjun-M) - Model development, optimization, and maintenance

Dataset Sources & Acknowledgments

We gratefully acknowledge:

Academic Institutions

University of Colorado Boulder - OLID dataset (Offensive Language Identification)
Carnegie Mellon University - Enron Email Corpus
UCI Machine Learning Repository - SMS Spam Collection Dataset

Open-Source Communities

ONNX Project - Model standardization and cross-platform deployment
Scikit-learn - Machine learning framework
NumPy - Scientific computing
ONNX Runtime - Inference engine

Language & Domain Specialists

Chinese NLP research community
Hindi/Hinglish language researchers
Multilingual offensive language identification teams
Spam detection research community

Special Thanks

This project builds upon decades of NLP and spam detection research. We thank all dataset creators, researchers, and the open-source community for making this work possible.

📜 License

Model License

SpamShield: MIT License

Free for use, modification, and distribution in open-source and commercial projects.

text

MIT License

Copyright (c) 2026 Arjun-M

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

Dataset License

Training Datasets: Creative Commons Attribution 4.0 International (CC-BY-4.0)

When using datasets:

✅ Attribute original dataset creators
✅ Include license notice in distributed works
✅ May use for commercial purposes
✅ May modify and adapt

📚 Citation

Please cite SpamShield in research or projects:

BibTeX

bibtex

@software{spamshield2026,
  author = {Arjun-M},
  title = {SpamShield: Multilingual Spam Detection \& Category Classification},
  year = {2026},
  url = {https://huggingface.co/M-Arjun/SpamShield},
  note = {ONNX-based dual-model architecture with binary spam detection 
          and 6-category classification}
}

Plain Text

Arjun-M. (2026). SpamShield: Multilingual Spam Detection & Category Classification. 
Retrieved from https://huggingface.co/M-Arjun/SpamShield

📦 What's Included

✅ 2 ONNX Models (Binary + Category)
✅ 2 Model Versions (v0.4 Full & v0.4-lite Optimized)
✅ Vectorizer (TF-IDF pre-trained, ready to use)
✅ Complete Documentation (Usage, API, examples)
✅ Metadata Configuration (Thresholds, settings)
✅ Performance Benchmarks (By language, by category)
✅ Integration Examples (Python, FastAPI, Flask, JavaScript)
✅ Full Attribution (Dataset sources and credits)

🚀 Production Deployments

SpamShield powers spam detection and content moderation in numerous production systems across different platforms and scales.

🔗 Resources

ONNX Documentation: onnxruntime.ai
Scikit-learn Docs: scikit-learn.org
TF-IDF Vectorizer: sklearn TfidfVectorizer
ONNX Model Specs: onnx.ai

Made with ❤️ for open-source content moderation

Last Updated: April 18, 2026

If you find SpamShield helpful, please give it a ⭐ on Hugging Face!