Deploy to Hugging Face Space

README.md

@@ -0,0 +1,41 @@
+---
+title: MLOps Mid Exam - Shipping Delay Prediction
+emoji: 📦
+colorFrom: blue
+colorTo: purple
+sdk: streamlit
+app_file: deployment/app.py
+pinned: false
+---
+
+# MLOps Mid Exam – Shipping Delay Prediction
+
+A lightweight MLOps project that predicts whether a shipment will arrive on time. The model is a scikit-learn pipeline (KNN + preprocessing) and the Streamlit app is deployed to Hugging Face Spaces while CI keeps the training artifacts healthy.
+
+- **Demo**: https://huggingface.co/spaces/vorddd/MLOps-MidExam  
+- **Model repo**: `vorddd/shipping-delay-knn`
+
+## How It Works
+
+- The training notebook exports `models/best_model_pipeline.joblib`.
+- `deployment/prediction.py` loads that file from `models/` during development and from the Hugging Face Hub in production (via `hf_hub_download`).
+- `deployment/app.py` stitches a simple overview page, an EDA tab (`deployment/eda.py`), and the prediction form.
+- Runtime dependencies live in `deployment/requirements.txt`; dev/test tooling stays in `requirements-dev.txt`.
+
+## Run Locally
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate          # or source .venv/bin/activate
+pip install -r deployment/requirements.txt -r requirements-dev.txt
+streamlit run deployment/app.py
+```
+
+Place the exported pipelines inside `models/` (already ignored in CD) and Streamlit will use them automatically. `pytest` runs the quick smoke tests.
+
+## CI/CD
+
+- **CI** (`.github/workflows/ci.yml`): runs on pushes/PRs to `main`, installs runtime + dev requirements, then executes `pytest`.
+- **CD** (`.github/workflows/cd.yml`): mirrors the minimal app bundle (README + `deployment/` folder + requirements) into a temp directory and force-pushes it to the Hugging Face Space `vorddd/MLOps-MidExam` with `HF_TOKEN`. If the token is missing, the deploy step exits gracefully.
+
+This setup keeps the repository easy to iterate on locally while ensuring the public app always downloads the latest pipeline from the Hub.

deployment/README.md

@@ -0,0 +1,14 @@
+---
+title: MLOps Mid Exam - Shipping Delay Prediction
+emoji: 📦
+colorFrom: blue
+colorTo: purple
+sdk: docker
+sdk_version: "latest"
+app_file: deployment/app.py
+pinned: false
+---
+
+# MLOps Mid Exam - Shipping Delay Prediction
+
+Streamlit dashboard to explore shipping data and run the trained KNN model for on-time delivery predictions. Built for the Hacktiv8 MLOps Mid Exam and deployed via GitHub Actions to Hugging Face Spaces.

deployment/__init__.py

@@ -0,0 +1,7 @@
+# deployment/__init__.py
+
+"""
+Package untuk komponen aplikasi MLOps MidExam.
+"""
+
+from .prediction import load_model, model_page

deployment/app.py

@@ -0,0 +1,65 @@
+from pathlib import Path
+
+import pandas as pd
+import streamlit as st
+
+from deployment.eda import eda_page
+from deployment.prediction import model_page
+
+st.set_page_config(
+    page_title="Shipping Service Monitor",
+    page_icon=":package:",
+    layout="wide",
+)
+
+BASE_DIR = Path(__file__).resolve().parent
+
+
+@st.cache_data(show_spinner=False)
+def load_data() -> pd.DataFrame:
+    """Read the dataset packaged with the deployment bundle."""
+    return pd.read_csv(BASE_DIR / "shipping.csv")
+
+
+def render_overview(data: pd.DataFrame) -> None:
+    st.title("Shipping Service Monitor")
+    st.caption("Shipping delay prediction")
+
+    col1, col2, col3 = st.columns(3)
+    col1.metric("Total Shipments", f"{len(data):,}")
+    col2.metric("Average Cost", f"${data['Cost_of_the_Product'].mean():.0f}")
+    on_time_rate = data["Reached.on.Time_Y.N"].mean() * 100
+    col3.metric("On-time Rate", f"{on_time_rate:.1f}%")
+
+    st.divider()
+    st.subheader("Sample of the Dataset")
+    st.dataframe(
+        data.head(5),
+        use_container_width=True,
+        hide_index=True,
+    )
+    st.info(
+        "This app mirrors the Hugging Face Space layout and reads the same CSV + model "
+        "artifacts, so local development and production behave identically."
+    )
+
+
+def main() -> None:
+    data = load_data()
+    render_overview(data)
+
+    st.sidebar.header("Navigation")
+    selected_option = st.sidebar.radio(
+        "Choose a page",
+        options=("Data Analysis", "Model Prediction"),
+        index=0,
+    )
+
+    if selected_option == "Data Analysis":
+        eda_page(data)
+    else:
+        model_page(data)
+
+
+if __name__ == "__main__":
+    main()

deployment/eda.py

@@ -0,0 +1,250 @@
+import numpy as np
+import pandas as pd
+import plotly.express as px
+import streamlit as st
+
+TARGET_COLUMN = "Reached.on.Time_Y.N"
+TARGET_LABELS = {1: "On Time", 0: "Late"}
+
+
+def _label_target(series: pd.Series) -> pd.Series:
+    return series.map(TARGET_LABELS).fillna("Unknown")
+
+
+def _get_categorical_columns(data: pd.DataFrame) -> list[str]:
+    return data.select_dtypes(include=["object"]).columns.tolist()
+
+
+def _get_numeric_columns(data: pd.DataFrame) -> list[str]:
+    """Return only business-relevant numeric features (exclude ID & target)."""
+    candidate_cols = [
+        "Customer_care_calls",
+        "Customer_rating",
+        "Cost_of_the_Product",
+        "Prior_purchases",
+        "Discount_offered",
+        "Weight_in_gms",
+    ]
+    return [c for c in candidate_cols if c in data.columns]
+
+
+def _make_numeric_bins(series: pd.Series, n_bins: int = 5) -> pd.Categorical:
+    """Create human-friendly ranges like '0–1000' instead of raw numbers."""
+    min_v = float(series.min())
+    max_v = float(series.max())
+
+    if min_v == max_v:
+        return pd.cut(series, bins=[min_v - 1, max_v + 1], labels=[f"{min_v:.0f}"])
+
+    bins = np.linspace(min_v, max_v, n_bins + 1)
+    labels = [f"{bins[i]:.0f}–{bins[i+1]:.0f}" for i in range(len(bins) - 1)]
+    return pd.cut(series, bins=bins, labels=labels, include_lowest=True)
+
+
+def eda_page(data: pd.DataFrame) -> None:
+    st.header("Exploratory Data Analysis")
+
+    total_shipments = len(data)
+    on_time_rate = data[TARGET_COLUMN].mean() * 100
+
+    median_discount = data["Discount_offered"].median()
+    median_weight = data["Weight_in_gms"].median()
+    loyal_share = (data["Prior_purchases"] > 3).mean() * 100
+
+    c1, c2, c3, c4 = st.columns(4)
+    c1.metric("Total shipments", f"{total_shipments:,}")
+    c2.metric("On-time delivery rate", f"{on_time_rate:.1f}%")
+    c3.metric("Median discount", f"{median_discount:.1f}%")
+    c4.metric("Loyal customers (> 3 prior purchases)", f"{loyal_share:.1f}%")
+
+    st.caption(
+        "Quick overview: how many shipments you have, how reliable deliveries are, "
+        "and how generous you are with discounts and loyal customers."
+    )
+
+    tab_target, tab_category, tab_numeric, tab_segments = st.tabs(
+        ["Delivery status", "By category", "By numeric feature", "Business segments"]
+    )
+
+    with tab_target:
+        st.subheader("Overall delivery status")
+
+        target_series = _label_target(data[TARGET_COLUMN])
+        target_counts = (
+            target_series.value_counts().rename_axis("Status").reset_index(name="Count")
+        )
+        target_counts["Percentage"] = (
+            target_counts["Count"] / target_counts["Count"].sum() * 100
+        )
+
+        fig = px.pie(
+            target_counts,
+            values="Count",
+            names="Status",
+            hole=0.35,
+        )
+        fig.update_traces(textposition="inside", textinfo="percent+label")
+        st.plotly_chart(fig, use_container_width=True)
+
+        late_row = target_counts.loc[target_counts["Status"] == "Late"]
+        if not late_row.empty:
+            late_pct = late_row["Percentage"].iloc[0]
+            st.write(
+                f"**Insight:** about **{late_pct:.1f}%** of all shipments arrive late. "
+                "This is the high-level reliability of your operation."
+            )
+
+    with tab_category:
+        st.subheader("How delivery status changes by category")
+
+        categorical_columns = _get_categorical_columns(data)
+        if not categorical_columns:
+            st.info("This dataset does not contain categorical features.")
+        else:
+            selected_cat = st.selectbox(
+                "Choose a categorical feature",
+                options=categorical_columns,
+            )
+
+            # Instead of 100% bars, show on-time rate per category
+            summary = (
+                data.groupby(selected_cat)
+                .agg(
+                    on_time_percent=(TARGET_COLUMN, lambda x: x.mean() * 100),
+                    total_shipments=(TARGET_COLUMN, "size"),
+                )
+                .reset_index()
+            )
+
+            fig_cat = px.bar(
+                summary,
+                x=selected_cat,
+                y="on_time_percent",
+                text_auto=".1f",
+                labels={
+                    "on_time_percent": "On-time delivery rate (%)",
+                    "total_shipments": "Number of shipments",
+                },
+            )
+            st.plotly_chart(fig_cat, use_container_width=True)
+
+            st.caption(
+                "Each bar shows **what percentage of shipments are delivered on time** "
+                f"for each value of **{selected_cat}**. Lower bars = higher risk segments."
+            )
+
+            st.write("Detailed numbers:")
+            st.dataframe(
+                summary.rename(
+                    columns={
+                        "on_time_percent": "On-time rate (%)",
+                        "total_shipments": "Total shipments",
+                    }
+                ),
+                use_container_width=True,
+            )
+
+    with tab_numeric:
+        st.subheader("Distribution of numeric features")
+
+        numeric_columns = _get_numeric_columns(data)
+        if not numeric_columns:
+            st.info("This dataset does not contain numeric features (other than ID/target).")
+        else:
+            selected_num = st.selectbox(
+                "Choose a numeric feature",
+                options=numeric_columns,
+            )
+
+            # Convert numeric values into simple ranges (bins)
+            binned = _make_numeric_bins(data[selected_num])
+            temp = data.copy()
+            temp["range"] = binned
+
+            summary_num = (
+                temp.groupby("range")
+                .agg(
+                    on_time_percent=(TARGET_COLUMN, lambda x: x.mean() * 100),
+                    total_shipments=(TARGET_COLUMN, "size"),
+                )
+                .reset_index()
+                .dropna()
+            )
+
+            fig_num = px.bar(
+                summary_num,
+                x="range",
+                y="on_time_percent",
+                text_auto=".1f",
+                labels={
+                    "range": f"{selected_num} range",
+                    "on_time_percent": "On-time delivery rate (%)",
+                },
+            )
+            st.plotly_chart(fig_num, use_container_width=True)
+
+            st.caption(
+                f"Bars show how **on-time delivery rate** changes across different ranges of "
+                f"**{selected_num}**. For example, you can see whether very high values are "
+                "associated with more late shipments."
+            )
+
+            st.write("Detailed numbers:")
+            st.dataframe(
+                summary_num.rename(
+                    columns={
+                        "range": f"{selected_num} range",
+                        "on_time_percent": "On-time rate (%)",
+                        "total_shipments": "Total shipments",
+                    }
+                ),
+                use_container_width=True,
+            )
+
+    with tab_segments:
+        st.subheader("Business segments: where do we perform well or poorly?")
+
+        grouping_column = st.selectbox(
+            "Group by",
+            ["Mode_of_Shipment", "Warehouse_block", "Product_importance", "Gender"],
+        )
+
+        summary = (
+            data.groupby(grouping_column)
+            .agg(
+                on_time_percent=(TARGET_COLUMN, lambda x: x.mean() * 100),
+                avg_cost=("Cost_of_the_Product", "mean"),
+                avg_discount=("Discount_offered", "mean"),
+            )
+            .reset_index()
+        )
+
+        fig_segment = px.bar(
+            summary,
+            x=grouping_column,
+            y="on_time_percent",
+            text_auto=".1f",
+            color="avg_discount",
+            color_continuous_scale="Blues",
+            labels={
+                "on_time_percent": "On-time delivery rate (%)",
+                "avg_discount": "Average discount",
+            },
+        )
+        st.plotly_chart(fig_segment, use_container_width=True)
+
+        st.dataframe(
+            summary.rename(
+                columns={
+                    "on_time_percent": "On-time rate (%)",
+                    "avg_cost": "Avg product cost",
+                    "avg_discount": "Avg discount",
+                }
+            ),
+            use_container_width=True,
+        )
+
+        st.caption(
+            "Use this view to spot **high-risk segments**: groups with low on-time rate, "
+            "especially if they also receive high discounts or involve high product cost."
+        )

deployment/prediction.py

@@ -0,0 +1,171 @@
+from pathlib import Path
+from typing import Optional
+
+import joblib
+import pandas as pd
+import streamlit as st
+from huggingface_hub import hf_hub_download
+
+# ==== Model configuration ====
+# Local path (used for CI tests & when you commit the artifact)
+LOCAL_MODEL_PATH = Path(__file__).resolve().parent / "best_model_pipeline.joblib"
+
+# Model repo on Hugging Face Hub (fallback when local file is not available)
+MODEL_REPO_ID = "vorddd/shipping-delay-knn-v1"
+MODEL_FILENAME = "best_model_pipeline.joblib"
+
+FEATURE_ORDER = [
+    "Customer_care_calls",
+    "Cost_of_the_Product",
+    "Prior_purchases",
+    "Discount_offered",
+    "Weight_in_gms",
+    "Product_importance",
+]
+
+
+@st.cache_resource(show_spinner=False)
+def load_model():
+    """
+    Load the trained model pipeline.
+
+    Priority:
+    1. If LOCAL_MODEL_PATH exists -> use that (for unit tests & local dev).
+    2. Otherwise -> download from Hugging Face Hub (for Spaces).
+    """
+    if LOCAL_MODEL_PATH.exists():
+        model_path = LOCAL_MODEL_PATH
+    else:
+        model_path = hf_hub_download(
+            repo_id=MODEL_REPO_ID,
+            filename=MODEL_FILENAME,
+            repo_type="model",
+        )
+
+    model = joblib.load(model_path)
+    return model
+
+
+def _get_feature_ranges(data: pd.DataFrame) -> dict:
+    """Get min, max, median for numeric features to build friendly sliders."""
+    ranges = {}
+    for column in FEATURE_ORDER[:-1]:  # numeric only, last one is categorical
+        series = data[column]
+        ranges[column] = (
+            int(series.min()),
+            int(series.max()),
+            int(series.median()),
+        )
+    return ranges
+
+
+def model_page(reference_data: Optional[pd.DataFrame] = None) -> None:
+    st.header("Shipment Delay Prediction")
+
+    st.write(
+        "Use this tool to estimate **whether a shipment is likely to arrive on time or late** "
+        "based on key business inputs such as product cost, discount, and customer history."
+    )
+    st.caption(
+        "Fill in the form below with realistic values. "
+        "The model will return a simple prediction: **On Time** or **Late**."
+    )
+
+    if reference_data is None:
+        raise ValueError("reference_data is required to build sensible input ranges")
+
+    # Build slider ranges from real data so the UI feels realistic
+    feature_ranges = _get_feature_ranges(reference_data)
+    product_options = sorted(reference_data["Product_importance"].unique())
+
+    with st.form("prediction_form"):
+        st.subheader("Shipment details")
+
+        col1, col2 = st.columns(2)
+
+        customer_care_calls = col1.slider(
+            "Customer care calls",
+            min_value=feature_ranges["Customer_care_calls"][0],
+            max_value=feature_ranges["Customer_care_calls"][1],
+            value=feature_ranges["Customer_care_calls"][2],
+            help="How many times this customer contacted customer service about this order.",
+        )
+        cost_of_product = col2.slider(
+            "Cost of the product",
+            min_value=feature_ranges["Cost_of_the_Product"][0],
+            max_value=feature_ranges["Cost_of_the_Product"][1],
+            value=feature_ranges["Cost_of_the_Product"][2],
+            help="Total product cost. Higher-value items may be treated differently in operations.",
+        )
+
+        prior_purchases = col1.slider(
+            "Prior purchases",
+            min_value=feature_ranges["Prior_purchases"][0],
+            max_value=feature_ranges["Prior_purchases"][1],
+            value=feature_ranges["Prior_purchases"][2],
+            help="How many times this customer has purchased before.",
+        )
+        discount_offered = col2.slider(
+            "Discount offered (%)",
+            min_value=feature_ranges["Discount_offered"][0],
+            max_value=feature_ranges["Discount_offered"][1],
+            value=feature_ranges["Discount_offered"][2],
+            help="Discount given for this order, in percent.",
+        )
+
+        weight_in_gms = st.slider(
+            "Product weight (grams)",
+            min_value=feature_ranges["Weight_in_gms"][0],
+            max_value=feature_ranges["Weight_in_gms"][1],
+            value=feature_ranges["Weight_in_gms"][2],
+            help="Heavier products may take more time to handle and ship.",
+        )
+
+        product_importance = st.selectbox(
+            "Product importance",
+            options=product_options,
+            help="Business importance of the product (for example: low, medium, high).",
+        )
+
+        submitted = st.form_submit_button("Predict shipment status")
+
+    if not submitted:
+        st.info("Fill in the shipment details and click **Predict shipment status**.")
+        return
+
+    # Build feature vector in the same order used during training
+    features = pd.DataFrame(
+        [[
+            customer_care_calls,
+            cost_of_product,
+            prior_purchases,
+            discount_offered,
+            weight_in_gms,
+            product_importance,
+        ]],
+        columns=FEATURE_ORDER,
+    )
+
+    model = load_model()
+    prediction_raw = model.predict(features)[0]
+    is_on_time = prediction_raw == 1
+
+    st.subheader("Prediction result")
+
+    if is_on_time:
+        st.success("This shipment is **predicted to arrive ON TIME**.")
+    else:
+        st.error("This shipment is **predicted to be LATE**.")
+
+    st.caption(
+        "The prediction is based on historical patterns in the training data. "
+        "Use it as a rough risk indicator, not as a guarantee."
+    )
+
+    st.markdown("---")
+    st.markdown("### Input summary")
+    st.write(
+        "These are the values you entered. "
+        "to see how the model reacts to different shipment profiles."
+    )
+    st.dataframe(features, use_container_width=True)

deployment/requirements.txt

@@ -0,0 +1,7 @@
+huggingface_hub
+joblib
+pandas
+streamlit
+plotly
+numpy
+scikit-learn==1.5.1

requirements.txt

@@ -0,0 +1,7 @@
+huggingface_hub
+joblib
+pandas
+streamlit
+plotly
+numpy
+scikit-learn==1.5.1