Grocery Next
An extremely lightweight next-item recommender for grocery baskets. It uses sparse item co-occurrence and smoothed association confidence—not a neural network—and requires only the Python standard library.
Given two or more grocery items, the model ranks complementary items that are likely to appear in the same basket.
Model details
| Property | Value |
|---|---|
| Method | Smoothed pairwise co-occurrence scoring |
| Training baskets | 28,000 synthetic baskets |
| Cuisine families | 28 |
| Distinct ingredients | 1,256 |
| Observed item pairs | 73,392 |
| Smoothing default | 4.0 |
| Model format | JSON schema version 1 |
| Model file size | 2,368,838 bytes (2.26 MiB) |
| Model SHA-256 | d55de601a87a05c1f9f3d5b58379ac9f3617d0c2560a1745699bf162bab66884 |
| Runtime dependencies | Python standard library only |
| License | Apache-2.0 |
The model stores item counts, observed pair counts, and configuration. It does not store the original baskets and does not contain neural-network weights.
How scoring works
For selected item s and candidate c, the implementation estimates:
P(c | s) ≈ (lists_containing_s_and_c + k × lists_containing_c / total_lists)
/ (lists_containing_s + k)
k defaults to 4 and shrinks sparse pair counts toward candidate popularity. For multiple selected items, predictions average the confidence across those items. Selected items are excluded and ties are sorted alphabetically.
Scores are ranking confidences, not calibrated probabilities of the next real purchase.
How to get good results
Use a popularity penalty. The most common ingredients in this corpus—onions (56.6% of baskets), garlic (50%), tomatoes (33%)—appear in nearly every dish template. Left to the raw estimate above, a handful of ubiquitous pantry staples dominate the ranking no matter what you ask: for almost any two inputs the top results are some permutation of onions, garlic, tomatoes, eggs, rice.
To make the output actually reflect your selection, pass a popularity_penalty, which re-ranks by:
score = confidence / (1 + popularity_penalty × P(c))
It discounts globally frequent candidates so items that are characteristic of your input can surface. It is a re-ranking preference applied at prediction time, not a statistical property of the model: 0 returns the raw estimate (the old flat behavior), larger values emphasize specificity.
from grocery import GroceryModel
model = GroceryModel.load("model.json")
# penalty=8 makes the output track the input instead of the corpus average.
for prediction in model.predict(["injera", "berbere"], top_k=5, popularity_penalty=8.0):
print(f"{prediction.item}: {prediction.score:.1%}")
popularity_penalty |
Behavior |
|---|---|
0 |
Raw smoothed association. Popular staples always win. |
8 (CLI default) |
Re-ranks to surface items characteristic of your selection. |
12+ |
Strongly emphasizes rarity; may start surfacing niche items. |
The same knob is exposed on the CLI (predict, demo, and interactive all accept it, defaulting to 8):
python3 grocery.py predict injera berbere --model model.json # penalty 8
python3 grocery.py predict injera berbere --model model.json --pop-penalty 0 # raw / old behavior
Same input, injera + berbere, before vs. after:
raw (pop-penalty 0): onions 89.1%, garlic 77.6%, vegetable oil 69.7%, tomatoes 63.2%, niter kibbeh 55.0%
penalty 8: niter kibbeh 47.8%, vegetable oil 45.4%, fresh ginger 37.3%, green chilies 31.8%, ground cardamom 20.1%
Intended uses
- Next-item suggestions for grocery baskets
- Interactive shopping-list completion
- Lightweight recommendation demos and baselines
- Low-resource or offline recommendation experiments
Limitations
- Training data is entirely synthetic; the model does not learn real purchase frequencies.
- It treats baskets as unordered sets and does not model recipe order, quantities, brands, prices, seasons, or dietary restrictions.
- Different spellings and aliases are separate items unless normalized before training or inference.
- Cultural coverage is broad but not exhaustive.
- Inputs must contain at least two distinct, non-empty items.
Files
model.json— trained model in compact JSON formatgrocery.py— dependency-free model, CLI, and loaderexample.py— minimal inference exampleLICENSE— Apache-2.0 license
Usage
Clone the repository and run the example:
git clone https://huggingface.co/barrydeen/grocery-next-model
cd grocery-next-model
python3 example.py
Or load it through huggingface_hub:
import sys
from pathlib import Path
from huggingface_hub import snapshot_download
repo_dir = Path(snapshot_download(repo_id="barrydeen/grocery-next-model"))
sys.path.insert(0, str(repo_dir))
from grocery import GroceryModel
model = GroceryModel.load(repo_dir / "model.json")
for prediction in model.predict(
["tomatoes", "onions"], top_k=5, popularity_penalty=8.0
):
print(prediction.item, prediction.score)
Direct Python usage:
from grocery import GroceryModel
model = GroceryModel.load("model.json")
for prediction in model.predict(["rice", "miso"], top_k=5, popularity_penalty=8.0):
print(f"{prediction.item}: {prediction.score:.1%}")
Training data
Trained on the companion dataset:
- Dataset:
barrydeen/grocery-next-dataset - 28,000 synthetic baskets across 28 cuisine families
- Dataset seed:
20261112 - Canonical corpus SHA-256:
28d8280d3b16646b3650ad6a81e523157caab5aeff3f92043f8150ade5752ab9 - Dataset license: CC BY 4.0
The model is trained by GroceryModel.from_lists(read_lists(...)), then saved with model.save(...).
Evaluation
No held-out benchmark is claimed. The companion source project includes 18 passing tests and smoke checks over representative cross-cultural associations:
| Selected items | Top recommendations (raw, popularity_penalty=0) |
|---|---|
| tomatoes, onions | garlic 59.4%, olive oil 23.4%, potatoes 21.1% |
| jasmine rice, green curry paste | fish sauce 78.5%, chicken thighs 58.8%, coconut milk 50.1% |
| injera, berbere | onions 89.1%, garlic 77.6%, vegetable oil 69.7% |
These raw-estimate rows verify that the synthetic associations are learned—not that the rankings are universally correct—and are exactly why a popularity penalty (see above) is recommended for end use.
Reproduce with:
python3 -m unittest discover -s tests -v
python3 scripts/verify_cultural_model.py
Licensing
Code and model artifacts are released under Apache-2.0. The training dataset is released separately under CC BY 4.0; see the dataset card for attribution requirements.
Citation
@misc{grocery_next_model_2026,
title = {Grocery Next: Lightweight Grocery Basket Recommender},
author = {Grocery Next contributors},
year = {2026},
publisher = {Hugging Face},
url = {https://huggingface.co/barrydeen/grocery-next-model}
}