Docs/FEATURES_STATUS.md

ShopStack Features: Built vs. Pending

Last updated: 2026-06-15 Test count: 3571 tests collected (verified 2026-06-15; previous 3134/2906/2651/2898 counts are stale). Run pytest tests/ --collect-only -q for the latest. Test result: 3550 passed, 21 skipped, 0 failed (serial run, 2026-06-15). Verification tier: Tier 3 (full test suite plus HF provider tests pass)

---

🟢 BUILT — ShopStock (Inventory)

Feature	Status	Evidence	Verification Tier
SQLite database (10 tables, WAL mode)	✅ Complete	database.py — full CRUD for all tables	Tier 3 (32 tests pass)
18 hierarchical household locations	✅ Complete	database.py — seeded on init	Tier 3
Add inventory item	✅ Complete	tools/registry.py — add_inventory_item	Tier 3
Update inventory item (partial fields)	✅ Complete	tools/registry.py — update_inventory_item	Tier 3
Consume inventory (partial/full, auto-status)	✅ Complete	tools/registry.py — consume_inventory_item	Tier 3
Move item between locations (with tracking)	✅ Complete	tools/registry.py — move_inventory_item	Tier 3
Find item by prefix search	✅ Complete	tools/registry.py — find_item	Tier 3
Inventory lot ID prefix resolution	✅ Complete	database.py — resolve_inventory_lot_id	Tier 3
Inventory view/search UI	✅ Complete	screens/inventory.py	Tier 3
Batch consume items (lot_id: qty)	✅ Complete	screens/inventory.py — consume_items_batch	Tier 3
Use Soon / expiration alerts (3-day default)	✅ Complete	tools/registry.py — get_use_soon_items	Tier 3
Seed demo inventory	✅ Complete	screens/inventory.py — seed_demo_inventory	Tier 3
Data portability (JSON/CSV export/import)	✅ Complete	portability.py	Tier 3

🟢 BUILT — ShopBasket (Shopping List)

Feature	Status	Evidence	Verification Tier
Create/update active shopping list	✅ Complete	tools/registry.py — create_or_update_shopping_list	Tier 3
Shopping list with items, priorities, reasons	✅ Complete	schemas/models.py — ShoppingList, ShoppingListItem	Tier 3
Complete list → add items to inventory	✅ Complete	services/shopping.py — complete_shopping_list_service	Tier 3
Mark items as purchased (per-item)	✅ Complete	services/shopping.py — mark_items_purchased_service	Tier 3
Classify items (buy/skip/use-soon)	✅ Complete	services/shopping.py — classify_shopping_items	Tier 3
Enrich items with Swiggy market prices	✅ Complete	services/shopping.py — enrich_items_with_swiggy	Tier 3
Shopping list UI with cards	✅ Complete	screens/shopping.py	Tier 3
Shopper share summary	✅ Complete	screens/shopping.py — _shopping_list_share_text/html	Tier 2
Trace recording for shopping workflows	✅ Complete	screens/shopping.py — _record_shopping_trace	Tier 2

🟢 BUILT — ShopCompare (Price Intelligence)

Feature	Status	Evidence	Verification Tier
Price history per item	✅ Complete	database.py — get_price_history	Tier 3
Unit price normalization (kg/g/L/mL)	✅ Complete	market/normalization.py	Tier 3
Price intelligence view (best store, drops)	✅ Complete	screens/price_compare.py — price_intelligence_view	Tier 3
Price memory view with plots	✅ Complete	screens/price_memory.py — price_memory_view	Tier 3
Record price observations via tool	✅ Complete	tools/registry.py — record_price_observation	Tier 3

🟢 BUILT — ShopLens (Scanning)

Feature	Status	Evidence	Verification Tier
Barcode decoding (pyzbar + zbarimg fallback)	✅ Complete	scanner.py — decode_barcode	Tier 2
Barcode type inference (EAN-13, EAN-8, CODE128, QR)	✅ Complete	scanner.py — _infer_barcode_type	Tier 2
Product code from barcode inference	✅ Complete	scanner.py — infer_product_from_code	Tier 2
Market Lens full pipeline (image + audio)	✅ Complete	services/market_lens.py — analyze_market_lens	Tier 2
Detect visible items + compare to inventory	✅ Complete	services/market_lens.py — analyze_visible_items	Tier 2
Audio transcription for voice input	✅ Complete	services/market_lens.py — transcribe_audio	Tier 2
Swiggy price enrichment in Market Lens	✅ Complete	services/market_lens.py — enrich_market_prices	Tier 2
Market Lens UI (scan, confirm buy, skip, save)	✅ Complete	screens/market_lens.py	Tier 2
Barcode add to inventory	✅ Complete	screens/market_lens.py — market_lens_barcode_add	Tier 2

🟢 BUILT — ShopMemory

Feature	Status	Evidence	Verification Tier
Price history, trends, best-store intelligence	✅ Complete	screens/price_memory.py, screens/price_compare.py	Tier 3
Field notes markdown editor	✅ Complete	screens/field_notes.py	Tier 3
Price memory view with chart data	✅ Complete	ui/views.py — PriceMemoryView	Tier 3
Purchase cadence detection	✅ Complete	decisions/rules.py — detect_purchase_cadence	Tier 2
Waste pattern detection	✅ Complete	decisions/rules.py — detect_waste_patterns	Tier 2
Price drop alerts	✅ Complete	screens/price_compare.py — price intelligence view	Tier 2

🟢 BUILT — ShopAgent (Reasoning)

Feature	Status	Evidence	Verification Tier
Decision engine (7-class buy/skip/use-soon)	✅ Complete	decisions/rules.py — classify_all	Tier 3
DecisionSet with filtered views (buy, skip, etc.)	✅ Complete	decisions/types.py — DecisionSet	Tier 3
Decision rendering (badges, cards, panels)	✅ Complete	decisions/__init__.py — render_* functions	Tier 2
Planner engine (complete → parse → execute)	✅ Complete	planner/engine.py — PlannerEngine	Tier 3
Tool-call prompt builder	✅ Complete	planner/prompts.py	Tier 3
JSON/XML parser for LLM output	✅ Complete	planner/parser.py	Tier 3
Trace system (creation, export, PII redaction)	✅ Complete	traces/export.py	Tier 3
Trace UI (list, detail, search, filter, export)	✅ Complete	screens/traces.py	Tier 3
Ask ShopStack UI (text + voice)	✅ Complete	screens/ask.py — ask_shopstack, ask_shopstack_from_audio	Tier 2
Voice add command parsing	✅ Complete	screens/ask.py — _handle_add_command	Tier 2
Dashboard state assembly	✅ Complete	services/dashboard.py — build_dashboard_state	Tier 3
Today dashboard UI (stats, decisions, cadence)	✅ Complete	screens/dashboard.py — today_dashboard	Tier 3
Swiggy availability check for shopping items	✅ Complete	decisions/rules.py — check_swiggy_availability	Tier 2

🟢 BUILT — Sources (Swiggy Instamart)

Feature	Status	Evidence	Verification Tier
Swiggy snapshot loader (CSV + JSON)	✅ Complete	market/sources/swiggy.py	Tier 3
Normalization pipeline (size, price, canonical)	✅ Complete	market/normalization.py	Tier 3
Market analytics (stats, cheapest, category)	✅ Complete	market/analytics.py	Tier 3
Basket builder (canonical matching)	✅ Complete	market/basket.py	Tier 3
Produce metadata (~80 items: shelf-life, waste-risk)	✅ Complete	market/metadata.py	Tier 3
Swiggy market view in UI	✅ Complete	screens/other.py — swiggy_market_view	Tier 2
Swiggy basket estimator	✅ Complete	screens/other.py — swiggy_basket_estimate	Tier 2
Swiggy price seeding to Price Memory	✅ Complete	screens/other.py — seed_swiggy_prices	Tier 2
Swiggy import script	✅ Complete	scripts/import_swiggy_snapshot.py	Tier 2

🟢 BUILT — Runtime & Model Stack

Feature	Status	Evidence	Verification Tier
Model registry (16 candidate entries)	✅ Complete	model_registry.py	Tier 3
Parameter budget enforcement (≤32B)	✅ Complete	model_registry.py — validate_active_model_budget	Tier 3
Provider factory with mock fallback	✅ Complete	providers/registry.py	Tier 3
Runtime diagnostics (provider status badge)	✅ Complete	screens/model_stack.py	Tier 2
Local provider (MLX + llama.cpp)	✅ Complete	providers/local_provider.py	Tier 3
OpenAI provider (cloud fallback)	✅ Complete	providers/openai_provider.py	Tier 2
Local Whisper provider	✅ Complete	providers/local_whisper_provider.py	Tier 2
Mock providers for all 11 interfaces	✅ Complete	providers/mock_providers.py	Tier 3

🟢 BUILT — Infrastructure

Feature	Status	Evidence	Verification Tier
Gradio Blocks UI (13 tabs)	✅ Complete	app.py — build_app()	Tier 3 (5 app smoke tests)
Module registry with canonical names	✅ Complete	module_registry.py	Tier 3
Error boundary decorator (@safe_render)	✅ Complete	screens/_utils.py	Tier 3
CI pipeline (GitHub Actions)	✅ Complete	.github/workflows/ci.yml	Tier 2
Pre-commit test count sync	✅ Complete	tools/sync-readme-stats	Tier 2
Portability (JSON/CSV export/import)	✅ Complete	portability.py	Tier 3
Test suite (2906 tests as of 2026-06-14)	✅ Complete	tests/	Tier 3

---

🟡 PARTIAL — Needs Attention

Feature	Status	Gap	Blast Radius
Test suite timeout	✅ Fixed	Tests run deterministically in ~70-83s	No longer a blocker. Parallel test runs possible.
Benchmark tests	⚠️ May be stale	Actually benchmark count unknown	2 benchmark files, 0 known runs in this session
Receipt scanning pipeline	🟡 Partial	OCR provider exists, no receipt→purchase flow	UI only. No pipeline wiring.
Household map UI	🟡 Duplicate	Both screens/other.py and screens/household.py define household_map_view	Supersession needed. household.py may be pending.
Price memory view	🟡 Duplicate	Both screens/other.py and screens/price.py define price_memory_view	price.py is the newer/canonical path.
Field notes screen	🟡 Duplicate	field_notes.py and other.py both define field_notes_view/save	field_notes.py imported; other.py version may be dead.
Swiggy freshness labels	🟡 Verification	"point-in-time" labels exist, no staleness logic	UI display only, no functional impact.

---

🔴 NOT BUILT — Pending

Feature	Priority	Notes	Depends On
Containerization	P1	No Dockerfile or deployment config	—
Production deployment	P1	No hosting setup	Containerization
Semantic inventory search	P1	BGE-M3 model registered (candidate), no wiring to search path	embeddings provider activation
HF Inference API provider	✅ Complete	providers/huggingface_provider.py — 26 tests cover init/complete/plan/retry/registry wiring	—
Modal cloud GPU provider	P1	Documented in MODEL_CATALOG, not implemented	—
Multi-retailer sources	P1	Only Swiggy; no Blinkit, Zepto, DMart adapters	Source adapter pattern established
Receipt → purchase pipeline	P1	OCR provider can extract text, no pipeline to create PurchaseEvent	OCR provider
Multi-user auth	P2	user_id columns exist, no login/routing	—
Purchase cadence dashboard widget	P2	detect_purchase_cadence exists, not wired to dashboard	—
Waste prevention dashboard widget	P2	detect_waste_patterns exists, not wired to dashboard	—
Load testing / performance	P2	No benchmark data yet	—
Demo data seed scripts	P2	seed_demo_inventory exists; no walkthrough script	—
TTS provider (real)	P3	MockTTSProvider only; kokoro-82m candidate	Model download
STT provider (high quality)	P3	LocalWhisperProvider active (tiny); qwen3-asr-1.7b candidate	Model download
Image generation (item cards)	P3	Flux.2-4b candidate only	Model download
Fine-tuned command parser	P4	shopstack-parser-lora planned	Training data
Nutrition tracking	P4	ItemCatalog.nutrition_reference exists in schema, no UI	—
Weather/trip context	P4	TripWeatherContext model exists, not used	—
Detection events pipeline (vision)	P4	DetectionEvent model, MockVisionProvider; no real model wired	Vision model
Segmentation (item cards)	P4	RMBG-1.4 candidate; MockSegmentationProvider only	Model download

---

Priority Summary

Priority	Count	Key Items
P0	0	(All critical features built)
P1	6	Containerization, Deployment, Semantic search, HF provider, Modal provider, Multi-retailer sources, Receipt pipeline
P2	4	Cadence widget, Waste widget, Load testing, Demo walkthrough
P3	4	TTS, STT (high quality), Image gen, Full dashboard integration
P4	4	Fine-tuned parser, Nutrition, Weather context, Detection pipeline

Immediate Next Work (recommended):

1. Fix test timeout — diagnose which test(s) hang, fix isolation
2. Resolve supersession conflicts — household.py vs other.py, price.py vs other.py
3. Wire semantic search — enable BGE-M3 for inventory prefix search fallback
4. Add receipt scanning pipeline — connect OCR output → purchase creation
5. Containerize app — add Dockerfile for deployment readiness

---

Status Update (2026-06-10) — Actual Codebase Reality vs Doc Claims

This section was added by an audit pass. See the parent conversation for full evidence.

Test Count

Doc Claim	Actual
Doc Claim	Actual
-----------	--------
"375+" / "558+" / "619" / "974" / "2651" / "2898" / "2903"	2906 tests collected (2026-06-14)

🔴 NOT BUILT — Reclassified Items

Items marked NOT BUILT that are actually BUILT or PARTIAL:

Doc Claim	Actual Status
Containerization P1: "No Dockerfile or deployment config"	✅ BUILT — Dockerfile, docker-compose.yml, .dockerignore all exist and functional
Multi-retailer sources P1: "Only Swiggy; no Blinkit, Zepto, DMart adapters"	✅ BUILT — All 3 adapters exist in shopstack/market/sources/
HF Inference API provider: "Complete"	✅ Already marked correct in original
Purchase cadence dashboard widget P2: "not wired to dashboard"	✅ WIRED — detect_purchase_cadence(db) is called in build_dashboard_state()
Waste prevention dashboard widget P2: "not wired to dashboard"	✅ WIRED — detect_waste_patterns(db) is called in build_dashboard_state()
Demo data seed scripts P2: "no walkthrough script"	✅ DONE — scripts/demo_walkthrough.py exists
Weather/trip context P4: "TripWeatherContext model exists, not used"	✅ BUILT — shopstack/services/weather.py and trip_context.py are fully implemented and used in dashboard
Nutrition tracking P4: "no UI"	🟡 PARTIAL — shopstack/ui/screens/nutrition.py and shopstack/services/nutrition.py exist; enrichment may be pending
Receipt → purchase pipeline P1: "no pipeline to create PurchaseEvent"	✅ BUILT — confirm_receipt() in receipt.py creates InventoryLot + PurchaseEvent + PriceObservation
Semantic inventory search P1: "not wired to search path"	🟡 PARTIAL — semantic_find_item tool exists in tools/registry.py; BGE-M3 activation pending

Items Still Truly PENDING

Feature	Priority	Status
Semantic search (BGE-M3 full wiring)	P1	Tool exists but embeddings not fully activated
Modal cloud GPU provider	P1	Not implemented
Multi-user auth	P2	user_id columns exist, no login/routing
Dark mode	Phase 3	Design tokens exist; no CSS toggle
Keyboard shortcuts	Phase 3	Not implemented
WCAG 2.1 AA full audit	Phase 3	Partial
Mobile capture PWA	Phase 3	Not started
Offline backup/restore	Phase 3	Not started
Nutrition enrichment / brand matching	Phase 4	Screen exists; data enrichment pending
Fine-tuned command parser	Phase 4	Needs dataset
Vision model integration	Phase 4	Models registered but not wired
Community price map	Phase 4	Not started
Load testing / performance	P2	Benchmark files exist but not consistently run

🟡 PARTIAL — Updated Reclassification

Feature	Old Status	New Status	Notes
Benchmark tests	⚠️ May be stale	🟡 Partial	benchmarks/ exist; need to run for current baselines
Household map UI	🟡 Duplicate	✅ Resolved	Supersession resolved per ACCEPTANCE_CONTRACT
Price memory view	🟡 Duplicate	✅ Resolved	price.py is canonical; other.py is shim
Field notes screen	🟡 Duplicate	✅ Resolved	field_notes.py is canonical
Swiggy freshness labels	🟡 Verification	🟡 Ongoing	Labels exist; staleness logic in _freshness_for() in rules.py