Heimdall SMS Guard
Heimdall SMS Guard 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
Component Value Vectorizer TfidfVectorizerAnalyzer char_wbn-gram range (3, 5)Classifier LogisticRegressionClass weight balancedSolver liblinearDecision threshold 0.41
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).
Metric Value Accuracy 0.9884 Spam Precision 0.9485 Spam Recall 0.9583 Spam F1 0.9534 False Positives 5 False Negatives 4
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
1 pip install -r requirements.txt
2 python inference.py
Programmatic use:
1 from inference import predict
2
3 result = predict ( "Free entry to win a prize. Text WIN to 12345." )
4 print ( result )
5 # {'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
File Purpose model.joblibTrained pipeline + threshold + config inference.pyLoader + predict() API requirements.txtRuntime dependencies metrics.jsonFinal test metrics example_inputs.jsonSample ham + spam messages limitations.mdFull limitations writeup
License
MIT
