pancodurden/Heimdall-sms-guard

Heimdall SMS Guard

[image]

Lightweight SMS spam classifier. Character n-gram TF-IDF features fed into a class-balanced Logistic Regression, with a tuned decision threshold.

Small, fast, CPU-only, no GPU required. Suitable for demos, baselines, and educational use.

Model Architecture

Pipeline serialized via joblib as a dict {pipeline, threshold, config}.

Test Metrics

Evaluated on a held-out stratified test split (774 messages, 12.40% spam).

Intended Use

• —SMS spam classification demos
• —Baseline benchmark for stronger spam models
• —Education / coursework on text classification
• —Research on lightweight NLP pipelines

Not Intended Use

• —Live consumer SMS filtering at scale
• —Anti-fraud or anti-phishing in financial messaging
• —Regulated communications filtering
• —Multilingual or non-English SMS
• —Image / MMS / RCS content

Limitations

See limitations.md for full detail.

• —Trained on an older English SMS spam dataset
• —May not generalize to modern spam patterns
• —Weak against unicode obfuscation, emoji-heavy spam, shortened links, callback scams
• —May produce false positives on transactional messages (OTP, 2FA, bank alerts, delivery notifications)
• —No drift detection or live monitoring included

Local Inference

pip install -r requirements.txt
python inference.py

Programmatic use:

from inference import predict

result = predict("Free entry to win a prize. Text WIN to 12345.")
print(result)
# {'label': 'spam', 'label_id': 1, 'spam_probability': 0.97, 'threshold': 0.41}

Status

Demo-ready. Not production-ready.

For production deployment, additional work required: monitoring, drift detection, fallback strategy, input validation hardening, threshold recalibration on live traffic, and privacy-aware logging.

Files

License

MIT