Upload 16 files

.gitattributes

@@ -0,0 +1,3 @@
+archive.zip filter=lfs diff=lfs merge=lfs -text
+background_top.png filter=lfs diff=lfs merge=lfs -text
+ecommerce_returns_cleaned.csv filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,26 @@
+FROM python:3.10-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+ENV GRADIO_SERVER_NAME=0.0.0.0
+ENV GRADIO_SERVER_PORT=7860
+
+WORKDIR /app
+COPY . /app
+
+# Python deps (from requirements.txt)
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Notebook execution deps
+RUN pip install --no-cache-dir notebook ipykernel papermill
+
+# Pre-install packages the notebooks use via !pip install
+RUN pip install --no-cache-dir textblob faker vaderSentiment transformers
+
+RUN python -m ipykernel install --user --name python3 --display-name "Python 3"
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,11 @@
+---
+title: SE21 App Template
+emoji: 📊
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
+short_description: AI-enhanced analytics dashboard template for SE21 students
+---
+
+Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,864 @@
+import os
+import re
+import json
+import time
+import traceback
+from pathlib import Path
+from typing import Dict, Any, List, Tuple
+
+import pandas as pd
+import gradio as gr
+import papermill as pm
+import plotly.graph_objects as go
+
+# Optional LLM (HuggingFace Inference API)
+try:
+    from huggingface_hub import InferenceClient
+except Exception:
+    InferenceClient = None
+
+# =========================================================
+# CONFIG
+# =========================================================
+
+BASE_DIR = Path(__file__).resolve().parent
+
+NB1 = os.environ.get("NB1", "datacreation.ipynb").strip()
+NB2 = os.environ.get("NB2", "pythonanalysis.ipynb").strip()
+
+RUNS_DIR = BASE_DIR / "runs"
+ART_DIR = BASE_DIR / "artifacts"
+PY_FIG_DIR = ART_DIR / "py" / "figures"
+PY_TAB_DIR = ART_DIR / "py" / "tables"
+
+PAPERMILL_TIMEOUT = int(os.environ.get("PAPERMILL_TIMEOUT", "1800"))
+MAX_PREVIEW_ROWS = int(os.environ.get("MAX_FILE_PREVIEW_ROWS", "50"))
+MAX_LOG_CHARS = int(os.environ.get("MAX_LOG_CHARS", "8000"))
+
+HF_API_KEY = os.environ.get("HF_API_KEY", "").strip()
+MODEL_NAME = os.environ.get("MODEL_NAME", "deepseek-ai/DeepSeek-R1").strip()
+HF_PROVIDER = os.environ.get("HF_PROVIDER", "novita").strip()
+N8N_WEBHOOK_URL = os.environ.get("N8N_WEBHOOK_URL", "").strip()
+
+LLM_ENABLED = bool(HF_API_KEY) and InferenceClient is not None
+llm_client = (
+    InferenceClient(provider=HF_PROVIDER, api_key=HF_API_KEY)
+    if LLM_ENABLED
+    else None
+)
+
+# =========================================================
+# HELPERS
+# =========================================================
+
+def ensure_dirs():
+    for p in [RUNS_DIR, ART_DIR, PY_FIG_DIR, PY_TAB_DIR]:
+        p.mkdir(parents=True, exist_ok=True)
+
+def stamp():
+    return time.strftime("%Y%m%d-%H%M%S")
+
+def tail(text: str, n: int = MAX_LOG_CHARS) -> str:
+    return (text or "")[-n:]
+
+def _ls(dir_path: Path, exts: Tuple[str, ...]) -> List[str]:
+    if not dir_path.is_dir():
+        return []
+    return sorted(p.name for p in dir_path.iterdir() if p.is_file() and p.suffix.lower() in exts)
+
+def _read_csv(path: Path) -> pd.DataFrame:
+    return pd.read_csv(path, nrows=MAX_PREVIEW_ROWS)
+
+def _read_json(path: Path):
+    with path.open(encoding="utf-8") as f:
+        return json.load(f)
+
+def artifacts_index() -> Dict[str, Any]:
+    return {
+        "python": {
+            "figures": _ls(PY_FIG_DIR, (".png", ".jpg", ".jpeg")),
+            "tables": _ls(PY_TAB_DIR, (".csv", ".json")),
+        },
+    }
+
+# =========================================================
+# PIPELINE RUNNERS
+# =========================================================
+
+def run_notebook(nb_name: str) -> str:
+    ensure_dirs()
+    nb_in = BASE_DIR / nb_name
+    if not nb_in.exists():
+        return f"ERROR: {nb_name} not found."
+    nb_out = RUNS_DIR / f"run_{stamp()}_{nb_name}"
+    pm.execute_notebook(
+        input_path=str(nb_in),
+        output_path=str(nb_out),
+        cwd=str(BASE_DIR),
+        log_output=True,
+        progress_bar=False,
+        request_save_on_cell_execute=True,
+        execution_timeout=PAPERMILL_TIMEOUT,
+        kernel_name="python3",
+    )
+    return f"Executed {nb_name}"
+
+
+def run_datacreation() -> str:
+    try:
+        log = run_notebook(NB1)
+        csvs = [f.name for f in BASE_DIR.glob("*.csv")]
+        return f"OK  {log}\n\nCSVs now in /app:\n" + "\n".join(f"  - {c}" for c in sorted(csvs))
+    except Exception as e:
+        return f"FAILED  {e}\n\n{traceback.format_exc()[-2000:]}"
+
+
+def run_pythonanalysis() -> str:
+    try:
+        log = run_notebook(NB2)
+        idx = artifacts_index()
+        figs = idx["python"]["figures"]
+        tabs = idx["python"]["tables"]
+        return (
+            f"OK  {log}\n\n"
+            f"Figures: {', '.join(figs) or '(none)'}\n"
+            f"Tables:  {', '.join(tabs) or '(none)'}"
+        )
+    except Exception as e:
+        return f"FAILED  {e}\n\n{traceback.format_exc()[-2000:]}"
+
+
+def run_full_pipeline() -> str:
+    logs = []
+    logs.append("=" * 50)
+    logs.append("STEP 1/2: Data Creation (web scraping + synthetic data)")
+    logs.append("=" * 50)
+    logs.append(run_datacreation())
+    logs.append("")
+    logs.append("=" * 50)
+    logs.append("STEP 2/2: Python Analysis (sentiment, ARIMA, dashboard)")
+    logs.append("=" * 50)
+    logs.append(run_pythonanalysis())
+    return "\n".join(logs)
+
+
+# =========================================================
+# GALLERY LOADERS
+# =========================================================
+
+def _load_all_figures() -> List[Tuple[str, str]]:
+    """Return list of (filepath, caption) for Gallery."""
+    items = []
+    for p in sorted(PY_FIG_DIR.glob("*.png")):
+        items.append((str(p), p.stem.replace('_', ' ').title()))
+    return items
+
+
+def _load_table_safe(path: Path) -> pd.DataFrame:
+    try:
+        if path.suffix == ".json":
+            obj = _read_json(path)
+            if isinstance(obj, dict):
+                return pd.DataFrame([obj])
+            return pd.DataFrame(obj)
+        return _read_csv(path)
+    except Exception as e:
+        return pd.DataFrame([{"error": str(e)}])
+
+
+def refresh_gallery():
+    """Called when user clicks Refresh on Gallery tab."""
+    figures = _load_all_figures()
+    idx = artifacts_index()
+
+    table_choices = list(idx["python"]["tables"])
+
+    default_df = pd.DataFrame()
+    if table_choices:
+        default_df = _load_table_safe(PY_TAB_DIR / table_choices[0])
+
+    return (
+        figures if figures else [],
+        gr.update(choices=table_choices, value=table_choices[0] if table_choices else None),
+        default_df,
+    )
+
+
+def on_table_select(choice: str):
+    if not choice:
+        return pd.DataFrame([{"hint": "Select a table above."}])
+    path = PY_TAB_DIR / choice
+    if not path.exists():
+        return pd.DataFrame([{"error": f"File not found: {choice}"}])
+    return _load_table_safe(path)
+
+
+# =========================================================
+# KPI LOADER
+# =========================================================
+
+def load_kpis() -> Dict[str, Any]:
+    for candidate in [PY_TAB_DIR / "kpis.json", PY_FIG_DIR / "kpis.json"]:
+        if candidate.exists():
+            try:
+                return _read_json(candidate)
+            except Exception:
+                pass
+    return {}
+
+
+# =========================================================
+# AI DASHBOARD -- LLM picks what to display
+# =========================================================
+
+DASHBOARD_SYSTEM = """You are an AI dashboard assistant for a retail analytics app focused on e-commerce return prediction and review intelligence.
+
+The user asks questions about product reviews, return risk, customer complaints, sentiment, rating distribution, and product/category return patterns. You have access to pre-computed artifacts from a Python analysis pipeline.
+
+AVAILABLE ARTIFACTS:
+{artifacts_json}
+
+KPI SUMMARY:
+{kpis_json}
+
+YOUR JOB:
+1. Answer the user's question using the KPIs and available artifacts.
+2. At the END of your response, output a JSON block fenced with ```json ... ``` using this exact shape:
+   {{"show": "figure"|"table"|"none", "scope": "python", "filename": "..."}}
+
+RULES:
+- If the user asks about return rate, return risk, returned products, or high-risk categories, show category_return_rate.csv if available.
+- If the user asks about sentiment or reviews, show sentiment_counts_sampled.csv or sentiment_distribution.png.
+- If the user asks about ratings, show rating_distribution.png or rating_distribution.csv.
+- If the user asks for dashboard overview, show df_dashboard.csv.
+- If no artifact is relevant, use "show": "none".
+- Keep the answer concise and business-focused.
+"""
+
+JSON_BLOCK_RE = re.compile(r"```json\s*(\{.*?\})\s*```", re.DOTALL)
+FALLBACK_JSON_RE = re.compile(r"\{[^{}]*\"show\"[^{}]*\}", re.DOTALL)
+
+
+def _parse_display_directive(text: str) -> Dict[str, str]:
+    m = JSON_BLOCK_RE.search(text)
+    if m:
+        try:
+            return json.loads(m.group(1))
+        except json.JSONDecodeError:
+            pass
+    m = FALLBACK_JSON_RE.search(text)
+    if m:
+        try:
+            return json.loads(m.group(0))
+        except json.JSONDecodeError:
+            pass
+    return {"show": "none"}
+
+
+def _clean_response(text: str) -> str:
+    """Strip the JSON directive block from the displayed response."""
+    return JSON_BLOCK_RE.sub("", text).strip()
+
+
+def _n8n_call(msg: str) -> Tuple[str, Dict]:
+    """Call the student's n8n webhook and return (reply, directive)."""
+    import requests as req
+    try:
+        resp = req.post(N8N_WEBHOOK_URL, json={"question": msg}, timeout=20)
+        data = resp.json()
+        answer = data.get("answer", "No response from n8n workflow.")
+        chart = data.get("chart", "none")
+        if chart and chart != "none":
+            return answer, {"show": "figure", "chart": chart}
+        return answer, {"show": "none"}
+    except Exception as e:
+        return f"n8n error: {e}. Falling back to keyword matching.", None
+
+
+def ai_chat(user_msg: str, history: list):
+    """Chat function for the AI Dashboard tab."""
+    if not user_msg or not user_msg.strip():
+        return history, "", None, None
+
+    idx = artifacts_index()
+    kpis = load_kpis()
+
+    # Priority: n8n webhook > HF LLM > keyword fallback
+    if N8N_WEBHOOK_URL:
+        reply, directive = _n8n_call(user_msg)
+        if directive is None:
+            reply_fb, directive = _keyword_fallback(user_msg, idx, kpis)
+            reply += "\n\n" + reply_fb
+    elif not LLM_ENABLED:
+        reply, directive = _keyword_fallback(user_msg, idx, kpis)
+    else:
+        system = DASHBOARD_SYSTEM.format(
+            artifacts_json=json.dumps(idx, indent=2),
+            kpis_json=json.dumps(kpis, indent=2) if kpis else "(no KPIs yet, run the pipeline first)",
+        )
+        msgs = [{"role": "system", "content": system}]
+        for entry in (history or [])[-6:]:
+            msgs.append(entry)
+        msgs.append({"role": "user", "content": user_msg})
+
+        try:
+            r = llm_client.chat_completion(
+                model=MODEL_NAME,
+                messages=msgs,
+                temperature=0.3,
+                max_tokens=600,
+                stream=False,
+            )
+            raw = (
+                r["choices"][0]["message"]["content"]
+                if isinstance(r, dict)
+                else r.choices[0].message.content
+            )
+            directive = _parse_display_directive(raw)
+            reply = _clean_response(raw)
+        except Exception as e:
+            reply = f"LLM error: {e}. Falling back to keyword matching."
+            reply_fb, directive = _keyword_fallback(user_msg, idx, kpis)
+            reply += "\n\n" + reply_fb
+
+    # Resolve artifacts — build interactive Plotly charts when possible
+    chart_out = None
+    tab_out = None
+
+    show = directive.get("show", "none") if isinstance(directive, dict) else "none"
+    fname = directive.get("filename", "") if isinstance(directive, dict) else ""
+    chart_name = directive.get("chart", "") if isinstance(directive, dict) else ""
+
+    # Interactive chart builders keyed by name. Old aliases are included so
+    # the app will still work if an LLM/webhook returns an older chart name.
+    chart_builders = {
+        "sales": build_monthly_return_chart,
+        "returns": build_monthly_return_chart,
+        "monthly_returns": build_monthly_return_chart,
+        "sentiment": build_sentiment_chart,
+        "top_sellers": build_top_return_categories_chart,
+        "top_returns": build_top_return_categories_chart,
+        "rating": build_rating_chart,
+        "ratings": build_rating_chart,
+    }
+
+    if chart_name and chart_name in chart_builders:
+        chart_out = chart_builders[chart_name]()
+
+    elif show == "figure" and fname:
+        low_fname = fname.lower()
+        if "sentiment" in low_fname:
+            chart_out = build_sentiment_chart()
+        elif "rating" in low_fname:
+            chart_out = build_rating_chart()
+        elif "category" in low_fname or "top" in low_fname or "risk" in low_fname:
+            chart_out = build_top_return_categories_chart()
+        elif "return" in low_fname or "dashboard" in low_fname or "monthly" in low_fname:
+            chart_out = build_monthly_return_chart()
+        else:
+            chart_out = _empty_chart(f"No interactive chart for {fname}")
+
+    if show == "table" and fname:
+        fp = PY_TAB_DIR / fname
+        if fp.exists():
+            tab_out = _load_table_safe(fp)
+        else:
+            reply += f"\n\n*(Could not find table: {fname})*"
+
+    new_history = (history or []) + [
+        {"role": "user", "content": user_msg},
+        {"role": "assistant", "content": reply},
+    ]
+
+    return new_history, "", chart_out, tab_out
+
+def _keyword_fallback(msg: str, idx: Dict, kpis: Dict) -> Tuple[str, Dict]:
+    """Retail return/review keyword matcher when LLM is unavailable."""
+    msg_lower = msg.lower()
+
+    if not idx["python"]["figures"] and not idx["python"]["tables"]:
+        return (
+            "No artifacts found yet. Please run the pipeline first, then come back here to explore the results.",
+            {"show": "none"},
+        )
+
+    reviews_rows = kpis.get("reviews_rows", "?")
+    returns_rows = kpis.get("returns_rows", "?")
+    n_products = kpis.get("n_products", kpis.get("n_titles", "?"))
+    return_rate = kpis.get("estimated_return_rate", None)
+
+    if isinstance(return_rate, (int, float)):
+        return_rate_text = f"{return_rate:.1%}"
+    else:
+        return_rate_text = "not available"
+
+    kpi_text = (
+        f"Quick summary: **{reviews_rows} reviews**, **{returns_rows} return records**, "
+        f"and **{n_products} products/classes** analyzed. Estimated return rate: **{return_rate_text}**."
+    )
+
+    if any(w in msg_lower for w in ["return", "returned", "returns", "highest return", "return rate", "risk"]):
+        return (
+            f"Here are the highest return-risk products/categories. {kpi_text}",
+            {"show": "table", "scope": "python", "filename": "category_return_rate.csv"},
+        )
+
+    if any(w in msg_lower for w in ["complaint", "complaints", "problem", "issues", "review", "reviews"]):
+        return (
+            f"Here is the review intelligence summary. {kpi_text}",
+            {"show": "table", "scope": "python", "filename": "sentiment_counts_sampled.csv"},
+        )
+
+    if any(w in msg_lower for w in ["sentiment", "positive", "negative", "neutral"]):
+        return (
+            f"Here is the sentiment breakdown from customer reviews. {kpi_text}",
+            {"show": "figure", "chart": "sentiment"},
+        )
+
+    if any(w in msg_lower for w in ["rating", "ratings", "stars"]):
+        return (
+            f"Here is the rating distribution. {kpi_text}",
+            {"show": "figure", "scope": "python", "filename": "rating_distribution.png"},
+        )
+
+    if any(w in msg_lower for w in ["dashboard", "overview", "summary", "kpi"]):
+        return (
+            f"Dashboard overview: {kpi_text}\n\nAsk me about return rates, review complaints, sentiment, ratings, or high-risk products.",
+            {"show": "table", "scope": "python", "filename": "df_dashboard.csv"},
+        )
+
+    return (
+        f"I can help analyze e-commerce returns and review intelligence. {kpi_text}\n\n"
+        "Try asking about: **highest return-rate categories**, **review complaints**, "
+        "**sentiment**, **ratings**, or **dashboard overview**.",
+        {"show": "none"},
+    )
+
+# =========================================================
+# KPI CARDS (BubbleBusters style)
+# =========================================================
+
+def render_kpi_cards() -> str:
+    kpis = load_kpis()
+    if not kpis:
+        return (
+            '<div style="background:rgba(255,255,255,.65);backdrop-filter:blur(16px);'
+            'border-radius:20px;padding:28px;text-align:center;'
+            'border:1.5px solid rgba(255,255,255,.7);'
+            'box-shadow:0 8px 32px rgba(124,92,191,.08);">'
+            '<div style="font-size:36px;margin-bottom:10px;">📊</div>'
+            '<div style="color:#a48de8;font-size:14px;'
+            'font-weight:800;margin-bottom:6px;">No data yet</div>'
+            '<div style="color:#9d8fc4;font-size:12px;">'
+            'Run the pipeline to populate these cards.</div>'
+            '</div>'
+        )
+
+    def fmt_value(key, val):
+        if val is None:
+            return "—"
+        if key == "estimated_return_rate" and isinstance(val, (int, float)):
+            return f"{val:.1%}"
+        if isinstance(val, (int, float)) and abs(val) >= 100:
+            return f"{val:,.0f}"
+        return str(val)
+
+    def card(icon, label, value, colour):
+        return f"""
+        <div style="background:rgba(255,255,255,.72);backdrop-filter:blur(16px);
+                    border-radius:20px;padding:18px 14px 16px;text-align:center;
+                    border:1.5px solid rgba(255,255,255,.8);
+                    box-shadow:0 4px 16px rgba(124,92,191,.08);
+                    border-top:3px solid {colour};">
+            <div style="font-size:26px;margin-bottom:7px;line-height:1;">{icon}</div>
+            <div style="color:#9d8fc4;font-size:9.5px;text-transform:uppercase;
+                        letter-spacing:1.8px;margin-bottom:7px;font-weight:800;">{label}</div>
+            <div style="color:#2d1f4e;font-size:16px;font-weight:800;">{value}</div>
+        </div>"""
+
+    # Backwards-compatible aliases: older notebook versions may still write
+    # n_titles/n_months/total_units_sold, while the retail notebook writes
+    # n_products/n_periods/total_return_records.
+    aliases = {
+        "n_products": kpis.get("n_products", kpis.get("n_titles")),
+        "n_periods": kpis.get("n_periods", kpis.get("n_months")),
+        "total_return_records": kpis.get("total_return_records", kpis.get("total_units_sold")),
+        "estimated_return_rate": kpis.get("estimated_return_rate"),
+        "reviews_rows": kpis.get("reviews_rows"),
+        "returns_rows": kpis.get("returns_rows"),
+    }
+
+    kpi_config = [
+        ("reviews_rows",          "💬", "Reviews",        "#a48de8"),
+        ("returns_rows",          "↩️", "Return Records", "#7aa6f8"),
+        ("n_products",            "🛍️", "Products",       "#6ee7c7"),
+        ("estimated_return_rate", "📉", "Return Rate",    "#e8537a"),
+    ]
+
+    html = (
+        '<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(140px,1fr));'
+        'gap:12px;margin-bottom:24px;">'
+    )
+
+    used = set()
+    for key, icon, label, colour in kpi_config:
+        val = aliases.get(key)
+        if val is None:
+            continue
+        used.add(key)
+        html += card(icon, label, fmt_value(key, val), colour)
+
+    # Extra KPIs not in config
+    for key, val in kpis.items():
+        if key in used or key in {"n_titles", "n_months", "total_units_sold", "total_revenue"}:
+            continue
+        label = key.replace("_", " ").title()
+        html += card("📈", label, fmt_value(key, val), "#8fa8f8")
+
+    html += "</div>"
+    return html
+
+# =========================================================
+# INTERACTIVE PLOTLY CHARTS (BubbleBusters style)
+# =========================================================
+
+CHART_PALETTE = ["#7c5cbf", "#2ec4a0", "#e8537a", "#e8a230", "#5e8fef",
+                 "#c45ea8", "#3dbacc", "#a0522d", "#6aaa3a", "#d46060"]
+
+def _styled_layout(**kwargs) -> dict:
+    defaults = dict(
+        template="plotly_white",
+        paper_bgcolor="rgba(255,255,255,0.95)",
+        plot_bgcolor="rgba(255,255,255,0.98)",
+        font=dict(family="system-ui, sans-serif", color="#2d1f4e", size=12),
+        margin=dict(l=60, r=20, t=70, b=70),
+        legend=dict(
+            orientation="h", yanchor="bottom", y=1.02, xanchor="right", x=1,
+            bgcolor="rgba(255,255,255,0.92)",
+            bordercolor="rgba(124,92,191,0.35)", borderwidth=1,
+        ),
+        title=dict(font=dict(size=15, color="#4b2d8a")),
+    )
+    defaults.update(kwargs)
+    return defaults
+
+
+def _empty_chart(title: str) -> go.Figure:
+    fig = go.Figure()
+    fig.update_layout(
+        title=title, height=420, template="plotly_white",
+        paper_bgcolor="rgba(255,255,255,0.95)",
+        annotations=[dict(text="Run the pipeline to generate data",
+            x=0.5, y=0.5, xref="paper", yref="paper", showarrow=False,
+            font=dict(size=14, color="rgba(124,92,191,0.5)"))],
+    )
+    return fig
+
+
+def build_monthly_return_chart() -> go.Figure:
+    path = PY_TAB_DIR / "df_dashboard.csv"
+    if not path.exists():
+        return _empty_chart("Monthly Return Overview — run the pipeline first")
+
+    df = pd.read_csv(path)
+    if df.empty:
+        return _empty_chart("df_dashboard.csv is empty")
+
+    date_col = next((c for c in df.columns if "month" in c.lower() or "date" in c.lower() or "time" in c.lower()), None)
+    val_cols = [c for c in df.columns if c != date_col and pd.api.types.is_numeric_dtype(df[c])]
+
+    if not val_cols:
+        # Try converting numeric-looking columns
+        for c in df.columns:
+            if c != date_col:
+                df[c] = pd.to_numeric(df[c], errors="coerce")
+        val_cols = [c for c in df.columns if c != date_col and pd.api.types.is_numeric_dtype(df[c])]
+
+    if not date_col or not val_cols:
+        return _empty_chart("Could not auto-detect columns in df_dashboard.csv")
+
+    df[date_col] = pd.to_datetime(df[date_col], errors="coerce")
+    fig = go.Figure()
+
+    for i, col in enumerate(val_cols):
+        y_format = ":.1%" if "rate" in col.lower() or "risk" in col.lower() else ":,.0f"
+        fig.add_trace(go.Scatter(
+            x=df[date_col], y=df[col], name=col.replace("_", " ").title(),
+            mode="lines+markers", line=dict(color=CHART_PALETTE[i % len(CHART_PALETTE)], width=2),
+            marker=dict(size=5),
+            hovertemplate=f"<b>{col.replace('_',' ').title()}</b><br>%{{x|%b %Y}}: %{{y{y_format}}}<extra></extra>",
+        ))
+
+    fig.update_layout(**_styled_layout(
+        height=450,
+        hovermode="x unified",
+        title=dict(text="Monthly Return Overview"),
+    ))
+    fig.update_xaxes(gridcolor="rgba(124,92,191,0.15)", showgrid=True)
+    fig.update_yaxes(gridcolor="rgba(124,92,191,0.15)", showgrid=True)
+    return fig
+
+
+# Backwards-compatible name used by older template code
+build_sales_chart = build_monthly_return_chart
+
+
+def build_rating_chart() -> go.Figure:
+    path = PY_TAB_DIR / "rating_distribution.csv"
+    if not path.exists():
+        return _empty_chart("Rating Distribution — run the pipeline first")
+
+    df = pd.read_csv(path)
+    if df.empty:
+        return _empty_chart("rating_distribution.csv is empty")
+
+    rating_col = next((c for c in df.columns if "rating" in c.lower()), df.columns[0])
+    count_col = next((c for c in df.columns if "count" in c.lower() or "number" in c.lower()), df.columns[-1])
+
+    fig = go.Figure(go.Bar(
+        x=df[rating_col].astype(str),
+        y=df[count_col],
+        marker_color="#7c5cbf",
+        hovertemplate="<b>Rating %{x}</b><br>Reviews: %{y:,.0f}<extra></extra>",
+    ))
+    fig.update_layout(**_styled_layout(
+        height=420,
+        title=dict(text="Distribution of Customer Ratings"),
+        showlegend=False,
+    ))
+    fig.update_xaxes(title="Rating")
+    fig.update_yaxes(title="Number of Reviews")
+    return fig
+
+
+def build_sentiment_chart() -> go.Figure:
+    path = PY_TAB_DIR / "sentiment_counts_sampled.csv"
+    if not path.exists():
+        return _empty_chart("Sentiment Distribution — run the pipeline first")
+
+    df = pd.read_csv(path)
+    if df.empty:
+        return _empty_chart("sentiment_counts_sampled.csv is empty")
+
+    title_col = df.columns[0]
+    sent_cols = [c for c in ["negative", "neutral", "positive"] if c in df.columns]
+    if not sent_cols:
+        return _empty_chart("No sentiment columns found in sentiment_counts_sampled.csv")
+
+    colors = {"negative": "#e8537a", "neutral": "#5e8fef", "positive": "#2ec4a0"}
+    fig = go.Figure()
+    for col in sent_cols:
+        fig.add_trace(go.Bar(
+            name=col.title(),
+            y=df[title_col].astype(str),
+            x=df[col],
+            orientation="h",
+            marker_color=colors.get(col, "#888"),
+            hovertemplate=f"<b>{col.title()}</b>: %{{x:,.0f}}<extra></extra>",
+        ))
+
+    fig.update_layout(**_styled_layout(
+        height=max(420, len(df) * 30),
+        barmode="stack",
+        title=dict(text="Sentiment Distribution by Product/Class"),
+    ))
+    fig.update_xaxes(title="Number of Reviews")
+    fig.update_yaxes(autorange="reversed")
+    return fig
+
+
+def build_top_return_categories_chart() -> go.Figure:
+    path = PY_TAB_DIR / "category_return_rate.csv"
+    if not path.exists():
+        path = PY_TAB_DIR / "top_titles_by_units_sold.csv"  # backwards-compatible fallback
+
+    if not path.exists():
+        return _empty_chart("Highest Return-Risk Categories — run the pipeline first")
+
+    df = pd.read_csv(path).head(15)
+    if df.empty:
+        return _empty_chart(f"{path.name} is empty")
+
+    category_col = next(
+        (c for c in df.columns if "category" in c.lower() or "class" in c.lower() or "title" in c.lower() or "product" in c.lower()),
+        df.columns[0],
+    )
+    value_col = next(
+        (c for c in df.columns if "return" in c.lower() or "risk" in c.lower() or "rate" in c.lower() or "unit" in c.lower()),
+        df.columns[-1],
+    )
+
+    df[value_col] = pd.to_numeric(df[value_col], errors="coerce")
+    fig = go.Figure(go.Bar(
+        y=df[category_col].astype(str),
+        x=df[value_col],
+        orientation="h",
+        marker=dict(color=df[value_col], colorscale=[[0, "#c5b4f0"], [1, "#7c5cbf"]]),
+        hovertemplate="<b>%{y}</b><br>Return rate/risk: %{x:.2%}<extra></extra>",
+    ))
+    fig.update_layout(**_styled_layout(
+        height=max(420, len(df) * 32),
+        title=dict(text="Highest Return-Risk Products / Categories"),
+        showlegend=False,
+    ))
+    fig.update_yaxes(autorange="reversed")
+    fig.update_xaxes(title="Return Rate / Risk Score")
+    return fig
+
+
+# Backwards-compatible name used by older template code
+build_top_sellers_chart = build_top_return_categories_chart
+
+def refresh_dashboard():
+    return render_kpi_cards(), build_sales_chart(), build_sentiment_chart(), build_top_sellers_chart()
+
+
+# =========================================================
+# UI
+# =========================================================
+
+ensure_dirs()
+
+def load_css() -> str:
+    css_path = BASE_DIR / "style.css"
+    return css_path.read_text(encoding="utf-8") if css_path.exists() else ""
+
+
+with gr.Blocks(title="AIBDM 2026 Workshop App") as demo:
+
+    gr.Markdown(
+        "# SE21 App Template\n"
+        "*This is an app template for SE21 students*",
+        elem_id="escp_title",
+    )
+
+    # ===========================================================
+    # TAB 1 -- Pipeline Runner
+    # ===========================================================
+    with gr.Tab("Pipeline Runner"):
+        gr.Markdown()
+
+        with gr.Row():
+            with gr.Column(scale=1):
+                btn_nb1 = gr.Button("Step 1: Data Creation", variant="secondary")
+            with gr.Column(scale=1):
+                btn_nb2 = gr.Button("Step 2: Python Analysis", variant="secondary")
+
+        with gr.Row():
+            btn_all = gr.Button("Run Full Pipeline (Both Steps)", variant="primary")
+
+        run_log = gr.Textbox(
+            label="Execution Log",
+            lines=18,
+            max_lines=30,
+            interactive=False,
+        )
+
+        btn_nb1.click(run_datacreation, outputs=[run_log])
+        btn_nb2.click(run_pythonanalysis, outputs=[run_log])
+        btn_all.click(run_full_pipeline, outputs=[run_log])
+
+    # ===========================================================
+    # TAB 2 -- Dashboard (KPIs + Interactive Charts + Gallery)
+    # ===========================================================
+    with gr.Tab("Dashboard"):
+        kpi_html = gr.HTML(value=render_kpi_cards)
+
+        refresh_btn = gr.Button("Refresh Dashboard", variant="primary")
+
+        gr.Markdown("#### Interactive Charts")
+        chart_sales = gr.Plot(label="Monthly Return Overview")
+        chart_sentiment = gr.Plot(label="Sentiment Distribution")
+        chart_top = gr.Plot(label="Highest Return Risk")
+
+        gr.Markdown("#### Static Figures (from notebooks)")
+        gallery = gr.Gallery(
+            label="Generated Figures",
+            columns=2,
+            height=480,
+            object_fit="contain",
+        )
+
+        gr.Markdown("#### Data Tables")
+        table_dropdown = gr.Dropdown(
+            label="Select a table to view",
+            choices=[],
+            interactive=True,
+        )
+        table_display = gr.Dataframe(
+            label="Table Preview",
+            interactive=False,
+        )
+
+        def _on_refresh():
+            kpi, c1, c2, c3 = refresh_dashboard()
+            figs, dd, df = refresh_gallery()
+            return kpi, c1, c2, c3, figs, dd, df
+
+        refresh_btn.click(
+            _on_refresh,
+            outputs=[kpi_html, chart_sales, chart_sentiment, chart_top,
+                     gallery, table_dropdown, table_display],
+        )
+        table_dropdown.change(
+            on_table_select,
+            inputs=[table_dropdown],
+            outputs=[table_display],
+        )
+
+    # ===========================================================
+    # TAB 3 -- AI Dashboard
+    # ===========================================================
+    with gr.Tab('"AI" Dashboard'):
+        _ai_status = (
+            "Connected to your **n8n workflow**." if N8N_WEBHOOK_URL
+            else "**LLM active.**" if LLM_ENABLED
+            else "Using **keyword matching**. Upgrade options: "
+                 "set `N8N_WEBHOOK_URL` to connect your n8n workflow, "
+                 "or set `HF_API_KEY` for direct LLM access."
+        )
+        gr.Markdown(
+            "### Ask questions, get interactive visualisations\n\n"
+            f"Type a question and the system will pick the right interactive chart or table. {_ai_status}"
+        )
+
+        with gr.Row(equal_height=True):
+            with gr.Column(scale=1):
+                chatbot = gr.Chatbot(
+                    label="Conversation",
+                    height=380,
+                )
+                user_input = gr.Textbox(
+                    label="Ask about your data",
+                    placeholder="e.g. Which products have the highest return rate? / What are the main complaints? / Sentiment analysis",
+                    lines=1,
+                )
+                gr.Examples(
+                    examples=[
+                        "Which products have the highest return rate?",
+                        "What are the main complaints in the reviews?",
+                        "What does the sentiment look like?",
+                        "Show me the rating distribution",
+                        "Give me a dashboard overview",
+                        "Which categories are highest risk?",
+                    ],
+                    inputs=user_input,
+                )
+
+            with gr.Column(scale=1):
+                ai_figure = gr.Plot(
+                    label="Interactive Chart",
+                )
+                ai_table = gr.Dataframe(
+                    label="Data Table",
+                    interactive=False,
+                )
+
+        user_input.submit(
+            ai_chat,
+            inputs=[user_input, chatbot],
+            outputs=[chatbot, user_input, ai_figure, ai_table],
+        )
+
+
+demo.launch(css=load_css(), allowed_paths=[str(BASE_DIR)])

archive.zip

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c1046fecda157adb083485fae9e219d4f76de68d26904c01e4a39b8fa8b9ecf
+size 2924120

datacreation.ipynb

@@ -0,0 +1,322 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 0,
+ "metadata": {
+  "colab": {
+   "provenance": []
+  },
+  "kernelspec": {
+   "name": "python3",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "cells": [
+  {
+   "cell_type": "code",
+   "source": [
+    "# ==================================================\n",
+    "# UNIVERSAL SETUP CELL\n",
+    "# Works in BOTH Google Colab and Hugging Face Spaces\n",
+    "# ==================================================\n",
+    "\n",
+    "import os\n",
+    "import random\n",
+    "import warnings\n",
+    "from pathlib import Path\n",
+    "\n",
+    "import numpy as np\n",
+    "import pandas as pd\n",
+    "\n",
+    "warnings.filterwarnings(\"ignore\")\n",
+    "\n",
+    "# Reproducibility\n",
+    "random.seed(42)\n",
+    "np.random.seed(42)\n",
+    "\n",
+    "# Detect environment automatically\n",
+    "if Path(\"/app\").exists():\n",
+    "    BASE_PATH = Path(\"/app\")          # Hugging Face Space\n",
+    "elif Path(\"/content\").exists():\n",
+    "    BASE_PATH = Path(\"/content\")      # Google Colab\n",
+    "else:\n",
+    "    BASE_PATH = Path.cwd()            # Local fallback\n",
+    "\n",
+    "DATA_PROCESSED = BASE_PATH / \"data_processed\"\n",
+    "OUTPUTS = BASE_PATH / \"outputs\"\n",
+    "\n",
+    "DATA_PROCESSED.mkdir(exist_ok=True)\n",
+    "OUTPUTS.mkdir(exist_ok=True)\n",
+    "\n",
+    "print(\"Environment ready.\")\n",
+    "print(\"Using BASE_PATH:\", BASE_PATH)\n",
+    "\n",
+    "# Find CSV files anywhere under BASE_PATH\n",
+    "csv_paths = [\n",
+    "    p for p in BASE_PATH.rglob(\"*.csv\")\n",
+    "    if \"sample_data\" not in str(p)\n",
+    "]\n",
+    "\n",
+    "print(\"Found CSV files:\")\n",
+    "for p in csv_paths:\n",
+    "    print(\"-\", p)\n",
+    "\n",
+    "# Locate required files\n",
+    "reviews_matches = [\n",
+    "    p for p in csv_paths\n",
+    "    if \"clothing\" in p.name.lower()\n",
+    "]\n",
+    "\n",
+    "returns_matches = [\n",
+    "    p for p in csv_paths\n",
+    "    if \"return\" in p.name.lower()\n",
+    "]\n",
+    "\n",
+    "if not reviews_matches:\n",
+    "    raise FileNotFoundError(\n",
+    "        \"Could not find the Womens Clothing E-Commerce Reviews CSV. \"\n",
+    "        \"Upload it to the Colab runtime OR put it in the same folder as app.py on Hugging Face.\"\n",
+    "    )\n",
+    "\n",
+    "if not returns_matches:\n",
+    "    raise FileNotFoundError(\n",
+    "        \"Could not find the ecommerce returns CSV. \"\n",
+    "        \"Upload it to the Colab runtime OR put it in the same folder as app.py on Hugging Face.\"\n",
+    "    )\n",
+    "\n",
+    "reviews_path = reviews_matches[0]\n",
+    "returns_path = returns_matches[0]\n",
+    "\n",
+    "print(\"Using reviews file:\", reviews_path)\n",
+    "print(\"Using returns file:\", returns_path)\n",
+    "\n",
+    "reviews_df = pd.read_csv(reviews_path)\n",
+    "returns_df = pd.read_csv(returns_path)\n",
+    "\n",
+    "# Main dataframe used by the rest of this notebook\n",
+    "df = reviews_df.copy()\n",
+    "\n",
+    "print(\"Loaded successfully.\")\n",
+    "print(\"Reviews shape:\", reviews_df.shape)\n",
+    "print(\"Returns shape:\", returns_df.shape)\n"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/"
+    },
+    "id": "bsHVIP13nWFe",
+    "outputId": "a44c956d-10cc-4879-f45f-e84c19bf7631"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "missing_summary = pd.DataFrame({\n",
+    "    \"column\": df.columns,\n",
+    "    \"missing_count\": df.isna().sum().values,\n",
+    "    \"missing_pct\": (df.isna().mean().values * 100).round(2)\n",
+    "}).sort_values(by=\"missing_pct\", ascending=False)\n",
+    "\n",
+    "display(missing_summary)"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 390
+    },
+    "id": "3qu3XSzfnV4-",
+    "outputId": "6480a5bb-b427-438e-8d5d-b9af2ebc67a0"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "df_clean = df.copy()\n",
+    "\n",
+    "# remove useless index column\n",
+    "df_clean = df_clean.drop(columns=[\"Unnamed: 0\"], errors=\"ignore\")\n",
+    "\n",
+    "# fill text columns\n",
+    "df_clean[\"Title\"] = df_clean[\"Title\"].fillna(\"No Title\")\n",
+    "df_clean[\"Review Text\"] = df_clean[\"Review Text\"].fillna(\"No Review\")\n",
+    "\n",
+    "# fill category columns\n",
+    "for col in [\"Department Name\", \"Class Name\", \"Division Name\"]:\n",
+    "    df_clean[col] = df_clean[col].fillna(\"Unknown\")\n",
+    "\n",
+    "# create sentiment label from rating\n",
+    "df_clean[\"sentiment\"] = df_clean[\"Rating\"].apply(\n",
+    "    lambda x: \"positive\" if x >= 4 else \"negative\"\n",
+    ")\n",
+    "\n",
+    "# create engagement score\n",
+    "df_clean[\"engagement_score\"] = (\n",
+    "    df_clean[\"Positive Feedback Count\"] + df_clean[\"Recommended IND\"]\n",
+    ")\n",
+    "\n",
+    "print(\"Cleaned shape:\", df_clean.shape)\n",
+    "display(df_clean.head())\n"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 633
+    },
+    "id": "da3lANHOnV13",
+    "outputId": "9704c238-2e77-4d74-a4c0-042526c0dfa2"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "class_summary = (\n",
+    "    df_clean.groupby(\"Class Name\")\n",
+    "    .agg(\n",
+    "        reviews=(\"Rating\", \"count\"),\n",
+    "        avg_rating=(\"Rating\", \"mean\"),\n",
+    "        recommendation_rate=(\"Recommended IND\", \"mean\"),\n",
+    "        avg_feedback=(\"Positive Feedback Count\", \"mean\")\n",
+    "    )\n",
+    "    .reset_index()\n",
+    ")\n",
+    "\n",
+    "# keep only classes with enough reviews\n",
+    "class_summary = class_summary[class_summary[\"reviews\"] >= 100]\n",
+    "\n",
+    "# sort by rating\n",
+    "class_summary = class_summary.sort_values(\n",
+    "    by=\"avg_rating\",\n",
+    "    ascending=False\n",
+    ")\n",
+    "\n",
+    "display(class_summary.head(10))\n",
+    "display(class_summary.tail(10))"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 701
+    },
+    "id": "MAW6wxDCnVzA",
+    "outputId": "c06b3a75-44d9-4620-ed82-e54a6c451c44"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "negative_reviews = df_clean[df_clean[\"sentiment\"] == \"negative\"].copy()\n",
+    "\n",
+    "print(\"Negative reviews:\", negative_reviews.shape)\n",
+    "\n",
+    "negative_reviews[\"Review Text\"] = negative_reviews[\"Review Text\"].astype(str)\n",
+    "\n",
+    "common_words = (\n",
+    "    negative_reviews[\"Review Text\"]\n",
+    "    .str.lower()\n",
+    "    .str.split(expand=True)\n",
+    "    .stack()\n",
+    "    .value_counts()\n",
+    "    .head(30)\n",
+    ")\n",
+    "\n",
+    "display(common_words)"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 1000
+    },
+    "id": "C6TafBY7nVv3",
+    "outputId": "ed36279a-1846-48a4-98d9-5c7839bd0b4b"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "code",
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "np.random.seed(42)\n",
+    "\n",
+    "synthetic_df = pd.DataFrame({\n",
+    "    \"customer_id\": range(1, 501),\n",
+    "    \"predicted_return_risk\": np.random.choice(\n",
+    "        [\"low\", \"medium\", \"high\"],\n",
+    "        size=500,\n",
+    "        p=[0.5, 0.3, 0.2]\n",
+    "    ),\n",
+    "    \"predicted_size_issue\": np.random.choice(\n",
+    "        [\"yes\", \"no\"],\n",
+    "        size=500,\n",
+    "        p=[0.25, 0.75]\n",
+    "    ),\n",
+    "    \"predicted_satisfaction_next_purchase\": np.random.randint(1, 6, 500)\n",
+    "})\n",
+    "\n",
+    "print(synthetic_df.shape)\n",
+    "display(synthetic_df.head())\n",
+    "\n",
+    "# Save outputs for the Hugging Face app / next analysis notebook\n",
+    "df_clean.to_csv(DATA_PROCESSED / \"reviews_cleaned.csv\", index=False)\n",
+    "class_summary.to_csv(DATA_PROCESSED / \"class_summary.csv\", index=False)\n",
+    "synthetic_df.to_csv(DATA_PROCESSED / \"synthetic_return_risk.csv\", index=False)\n",
+    "returns_df.to_csv(DATA_PROCESSED / \"returns_input.csv\", index=False)\n",
+    "\n",
+    "common_words.reset_index().rename(\n",
+    "    columns={\"index\": \"word\", \"Review Text\": \"count\", 0: \"count\"}\n",
+    ").to_csv(DATA_PROCESSED / \"common_negative_words.csv\", index=False)\n",
+    "\n",
+    "print(\"Saved processed files to:\", DATA_PROCESSED)\n",
+    "print([p.name for p in DATA_PROCESSED.glob(\"*.csv\")])\n"
+   ],
+   "metadata": {
+    "colab": {
+     "base_uri": "https://localhost:8080/",
+     "height": 222
+    },
+    "id": "gmcDmANBnVsP",
+    "outputId": "bba8768d-f088-419a-92ff-8092654ee950"
+   },
+   "execution_count": null,
+   "outputs": []
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# Automation Opportunities\n",
+    "\n",
+    "## Automation 1 — Review Sentiment Alert\n",
+    "Automatically flag clothing classes when average rating drops below 3.5.\n",
+    "\n",
+    "## Automation 2 — Product Improvement Suggestions\n",
+    "Use negative review keywords to automatically suggest:\n",
+    "- sizing guide improvements\n",
+    "- fabric description clarification\n",
+    "- fit recommendations\n",
+    "- photo quality updates\n",
+    "\n",
+    "## Automation 3 — Future Return Risk Dashboard\n",
+    "Combine real reviews with synthetic future risk signals to monitor:\n",
+    "- high-risk customer segments\n",
+    "- classes with repeated size complaints\n",
+    "- products likely to receive negative reviews next season"
+   ],
+   "metadata": {
+    "id": "fmUnLL36pT_z"
+   },
+   "outputs": [],
+   "execution_count": null
+  }
+ ]
+}

ecommerce_returns_cleaned.csv

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7feb1ef02dff68370245fbef6e84b04c691b631bfd56bf1afb3c547eb08cef17
+size 36312047

gitattributes

@@ -0,0 +1,37 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+background_top.png filter=lfs diff=lfs merge=lfs -text
+ecommerce_returns_cleaned.csv filter=lfs diff=lfs merge=lfs -text

gitattributes (1)

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+background_top.png filter=lfs diff=lfs merge=lfs -text

gitattributes (2)

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+background_top.png filter=lfs diff=lfs merge=lfs -text

pythonanalysis.ipynb

@@ -0,0 +1,1046 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "85361b58",
+      "metadata": {
+        "id": "85361b58"
+      },
+      "source": [
+        "# Step 2 — Python Analysis / Modeling\n",
+        "\n",
+        "Clean version for the Hugging Face SE21 app template. It creates dashboard artifacts."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 5,
+      "id": "c88b847c",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "c88b847c",
+        "outputId": "d0c3643a-d491-4746-a55b-35ed016e4fe4"
+      },
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "Environment ready.\n",
+            "BASE_PATH: /content\n",
+            "CSV files found:\n",
+            "- /content/Womens Clothing E-Commerce Reviews.csv\n",
+            "- /content/ecommerce_returns_cleaned.csv\n",
+            "Using reviews file: /content/Womens Clothing E-Commerce Reviews.csv\n",
+            "Using returns file: /content/ecommerce_returns_cleaned.csv\n",
+            "Reviews shape: (23486, 10)\n",
+            "Returns shape: (113314, 29)\n",
+            "Reviews columns: ['Clothing ID', 'Age', 'Title', 'Review Text', 'Rating', 'Recommended IND', 'Positive Feedback Count', 'Division Name', 'Department Name', 'Class Name']\n",
+            "Returns columns: ['order_id', 'order_item_id', 'product_id', 'seller_id', 'customer_id', 'order_status', 'order_purchase_timestamp', 'order_delivered_customer_date', 'order_estimated_delivery_date', 'review_score', 'review_comment_title', 'review_comment_message', 'price', 'freight_value', 'total_cost', 'product_category_name', 'product_name_lenght', 'product_description_lenght', 'product_photos_qty', 'product_weight_g', 'product_length_cm', 'product_height_cm', 'product_width_cm', 'has_review_text', 'review_text_length', 'delivery_delay_days', 'negative_keyword_flag', 'synthetic_return_risk', 'likely_return']\n",
+            "Data loaded and cleaned.\n"
+          ]
+        }
+      ],
+      "source": [
+        "# ==================================================\n",
+        "# STEP 2: UNIVERSAL ANALYSIS SETUP\n",
+        "# Works in BOTH Hugging Face Spaces and Google Colab\n",
+        "# ==================================================\n",
+        "\n",
+        "import os\n",
+        "import json\n",
+        "import random\n",
+        "import warnings\n",
+        "from pathlib import Path\n",
+        "\n",
+        "os.environ.setdefault(\"MPLCONFIGDIR\", \"/tmp/matplotlib\")\n",
+        "\n",
+        "import numpy as np\n",
+        "import pandas as pd\n",
+        "import matplotlib.pyplot as plt\n",
+        "\n",
+        "warnings.filterwarnings(\"ignore\")\n",
+        "random.seed(42)\n",
+        "np.random.seed(42)\n",
+        "\n",
+        "# Pick the correct runtime folder automatically.\n",
+        "# Hugging Face Space uses /app. Colab uses /content.\n",
+        "candidate_roots = [Path(\"/app\"), Path(\"/content\"), Path.cwd(), Path(\"/mnt/data\")]\n",
+        "BASE_PATH = None\n",
+        "\n",
+        "for root in candidate_roots:\n",
+        "    if root.exists():\n",
+        "        csvs = []\n",
+        "        for p in root.rglob(\"*.csv\"):\n",
+        "            parts = {part.lower() for part in p.parts}\n",
+        "            if \"sample_data\" in parts:\n",
+        "                continue\n",
+        "            if \"outputs\" in parts or \"figures\" in parts or \"tables\" in parts or \"artifacts\" in parts:\n",
+        "                continue\n",
+        "            csvs.append(p)\n",
+        "        if csvs:\n",
+        "            BASE_PATH = root\n",
+        "            break\n",
+        "\n",
+        "if BASE_PATH is None:\n",
+        "    if Path(\"/app\").exists():\n",
+        "        BASE_PATH = Path(\"/app\")\n",
+        "    elif Path(\"/content\").exists():\n",
+        "        BASE_PATH = Path(\"/content\")\n",
+        "    else:\n",
+        "        BASE_PATH = Path.cwd()\n",
+        "\n",
+        "DATA_PROCESSED = BASE_PATH / \"data_processed\"\n",
+        "\n",
+        "OUTPUTS = BASE_PATH / \"outputs\"\n",
+        "FIGURES = BASE_PATH / \"figures\"\n",
+        "TABLES = BASE_PATH / \"tables\"\n",
+        "ARTIFACTS = BASE_PATH / \"artifacts\"\n",
+        "\n",
+        "# Extra folders because different templates check different places\n",
+        "OUTPUT_FIGURES = OUTPUTS / \"figures\"\n",
+        "OUTPUT_TABLES = OUTPUTS / \"tables\"\n",
+        "ARTIFACT_FIGURES = ARTIFACTS / \"figures\"\n",
+        "ARTIFACT_TABLES = ARTIFACTS / \"tables\"\n",
+        "\n",
+        "ALL_OUTPUT_DIRS = [\n",
+        "    DATA_PROCESSED,\n",
+        "    OUTPUTS,\n",
+        "    FIGURES,\n",
+        "    TABLES,\n",
+        "    ARTIFACTS,\n",
+        "    OUTPUT_FIGURES,\n",
+        "    OUTPUT_TABLES,\n",
+        "    ARTIFACT_FIGURES,\n",
+        "    ARTIFACT_TABLES,\n",
+        "]\n",
+        "\n",
+        "for folder in ALL_OUTPUT_DIRS:\n",
+        "    folder.mkdir(parents=True, exist_ok=True)\n",
+        "\n",
+        "print(\"Environment ready.\")\n",
+        "print(\"BASE_PATH:\", BASE_PATH)\n",
+        "\n",
+        "# Load data created by Step 1 if available.\n",
+        "csv_paths = []\n",
+        "for p in BASE_PATH.rglob(\"*.csv\"):\n",
+        "    parts = {part.lower() for part in p.parts}\n",
+        "    if \"sample_data\" in parts:\n",
+        "        continue\n",
+        "    if \"outputs\" in parts or \"figures\" in parts or \"tables\" in parts or \"artifacts\" in parts:\n",
+        "        continue\n",
+        "    csv_paths.append(p)\n",
+        "\n",
+        "print(\"CSV files found:\")\n",
+        "for p in csv_paths:\n",
+        "    print(\"-\", p)\n",
+        "\n",
+        "def first_existing(paths):\n",
+        "    for p in paths:\n",
+        "        if Path(p).exists():\n",
+        "            return Path(p)\n",
+        "    return None\n",
+        "\n",
+        "reviews_path = first_existing([\n",
+        "    DATA_PROCESSED / \"reviews_cleaned.csv\",\n",
+        "    DATA_PROCESSED / \"womens_reviews_cleaned.csv\",\n",
+        "    BASE_PATH / \"Womens Clothing E-Commerce Reviews.csv\",\n",
+        "])\n",
+        "\n",
+        "returns_path = first_existing([\n",
+        "    DATA_PROCESSED / \"returns_input.csv\",\n",
+        "    DATA_PROCESSED / \"returns_cleaned.csv\",\n",
+        "    BASE_PATH / \"ecommerce_returns_cleaned.csv\",\n",
+        "    DATA_PROCESSED / \"synthetic_return_risk.csv\",\n",
+        "])\n",
+        "\n",
+        "# Fallback search.\n",
+        "if reviews_path is None:\n",
+        "    review_matches = [\n",
+        "        p for p in csv_paths\n",
+        "        if (\"clothing\" in p.name.lower()) or (\"review\" in p.name.lower() and \"return\" not in p.name.lower())\n",
+        "    ]\n",
+        "    reviews_path = review_matches[0] if review_matches else None\n",
+        "\n",
+        "if returns_path is None:\n",
+        "    return_matches = [\n",
+        "        p for p in csv_paths\n",
+        "        if \"return\" in p.name.lower()\n",
+        "    ]\n",
+        "    returns_path = return_matches[0] if return_matches else None\n",
+        "\n",
+        "\n",
+        "if returns_path is None:\n",
+        "    raise FileNotFoundError(\"Step 2 could not find the ecommerce returns CSV.\")\n",
+        "\n",
+        "print(\"Using reviews file:\", reviews_path)\n",
+        "print(\"Using returns file:\", returns_path)\n",
+        "\n",
+        "reviews_df = pd.read_csv(reviews_path).drop(columns=[\"Unnamed: 0\"], errors=\"ignore\")\n",
+        "returns_df = pd.read_csv(returns_path).drop(columns=[\"Unnamed: 0\"], errors=\"ignore\")\n",
+        "\n",
+        "print(\"Reviews shape:\", reviews_df.shape)\n",
+        "print(\"Returns shape:\", returns_df.shape)\n",
+        "print(\"Reviews columns:\", reviews_df.columns.tolist())\n",
+        "print(\"Returns columns:\", returns_df.columns.tolist())\n",
+        "\n",
+        "# Basic cleanup / type safety\n",
+        "for col in [\"Age\", \"Rating\", \"Recommended IND\", \"Positive Feedback Count\"]:\n",
+        "    if col in reviews_df.columns:\n",
+        "        reviews_df[col] = pd.to_numeric(reviews_df[col], errors=\"coerce\")\n",
+        "\n",
+        "if \"Review Text\" in reviews_df.columns:\n",
+        "    reviews_df[\"Review Text\"] = reviews_df[\"Review Text\"].fillna(\"\").astype(str)\n",
+        "\n",
+        "if \"Class Name\" in reviews_df.columns:\n",
+        "    reviews_df[\"Class Name\"] = reviews_df[\"Class Name\"].fillna(\"Unknown\").astype(str)\n",
+        "\n",
+        "for col in [\"review_score\", \"likely_return\", \"price\", \"freight_value\", \"delivery_delay_days\", \"synthetic_return_risk\"]:\n",
+        "    if col in returns_df.columns:\n",
+        "        returns_df[col] = pd.to_numeric(returns_df[col], errors=\"coerce\")\n",
+        "\n",
+        "print(\"Data loaded and cleaned.\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 6,
+      "id": "f9eb3801",
+      "metadata": {
+        "id": "f9eb3801"
+      },
+      "outputs": [],
+      "source": [
+        "# ==================================================\n",
+        "# HELPERS: save artifacts where the app can find them\n",
+        "# ==================================================\n",
+        "# ==================================================\n",
+        "# HELPERS: save artifacts everywhere the app may check\n",
+        "# ==================================================\n",
+        "\n",
+        "def safe_write_csv(df, path):\n",
+        "    try:\n",
+        "        df.to_csv(path)\n",
+        "        return True\n",
+        "    except Exception as e:\n",
+        "        print(f\"Could not save {path}: {e}\")\n",
+        "        return False\n",
+        "\n",
+        "\n",
+        "def safe_savefig(path):\n",
+        "    try:\n",
+        "        plt.savefig(path, dpi=150, bbox_inches=\"tight\")\n",
+        "        return True\n",
+        "    except Exception as e:\n",
+        "        print(f\"Could not save {path}: {e}\")\n",
+        "        return False\n",
+        "\n",
+        "\n",
+        "def safe_write_text(text, path):\n",
+        "    try:\n",
+        "        path.write_text(text, encoding=\"utf-8\")\n",
+        "        return True\n",
+        "    except Exception as e:\n",
+        "        print(f\"Could not save {path}: {e}\")\n",
+        "        return False\n",
+        "\n",
+        "\n",
+        "def save_table(df, name):\n",
+        "    if isinstance(df, pd.Series):\n",
+        "        df = df.to_frame()\n",
+        "\n",
+        "    table_folders = [\n",
+        "        TABLES,\n",
+        "        OUTPUT_TABLES,\n",
+        "        OUTPUTS,\n",
+        "        ARTIFACT_TABLES,\n",
+        "        ARTIFACTS,\n",
+        "    ]\n",
+        "\n",
+        "    saved_anywhere = False\n",
+        "\n",
+        "    for folder in table_folders:\n",
+        "        folder.mkdir(parents=True, exist_ok=True)\n",
+        "        path = folder / f\"{name}.csv\"\n",
+        "        saved_anywhere = safe_write_csv(df, path) or saved_anywhere\n",
+        "\n",
+        "    if saved_anywhere:\n",
+        "        print(f\"Saved table everywhere: {name}.csv\")\n",
+        "    else:\n",
+        "        raise RuntimeError(f\"Could not save table {name}.csv\")\n",
+        "\n",
+        "\n",
+        "def save_figure(name):\n",
+        "    figure_folders = [\n",
+        "        FIGURES,\n",
+        "        OUTPUT_FIGURES,\n",
+        "        OUTPUTS,\n",
+        "        ARTIFACT_FIGURES,\n",
+        "        ARTIFACTS,\n",
+        "    ]\n",
+        "\n",
+        "    saved_anywhere = False\n",
+        "\n",
+        "    for folder in figure_folders:\n",
+        "        folder.mkdir(parents=True, exist_ok=True)\n",
+        "        path = folder / f\"{name}.png\"\n",
+        "        saved_anywhere = safe_savefig(path) or saved_anywhere\n",
+        "\n",
+        "    if saved_anywhere:\n",
+        "        print(f\"Saved figure everywhere: {name}.png\")\n",
+        "    else:\n",
+        "        raise RuntimeError(f\"Could not save figure {name}.png\")\n",
+        "\n",
+        "\n",
+        "def save_text(text, name):\n",
+        "    text_folders = [\n",
+        "        TABLES,\n",
+        "        OUTPUT_TABLES,\n",
+        "        OUTPUTS,\n",
+        "        ARTIFACT_TABLES,\n",
+        "        ARTIFACTS,\n",
+        "    ]\n",
+        "\n",
+        "    saved_anywhere = False\n",
+        "\n",
+        "    for folder in text_folders:\n",
+        "        folder.mkdir(parents=True, exist_ok=True)\n",
+        "        path = folder / f\"{name}.txt\"\n",
+        "        saved_anywhere = safe_write_text(text, path) or saved_anywhere\n",
+        "\n",
+        "    if saved_anywhere:\n",
+        "        print(f\"Saved text everywhere: {name}.txt\")\n",
+        "    else:\n",
+        "        raise RuntimeError(f\"Could not save text {name}.txt\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 7,
+      "id": "a99949ac",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "a99949ac",
+        "outputId": "33b9f5b0-67b0-4a44-8eef-b572cb8f7492"
+      },
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "Saved table everywhere: rating_distribution.csv\n",
+            "Saved figure everywhere: rating_distribution.png\n",
+            "Saved table everywhere: recommendation_by_class.csv\n",
+            "Saved figure everywhere: recommendation_by_class.png\n",
+            "Saved table everywhere: average_rating_by_age.csv\n",
+            "Saved figure everywhere: average_rating_by_age.png\n",
+            "Saved table everywhere: negative_keyword_counts.csv\n",
+            "Saved figure everywhere: negative_keyword_counts.png\n",
+            "Saved table everywhere: category_return_rate.csv\n",
+            "Saved figure everywhere: category_return_rate.png\n",
+            "Saved table everywhere: monthly_return_rate.csv\n",
+            "Saved figure everywhere: monthly_return_rate.png\n",
+            "Saved table everywhere: feature_importance.csv\n",
+            "Saved figure everywhere: feature_importance.png\n",
+            "Saved text everywhere: classification_report.txt\n",
+            "Artifact creation section finished.\n"
+          ]
+        }
+      ],
+      "source": [
+        "# ==================================================\n",
+        "# CREATE DASHBOARD ARTIFACTS\n",
+        "# ==================================================\n",
+        "\n",
+        "created_figures = []\n",
+        "created_tables = []\n",
+        "\n",
+        "# 1) Rating distribution\n",
+        "if \"Rating\" in reviews_df.columns:\n",
+        "    rating_distribution = reviews_df[\"Rating\"].dropna().value_counts().sort_index().to_frame(\"count\")\n",
+        "    save_table(rating_distribution, \"rating_distribution\")\n",
+        "    created_tables.append(\"rating_distribution.csv\")\n",
+        "\n",
+        "    plt.figure(figsize=(7, 4))\n",
+        "    plt.bar(rating_distribution.index.astype(str), rating_distribution[\"count\"])\n",
+        "    plt.title(\"Distribution of Customer Ratings\")\n",
+        "    plt.xlabel(\"Rating\")\n",
+        "    plt.ylabel(\"Number of Reviews\")\n",
+        "    plt.tight_layout()\n",
+        "    save_figure(\"rating_distribution\")\n",
+        "    created_figures.append(\"rating_distribution.png\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# 2) Recommendation rate by clothing class\n",
+        "if {\"Class Name\", \"Recommended IND\"}.issubset(reviews_df.columns):\n",
+        "    recommendation_by_class = (\n",
+        "        reviews_df.groupby(\"Class Name\")[\"Recommended IND\"]\n",
+        "        .mean()\n",
+        "        .sort_values(ascending=False)\n",
+        "        .head(10)\n",
+        "        .to_frame(\"recommendation_rate\")\n",
+        "    )\n",
+        "    save_table(recommendation_by_class, \"recommendation_by_class\")\n",
+        "    created_tables.append(\"recommendation_by_class.csv\")\n",
+        "\n",
+        "    plt.figure(figsize=(10, 5))\n",
+        "    plt.bar(recommendation_by_class.index.astype(str), recommendation_by_class[\"recommendation_rate\"])\n",
+        "    plt.title(\"Top 10 Most Recommended Clothing Classes\")\n",
+        "    plt.xlabel(\"Class Name\")\n",
+        "    plt.ylabel(\"Recommendation Rate\")\n",
+        "    plt.xticks(rotation=75)\n",
+        "    plt.tight_layout()\n",
+        "    save_figure(\"recommendation_by_class\")\n",
+        "    created_figures.append(\"recommendation_by_class.png\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# 3) Average rating by age\n",
+        "if {\"Age\", \"Rating\"}.issubset(reviews_df.columns):\n",
+        "    average_rating_by_age = (\n",
+        "        reviews_df.groupby(\"Age\")[\"Rating\"]\n",
+        "        .mean()\n",
+        "        .dropna()\n",
+        "        .to_frame(\"average_rating\")\n",
+        "    )\n",
+        "    save_table(average_rating_by_age, \"average_rating_by_age\")\n",
+        "    created_tables.append(\"average_rating_by_age.csv\")\n",
+        "\n",
+        "    plt.figure(figsize=(10, 4))\n",
+        "    plt.plot(average_rating_by_age.index, average_rating_by_age[\"average_rating\"])\n",
+        "    plt.title(\"Average Rating by Customer Age\")\n",
+        "    plt.xlabel(\"Age\")\n",
+        "    plt.ylabel(\"Average Rating\")\n",
+        "    plt.tight_layout()\n",
+        "    save_figure(\"average_rating_by_age\")\n",
+        "    created_figures.append(\"average_rating_by_age.png\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# 4) Complaint / return-risk keyword counts\n",
+        "review_text_column = None\n",
+        "for candidate in [\"Review Text\", \"review_text\", \"review_comment_message\"]:\n",
+        "    if candidate in reviews_df.columns:\n",
+        "        review_text_column = candidate\n",
+        "        break\n",
+        "\n",
+        "if review_text_column is not None:\n",
+        "    keywords = [\n",
+        "        \"bad\", \"poor\", \"cheap\", \"small\", \"large\", \"tight\", \"loose\",\n",
+        "        \"scratchy\", \"thin\", \"return\", \"returned\", \"disappointed\",\n",
+        "        \"quality\", \"fit\", \"sizing\", \"fabric\", \"uncomfortable\"\n",
+        "    ]\n",
+        "    text_series = reviews_df[review_text_column].fillna(\"\").astype(str).str.lower()\n",
+        "    keyword_counts = {}\n",
+        "    for word in keywords:\n",
+        "        keyword_counts[word] = int(text_series.str.contains(word, regex=False).sum())\n",
+        "\n",
+        "    negative_keyword_counts = (\n",
+        "        pd.DataFrame(keyword_counts.items(), columns=[\"keyword\", \"review_count\"])\n",
+        "        .sort_values(\"review_count\", ascending=False)\n",
+        "        .set_index(\"keyword\")\n",
+        "    )\n",
+        "    save_table(negative_keyword_counts, \"negative_keyword_counts\")\n",
+        "    created_tables.append(\"negative_keyword_counts.csv\")\n",
+        "\n",
+        "    top_keywords = negative_keyword_counts.head(10)\n",
+        "    plt.figure(figsize=(9, 4))\n",
+        "    plt.bar(top_keywords.index.astype(str), top_keywords[\"review_count\"])\n",
+        "    plt.title(\"Most Common Return-Risk Keywords in Reviews\")\n",
+        "    plt.xlabel(\"Keyword\")\n",
+        "    plt.ylabel(\"Number of Reviews\")\n",
+        "    plt.xticks(rotation=45)\n",
+        "    plt.tight_layout()\n",
+        "    save_figure(\"negative_keyword_counts\")\n",
+        "    created_figures.append(\"negative_keyword_counts.png\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# 5) Product category return rate\n",
+        "if {\"product_category_name\", \"likely_return\"}.issubset(returns_df.columns):\n",
+        "    category_return_rate = (\n",
+        "        returns_df.groupby(\"product_category_name\")[\"likely_return\"]\n",
+        "        .mean()\n",
+        "        .sort_values(ascending=False)\n",
+        "        .head(15)\n",
+        "        .to_frame(\"return_rate\")\n",
+        "    )\n",
+        "    save_table(category_return_rate, \"category_return_rate\")\n",
+        "    created_tables.append(\"category_return_rate.csv\")\n",
+        "\n",
+        "    plt.figure(figsize=(11, 5))\n",
+        "    plt.bar(category_return_rate.index.astype(str), category_return_rate[\"return_rate\"])\n",
+        "    plt.title(\"Top Product Categories by Estimated Return Rate\")\n",
+        "    plt.xlabel(\"Product Category\")\n",
+        "    plt.ylabel(\"Return Rate\")\n",
+        "    plt.xticks(rotation=75)\n",
+        "    plt.tight_layout()\n",
+        "    save_figure(\"category_return_rate\")\n",
+        "    created_figures.append(\"category_return_rate.png\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# 6) Monthly return rate\n",
+        "if {\"order_purchase_timestamp\", \"likely_return\"}.issubset(returns_df.columns):\n",
+        "    monthly_df = returns_df.copy()\n",
+        "    monthly_df[\"order_purchase_timestamp\"] = pd.to_datetime(monthly_df[\"order_purchase_timestamp\"], errors=\"coerce\")\n",
+        "    monthly_df = monthly_df.dropna(subset=[\"order_purchase_timestamp\"])\n",
+        "\n",
+        "    if len(monthly_df) > 0:\n",
+        "        monthly_return_rate = (\n",
+        "            monthly_df.set_index(\"order_purchase_timestamp\")\n",
+        "            .resample(\"M\")[\"likely_return\"]\n",
+        "            .mean()\n",
+        "            .dropna()\n",
+        "            .to_frame(\"return_rate\")\n",
+        "        )\n",
+        "        save_table(monthly_return_rate, \"monthly_return_rate\")\n",
+        "        created_tables.append(\"monthly_return_rate.csv\")\n",
+        "\n",
+        "        plt.figure(figsize=(10, 4))\n",
+        "        plt.plot(monthly_return_rate.index, monthly_return_rate[\"return_rate\"])\n",
+        "        plt.title(\"Monthly Estimated Return Rate\")\n",
+        "        plt.xlabel(\"Month\")\n",
+        "        plt.ylabel(\"Return Rate\")\n",
+        "        plt.tight_layout()\n",
+        "        save_figure(\"monthly_return_rate\")\n",
+        "        created_figures.append(\"monthly_return_rate.png\")\n",
+        "        plt.close()\n",
+        "\n",
+        "# 7) Simple feature importance if sklearn is available\n",
+        "try:\n",
+        "    from sklearn.ensemble import RandomForestClassifier\n",
+        "    from sklearn.model_selection import train_test_split\n",
+        "    from sklearn.metrics import accuracy_score, classification_report\n",
+        "\n",
+        "    feature_columns = [c for c in [\"Age\", \"Rating\", \"Positive Feedback Count\"] if c in reviews_df.columns]\n",
+        "    if \"Recommended IND\" in reviews_df.columns and len(feature_columns) > 0:\n",
+        "        model_df = reviews_df[feature_columns + [\"Recommended IND\"]].dropna().copy()\n",
+        "        if model_df[\"Recommended IND\"].nunique() >= 2:\n",
+        "            X = model_df[feature_columns]\n",
+        "            y = model_df[\"Recommended IND\"].astype(int)\n",
+        "            X_train, X_test, y_train, y_test = train_test_split(\n",
+        "                X, y, test_size=0.2, random_state=42, stratify=y\n",
+        "            )\n",
+        "\n",
+        "            clf = RandomForestClassifier(n_estimators=100, random_state=42)\n",
+        "            clf.fit(X_train, y_train)\n",
+        "            predictions = clf.predict(X_test)\n",
+        "            accuracy = accuracy_score(y_test, predictions)\n",
+        "\n",
+        "            feature_importance = (\n",
+        "                pd.Series(clf.feature_importances_, index=feature_columns)\n",
+        "                .sort_values(ascending=False)\n",
+        "                .to_frame(\"importance\")\n",
+        "            )\n",
+        "            save_table(feature_importance, \"feature_importance\")\n",
+        "            created_tables.append(\"feature_importance.csv\")\n",
+        "\n",
+        "            plt.figure(figsize=(7, 4))\n",
+        "            plt.bar(feature_importance.index.astype(str), feature_importance[\"importance\"])\n",
+        "            plt.title(\"Feature Importance for Recommendation Prediction\")\n",
+        "            plt.xlabel(\"Feature\")\n",
+        "            plt.ylabel(\"Importance\")\n",
+        "            plt.tight_layout()\n",
+        "            save_figure(\"feature_importance\")\n",
+        "            created_figures.append(\"feature_importance.png\")\n",
+        "            plt.close()\n",
+        "\n",
+        "            report = \"Model accuracy: {:.4f}\\n\\n{}\".format(\n",
+        "                accuracy,\n",
+        "                classification_report(y_test, predictions)\n",
+        "            )\n",
+        "            save_text(report, \"classification_report\")\n",
+        "except Exception as e:\n",
+        "    print(\"ML section skipped:\", repr(e))\n",
+        "\n",
+        "print(\"Artifact creation section finished.\")"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": 8,
+      "id": "c4bbc916",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "c4bbc916",
+        "outputId": "1dc63b01-ed81-47cd-cf56-3e193b2f87f2"
+      },
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "Saved table everywhere: dashboard_summary.csv\n",
+            "Saved text everywhere: business_insights_report.txt\n",
+            "STEP 2 COMPLETE.\n",
+            "Figures: ['average_rating_by_age.png', 'category_return_rate.png', 'feature_importance.png', 'monthly_return_rate.png', 'negative_keyword_counts.png', 'rating_distribution.png', 'recommendation_by_class.png']\n",
+            "Tables: ['average_rating_by_age.csv', 'category_return_rate.csv', 'dashboard_summary.csv', 'feature_importance.csv', 'monthly_return_rate.csv', 'negative_keyword_counts.csv', 'rating_distribution.csv', 'recommendation_by_class.csv']\n",
+            "Outputs: ['average_rating_by_age.csv', 'average_rating_by_age.png', 'business_insights_report.txt', 'category_return_rate.csv', 'category_return_rate.png', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'feature_importance.png', 'monthly_return_rate.csv', 'monthly_return_rate.png', 'negative_keyword_counts.csv', 'negative_keyword_counts.png', 'rating_distribution.csv', 'rating_distribution.png', 'recommendation_by_class.csv', 'recommendation_by_class.png']\n"
+          ]
+        }
+      ],
+      "source": [
+        "# ==================================================\n",
+        "# FINAL REPORT + MANIFEST\n",
+        "# ==================================================\n",
+        "\n",
+        "summary_rows = [\n",
+        "    {\"metric\": \"reviews_rows\", \"value\": int(len(reviews_df))},\n",
+        "    {\"metric\": \"returns_rows\", \"value\": int(len(returns_df))},\n",
+        "    {\"metric\": \"figures_created\", \"value\": int(len(list(FIGURES.glob(\"*.png\"))))},\n",
+        "    {\"metric\": \"tables_created\", \"value\": int(len(list(TABLES.glob(\"*.csv\"))))},\n",
+        "]\n",
+        "\n",
+        "summary_df = pd.DataFrame(summary_rows).set_index(\"metric\")\n",
+        "save_table(summary_df, \"dashboard_summary\")\n",
+        "\n",
+        "insights = \"\"\"\n",
+        "FINAL BUSINESS INSIGHTS\n",
+        "=======================\n",
+        "\n",
+        "This analysis supports an e-commerce return prediction and review intelligence assistant.\n",
+        "\n",
+        "Main findings:\n",
+        "- Customer ratings and recommendation behavior are useful signals for product satisfaction.\n",
+        "- Review text reveals return-risk themes such as fit, sizing, fabric, quality, and discomfort.\n",
+        "- Product categories with higher estimated return rates should be prioritized for improvement.\n",
+        "- Monthly return-rate tracking can help the business monitor operational or seasonal changes.\n",
+        "\n",
+        "Recommended automations:\n",
+        "1. Automatically scan new reviews for return-risk keywords.\n",
+        "2. Automatically rank products and categories by estimated return risk.\n",
+        "3. Automatically generate business recommendations for product pages, sizing guidance, and quality control.\n",
+        "\"\"\"\n",
+        "\n",
+        "save_text(insights, \"business_insights_report\")\n",
+        "\n",
+        "manifest = {\n",
+        "    \"base_path\": str(BASE_PATH),\n",
+        "    \"figures\": sorted([p.name for p in FIGURES.glob(\"*.png\")]),\n",
+        "    \"tables\": sorted([p.name for p in TABLES.glob(\"*.csv\")]),\n",
+        "    \"outputs\": sorted([p.name for p in OUTPUTS.iterdir() if p.is_file()]),\n",
+        "}\n",
+        "\n",
+        "for folder in [OUTPUTS, ARTIFACTS, TABLES]:\n",
+        "    try:\n",
+        "        with open(folder / \"artifacts_manifest.json\", \"w\", encoding=\"utf-8\") as f:\n",
+        "            json.dump(manifest, f, indent=2)\n",
+        "    except Exception as e:\n",
+        "        print(f\"Could not save manifest in {folder}: {e}\")\n",
+        "\n",
+        "print(\"STEP 2 COMPLETE.\")\n",
+        "print(\"Figures:\", manifest[\"figures\"])\n",
+        "print(\"Tables:\", manifest[\"tables\"])\n",
+        "print(\"Outputs:\", manifest[\"outputs\"])"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "print(\"\\nFINAL ARTIFACT CHECK\")\n",
+        "\n",
+        "check_dirs = {\n",
+        "    \"FIGURES\": FIGURES,\n",
+        "    \"TABLES\": TABLES,\n",
+        "    \"OUTPUTS\": OUTPUTS,\n",
+        "    \"OUTPUT_FIGURES\": OUTPUT_FIGURES,\n",
+        "    \"OUTPUT_TABLES\": OUTPUT_TABLES,\n",
+        "    \"ARTIFACTS\": ARTIFACTS,\n",
+        "    \"ARTIFACT_FIGURES\": ARTIFACT_FIGURES,\n",
+        "    \"ARTIFACT_TABLES\": ARTIFACT_TABLES,\n",
+        "}\n",
+        "\n",
+        "for label, folder in check_dirs.items():\n",
+        "    files = sorted([p.name for p in folder.iterdir() if p.is_file()])\n",
+        "    print(label, \"=\", files)"
+      ],
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "fexa62gDM2c7",
+        "outputId": "e84626f3-e126-43f8-a408-665ccd7eb914"
+      },
+      "id": "fexa62gDM2c7",
+      "execution_count": 9,
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "\n",
+            "FINAL ARTIFACT CHECK\n",
+            "FIGURES = ['average_rating_by_age.png', 'category_return_rate.png', 'feature_importance.png', 'monthly_return_rate.png', 'negative_keyword_counts.png', 'rating_distribution.png', 'recommendation_by_class.png']\n",
+            "TABLES = ['artifacts_manifest.json', 'average_rating_by_age.csv', 'business_insights_report.txt', 'category_return_rate.csv', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'monthly_return_rate.csv', 'negative_keyword_counts.csv', 'rating_distribution.csv', 'recommendation_by_class.csv']\n",
+            "OUTPUTS = ['artifacts_manifest.json', 'average_rating_by_age.csv', 'average_rating_by_age.png', 'business_insights_report.txt', 'category_return_rate.csv', 'category_return_rate.png', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'feature_importance.png', 'monthly_return_rate.csv', 'monthly_return_rate.png', 'negative_keyword_counts.csv', 'negative_keyword_counts.png', 'rating_distribution.csv', 'rating_distribution.png', 'recommendation_by_class.csv', 'recommendation_by_class.png']\n",
+            "OUTPUT_FIGURES = ['average_rating_by_age.png', 'category_return_rate.png', 'feature_importance.png', 'monthly_return_rate.png', 'negative_keyword_counts.png', 'rating_distribution.png', 'recommendation_by_class.png']\n",
+            "OUTPUT_TABLES = ['average_rating_by_age.csv', 'business_insights_report.txt', 'category_return_rate.csv', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'monthly_return_rate.csv', 'negative_keyword_counts.csv', 'rating_distribution.csv', 'recommendation_by_class.csv']\n",
+            "ARTIFACTS = ['artifacts_manifest.json', 'average_rating_by_age.csv', 'average_rating_by_age.png', 'business_insights_report.txt', 'category_return_rate.csv', 'category_return_rate.png', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'feature_importance.png', 'monthly_return_rate.csv', 'monthly_return_rate.png', 'negative_keyword_counts.csv', 'negative_keyword_counts.png', 'rating_distribution.csv', 'rating_distribution.png', 'recommendation_by_class.csv', 'recommendation_by_class.png']\n",
+            "ARTIFACT_FIGURES = ['average_rating_by_age.png', 'category_return_rate.png', 'feature_importance.png', 'monthly_return_rate.png', 'negative_keyword_counts.png', 'rating_distribution.png', 'recommendation_by_class.png']\n",
+            "ARTIFACT_TABLES = ['average_rating_by_age.csv', 'business_insights_report.txt', 'category_return_rate.csv', 'classification_report.txt', 'dashboard_summary.csv', 'feature_importance.csv', 'monthly_return_rate.csv', 'negative_keyword_counts.csv', 'rating_distribution.csv', 'recommendation_by_class.csv']\n"
+          ]
+        }
+      ]
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "# ==================================================\n",
+        "# FORCE DASHBOARD ARTIFACTS FOR SE21 HUGGING FACE APP\n",
+        "# Put this as the VERY LAST CELL of pythonanalysis.ipynb\n",
+        "# ==================================================\n",
+        "\n",
+        "import os\n",
+        "import json\n",
+        "from pathlib import Path\n",
+        "\n",
+        "import pandas as pd\n",
+        "import numpy as np\n",
+        "\n",
+        "import matplotlib\n",
+        "matplotlib.use(\"Agg\")\n",
+        "import matplotlib.pyplot as plt\n",
+        "\n",
+        "# Detect runtime\n",
+        "if Path(\"/app\").exists():\n",
+        "    BASE_PATH = Path(\"/app\")\n",
+        "elif Path(\"/content\").exists():\n",
+        "    BASE_PATH = Path(\"/content\")\n",
+        "else:\n",
+        "    BASE_PATH = Path.cwd()\n",
+        "\n",
+        "# THESE ARE THE EXACT FOLDERS app.py READS\n",
+        "PY_FIG_DIR = BASE_PATH / \"artifacts\" / \"py\" / \"figures\"\n",
+        "PY_TAB_DIR = BASE_PATH / \"artifacts\" / \"py\" / \"tables\"\n",
+        "\n",
+        "PY_FIG_DIR.mkdir(parents=True, exist_ok=True)\n",
+        "PY_TAB_DIR.mkdir(parents=True, exist_ok=True)\n",
+        "\n",
+        "print(\"Saving dashboard artifacts to:\")\n",
+        "print(\"Figures:\", PY_FIG_DIR)\n",
+        "print(\"Tables:\", PY_TAB_DIR)\n",
+        "\n",
+        "# Find CSV files\n",
+        "csv_paths = [\n",
+        "    p for p in BASE_PATH.rglob(\"*.csv\")\n",
+        "    if \"sample_data\" not in str(p)\n",
+        "    and \"artifacts\" not in str(p)\n",
+        "    and \"outputs\" not in str(p)\n",
+        "    and \"figures\" not in str(p)\n",
+        "    and \"tables\" not in str(p)\n",
+        "]\n",
+        "\n",
+        "print(\"CSV files found:\")\n",
+        "for p in csv_paths:\n",
+        "    print(\"-\", p)\n",
+        "\n",
+        "# Find reviews dataset\n",
+        "reviews_candidates = [\n",
+        "    BASE_PATH / \"data_processed\" / \"reviews_cleaned.csv\",\n",
+        "    BASE_PATH / \"Womens Clothing E-Commerce Reviews.csv\",\n",
+        "]\n",
+        "\n",
+        "reviews_path = next((p for p in reviews_candidates if p.exists()), None)\n",
+        "\n",
+        "if reviews_path is None:\n",
+        "    matches = [\n",
+        "        p for p in csv_paths\n",
+        "        if \"clothing\" in p.name.lower() or \"review\" in p.name.lower()\n",
+        "    ]\n",
+        "    reviews_path = matches[0] if matches else None\n",
+        "\n",
+        "# Find returns dataset\n",
+        "returns_candidates = [\n",
+        "    BASE_PATH / \"data_processed\" / \"returns_input.csv\",\n",
+        "    BASE_PATH / \"data_processed\" / \"returns_cleaned.csv\",\n",
+        "    BASE_PATH / \"ecommerce_returns_cleaned.csv\",\n",
+        "    BASE_PATH / \"data_processed\" / \"synthetic_return_risk.csv\",\n",
+        "]\n",
+        "\n",
+        "returns_path = next((p for p in returns_candidates if p.exists()), None)\n",
+        "\n",
+        "if returns_path is None:\n",
+        "    matches = [\n",
+        "        p for p in csv_paths\n",
+        "        if \"return\" in p.name.lower()\n",
+        "    ]\n",
+        "    returns_path = matches[0] if matches else None\n",
+        "\n",
+        "if reviews_path is None:\n",
+        "    raise FileNotFoundError(\"Could not find reviews CSV.\")\n",
+        "\n",
+        "if returns_path is None:\n",
+        "    raise FileNotFoundError(\"Could not find returns CSV.\")\n",
+        "\n",
+        "print(\"Using reviews:\", reviews_path)\n",
+        "print(\"Using returns:\", returns_path)\n",
+        "\n",
+        "reviews_df = pd.read_csv(reviews_path).drop(columns=[\"Unnamed: 0\"], errors=\"ignore\")\n",
+        "returns_df = pd.read_csv(returns_path).drop(columns=[\"Unnamed: 0\"], errors=\"ignore\")\n",
+        "\n",
+        "print(\"Reviews shape:\", reviews_df.shape)\n",
+        "print(\"Returns shape:\", returns_df.shape)\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# 1. Rating distribution\n",
+        "# --------------------------------------------------\n",
+        "if \"Rating\" in reviews_df.columns:\n",
+        "    rating_distribution = (\n",
+        "        reviews_df[\"Rating\"]\n",
+        "        .dropna()\n",
+        "        .value_counts()\n",
+        "        .sort_index()\n",
+        "        .reset_index()\n",
+        "    )\n",
+        "    rating_distribution.columns = [\"rating\", \"count\"]\n",
+        "\n",
+        "    rating_distribution.to_csv(PY_TAB_DIR / \"rating_distribution.csv\", index=False)\n",
+        "\n",
+        "    plt.figure(figsize=(7, 4))\n",
+        "    plt.bar(rating_distribution[\"rating\"].astype(str), rating_distribution[\"count\"])\n",
+        "    plt.title(\"Distribution of Customer Ratings\")\n",
+        "    plt.xlabel(\"Rating\")\n",
+        "    plt.ylabel(\"Number of Reviews\")\n",
+        "    plt.tight_layout()\n",
+        "    plt.savefig(PY_FIG_DIR / \"rating_distribution.png\", dpi=150, bbox_inches=\"tight\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# 2. Sentiment counts for app's sentiment chart\n",
+        "# The app specifically looks for sentiment_counts_sampled.csv\n",
+        "# --------------------------------------------------\n",
+        "if \"Rating\" in reviews_df.columns:\n",
+        "    temp = reviews_df.copy()\n",
+        "\n",
+        "    def rating_to_sentiment(r):\n",
+        "        try:\n",
+        "            r = float(r)\n",
+        "            if r <= 2:\n",
+        "                return \"negative\"\n",
+        "            elif r == 3:\n",
+        "                return \"neutral\"\n",
+        "            else:\n",
+        "                return \"positive\"\n",
+        "        except:\n",
+        "            return \"neutral\"\n",
+        "\n",
+        "    temp[\"sentiment\"] = temp[\"Rating\"].apply(rating_to_sentiment)\n",
+        "\n",
+        "    group_col = \"Class Name\" if \"Class Name\" in temp.columns else None\n",
+        "\n",
+        "    if group_col:\n",
+        "        sentiment_counts = (\n",
+        "            temp.groupby([group_col, \"sentiment\"])\n",
+        "            .size()\n",
+        "            .unstack(fill_value=0)\n",
+        "            .reset_index()\n",
+        "            .head(15)\n",
+        "        )\n",
+        "        sentiment_counts = sentiment_counts.rename(columns={group_col: \"title\"})\n",
+        "    else:\n",
+        "        sentiment_counts = (\n",
+        "            temp[\"sentiment\"]\n",
+        "            .value_counts()\n",
+        "            .to_frame()\n",
+        "            .T\n",
+        "            .reset_index(drop=True)\n",
+        "        )\n",
+        "        sentiment_counts.insert(0, \"title\", \"All Reviews\")\n",
+        "\n",
+        "    for col in [\"negative\", \"neutral\", \"positive\"]:\n",
+        "        if col not in sentiment_counts.columns:\n",
+        "            sentiment_counts[col] = 0\n",
+        "\n",
+        "    sentiment_counts[[\"title\", \"negative\", \"neutral\", \"positive\"]].to_csv(\n",
+        "        PY_TAB_DIR / \"sentiment_counts_sampled.csv\",\n",
+        "        index=False\n",
+        "    )\n",
+        "\n",
+        "    # Also save a normal figure\n",
+        "    sentiment_total = temp[\"sentiment\"].value_counts().reindex(\n",
+        "        [\"negative\", \"neutral\", \"positive\"],\n",
+        "        fill_value=0\n",
+        "    )\n",
+        "\n",
+        "    plt.figure(figsize=(7, 4))\n",
+        "    plt.bar(sentiment_total.index, sentiment_total.values)\n",
+        "    plt.title(\"Review Sentiment Distribution\")\n",
+        "    plt.xlabel(\"Sentiment\")\n",
+        "    plt.ylabel(\"Number of Reviews\")\n",
+        "    plt.tight_layout()\n",
+        "    plt.savefig(PY_FIG_DIR / \"sentiment_distribution.png\", dpi=150, bbox_inches=\"tight\")\n",
+        "    plt.close()\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# 3. Category return rate\n",
+        "# --------------------------------------------------\n",
+        "return_col = None\n",
+        "for candidate in [\"likely_return\", \"synthetic_return_risk\", \"returned\", \"return_flag\"]:\n",
+        "    if candidate in returns_df.columns:\n",
+        "        return_col = candidate\n",
+        "        break\n",
+        "\n",
+        "category_col = None\n",
+        "for candidate in [\"product_category_name\", \"category\", \"Class Name\", \"product_id\"]:\n",
+        "    if candidate in returns_df.columns:\n",
+        "        category_col = candidate\n",
+        "        break\n",
+        "\n",
+        "if return_col is not None:\n",
+        "    returns_df[return_col] = pd.to_numeric(returns_df[return_col], errors=\"coerce\")\n",
+        "\n",
+        "if return_col is not None and category_col is not None:\n",
+        "    category_return_rate = (\n",
+        "        returns_df.groupby(category_col)[return_col]\n",
+        "        .mean()\n",
+        "        .sort_values(ascending=False)\n",
+        "        .head(15)\n",
+        "        .reset_index()\n",
+        "    )\n",
+        "    category_return_rate.columns = [\"category\", \"return_rate\"]\n",
+        "\n",
+        "    category_return_rate.to_csv(PY_TAB_DIR / \"category_return_rate.csv\", index=False)\n",
+        "\n",
+        "    plt.figure(figsize=(11, 5))\n",
+        "    plt.bar(category_return_rate[\"category\"].astype(str), category_return_rate[\"return_rate\"])\n",
+        "    plt.title(\"Highest Return-Rate Categories\")\n",
+        "    plt.xlabel(\"Category\")\n",
+        "    plt.ylabel(\"Return Rate\")\n",
+        "    plt.xticks(rotation=75)\n",
+        "    plt.tight_layout()\n",
+        "    plt.savefig(PY_FIG_DIR / \"category_return_rate.png\", dpi=150, bbox_inches=\"tight\")\n",
+        "    plt.close()\n",
+        "\n",
+        "    # The template's AI fallback weirdly expects this filename for \"top\" questions.\n",
+        "    # We reuse it to show highest return-risk categories.\n",
+        "    top_titles_by_units_sold = category_return_rate.copy()\n",
+        "    top_titles_by_units_sold.columns = [\"title\", \"units_sold\"]\n",
+        "    top_titles_by_units_sold.to_csv(PY_TAB_DIR / \"top_titles_by_units_sold.csv\", index=False)\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# 4. Dashboard time-series file\n",
+        "# The app's dashboard chart specifically looks for df_dashboard.csv\n",
+        "# --------------------------------------------------\n",
+        "if \"order_purchase_timestamp\" in returns_df.columns and return_col is not None:\n",
+        "    ts = returns_df.copy()\n",
+        "    ts[\"order_purchase_timestamp\"] = pd.to_datetime(\n",
+        "        ts[\"order_purchase_timestamp\"],\n",
+        "        errors=\"coerce\"\n",
+        "    )\n",
+        "    ts = ts.dropna(subset=[\"order_purchase_timestamp\"])\n",
+        "\n",
+        "    if not ts.empty:\n",
+        "        dashboard_df = (\n",
+        "            ts.set_index(\"order_purchase_timestamp\")\n",
+        "            .resample(\"M\")\n",
+        "            .agg(\n",
+        "                return_rate=(return_col, \"mean\"),\n",
+        "                orders=(return_col, \"count\")\n",
+        "            )\n",
+        "            .reset_index()\n",
+        "        )\n",
+        "        dashboard_df = dashboard_df.rename(columns={\"order_purchase_timestamp\": \"month\"})\n",
+        "    else:\n",
+        "        dashboard_df = pd.DataFrame({\n",
+        "            \"month\": pd.date_range(\"2024-01-01\", periods=3, freq=\"M\"),\n",
+        "            \"return_rate\": [0, 0, 0],\n",
+        "            \"orders\": [0, 0, 0],\n",
+        "        })\n",
+        "else:\n",
+        "    dashboard_df = pd.DataFrame({\n",
+        "        \"month\": pd.date_range(\"2024-01-01\", periods=3, freq=\"M\"),\n",
+        "        \"return_rate\": [0, 0, 0],\n",
+        "        \"orders\": [0, 0, 0],\n",
+        "    })\n",
+        "\n",
+        "dashboard_df.to_csv(PY_TAB_DIR / \"df_dashboard.csv\", index=False)\n",
+        "\n",
+        "plt.figure(figsize=(9, 4))\n",
+        "plt.plot(pd.to_datetime(dashboard_df[\"month\"]), dashboard_df[\"return_rate\"], marker=\"o\")\n",
+        "plt.title(\"Monthly Estimated Return Rate\")\n",
+        "plt.xlabel(\"Month\")\n",
+        "plt.ylabel(\"Return Rate\")\n",
+        "plt.tight_layout()\n",
+        "plt.savefig(PY_FIG_DIR / \"monthly_return_rate.png\", dpi=150, bbox_inches=\"tight\")\n",
+        "plt.close()\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# 5. KPIs\n",
+        "# --------------------------------------------------\n",
+        "kpis = {\n",
+        "    \"reviews_rows\": int(len(reviews_df)),\n",
+        "    \"returns_rows\": int(len(returns_df)),\n",
+        "    \"n_titles\": int(reviews_df[\"Clothing ID\"].nunique()) if \"Clothing ID\" in reviews_df.columns else int(len(reviews_df)),\n",
+        "    \"n_months\": int(len(dashboard_df)),\n",
+        "    \"total_units_sold\": int(len(returns_df)),\n",
+        "    \"estimated_return_rate\": float(returns_df[return_col].mean()) if return_col is not None else None,\n",
+        "}\n",
+        "\n",
+        "with open(PY_TAB_DIR / \"kpis.json\", \"w\", encoding=\"utf-8\") as f:\n",
+        "    json.dump(kpis, f, indent=2)\n",
+        "\n",
+        "# --------------------------------------------------\n",
+        "# Final verification\n",
+        "# --------------------------------------------------\n",
+        "print(\"\\nFORCE ARTIFACT CELL RAN SUCCESSFULLY\")\n",
+        "print(\"Figures now in app-readable folder:\")\n",
+        "print(sorted([p.name for p in PY_FIG_DIR.glob(\"*\")]))\n",
+        "\n",
+        "print(\"Tables now in app-readable folder:\")\n",
+        "print(sorted([p.name for p in PY_TAB_DIR.glob(\"*\")]))"
+      ],
+      "metadata": {
+        "id": "G-jXRriWP1TW",
+        "outputId": "23349a23-0bdc-476f-fb72-8e388be9630c",
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        }
+      },
+      "id": "G-jXRriWP1TW",
+      "execution_count": 10,
+      "outputs": [
+        {
+          "output_type": "stream",
+          "name": "stdout",
+          "text": [
+            "Saving dashboard artifacts to:\n",
+            "Figures: /content/artifacts/py/figures\n",
+            "Tables: /content/artifacts/py/tables\n",
+            "CSV files found:\n",
+            "- /content/Womens Clothing E-Commerce Reviews.csv\n",
+            "- /content/ecommerce_returns_cleaned.csv\n",
+            "Using reviews: /content/Womens Clothing E-Commerce Reviews.csv\n",
+            "Using returns: /content/ecommerce_returns_cleaned.csv\n",
+            "Reviews shape: (23486, 10)\n",
+            "Returns shape: (113314, 29)\n",
+            "\n",
+            "FORCE ARTIFACT CELL RAN SUCCESSFULLY\n",
+            "Figures now in app-readable folder:\n",
+            "['category_return_rate.png', 'monthly_return_rate.png', 'rating_distribution.png', 'sentiment_distribution.png']\n",
+            "Tables now in app-readable folder:\n",
+            "['category_return_rate.csv', 'df_dashboard.csv', 'kpis.json', 'rating_distribution.csv', 'sentiment_counts_sampled.csv', 'top_titles_by_units_sold.csv']\n"
+          ]
+        }
+      ]
+    }
+  ],
+  "metadata": {
+    "kernelspec": {
+      "display_name": "Python 3",
+      "language": "python",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python",
+      "version": "3.10"
+    },
+    "colab": {
+      "provenance": []
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}

requirements.txt

@@ -0,0 +1,17 @@
+gradio==6.0.0
+pandas>=2.0.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+seaborn>=0.13.0
+statsmodels>=0.14.0
+scikit-learn>=1.3.0
+papermill>=2.5.0
+nbformat>=5.9.0
+pillow>=10.0.0
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+vaderSentiment>=3.3.2
+huggingface_hub>=0.20.0
+textblob>=0.18.0
+faker>=20.0.0
+plotly>=5.18.0

style.css

@@ -0,0 +1,326 @@
+/* --- Target the Gradio app wrapper for backgrounds --- */
+gradio-app,
+.gradio-app,
+.main,
+#app,
+[data-testid="app"] {
+  background-color: rgb(40,9,109) !important;
+  background-image:
+    url('https://huggingface.co/spaces/atascioglu/SE21AppTemplate/resolve/main/background_top.png'),
+    url('https://huggingface.co/spaces/atascioglu/SE21AppTemplate/resolve/main/background_mid.png'),
+    url('https://huggingface.co/spaces/atascioglu/SE21AppTemplate/resolve/main/background_bottom.png') !important;
+  background-position:
+    top center,
+    0 913px,
+    bottom center !important;
+  background-repeat:
+    no-repeat,
+    repeat-y,
+    no-repeat !important;
+  background-size:
+    100% auto,
+    100% auto,
+    100% auto !important;
+  min-height: 100vh !important;
+}
+
+/* --- Fallback on html/body --- */
+html, body {
+  background-color: rgb(40,9,109) !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  min-height: 100vh !important;
+}
+
+/* Bottom image is now part of the main background layers (positioned at bottom center) */
+
+/* --- Main container --- */
+.gradio-container {
+  max-width: 1400px !important;
+  width: 94vw !important;
+  margin: 0 auto !important;
+  padding-top: 220px !important;
+  padding-bottom: 150px !important;
+  background: transparent !important;
+}
+
+/* --- Title in ESCP gold --- */
+#escp_title h1 {
+  color: rgb(242,198,55) !important;
+  font-size: 3rem !important;
+  font-weight: 800 !important;
+  text-align: center !important;
+  margin: 0 0 12px 0 !important;
+}
+
+/* --- Subtitle --- */
+#escp_title p, #escp_title em {
+  color: rgba(255,255,255,0.85) !important;
+  text-align: center !important;
+}
+
+/* --- Tab bar background --- */
+.tabs > .tab-nav,
+.tab-nav,
+div[role="tablist"],
+.svelte-tabs > .tab-nav {
+  background: rgba(40,9,109,0.6) !important;
+  border-radius: 10px 10px 0 0 !important;
+  padding: 4px !important;
+}
+
+/* --- ALL tab buttons: force white text --- */
+.tabs > .tab-nav button,
+.tab-nav button,
+div[role="tablist"] button,
+button[role="tab"],
+.svelte-tabs button,
+.tab-nav > button,
+.tabs button {
+  color: #ffffff !important;
+  font-weight: 600 !important;
+  border: none !important;
+  background: transparent !important;
+  padding: 10px 20px !important;
+  border-radius: 8px 8px 0 0 !important;
+  opacity: 1 !important;
+}
+
+/* --- Selected tab: ESCP gold --- */
+.tabs > .tab-nav button.selected,
+.tab-nav button.selected,
+button[role="tab"][aria-selected="true"],
+button[role="tab"].selected,
+div[role="tablist"] button[aria-selected="true"],
+.svelte-tabs button.selected {
+  color: rgb(242,198,55) !important;
+  background: rgba(255,255,255,0.12) !important;
+}
+
+/* --- Unselected tabs: ensure visibility --- */
+.tabs > .tab-nav button:not(.selected),
+.tab-nav button:not(.selected),
+button[role="tab"][aria-selected="false"],
+button[role="tab"]:not(.selected),
+div[role="tablist"] button:not([aria-selected="true"]) {
+  color: #ffffff !important;
+  opacity: 1 !important;
+}
+
+/* --- White card panels --- */
+.gradio-container .gr-block,
+.gradio-container .gr-box,
+.gradio-container .gr-panel,
+.gradio-container .gr-group {
+  background: #ffffff !important;
+  border-radius: 10px !important;
+}
+
+/* --- Tab content area --- */
+.tabitem {
+  background: rgba(255,255,255,0.95) !important;
+  border-radius: 0 0 10px 10px !important;
+  padding: 16px !important;
+}
+
+/* --- Inputs --- */
+.gradio-container input,
+.gradio-container textarea,
+.gradio-container select {
+  background: #ffffff !important;
+  border: 1px solid #d1d5db !important;
+  border-radius: 8px !important;
+}
+
+/* --- Buttons: ESCP purple primary --- */
+.gradio-container button:not([role="tab"]) {
+  font-weight: 600 !important;
+  padding: 10px 16px !important;
+  border-radius: 10px !important;
+}
+
+button.primary {
+  background-color: rgb(40,9,109) !important;
+  color: #ffffff !important;
+  border: none !important;
+}
+
+button.primary:hover {
+  background-color: rgb(60,20,140) !important;
+}
+
+button.secondary {
+  background-color: #ffffff !important;
+  color: rgb(40,9,109) !important;
+  border: 2px solid rgb(40,9,109) !important;
+}
+
+button.secondary:hover {
+  background-color: rgb(240,238,250) !important;
+}
+
+/* --- Dataframes --- */
+[data-testid="dataframe"] {
+  background-color: #ffffff !important;
+  border-radius: 10px !important;
+}
+
+table {
+  font-size: 0.85rem !important;
+}
+
+/* --- Chatbot (AI Dashboard tab) --- */
+.gr-chatbot {
+  min-height: 380px !important;
+  background-color: #ffffff !important;
+  border-radius: 12px !important;
+}
+
+.gr-chatbot .message.user {
+  background-color: rgb(232,225,250) !important;
+  border-radius: 12px !important;
+}
+
+.gr-chatbot .message.bot {
+  background-color: #f3f4f6 !important;
+  border-radius: 12px !important;
+}
+
+/* --- Gallery --- */
+.gallery {
+  background: #ffffff !important;
+  border-radius: 10px !important;
+}
+
+/* --- Log textbox --- */
+textarea {
+  font-family: monospace !important;
+  font-size: 0.8rem !important;
+}
+
+/* --- Markdown headings inside tabs --- */
+.tabitem h3 {
+  color: rgb(40,9,109) !important;
+  font-weight: 700 !important;
+}
+
+.tabitem h4 {
+  color: #374151 !important;
+}
+
+/* --- Examples row (AI Dashboard) --- */
+.examples-row button {
+  background: rgb(240,238,250) !important;
+  color: rgb(40,9,109) !important;
+  border: 1px solid rgb(40,9,109) !important;
+  border-radius: 8px !important;
+  font-size: 0.85rem !important;
+}
+
+.examples-row button:hover {
+  background: rgb(232,225,250) !important;
+}
+
+/* --- Header / footer: transparent over banner --- */
+header, header *,
+footer, footer * {
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+footer a, footer button,
+header a, header button {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+
+#footer, #footer *,
+[class*="footer"], [class*="footer"] *,
+[class*="chip"], [class*="pill"], [class*="chip"] *, [class*="pill"] * {
+  background: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+}
+
+[data-testid*="api"], [data-testid*="settings"],
+[id*="api"], [id*="settings"],
+[class*="api"], [class*="settings"],
+[class*="bottom"], [class*="toolbar"], [class*="controls"] {
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+[data-testid*="api"] *, [data-testid*="settings"] *,
+[id*="api"] *, [id*="settings"] *,
+[class*="api"] *, [class*="settings"] * {
+  background: transparent !important;
+  box-shadow: none !important;
+}
+
+section footer {
+  background: transparent !important;
+}
+
+section footer button,
+section footer a {
+  background: transparent !important;
+  background-color: transparent !important;
+  border: none !important;
+  box-shadow: none !important;
+  color: white !important;
+}
+
+section footer button:hover,
+section footer button:focus,
+section footer a:hover,
+section footer a:focus {
+  background: transparent !important;
+  background-color: transparent !important;
+  box-shadow: none !important;
+}
+
+section footer button,
+section footer button * {
+  background: transparent !important;
+  background-color: transparent !important;
+  background-image: none !important;
+  box-shadow: none !important;
+  filter: none !important;
+}
+
+section footer button::before,
+section footer button::after {
+  background: transparent !important;
+  background-color: transparent !important;
+  background-image: none !important;
+  box-shadow: none !important;
+  filter: none !important;
+}
+
+section footer a,
+section footer a * {
+  background: transparent !important;
+  background-color: transparent !important;
+  box-shadow: none !important;
+}
+
+.gradio-container footer button,
+.gradio-container footer button *,
+.gradio-container .footer button,
+.gradio-container .footer button * {
+  background: transparent !important;
+  background-color: transparent !important;
+  background-image: none !important;
+  box-shadow: none !important;
+}
+
+.gradio-container footer button::before,
+.gradio-container footer button::after,
+.gradio-container .footer button::before,
+.gradio-container .footer button::after {
+  background: transparent !important;
+  background-color: transparent !important;
+  background-image: none !important;
+  box-shadow: none !important;
+}