Update app.py

app.py

@@ -6,19 +6,23 @@ Pipeline
     1. load + normalize        deterministic
     2. context card            deterministic
     3. code generation         LLM
-    4. sandboxed execution     deterministic
+    4. sandboxed execution     deterministic  (+ plot-quality guards)
     5. one repair pass         LLM, given a cleaned traceback
-    6. facts + tables          deterministic  (argmax, describe, corr)
+    6. facts + tables          deterministic  (idxmax, describe, corr)
     7. narrative               LLM, one sentence per pre-computed fact
 
 Design principle: the model does the two things it is good at — writing analysis
 code and repairing it. Every lookup, table and superlative is computed in Python.
+
+The three Quick Starters are served from a pre-generated cache in quickstarts/
+and never touch the model, so the common path is instant and costs no GPU quota.
 """
 
 import base64
 import contextlib
 import glob
 import io
+import json
 import os
 import re
 import shutil
@@ -34,6 +38,8 @@ import torch
 matplotlib.use("Agg")
 import matplotlib.pyplot as plt  # noqa: E402
 import seaborn as sns  # noqa: E402
+from matplotlib.ticker import (FuncFormatter, LogLocator,  # noqa: E402
+                               NullFormatter, ScalarFormatter)
 from huggingface_hub import HfApi, hf_hub_download  # noqa: E402
 from transformers import AutoModelForCausalLM, AutoTokenizer  # noqa: E402
 
@@ -42,11 +48,18 @@ from transformers import AutoModelForCausalLM, AutoTokenizer  # noqa: E402
 # --------------------------------------------------------------------------- #
 MODEL_ID = "Qwen/Qwen2.5-Coder-1.5B-Instruct"
 
+# On ZeroGPU, `spaces` enables CUDA emulation at import, so placing the model on
+# "cuda" at module level is required. On CPU Spaces (or locally) there is no CUDA,
+# so fall back to float32 on CPU — the app boots, but generation is far slower.
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+DTYPE = torch.bfloat16 if DEVICE == "cuda" else torch.float32
+
 tok = AutoTokenizer.from_pretrained(MODEL_ID)
-model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=torch.bfloat16).to("cuda")
+model = AutoModelForCausalLM.from_pretrained(MODEL_ID, dtype=DTYPE).to(DEVICE)
 model.eval()
 if tok.pad_token_id is None:
     tok.pad_token = tok.eos_token
+print(f"[startup] device={DEVICE} dtype={DTYPE}")
 
 PLOTS_DIR = "plots"
 
@@ -121,6 +134,15 @@ def normalize(df: pd.DataFrame) -> pd.DataFrame:
     return df
 
 
+def drop_index_cols(df: pd.DataFrame):
+    """Remove monotonic unique integer columns — row ids, not variables."""
+    drop = [c for c in df.columns
+            if pd.api.types.is_integer_dtype(df[c])
+            and df[c].is_monotonic_increasing
+            and df[c].nunique() == len(df)]
+    return df.drop(columns=drop), drop
+
+
 # --------------------------------------------------------------------------- #
 # 2. Context card
 # --------------------------------------------------------------------------- #
@@ -173,7 +195,7 @@ def extract_code(text: str) -> str:
 
 
 # --------------------------------------------------------------------------- #
-# 4. Execution sandbox
+# 4. Execution sandbox (+ plot-quality guards)
 # --------------------------------------------------------------------------- #
 BANNED = re.compile(r"\b(pd\.read_\w+|load_dataset|sns\.load_dataset)\s*\(")
 CORR_FIX = re.compile(r"\.corr\(\s*\)")          # bare df.corr() -> numeric_only
@@ -185,6 +207,9 @@ UNSAFE = re.compile(
     r"\bimport\s+(os|sys)\b|\bopen\s*\(|\beval\s*\(|\bexec\s*\(|\bgetattr\s*\()"
 )
 
+MAX_ANNOT_COLS = 12          # above this, heatmap cell numbers are unreadable
+MAX_TICKS = 20               # above this, thin the tick labels
+
 
 def sanitize(code: str) -> str:
     """Neutralize data reloads; patch the one error the model cannot reliably fix.
@@ -202,13 +227,89 @@ def sanitize(code: str) -> str:
     return "\n".join(out)
 
 
-def drop_index_cols(df: pd.DataFrame):
-    """Remove monotonic unique integer columns — row ids, not variables."""
-    drop = [c for c in df.columns
-            if pd.api.types.is_integer_dtype(df[c])
-            and df[c].is_monotonic_increasing
-            and df[c].nunique() == len(df)]
-    return df.drop(columns=drop), drop
+def _short(s, n=18):
+    s = str(s)
+    return s if len(s) <= n else f"{s[:n//2 - 1]}…{s[-(n//2 - 1):]}"
+
+
+def _tick(v, _=None):
+    """Plain numbers with thousands separators — never 1e7."""
+    return f"{v:,.0f}" if abs(v) >= 1000 else f"{v:g}"
+
+
+def _tidy(fig):
+    """Make any figure legible: thin dense ticks, rotate, kill scientific notation."""
+    for ax in fig.get_axes():
+        if len(ax.get_xticklabels()) > MAX_TICKS:
+            step = max(1, len(ax.get_xticks()) // MAX_TICKS)
+            ax.set_xticks(ax.get_xticks()[::step])
+        for axis, scale in ((ax.xaxis, ax.get_xscale()), (ax.yaxis, ax.get_yscale())):
+            # only touch numeric axes: a heatmap's labels use a FixedFormatter
+            if scale == "linear" and isinstance(axis.get_major_formatter(), ScalarFormatter):
+                axis.set_major_formatter(FuncFormatter(_tick))
+        plt.setp(ax.get_xticklabels(), rotation=45, ha="right", fontsize=8)
+        plt.setp(ax.get_yticklabels(), fontsize=8)
+
+
+def _install_plot_guards():
+    """Patch the real modules, so `import matplotlib.pyplot as plt` cannot bypass us."""
+    real = {"savefig": plt.savefig, "heatmap": sns.heatmap, "histplot": sns.histplot}
+
+    def savefig(fname, *a, **kw):
+        fig = plt.gcf()
+        w, h = fig.get_size_inches()
+        fig.set_size_inches(max(w, 8), max(h, 5))
+        _tidy(fig)
+        kw.setdefault("bbox_inches", "tight")
+        kw.setdefault("dpi", 110)
+        return real["savefig"](fname, *a, **kw)
+
+    def heatmap(data, *a, **kw):
+        n = getattr(data, "shape", (0, 0))[1]
+        if n > MAX_ANNOT_COLS:
+            kw["annot"] = False
+        kw.setdefault("cmap", "coolwarm")
+        side = min(max(7, 0.5 * n + 4), 20)
+        plt.gcf().set_size_inches(side, side * 0.85)
+        ax = real["heatmap"](data, *a, **kw)
+        if hasattr(data, "columns"):
+            fs = 8 if n <= 15 else 6
+            ax.set_xticklabels([_short(c, 24) for c in data.columns],
+                               rotation=45, ha="right", fontsize=fs)
+            ax.set_yticklabels([_short(c, 24) for c in data.index],
+                               rotation=0, fontsize=fs)
+        return ax
+
+    def _series(a, kw):
+        d, x = kw.get("data", a[0] if a else None), kw.get("x")
+        try:
+            if isinstance(x, str) and hasattr(d, "columns"):
+                return pd.to_numeric(d[x], errors="coerce").dropna()
+            if isinstance(d, pd.Series):
+                return pd.to_numeric(d, errors="coerce").dropna()
+        except Exception:
+            pass
+        return None
+
+    def histplot(*a, **kw):
+        s = _series(a, kw)
+        logged = False
+        # heavy right skew (prices, fares, incomes) -> log x, else one tall bar
+        if (s is not None and len(s) > 20 and s.min() > 0
+                and s.max() / max(s.median(), 1e-9) > 50 and "log_scale" not in kw):
+            kw["log_scale"] = (True, False)
+            logged = True
+        ax = real["histplot"](*a, **kw)
+        if logged:
+            ax.xaxis.set_major_locator(LogLocator(base=10, subs=(1.0, 2.0, 5.0),
+                                                  numticks=12))
+            ax.xaxis.set_major_formatter(FuncFormatter(_tick))
+            ax.xaxis.set_minor_formatter(NullFormatter())
+            ax.set_xlabel(f"{ax.get_xlabel()} (log scale)")
+        return ax
+
+    plt.savefig, sns.heatmap, sns.histplot = savefig, heatmap, histplot
+    return real
 
 
 def run_code(code: str, df: pd.DataFrame) -> dict:
@@ -218,20 +319,22 @@ def run_code(code: str, df: pd.DataFrame) -> dict:
 
     before = set(glob.glob(f"{PLOTS_DIR}/*.png"))
     ns = {"df": df.copy(), "pd": pd, "np": np, "plt": plt, "sns": sns}
+
+    real = _install_plot_guards()
     buf, err = io.StringIO(), None
     try:
         with contextlib.redirect_stdout(buf):
             exec(code, ns)                                  # noqa: S102
     except Exception:
         err = traceback.format_exc(limit=3)
-
-    # safety net: model called plt.show(), or crashed with a figure still open
-    for i, num in enumerate(plt.get_fignums(), start=1):
-        fig = plt.figure(num)
-        if not fig.get_axes():                 # skip blank figures
-            continue
-        fig.savefig(f"{PLOTS_DIR}/figure_{i}.png", bbox_inches="tight")
-    plt.close("all")
+    finally:
+        for i, num in enumerate(plt.get_fignums(), start=1):
+            fig = plt.figure(num)
+            if fig.get_axes():
+                fig.savefig(f"{PLOTS_DIR}/figure_{i}.png")
+        plt.close("all")
+        plt.savefig, sns.heatmap, sns.histplot = (
+            real["savefig"], real["heatmap"], real["histplot"])
 
     return {"ok": err is None, "stdout": buf.getvalue(), "error": err,
             "plots": sorted(set(glob.glob(f"{PLOTS_DIR}/*.png")) - before)}
@@ -254,6 +357,18 @@ def format_error(err: str, code: str) -> str:
 REDUNDANT_R = 0.99      # |r| at or above this is a duplicate encoding, not a finding
 
 
+def fmt_num(v):
+    """Plain, comma-separated numbers. Never 1.02011e+06."""
+    if pd.isna(v):
+        return ""
+    v = float(v)
+    if v.is_integer():
+        return f"{int(v):,}"
+    if abs(v) >= 1000:
+        return f"{v:,.0f}"
+    return f"{v:,.2f}"
+
+
 def corr_pairs(df: pd.DataFrame):
     """Split correlations into real findings and near-duplicate columns."""
     num = df.select_dtypes(include="number")
@@ -273,13 +388,20 @@ def corr_pairs(df: pd.DataFrame):
 
 
 def make_tables(df: pd.DataFrame, max_card: int = 6) -> dict:
+    """Every table rendered by pandas. The model never transcribes one.
+
+    disable_numparse stops tabulate re-parsing our formatted strings and
+    re-rendering large values in scientific notation.
+    """
     t = {}
+
     n = df.isna().sum()
     n = n[n > 0].sort_values(ascending=False)
     if len(n):
         head = n.head(15)
-        tbl = pd.DataFrame({"missing": head,
-                            "pct": (100 * head / len(df)).round(1)}).to_markdown()
+        tbl = pd.DataFrame({"missing": head.map(fmt_num),
+                            "pct": (100 * head / len(df)).round(1)}
+                           ).to_markdown(disable_numparse=True)
         if len(n) > 15:
             tbl += f"\n\n_+{len(n) - 15} more columns with missing values._"
         t["missing"] = tbl
@@ -305,8 +427,12 @@ def make_tables(df: pd.DataFrame, max_card: int = 6) -> dict:
             + pd.DataFrame(dup[:8]).to_markdown(index=False))
 
     num = df.select_dtypes(include="number")
-    t["describe"] = (num.describe().T.round(2).to_markdown()      # transposed
-                     if len(num.columns) else "_None._")
+    if len(num.columns):
+        desc = num.describe().T
+        desc = desc.map(fmt_num) if hasattr(desc, "map") else desc.applymap(fmt_num)
+        t["describe"] = desc.to_markdown(disable_numparse=True)
+    else:
+        t["describe"] = "_No numeric columns._"
     return t
 
 
@@ -318,10 +444,10 @@ def key_facts(df: pd.DataFrame, max_card: int = 6) -> dict:
     if len(n):
         c = n.idxmax()
         f["missing"] = (f"{c} has the most missing values: "
-                        f"{n.max()} ({100 * n.max() / len(df):.1f}%)")
+                        f"{fmt_num(n.max())} ({100 * n.max() / len(df):.1f}%)")
 
-    bins, best = [c for c in df.select_dtypes(include="number")
-                  if df[c].nunique() == 2], None
+    bins = [c for c in df.select_dtypes(include="number") if df[c].nunique() == 2]
+    best = None
     for c in [c for c in df.columns if df[c].nunique(dropna=True) <= max_card]:
         for b in bins:
             if b == c:
@@ -358,11 +484,12 @@ def one_liner(fact: str) -> str:
 
 
 def audit_numbers(md: str, allowed_text: str) -> list:
-    """Flag numbers in the prose absent from the evidence. Detects fabrication,
+    """Flag numerals in the prose absent from the evidence. Detects fabrication,
     not misinterpretation — a flag list, not a verdict."""
-    allowed = set(re.findall(r"\d+\.?\d*", allowed_text))
+    allowed = set(re.findall(r"\d+\.?\d*", allowed_text.replace(",", "")))
     prose = "\n".join(l for l in md.splitlines() if not l.strip().startswith("|"))
-    return sorted({x for x in re.findall(r"\d+\.?\d*", prose) if x not in allowed})
+    return sorted({x for x in re.findall(r"\d+\.?\d*", prose.replace(",", ""))
+                   if x not in allowed})
 
 
 def embed_images(md: str) -> str:
@@ -376,46 +503,143 @@ def embed_images(md: str) -> str:
     return re.sub(r"\]\(([^)]+\.png)\)", repl, md)
 
 
+def report_to_pdf(report_md: str, plots: list, path: str = "eda_report.pdf") -> str:
+    """Render the markdown report plus every figure to a single PDF."""
+    from fpdf import FPDF
+    from fpdf.enums import XPos, YPos
+
+    def clean(s):
+        for a, b in [("—", "-"), ("…", "..."), ("≥", ">="), ("×", "x"),
+                     ("’", "'"), ("“", '"'), ("”", '"')]:
+            s = s.replace(a, b)
+        return s.encode("latin-1", "replace").decode("latin-1")
+
+    pdf = FPDF(format="A4")
+    pdf.set_auto_page_break(True, margin=15)
+    pdf.add_page()
+    usable = pdf.w - pdf.l_margin - pdf.r_margin
+    max_table_chars = int(usable / (6.5 * 0.6 * 0.3528))   # Courier 0.6 em, 1pt=0.3528mm
+
+    def write(text, style="", size=10, h=5):
+        """Always start at the left margin — otherwise multi_cell width goes to zero."""
+        pdf.set_font("Courier" if style == "mono" else "Helvetica",
+                     "B" if style == "B" else "", size)
+        pdf.set_x(pdf.l_margin)
+        pdf.multi_cell(0, h, text, new_x=XPos.LMARGIN, new_y=YPos.NEXT)
+
+    for raw in report_md.splitlines():
+        line = clean(raw.rstrip())
+        if line.startswith("!["):
+            continue
+        is_table = line.startswith("|")
+        if not is_table:
+            line = re.sub(r"[*_`]", "", line)
+            line = " ".join(w if len(w) <= 50 else
+                            " ".join(w[i:i + 50] for i in range(0, len(w), 50))
+                            for w in line.split())
+        elif len(line) > max_table_chars:
+            line = line[:max_table_chars - 3] + "..."
+
+        if line.startswith("# "):
+            write(line[2:], "B", 15, 8); pdf.ln(1)
+        elif line.startswith("## "):
+            pdf.ln(2); write(line[3:], "B", 12, 7)
+        elif is_table:
+            write(line, "mono", 6.5, 3.4)
+        elif line.strip():
+            write(line, "", 10, 5)
+        else:
+            pdf.ln(2)
+
+    for p in plots:
+        pdf.add_page()
+        write(clean(os.path.basename(p)[:-4].replace("_", " ")), "B", 11, 7)
+        pdf.image(p, w=usable)
+
+    pdf.output(path)
+    return path
+
+
+def build_report(df, res, name, instruction, dropped=None) -> tuple:
+    t, kf = make_tables(df), key_facts(df)
+
+    P = [f"# EDA Report — {name}", "", f"*{instruction}*", "",
+         "## Overview", one_liner(schema_only(df, name)), ""]
+    if dropped:
+        P += [f"_Index-like columns excluded from analysis: {', '.join(dropped)}._", ""]
+
+    P += ["## Missing Values", t["missing"], ""]
+    if "missing" in kf:
+        P += [one_liner(kf["missing"]), ""]
+
+    P += ["## Group Differences", t["groups"], ""]
+    if "group" in kf:
+        P += [one_liner(kf["group"]), ""]
+
+    P += ["## Correlations", t["corr"], ""]
+    if "corr" in kf:
+        P += [one_liner(kf["corr"]), ""]
+
+    if "redundant" in t:
+        P += ["## Redundant Columns", t["redundant"], ""]
+
+    P += ["## Numeric Summary", t["describe"], ""]
+
+    take = generate("Rewrite each fact as one markdown bullet. Add nothing.",
+                    "\n".join(f"- {v}" for v in kf.values()), max_new_tokens=200)
+    P += ["## Takeaways",
+          *[l.strip() for l in take.splitlines() if l.strip().startswith(("-", "*"))][:3],
+          ""]
+
+    P += ["## Figures", ""]
+    for p in res["plots"]:
+        P += [f"**{os.path.basename(p)[:-4].replace('_', ' ')}**", "", f"![]({p})", ""]
+
+    report = "\n".join(P)
+    allowed = "\n".join([*t.values(), *kf.values(), schema_only(df, name)])
+    return report, audit_numbers(report, allowed)
+
+
 # --------------------------------------------------------------------------- #
-# 7. Gradio handler
+# 7. Pipeline + Gradio plumbing
 # --------------------------------------------------------------------------- #
 DATASET_RE = re.compile(r"^[\w.-]+(/[\w.-]+)?$")
-BLANK = ("", "", "", [], "", "")
+BLANK = (None, "", "", [], "", "")
 
 
-@spaces.GPU(duration=150)
-def run_agent(instruction: str, dataset: str):
-    """Streams: status, code, stdout, gallery, report, flags."""
+def _pipeline(instruction: str, dataset: str):
+    """Streams: status, pdf, code, stdout, gallery, report, flags."""
     instruction = (instruction or "").strip()
     dataset = (dataset or "").strip()
     if not DATASET_RE.match(dataset):
-        yield ("**Invalid dataset id.** Use the form `owner/name`.", *BLANK[1:])
+        yield ("**Invalid dataset id.** Use the form `owner/name`.", *BLANK)
         return
 
     shutil.rmtree(PLOTS_DIR, ignore_errors=True)
     os.makedirs(PLOTS_DIR, exist_ok=True)
 
-    yield (f"Loading `{dataset}` …", "", "", [], "", "")
+    yield (f"Loading `{dataset}` …", *BLANK)
     try:
         df = normalize(load_hf_dataframe(dataset))
     except Exception as e:
-        yield (f"**Could not load `{dataset}`.** {type(e).__name__}: {e}", *BLANK[1:])
+        yield (f"**Could not load `{dataset}`.** {type(e).__name__}: {e}", *BLANK)
         return
 
     df, dropped = drop_index_cols(df)
     context = build_context(df, dataset)
-    yield (f"Loaded **{df.shape[0]} x {df.shape[1]}**. Generating analysis code …",
-           "", "", [], "", "")
+    note = f" Dropped index-like columns: {', '.join(dropped)}." if dropped else ""
+    yield (f"Loaded **{df.shape[0]} x {df.shape[1]}**.{note} Generating analysis code …",
+           *BLANK)
 
     code = sanitize(extract_code(
         generate(CODE_SYSTEM, f"{context}\n\nTask: {instruction}", max_new_tokens=1200)))
     res = run_code(code, df)
     yield (f"Attempt 1: {'ok' if res['ok'] else 'failed'}. Executing …",
-           code, res["stdout"], res["plots"], "", "")
+           None, code, res["stdout"], res["plots"], "", "")
 
     if not res["ok"]:
         yield ("Attempt 1 failed — repairing from the traceback …",
-               code, res["stdout"] + "\n" + format_error(res["error"], code),
+               None, code, res["stdout"] + "\n" + format_error(res["error"], code),
                res["plots"], "", "")
         fix = (f"{context}\n\nThis code failed:\n```python\n{code}\n```\n\n"
                f"Error:\n{format_error(res['error'], code)}\n\nReturn the corrected script.")
@@ -423,99 +647,191 @@ def run_agent(instruction: str, dataset: str):
         res = run_code(code, df)
 
     plots = sorted(glob.glob(f"{PLOTS_DIR}/*.png"))
+    res["plots"] = plots
     status = ("Code ran successfully" if res["ok"]
               else "Code still failing after one repair — report built from data only")
-    yield (f"{status}. Writing report …", code, res["stdout"], plots, "", "")
+    yield (f"{status}. Writing report …", None, code, res["stdout"], plots, "", "")
 
-    t, kf = make_tables(df), key_facts(df)
-    P = [f"# EDA Report — {dataset}", "", f"*{instruction}*", "",
-         "## Overview", one_liner(schema_only(df, dataset)), ""]
-    if dropped:
-        P += [f"_Index-like columns excluded from analysis: {', '.join(dropped)}._", ""]
-    P += ["## Missing Values", t["missing"], ""]
-    if "missing" in kf:
-        P += [one_liner(kf["missing"]), ""]
-    P += ["## Group Differences", t["groups"], ""]
-    if "group" in kf:
-        P += [one_liner(kf["group"]), ""]
-    P += ["## Correlations", t["corr"], ""]
-    if "corr" in kf:
-        P += [one_liner(kf["corr"]), ""]
-    if "redundant" in t:
-        P += ["## Redundant Columns", t["redundant"], ""]
-    P += ["## Numeric Summary", t["describe"], ""]
+    report, flags = build_report(df, res, dataset, instruction, dropped)
+    safe = re.sub(r"[^\w.-]", "_", dataset)
+    try:
+        pdf = report_to_pdf(report, plots, path=f"eda_report_{safe}.pdf")
+        pdf_note = ""
+    except Exception as e:
+        pdf, pdf_note = None, f" (PDF unavailable: {type(e).__name__})"
 
-    take = generate("Rewrite each fact as one markdown bullet. Add nothing.",
-                    "\n".join(f"- {v}" for v in kf.values()), max_new_tokens=200)
-    P += ["## Takeaways",
-          *[l.strip() for l in take.splitlines() if l.strip().startswith(("-", "*"))][:3],
-          ""]
+    yield (f"Done — {status.lower()}, {len(plots)} figures.{pdf_note}",
+           pdf, code, res["stdout"], plots,
+           embed_images(report), ", ".join(flags) if flags else "none")
 
-    P += ["## Figures", ""]
-    for p in plots:
-        P += [f"**{os.path.basename(p)[:-4].replace('_', ' ')}**", "", f"![]({p})", ""]
 
-    report = "\n".join(P)
-    flags = audit_numbers(report, "\n".join(t.values()) + "\n".join(kf.values())
-                          + schema_only(df, dataset))
+@spaces.GPU(duration=120)
+def _run_gpu(instruction: str, dataset: str):
+    yield from _pipeline(instruction, dataset)
+
+
+_CACHE: dict = {}
+
 
-    with open("eda_report.md", "w") as fh:
-        fh.write(report)
+def run_agent(instruction: str, dataset: str):
+    """Cache check happens outside @spaces.GPU, so a repeat run costs no quota.
+
+    Free ZeroGPU is 5 min/day and the requested duration is checked upfront,
+    so re-demoing the same dataset would otherwise exhaust the allowance.
+    """
+    key = ((instruction or "").strip(), (dataset or "").strip())
+    if key in _CACHE:
+        status, *rest = _CACHE[key]
+        yield (status + "  _(cached — no GPU used)_", *rest)
+        return
 
-    yield (f"Done — {status.lower()}, {len(plots)} figures.",
-           code, res["stdout"], plots, embed_images(report),
-           ", ".join(flags) if flags else "none")
+    last = None
+    for out in _run_gpu(*key):
+        last = out
+        yield out
+    if last and last[5]:                 # only cache runs that produced a report
+        _CACHE[key] = last
 
 
+# --------------------------------------------------------------------------- #
+# 8. Quick Starters — pre-generated, instant, no model call
+# --------------------------------------------------------------------------- #
 DEFAULT_INSTRUCTION = ("Run a comprehensive exploratory data analysis, highlighting "
                        "missing values, distributions, and key feature correlations.")
 
-with gr.Blocks(title="EDA Agent") as demo:
+QS_DIR = "quickstarts"
+QUICKSTARTS = [
+    {"slug": "titanic",
+     "label": "🚢 Titanic — hidden missing values",
+     "blurb": "77% of `cabin` is missing, but the raw file hides it as `''`.",
+     "dataset": "mstz/titanic",
+     "instruction": DEFAULT_INSTRUCTION},
+    {"slug": "iris",
+     "label": "🌸 Iris — a clean baseline",
+     "blurb": "No missing values, a row-id column the agent drops, tight correlations.",
+     "dataset": "scikit-learn/iris",
+     "instruction": "Explore this dataset: missing values, distributions, correlations."},
+    {"slug": "housing",
+     "label": "🏠 Canada housing — skewed prices",
+     "blurb": "35,768 listings with a long price tail the agent replots on a log axis.",
+     "dataset": "imanmalhi/canada_realestate_listings",
+     "instruction": DEFAULT_INSTRUCTION},
+]
+
+
+def load_quickstart(spec: dict):
+    """Read a pre-generated run from disk. Returns None if it was never built."""
+    d = os.path.join(QS_DIR, spec["slug"])
+    meta_path = os.path.join(d, "meta.json")
+    if not os.path.exists(meta_path):
+        return None
+    meta = json.load(open(meta_path))
+    report = open(os.path.join(d, "report.md")).read()
+    code = open(os.path.join(d, "code.py")).read()
+    stdout = open(os.path.join(d, "stdout.txt")).read()
+    plots = sorted(glob.glob(os.path.join(d, "plots", "*.png")))
+    pdf = os.path.join(d, "report.pdf")
+    return (
+        spec["instruction"], spec["dataset"],
+        f"**{spec['label']}** — pre-generated example, loaded instantly (no GPU used).",
+        pdf if os.path.exists(pdf) else None,
+        code, stdout, plots, embed_images(report),
+        ", ".join(meta.get("flags") or []) or "none",
+    )
+
+
+def quickstart_handler(spec: dict):
+    """Serve from cache; fall back to a live run if the cache was not uploaded."""
+    def handler():
+        cached = load_quickstart(spec)
+        if cached is not None:
+            return cached
+        last = None
+        for out in run_agent(spec["instruction"], spec["dataset"]):
+            last = out
+        status, pdf, code, stdout, plots, report, flags = last
+        return (spec["instruction"], spec["dataset"], status, pdf,
+                code, stdout, plots, report, flags)
+    return handler
+
+
+def reset_form():
+    return DEFAULT_INSTRUCTION, "mstz/titanic"
+
+
+# --------------------------------------------------------------------------- #
+# 9. UI
+# --------------------------------------------------------------------------- #
+CSS = """
+#hero {text-align:center; padding: 6px 0 2px 0;}
+.qs-card {border:1px solid var(--border-color-primary); border-radius:12px;
+          padding:10px 12px; height:100%;}
+footer {visibility:hidden}
+"""
+
+with gr.Blocks(title="EDA Agent", theme=gr.themes.Soft(), css=CSS) as demo:
+    gr.Markdown(
+        "<div id='hero'>\n\n"
+        "# 📊 EDA Agent\n"
+        "**Point it at any Hugging Face dataset. It writes its own analysis code, "
+        "runs it, fixes it when it crashes, and hands back a report.**\n\n"
+        "</div>",
+    )
     gr.Markdown(
-        "# EDA Agent\n"
-        "A **Qwen2.5-Coder-1.5B** agent that writes its own analysis code, executes it, "
-        "repairs it from the traceback if it crashes, and reports the results.\n\n"
-        "Tables, figures and every superlative are computed in Python — the model writes "
-        "code and prose only. Runs on ZeroGPU; a full report takes about a minute."
+        "Powered by `Qwen2.5-Coder-1.5B-Instruct`. The model writes **code and prose "
+        "only** — every table, figure and “which is highest” lookup is computed in "
+        "pandas, so the numbers in the report cannot be hallucinated. "
+        "A built-in check flags any figure in the text that is missing from the data."
     )
 
+    gr.Markdown("### ⚡ Quick Starters — one click, instant, no GPU used")
+    with gr.Row():
+        qs_buttons = []
+        for spec in QUICKSTARTS:
+            with gr.Column(elem_classes="qs-card"):
+                btn = gr.Button(spec["label"], variant="secondary", size="lg")
+                gr.Markdown(f"<small>{spec['blurb']}</small>")
+                qs_buttons.append((btn, spec))
+
+    gr.Markdown("### 🔎 Or run it on any dataset")
     with gr.Row():
         instruction = gr.Textbox(label="Prompt instruction", value=DEFAULT_INSTRUCTION,
                                  lines=3, scale=3)
-        dataset = gr.Textbox(label="Hugging Face dataset", value="mstz/titanic",
-                             lines=1, scale=1)
-    run_btn = gr.Button("Run EDA Agent", variant="primary")
+        dataset = gr.Textbox(label="Hugging Face dataset id", value="mstz/titanic",
+                             placeholder="owner/name", lines=1, scale=1)
+    with gr.Row():
+        run_btn = gr.Button("🚀 Run EDA Agent", variant="primary", size="lg", scale=4)
+        reset_btn = gr.Button("↺ Reset", variant="secondary", size="lg", scale=1)
+
+    gr.Markdown(
+        "<small>A fresh run takes about a minute on ZeroGPU. Free daily GPU quota is "
+        "shared per visitor — if you hit the limit, the Quick Starters above always "
+        "work.</small>"
+    )
+
     status = gr.Markdown()
+    pdf_file = gr.File(label="⬇️ Full report as PDF (text, tables and every figure)")
 
     with gr.Tabs():
-        with gr.Tab("Report"):
+        with gr.Tab("📄 Report"):
             report_md = gr.Markdown()
             flags_box = gr.Textbox(label="Unverified numbers (fabrication check)",
                                    interactive=False)
-        with gr.Tab("Generated code"):
+        with gr.Tab("🖼️ Figures"):
+            gallery = gr.Gallery(label="Figures", columns=2, height=560)
+        with gr.Tab("🐍 Generated code"):
             code_box = gr.Code(language="python", label="Model-written analysis code")
-        with gr.Tab("Execution output"):
+        with gr.Tab("🖥️ Execution output"):
             stdout_box = gr.Textbox(label="stdout / traceback", lines=18,
                                     interactive=False)
-        with gr.Tab("Plots"):
-            gallery = gr.Gallery(label="Figures", columns=2, height=520)
-
-    gr.Examples(
-        examples=[
-            [DEFAULT_INSTRUCTION, "mstz/titanic"],
-            ["Explore this dataset: missing values, distributions, correlations.",
-             "scikit-learn/iris"],
-            ["Summarise the distributions and flag any strongly correlated features.",
-             "scikit-learn/adult-census-income"],
-        ],
-        inputs=[instruction, dataset],
-    )
 
-    run_btn.click(
-        run_agent,
-        inputs=[instruction, dataset],
-        outputs=[status, code_box, stdout_box, gallery, report_md, flags_box],
-    )
+    live_outputs = [status, pdf_file, code_box, stdout_box, gallery, report_md, flags_box]
+    qs_outputs = [instruction, dataset] + live_outputs
+
+    run_btn.click(run_agent, [instruction, dataset], live_outputs)
+    reset_btn.click(reset_form, None, [instruction, dataset])
+    for btn, spec in qs_buttons:
+        btn.click(quickstart_handler(spec), None, qs_outputs)
 
 if __name__ == "__main__":
     demo.queue().launch()