ash469/smart-return-risk-analytics

Purpose and Entry Points

Smart Return Risk Analytics is an offline e-commerce ML pipeline plus Streamlit decision-support UI. It ingests Olist CSV data, builds SQLite analytics tables/features, simulates return labels, trains binary classifiers, and serves return-risk predictions and historical analysis.

Primary execution entry points:

• Database initialization: src/db_setup.py

• CSV ingestion: src/data_loader.py

• SQL pipeline execution: src/sql_executor.py

• Model training/artifact export: src/train_and_save_models.py

• Dashboard runtime: dashboard/app.py

Source Data and Persistence Boundary

Raw Olist entities are versioned as CSVs under data/raw/, including orders, items, products, customers, and reviews. SQLite is the system’s relational processing boundary, with persisted databases at data/database.sqlite, data/ecommerce.db, and data/ecommerce_returns.db.

The pipeline converts raw operational-like data into queryable tables before ML-ready feature assembly, rather than having the dashboard query CSVs directly.

SQL Analytics and Feature Stage

Ordered SQL scripts define the analytics pipeline:

• Schema/table setup: sql/01_setup_tables.sql

• Data validation: sql/02_data_quality_checks.sql

• Customer and product aggregations: sql/03_customer_features.sql, sql/04_product_features.sql

• Order-level features and return-oriented data: sql/05_order_level_features.sql

Materialized SQL outputs provide intermediate contracts for downstream modeling: data/sql_outputs/customer_features.csv, data/sql_outputs/product_features.csv, and data/sql_outputs/order_features_with_returns.csv. The return target is synthetic, based on business signals such as review, delivery, and freight behavior.

ML Dataset and Training

The consolidated modeling contract is data/final/ml_ready_dataset.csv. Training experiments exist as notebooks and one executable model script, while src/train_and_save_models.py is the intended repeatable artifact-building path.

The system evaluates multiple binary classifiers—logistic regression, decision tree, random forest, and XGBoost—with class-imbalance and explainability capabilities described as part of the stack. Core model development paths are models/01_logistic_regression.ipynb, models/03_random_forest.ipynb, and models/04_xgboost.py.

Model Artifact Boundary

The dashboard consumes serialized inference artifacts rather than retraining models:

• Classifiers: dashboard/models/lr_model.pkl, dashboard/models/rf_model.pkl, dashboard/models/xgb_model.pkl

• Input schema and imputation metadata: dashboard/models/feature_columns.pkl, dashboard/models/feature_medians.pkl

This establishes a deployment boundary: training produces stable model/feature contracts; interactive pages load those contracts for prediction.

Dashboard Application Flow

dashboard/app.py is the Streamlit shell and routes users to three business workflows:

• Single-order/customer risk prediction: dashboard/pages/1_Single_Predictor.py

• Interactive scenario and cost/risk simulation: dashboard/pages/2_What_If_Simulator.py

• Aggregate historical metrics and trends: dashboard/pages/3_Historical_Analytics.py

Shared UI-side preprocessing and model-loading behavior belongs in dashboard/utils.py. Dashboard execution requires Python, Streamlit, the serialized model artifacts, and local data/database resources; no hosted service or API integration is represented.

Key Runtime Stack

The repository runs locally on Python 3.8+, using Pandas/NumPy for data processing, SQLite for storage and SQL transformation, scikit-learn and XGBoost for classification, and Streamlit/Plotly-oriented visualization for interactive analysis. Notebooks in notebooks/ are exploratory and feature-engineering stages, whereas src/, sql/, and dashboard/ define the operational pipeline and serving surface.