lxe/receipt-item-namer

Receipt Item Namer (Qwen3.5-4B LoRA)

Turns one printed US receipt line into a readable product name and one of 39 spending categories. This is the adapter that ships on-device in the Receipt Kitten iOS app (4-bit MLX base + this LoRA, about 0.6 s per item on an M-series Mac).

Store: Walmart Supercenter (grocery)
Item: GV PPR TWL 6RL

-> Great Value Paper Towels | Paper & Disposables

Files

• mlx/: adapters.safetensors + adapter_config.json for mlx-lm / mlx-swift-lm (61 MB).
• peft/: the same adapter as a PEFT LoRA for transformers (bf16 training output), plus training_summary.json (validation loss history).
• taxonomy.json: the 39 categories (taxonomy v2) with definitions. sections.py: label cleaning and prompt builder.
• eval/: metrics on the private truth set and on held-out real lines.

Usage

Prompt = one user turn, no system prompt, Qwen chat template with thinking disabled, greedy decoding, max 40 new tokens. Optional Section: line when the receipt prints a heading (e.g. HOUSEHOLD, PRODUCE) above the item:

Store: {store} ({store_type})
Section: {heading}
Item: {label}

store_type is one of grocery, retail, big-box, pharmacy, convenience, restaurant, cafe, gas, other. Clean the label with sections.namer_label first (drops UPC codes, tax flags and 2 @ quantity prefixes). Output: Name | Category; if the category is not in taxonomy.json, treat the answer as unknown.

from mlx_lm import load, generate
model, tok = load("path/to/Qwen3.5-4B-mlx-4bit", adapter_path="mlx")   # a 4-bit MLX conversion of Qwen/Qwen3.5-4B
msgs = [{"role": "user", "content": "Store: Target (retail)\nItem: UP&UP ALOE WIPES\n"}]
ids = tok.apply_chat_template(msgs, add_generation_prompt=True, enable_thinking=False)
print(generate(model, tok, prompt=ids, max_tokens=40))

The app runs it on a 4-bit (group size 64) MLX conversion of the base; the scores below are for that setup.

Evaluation

Truth set: 988 line items on 152 real US/CA receipts with hand-checked names and categories (not public: it includes the author's own receipts). None of these receipts are in the training data (image-hash and text overlap checks).

model	leaf acc	top-level acc	name F1	brand correct	leaf on high-confidence items
Qwen3.5-4B zero-shot (long system prompt)	59.9%	75.1%	0.541	27.6%	71.4%
v2 adapter (real + synthetic, no household)	76.7%	88.3%	0.672	60.5%	87.4%
this adapter (v4)	79.2%	90.1%	0.689	61.9%	89.0%

v2 -> v4: 75 items fixed, 51 broken (exact McNemar p = 0.04); the gain is in household, home, garden and tools lines. On 764 held-out real receipt lines labelled by the teacher: 91.4% leaf, 94.9% top-level.

Training

LoRA r16, alpha 32, dropout 0, on the attention, linear-attention and MLP projections of all 32 text layers of Qwen/Qwen3.5-4B (bf16); lr 2e-4, 2 epochs, batch 64, 3% warmup, loss on the assistant turn only; one RTX PRO 6000, under an hour. 185,079 training rows:

• 112,114 synthetic POS-style lines (names from USDA Branded Foods and Open Food Facts, hand-written lexicons, real-receipt seeds), categories re-labelled to taxonomy v2 by DeepSeek V4.1 Flash;
• 40,653 real receipt lines (13,551 distinct, repeated x3), labelled by the same teacher: ReceiptBench, ExpressExpense SRD, JensWalter/my-receipts, docjay131/receipts-ocr-dataset and WildReceipt receipts;
• 32,312 household lines (teacher-generated inventories for 21 US chains + Open Products/Beauty/Pet Food Facts products).

The published datasets are a subset of this mix: WildReceipt receipts (no stated license) and documents with personal data are not redistributed. See the dataset cards.

Training data disclosure

Part of the training mix came from WildReceipt (Sun et al., 2021, "Spatial Dual-Modality Graph Reasoning for Key Information Extraction"; distributed via OpenMMLab MMOCR). WildReceipt has no stated license (MMOCR lists it as "N/A"), and its images were collected from web searches. This model was trained on product-line text derived from those receipts using our own OCR; it outputs product names and categories only and cannot reproduce the images or the original annotations. No WildReceipt images, annotations or derived rows are redistributed in the companion datasets. If you are a rights holder and have a concern, please open a discussion on this repository.

Limitations

• US-centric retail and restaurant receipts; English only.
• Names for heavily abbreviated labels are guesses and sometimes invent a plausible brand; about 1 in 5 leaf categories is wrong on hard retail receipts (household vs. home & garden vs. tools boundaries are the weakest).
• Teacher-labelled training data: systematic teacher errors are learned.

License

Apache-2.0 for the adapter weights (base model Qwen/Qwen3.5-4B is Apache-2.0).

Contains information from Open Food Facts, Open Products Facts, Open Beauty Facts and Open Pet Food Facts, which is made available under the Open Database License (ODbL) v1.0 (https://opendatacommons.org/licenses/odbl/1-0/). Training data also derives from ReceiptBench (MIT), ExpressExpense SRD (MIT; source: ExpressExpense.com), docjay131/receipts-ocr-dataset (MIT), JensWalter/my-receipts (CC0), USDA FoodData Central (public domain) and WildReceipt (Sun et al., 2021, "Spatial Dual-Modality Graph Reasoning for Key Information Extraction"; no license stated). Teacher labels were generated with the DeepSeek Open Platform API, whose terms allow training other models on outputs.