MarginGraph / app.py
EquilStable's picture
Update app.py
1891570 verified
Raw History Blame Contribute Delete
20.1 kB
"""MarginGraph live demo (Gradio, CPU only, ~150 MB RAM).
Tab 1 Demo store: build a basket from 2,000 real Online Retail II products,
compare plain top-2 add-ons with MarginGraph's margin-safe pick.
Tab 2 Your store: upload your products (price, cost, stock) and optionally
your order history; get recommendations for one basket or a whole CSV.
Tab 3 Backtest: measured numbers on held-out Oct-Dec 2011 baskets.
"""
from __future__ import annotations
import json
import tempfile
from pathlib import Path
import core
import gradio as gr
try: # ZeroGPU Spaces refuse to start without one @spaces.GPU function; the app itself runs on CPU.
import spaces
@spaces.GPU
def _zerogpu_placeholder():
return None
except ImportError:
pass
import numpy as np
import pandas as pd
ART = Path(__file__).resolve().parent / "artifacts"
META = json.loads((ART / "meta.json").read_text())
_npz = np.load(ART / "ease.npz")
DEMO = core.Model(
items=[str(s) for s in _npz["items"]],
B=_npz["B"].astype(np.float32),
calib=META["calibration"],
catalog=pd.read_csv(ART / "catalog.csv", dtype={"item": str}),
)
del _npz
PRODUCT_COLS = ["item", "description", "price", "unit_cost", "stock", "overstock"]
ALIASES = {
"item": ["item", "stock_code", "stockcode", "sku", "product_id", "product", "code", "id"],
"description": ["description", "name", "title", "product_name"],
"price": ["price", "unit_price", "sell_price", "retail_price"],
"unit_cost": ["unit_cost", "cost", "cogs", "buy_price", "purchase_price"],
"stock": ["stock", "qty", "quantity", "on_hand", "inventory", "stock_level"],
"overstock": ["overstock", "overstocked", "clearance", "excess"],
"basket": ["basket", "basket_id", "order", "order_id", "invoice", "invoice_no", "transaction_id", "cart_id"],
}
SIM_NOTE = ("Demo store costs and stock are **simulated** (Online Retail II publishes prices but not costs "
"or inventory). Upload your own numbers in *Your store* to use real ones.")
# ---------------------------------------------------------------- helpers
def label(model: core.Model, code: str) -> str:
i = model.pos.get(code)
return f"{code} · {model.catalog['description'].iat[i]}" if i is not None else code
def choices(model: core.Model) -> list[str]:
return [label(model, c) for c in model.items if model.catalog["stock"].iat[model.pos[c]] >= 0]
def codes_from(sel) -> list[str]:
if isinstance(sel, str):
sel = [s for s in sel.replace("\n", ",").split(",")]
return [s.split("·")[0].strip().upper() for s in (sel or []) if s and s.strip()]
def policy(floor, overstock_w, lam, discounts, k) -> core.Policy:
return core.Policy(lam=float(lam), overstock_weight=float(overstock_w), floor=float(floor),
discounts=(0.0, 0.10, 0.20) if discounts else (0.0,), max_addons=int(k))
def money(x: float) -> str:
return f"£{x:,.2f}"
def card(title: str, cand: pd.DataFrame, chosen, pol: core.Policy, accent: str) -> str:
st = core.offer_stats(cand, chosen, pol)
rows = []
for j, d in chosen:
r = cand.loc[j]
price = r.price * (1 - d)
m = (price - r.unit_cost) / price if price else 0
tags = []
if r.overstock:
tags.append('<span class="mg-tag mg-over">overstock</span>')
if d:
tags.append(f'<span class="mg-tag">-{int(d*100)}%</span>')
if m < pol.floor:
tags.append('<span class="mg-tag mg-bad">below margin floor</span>')
rows.append(
f'<div class="mg-item"><div class="mg-name">{r.description.title()} '
f'<span class="mg-code">{r["item"]}</span> {"".join(tags)}</div>'
f'<div class="mg-meta">{money(price)} · margin {m:.0%} · p(buy) {min(1, r.p_accept*(1+pol.elasticity*d)):.1%}'
f' · stock {int(r.stock)}</div>'
f'<div class="mg-why">bought with: {str(r.because_of).title()}</div></div>')
body = "".join(rows) or '<div class="mg-meta">No add-on passes the rules for this basket.</div>'
return (f'<div class="mg-card" style="border-top:4px solid {accent}"><div class="mg-h">{title}</div>{body}'
f'<div class="mg-foot">Expected profit <b>{money(st["exp_profit"])}</b> · expected margin '
f'{st["exp_margin"]:.0%} · chance of at least one sale ≈ {min(1, st["hit_prob"]):.0%}</div></div>')
def run(model: core.Model, codes: list[str], pol: core.Policy):
res = model.recommend(codes, pol)
if not res["known"]:
msg = "Add at least one product the model knows."
if res["unknown"]:
msg += f" Unknown codes: {', '.join(res['unknown'][:10])}"
return f'<div class="mg-note">{msg}</div>', "", "", None
cand = res["candidates"]
a = core.offer_stats(cand, res["top"], pol)
b = core.offer_stats(cand, res["optimized"], pol)
dp = (b["exp_profit"] / a["exp_profit"] - 1) * 100 if a["exp_profit"] > 0 else 0.0
dh = (min(1, b["hit_prob"]) - min(1, a["hit_prob"])) * 100
summary = (f'<div class="mg-sum"><div><span class="mg-big">{dp:+.0f}%</span><br>expected profit vs plain top-{pol.max_addons}</div>'
f'<div><span class="mg-big">{dh:+.1f} pts</span><br>chance of an add-on sale</div>'
f'<div><span class="mg-big">{a["floor_violations"]} → {b["floor_violations"]}</span><br>items below the {pol.floor:.0%} floor</div></div>')
if res["unknown"]:
summary += f'<div class="mg-note">Ignored codes not in the model: {", ".join(res["unknown"][:10])}</div>'
tbl = cand.assign(
p_accept=(cand.p_accept * 100).round(1), margin=(cand.margin * 100).round(0),
exp_profit=cand.exp_profit.round(3), price=cand.price.round(2), unit_cost=cand.unit_cost.round(2),
picked=["✓" if j in {x for x, _ in res["optimized"]} else "" for j in range(len(cand))],
).rename(columns={"p_accept": "p(buy) %", "margin": "margin %", "exp_profit": "exp. profit £"})
return (summary, card(f"Plain top-{pol.max_addons} (relevance only)", cand, res["top"], pol, "#9aa0a6"),
card("MarginGraph pick", cand, res["optimized"], pol, "#0f9d58"), tbl)
# ---------------------------------------------------------------- merchant
def _rename(df: pd.DataFrame, wanted: list[str]) -> pd.DataFrame:
low = {c.lower().strip().replace(" ", "_"): c for c in df.columns}
m = {}
for w in wanted:
for a in ALIASES[w]:
if a in low:
m[low[a]] = w
break
return df.rename(columns=m)
def read_products(path) -> pd.DataFrame:
df = _rename(pd.read_csv(path, dtype=str), PRODUCT_COLS)
miss = [c for c in ["item", "price", "unit_cost", "stock"] if c not in df.columns]
if miss:
raise gr.Error(f"Products CSV is missing column(s): {', '.join(miss)}. Download the template.")
df["item"] = df["item"].astype(str).str.strip().str.upper()
if "description" not in df:
df["description"] = df["item"]
if "overstock" not in df:
df["overstock"] = "false"
df["overstock"] = df["overstock"].astype(str).str.strip().str.lower().isin(["1", "true", "yes", "y", "x"])
for c in ["price", "unit_cost", "stock"]:
df[c] = pd.to_numeric(df[c].astype(str).str.replace(r"[£$€,\s]", "", regex=True), errors="coerce")
bad = df[["price", "unit_cost", "stock"]].isna().any(axis=1).sum()
df = df.dropna(subset=["price", "unit_cost", "stock"])
df.attrs["dropped"] = int(bad)
return df[PRODUCT_COLS]
def read_baskets(path) -> list[list[str]]:
df = _rename(pd.read_csv(path, dtype=str), ["basket", "item"])
if not {"basket", "item"} <= set(df.columns):
raise gr.Error("Orders CSV needs two columns: order_id (or invoice/basket_id) and item (or sku/stock_code).")
return core.baskets_from_lines(df, "basket", "item")
def load_store(products_file, orders_file):
if products_file is None:
raise gr.Error("Upload a products CSV first (use the template).")
prods = read_products(products_file)
notes = [f"Loaded **{len(prods):,}** products"
+ (f" ({prods.attrs['dropped']} rows skipped: missing price, cost or stock)." if prods.attrs["dropped"] else ".")]
if orders_file is not None:
baskets = read_baskets(orders_file)
try:
model = core.train_from_baskets(baskets, prods)
except ValueError as e:
raise gr.Error(str(e)) from e
h = model.calib["hit"]
notes.append(f"Trained on **{len(baskets):,}** of your orders ({len(model.items):,} products). "
f"Backtest on your most recent 20% of orders: the hidden item is in our top-2 "
f"**{h['hit@2']:.1%}** of the time, top-10 **{h['hit@10']:.1%}** "
f"({model.calib['n_events']:,} test baskets).")
else:
model = core.Model(DEMO.items, DEMO.B, DEMO.calib, prods)
n = int(model.catalog["price"].gt(0).sum())
notes.append(f"No order history uploaded, so the demo model (Online Retail II co-purchases) is used. "
f"**{n:,}** of your products match its item codes and can be recommended. "
f"Upload orders to train on your own data.")
if n == 0:
notes.append("⚠️ None of your codes match. Upload your order history so the model can learn your catalog.")
sold = model.catalog[model.catalog["price"] > 0]
return model, "\n\n".join(notes), gr.Dropdown(choices=[label(model, c) for c in sold["item"]], value=[])
def store_recommend(model, sel, floor, ow, lam, disc, k):
if model is None:
raise gr.Error("Load your store first.")
return run(model, codes_from(sel), policy(floor, ow, lam, disc, k))
def batch(model, baskets_file, floor, ow, lam, disc, k):
if model is None:
model = DEMO
if baskets_file is None:
raise gr.Error("Upload a CSV of open baskets (basket_id, item).")
df = _rename(pd.read_csv(baskets_file, dtype=str), ["basket", "item"])
if not {"basket", "item"} <= set(df.columns):
raise gr.Error("Baskets CSV needs columns basket_id and item.")
pol = policy(floor, ow, lam, disc, k)
out = []
for bid, g in df.groupby("basket", sort=False):
res = model.recommend(g["item"].tolist(), pol)
if not res["known"]:
out.append({"basket_id": bid, "slot": 0, "item": "", "description": "no known items"})
continue
cand = res["candidates"]
for slot, (j, d) in enumerate(res["optimized"], 1):
r = cand.loc[j]
price = r.price * (1 - d)
out.append({"basket_id": bid, "slot": slot, "item": r["item"], "description": r.description,
"price": round(price, 2), "discount": d, "margin": round((price - r.unit_cost) / price, 3),
"p_accept": round(r.p_accept * (1 + pol.elasticity * d), 4),
"expected_profit": round(r.p_accept * (1 + pol.elasticity * d) * (price - r.unit_cost), 4),
"overstock": bool(r.overstock), "because_of": r.because_of})
res = pd.DataFrame(out)
path = Path(tempfile.mkdtemp()) / "margingraph_recommendations.csv"
res.to_csv(path, index=False)
return res.head(50), str(path)
def template() -> str:
path = Path(tempfile.mkdtemp()) / "products_template.csv"
DEMO.catalog[PRODUCT_COLS].head(300).to_csv(path, index=False)
return str(path)
def orders_template() -> str:
path = Path(tempfile.mkdtemp()) / "orders_template.csv"
rows = [(f"ORD{i:05d}", c) for i, b in enumerate(META["examples"]) for c in b]
pd.DataFrame(rows, columns=["order_id", "item"]).to_csv(path, index=False)
return str(path)
# ---------------------------------------------------------------- backtest tab
def backtest_md() -> str:
bt, tr = META["backtest"], META["test_ranking"]
names = {"top2_relevance": "Plain top-2 (relevance only)",
"margingraph_lam0.5": "MarginGraph, balance 0.5",
"margingraph_lam1.0": "MarginGraph, balance 1.0 (profit)",
"margingraph_lam1.0_overstock2x": "MarginGraph, balance 1.0, overstock 2x"}
lines = ["| Strategy | Hit@2 | Realized profit / basket | vs top-2 (95% CI, £/basket) | Below 15% floor | Overstock share |",
"|---|---|---|---|---|---|"]
for k, v in bt.items():
ci = v["realized_profit_diff_ci95"]
lines.append(f"| {names.get(k, k)} | {v['hit@2']:.1%} | £{v['realized_profit_per_basket']:.4f} | "
f"{v['realized_profit_vs_top2_pct']:+.1f}% ([{ci[0]:+.4f}, {ci[1]:+.4f}]) | "
f"{v['margin_floor_violations_per_basket']:.3f} | {v['overstock_share_of_offers']:.1%} |")
return f"""
### Measured on real held-out baskets (not targets)
**Protocol.** Model fit on Dec 2009 to Sep 2011, tested on {META['n_test_events']:,} invoices from Oct to Dec 2011.
In each test invoice one product is hidden; a strategy *hits* if one of its 2 add-ons is that product.
*Realized profit* only counts the hidden product, so it is grounded in what customers really bought.
**Stage 1 (EASE, {META['n_items']:,} products, {META['test_line_coverage']:.0%} of test lines covered):**
Hit@2 {tr['hit']['hit@2']:.1%} · Hit@5 {tr['hit']['hit@5']:.1%} · Hit@10 {tr['hit']['hit@10']:.1%}.
Picking at random from {META['n_items']:,} products would hit about {2/META['n_items']:.2%} at 2.
**Stage 2:**
{chr(10).join(lines)}
Costs and stock in this table are **simulated** (Beta(4,6) margins, mean 40%; 15% of items overstocked),
so profit numbers show how the optimizer behaves, not what a real store would earn.
The full research pipeline (LightGBM reranker, Hit@10 38.1%) lives in the main repo.
"""
# ---------------------------------------------------------------- UI
CSS = """
.mg-card{background:var(--block-background-fill);border:1px solid var(--border-color-primary);border-radius:10px;padding:14px;min-height:210px}
.mg-h{font-weight:700;font-size:1.05em;margin-bottom:8px}
.mg-item{padding:8px 0;border-bottom:1px dashed var(--border-color-primary)}
.mg-name{font-weight:600}.mg-code{opacity:.6;font-size:.85em;font-weight:400}
.mg-meta,.mg-why{font-size:.9em;opacity:.85}.mg-why{font-style:italic}
.mg-foot{margin-top:10px;font-size:.95em}
.mg-tag{display:inline-block;font-size:.75em;padding:1px 6px;border-radius:8px;background:#e8eaed;color:#333;margin-left:4px}
.mg-over{background:#fde293}.mg-bad{background:#f6aea9}
.mg-sum{display:flex;gap:16px;flex-wrap:wrap;margin:6px 0}.mg-sum>div{flex:1;min-width:150px;text-align:center;padding:8px;border-radius:10px;background:var(--block-background-fill);border:1px solid var(--border-color-primary)}
.mg-big{font-size:1.8em;font-weight:700}
.mg-note{padding:8px;border-radius:8px;background:#fef7e0;color:#5f4b00;margin-top:6px}
"""
DEMO_CHOICES = choices(DEMO)
def controls():
with gr.Row():
floor = gr.Slider(0, 0.5, 0.15, step=0.01, label="Margin floor (min margin per add-on)")
ow = gr.Slider(1.0, 2.0, 1.0, step=0.05, label="Overstock weight (push excess stock)")
lam = gr.Slider(0, 1, 1.0, step=0.05, label="Balance: 0 = most likely to sell, 1 = most profit")
with gr.Row():
disc = gr.Checkbox(False, label="Allow 10% / 20% discounts (assumed demand response)")
k = gr.Radio([1, 2], value=2, label="Add-ons to show")
return floor, ow, lam, disc, k
with gr.Blocks(title="MarginGraph: profit-aware add-on recommendations") as demo:
gr.Markdown("""# MarginGraph
**Checkout add-ons that customers want *and* that keep your margin.** Stage 1 learns what is bought together
from real orders. Stage 2 picks the best 2 add-ons under hard business rules: a minimum margin,
in-stock only, and an optional push for overstocked items.""")
with gr.Tab("Demo store"):
gr.Markdown(SIM_NOTE)
with gr.Row():
basket = gr.Dropdown(DEMO_CHOICES, value=[label(DEMO, c) for c in META["examples"][0]],
multiselect=True, label="Basket (type to search 2,000 products)", scale=4)
ex_btn = gr.Button("🎲 Real basket", scale=1)
floor, ow, lam, disc, k = controls()
go = gr.Button("Recommend add-ons", variant="primary")
summary = gr.HTML()
with gr.Row():
left, right = gr.HTML(), gr.HTML()
with gr.Accordion("All 20 candidates the optimizer looked at", open=False):
table = gr.Dataframe(wrap=True)
ins = [basket, floor, ow, lam, disc, k]
outs = [summary, left, right, table]
fn = lambda sel, *a: run(DEMO, codes_from(sel), policy(*a)) # noqa: E731
go.click(fn, ins, outs)
for c in [floor, ow, lam, disc, k]:
c.release(fn, ins, outs) if isinstance(c, gr.Slider) else c.change(fn, ins, outs)
def random_basket():
b = META["examples"][np.random.randint(len(META["examples"]))]
return [label(DEMO, c) for c in b]
ex_btn.click(random_basket, None, basket).then(fn, ins, outs)
demo.load(fn, ins, outs)
with gr.Tab("Your store"):
gr.Markdown("""**Use your own catalog.** 1) Upload products with `item, description, price, unit_cost, stock`
(optional `overstock` = yes/no). 2) Optionally upload order history (`order_id, item`, one row per item, oldest first)
so the model learns *your* customers; without it the demo model is used for matching item codes.
Files stay in this session only and are not stored.""")
store = gr.State(None)
with gr.Row():
with gr.Column():
pf = gr.File(label="Products CSV", file_types=[".csv"], elem_id="products-file")
gr.DownloadButton("Products template", value=template)
with gr.Column():
of = gr.File(label="Order history CSV (optional)", file_types=[".csv"], elem_id="orders-file")
gr.DownloadButton("Orders template", value=orders_template)
load_btn = gr.Button("Load my store", variant="primary")
status = gr.Markdown()
s_basket = gr.Dropdown([], multiselect=True, label="Basket from your catalog")
sfloor, sow, slam, sdisc, sk = controls()
s_go = gr.Button("Recommend", variant="primary")
s_sum = gr.HTML()
with gr.Row():
s_left, s_right = gr.HTML(), gr.HTML()
with gr.Accordion("Candidates", open=False):
s_tbl = gr.Dataframe(wrap=True)
load_btn.click(load_store, [pf, of], [store, status, s_basket])
s_go.click(store_recommend, [store, s_basket, sfloor, sow, slam, sdisc, sk], [s_sum, s_left, s_right, s_tbl])
gr.Markdown("### Batch: recommendations for many open baskets\nUpload `basket_id, item` rows; "
"uses your store if loaded, otherwise the demo store.")
bf = gr.File(label="Open baskets CSV", file_types=[".csv"], elem_id="baskets-file")
b_go = gr.Button("Run batch")
b_tbl = gr.Dataframe(label="First 50 rows")
b_dl = gr.File(label="Download all recommendations")
b_go.click(batch, [store, bf, sfloor, sow, slam, sdisc, sk], [b_tbl, b_dl])
with gr.Tab("Backtest"):
gr.Markdown(backtest_md())
with gr.Tab("How it works / API"):
gr.Markdown("""
**Pipeline.** Basket → EASE co-purchase model scores every product → top 20 candidates →
p(buy) calibrated on held-out baskets → exact optimizer picks ≤ 2 add-ons that maximize
`p(buy) × ((1 − balance) × avg p + balance × overstock_weight × unit profit)`
subject to margin ≥ floor, stock > 0, one discount per item. Rules are enforced in code; nothing is guessed by an LLM.
**Call it from code** (every button is also an API endpoint):
```python
from gradio_client import Client
c = Client("EquilStable/MarginGraph")
print(c.view_api())
```
Source and research pipeline: [github.com/Sanskar1724/MarginGraph](https://github.com/Sanskar1724/MarginGraph)
""")
if __name__ == "__main__":
demo.launch(css=CSS, theme=gr.themes.Soft())