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` |