Skip to content

README.md

Latest commit

 

History

History
303 lines (237 loc) · 9.83 KB

README.md

File metadata and controls

303 lines (237 loc) · 9.83 KB
Raw

🛒 E-Commerce Product Classifier

A production-grade NLP system that classifies product listings into 19 categories using fine-tuned DistilBERT — with real-time data drift detection, automated monitoring, and an interactive React analytics dashboard. Built the way ML systems actually run in production.

CI/CD Pipeline License: MIT Python 3.11 FastAPI React

The Problem This Solves

E-commerce platforms with millions of SKUs rely on accurate product categorization for search ranking, recommendations, and inventory management. Manual tagging doesn't scale. A misclassified product is effectively invisible to buyers searching the right category.

This system automates product classification at inference speeds of ~42ms per request — and crucially, detects when incoming product data starts drifting from the training distribution before accuracy silently degrades in production.

📊 Model Performance

Fine-tuned on 50,000 Amazon product samples across 19 categories.

Metric Score
Accuracy 68.3%
F1 Score (Macro) 0.641
Precision (Macro) 0.643
Recall (Macro) 0.683

Context: Macro F1 of 0.641 across 19 heavily imbalanced categories is the honest aggregate. The model excels in high-signal categories and struggles in semantically overlapping ones — a known challenge in multi-class product taxonomy. See per-category breakdown below.

Top-Performing Categories:

Category F1 Score
🎵 Digital Music 97.2%
👗 Amazon Fashion 85.8%
🎸 Musical Instruments 84.5%
🚗 Automotive 84.1%

Hardest Categories (semantically overlapping):

These categories share vocabulary (e.g., "Electronics" vs "Computers", "Toys" vs "Baby Products") — a known challenge in flat multi-class taxonomies that hierarchical classification would address.

🏗️ System Architecture

                        ┌─────────┐
                        │  User   │
                        └────┬────┘
                             │ HTTP POST
                             ▼
                   ┌──────────────────┐
                   │  FastAPI Backend  │
                   └────────┬─────────┘
                  Inference │         │ Log
                            │         │
                    ┌───────▼──┐   ┌──▼──────────────────┐
                    │DistilBERT│   │ SQLite Predictions DB │
                    │Classifier│   └──────────┬────────────┘
                    └───┬──────┘              │ Metrics
                   Sync │                     ▼
                        │         ┌───────────────────────┐
                        │         │   Performance Tracker  │
                        ▼         └───────────┬────────────┘
          ┌─────────────────────────┐         │ Real-time Data
          │ Evidently AI            │         │
          │ Drift Detector          │         │
          └────────────┬────────────┘         │
                Report │                      │
                        ▼                    ▼
                   ┌────────────────────────────┐
                   │       React Dashboard       │
                   └────────────────────────────┘

Flow:

  1. Product listing hits the FastAPI endpoint
  2. DistilBERT classifier runs inference (~42ms)
  3. Prediction + metadata logged to SQLite
  4. Evidently AI monitors incoming text distribution via PSI
  5. Performance Tracker computes rolling accuracy metrics
  6. React Dashboard visualizes everything in real time

✨ Features

🛠️ Backend (FastAPI)

  • Async inference — single and batch prediction endpoints
  • Pydantic v2 validation — strict input/output schema enforcement
  • Automated logging — every request logged with latency, confidence score, and prediction

📈 Monitoring & Observability

  • Data drift detection — Evidently AI monitors text distribution shifts using Population Stability Index (PSI)
  • Performance tracking — SQLite-backed persistent logging with rolling metric calculations
  • A/B testing infrastructure — Chi-square framework for comparing model versions before promoting to production

💻 React Analytics Dashboard

  • Real-time accuracy trends and confidence distribution charts
  • Inference latency monitoring
  • Interactive model playground for live predictions
  • Drift status indicators and system health view
  • Per-category performance breakdown

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • Node.js 20+
  • Docker (optional)

1. Clone the repository

git clone https://github.com/Emart29/ecommerce-product-classifier.git
cd ecommerce-product-classifier

2. Set up the Python environment

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Initialize data directories

mkdir -p data/monitoring/drift_reports

4. Start the API server

python -m src.api.main

API live at http://localhost:8000 · Swagger UI at /docs

5. Start the React dashboard

cd frontend
npm install
npm run dev

Dashboard live at http://localhost:5173

Docker (one command)

docker-compose up --build

📡 API Reference

POST /predict — Classify a single product

Request:

{
  "title": "Acoustic Guitar Starter Pack with Tuner and Bag"
}

Response:

{
  "category": "Musical Instruments",
  "confidence": 0.921,
  "latency_ms": 42.3
}

POST /predict/batch — Classify multiple products

Accepts an array of product objects. Full interactive docs at /docs.

🧪 Running Tests

# Full test suite
PYTHONPATH=. pytest tests/ -v

# Monitoring-specific tests
PYTHONPATH=. pytest tests/test_monitoring.py -v

📁 Project Structure

ecommerce-product-classifier/
├── src/
│   └── api/                    # FastAPI routes, schemas, inference
├── frontend/                   # React analytics dashboard
├── models/                     # Fine-tuned DistilBERT weights & config
├── data/
│   └── monitoring/
│       └── drift_reports/      # Evidently AI HTML drift reports
├── scripts/                    # Data generation & evaluation utilities
├── tests/                      # Pytest test suite
├── .github/workflows/          # CI/CD pipeline (lint → test → Docker build)
├── docker-compose.yml
├── Dockerfile
├── params.yaml                 # Configurable model & training params
└── requirements.txt

🛠️ Tech Stack

Layer Technologies
ML / NLP PyTorch, HuggingFace Transformers, DistilBERT, Scikit-learn
Monitoring Evidently AI (PSI drift detection)
Backend FastAPI, Uvicorn, SQLAlchemy, Pydantic v2
Frontend React (Vite), Tailwind CSS v4, Chart.js, Lucide Icons
DevOps Docker, Docker Compose, Pytest, GitHub Actions

🔄 CI/CD Pipeline

Every push triggers an automated pipeline:

Push / PR → Lint (black + flake8) → Tests (pytest) → Docker Build

The pipeline enforces code quality and validates the container builds correctly before any merge — the same pattern used in production ML systems.

📌 Key Engineering Decisions

Why DistilBERT over a larger model? DistilBERT is 40% smaller and 60% faster than BERT-base with 97% of the performance. For a classification API serving real-time requests, latency matters more than marginal accuracy gains.

Why Evidently AI for drift detection? Most ML systems degrade silently — accuracy drops weeks before anyone notices. PSI-based drift detection catches distribution shifts early, giving teams time to retrain before users are impacted.

Why SQLite for monitoring logs? For a single-instance deployment, SQLite is zero-infrastructure, fast enough for rolling metrics, and trivially replaceable with PostgreSQL when scaling horizontally.

🗺️ Roadmap

  • Hierarchical classification to resolve overlapping categories
  • Model versioning with automatic promotion/rollback
  • Streaming predictions for large batch jobs
  • PostgreSQL migration for multi-instance deployment
  • Alerting (Slack/email) on drift threshold breach

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branch naming, code style, commit conventions, and the PR process.

📄 License

Distributed under the MIT License. See LICENSE for details.

Built by Emmanuel Nwanguma
LinkedIn · GitHub · Email