Enterprise AI Spam Detection Microservice

A decoupled Machine Learning architecture consisting of a containerized, high-performance REST API for inference and a modern client-side web application. The system leverages Natural Language Processing (NLP) to classify threat vectors in real-time with over 97% accuracy.

---

🏗️ Decoupled System Architecture

Unlike monolithic ML notebooks, this system is engineered for production enterprise environments using a strict client-server microservice pattern and Docker containerization.

[ Client UI (Streamlit) ] ──( HTTP POST /predict )──> [ Hugging Face Docker Container ]
                                                                     │
                                                           (FastAPI Inference Gateway)
                                                                     │
                                                       (Tokenization & Vector Mapping)
                                                                     ▼
[ Threat Analysis Dashboard ] <──( JSON Response )─── [ Logistic Regression Model (.pkl) ]

1. Inference Backend (FastAPI + Docker): A stateless, high-concurrency API layer deployed as a Docker container on Hugging Face Spaces. It ingests raw string payloads, performs regex tokenization, maps token distributions against a serialized 3,000-word vocabulary matrix, and returns confidence probabilities.
2. Client Interface (Streamlit): A server-side rendered frontend utilizing asynchronous HTTP requests to communicate with the remote ML Gateway. Designed with a sleek, dark-mode B2B SaaS aesthetic.

---

🧠 Machine Learning Pipeline

• Data Engineering: Processed a highly-dimensional dataset containing 5,000+ records pre-vectorized into a 3,000-column feature space.
• Model Selection: Trained and evaluated multiple probabilistic classifiers (MultinomialNB) and linear models (LogisticRegression).
• Performance Metrics: The Logistic Regression model achieved the highest convergence accuracy (97.4%) on the reserved testing set and was serialized via joblib for production deployment.
• Dynamic Feature Mapping: The production API dynamically maps raw user input to the exact feature dimensionality required by the serialized model using collections.Counter and pandas, eliminating the need for complex, memory-heavy vectorizer payloads.
• Dependency Pinning: Strict version control (scikit-learn==1.9.0) is enforced between the local training environment and the production Docker engine to prevent unpickling corruption.

---

🚀 API Endpoint Documentation

The FastAPI backend automatically generates interactive OpenAPI (Swagger) documentation available at the /docs route.

Endpoint: POST /predict

Content-Type: application/json

Request Payload:

{
  "content": "URGENT: Your account has been compromised. Click here to claim your reward."
}

Response Payload:

{
  "prediction": "Spam",
  "confidence": 0.9845,
  "status": 200
}

---

💻 Local Setup & Testing

1. Initialize Environment

git clone [https://github.com/engrmaziz/ml-spam-classifier.git](https://github.com/engrmaziz/ml-spam-classifier.git)
cd ml-spam-classifier
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Start the Inference API

Launch the FastAPI microservice locally on port 8000:

uvicorn api:app --reload

Visit http://localhost:8000/docs to view the interactive OpenAPI UI.

3. Launch the Client Dashboard

In a secondary terminal instance, configure your environment variables and start the frontend:

export API_URL="http://localhost:8000/predict"
streamlit run app.py

---

📦 Production Deployment

• Backend Engine: Deployed via custom Dockerfile (FROM python:3.12) to Hugging Face Spaces.
• Frontend UI: Deployed to Streamlit Community Cloud with secure environment variable routing.