README.md

metadata

title: SMS Classifier API
emoji: 📱
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

SMS Classifier API

REST API that classifies SMS messages into operational categories using multilingual DistilBERT fine-tuned on a synthetic bilingual dataset (ES + EN).

Live demo: https://cmeneses99-sms-classifier-api.hf.space

Categories

Category	Description
transaction	Payment confirmations, debits and transfers
otp_verification	One-time codes for identity verification
promotion_offer	Discounts, coupons and merchant offers
security_alert	Unrecognized access and suspicious activity
delivery_logistics	Shipment status and order tracking
appointment_reminder	Medical and dental appointment reminders
customer_service	Tickets, claims and support updates
spam_advertising	Fraudulent messages and misleading advertising
billing_reminder	Pending invoices and payment due dates

Tech stack

• Python 3.11 + FastAPI + Uvicorn
• DistilBERT (distilbert-base-multilingual-cased) via HuggingFace Transformers
• PyTorch (CPU-only in production)
• Pydantic v2 for validation
• Docker for containerization
• Hugging Face Spaces for deployment
• Hugging Face Hub for model hosting

Project structure

app/
├── main.py                      # App entry point
├── utils.py                     # normalize(), read_static()
├── core/                        # Shared infrastructure
│   ├── cache.py                 # Thread-safe LRU cache
│   ├── model_loader.py          # Downloads and loads the model at startup
│   ├── schemas.py               # Pydantic models
│   └── category_meta.py         # Category metadata
├── services/
│   └── classifier.py            # Inference logic + LRU cache integration
├── api/                         # JSON endpoints
│   ├── inference.py             # POST /classify, POST /classify/batch
│   └── meta.py                  # GET /health, GET /api/categories
├── web/                         # HTML endpoints
│   └── pages.py                 # UI routes
└── templates/                   # HTML files
    ├── home.html
    ├── index.html
    ├── batch.html
    └── categories.html
training/
├── config.py                    # Hyperparameters
├── generate_dataset.py          # Generates training/data/sms_dataset.csv
├── train.py                     # Fine-tuning script
└── eval_report.py               # Per-category metrics report

Run locally

Requirements

• Python 3.11+
• Trained model in ./model/ (see training section)

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Linux/Mac

# Install dependencies
pip install -r requirements.txt
pip install torch --index-url https://download.pytorch.org/whl/cpu

# Start API
uvicorn app.main:app --reload

API available at http://localhost:8000

With Docker

docker compose up --build

Train the model

pip install -r requirements-training.txt

cd training
python generate_dataset.py   # generates training/data/sms_dataset.csv
python train.py              # fine-tuning → saves model to ./model/
python eval_report.py        # per-category metrics report

Endpoints

Method	Route	Description
GET	/	Home with API description
GET	/classify	Interactive single classifier (UI)
GET	/classify/batch	Batch classifier (UI)
GET	/categories	Categories view with examples
POST	/classify	Classify one message (JSON)
POST	/classify/batch	Classify multiple messages (JSON)
GET	/api/categories	List categories (JSON)
GET	/health	Service status and cache stats

POST /classify

curl -X POST http://localhost:8000/classify \
  -H "Content-Type: application/json" \
  -d '{"text": "Your OTP code is 482910. Do not share it."}'

{
  "text": "Your OTP code is 482910. Do not share it.",
  "prediction": {
    "category": "otp_verification",
    "confidence": 0.9821
  },
  "top_3": [
    { "category": "otp_verification", "confidence": 0.9821 },
    { "category": "security_alert",   "confidence": 0.0091 },
    { "category": "customer_service", "confidence": 0.0044 }
  ],
  "cached": false
}

POST /classify/batch

curl -X POST http://localhost:8000/classify/batch \
  -H "Content-Type: application/json" \
  -d '{"texts": ["Your OTP code is 482910.", "Your card was charged $45 at Amazon."]}'

{
  "results": [...],
  "total": 2,
  "from_cache": 0
}

Deploy on Hugging Face Spaces

1. Create a Space at huggingface.co/new-space with SDK: Docker
2. Push the code to the Space repo:

   git remote add hfspace https://USER:TOKEN@huggingface.co/spaces/USER/SPACE-NAME
   git push hfspace main
   

3. HF Spaces detects the Dockerfile automatically and builds the image
4. On startup, the model is downloaded from HF Hub (~520MB, first time only)

Model hosted at huggingface.co/cmeneses99/sms-classifier.