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 format
  • grocery.py — dependency-free model, CLI, and loader
  • example.py — minimal inference example
  • LICENSE — 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}
}
Downloads last month

-

Downloads are not tracked for this model. How to track
Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support

Dataset used to train barrydeen/grocery-next-model