ML Service - Complete Guide

Port: 8000
Language: Python (Flask)
ML Framework: scikit-learn, pandas, numpy
Model: XGBoost trained on discount prediction
Responsibility: Train discount prediction model, serve predictions

What ML Service Does

ML Service is the intelligent prediction engine:

✅ Train XGBoost discount prediction model
✅ Generate synthetic training data
✅ Serve real-time predictions
✅ Monitor model performance
✅ Retrain periodically with new data

Model Overview

What It Predicts

Input:
- Order total amount
- Number of items
- Time of day / day of week
- Customer history
- Customer loyalty

Output:
Discount class: 0%, 5%, 10%, 15%, or 20%
Confidence: 0.0 to 1.0

Model Architecture

XGBoost Classifier with 100 decision trees
- Max tree depth: 6
- Learning rate: 0.1
- Objective: multi-class classification
- Classes: [0%, 5%, 10%, 15%, 20%]

Input features: 11
Hidden layers: None (XGBoost is tree-based)
Output neurons: 5 (probability for each class)

Feature Engineering

Features Used

features = {
    1. "total_amount": float,
       # Order total in INR, range 200-5000

    2. "items_count": int,
       # Number of items in order, range 1-20

    3. "day_of_week": int,
       # 0=Monday to 6=Sunday

    4. "hour_of_day": int,
       # 0-23, representing order time

    5. "customer_order_count": int,
       # Total historical orders, range 0-500

    6. "customer_avg_spend": float,
       # Average INR per order, range 150-3000

    7. "order_frequency_days": int,
       # Days since last order, range 0-1000

    8. "has_vegetarian": int,
       # Binary: 1 if order has veg items

    9. "has_non_vegetarian": int,
       # Binary: 1 if order has non-veg items

    10. "is_weekend": int,
        # Binary: 1 if Friday-Sunday

    11. "month_of_year": int,
        # 1-12, for seasonal patterns
}

Training Pipeline

Data Collection

from datetime import datetime, timedelta
import pandas as pd

# Collect historical orders (6 months)
start_date = datetime.now() - timedelta(days=180)
end_date = datetime.now()

query = """
SELECT 
    order_id, total_amount, items_count,
    created_at, customer_id, customer.order_count
FROM orders
WHERE created_at BETWEEN ? AND ?
"""

df = pd.read_sql(query, connection)
# Result: 15,000+ historical orders

Data Preprocessing

# Clean data
df = df.dropna()
df = df[(df['total_amount'] > 0) & (df['total_amount'] < 10000)]

# Extract features
df['day_of_week'] = df['created_at'].dt.dayofweek
df['hour_of_day'] = df['created_at'].dt.hour
df['is_weekend'] = (df['day_of_week'] >= 5).astype(int)

# Get customer history
customer_history = df.groupby('customer_id').agg({
    'order_count': 'max',
    'total_amount': 'mean'
}).reset_index()
customer_history.rename(columns={
    'order_count': 'customer_order_count',
    'total_amount': 'customer_avg_spend'
}, inplace=True)

# Merge with main data
df = df.merge(customer_history, on='customer_id', how='left')

# Handle missing values
df.fillna(0, inplace=True)

print(f"Dataset: {len(df)} samples, {len(df.columns)} features")
# Dataset: 12,500 samples, 11 features

Label Creation

# Historical discounts applied (labels)
df['discount_applied'] = df['actual_discount_percentage']

# Map to classes
discount_classes = {
    0: 0,      # 0% discount
    5: 1,      # 5% discount
    10: 2,     # 10% discount
    15: 3,     # 15% discount
    20: 4      # 20% discount
}
df['discount_class'] = df['discount_applied'].map(discount_classes)

print(df['discount_class'].value_counts().sort_index())
# 0    4100  (33%)
# 1    2500  (20%)
# 2    3200  (26%)
# 3    1500  (12%)
# 4    1200  (9%)

Train-Test Split

from sklearn.model_selection import train_test_split

X = df[features_list]
y = df['discount_class']

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=42, stratify=y
)

print(f"Training set: {len(X_train)} samples")
print(f"Test set: {len(X_test)} samples")
# Training set: 10000 samples
# Test set: 2500 samples

Model Training

from xgboost import XGBClassifier

# Create model
model = XGBClassifier(
    n_estimators=100,
    max_depth=6,
    learning_rate=0.1,
    random_state=42,
    objective='multi:softprob',
    num_class=5,
    eval_metric='mlogloss'
)

# Train
model.fit(
    X_train, y_train,
    eval_set=[(X_test, y_test)],
    verbose=True
)

# Training time: 15-20 seconds

Model Evaluation

from sklearn.metrics import accuracy_score, precision_recall_fscore_support

y_pred = model.predict(X_test)

accuracy = accuracy_score(y_test, y_pred)
precision, recall, f1, _ = precision_recall_fscore_support(
    y_test, y_pred, average='weighted'
)

print(f"Accuracy: {accuracy:.2%}")
print(f"Precision: {precision:.2%}")
print(f"Recall: {recall:.2%}")
print(f"F1-Score: {f1:.2%}")

# Output:
# Accuracy: 79.2%
# Precision: 81.1%
# Recall: 77.5%
# F1-Score: 79.1%

Model Persistence

import joblib

# Save model
joblib.dump(model, 'models/discount_model.pkl')

# Model size: ~25MB
# Load model
model = joblib.load('models/discount_model.pkl')

Real-Time Prediction

Prediction Endpoint

POST http://localhost:8000/api/predict

Request:
{
  "total_amount": 1250,
  "items_count": 4,
  "day_of_week": 5,
  "hour_of_day": 19,
  "customer_order_count": 12,
  "customer_avg_spend": 1100,
  "order_frequency_days": 5,
  "has_vegetarian": 1,
  "has_non_vegetarian": 1,
  "is_weekend": 1,
  "month_of_year": 10
}

Response:
{
  "success": true,
  "data": {
    "predicted_discount_class": 2,
    "predicted_discount_percentage": 10,
    "class_probabilities": {
      "0%": 0.05,
      "5%": 0.15,
      "10%": 0.67,
      "15%": 0.10,
      "20%": 0.03
    },
    "confidence": 0.67,
    "inference_time_ms": 8
  }
}

Prediction Logic

# Load model
model = joblib.load('models/discount_model.pkl')

# Make prediction
X_input = np.array([feature_values])
prediction = model.predict(X_input)[0]
probabilities = model.predict_proba(X_input)[0]

# Get confidence (highest probability)
confidence = probabilities.max()

# Map to discount
discount_map = {0: 0, 1: 5, 2: 10, 3: 15, 4: 20}
predicted_discount = discount_map[prediction]

# Decision rule
if confidence > 0.7:
    return predicted_discount
else:
    return None  # Fall back to rule-based discount

Model Retraining

Retraining Schedule

Trigger 1: Daily at 2:00 AM
- Collect orders from previous day
- Retrain model with new data
- Validate performance
- If better → deploy new model

Trigger 2: Manual retraining
- Manager initiates retraining
- Collects last 6 months data
- Trains and validates
- Shows performance diff before deployment

Pipeline Automation

# scripts/train_model.py
import subprocess
import pandas as pd
from datetime import datetime

def train_model():
    print("Starting model training...")
    
    # 1. Collect data
    df = collect_training_data()
    print(f"Collected {len(df)} orders")
    
    # 2. Preprocess
    df = preprocess_data(df)
    
    # 3. Train
    model = train_xgboost(df)
    
    # 4. Evaluate
    metrics = evaluate_model(model, df)
    
    # 5. Save
    if metrics['accuracy'] > 0.78:
        joblib.dump(model, f'models/discount_model.pkl')
        print("Model saved successfully")
    else:
        print("Performance too low, keeping old model")
    
    return metrics

# Run daily
if __name__ == "__main__":
    metrics = train_model()

Database Schema

model ModelMetrics {
  id                      String   @id @default(uuid())
  model_version           String
  training_date           DateTime
  accuracy                Float
  precision               Float
  recall                  Float
  f1_score                Float
  test_samples            Int
  training_samples        Int
  features_count          Int
  feature_importance      Json
  created_at              DateTime @default(now())

  @@map("model_metrics")
}

Performance Characteristics

Model training: 15-20 seconds (on 10,000 samples)
Prediction latency: 8-12ms per request
Model size: ~25MB in memory
Throughput: 100+ predictions/second
Model accuracy: ~79% on test set

Testing ML Service

# Make prediction
curl -X POST http://localhost:8000/api/predict \
  -H "Content-Type: application/json" \
  -d '{
    "total_amount": 1250,
    "items_count": 4,
    "day_of_week": 5,
    "hour_of_day": 19,
    "customer_order_count": 12,
    "customer_avg_spend": 1100,
    "order_frequency_days": 5,
    "has_vegetarian": 1,
    "has_non_vegetarian": 1,
    "is_weekend": 1,
    "month_of_year": 10
  }'

# Response:
# Predicted discount: 10% with 67% confidence

Endpoints Summary

Method	Endpoint	Purpose	Auth
`POST`	`/api/predict`	Get discount prediction	Internal
`GET`	`/api/model/metrics`	Get model performance	JWT + MANAGER
`POST`	`/api/model/retrain`	Manually retrain	JWT + ADMIN

See Also:

DISCOUNT_ENGINE.md - How predictions are used
SYSTEM_OVERVIEW.md - ML Service in architecture

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ML Service - Complete Guide

What ML Service Does

Model Overview

What It Predicts

Model Architecture

Feature Engineering

Features Used

Training Pipeline

Data Collection

Data Preprocessing

Label Creation

Train-Test Split

Model Training

Model Evaluation

Model Persistence

Real-Time Prediction

Prediction Endpoint

Prediction Logic

Model Retraining

Retraining Schedule

Pipeline Automation

Database Schema

Performance Characteristics

Testing ML Service

Endpoints Summary

FilesExpand file tree

ML_SERVICE.md

Latest commit

History

ML_SERVICE.md

File metadata and controls

ML Service - Complete Guide

What ML Service Does

Model Overview

What It Predicts

Model Architecture

Feature Engineering

Features Used

Training Pipeline

Data Collection

Data Preprocessing

Label Creation

Train-Test Split

Model Training

Model Evaluation

Model Persistence

Real-Time Prediction

Prediction Endpoint

Prediction Logic

Model Retraining

Retraining Schedule

Pipeline Automation

Database Schema

Performance Characteristics

Testing ML Service

Endpoints Summary