Instacart Reorder Recommender
A known-shopper grocery reorder recommender with leakage-aware data validation, saved training artifacts, calibrated ranking, baseline lift, serving endpoints, monitoring, and a browser demo.
What it is
The product question is straightforward: for a known shopper, which items should appear in a buy-again shelf or smart cart suggestion?
That is a practical recommender surface because grocery buying has rhythm, basket context, and repeated products. It should not be framed as cold-start discovery or a live commerce impact claim.
The loop it has to make believable
- 01
Evaluated candidate ranking separately from full-basket reconstruction so the metrics do not overstate product value.
- 02
Saved feature contracts and fingerprints so training and serving can be checked against the same artifact boundary.
How it’s built
The repo is strongest where many recommender demos are weak: contracts, leakage control, split protocol, evaluation boundaries, calibration, and serving parity.
The FastAPI app loads saved artifacts and returns ranked products with feature version, request ID, fallback status, and latency metadata.
Architecture
- Data path
- Raw Instacart CSVs, point-in-time validation, referential integrity, deterministic splits, dataset fingerprints
- Features
- 65 serving features under contract ca27e59e71136bc1
- Evaluation
- Candidate reorder and full-basket contracts, baseline lift, slice metrics, calibration plots, threshold curves
- Serving
- FastAPI loads model artifacts, feature schema, processed feature tables, product metadata, demo bundle, and monitoring state
What has to hold up
- Reported LightGBM temporal candidate F1 of 0.5665, full-basket F1 of 0.4159, P@10 of 0.5577, R@10 of 0.7025, and 1.67x lift over recency.
- Exposed recommendations, portfolio overview, health, OpenAPI docs, monitoring, and latency metadata through FastAPI.
How I would present it
I would show the portfolio endpoint and one recommendation request, then inspect the run summary and baseline lift table.
The honest claim is artifact-backed offline ML plus local serving, not an online A/B-tested production recommender.
Proof
VerifyRepository, checks, stack, status
- 01
Start with the project status and available evidence.
- 02
Read the architecture and edge-case sections.
- 03
Follow the documented proof path: README, verify_run_20260304, feature contract, resume_release evidence, API demo path.
- Role
- Data contracts, feature engineering, model evaluation, serving API
- Scope
- Artifact-backed grocery reorder recommender
- Proof
- README, verify_run_20260304, feature contract, resume_release evidence, API demo path
- Stack
- Python, Pandas, LightGBM, XGBoost, FastAPI, Pydantic, Prometheus
- Candidate F1
- 0.5665
- Basket F1
- 0.4159
- P@10/R@10
- 0.5577/0.7025
- Tests
- 93 passed