Upload folder using huggingface_hub

README.md

@@ -1,13 +1,306 @@
 ---
-title: Shopstack
-emoji: 🏃
-colorFrom: red
+title: ShopStack
+emoji: 🛒
+colorFrom: green
 colorTo: blue
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: "6.17.3"
 app_file: app.py
 pinned: false
+tags: [shopstack, gradio, inventory, shopping, offline-first, household]
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ShopStack
+
+Local-first, off-the-grid **shopping intelligence platform**. Know what you have, what to use soon, what to buy, what to skip, and where to buy from — without sending your data to the cloud.
+
+ShopStack is a stack of shopping intelligence layers: home inventory (ShopStock), shopping lists and market baskets (ShopBasket), retailer price comparison (ShopCompare), scanning and import (ShopLens), price history and preferences (ShopMemory), and a reasoning agent (ShopAgent) that decides buy/skip/use-soon across all modules.
+
+## Philosophy
+
+ShopStack runs entirely locally — SQLite database (WAL mode), mockable provider interfaces, and a Gradio workflow UI that works offline. The "Off the Grid" path means zero cloud dependencies for core functionality.
+The default mock providers let you build and test the full app without loading any ML models.
+
+**Total parameter limit:** ≤32 billion parameters across all loaded models.
+
+## Modules
+
+| Module | Purpose |
+|--------|---------|
+| **ShopStock** | Inventory, pantry, fridge, expiry, low-stock, use-soon |
+| **ShopBasket** | Shopping list, cart builder, market basket optimization |
+| **ShopCompare** | Retailer price comparison (Swiggy, Blinkit, Zepto, ...) |
+| **ShopLens** | Scanning: barcode, photo, receipt, barcode |
+| **ShopMemory** | Price history, household preferences, field notes |
+| **ShopAgent** | Reasoning: buy/skip/use-soon/compare decisions |
+| **Sources** | Retailer datasets (Swiggy Instamart + future) |
+
+See `Docs/SHOPSTACK_PRODUCT_ARCHITECTURE.md` for full details.
+
+## Gradio Workflows
+
+ShopStack is organized around workflow experiences:
+
+ - **Today** — Decision-first dashboard: what to buy, skip, use soon, and compare
+- **Ask ShopStack** — Natural language queries across all modules
+- **Shopping List** — Create, classify (buy/skip/use-soon), and complete shopping plans
+- **Market Lens** — Scan items via camera or voice, compare to inventory
+- **Add Purchase** — Record what was bought (price, store, location)
+- **Find Item at Home** — Search inventory by location and status
+- **Use Soon** — Expiring and aging items flagged for attention
+- **Price Memory Check** — Price history, trends, and best-store intelligence
+- **Traces** — Workflow audit trail with redacted export
+- **Field Notes** — Household notes and preferences
+
+## Quick Start
+
+```bash
+uv venv --python 3.13
+uv pip install -e ".[dev]"
+uv run python app.py
+```
+
+Open `http://localhost:7860` in your browser.
+
+## Market Snapshot Import
+
+ShopStack can ingest the real Swiggy Instamart fresh vegetables snapshot found in `data/swiggy_fresh_vegetables_cards_6jun26.json` (or the matching CSV) into the local price observation database.
+
+```bash
+uv run python scripts/import_swiggy_snapshot.py
+```
+
+Imported observations are tagged with `source_event_id = swiggy_fresh_vegetables_20260606` so they can be filtered or audited later.
+
+## Tests
+
+```bash
+uv run pytest tests/ -v
+uv run pytest benchmarks/ -v -m benchmark
+```
+
+Run `uv run pytest tests/ --collect-only -q` for the current test count.
+
+## Current Verified by Code Inspection
+
+As of the current code inspection, the following metrics are verified:
+- **17 Database Tables & 2 Views**: `inventory_lots`, `purchase_events`, `shopping_lists`, `shopping_list_items`, `household_locations`, `movement_events`, `price_observations`, `stores`, `traces`, `app_config`, `market_snapshots`, `market_records`, `market_record_components`, `reconciliation_events`, `preference_signals`, `inventory_events`, `households` (Tables), `price_history`, `agent_traces` (Views).
+- **12 Tools**: Including `semantic_find_item`.
+
+*Note: Tests are continuously added. For the latest test count, run `uv run pytest tests/ --collect-only -q`.*
+
+**Engineering Mandate:** Do not narrow scope to hackathon/MVP. ShopStack is designed as a long-term, bold, and comprehensive intelligence platform. Follow `motto_v3.md` principles exactly.
+
+## Project Structure
+
+```
+shopstack/
+  __init__.py
+  _version.py               # v0.1.0
+  config.py                 # Settings (pydantic-settings, env prefix SHOPSTACK_)
+  model_registry.py         # 16 candidate model entries (all ≤32B total)
+  schemas/
+    models.py               # All Pydantic domain models (14+ classes, 16 enums)
+  providers/
+    interfaces.py           # 11 abstract provider ABCs
+    mock_providers.py       # Full mock implementations for all 11 (Indian/Hinglish data)
+    registry.py             # ProviderRegistry factory wired to Settings
+  persistence/
+    database.py             # SQLite Database (WAL, 17 tables, 2 views, 18 seeded locations, full CRUD)
+  services/                 # Business logic services (decision engine, shopping, dashboard, preferences, freshness)
+  tools/
+    registry.py             # ToolRegistry — 12 tools executing against Database
+  traces/
+    export.py               # Trace creation, JSONL export, PII redaction
+  data_sources/             # Data source adapters for market snapshots and external feeds
+  ui/                       # (reserved)
+  configs/                  # (reserved)
+
+app.py                      # Gradio Blocks UI entry point (workflow-first tabs, custom warm CSS)
+tests/                      # pytest test suite (run `pytest tests/ --collect-only -q` for current count)
+benchmarks/                 # pytest benchmark suite (9 latency markers)
+```
+
+## Architecture
+
+```
+Gradio Blocks (app.py)
+  → ToolRegistry (12 tools, validates args, calls Database)
+    → Database (SQLite WAL, 17 tables, 2 views, 18 seeded locations)
+  → ProviderRegistry (wired from Settings)
+    → MockProviders (default — 11 interfaces, all offline)
+    → Market services (market source registry load + snapshot status helpers in `shopstack.services.market_sources`)
+  → Settings (pydantic-settings, env-overridable)
+  → ModelRegistry (16 candidates, not loaded by default)
+```
+
+### 11 Provider Interfaces
+
+| Interface | Mock Behavior |
+|-----------|--------------|
+| `STTProvider` | Returns predefined Hindi/Hinglish phrases |
+| `TTSProvider` | Writes a note about what would be spoken |
+| `VisionProvider` | Randomly samples from 26 common kitchen items |
+| `ObjectDetectionProvider` | Returns plausible bounding boxes + confidences |
+| `GroundingProvider` | Returns grounded item references |
+| `SegmentationProvider` | Returns placeholder masks |
+| `OCRProvider` | Returns mock extracted text |
+| `PlannerProvider` | Returns structured multi-step plans |
+| `ToolCallParserProvider` | Parses intent → tool call candidates |
+| `EmbeddingsProvider` | Returns random 384-d vectors |
+| `ImageEditProvider` | Returns a dummy edited image path |
+
+### 12 Tools
+
+| Tool | Purpose |
+|------|---------|
+| `add_inventory_item` | Add a new item to household inventory |
+| `update_inventory_item` | Update details of an existing inventory item |
+| `consume_inventory_item` | Record consumption (partial or full) |
+| `move_inventory_item` | Move an item to a different storage location |
+| `find_item` | Search for an item across inventory and locations |
+| `semantic_find_item` | Search for an item using exact, prefix, and semantic embedding search with match quality scores |
+| `create_or_update_shopping_list` | Create/update the active shopping list |
+| `compare_visible_item_to_inventory` | Compare detected item against current stock |
+| `record_price_observation` | Record a price observation for an item |
+| `get_use_soon_items` | Get items expiring or aging soon |
+| `get_next_buy_suggestions` | Get suggestions for what to buy next |
+| `export_anonymized_trace` | Export an anonymized agent trace |
+
+### 10 Database Tables
+
+`inventory_lots`, `purchase_events`, `shopping_lists`, `shopping_list_items`, `household_locations`, `movement_events`, `price_observations`, `stores`, `traces`, `app_config`
+
+Compatibility aliases: `price_history` and `agent_traces` are exposed as read/delete-compatible views for older docs, tests, and scripts.
+
+18 hierarchical household locations seeded on every init (safe via COUNT check): Home → Kitchen → Fridge → Fridge Door → ..., Pantry → Shelf → ..., etc.
+
+### Trace System
+
+Every tool execution creates an agent trace stored in the database. Traces include perception snapshots, inventory context, decision rationale, proposed tool calls, and human confirmation status. On export, traces are **redacted** for PII:
+
+- Phone numbers (10+ digits)
+- Email addresses
+- Aadhar numbers (12-digit pattern)
+- PAN numbers (5 letters + 4 digits + 1 letter)
+- Geo addresses (street patterns)
+
+Explicitly **not** redacted: generic `name` fields, canonical item names, location names.
+
+## Screens
+
+| Tab | Purpose |
+|-----|---------|
+| **Plan Today's Shopping** | Dashboard workflow — today view, use-soon signals, and shopping recommendations |
+| **Shopping List** | View / create / manage the active shopping list |
+| **Market Lens: Should I Buy This?** | Camera / voice input → detect → compare vs inventory |
+| **Add Purchase** | Manual purchase recording form with store, price, item details |
+| **Find an Item at Home** | Search + map lookup for likely storage location |
+| **Use Soon / Waste Saver** | Expiring and aging items with priority list |
+| **Price Memory Check** | Historical price observations per item |
+| **Find Item Location** | Storage hierarchy and item count view |
+| **Model Stack** | Active model stack + budget status and candidate catalog |
+| **Agent Trace** | Agent session trace viewer with redaction preview |
+| **Field Notes** | Agent reasoning and decision log |
+
+## Configuration
+
+All settings are pydantic-settings with `SHOPSTACK_` env prefix:
+
+Operational resource guards are documented in **[`Docs/RESOURCE_OPTIMIZATION_POLICY.md`](Docs/RESOURCE_OPTIMIZATION_POLICY.md)**.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SHOPSTACK_DB_PATH` | `data/shopstack.db` | SQLite database file path |
+| `SHOPSTACK_APP_PORT` | `7860` | Gradio server port |
+| `SHOPSTACK_OFF_THE_GRID` | `true` | Use mock providers (no cloud) |
+| `SHOPSTACK_LOCAL_AUTO_UNLOAD` | `true` | Unload local model runtime after each local provider call |
+| `SHOPSTACK_LOCAL_WHISPER_AUTO_UNLOAD` | `true` | Unload local STT model after each transcription |
+| `SHOPSTACK_TRACE_MAX_ROWS` | `2000` | Maximum number of trace rows to retain |
+| `SHOPSTACK_TRACE_TTL_DAYS` | `30` | Delete traces older than this many days |
+| `SHOPSTACK_STT_BACKEND` | `mock` | STT provider selection |
+| `SHOPSTACK_TTS_BACKEND` | `mock` | TTS provider selection |
+| `SHOPSTACK_VISION_BACKEND` | `mock` | Vision provider selection |
+| `SHOPSTACK_OBJECT_DETECTION_BACKEND` | `mock` | Object detection provider |
+| ... per-provider backends default to `mock` |
+
+## Model Catalog
+
+See **[`Docs/MODEL_CATALOG.md`](Docs/MODEL_CATALOG.md)** for the full living model catalog — including downloaded & tested models, parameter budget tracking, runtime backends (MLX, llama.cpp/GGUF, transformers), HF Pro and Modal Labs credit resources, and experiment logs.
+
+The programmatic registry lives in `shopstack/model_registry.py` (16+ entries across STT, TTS, Vision, OCR, Embeddings, and Planner categories).
+
+- **Active / loaded models**: actually selected at runtime.
+- **Candidate models**: documented options available for future activation.
+- **Budget check**: only active/loaded models are counted against the **32B** cap (enforced by `validate_active_model_budget()`).
+
+**Active design constraint:** Total parameter count across all simultaneously active models must not exceed 32 billion. Mock mode shows an active-loaded stack of `0B`.
+
+## Key Design Decisions
+
+- **Single shared schemas file** — models are interconnected and share enums; a single file avoids circular imports.
+- **Provider ABCs named `*Provider`** — `STTProvider`, not `STT`; mock classes named `Mock*Provider`.
+- **PurchaseEvent enriched with per-item fields** — `canonical_name`, `quantity`, `unit`, `total_price` live on the event, not on a separate join table.
+- **PriceObservation defaults** — `observation_date` defaults to `date.today()`.
+- **PII redaction is targeted** — only phone, email, Aadhar, PAN, and address patterns are redacted. Generic `name` keys are preserved.
+- **No auto-purchase or payment scraping** — design-level constraint. ShopStack tells you what to buy, it doesn't buy for you.
+
+## Development
+
+```bash
+uv pip install -e ".[dev]"
+uv run pytest tests/ -v
+uv run pytest benchmarks/ -v -m benchmark
+uv run python app.py
+```
+
+## Deployment
+
+ShopStack can run via Docker or on any of the supported platforms.
+
+### Docker (local)
+
+```bash
+docker compose up --build
+# Open http://localhost:7860
+```
+
+Data persists in a Docker volume (`shopstack_data`).
+
+### Docker (standalone)
+
+```bash
+docker build -t shopstack .
+docker run -p 7860:7860 -v shopstack_data:/app/data shopstack
+```
+
+### Railway
+
+1. Push your repo to GitHub.
+2. Create a new project on [Railway](https://railway.app) → **Deploy from GitHub repo**.
+3. Railway auto-detects `Dockerfile` and `railway.json`.
+4. Add a **Volume** with mount path `/app/data` (1 GB) for SQLite persistence.
+5. (Optional) Set `SHOPSTACK_HF_API_KEY` and `SHOPSTACK_PLANNER_BACKEND=huggingface` for cloud-backed planning.
+
+### Render
+
+1. Push your repo to GitHub.
+2. Create a new **Web Service** on [Render](https://render.com) → **Deploy from Dockerfile**.
+3. Select the **Starter** plan ($7/mo) — required for persistent disk.
+4. Add a **Disk** mount at `/app/data` with 1 GB.
+5. `render.yaml` is auto-detected if you connect via Blueprint.
+
+### Fly.io
+
+```bash
+# Install flyctl first: https://fly.io/docs/hands-on/install-flyctl/
+flyctl launch --dockerfile ./Dockerfile
+flyctl volumes create shopstack_data --region <your-region> --size 1
+flyctl deploy
+```
+
+See `fly.toml` for configuration reference.
+
+## License
+
+MIT

app.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import os
+
+# HF Spaces: ensure DB_PATH defaults to a writable location before
+# shopstack.config instantiates Settings() at module import time.
+os.environ.setdefault("SHOPSTACK_DB_PATH", "shopstack.db")
+
+import gradio as gr
+
+from shopstack.ui.header import header_block
+from shopstack.ui.theme import CSS
+from shopstack.ui.tabs.context import TabContext
+from shopstack.ui.tabs.today import build_today_tab, TodayTabHandles
+from shopstack.ui.tabs.basket import build_basket_tab
+from shopstack.ui.tabs.cookbook import build_cookbook_tab
+from shopstack.ui.tabs.market import build_market_tab
+from shopstack.ui.tabs.reconcile import build_reconcile_tab, ReconcileTabHandles
+from shopstack.ui.tabs.memory import build_memory_tab
+from shopstack.ui.household_settings import build_household_settings
+from shopstack.ui.locale_save import build_locale_save
+from shopstack.ui.pwa_mount import mount_pwa_static
+from shopstack.services.sms_webhook import mount_sms_webhook
+
+from shopstack.app_context import (
+    APP_DESCRIPTION,
+    APP_NAME,
+    current_user_id,
+    db,
+    tools,
+    providers,
+    planner,
+)
+from shopstack.services.i18n import load_locale_preference
+from shopstack.ui.state.household import (
+    household_choices,
+    switch_household_state,
+    show_add_form,
+    hide_add_form,
+    create_household_state,
+)
+# Canonical paths — the re-exports in primitives.py emit
+# DeprecationWarning on first call (see Pass 5 supersession).
+from shopstack.ui.components.js_helpers import (
+    autocomplete_injector_js,
+    url_state_sync_js,
+)
+
+
+def build_app() -> gr.Blocks:
+    """Compose the ShopStack app — pure composition, no business logic.
+
+    Wires up the 6 top-level tabs, the household settings accordion,
+    the locale-save API endpoint, and any app-level HTTP / static
+    mounts. All business logic lives in the sub-modules; this
+    function just glues them together.
+
+    Architecture:
+      * gr.Blocks is the root container.
+      * mount_pwa_static() mounts shopstack/static/ at /static/*
+        so the PWA shell is reachable.
+      * mount_sms_webhook() mounts /api/sms/incoming for inbound
+        SMS / WhatsApp quick-add.
+      * header_block() renders the top header (brand, runtime badge,
+        theme toggle, i18n selector, PWA manifest link, JS).
+      * build_locale_save() adds the hidden i18n persistence endpoint
+        that the header's JS POSTs to.
+      * 6 build_<tab>_tab() calls render the daily product flow.
+      * build_household_settings() renders the workspace admin panel
+        (household switcher + community opt-in + SMS phone registry).
+      * The tail block wires cross-tab event handlers (household
+        switch → Today refresh, location refresh, JS injection).
+    """
+    with gr.Blocks(title=APP_NAME) as app:
+        # App-level bootstrap: PWA static mount + SMS webhook endpoint
+        mount_pwa_static(app)
+        mount_sms_webhook(app)
+
+        # Header: brand title, runtime badge, theme toggle, i18n selector
+        initial_locale = load_locale_preference(current_user_id() or "default_household")
+        gr.HTML(
+            header_block(APP_NAME, APP_DESCRIPTION, current_locale=initial_locale),
+            padding=True,
+        )
+
+        # Hidden i18n persistence endpoint (called by the header's JS)
+        build_locale_save()
+
+        # ── 6-tab daily loop: Home → Recipes → Groceries → While Shopping → At Home → Memory ──
+        with gr.Tabs(elem_classes="tabs", elem_id="main-content") as tabs:
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 1: Home — what matters now?
+            # ═══════════════════════════════════════════════════════════════
+            today_handles: TodayTabHandles = build_today_tab(
+                blocks=app, app=app, ctx=TabContext(),
+            )
+            today_stats = today_handles.today_stats
+            today_soon = today_handles.today_soon
+            today_list = today_handles.today_list
+            today_low = today_handles.today_low
+            today_recent = today_handles.today_recent
+            today_changed = today_handles.today_changed
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 2: Recipes — browse the 30-recipe library
+            # ═══════════════════════════════════════════════════════════════
+            build_cookbook_tab(blocks=app, app=app, ctx=TabContext())
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 3: Groceries — what should I buy / skip / compare?
+            # ═══════════════════════════════════════════════════════════════
+            build_basket_tab(blocks=app, app=app, ctx=TabContext())
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 4: While Shopping — check items before you buy them
+            # ═══════════════════════════════════════════════════════════════
+            build_market_tab(blocks=app, app=app, ctx=TabContext())
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 5: At Home — what actually happened?
+            # ═══════════════════════════════════════════════════════════════
+            reconcile_handles = build_reconcile_tab(blocks=app, app=app, ctx=TabContext())
+            p_location = reconcile_handles.p_location
+            move_dest = reconcile_handles.move_dest
+
+            # ═══════════════════════════════════════════════════════════════
+            # Tab 6: Memory — what did we learn?
+            # ═══════════════════════════════════════════════════════════════
+            build_memory_tab(blocks=app, app=app, ctx=TabContext())
+
+        # Household settings accordion (workspace admin panel)
+        hh = build_household_settings(app)
+        household_dropdown = hh.household_dropdown
+        add_hh_btn = hh.add_hh_btn
+        hh_add_row = hh.hh_add_row
+        hh_name_input = hh.hh_name_input
+        hh_create_btn = hh.hh_create_btn
+        hh_cancel_btn = hh.hh_cancel_btn
+
+        # Refresh dropdown choices on initial load
+        app.load(
+            lambda: gr.update(choices=household_choices(), value=current_user_id()),
+            outputs=household_dropdown,
+        )
+
+        # Wire household dropdown change after all output components are defined
+        household_dropdown.change(
+            switch_household_state,
+            household_dropdown,
+            [household_dropdown, today_stats, today_soon, today_list, today_low, today_recent, today_changed],
+            api_name="switch_household",
+            api_description="Switch active household and refresh dashboard",
+        )
+
+        # Per-render refresh of location-dependent dropdowns.
+        def _refresh_location_choices() -> gr.update:
+            return gr.update(choices=[(l.name, l.location_id) for l in db.get_locations()])
+
+        app.load(_refresh_location_choices, outputs=p_location)
+        app.load(_refresh_location_choices, outputs=move_dest)
+
+        # Post-render JS: inject `autocomplete="off"` into every Gradio
+        # text/number input. Vercel WIG requires this on every form input.
+        app.load(None, js=autocomplete_injector_js())
+        # URL state sync: clicking a tab updates the URL hash, and
+        # opening the app with `#basket` deep-links to the Shopping tab.
+        app.load(None, js=url_state_sync_js())
+
+        # Wire add-household button and form
+        add_hh_btn.click(
+            show_add_form,
+            outputs=hh_add_row,
+            api_name="show_add_household",
+            api_description="Show the add-household form",
+        )
+        hh_cancel_btn.click(
+            hide_add_form,
+            outputs=hh_add_row,
+            api_name="cancel_add_household",
+            api_description="Hide the add-household form without creating",
+        )
+        hh_create_btn.click(
+            create_household_state,
+            hh_name_input,
+            [household_dropdown, hh_add_row, today_stats, today_soon, today_list, today_low, today_recent, today_changed],
+            api_name="create_household",
+            api_description="Create a new household, switch to it, and refresh the dashboard",
+        )
+
+    return app
+
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--port", type=int, default=7860)
+    parser.add_argument("--share", action="store_true")
+    args = parser.parse_args()
+
+    app = build_app()
+    app.launch(server_port=args.port, share=args.share, theme=gr.themes.Base(), css=CSS)

packages.txt

@@ -0,0 +1 @@
+libzbar0

requirements.txt

@@ -0,0 +1,10 @@
+gradio>=5.0,<7.0
+pydantic>=2.0,<3.0
+pydantic-settings>=2.0,<3.0
+huggingface_hub>=0.20
+httpx>=0.25
+pillow>=10.0
+pandas>=2.0
+pydub>=0.25
+pytest>=8.0,<9.0
+pytest-cov>=5.0,<6.0

setup.py

@@ -0,0 +1,40 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="shopstack",
+    version="0.1.0",
+    packages=find_packages(),
+    include_package_data=True,
+    python_requires=">=3.10",
+    install_requires=[
+        "gradio>=5",
+        "pydantic>=2",
+        "pydantic-settings>=2",
+        "huggingface_hub>=0.20",
+        "httpx>=0.25",
+        "pydub",
+        "pillow",
+        "pandas",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=9",
+            "pytest-cov",
+            "pytest-benchmark",
+        ],
+        "cloud": [
+            "openai>=1.0",
+        ],
+        "local": [
+            "llama-cpp-python>=0.3",
+        ],
+        "otel": [
+            "opentelemetry-api>=1.30",
+            "opentelemetry-sdk>=1.30",
+            "opentelemetry-exporter-otlp-proto-grpc>=1.30",
+        ],
+        "eval": [
+            "ruff>=0.9",
+        ],
+    },
+)

shopstack/_legacy_decisions.py

@@ -0,0 +1,88 @@
+"""DB-aware render wrappers for decision dashboard cards.
+
+These functions combine data fetching (from Database) with HTML rendering
+(from ui.renderers.decision_cards). They exist here because the decisions
+package cannot import from UI without creating circular imports.
+
+New code should call renderers directly with pre-fetched data rather than
+using these wrappers.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date
+from typing import Any
+
+from shopstack.persistence.database import Database
+
+logger = logging.getLogger(__name__)
+
+
+# --- Render wrappers (backward-compatible with old db-based signatures) ---
+
+
+def render_market_basket(ds) -> str:
+    from shopstack.ui.renderers.decision_cards import render_market_basket
+    return render_market_basket(ds)
+
+
+def render_inventory_overview(all_inv: list[Any]) -> str:
+    from shopstack.ui.renderers.decision_cards import render_inventory_overview
+    return render_inventory_overview(all_inv)
+
+
+def render_my_list_panel(ds, active_list: Any) -> str:
+    from shopstack.ui.renderers.decision_cards import render_my_list_panel
+    return render_my_list_panel(ds, active_list)
+
+
+def render_compare_panel(ds) -> str:
+    from shopstack.ui.renderers.decision_cards import render_compare_panel
+    return render_compare_panel(ds)
+
+
+def render_decision_panel(ds) -> str:
+    from shopstack.ui.renderers.decision_cards import render_decision_panel
+    return render_decision_panel(ds)
+
+
+def render_what_changed(db: Database) -> str:
+    from shopstack.ui.renderers.decision_cards import render_what_changed
+    purchases = db.get_purchase_events(limit=5)
+    traces = db.get_traces(limit=5)
+    return render_what_changed(purchases, traces)
+
+
+def render_cadence_insights(db: Database) -> str:
+    from shopstack.decisions import detect_purchase_cadence
+    from shopstack.ui.renderers.decision_cards import render_cadence_insights
+    cadence = detect_purchase_cadence(db)
+    return render_cadence_insights(cadence)
+
+
+def render_waste_warnings(db: Database) -> str:
+    from shopstack.decisions import detect_waste_patterns
+    from shopstack.ui.renderers.decision_cards import render_waste_warnings
+    signals = detect_waste_patterns(db)
+    return render_waste_warnings(signals)
+
+
+def render_swiggy_soldout_warning(shopping_list_names: list[str]) -> str:
+    from shopstack.decisions import check_swiggy_availability
+    from shopstack.ui.renderers.decision_cards import render_swiggy_soldout_warning
+    avail = check_swiggy_availability(shopping_list_names)
+    return render_swiggy_soldout_warning(avail)
+
+
+def render_needs_confirmation(db: Database) -> str:
+    from shopstack.ui.renderers.decision_cards import render_needs_confirmation
+    all_inv = db.get_inventory()
+    uncertain = [
+        lot for lot in all_inv
+        if lot.status == "active" and lot.quantity > 0 and (
+            not lot.purchase_date
+            or (date.today() - lot.purchase_date).days > 14
+        )
+    ]
+    return render_needs_confirmation(uncertain)

shopstack/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

shopstack/app_context.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from shopstack.config import settings
+from shopstack.model_registry import get_registry
+from shopstack.module_registry import (
+    ModuleMetadata,
+    get_all as get_all_modules,
+    navigation as _build_navigation,
+    summary_table as _build_summary,
+)
+from shopstack.persistence.database import Database
+from shopstack.planner.engine import PlannerEngine
+from shopstack.providers.registry import ProviderRegistry
+from shopstack.tools.registry import ToolRegistry
+
+# ── Shared product constants (single source of truth) ──────────────
+# These derive from config but are exported here so every UI surface
+# imports from one place instead of hardcoding copy.
+APP_NAME: str = settings.app_name
+APP_DESCRIPTION: str = settings.app_description
+
+# ── Module registry (module metadata + lookup helpers) ──────────────
+# See shopstack/module_registry.py for all module definitions.
+MODULES: list[ModuleMetadata] = get_all_modules()
+MODULE_SUMMARY: list[dict[str, str]] = _build_summary()
+NAV_ENTRIES: list[tuple[str, str, str]] = _build_navigation()
+
+# ── Core singletons ─────────────────────────────────────────────────
+db = Database(settings.db_path)
+
+# Resolve active household from stored config, so every DB operation
+# is scoped to the current household automatically.
+_household_id = db.active_household_id
+
+providers = ProviderRegistry(settings)
+# Wire embeddings provider into ToolRegistry for semantic search fallback.
+# The embedding provider is lazy-resolved from ProviderRegistry; if BGE-M3
+# or sentence-transformers is unavailable, semantic_find_item falls back to
+# prefix search automatically.
+tools = ToolRegistry(db, embedding_provider=providers.embeddings)
+planner = PlannerEngine(db, tools, providers)
+model_registry = get_registry()
+
+
+# ── Service singletons (wired from app_context) ────────────────────
+from shopstack.services.trace import TraceService  # noqa: E402 — circular import
+
+_trace_service: TraceService | None = None
+
+
+def get_trace_service() -> TraceService:
+    global _trace_service
+    if _trace_service is None:
+        _trace_service = TraceService(db)
+    return _trace_service
+
+
+def current_user_id() -> str:
+    """Return the currently active household/user ID for DB scoping.
+
+    Screen builders should call this and pass the result as ``user_id``
+    to every ``db.*()`` call that accepts the parameter. This ensures
+    all inventory, shopping list, and trace queries are scoped to the
+    active household.
+    """
+    return db.active_household_id
+
+
+def switch_household(household_id: str) -> bool:
+    """Switch the active household. Returns True if successful."""
+    if not household_id:
+        return False
+    # Verify the household exists
+    households = db.list_households()
+    if not any(h["household_id"] == household_id for h in households):
+        return False
+    db.active_household_id = household_id
+    return True
+
+
+def list_households() -> list[dict[str, str]]:
+    """List all registered households."""
+    return db.list_households()
+
+
+def add_household(household_id: str, name: str) -> bool:
+    """Register a new household."""
+    return db.add_household(household_id, name)
+
+
+def runtime_label() -> str:
+    """Return a human-readable label describing the current provider runtime.
+
+    Uses the provider registry to determine whether real AI backends are loaded
+    or the app is running in mock mode. Safe to call at import time.
+    """
+    try:
+        runtime = providers.get_runtime_diagnostics()
+        loaded_real = [
+            r for r in runtime.providers
+            if getattr(r, "loaded", False) and getattr(r, "backend", "") != "mock"
+        ]
+        return "Local runtime" if loaded_real else "Local mock mode"
+    except Exception:
+        return "Local runtime"

shopstack/basket/__init__.py

@@ -0,0 +1,4 @@
+from shopstack.basket.models import BasketCandidate, BasketItem
+from shopstack.basket.service import optimize_baskets
+
+__all__ = ["BasketCandidate", "BasketItem", "optimize_baskets"]

shopstack/basket/constraints.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+from typing import Any
+from shopstack.basket.models import BasketCandidate
+
+def apply_constraints(candidate: BasketCandidate, rules: dict[str, Any]) -> BasketCandidate:
+    """
+    Apply hard constraints to a candidate basket.
+    Rules could contain:
+      - max_cost: float
+      - require_fresh: bool
+      - avoid_ads: bool
+    """
+    
+    # Example logic for constraints
+    if rules.get("max_cost") and candidate.total_cost > rules["max_cost"]:
+        candidate.overall_score -= 1000  # heavy penalty
+
+    if rules.get("require_fresh"):
+        for item in candidate.items:
+            if item.freshness == "stale":
+                candidate.overall_score -= 50
+                
+    if rules.get("avoid_ads"):
+        for item in candidate.items:
+            if item.is_ad:
+                candidate.overall_score -= 20
+                
+    return candidate

shopstack/basket/models.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+from pydantic import BaseModel, Field
+
+class BasketItem(BaseModel):
+    canonical_name: str
+    display_name: str
+    source: str
+    quantity: float
+    price_inr: float
+    price_per_kg: float | None = None
+    freshness: str = "unknown"
+    waste_risk: str = "unknown"
+    is_ad: bool = False
+    is_upgrade: bool = False
+    price_status: str = "known"
+    notes: str | None = None
+
+class BasketCandidate(BaseModel):
+    id: str = ""
+    items: list[BasketItem] = Field(default_factory=list)
+    source_name: str  # "swiggy", "zepto", "dmart", or "mixed"
+    total_cost: float = 0.0
+    
+    # Components of the rank
+    usefulness_score: float = 0.0
+    cost_score: float = 0.0
+    freshness_score: float = 0.0
+    waste_risk_score: float = 0.0
+    preference_score: float = 0.0
+    
+    overall_score: float = 0.0
+    missing_items: list[str] = Field(default_factory=list)
+    
+    @property
+    def item_count(self) -> int:
+        return len(self.items)

shopstack/basket/scoring.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from shopstack.basket.models import BasketCandidate
+
+def calculate_scores(candidate: BasketCandidate) -> BasketCandidate:
+    # Usefulness: based on proportion of found items vs missing items
+    total_wanted = candidate.item_count + len(candidate.missing_items)
+    if total_wanted > 0:
+        candidate.usefulness_score = (candidate.item_count / total_wanted) * 100
+    else:
+        candidate.usefulness_score = 0.0
+
+    # Cost score: Inverse of cost (higher is better). Just a relative heuristic.
+    if candidate.total_cost > 0:
+        candidate.cost_score = 10000.0 / candidate.total_cost  # Arbitrary scaling
+    else:
+        candidate.cost_score = 0.0
+
+    # Freshness score: penalty for stale items
+    stale_count = sum(1 for i in candidate.items if i.freshness == "stale")
+    candidate.freshness_score = max(0, 100 - (stale_count * 20))
+
+    # Waste risk score: penalty for high waste items
+    high_waste = sum(1 for i in candidate.items if i.waste_risk == "high")
+    candidate.waste_risk_score = max(0, 100 - (high_waste * 15))
+
+    # Preference score: penalize sponsored ads
+    ads = sum(1 for i in candidate.items if i.is_ad)
+    candidate.preference_score = max(0, 100 - (ads * 10))
+
+    # Overall score: weighted sum
+    candidate.overall_score = (
+        candidate.usefulness_score * 0.4 +
+        candidate.cost_score * 0.3 +
+        candidate.freshness_score * 0.1 +
+        candidate.waste_risk_score * 0.1 +
+        candidate.preference_score * 0.1
+    )
+    return candidate

shopstack/basket/service.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import logging
+
+from shopstack.basket.models import BasketCandidate, BasketItem
+from shopstack.basket.scoring import calculate_scores
+from shopstack.schemas.models import DecisionSet
+
+logger = logging.getLogger(__name__)
+
+
+def _prefer_freshness(
+    source_id: str,
+    snapshot,
+    source_registry,
+) -> str:
+    """Resolve freshness from source registry metadata when available."""
+    if source_registry is not None:
+        try:
+            status = source_registry.freshness_of(source_id)
+            if isinstance(status, dict) and "is_stale" in status:
+                return "stale" if bool(status.get("is_stale")) else "fresh"
+        except Exception as exc:  # pragma: no cover - defensive compatibility
+            logger.debug("Freshness lookup failed for %s: %s", source_id, exc)
+
+    if getattr(snapshot, "is_stale", False):
+        return "stale"
+    return "fresh"
+
+
+def _build_decision_only_basket(decision_set: DecisionSet) -> list[BasketCandidate]:
+    """Build a useful fallback basket without any live snapshot data."""
+    if not decision_set.buy:
+        return []
+
+    candidate = BasketCandidate(source_name="decision_only", id="basket_decision_only")
+    for decision in decision_set.buy:
+        candidate.items.append(
+            BasketItem(
+                canonical_name=decision.canonical_name,
+                display_name=decision.display_name,
+                source="decision_only",
+                quantity=float(getattr(decision, "requested_quantity", 1.0)),
+                price_inr=0.0,
+                price_status="unavailable",
+                notes="No active market snapshot loaded — price will be local list estimate.",
+                freshness="unknown",
+                waste_risk=getattr(decision, "waste_risk", "unknown"),
+                is_ad=False,
+                is_upgrade=False,
+            )
+        )
+    candidate.missing_items = []
+    calculate_scores(candidate)
+    return [candidate]
+
+
+def _load_fallback_snapshot(source_registry) -> dict[str, object]:
+    """Try a deterministic single-source fallback for demo stability."""
+    snapshots: dict[str, object] = {}
+    if source_registry is None:
+        return snapshots
+
+    try:
+        registered = list(source_registry.registered())
+    except Exception:
+        registered = []
+
+    for source_id in ("swiggy", "blinkit", "zepto", "dmart"):
+        if source_id not in registered:
+            continue
+        try:
+            snapshot = source_registry.latest(source_id)
+            if snapshot is None:
+                snapshot = source_registry.load(source_id)
+            if snapshot is not None and getattr(snapshot, "normalized_records", None):
+                snapshots[source_id] = snapshot
+                break
+        except Exception as exc:  # pragma: no cover - data adapter failures
+            logger.debug("Fallback snapshot load failed for %s: %s", source_id, exc)
+            continue
+
+    return snapshots
+
+
+def optimize_baskets(
+    decision_set: DecisionSet,
+    source_registry=None,
+) -> list[BasketCandidate]:
+    """Generate and rank basket candidates based on buy decisions."""
+    buy_items = decision_set.buy
+    if not buy_items:
+        return []
+
+    # Map canonical names to market records across all sources
+    all_snapshots: dict[str, object] = {}
+    if source_registry:
+        try:
+            all_snapshots = source_registry.all_snapshots()
+        except Exception:
+            all_snapshots = {}
+
+    if not all_snapshots:
+        all_snapshots = _load_fallback_snapshot(source_registry)
+    if not all_snapshots:
+        # Deterministic UX: never return empty for non-empty shopping lists.
+        return _build_decision_only_basket(decision_set)
+
+    # If source snapshots exist but contain no market rows, still avoid hard-empty.
+    if not any(snapshot.normalized_records for snapshot in all_snapshots.values()):
+        return _build_decision_only_basket(decision_set)
+
+    candidates: list[BasketCandidate] = []
+    
+    # 1. Generate a single-source basket for each source
+    for source_id, snapshot in all_snapshots.items():
+        if not snapshot or not snapshot.normalized_records:
+            continue
+        
+        candidate = BasketCandidate(source_name=source_id, id=f"basket_{source_id}")
+        source_records = {r.canonical_name: r for r in snapshot.normalized_records if r.is_available}
+        source_freshness = _prefer_freshness(source_id, snapshot, source_registry)
+        
+        total_cost = 0.0
+        missing = []
+        
+        for decision in buy_items:
+            cname = decision.canonical_name
+            record = source_records.get(cname)
+            if record:
+                item = BasketItem(
+                    canonical_name=cname,
+                    display_name=decision.display_name,
+                    source=source_id,
+                    quantity=1.0,  # default
+                    price_inr=record.price_inr,
+                    price_per_kg=record.price_per_kg,
+                    freshness=source_freshness,
+                    waste_risk=decision.waste_risk,
+                    is_ad=getattr(record, "is_ad", False),
+                    is_upgrade=getattr(record, "is_upgrade", False),
+                    notes=record.raw_name if record.is_ad or record.is_upgrade else None,
+                )
+                candidate.items.append(item)
+                total_cost += item.price_inr
+            else:
+                missing.append(cname)
+                
+        candidate.total_cost = total_cost
+        candidate.missing_items = missing
+        if candidate.items or candidate.missing_items:
+            calculate_scores(candidate)
+            candidates.append(candidate)
+            
+    # 2. Generate a mixed (cheapest overall) basket
+    mixed_candidate = BasketCandidate(source_name="mixed", id="basket_mixed")
+    mixed_cost = 0.0
+    mixed_missing = []
+    
+    for decision in buy_items:
+        cname = decision.canonical_name
+        best_record = None
+        best_source = None
+        
+        for source_id, snapshot in all_snapshots.items():
+            if not snapshot or not snapshot.normalized_records:
+                continue
+            for r in snapshot.normalized_records:
+                if r.canonical_name == cname and r.is_available:
+                    if best_record is None or r.price_inr < best_record.price_inr:
+                        best_record = r
+                        best_source = source_id
+                        
+        if best_record and best_source:
+            snapshot = all_snapshots[best_source]
+            source_freshness = _prefer_freshness(best_source, snapshot, source_registry)
+            mixed_candidate.items.append(
+                BasketItem(
+                    canonical_name=cname,
+                    display_name=decision.display_name,
+                    source=best_source,
+                    quantity=1.0,
+                    price_inr=best_record.price_inr,
+                    price_per_kg=best_record.price_per_kg,
+                    freshness=source_freshness,
+                    waste_risk=decision.waste_risk,
+                    is_ad=getattr(best_record, "is_ad", False),
+                    is_upgrade=getattr(best_record, "is_upgrade", False),
+                    notes=best_record.raw_name if best_record.is_ad or best_record.is_upgrade else None,
+                )
+            )
+            mixed_cost += best_record.price_inr
+        else:
+            mixed_missing.append(cname)
+            
+    mixed_candidate.total_cost = mixed_cost
+    mixed_candidate.missing_items = mixed_missing
+    if mixed_candidate.items or mixed_candidate.missing_items:
+        calculate_scores(mixed_candidate)
+        candidates.append(mixed_candidate)
+        
+    # Sort by overall score descending
+    candidates.sort(key=lambda c: c.overall_score, reverse=True)
+    
+    return candidates

shopstack/catalog/models.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+class WasteRisk(str, Enum):
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+class ProductCategory(str, Enum):
+    VEGETABLES = "vegetables"
+    FRUITS = "fruits"
+    DAIRY = "dairy"
+    MEAT = "meat"
+    GROCERY = "grocery"
+    HERBS_AND_SPICES = "herbs_and_spices"
+    BEVERAGES = "beverages"
+    SNACKS = "snacks"
+    OTHER = "other"
+
+@dataclass
+class ProductCatalogEntry:
+    canonical_id: str
+    canonical_name: str
+    aliases: List[str] = field(default_factory=list)
+    category: ProductCategory = ProductCategory.OTHER
+    shelf_life_days: Optional[int] = None
+    waste_risk: WasteRisk = WasteRisk.MEDIUM
+    storage_hints: str = ""
+    unit_preference: str = "pieces"
+    variant_family: str = ""
+    premium_claims: List[str] = field(default_factory=list)
+    substitute_groups: List[str] = field(default_factory=list)

shopstack/catalog/service.py

@@ -0,0 +1,22 @@
+from typing import Dict, List, Optional
+from shopstack.catalog.models import ProductCatalogEntry
+
+class CatalogService:
+    def __init__(self):
+        self._catalog: Dict[str, ProductCatalogEntry] = {}
+        self._alias_map: Dict[str, str] = {}
+        
+    def add_entry(self, entry: ProductCatalogEntry):
+        self._catalog[entry.canonical_id] = entry
+        self._alias_map[entry.canonical_name.lower()] = entry.canonical_id
+        for alias in entry.aliases:
+            self._alias_map[alias.lower()] = entry.canonical_id
+            
+    def get_by_canonical_id(self, canonical_id: str) -> Optional[ProductCatalogEntry]:
+        return self._catalog.get(canonical_id)
+        
+    def get_by_name(self, name: str) -> Optional[ProductCatalogEntry]:
+        canonical_id = self._alias_map.get(name.lower().strip())
+        if canonical_id:
+            return self._catalog.get(canonical_id)
+        return None

shopstack/config.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    app_name: str = "ShopStack"
+    app_description: str = "Shopping intelligence platform: know what you have, what to buy, what to skip, and where to buy from."
+    app_version: str = "0.1.0"
+    debug: bool = True
+
+    ui_mode: str = "consumer"  # "consumer" | "developer" — gates developer-facing UI elements
+
+    off_the_grid: bool = True
+    default_household_user_id: str = "default_household"
+    app_port: int = 7860
+    db_path: str = str(Path(__file__).resolve().parent.parent / "data" / "shopstack.db")
+    data_dir: str = str(Path(__file__).resolve().parent.parent / "data")
+
+    openai_api_key: str = ""
+    hf_api_key: str = ""
+
+    local_model_dir: str = ""
+    local_model_repo: str = "unsloth/Llama-3.2-3B-Instruct-GGUF"
+    local_model_file: str = "Llama-3.2-3B-Instruct-Q4_K_M.gguf"
+    local_mlx_model: str = "mlx-community/Ministral-8B-Instruct-2410-4bit"
+    local_auto_download: bool = True
+
+    local_whisper_size: str = "tiny"
+    local_auto_unload: bool = True
+    local_whisper_auto_unload: bool = True
+    model_stack: str = "default"
+
+    trace_max_rows: int = 2000
+    trace_ttl_days: int = 30
+
+    cost_budget_limit: float = 1.00
+
+    planner_backend: str = "local"
+    stt_backend: str = "sensevoice"
+    tts_backend: str = "kokoro"
+    vision_backend: str = "qwen3vl"
+    ocr_backend: str = "tesseract"
+    segmentation_backend: str = "birefnet"
+    grounding_backend: str = "grounding_dino"
+    image_gen_backend: str = "svg"
+    embeddings_backend: str = "nomic"
+    tool_call_parser_backend: str = "minicpm5"
+    planner_compact_tools: bool = False  # Use compact type-shorthand tool descriptions (~90% accuracy vs ~50%)
+    planner_allow_writes: bool = False
+
+    model_config = {"env_file": ".env", "env_prefix": "SHOPSTACK_", "extra": "ignore"}
+
+    def __init__(self, **values):
+        super().__init__(**values)
+        # Backward-compatibility shim for the old environment variable name.
+        # Prefer new SHOPSTACK_DB_PATH when explicitly set.
+        legacy_db_path = os.getenv("SHOPSTACK_DATABASE_PATH")
+        if legacy_db_path and "db_path" not in self.model_dump(exclude_unset=True):
+            self.db_path = legacy_db_path
+
+        self._apply_model_stack_preset()
+
+    def _apply_model_stack_preset(self) -> None:
+        """Overlay a named model stack preset onto unset provider backends."""
+        preset = self.model_stack.strip().lower()
+        if preset != "openbmb_local":
+            return
+
+        explicit_fields = set(self.model_dump(exclude_unset=True).keys())
+        preset_backends = {
+            "planner_backend": "minicpm5",
+            "ocr_backend": "glm_ocr",  # overrides default tesseract for vision-native OCR
+        }
+        # vision_backend=qwen3vl, segmentation_backend=birefnet, embeddings_backend=nomic,
+        # and most other backends are now the default — no longer need explicit preset overrides.
+        for field_name, backend in preset_backends.items():
+            if field_name not in explicit_fields:
+                setattr(self, field_name, backend)
+
+    @property
+    def provider_backends(self) -> dict[str, str]:
+        """Backward-compatible provider backend map.
+
+        Canonical configuration is in *_backend fields (for example
+        stt_backend), but existing callers may still read provider_backends.
+        """
+        backends = {
+            "stt": self.stt_backend,
+            "tts": self.tts_backend,
+            "vision": self.vision_backend,
+            "object_detection": self.vision_backend,
+            "grounding": self.grounding_backend,
+            "segmentation": self.segmentation_backend,
+            "ocr": self.ocr_backend,
+            "planner": self.planner_backend,
+            "tool_call_parser": self.tool_call_parser_backend,
+            "embeddings": self.embeddings_backend,
+            "image_edit": self.image_gen_backend,
+            "image_gen": self.image_gen_backend,
+        }
+        return backends
+
+    @property
+    def database_path(self) -> str:
+        """Backward-compatible alias for legacy callers."""
+        return self.db_path
+
+
+settings = Settings()

shopstack/cost_tracker.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+MODEL_PRICING: dict[str, dict[str, float | str]] = {
+    "gpt-4o": {"input_per_mtok": 2.50, "output_per_mtok": 10.00},
+    "gpt-4o-mini": {"input_per_mtok": 0.15, "output_per_mtok": 0.60},
+    "text-embedding-3-small": {"input_per_mtok": 0.02, "output_per_mtok": 0.02},
+    "whisper-1": {"input_per_mtok": 0.0, "output_per_mtok": 0.0, "note": "priced per audio minute"},
+    "microsoft/Phi-3-mini-4k-instruct": {"input_per_mtok": 0.0, "output_per_mtok": 0.0, "note": "HF inference may bill separately"},
+    "mlx-community/Llama-3.2-3B-Instruct-4bit": {"input_per_mtok": 0.0, "output_per_mtok": 0.0, "note": "local - free"},
+    "unsloth/Llama-3.2-3B-Instruct-GGUF": {"input_per_mtok": 0.0, "output_per_mtok": 0.0, "note": "local - free"},
+    "mock": {"input_per_mtok": 0.0, "output_per_mtok": 0.0, "note": "mock - free"},
+}
+
+INPUT_TIER_THRESHOLDS: list[tuple[int, str]] = [
+    (300, "haiku"),
+    (1000, "sonnet"),
+]
+
+MODEL_TIER_MAP: dict[str, str] = {
+    "gpt-4o-mini": "haiku",
+    "gpt-4o": "sonnet",
+    "microsoft/Phi-3-mini-4k-instruct": "haiku",
+    "mlx-community/Llama-3.2-3B-Instruct-4bit": "local",
+    "unsloth/Llama-3.2-3B-Instruct-GGUF": "local",
+    "mock": "mock",
+}
+
+TIER_COST_MULTIPLIER: dict[str, float] = {
+    "haiku": 1.0,
+    "sonnet": 4.0,
+    "local": 0.0,
+    "mock": 0.0,
+}
+
+
+def estimate_model_tier(text_length: int, item_count: int = 0) -> str:
+    for threshold, tier in INPUT_TIER_THRESHOLDS:
+        if text_length < threshold and item_count < 30:
+            return tier
+    return "sonnet"
+
+
+def estimate_cost_usd(
+    model_key: str,
+    input_tokens: int,
+    output_tokens: int,
+) -> float:
+    pricing = MODEL_PRICING.get(model_key)
+    if not pricing:
+        return 0.0
+    input_rate = pricing.get("input_per_mtok", 0)
+    output_rate = pricing.get("output_per_mtok", 0)
+    input_cost = (input_tokens / 1_000_000) * (input_rate if isinstance(input_rate, (int, float)) else 0.0)
+    output_cost = (output_tokens / 1_000_000) * (output_rate if isinstance(output_rate, (int, float)) else 0.0)
+    return round(input_cost + output_cost, 6)
+
+
+@dataclass(frozen=True)
+class CostRecord:
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+    tier: str
+    latency_ms: float | None = None
+
+
+@dataclass(frozen=True)
+class CostTracker:
+    budget_limit: float = 1.00
+    records: tuple[CostRecord, ...] = ()
+
+    def add(self, record: CostRecord) -> CostTracker:
+        return CostTracker(
+            budget_limit=self.budget_limit,
+            records=(*self.records, record),
+        )
+
+    @property
+    def total_cost(self) -> float:
+        return sum(r.cost_usd for r in self.records)
+
+    @property
+    def total_input_tokens(self) -> int:
+        return sum(r.input_tokens for r in self.records)
+
+    @property
+    def total_output_tokens(self) -> int:
+        return sum(r.output_tokens for r in self.records)
+
+    @property
+    def over_budget(self) -> bool:
+        return self.total_cost > self.budget_limit
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "total_cost": self.total_cost,
+            "total_input_tokens": self.total_input_tokens,
+            "total_output_tokens": self.total_output_tokens,
+            "call_count": len(self.records),
+            "budget_limit": self.budget_limit,
+            "over_budget": self.over_budget,
+            "records": [
+                {
+                    "model": r.model,
+                    "input_tokens": r.input_tokens,
+                    "output_tokens": r.output_tokens,
+                    "cost_usd": r.cost_usd,
+                    "tier": r.tier,
+                    "latency_ms": r.latency_ms,
+                }
+                for r in self.records
+            ],
+        }

shopstack/data/seed_demo.py

@@ -0,0 +1,79 @@
+"""Seed demo inventory data for developer walkthroughs and testing.
+
+This module lives in shopstack.data so the screen module (inventory.py)
+doesn't carry a large static data array in its module body.
+"""
+
+DEMO_SEED_INVENTORY = [
+    {
+        "canonical_name": "milk",
+        "display_name": "Milk",
+        "quantity": 2.0,
+        "unit": "liter",
+        "price": 74.0,
+        "store": "local milk booth",
+        "location": "fridge",
+        "category": "dairy",
+        "expiry": 7,
+    },
+    {
+        "canonical_name": "rice",
+        "display_name": "Basmati Rice",
+        "quantity": 5.0,
+        "unit": "kg",
+        "price": 410.0,
+        "store": "Big Bazaar",
+        "location": "pantry",
+        "category": "grains",
+    },
+    {
+        "canonical_name": "eggs",
+        "display_name": "Eggs",
+        "quantity": 12.0,
+        "unit": "pieces",
+        "price": 96.0,
+        "store": "Morning Eggstop",
+        "location": "fridge_top",
+        "category": "protein",
+    },
+    {
+        "canonical_name": "onion",
+        "display_name": "Onion",
+        "quantity": 1.5,
+        "unit": "kg",
+        "price": 32.0,
+        "store": "Local Vendor",
+        "location": "pantry_mid",
+        "category": "vegetable",
+    },
+    {
+        "canonical_name": "toothpaste",
+        "display_name": "Toothpaste",
+        "quantity": 1.0,
+        "unit": "unit",
+        "price": 129.0,
+        "store": "Apna Store",
+        "location": "bathroom_cabinet",
+        "category": "personal care",
+    },
+    {
+        "canonical_name": "olive oil",
+        "display_name": "Olive Oil",
+        "quantity": 1.0,
+        "unit": "L",
+        "price": 690.0,
+        "store": "Supermart",
+        "location": "pantry_mid",
+        "category": "cooking",
+    },
+    {
+        "canonical_name": "curd",
+        "display_name": "Curd",
+        "quantity": 0.5,
+        "unit": "kg",
+        "price": 48.0,
+        "store": "Fresh Dairy",
+        "location": "fridge",
+        "category": "dairy",
+    },
+]

shopstack/decisions/__init__.py

@@ -0,0 +1,84 @@
+from shopstack.decisions.types import (
+    Decision,
+    DECISION_COLORS,
+    DECISION_ICONS,
+    ACTION_MAP,
+)
+from shopstack.schemas.models import (
+    DecisionEvidence,
+    DecisionResult,
+    DecisionSet,
+    DecisionWarning,
+    FreshnessStatus,
+)
+from shopstack.decisions.rules import (
+    classify_all,
+    _classify,
+    _get_produce_meta,
+    detect_purchase_cadence,
+    detect_waste_patterns,
+    check_swiggy_availability,
+)
+
+_RENDER_NAMES = {
+    "render_market_basket",
+    "render_inventory_overview",
+    "render_my_list_panel",
+    "render_compare_panel",
+    "render_decision_panel",
+}
+_LEGACY_NAMES = {
+    "render_what_changed",
+    "render_cadence_insights",
+    "render_waste_warnings",
+    "render_swiggy_soldout_warning",
+    "render_needs_confirmation",
+}
+
+
+def __getattr__(name: str):
+    """Lazy re-exports for backward-compatible render wrappers.
+
+    New code should import directly from shopstack.ui.renderers.decision_cards
+    or shopstack._legacy_decisions.
+
+    This __getattr__ avoids a circular import: decisions → renderers → decisions
+    that would otherwise crash when any code path triggers both packages.
+    """
+    if name in _RENDER_NAMES:
+        import shopstack.ui.renderers as _r
+        return getattr(_r, name)
+    if name in _LEGACY_NAMES:
+        import shopstack._legacy_decisions as _l
+        return getattr(_l, name)
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+__all__ = [
+    "Decision",
+    "DECISION_COLORS",
+    "DECISION_ICONS",
+    "ACTION_MAP",
+    "DecisionEvidence",
+    "DecisionResult",
+    "DecisionSet",
+    "DecisionWarning",
+    "FreshnessStatus",
+    "classify_all",
+    "_classify",
+    "_get_produce_meta",
+    "detect_purchase_cadence",
+    "detect_waste_patterns",
+    "check_swiggy_availability",
+    "render_market_basket",
+    "render_inventory_overview",
+    "render_my_list_panel",
+    "render_compare_panel",
+    "render_decision_panel",
+    "render_what_changed",
+    "render_cadence_insights",
+    "render_waste_warnings",
+    "render_swiggy_soldout_warning",
+    "render_needs_confirmation",
+]

shopstack/decisions/rules.py

@@ -0,0 +1,733 @@
+"""Decision rules — classification logic for household shopping decisions.
+
+This module computes buy / skip / use-soon / optional / compare / wait
+decisions from inventory state, shopping list, and market signals. Pure logic —
+no HTML rendering, no database access except through passed-in interfaces.
+
+Every decision produces a DecisionResult (from shopstack.schemas.models).
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import date, timedelta
+from typing import Any
+
+from shopstack.schemas.models import (
+    DecisionEvidence,
+    DecisionResult,
+    DecisionSet,
+    DecisionWarning,
+)
+from shopstack.decisions.types import Decision, ACTION_MAP
+from shopstack.persistence.database import Database
+
+logger = logging.getLogger(__name__)
+
+_LOW_STOCK_THRESHOLD = 0.5
+_USE_SOON_DAYS = 3
+_RECENT_PURCHASE_DAYS = 2
+
+
+def _get_use_soon(inventory: Any, days: int, user_id: str = "") -> dict[str, Any]:
+    """Call get_use_soon (InventoryRepo) or get_use_soon_items (ToolRegistry)."""
+    if hasattr(inventory, "get_use_soon"):
+        return inventory.get_use_soon(days=days, user_id=user_id)
+    return inventory.get_use_soon_items(days=days, user_id=user_id)
+
+
+def classify_all(
+    db: Database,
+    inventory: Any,
+    market_snapshot=None,
+    source_registry: Any = None,
+    user_id: str = "",
+) -> DecisionSet:
+    from shopstack.services.preference import PreferenceService
+    pref_service = PreferenceService(db)
+    uid = user_id
+    staples = set(pref_service.get_staples(user_id=uid))
+    disliked = set(pref_service.get_disliked(user_id=uid))
+
+    active_inv = [lot for lot in db.get_inventory(user_id=uid) if lot.status == "active"]
+    use_soon_items = _get_use_soon(inventory, _USE_SOON_DAYS, user_id=uid).get("items", [])
+    active_list = db.get_active_shopping_list(user_id=uid)
+    purchases = db.get_purchase_events(limit=50, user_id=uid)
+    recent_dates: set[date] = set()
+    for p in purchases:
+        try:
+            pdate = p.timestamp.date() if hasattr(p.timestamp, "date") else p.timestamp
+            if pdate and pdate >= date.today() - timedelta(days=_RECENT_PURCHASE_DAYS):
+                recent_dates.add(pdate)
+        except Exception:
+            pass
+
+    use_soon_names = {item.get("canonical_name", "") for item in use_soon_items}
+    list_names: set[str] = set()
+    if active_list and active_list.items:
+        list_names = {item.canonical_name for item in active_list.items if item.status in ("pending", "seen")}
+
+    market_by_canonical: dict[str, Any] = {}
+    market_evidence_map: dict[str, Any] = {}
+
+    # Build market data from single snapshot or multi-source registry
+    _multi_source_market_data(market_snapshot, source_registry, market_by_canonical, market_evidence_map)
+
+    # Purchase cadence — used for predictive restock recommendations
+    cadence_data = detect_purchase_cadence(db, user_id=uid)
+
+    seen: set[str] = set()
+    decisions: list[DecisionResult] = []
+
+    # Import decision engine services locally to avoid circular imports
+    from shopstack.services.freshness import FreshnessReport
+    from shopstack.services.decision_engine import should_buy, should_skip, use_soon
+
+    for lot in active_inv:
+        cname = lot.canonical_name
+        if cname in seen:
+            continue
+        seen.add(cname)
+
+        meta = _get_produce_meta(cname)
+        market = market_by_canonical.get(cname)
+
+        use_soon_match = cname in use_soon_names
+        low_stock = lot.quantity <= _LOW_STOCK_THRESHOLD or lot.status == "low"
+        on_list = cname in list_names
+        recently_bought = lot.purchase_date and lot.purchase_date in recent_dates
+        is_staple = cname in staples
+        is_disliked = cname in disliked
+
+        # Derive freshness report for the market record
+        fr = None
+        if market:
+            evidence_val = market_evidence_map.get(cname, {})
+            cap_at = evidence_val.get("captured_at")
+            if cap_at:
+                if not isinstance(cap_at, str):
+                    cap_at = getattr(cap_at, "isoformat", lambda: str(cap_at))()
+                fr = FreshnessReport(
+                    status="stale" if evidence_val.get("is_stale") else "fresh",
+                    age_days=evidence_val.get("age_days"),
+                    label="",
+                    captured_at=cap_at,
+                    is_stale=bool(evidence_val.get("is_stale")),
+                    warning="",
+                )
+
+        decision_res = None
+
+        if use_soon_match:
+            decision_res = use_soon(
+                canonical_name=cname,
+                display_name=lot.display_name,
+                quantity_at_home=lot.quantity,
+                unit=lot.unit,
+                shelf_life_days=meta.shelf_life_days if meta else 0,
+                purchase_date=lot.purchase_date,
+                waste_risk=meta.waste_risk if meta else "unknown",
+            )
+            if decision_res:
+                decision_res.source_trace = "rule:classify_all:inventory_loop"
+
+        if not decision_res:
+            decision_res = should_buy(
+                canonical_name=cname,
+                display_name=lot.display_name,
+                quantity_at_home=lot.quantity,
+                unit=lot.unit,
+                market_record=market,
+                freshness=fr,
+                on_shopping_list=on_list,
+                is_staple=is_staple,
+                waste_risk=meta.waste_risk if meta else "unknown",
+                purchase_cadence_days=cadence_data.get(cname, {}).get("avg_interval_days"),
+                last_purchase_date=lot.purchase_date,
+                recently_bought=bool(recently_bought),
+                is_disliked=is_disliked,
+            )
+            if decision_res:
+                if is_staple and not any("staple" in r.lower() for r in decision_res.reasons):
+                    decision_res.reasons.append("Household staple")
+                    decision_res.confidence = min(decision_res.confidence + 0.1, 0.95)
+                decision_res.source_trace = "rule:classify_all:inventory_loop"
+
+        if not decision_res:
+            decision_res = should_skip(
+                canonical_name=cname,
+                display_name=lot.display_name,
+                quantity_at_home=lot.quantity,
+                unit=lot.unit,
+                waste_risk=meta.waste_risk if meta else "unknown",
+                on_shopping_list=on_list,
+                recently_bought=bool(recently_bought),
+                market_record=market,
+                freshness=fr,
+                is_disliked=is_disliked,
+            )
+            if decision_res:
+                decision_res.source_trace = "rule:classify_all:inventory_loop"
+
+        if not decision_res:
+            data_freshness, data_freshness_label = _freshness_for(cname, market_evidence_map)
+            decision_res = DecisionResult(
+                canonical_name=cname,
+                display_name=lot.display_name,
+                action="watch",
+                confidence=0.5,
+                reasons=["Monitor"],
+                evidence=[DecisionEvidence(source="inventory", value=f"{lot.quantity} {lot.unit}", confidence=1.0)],
+                source_trace="rule:classify_all:inventory_loop",
+                quantity_at_home=lot.quantity,
+                unit=lot.unit,
+                market_price=market.price_inr if market else None,
+                market_price_per_kg=market.price_per_kg if market else None,
+                market_available=bool(market),
+                market_raw_size=market.raw_size if market else "",
+                shopping_list_status="on_list" if on_list else "",
+                waste_risk=meta.waste_risk if meta else "unknown",
+                shelf_life_days=meta.shelf_life_days if meta else 0,
+                last_purchase_date=lot.purchase_date,
+                location=lot.storage_location_id or "",
+                data_freshness=data_freshness,
+                data_freshness_label=data_freshness_label,
+            )
+
+        # Enrich fields to be fully backwards-compatible
+        decision_res.shopping_list_status = "on_list" if on_list else ""
+        decision_res.shelf_life_days = meta.shelf_life_days if meta else 0
+        decision_res.last_purchase_date = lot.purchase_date
+        decision_res.location = lot.storage_location_id or ""
+        
+        if is_disliked and not any(w.code == "disliked_item" for w in decision_res.warnings):
+            decision_res.warnings.append(DecisionWarning(code="disliked_item", message="Disliked/avoided by household", severity="warning"))
+            
+        if meta and meta.waste_risk == "high" and decision_res.action == "buy" and not any(w.code == "waste_risk" for w in decision_res.warnings):
+            decision_res.warnings.append(DecisionWarning(code="waste_risk", message="High waste risk for this item", severity="warning"))
+            
+        if market and getattr(market, 'is_stale', False) and not any(w.code == "stale_data" for w in decision_res.warnings):
+            decision_res.warnings.append(DecisionWarning(code="stale_data", message="Market data is stale", severity="warning"))
+
+        decisions.append(decision_res)
+
+    if active_list and active_list.items:
+        for item in active_list.items:
+            if item.status not in ("pending", "seen"):
+                continue
+            if item.canonical_name in seen:
+                continue
+            seen.add(item.canonical_name)
+
+            inv_match = next((lot for lot in active_inv if lot.canonical_name == item.canonical_name), None)
+            meta = _get_produce_meta(item.canonical_name)
+            market = market_by_canonical.get(item.canonical_name)
+            qty = inv_match.quantity if inv_match else 0
+            low_stock = qty <= _LOW_STOCK_THRESHOLD
+            use_soon_match = item.canonical_name in use_soon_names
+            is_staple = item.canonical_name in staples
+            is_disliked = item.canonical_name in disliked
+
+            fr = None
+            if market:
+                evidence_val = market_evidence_map.get(item.canonical_name, {})
+                cap_at = evidence_val.get("captured_at")
+                if cap_at:
+                    if not isinstance(cap_at, str):
+                        cap_at = getattr(cap_at, "isoformat", lambda: str(cap_at))()
+                    fr = FreshnessReport(
+                        status="stale" if evidence_val.get("is_stale") else "fresh",
+                        age_days=evidence_val.get("age_days"),
+                        label="",
+                        captured_at=cap_at,
+                        is_stale=bool(evidence_val.get("is_stale")),
+                        warning="",
+                    )
+
+            decision_res = None
+            if is_disliked:
+                decision_res = should_skip(
+                    canonical_name=item.canonical_name,
+                    display_name=item.canonical_name.replace("_", " ").title(),
+                    quantity_at_home=qty,
+                    unit=inv_match.unit if inv_match else "unit",
+                    waste_risk=meta.waste_risk if meta else "unknown",
+                    on_shopping_list=True,
+                    recently_bought=False,
+                    market_record=market,
+                    freshness=fr,
+                    is_disliked=True,
+                )
+                if decision_res:
+                    decision_res.source_trace = "rule:classify_all:list_loop"
+
+            elif inv_match is None:
+                decision_res = should_buy(
+                    canonical_name=item.canonical_name,
+                    display_name=item.canonical_name.replace("_", " ").title(),
+                    quantity_at_home=0.0,
+                    unit="unit",
+                    market_record=market,
+                    freshness=fr,
+                    on_shopping_list=True,
+                    is_staple=is_staple,
+                    waste_risk=meta.waste_risk if meta else "unknown",
+                    is_disliked=is_disliked,
+                )
+                if decision_res:
+                    if is_staple and not any("staple" in r.lower() for r in decision_res.reasons):
+                        decision_res.reasons.append("Household staple")
+                        decision_res.confidence = min(decision_res.confidence + 0.1, 0.95)
+                    decision_res.source_trace = "rule:classify_all:list_loop"
+            else:
+                if use_soon_match:
+                    decision_res = use_soon(
+                        canonical_name=item.canonical_name,
+                        display_name=inv_match.display_name,
+                        quantity_at_home=inv_match.quantity,
+                        unit=inv_match.unit,
+                        shelf_life_days=meta.shelf_life_days if meta else 0,
+                        purchase_date=inv_match.purchase_date,
+                        waste_risk=meta.waste_risk if meta else "unknown",
+                    )
+                    if decision_res:
+                        decision_res.source_trace = "rule:classify_all:list_loop"
+
+                if not decision_res:
+                    decision_res = should_buy(
+                        canonical_name=item.canonical_name,
+                        display_name=inv_match.display_name,
+                        quantity_at_home=inv_match.quantity,
+                        unit=inv_match.unit,
+                        market_record=market,
+                        freshness=fr,
+                        on_shopping_list=True,
+                        is_staple=is_staple,
+                        waste_risk=meta.waste_risk if meta else "unknown",
+                        is_disliked=is_disliked,
+                    )
+                    if decision_res:
+                        if is_staple and not any("staple" in r.lower() for r in decision_res.reasons):
+                            decision_res.reasons.append("Household staple")
+                            decision_res.confidence = min(decision_res.confidence + 0.1, 0.95)
+                        decision_res.source_trace = "rule:classify_all:list_loop"
+
+                if not decision_res:
+                    decision_res = should_skip(
+                        canonical_name=item.canonical_name,
+                        display_name=inv_match.display_name,
+                        quantity_at_home=inv_match.quantity,
+                        unit=inv_match.unit,
+                        waste_risk=meta.waste_risk if meta else "unknown",
+                        on_shopping_list=True,
+                        recently_bought=False,
+                        market_record=market,
+                        freshness=fr,
+                        is_disliked=is_disliked,
+                    )
+                    if decision_res:
+                        decision_res.source_trace = "rule:classify_all:list_loop"
+
+            if not decision_res:
+                data_freshness, data_freshness_label = _freshness_for(item.canonical_name, market_evidence_map)
+                decision_res = DecisionResult(
+                    canonical_name=item.canonical_name,
+                    display_name=item.canonical_name.replace("_", " ").title(),
+                    action="watch",
+                    confidence=0.5,
+                    reasons=["Monitor"],
+                    evidence=[DecisionEvidence(source="shopping_list", value="on_list", confidence=1.0)],
+                    source_trace="rule:classify_all:list_loop",
+                    quantity_at_home=qty,
+                    unit=inv_match.unit if inv_match else "unit",
+                    market_price=market.price_inr if market else None,
+                    market_price_per_kg=market.price_per_kg if market else None,
+                    market_available=bool(market),
+                    market_raw_size=market.raw_size if market else "",
+                    shopping_list_status="on_list",
+                    waste_risk=meta.waste_risk if meta else "unknown",
+                    shelf_life_days=meta.shelf_life_days if meta else 0,
+                    last_purchase_date=inv_match.purchase_date if inv_match else None,
+                    location=inv_match.storage_location_id if inv_match else "",
+                    data_freshness=data_freshness,
+                    data_freshness_label=data_freshness_label,
+                )
+
+            decision_res.shopping_list_status = "on_list"
+            decision_res.shelf_life_days = meta.shelf_life_days if meta else 0
+            decision_res.last_purchase_date = inv_match.purchase_date if inv_match else None
+            decision_res.location = inv_match.storage_location_id if inv_match else ""
+
+            if is_disliked and not any(w.code == "disliked_item" for w in decision_res.warnings):
+                decision_res.warnings.append(DecisionWarning(code="disliked_item", message="Disliked/avoided by household", severity="warning"))
+
+            decisions.append(decision_res)
+
+    if market_snapshot is not None:
+        market_source_name = getattr(market_snapshot, 'source', 'market')
+        for cname, r in market_by_canonical.items():
+            if cname in seen:
+                continue
+            seen.add(cname)
+
+            meta = _get_produce_meta(cname)
+            price_ppk = r.price_per_kg or 0
+            if price_ppk <= 0:
+                continue
+
+            all_weighted = [
+                rec for rec in market_snapshot.normalized_records
+                if rec.canonical_name == cname and rec.is_weight_based and not rec.is_combo
+            ]
+            if len(all_weighted) >= 2:
+                prices = [rec.price_per_kg for rec in all_weighted if rec.price_per_kg]
+                if prices and price_ppk <= min(prices) * 1.05:
+                    action = "optional"
+                    reason_str = f"Good price: \u20b9{price_ppk:.0f}/kg on {market_source_name}"
+                    confidence = 0.7
+                else:
+                    action = "watch"
+                    reason_str = f"Available at \u20b9{price_ppk:.0f}/kg on {market_source_name}"
+                    confidence = 0.5
+            else:
+                action = "watch"
+                reason_str = f"Available at \u20b9{price_ppk:.0f}/kg on {market_source_name}"
+                confidence = 0.5
+
+            data_freshness, data_freshness_label = _freshness_for(cname, market_evidence_map)
+            decisions.append(DecisionResult(
+                canonical_name=cname,
+                display_name=cname.replace("_", " ").title(),
+                action=action,
+                confidence=confidence,
+                reasons=[reason_str],
+                evidence=[DecisionEvidence(source="market", value=f"\u20b9{r.price_inr} at {market_source_name}", confidence=1.0)],
+                source_trace="rule:classify_all:market_loop",
+                quantity_at_home=0,
+                unit="",
+                market_price=r.price_inr,
+                market_price_per_kg=r.price_per_kg,
+                market_available=True,
+                market_raw_size=r.raw_size,
+                waste_risk=meta.waste_risk if meta else "unknown",
+                shelf_life_days=meta.shelf_life_days if meta else 0,
+                data_freshness=data_freshness,
+                data_freshness_label=data_freshness_label,
+            ))
+
+    # Populate snapshot-level metadata from market evidence
+    snap_source = ""
+    snap_captured = ""
+    snap_freshness = "unknown"
+    if market_evidence_map:
+        first_ev = next(iter(market_evidence_map.values()))
+        snap_source = first_ev.get("source", "")
+        captured = first_ev.get("captured_at")
+        if captured:
+            try:
+                from datetime import datetime as _dt
+                if isinstance(captured, str):
+                    captured = _dt.fromisoformat(captured)
+                snap_captured = captured.isoformat()
+            except Exception:
+                snap_captured = str(captured)
+        any_stale = any(ev.get("is_stale", False) for ev in market_evidence_map.values())
+        snap_freshness = "stale" if any_stale else "fresh"
+
+    return DecisionSet(
+        decisions=decisions,
+        snapshot_source=snap_source,
+        snapshot_captured_at=snap_captured,
+        snapshot_freshness=snap_freshness,
+    )
+
+
+def _classify(
+    quantity: float,
+    unit: str,
+    low_stock: bool,
+    use_soon: bool,
+    on_list: bool,
+    recently_bought: bool,
+    has_market: bool,
+    waste_risk: str,
+    is_disliked: bool = False,
+) -> tuple[str, str, float]:
+
+    if is_disliked:
+        return Decision.SKIP.value, "Disliked/avoided by household", 0.95
+
+    if use_soon and quantity > 0:
+        if low_stock:
+            return Decision.USE_SOON.value, "Use remaining before it expires, then restock", 0.85
+        return Decision.USE_SOON.value, "Use existing before buying more", 0.9
+
+    if low_stock and quantity <= 0:
+        if has_market:
+            return Decision.BUY.value, "Out of stock, available on Swiggy", 0.9
+        return Decision.BUY.value, "Out of stock", 0.85
+
+    if low_stock:
+        if has_market:
+            return Decision.BUY.value, f"Running low ({quantity} {unit} left)", 0.85
+        return Decision.BUY.value, f"Running low ({quantity} {unit} left)", 0.8
+
+    if on_list and quantity > 0:
+        if waste_risk == "high":
+            return Decision.SKIP.value, "Already have enough, high waste risk if you buy more", 0.8
+        return Decision.SKIP.value, "Already have enough at home", 0.75
+
+    if quantity > 0 and not low_stock and not use_soon:
+        if recently_bought:
+            return Decision.SKIP.value, "Recently purchased", 0.8
+        if waste_risk == "high":
+            return Decision.SKIP.value, "Stocked, high waste risk", 0.7
+        return Decision.SKIP.value, "Well stocked", 0.7
+
+    return Decision.WATCH.value, "Monitor", 0.5
+
+
+def _get_produce_meta(canonical_name: str):
+    try:
+        from shopstack.market.metadata import get_produce_metadata
+        return get_produce_metadata(canonical_name)
+    except Exception:
+        return None
+
+
+def _freshness_for(cname: str, evidence_map: dict[str, Any]) -> tuple[str, str]:
+    """Derive (data_freshness, data_freshness_label) from market evidence."""
+    ev = evidence_map.get(cname)
+    if not ev:
+        return "unknown", ""
+    age = ev.get("age_days", 0)
+    is_stale = ev.get("is_stale", False)
+    freshness = "stale" if is_stale else "fresh"
+    captured = ev.get("captured_at")
+    if captured:
+        try:
+            from datetime import datetime
+            if isinstance(captured, str):
+                captured = datetime.fromisoformat(captured)
+            label = f"Snapshot from {captured.strftime('%-d %b %Y')}"
+        except Exception:
+            label = ""
+    else:
+        label = ""
+    return freshness, label
+
+
+def classify_inventory_comparison(
+    total_have: float, requested_qty: float, unit: str, is_use_soon: bool
+) -> tuple[str, str]:
+    """Return (decision, reason) from raw inventory comparison facts.
+
+    Thresholds:
+      >= 2x requested → skip (already plenty)
+      >= 1x requested → optional (have enough, buy only if needed)
+      < 1x requested  → buy (need more)
+    """
+    if total_have <= 0:
+        return "buy", f"Not found in inventory."
+
+    shortfall = max(requested_qty - total_have, 0)
+    surplus_ratio = total_have / requested_qty if requested_qty > 0 else float("inf")
+
+    if surplus_ratio >= 2:
+        return "skip", f"Already have {total_have} {unit} at home."
+    if surplus_ratio >= 1:
+        return "optional", f"Have {total_have} {unit}. Only buy if needed."
+    return "buy", f"Have only {total_have} {unit}. Buy {shortfall} {unit}."
+
+
+def _multi_source_market_data(
+    market_snapshot,
+    source_registry,
+    market_by_canonical: dict,
+    market_evidence_map: dict,
+) -> None:
+    """Populate market_by_canonical and market_evidence_map from single snapshot or multi-source registry.
+
+    Logs warnings on partial failures instead of silently degrading.
+    """
+    if source_registry is not None:
+        try:
+            all_snapshots = source_registry.all_snapshots()
+            for source_id, snap in all_snapshots.items():
+                if snap and snap.normalized_records:
+                    for r in snap.normalized_records:
+                        if r.is_available and r.is_weight_based and not r.is_combo:
+                            existing = market_by_canonical.get(r.canonical_name)
+                            if existing is None or (r.price_per_kg and existing.price_per_kg and r.price_per_kg < existing.price_per_kg):
+                                market_by_canonical[r.canonical_name] = r
+
+            for source_id, snap in all_snapshots.items():
+                if not snap or not snap.normalized_records:
+                    continue
+                for cname in set(market_by_canonical.keys()):
+                    records = [r for r in snap.normalized_records if r.canonical_name == cname]
+                    if not records:
+                        continue
+                    best = market_by_canonical.get(cname)
+                    existing_evidence = market_evidence_map.get(cname)
+                    price_per_kg = best.price_per_kg if best else None
+                    if existing_evidence:
+                        if price_per_kg is not None and existing_evidence.get("best_value_per_kg") is not None:
+                            if price_per_kg < existing_evidence["best_value_per_kg"]:
+                                existing_evidence["source"] = source_id
+                                existing_evidence["best_value_price"] = best.price_inr if best else None
+                                existing_evidence["best_value_per_kg"] = price_per_kg
+                    else:
+                        freshness = _build_freshness(snap)
+                        market_evidence_map[cname] = {
+                            "source": source_id,
+                            "captured_at": snap.captured_at,
+                            "age_days": freshness.get("age_days", 0),
+                            "is_stale": freshness.get("is_stale", True),
+                            "best_value_price": best.price_inr if best else None,
+                            "best_value_per_kg": price_per_kg,
+                        }
+        except Exception:
+            logger.warning("Multi-source market data failed, falling back to single snapshot", exc_info=True)
+
+    # Fallback: single snapshot path
+    if market_snapshot is not None and not market_by_canonical:
+        for r in market_snapshot.normalized_records:
+            if r.is_available and r.is_weight_based and not r.is_combo:
+                existing = market_by_canonical.get(r.canonical_name)
+                if existing is None or (r.price_per_kg and existing.price_per_kg and r.price_per_kg < existing.price_per_kg):
+                    market_by_canonical[r.canonical_name] = r
+        for cname in set(market_by_canonical.keys()):
+            records = [r for r in market_snapshot.normalized_records if r.canonical_name == cname]
+            available = [r for r in records if r.is_available]
+            sold_out = [r for r in records if not r.is_available]
+            best = market_by_canonical.get(cname)
+            freshness = _build_freshness(market_snapshot)
+            market_evidence_map[cname] = {
+                "source": market_snapshot.source,
+                "captured_at": market_snapshot.captured_at,
+                "age_days": freshness.get("age_days", 0),
+                "is_stale": freshness.get("is_stale", True),
+                "best_value_price": best.price_inr if best else None,
+                "best_value_per_kg": best.price_per_kg if best else None,
+            }
+
+
+def _build_freshness(market_snapshot) -> dict[str, Any]:
+    try:
+        from shopstack.market.sources.swiggy import snapshot_freshness
+        return snapshot_freshness(market_snapshot)
+    except Exception:
+        logger.debug("Market snapshot freshness check unavailable", exc_info=True)
+        return {"age_days": 0, "is_stale": False, "label": "unknown"}
+
+
+def detect_purchase_cadence(db: Database, user_id: str = "") -> dict[str, dict[str, Any]]:
+    purchases = db.get_purchase_events(limit=200, user_id=user_id)
+    by_item: dict[str, list[Any]] = {}
+    for p in purchases:
+        try:
+            dt = p.timestamp if hasattr(p.timestamp, "year") else None
+        except Exception:
+            dt = None
+        if dt is None:
+            continue
+        by_item.setdefault(p.canonical_name, []).append(p)
+
+    cadence: dict[str, dict[str, Any]] = {}
+    for cname, events in by_item.items():
+        events.sort(key=lambda e: e.timestamp, reverse=True)
+        if len(events) < 2:
+            continue
+        intervals = []
+        for i in range(len(events) - 1):
+            d1 = events[i].timestamp.date() if hasattr(events[i].timestamp, "date") else events[i].timestamp
+            d2 = events[i + 1].timestamp.date() if hasattr(events[i + 1].timestamp, "date") else events[i + 1].timestamp
+            if d1 and d2:
+                gap = (d1 - d2).days
+                if gap > 0:
+                    intervals.append(gap)
+        if not intervals:
+            continue
+        avg_interval = sum(intervals) / len(intervals)
+        last = events[0].timestamp.date() if hasattr(events[0].timestamp, "date") else events[0].timestamp
+        next_expected = last + timedelta(days=round(avg_interval))
+        typical_qty = sum(e.quantity for e in events) / len(events)
+        cadence[cname] = {
+            "avg_interval_days": round(avg_interval, 1),
+            "last_bought": last,
+            "typical_qty": round(typical_qty, 2),
+            "typical_unit": events[0].unit,
+            "next_expected": next_expected,
+            "purchase_count": len(events),
+        }
+    return cadence
+
+
+def detect_waste_patterns(db: Database, user_id: str = "") -> list[dict[str, Any]]:
+    cadence = detect_purchase_cadence(db, user_id=user_id)
+    waste_signals: list[dict[str, Any]] = []
+    inv = db.get_inventory(user_id=user_id)
+
+    for cname, info in cadence.items():
+        if info["purchase_count"] < 3:
+            continue
+        meta = _get_produce_meta(cname)
+        waste_risk = meta.waste_risk if meta else "unknown"
+        if waste_risk != "high":
+            continue
+
+        lot = next((lot for lot in inv if lot.canonical_name == cname and lot.status == "active"), None)
+        overstocked = lot and lot.quantity > 1.0
+        if overstocked or info["avg_interval_days"] < 2:
+            waste_signals.append({
+                "canonical_name": cname,
+                "display_name": cname.replace("_", " ").title(),
+                "reason": f"High waste-risk produce bought every {info['avg_interval_days']:.0f} days",
+                "current_quantity": lot.quantity if lot else 0,
+                "unit": lot.unit if lot else "unit",
+                "waste_risk": waste_risk,
+                "avg_interval_days": info["avg_interval_days"],
+            })
+
+    return waste_signals
+
+
+def check_swiggy_availability(canonical_names: list[str]) -> dict[str, dict[str, Any]]:
+    try:
+        from shopstack.market.sources.swiggy import load_snapshot
+        snap = load_snapshot()
+    except Exception:
+        return {}
+
+    result: dict[str, dict[str, Any]] = {}
+    all_records: dict[str, list[Any]] = {}
+    for r in snap.normalized_records:
+        all_records.setdefault(r.canonical_name, []).append(r)
+
+    for cname in canonical_names:
+        records = all_records.get(cname, [])
+        if not records:
+            continue
+        available = [r for r in records if r.is_available]
+        sold_out = [r for r in records if not r.is_available]
+        if available:
+            best = min(
+                (r for r in available if r.is_weight_based and not r.is_combo and r.price_per_kg),
+                key=lambda r: r.price_per_kg,
+                default=available[0],
+            )
+            result[cname] = {
+                "available": True,
+                "price": best.price_inr,
+                "price_per_kg": best.price_per_kg,
+                "raw_size": best.raw_size,
+            }
+        elif sold_out:
+            result[cname] = {
+                "available": False,
+                "price": sold_out[0].price_inr,
+                "price_per_kg": sold_out[0].price_per_kg,
+                "raw_size": sold_out[0].raw_size,
+            }
+    return result

shopstack/decisions/types.py

@@ -0,0 +1,50 @@
+"""Decision types — pure data structures for the ShopStack decision engine.
+
+No HTML rendering, no database access, no provider calls.
+Every ShopStack decision (buy / skip / use-soon / compare / etc.) uses
+DecisionResult as its canonical representation.
+"""
+
+from __future__ import annotations
+
+from datetime import date, datetime
+from enum import Enum
+from typing import Any
+
+from shopstack.schemas.models import (  # noqa: F401 — canonical types
+    DecisionEvidence,
+    DecisionResult,
+    DecisionSet,
+    DecisionWarning,
+    FreshnessStatus,
+    _ACTION_COLORS,
+    _ACTION_ICONS,
+)
+
+# Keep DECISION_COLORS / DECISION_ICONS as module-level exports for callers.
+DECISION_COLORS = _ACTION_COLORS
+DECISION_ICONS = _ACTION_ICONS
+
+
+class Decision(str, Enum):
+    BUY = "buy"
+    SKIP = "skip"
+    USE_SOON = "use_soon"
+    OPTIONAL = "optional"
+    COMPARE = "compare"
+    CONFIRM = "confirm"
+    WATCH = "watch"
+
+
+# ── Legacy aliases for backward compatibility with existing tests ──────────
+# These map the old Decision enum values to the new DecisionResult.action values.
+# Used by classify_all() and _classify() when building DecisionResult items.
+ACTION_MAP: dict[str, str] = {
+    "buy": "buy",
+    "skip": "skip",
+    "use_soon": "use_soon",
+    "optional": "optional",
+    "compare": "compare",
+    "confirm": "wait",        # confirm → wait in new schema
+    "watch": "wait",          # watch → wait in new schema
+}

shopstack/domain/__init__.py

@@ -0,0 +1,82 @@
+"""Domain layer — pure business logic, no external dependencies.
+
+This package extracts canonical business rules from services/UI into
+testable, reusable pure functions. Each module has zero imports from
+shopstack.services, shopstack.ui, or shopstack.persistence.
+
+Supersedes scattered logic in:
+- shopstack/market/normalization.py (unit price, canonical maps)
+- shopstack/services/freshness.py (freshness classification)
+- shopstack/services/dashboard.py (inventory alerts)
+- shopstack/ui/screens/other.py (location hierarchy)
+- shopstack/decisions/rules.py (decision predicates, partially)
+"""
+
+from __future__ import annotations
+
+from .unit_price import (
+    parse_size,
+    compute_unit_prices,
+    SizeParseResult,
+    CANONICAL_MAP,
+    ITEM_ALIASES,
+    resolve_canonical,
+    normalize_item_name,
+    canonicalize_name,
+)
+from .market_freshness import (
+    classify_freshness,
+    classify_snapshot_freshness,
+    inventory_freshness_label,
+    inventory_confidence,
+    needs_confirmation,
+    confirmation_prompt,
+    FreshnessReport,
+)
+from .inventory_alerts import (
+    classify_inventory_alert,
+    InventoryAlert,
+    AlertLevel,
+)
+from .storage_locations import (
+    is_parent_of,
+    get_location_hierarchy,
+    LocationNode,
+)
+from .product_matching import (
+    score_product_match,
+    MatchScore,
+    MatchReason,
+)
+
+__all__ = [
+    # unit_price
+    "parse_size",
+    "compute_unit_prices",
+    "SizeParseResult",
+    "CANONICAL_MAP",
+    "ITEM_ALIASES",
+    "resolve_canonical",
+    "normalize_item_name",
+    "canonicalize_name",
+    # market_freshness
+    "classify_freshness",
+    "classify_snapshot_freshness",
+    "inventory_freshness_label",
+    "inventory_confidence",
+    "needs_confirmation",
+    "confirmation_prompt",
+    "FreshnessReport",
+    # inventory_alerts
+    "classify_inventory_alert",
+    "InventoryAlert",
+    "AlertLevel",
+    # storage_locations
+    "is_parent_of",
+    "get_location_hierarchy",
+    "LocationNode",
+    # product_matching
+    "score_product_match",
+    "MatchScore",
+    "MatchReason",
+]

shopstack/market/__init__.py

@@ -0,0 +1,35 @@
+from .analytics import (
+    available_canonical_names,
+    compute_snapshot_analytics,
+    find_all_options,
+    find_cheapest_weight_option,
+)
+from .basket import (
+    BasketItem,
+    OptimizedBasket,
+    OptimizedBasketItem,
+    basket_summary,
+    build_basket,
+    build_optimized_basket,
+)
+from .metadata import ProduceMetadata, get_produce_metadata, use_first, waste_risk_ranking
+from .schema import MarketSnapshot, NormalizedMarketRecord
+
+__all__ = [
+    "MarketSnapshot",
+    "NormalizedMarketRecord",
+    "BasketItem",
+    "OptimizedBasket",
+    "OptimizedBasketItem",
+    "ProduceMetadata",
+    "compute_snapshot_analytics",
+    "find_cheapest_weight_option",
+    "find_all_options",
+    "available_canonical_names",
+    "build_basket",
+    "build_optimized_basket",
+    "basket_summary",
+    "get_produce_metadata",
+    "waste_risk_ranking",
+    "use_first",
+]

shopstack/market/analytics.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+from collections import Counter
+from typing import Any
+
+from .schema import MarketSnapshot, NormalizedMarketRecord
+
+
+def compute_snapshot_analytics(snapshot: MarketSnapshot) -> dict[str, Any]:
+    records = snapshot.normalized_records
+    n_total = len(records)
+
+    if n_total == 0:
+        return {
+            "total": 0,
+            "available": 0,
+            "sold_out": 0,
+            "combos": 0,
+            "ads": 0,
+            "upgrades": 0,
+            "avg_price": 0,
+            "median_price": 0,
+            "avg_discount": 0,
+            "category_counts": {},
+            "canonical_counts": {},
+            "weight_price_range": {},
+            "weight_price_by_canonical": {},
+            "best_value_by_canonical": {},
+        }
+
+    available = [r for r in records if r.is_available]
+    sold_out = [r for r in records if not r.is_available]
+    combos = [r for r in records if r.is_combo]
+    ads = [r for r in records if r.is_ad]
+    upgrades = [r for r in records if r.is_upgrade]
+
+    prices = [r.price_inr for r in records if r.price_inr > 0]
+    avg_price = sum(prices) / len(prices) if prices else 0
+    median_price = _median(prices) if prices else 0
+
+    discounts = [
+        r.computed_discount_percent
+        for r in records
+        if r.computed_discount_percent > 0
+    ]
+    avg_discount = sum(discounts) / len(discounts) if discounts else 0
+
+    # Top discounts: up to 5 records with the highest *displayed* discount,
+    # tied by price ascending. Restores the ``top_discounts`` field that
+    # the deprecated ``summarize_swiggy_snapshot`` exposed in Pass 9
+    # supersession (see Pass 9 addendum: "Add features back to canonical").
+    # Using ``discount_percent_displayed`` (the canonical field) rather
+    # than the legacy ``discount_percent`` (which was a custom dataclass
+    # field on the deprecated ``SwiggyVegetableRecord``).
+    top_discounts_records = [
+        r for r in records
+        if r.discount_percent_displayed is not None
+        and r.discount_percent_displayed > 0
+    ]
+    top_discounts_records.sort(
+        key=lambda r: (-r.discount_percent_displayed, r.price_inr or 0.0)
+    )
+    top_discounts = [
+        {
+            "name": r.raw_name,
+            "canonical_name": r.canonical_name,
+            "price_inr": r.price_inr,
+            "discount_percent": r.discount_percent_displayed,
+        }
+        for r in top_discounts_records[:5]
+    ]
+
+    canonical_counts: dict[str, int] = Counter(
+        r.canonical_name for r in records if not r.is_combo
+    )
+
+    weight_records = [
+        r
+        for r in records
+        if r.is_weight_based and r.price_per_kg is not None and not r.is_combo
+    ]
+    by_canonical: dict[str, list[float]] = {}
+    for r in weight_records:
+        if r.price_per_kg is not None:
+            by_canonical.setdefault(r.canonical_name, []).append(r.price_per_kg)
+    weight_price_by_canonical = {
+        k: {
+            "min": round(min(vals), 2),
+            "max": round(max(vals), 2),
+            "avg": round(sum(vals) / len(vals), 2),
+            "count": len(vals),
+        }
+        for k, vals in by_canonical.items()
+    }
+
+    overall_ppa = _percentile_bounds(
+        [r.price_per_kg for r in weight_records]
+    )
+
+    best_value: dict[str, NormalizedMarketRecord] = {}
+    for r in weight_records:
+        if r.price_per_kg is None:
+            continue
+        existing = best_value.get(r.canonical_name)
+        if existing is None or (existing.price_per_kg is not None and r.price_per_kg < existing.price_per_kg):
+            best_value[r.canonical_name] = r
+
+    best_value_summary = {
+        k: {
+            "price_per_kg": v.price_per_kg,
+            "price_inr": v.price_inr,
+            "raw_name": v.raw_name,
+            "raw_size": v.raw_size,
+            "is_available": v.is_available,
+        }
+        for k, v in best_value.items()
+    }
+
+    return {
+        "total": n_total,
+        "available": len(available),
+        "sold_out": len(sold_out),
+        "combos": len(combos),
+        "ads": len(ads),
+        "upgrades": len(upgrades),
+        "avg_price": round(avg_price, 2),
+        "median_price": round(median_price, 2),
+        "avg_discount": round(avg_discount, 2),
+        "top_discounts": top_discounts,
+        "category_counts": dict(Counter(r.source_category for r in records)),
+        "canonical_counts": dict(canonical_counts),
+        "weight_price_range": overall_ppa,
+        "weight_price_by_canonical": weight_price_by_canonical,
+        "best_value_by_canonical": best_value_summary,
+        "weight_records_count": len(weight_records),
+    }
+
+
+def _median(values: list[float]) -> float:
+    if not values:
+        return 0
+    s = sorted(values)
+    n = len(s)
+    mid = n // 2
+    if n % 2 == 0:
+        return (s[mid - 1] + s[mid]) / 2
+    return s[mid]
+
+
+def _percentile_bounds(
+    values: list[float | None],
+) -> dict[str, float | None]:
+    clean = sorted(v for v in values if v is not None and v > 0)
+    if not clean:
+        return {"min": None, "max": None, "p25": None, "p50": None, "p75": None}
+    n = len(clean)
+
+    def pct(p: float) -> float:
+        idx = max(0, min(n - 1, int(n * p) - 1 if n * p >= 1 else 0))
+        return round(clean[idx], 2)
+
+    return {
+        "min": round(clean[0], 2),
+        "max": round(clean[-1], 2),
+        "p25": pct(0.25),
+        "p50": pct(0.50),
+        "p75": pct(0.75),
+    }
+
+
+def find_cheapest_weight_option(
+    snapshot: MarketSnapshot,
+    canonical_name: str,
+    available_only: bool = True,
+) -> NormalizedMarketRecord | None:
+    candidates = [
+        r
+        for r in snapshot.normalized_records
+        if r.canonical_name == canonical_name
+        and r.is_weight_based
+        and not r.is_combo
+        and r.price_per_kg is not None
+        and (r.is_available or not available_only)
+    ]
+    if not candidates:
+        return None
+    def _ppa_key(r: NormalizedMarketRecord) -> float:
+        v = r.price_per_kg
+        assert v is not None, "price_per_kg should be non-None by filter above"
+        return v
+    return min(candidates, key=_ppa_key)
+
+
+def find_all_options(
+    snapshot: MarketSnapshot,
+    canonical_name: str,
+    available_only: bool = True,
+) -> list[NormalizedMarketRecord]:
+    return [
+        r
+        for r in snapshot.normalized_records
+        if r.canonical_name == canonical_name
+        and (r.is_available or not available_only)
+    ]
+
+
+def available_canonical_names(snapshot: MarketSnapshot) -> set[str]:
+    return {
+        r.canonical_name
+        for r in snapshot.normalized_records
+        if r.is_available and not r.is_combo
+    }

shopstack/market/basket.py

@@ -0,0 +1,495 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any
+
+from .analytics import (
+    available_canonical_names,
+    find_all_options,
+    find_cheapest_weight_option,
+)
+from .metadata import get_produce_metadata
+from .schema import MarketSnapshot, NormalizedMarketRecord
+
+
+@dataclass
+class BasketItem:
+    requested_name: str
+    canonical_name: str
+    matched: bool
+    reason: str
+    recommended_record: NormalizedMarketRecord | None
+    alternatives: list[NormalizedMarketRecord]
+    estimated_price_inr: float | None
+    estimated_price_per_kg: float | None
+
+
+def build_basket(
+    items: list[str],
+    snapshot: MarketSnapshot,
+    available_only: bool = True,
+) -> list[BasketItem]:
+    available = available_canonical_names(snapshot)
+    results: list[BasketItem] = []
+
+    for raw_item in items:
+        cleaned = raw_item.strip()
+        if not cleaned:
+            continue
+        canonical = _match_canonical(cleaned, available)
+        if canonical is None:
+            results.append(
+                BasketItem(
+                    requested_name=cleaned,
+                    canonical_name="",
+                    matched=False,
+                    reason="no_match_in_snapshot",
+                    recommended_record=None,
+                    alternatives=[],
+                    estimated_price_inr=None,
+                    estimated_price_per_kg=None,
+                )
+            )
+            continue
+
+        cheapest = find_cheapest_weight_option(snapshot, canonical, available_only)
+        all_opts = find_all_options(snapshot, canonical, available_only)
+
+        if cheapest is None:
+            non_weight = [
+                r
+                for r in all_opts
+                if not r.is_weight_based and not r.is_combo
+            ]
+            if non_weight:
+                rec = min(non_weight, key=lambda r: r.price_inr)
+                results.append(
+                    BasketItem(
+                        requested_name=cleaned,
+                        canonical_name=canonical,
+                        matched=True,
+                        reason="piece_based_only",
+                        recommended_record=rec,
+                        alternatives=non_weight[:3],
+                        estimated_price_inr=rec.price_inr,
+                        estimated_price_per_kg=None,
+                    )
+                )
+            else:
+                results.append(
+                    BasketItem(
+                        requested_name=cleaned,
+                        canonical_name=canonical,
+                        matched=True,
+                        reason="no_available_weight_or_piece",
+                        recommended_record=None,
+                        alternatives=all_opts[:3],
+                        estimated_price_inr=None,
+                        estimated_price_per_kg=None,
+                    )
+                )
+        else:
+            results.append(
+                BasketItem(
+                    requested_name=cleaned,
+                    canonical_name=canonical,
+                    matched=True,
+                    reason="weight_based_cheapest",
+                    recommended_record=cheapest,
+                    alternatives=[
+                        r for r in all_opts if r is not cheapest
+                    ][:3],
+                    estimated_price_inr=cheapest.price_inr,
+                    estimated_price_per_kg=cheapest.price_per_kg,
+                )
+            )
+
+    return results
+
+
+def basket_summary(basket: list[BasketItem]) -> dict[str, Any]:
+    matched = [b for b in basket if b.matched]
+    unmatched = [b for b in basket if not b.matched]
+    total_estimated = sum(
+        b.estimated_price_inr for b in matched if b.estimated_price_inr
+    )
+    return {
+        "total_requested": len(basket),
+        "matched": len(matched),
+        "unmatched": len(unmatched),
+        "total_estimated_price_inr": round(total_estimated, 2),
+        "unmatched_items": [b.requested_name for b in unmatched],
+    }
+
+
+# ─── Decision-Aware Basket Optimizer ───────────────────────────────────────
+
+
+@dataclass
+class OptimizedBasketItem:
+    requested_name: str
+    canonical_name: str
+    decision: str  # "buy" | "skip" | "use_soon" | "compare" | "unavailable"
+    reason_type: str  # "enough_stock" | "waste_risk" | "stale_data" | "no_availability" | "price_low" | "price_high" | "inventory_subtracted"
+    reason: str
+    matched: bool
+    requested_quantity: float = 1.0
+    unit: str = "unit"
+    already_owned_quantity: float = 0.0
+    net_quantity_to_buy: float = 0.0
+    recommended_record: NormalizedMarketRecord | None = None
+    alternatives: list[NormalizedMarketRecord] = field(default_factory=list)
+    estimated_price_inr: float | None = None
+    estimated_price_per_kg: float | None = None
+    waste_risk: str = "unknown"
+    freshness_note: str = ""
+
+
+@dataclass
+class OptimizedBasket:
+    items: list[OptimizedBasketItem] = field(default_factory=list)
+
+    @property
+    def buy(self) -> list[OptimizedBasketItem]:
+        return [i for i in self.items if i.decision == "buy"]
+
+    @property
+    def skip(self) -> list[OptimizedBasketItem]:
+        return [i for i in self.items if i.decision == "skip"]
+
+    @property
+    def use_soon(self) -> list[OptimizedBasketItem]:
+        return [i for i in self.items if i.decision == "use_soon"]
+
+    @property
+    def total_estimated(self) -> float:
+        return round(sum(
+            i.estimated_price_inr or 0 for i in self.buy
+        ), 2)
+
+    @property
+    def summary(self) -> dict[str, Any]:
+        return {
+            "total_requested": len(self.items),
+            "buy": len(self.buy),
+            "skip": len(self.skip),
+            "use_soon": len(self.use_soon),
+            "total_estimated_price_inr": self.total_estimated,
+        }
+
+
+def _normalize_unit_to_grams(qty: float, unit: str) -> float:
+    """Convert a quantity in user-facing units to grams for price calculation."""
+    u = unit.lower().strip()
+    if u in ("kg", "kilo", "kilos", "kilogram", "kilograms"):
+        return qty * 1000
+    if u in ("g", "gram", "grams"):
+        return qty
+    if u in ("l", "litre", "liter", "litres", "liters"):
+        return qty * 1000
+    if u in ("ml", "milliliter", "millilitre"):
+        return qty
+    # For piece-based items, return as-is (matched against piece records)
+    return qty
+
+
+def build_optimized_basket(
+    requested_items: list[dict[str, Any]],
+    snapshot: MarketSnapshot,
+    inventory_map: dict[str, float] | None = None,
+    available_only: bool = True,
+    budget_inr: float | None = None,
+    household_size: int = 1,
+    days_to_plan: int = 3,
+    avoid_items: list[str] | None = None,
+) -> OptimizedBasket:
+    """Build a decision-aware basket from requested items and market snapshot.
+
+    Each item is classified into buy / skip / use_soon / compare / unavailable
+    with an explicit ``reason_type`` explaining the classification logic.
+
+    Args:
+        requested_items: List of dicts with ``canonical_name``, ``requested_quantity``, ``unit``.
+        snapshot: Market snapshot with normalized records.
+        inventory_map: Map of canonical_name -> total quantity owned (inventory subtraction).
+        available_only: If True, only consider available items when recommending.
+        budget_inr: Optional budget cap in INR. If set, items beyond budget get ``over_budget`` reason_type.
+        household_size: Number of people. Adjusts recommended quantities.
+        days_to_plan: Number of days to plan for. Adjusts recommended quantities.
+        avoid_items: List of canonical names the household wants to avoid.
+
+    Returns:
+        An ``OptimizedBasket`` with per-item classifications.
+    """
+    inventory_map = inventory_map or {}
+    avoid_set = {a.lower().strip() for a in (avoid_items or [])}
+    available = available_canonical_names(snapshot)
+    snapshot_date = _parse_date(snapshot.captured_at) if snapshot.captured_at else date.today()
+    age_days = (date.today() - snapshot_date).days if snapshot_date else 0
+    is_stale = age_days > 1
+    freshness_note = f"Snapshot {age_days}d old" if is_stale else "Today's data"
+
+    results: list[OptimizedBasketItem] = []
+    running_total = 0.0
+
+    for raw in requested_items:
+        name = raw.get("canonical_name", "").strip()
+        if not name:
+            continue
+        qty = float(raw.get("requested_quantity", 1.0) or 1.0)
+        unit = raw.get("unit", "unit") or "unit"
+
+        # Inventory subtraction
+        owned = inventory_map.get(name.lower(), 0.0)
+        net_needed = max(qty - owned, 0.0)
+
+        # Match to snapshot
+        canonical = _match_canonical(name, available)
+        if canonical is None:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=name,
+                decision="unavailable",
+                reason_type="no_availability",
+                reason=f"No market data found for {name}",
+                matched=False,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=qty,
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Produce metadata for waste risk
+        meta = _get_produce_meta(canonical)
+        waste_risk = meta.waste_risk if meta else "unknown"
+        shelf_life = meta.shelf_life_days if meta else 0
+
+        # Check for "use soon" signal from produce metadata
+        if owned > 0 and shelf_life > 0 and shelf_life <= 5:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="use_soon",
+                reason_type="waste_risk",
+                reason=f"Use existing {owned} {unit} before buying more",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=0,
+                waste_risk=waste_risk,
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Skip if enough already owned
+        if net_needed <= 0:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="skip",
+                reason_type="enough_stock",
+                reason=f"Already have {owned} {unit} at home",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=0,
+                waste_risk=waste_risk,
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Waste risk for high-waste items
+        if waste_risk == "high" and owned > 0:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="skip",
+                reason_type="waste_risk",
+                reason=f"High waste risk — you have {owned} {unit} already",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=0,
+                waste_risk=waste_risk,
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Stale data warning
+        if is_stale and not available_only:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="compare",
+                reason_type="stale_data",
+                reason=f"Market data {age_days} days old — verify prices before checkout",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=net_needed,
+                waste_risk=waste_risk,
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Skip items the household avoids
+        if name.lower().strip() in avoid_set:
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="skip",
+                reason_type="household_avoids",
+                reason=f"{name.title().replace('_', ' ')} is on your household avoid list",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=0,
+                waste_risk=waste_risk or "unknown",
+                freshness_note=freshness_note,
+            ))
+            continue
+
+        # Scale quantity by household size and days to plan
+        scaled_qty = qty * household_size * (days_to_plan / 3.0) if household_size > 0 else qty
+        net_needed = max(scaled_qty - owned, 0.0)
+
+        # Find cheapest market option
+        cheapest = find_cheapest_weight_option(snapshot, canonical, available_only)
+        all_opts = find_all_options(snapshot, canonical, available_only)
+
+        if cheapest is not None:
+            # Convert net_needed to grams to match normalized_quantity (always in grams)
+            net_needed_grams = _normalize_unit_to_grams(net_needed, unit)
+            nq = cheapest.normalized_quantity
+            if nq is not None and nq > 0 and net_needed_grams > 0:
+                _price = cheapest.price_inr * (net_needed_grams / nq)
+            else:
+                _price = cheapest.price_inr
+
+            # Budget cap check
+            if budget_inr is not None and running_total + _price > budget_inr:
+                results.append(OptimizedBasketItem(
+                    requested_name=name,
+                    canonical_name=canonical,
+                    decision="compare",
+                    reason_type="over_budget",
+                    reason=f"Exceeds remaining budget of \u20b9{budget_inr - running_total:.0f} (\u20b9{_price:.0f} needed)",
+                    matched=True,
+                    requested_quantity=qty,
+                    unit=unit,
+                    already_owned_quantity=owned,
+                    net_quantity_to_buy=net_needed,
+                    recommended_record=cheapest,
+                    alternatives=[r for r in all_opts if r is not cheapest][:3],
+                    estimated_price_inr=cheapest.price_inr,
+                    estimated_price_per_kg=cheapest.price_per_kg,
+                    waste_risk=waste_risk,
+                    freshness_note=freshness_note,
+                ))
+                continue
+            running_total += _price
+
+            results.append(OptimizedBasketItem(
+                requested_name=name,
+                canonical_name=canonical,
+                decision="buy",
+                reason_type="price_low",
+                reason=f"Buy {net_needed:.1f} {unit} at \u20b9{cheapest.price_inr:.0f} (\u20b9{cheapest.price_per_kg:.0f}/kg)",
+                matched=True,
+                requested_quantity=qty,
+                unit=unit,
+                already_owned_quantity=owned,
+                net_quantity_to_buy=net_needed,
+                recommended_record=cheapest,
+                alternatives=[r for r in all_opts if r is not cheapest][:3],
+                estimated_price_inr=cheapest.price_inr,
+                estimated_price_per_kg=cheapest.price_per_kg,
+                waste_risk=waste_risk,
+                freshness_note=freshness_note,
+            ))
+        else:
+            # No weight-based option found — try piece-based
+            non_weight = [
+                r for r in all_opts
+                if not r.is_weight_based and not r.is_combo
+            ]
+            if non_weight:
+                rec = min(non_weight, key=lambda r: r.price_inr)
+                results.append(OptimizedBasketItem(
+                    requested_name=name,
+                    canonical_name=canonical,
+                    decision="buy",
+                    reason_type="price_low",
+                    reason=f"Buy {net_needed:.1f} {unit} — piece-based at \u20b9{rec.price_inr:.0f}",
+                    matched=True,
+                    requested_quantity=qty,
+                    unit=unit,
+                    already_owned_quantity=owned,
+                    net_quantity_to_buy=net_needed,
+                    recommended_record=rec,
+                    alternatives=non_weight[:3],
+                    estimated_price_inr=rec.price_inr,
+                    waste_risk=waste_risk,
+                    freshness_note=freshness_note,
+                ))
+            else:
+                results.append(OptimizedBasketItem(
+                    requested_name=name,
+                    canonical_name=canonical,
+                    decision="unavailable",
+                    reason_type="no_availability",
+                    reason="No available weight or piece options",
+                    matched=True,
+                    requested_quantity=qty,
+                    unit=unit,
+                    already_owned_quantity=owned,
+                    net_quantity_to_buy=net_needed,
+                    freshness_note=freshness_note,
+                ))
+
+    return OptimizedBasket(items=results)
+
+
+def _parse_date(value: str) -> date | None:
+    try:
+        return date.fromisoformat(value[:10])
+    except (ValueError, TypeError):
+        return None
+
+
+def _get_produce_meta(canonical_name: str):
+    try:
+        return get_produce_metadata(canonical_name)
+    except Exception:
+        return None
+
+
+def _match_canonical(query: str, available: set[str]) -> str | None:
+    lowered = query.lower().strip()
+    if lowered in available:
+        return lowered
+    
+    from shopstack.market.normalization import resolve_canonical
+    mapped = resolve_canonical(lowered)
+    if mapped and mapped in available:
+        return mapped
+        
+    if mapped:
+        for a in available:
+            if mapped in a or a in mapped:
+                return a
+
+    partial = [
+        a for a in available if lowered in a or a in lowered
+    ]
+    if partial:
+        return partial[0]
+    return None

shopstack/market/combo.py

@@ -0,0 +1,80 @@
+from typing import Dict, List, Optional, Tuple
+from shopstack.market.schema import NormalizedMarketRecord
+from shopstack.catalog.models import WasteRisk
+from shopstack.catalog.service import CatalogService
+
+class ComboEvaluator:
+    def __init__(self, catalog_service: CatalogService):
+        self.catalog = catalog_service
+
+    def evaluate_combo(
+        self,
+        combo_record: NormalizedMarketRecord,
+        individual_options: Dict[str, NormalizedMarketRecord],
+        user_inventory: List[str]
+    ) -> Dict[str, any]:
+        """
+        Evaluates a combo against buying individual items.
+        Returns a dictionary with savings, waste risk, and recommendation.
+        """
+        if not combo_record.is_combo:
+            return {"error": "Not a combo record"}
+
+        components = combo_record.component_names
+        if not components:
+            return {"error": "No components detected in combo"}
+
+        total_individual_price = 0.0
+        missing_individual_price = False
+        component_waste_risks = []
+        already_owned = []
+
+        for comp in components:
+            # Calculate waste risk if user already owns it
+            if comp in user_inventory:
+                already_owned.append(comp)
+                entry = self.catalog.get_by_canonical_id(comp)
+                if entry:
+                    component_waste_risks.append(entry.waste_risk.value)
+                else:
+                    component_waste_risks.append(WasteRisk.MEDIUM.value)
+
+            # Sum individual prices
+            if comp in individual_options and individual_options[comp].is_available:
+                total_individual_price += individual_options[comp].price_inr
+            else:
+                missing_individual_price = True
+
+        # Savings calculation
+        savings = 0.0
+        combo_value_ratio = 1.0
+        if not missing_individual_price and total_individual_price > 0:
+            savings = total_individual_price - combo_record.price_inr
+            combo_value_ratio = combo_record.price_inr / total_individual_price
+
+        # Waste risk calculation
+        overall_waste_risk = WasteRisk.LOW.value
+        if already_owned:
+            if WasteRisk.HIGH.value in component_waste_risks:
+                overall_waste_risk = WasteRisk.HIGH.value
+            else:
+                overall_waste_risk = WasteRisk.MEDIUM.value
+
+        recommendation = "neutral"
+        if overall_waste_risk == WasteRisk.HIGH.value:
+            recommendation = "skip_due_to_waste_risk"
+        elif savings > 0:
+            recommendation = "buy_combo"
+        elif not missing_individual_price and savings < 0:
+            recommendation = "buy_individuals"
+
+        return {
+            "components": components,
+            "total_individual_price": total_individual_price if not missing_individual_price else None,
+            "combo_price": combo_record.price_inr,
+            "savings": savings if not missing_individual_price else None,
+            "value_ratio": combo_value_ratio if not missing_individual_price else None,
+            "already_owned_components": already_owned,
+            "waste_risk": overall_waste_risk,
+            "recommendation": recommendation
+        }

shopstack/market/comparison.py

@@ -0,0 +1,98 @@
+from dataclasses import dataclass
+from datetime import date
+from typing import List, Optional
+
+from shopstack.market.schema import NormalizedMarketRecord
+
+
+@dataclass
+class ComparisonResult:
+    canonical_name: str
+    best_record: Optional[NormalizedMarketRecord]
+    all_records: List[NormalizedMarketRecord]
+    freshness_warnings: List[str]
+    ad_warnings: List[str]
+    confidence_score: float
+
+
+def compare_records(
+    canonical_name: str,
+    records: List[NormalizedMarketRecord],
+    today: Optional[date] = None
+) -> ComparisonResult:
+    """Compare multiple market records to find the best option."""
+    if today is None:
+        today = date.today()
+
+    best_record = None
+    freshness_warnings = []
+    ad_warnings = []
+    confidence_score = 1.0
+
+    if not records:
+        return ComparisonResult(
+            canonical_name=canonical_name,
+            best_record=None,
+            all_records=[],
+            freshness_warnings=[],
+            ad_warnings=[],
+            confidence_score=0.0
+        )
+
+    # Filter out unavailable items
+    available_records = [r for r in records if r.is_available]
+    if not available_records:
+        confidence_score -= 0.5
+    
+    # Check for ads and freshness
+    for rec in records:
+        if rec.is_ad:
+            ad_warnings.append(f"Record from {rec.source} is marked as an ad.")
+        try:
+            captured_date = date.fromisoformat(rec.captured_at[:10])
+            if (today - captured_date).days > 1:
+                freshness_warnings.append(
+                    f"Data from {rec.source} is {(today - captured_date).days} days old."
+                )
+        except (ValueError, TypeError):
+            freshness_warnings.append(f"Invalid date format for record from {rec.source}.")
+            confidence_score -= 0.1
+    
+    # Sort by price_per_kg or price_inr
+    if available_records:
+        def sort_key(r: NormalizedMarketRecord):
+            # Prefer price_per_kg if available, else use price_inr / normalized_quantity
+            if r.price_per_kg:
+                return r.price_per_kg
+            if r.price_per_100g:
+                return r.price_per_100g * 10
+            if r.price_per_piece:
+                return r.price_per_piece
+            if r.normalized_quantity and r.normalized_quantity > 0:
+                return r.price_inr / r.normalized_quantity
+            return r.price_inr
+        
+        sorted_records = sorted(available_records, key=sort_key)
+        best_record = sorted_records[0]
+        
+        # Penalize confidence if best record is an ad or stale
+        if best_record.is_ad:
+            confidence_score -= 0.2
+        try:
+            captured_date = date.fromisoformat(best_record.captured_at[:10])
+            if (today - captured_date).days > 1:
+                confidence_score -= 0.3
+        except Exception:
+            pass
+            
+        if len(sorted_records) < 2:
+            confidence_score -= 0.1  # Less confidence if only one source
+
+    return ComparisonResult(
+        canonical_name=canonical_name,
+        best_record=best_record,
+        all_records=records,
+        freshness_warnings=list(set(freshness_warnings)),
+        ad_warnings=list(set(ad_warnings)),
+        confidence_score=max(0.0, min(1.0, confidence_score))
+    )

shopstack/market/metadata.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ProduceMetadata:
+    canonical_name: str
+    shelf_life_days: int
+    storage: str
+    waste_risk: str
+    use_priority: int
+    tips: str
+
+
+_PRODUCE: dict[str, ProduceMetadata] = {
+    "tomato": ProduceMetadata("tomato", 7, "counter", "medium", 2, "Use in cooking within 5 days for best flavor."),
+    "onion": ProduceMetadata("onion", 30, "cool_dry", "low", 5, "Store ventilated, away from potatoes."),
+    "potato": ProduceMetadata("potato", 21, "cool_dark", "low", 4, "Keep away from onions to prevent sprouting."),
+    "baby_potato": ProduceMetadata("baby_potato", 14, "cool_dark", "low", 4, "Use within a week for best texture."),
+    "sweet_potato": ProduceMetadata("sweet_potato", 21, "cool_dark", "low", 4, "Cure 10 days at room temp for sweetness."),
+    "carrot": ProduceMetadata("carrot", 14, "fridge_crisper", "medium", 3, "Remove greens before storing."),
+    "cucumber": ProduceMetadata("cucumber", 7, "fridge_crisper", "high", 1, "Use within 4 days, shrivels quickly."),
+    "brinjal": ProduceMetadata("brinjal", 5, "fridge_crisper", "high", 1, "Browns fast once cut — use immediately."),
+    "capsicum": ProduceMetadata("capsicum", 10, "fridge_crisper", "medium", 3, "Stays crisp in a paper bag."),
+    "bell_pepper": ProduceMetadata("bell_pepper", 10, "fridge_crisper", "medium", 3, "Red/yellow spoil faster than green."),
+    "cauliflower": ProduceMetadata("cauliflower", 7, "fridge_crisper", "high", 2, "Brown spots = early spoilage."),
+    "broccoli": ProduceMetadata("broccoli", 5, "fridge_crisper", "high", 1, "Yellow florets = over the hill."),
+    "ridge_gourd": ProduceMetadata("ridge_gourd", 4, "fridge_crisper", "high", 1, "Use quickly, goes limp fast."),
+    "bottle_gourd": ProduceMetadata("bottle_gourd", 5, "fridge_crisper", "high", 2, "Cut away bitter portions."),
+    "bitter_gourd": ProduceMetadata("bitter_gourd", 5, "fridge_crisper", "high", 2, "Wrap loosely in paper."),
+    "snake_gourd": ProduceMetadata("snake_gourd", 4, "fridge_crisper", "high", 1, "Use within 2 days of purchase."),
+    "pointed_gourd": ProduceMetadata("pointed_gourd", 4, "fridge_crisper", "high", 1, "Delicate, use quickly."),
+    "round_gourd": ProduceMetadata("round_gourd", 4, "fridge_crisper", "high", 1, "Best same-day."),
+    "coccinia": ProduceMetadata("coccinia", 5, "fridge_crisper", "medium", 2, "Good in stir-fry."),
+    "cluster_beans": ProduceMetadata("cluster_beans", 4, "fridge_crisper", "high", 1, "String before cooking."),
+    "french_beans": ProduceMetadata("french_beans", 5, "fridge_crisper", "high", 2, "Snap off ends before storing."),
+    "ladys_finger": ProduceMetadata("ladys_finger", 4, "fridge_crisper", "high", 1, "Keep dry, moisture causes slime."),
+    "drumstick": ProduceMetadata("drumstick", 5, "fridge_crisper", "medium", 2, "Use in sambar or curry."),
+    "beetroot": ProduceMetadata("beetroot", 14, "fridge_crisper", "low", 4, "Leaves edible, cook like spinach."),
+    "radish": ProduceMetadata("radish", 7, "fridge_crisper", "low", 3, "Remove leaves before storing."),
+    "raw_banana": ProduceMetadata("raw_banana", 5, "counter", "medium", 2, "Ripens at room temp."),
+    "raw_mango": ProduceMetadata("raw_mango", 7, "counter", "medium", 2, "Use in pickles or curries."),
+    "yam": ProduceMetadata("yam", 14, "cool_dark", "low", 4, "Peel deeply to remove oxalates."),
+    "colocasia": ProduceMetadata("colocasia", 14, "cool_dark", "low", 4, "Boil before peeling."),
+    "zucchini": ProduceMetadata("zucchini", 7, "fridge_crisper", "medium", 3, "Pat dry before storing."),
+    "red_cabbage": ProduceMetadata("red_cabbage", 14, "fridge_crisper", "low", 4, "Lasts longer than green."),
+    "coconut": ProduceMetadata("coconut", 30, "fridge_crisper", "low", 5, "Crack within 2 days for best water."),
+    "curry_leaves": ProduceMetadata("curry_leaves", 7, "fridge_crisper", "high", 2, "Strip leaves from stem, freeze extras."),
+    "coriander": ProduceMetadata("coriander", 4, "fridge_crisper", "high", 1, "Wrap in paper towel, use early."),
+    "mint": ProduceMetadata("mint", 4, "fridge_crisper", "high", 1, "Like coriander, wilts fast."),
+    "green_chilli": ProduceMetadata("green_chilli", 10, "fridge_crisper", "medium", 3, "Stems on until use."),
+    "garlic": ProduceMetadata("garlic", 60, "cool_dry", "low", 5, "Unpeeled bulbs last months."),
+    "ginger": ProduceMetadata("ginger", 30, "fridge_crisper", "low", 5, "Freeze for longer storage."),
+    "sambar_onion": ProduceMetadata("sambar_onion", 21, "cool_dry", "low", 4, "Shallots, store like onions."),
+    "white_onion": ProduceMetadata("white_onion", 30, "cool_dry", "low", 5, "Milder than red onion."),
+}
+
+
+def get_produce_metadata(canonical_name: str) -> ProduceMetadata | None:
+    return _PRODUCE.get(canonical_name)
+
+
+def waste_risk_ranking() -> list[str]:
+    items = list(_PRODUCE.values())
+    items.sort(key=lambda p: (p.use_priority, -p.shelf_life_days))
+    return [p.canonical_name for p in items]
+
+
+def use_first(items: list[str]) -> list[str]:
+    ranked = []
+    for name in items:
+        meta = _PRODUCE.get(name)
+        if meta:
+            ranked.append((name, meta.use_priority))
+        else:
+            ranked.append((name, 99))
+    ranked.sort(key=lambda x: x[1])
+    return [name for name, _ in ranked]

shopstack/market/normalization.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+import logging
+import re
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+_WEIGHT_PATTERN = re.compile(
+    r"^(\d+(?:\.\d+)?)\s*(kg|g|ml|l|liter|litre)\s*(?:x\s*(\d+))?$",
+    re.IGNORECASE,
+)
+_PIECE_PATTERN = re.compile(
+    r"^(\d+)\s*(?:pieces|piece|pcs|pc)\s*(?:x\s*(\d+))?$",
+    re.IGNORECASE,
+)
+_COMBO_PATTERN = re.compile(r"^(\d+)\s*(?:combo|pack)$", re.IGNORECASE)
+_SIZE_CLASS_PATTERN = re.compile(
+    r"^(\d+)\s*(small|medium|large)$",
+    re.IGNORECASE,
+)
+_SIZE_CLASS_GRAM_ESTIMATES: dict[str, int] = {
+    "small": 80,
+    "medium": 120,
+    "large": 180,
+}
+
+
+@dataclass
+class SizeParseResult:
+    normalized_quantity: float | None = None
+    normalized_unit: str | None = None
+    package_count: int = 1
+    is_weight_based: bool = False
+    is_piece_based: bool = False
+    is_combo: bool = False
+    is_pack: bool = False
+    is_size_class: bool = False
+    size_class: str = ""
+    warnings: list[str] | None = None
+
+    def __post_init__(self):
+        if self.warnings is None:
+            self.warnings = []
+
+
+def parse_size(raw_size: str) -> SizeParseResult:
+    if not raw_size:
+        return SizeParseResult(warnings=["empty_size"])
+
+    stripped = raw_size.strip()
+
+    m = _WEIGHT_PATTERN.match(stripped)
+    if m:
+        qty = float(m.group(1))
+        unit_raw = m.group(2).lower()
+        pkg = int(m.group(3)) if m.group(3) else 1
+        unit = _normalize_weight_unit(unit_raw)
+        if unit_raw in ("kg", "l", "liter", "litre"):
+            qty = qty * 1000
+        total_qty = qty * pkg
+        return SizeParseResult(
+            normalized_quantity=total_qty,
+            normalized_unit=unit,
+            package_count=pkg,
+            is_weight_based=True,
+        )
+
+    m = _PIECE_PATTERN.match(stripped)
+    if m:
+        qty = int(m.group(1))
+        pkg = int(m.group(2)) if m.group(2) else 1
+        total_pieces = qty * pkg
+        return SizeParseResult(
+            normalized_quantity=float(total_pieces),
+            normalized_unit="pieces",
+            package_count=pkg,
+            is_piece_based=True,
+        )
+
+    m = _COMBO_PATTERN.match(stripped)
+    if m:
+        is_pack = "pack" in stripped.lower()
+        return SizeParseResult(
+            is_combo=not is_pack,
+            is_pack=is_pack,
+            warnings=["combo_or_pack_no_weight"],
+        )
+
+    m = _SIZE_CLASS_PATTERN.match(stripped)
+    if m:
+        count = int(m.group(1))
+        cls = m.group(2).lower()
+        estimated_grams = count * _SIZE_CLASS_GRAM_ESTIMATES[cls]
+        return SizeParseResult(
+            normalized_quantity=float(estimated_grams),
+            normalized_unit="g",
+            package_count=count,
+            is_size_class=True,
+            is_weight_based=True,
+            size_class=cls,
+            warnings=[f"estimated_size_class_weight:{cls}:{_SIZE_CLASS_GRAM_ESTIMATES[cls]}g_each"],
+        )
+
+    if re.match(r"^\d+\s*$", stripped):
+        n = int(stripped)
+        return SizeParseResult(
+            normalized_quantity=float(n),
+            normalized_unit="pieces",
+            package_count=n,
+            is_piece_based=True,
+        )
+
+    return SizeParseResult(warnings=[f"unrecognized_size:{stripped}"])
+
+
+def _normalize_weight_unit(unit: str) -> str:
+    mapping = {
+        "kg": "g",
+        "g": "g",
+        "l": "mL",
+        "ml": "mL",
+        "liter": "mL",
+        "litre": "mL",
+    }
+    return mapping.get(unit, unit)
+
+
+def compute_unit_prices(
+    price: float,
+    quantity: float | None,
+    unit: str | None,
+    is_weight_based: bool,
+    is_piece_based: bool,
+) -> dict[str, float | None]:
+    result: dict[str, float | None] = {
+        "price_per_kg": None,
+        "price_per_100g": None,
+        "price_per_piece": None,
+    }
+    if price <= 0 or quantity is None or quantity <= 0:
+        return result
+
+    if is_weight_based and unit == "g":
+        result["price_per_kg"] = round(price / quantity * 1000, 2)
+        result["price_per_100g"] = round(price / quantity * 100, 2)
+    elif is_piece_based and unit == "pieces":
+        result["price_per_piece"] = round(price / quantity, 2)
+
+    return result
+
+
+_CANONICAL_MAP: dict[str, str] = {
+    "tomato": "tomato",
+    "indian tomato": "tomato",
+    "hybrid tomato": "tomato",
+    "desi tomato": "tomato",
+    "snibs snack tomatoes": "tomato",
+    "cherry tomato": "tomato",
+    "onion": "onion",
+    "sambar onion": "sambar_onion",
+    "white onion": "white_onion",
+    "value pack onion": "onion",
+    "potato": "potato",
+    "baby potato": "baby_potato",
+    "chandramukhi potato": "potato",
+    "sweet potato": "sweet_potato",
+    "carrot": "carrot",
+    "ooty carrot": "carrot",
+    "cucumber": "cucumber",
+    "english cucumber": "cucumber",
+    "green cucumber": "cucumber",
+    "brinjal": "brinjal",
+    "kateri brinjal": "brinjal",
+    "long purple brinjal": "brinjal",
+    "capsicum": "capsicum",
+    "green capsicum": "capsicum",
+    "bell pepper": "bell_pepper",
+    "red bell pepper": "bell_pepper",
+    "yellow bell pepper": "bell_pepper",
+    "red & yellow bell pepper": "bell_pepper",
+    "ridge gourd": "ridge_gourd",
+    "bottle gourd": "bottle_gourd",
+    "bitter gourd": "bitter_gourd",
+    "forest bitter gourd": "bitter_gourd",
+    "snake gourd": "snake_gourd",
+    "pointed gourd": "pointed_gourd",
+    "round gourd": "round_gourd",
+    "cauliflower": "cauliflower",
+    "coccinia": "coccinia",
+    "cluster beans": "cluster_beans",
+    "french beans": "french_beans",
+    "haricot beans": "haricot_beans",
+    "broad beans": "broad_beans",
+    "cowpea beans": "cowpea_beans",
+    "ladys finger": "ladys_finger",
+    "lady finger": "ladys_finger",
+    "okra": "ladys_finger",
+    "drumstick": "drumstick",
+    "beetroot": "beetroot",
+    "radish": "radish",
+    "white radish": "radish",
+    "raw banana": "raw_banana",
+    "raw mango": "raw_mango",
+    "totapuri raw mango": "raw_mango",
+    "yam": "yam",
+    "colocasia": "colocasia",
+    "arvi": "colocasia",
+    "broccoli": "broccoli",
+    "zucchini": "zucchini",
+    "green zucchini": "zucchini",
+    "yellow zucchini": "zucchini",
+    "coconut": "coconut",
+    "red cabbage": "red_cabbage",
+    "curry leaves": "curry_leaves",
+    "coriander leaves": "coriander",
+    "mint leaves": "mint",
+    "green chilli": "green_chilli",
+    "garlic": "garlic",
+    "ginger": "ginger",
+}
+
+_COMBO_KEYWORDS = ("combo", "&", "mix")
+
+# User-facing alias map: Hindi/regional/colloquial → canonical English name.
+# This is the single source of truth for linguistic aliases.
+# Market product variants (e.g. "baby potato", "sambar onion") are NOT here
+# because they represent distinct inventory items — those live in _CANONICAL_MAP.
+# User-facing alias map: Hindi/regional/colloquial → canonical English name.
+# This is the single source of truth for linguistic aliases.
+# Market product variants (e.g. "baby potato", "sambar onion") are NOT here
+# because they represent distinct inventory items — those live in _CANONICAL_MAP.
+#
+# Covers: Hindi, Kannada, Tamil, Telugu, Marathi, Gujarati, Bengali, common English colloquial.
+ITEM_ALIASES: dict[str, list[str]] = {
+    # ── Vegetables ──
+    "tomato": ["tamatar", "tamatar", "tomatoes", "thakkali"],
+    "onion": ["pyaaz", "pyaz", "eerulli", "uli"],
+    "sambar_onion": ["sambar pyaaz", "sambar ulli", "chinna ulli"],
+    "potato": ["aloo", "alu", "chikka aloo", "batata", "urulai kazhangu"],
+    "baby_potato": ["baby aloo", "baby batata"],
+    "sweet_potato": ["shakarkand", "shakarkandi", "genasu"],
+    "carrot": ["gajar", "gajar", "carrot", "padavalakayi"],
+    "cucumber": ["sowthekaayi", "kheera", "kakdi"],
+    "brinjal": ["baingan", "vankaya", "kathirikai", "eggplant", "aubergine"],
+    "capsicum": ["shimla mirch", "donna mirchi", "kudaimilagai"],
+    "bell_pepper": ["bell pepper", "capsicum shimla", "kudaimilagai"],
+    "cauliflower": ["gobhi", "phool gobhi", "hogekayi"],
+    "broccoli": ["broccoli", "broccoli gobhi"],
+    "ridge_gourd": ["turai", "toraai", "peerkangai", "heerekayi"],
+    "bottle_gourd": ["lauki", "dudhi", "sorekayi"],
+    "bitter_gourd": ["karela", "pavakka", "kagalkayi"],
+    "snake_gourd": ["chichinda", "pudalanga", "padavalakayi"],
+    "pointed_gourd": ["parwal", "paraval", "tindora"],
+    "cluster_beans": ["guar", "guar phali", "kothavarangai"],
+    "french_beans": ["beans", "green beans", "hara phali", "farasbi"],
+    "ladys_finger": ["bhindi", "okra", "vendakkai"],
+    "drumstick": ["moringa", "nuggekaayi", "murungakkai"],
+    "beetroot": ["chukandar", "beetroot", "beet"],
+    "radish": ["mooli", "mooli", "mullangi", "mula"],
+    "raw_banana": ["kaccha kela", "vazhakkai"],
+    "raw_mango": ["kaccha aam", "manga", "mamidi"],
+    "yam": ["suran", "elephant foot yam", "senai"],
+    "colocasia": ["arbi", "arvi", "seppankizhangu"],
+    "zucchini": ["turai chini", "courgette"],
+    "red_cabbage": ["laal gobhi", "red cabbage"],
+    # ── Herbs & spices ──
+    "coriander": ["dhania", "cilantro", "kothambari", "kothamalli"],
+    "curry_leaves": ["kadi patta", "karibevu", "karivepaku", "kadi leaves"],
+    "mint": ["pudina", "pudina", "pudhina"],
+    "green_chilli": ["hari mirch", "hasi menasu", "pachai milagai", "mirchi"],
+    "garlic": ["lehsun", "lasun", "vellulli"],
+    "ginger": ["adrak", "allam", "inji"],
+    # ── Dairy & staples ──
+    "curd": ["dahi", "yogurt", "mosaru", "perugu", "thayir"],
+    "milk": ["doodh", "khir", "paal", "paal", "halu", "milkk"],
+    "paneer": ["paneer", "cottage cheese", "panir"],
+    "wheat flour": ["atta", "aata", "godhi hittu"],
+    "rice": ["chawal", "akki", "arisi"],
+    "lentils": ["dal", "daal", "pappu", "paruppu"],
+    "coconut": ["nariyal", "narkel", "tengina kayi"],
+    "mustard_seeds": ["rai", "sarson", "sasive"],
+    "turmeric": ["haldi", "arishina"],
+    "cumin": ["jeera", "jeerige"],
+    "fenugreek": ["methi", "methi seeds", "menthya"],
+    "black_pepper": ["kali mirch", "kali menasu", "milagu"],
+    # ── Fruits ──
+    "banana": ["kela", "balehannu", "vaazhai pazham"],
+    "mango": ["aam", "mavina kayi", "maanga"],
+    "apple": ["seb", "apple"],
+    "orange": ["santara", "santra", "kintoor"],
+    "grapes": ["angoor", "drakshi"],
+    "papaya": ["papita", "pappali", "babbakayi"],
+    "pineapple": ["ananas", "ananasina hayi"],
+    # ── Grains & pulses ──
+    "moong_dal": ["moong dal", "hesaru bele", "pasiparuppu"],
+    "toor_dal": ["toor dal", "tovar dal", "sambar powder dal", "thuvaram paruppu"],
+    "chana_dal": ["chana dal", "kadalai paruppu"],
+    "urad_dal": ["urad dal", "uzhunnu paruppu"],
+    "besan": ["gram flour", "chickpea flour", "kadle hittu"],
+    # ── Condiments & other ──
+    "sugar": ["cheeni", "sakare", "sarkarai"],
+    "salt": ["namak", "uppu"],
+    "oil": ["tel", "enne", "ennai"],
+    "ghee": ["ghee", "neyyi", "nei"],
+    "vinegar": ["sirka", "vinagiri"],
+}
+
+
+
+CANONICAL_MAP = _CANONICAL_MAP
+
+def resolve_canonical(query: str) -> str | None:
+    if not query:
+        return None
+    q = query.strip().lower()
+    
+    # 1. Exact match in CANONICAL_MAP
+    if q in CANONICAL_MAP:
+        return CANONICAL_MAP[q]
+        
+    # 2. Exact match in ITEM_ALIASES keys
+    if q in ITEM_ALIASES:
+        return q
+        
+    # 3. Substring match in CANONICAL_MAP keys
+    for key, val in CANONICAL_MAP.items():
+        if key in q or q in key:
+            return val
+            
+    # 4. Alias lookup using ITEM_ALIASES
+    q_clean = re.sub(r"[^\w\s]", " ", q).strip()
+    q_clean = re.sub(r"\s+", " ", q_clean)
+    for canonical, aliases in ITEM_ALIASES.items():
+        if q_clean == canonical or q_clean in aliases:
+            return canonical
+        for alias in aliases:
+            if alias in q_clean or q_clean in alias:
+                return canonical
+                
+    return None
+
+
+def normalize_item_name(name: str) -> str:
+    """Normalize a user-supplied item name: clean punctuation + resolve aliases.
+
+    This is the canonical normalization for user-input and inventory matching.
+    Market-data normalization uses ``canonicalize_name`` instead.
+    """
+    normal = re.sub(r"[^\w\s]", " ", name.lower()).strip()
+    normal = re.sub(r"\s+", " ", normal)
+    for canonical, aliases in ITEM_ALIASES.items():
+        if normal == canonical or normal in aliases:
+            return canonical
+    return normal
+
+
+def canonicalize_name(raw_name: str) -> tuple[str, str, list[str]]:
+    cleaned = _clean_name(raw_name)
+    is_combo = _detect_combo(raw_name)
+    components: list[str] = []
+
+    if is_combo:
+        components = _extract_combo_components(cleaned)
+        slug_parts = [c for c in components if c]
+        if slug_parts:
+            slug = "combo_" + "_".join(slug_parts[:5])
+        else:
+            slug = "combo_" + cleaned.replace(" ", "_")[:40]
+        return slug, "", components
+
+    lowered = cleaned.lower()
+    canonical = _CANONICAL_MAP.get(lowered, "")
+    if not canonical:
+        for key, val in _CANONICAL_MAP.items():
+            if key in lowered or lowered in key:
+                canonical = val
+                break
+    if not canonical:
+        canonical = lowered.replace(" ", "_")[:40]
+
+    variety = ""
+    if raw_name != cleaned:
+        paren = re.search(r"\(([^)]+)\)", raw_name)
+        if paren:
+            variety = paren.group(1)
+
+    return canonical, variety, []
+
+
+def _clean_name(name: str) -> str:
+    cleaned = re.sub(r"\s*-\s*.*$", "", name)
+    cleaned = re.sub(r"\s*\([^)]*\)\s*", " ", cleaned).strip()
+    # Strip apostrophes so "Lady's Finger" normalises to "ladys finger" (matches canonical map)
+    cleaned = cleaned.replace("'", "")
+    cleaned = re.sub(r"\s+", " ", cleaned)
+    prefixes = ("nectr ", "pluckk ozone washed ", "pluckk ", "freshcon cooked ", "urban harvest ")
+    for prefix in prefixes:
+        if cleaned.lower().startswith(prefix):
+            cleaned = cleaned[len(prefix):]
+            break
+    cleaned = re.sub(r"\s+\(chemical free\)", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+chemical free", "", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+protected cultivation", "", cleaned, flags=re.IGNORECASE)
+    return cleaned.strip()
+
+
+def _detect_combo(name: str) -> bool:
+    lowered = name.lower()
+    if "combo" in lowered:
+        return True
+    if " & " in lowered or "&" in lowered:
+        parts = [p.strip() for p in lowered.split("&") if p.strip()]
+        if len(parts) >= 2:
+            return True
+    if "herbs mix" in lowered:
+        return True
+    if "sambar veg" in lowered:
+        return True
+    return False
+
+
+def _extract_combo_components(cleaned_name: str) -> list[str]:
+    lowered = cleaned_name.lower()
+    if "herbs mix" in lowered:
+        return ["curry_leaves", "coriander", "mint"]
+    if "sambar veg" in lowered:
+        return ["drumstick", "radish", "cluster_beans", "ladys_finger"]
+
+    parts = re.split(r"[,&]|, and | and ", lowered)
+    components: list[str] = []
+    for part in parts:
+        part = part.strip()
+        if not part:
+            continue
+        clean_part = _clean_name(part)
+        canonical = _CANONICAL_MAP.get(clean_part, "")
+        if not canonical:
+            for key, val in _CANONICAL_MAP.items():
+                if key in clean_part:
+                    canonical = val
+                    break
+        if not canonical:
+            canonical = clean_part.replace(" ", "_")[:30]
+        components.append(canonical)
+    return components

shopstack/market/schema.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class NormalizedMarketRecord:
+    source: str
+    source_category: str
+    raw_name: str
+    canonical_name: str
+    description: str
+    raw_size: str
+    normalized_quantity: float | None
+    normalized_unit: str | None
+    package_count: int
+    is_combo: bool
+    is_weight_based: bool
+    is_piece_based: bool
+    is_size_class: bool
+    size_class: str
+    price_inr: float
+    mrp_inr: float
+    discount_percent_displayed: float
+    discount_amount_inr: float
+    computed_discount_percent: float
+    availability: str
+    is_available: bool
+    tag: str
+    is_ad: bool
+    is_upgrade: bool
+    card_index: int
+    delivery_time: str
+    captured_at: str
+    snapshot_id: str
+    price_per_kg: float | None
+    price_per_100g: float | None
+    price_per_piece: float | None
+    normalization_warnings: list[str] = field(default_factory=list)
+    component_names: list[str] = field(default_factory=list)
+    variety: str = ""
+    brand: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": self.source,
+            "source_category": self.source_category,
+            "raw_name": self.raw_name,
+            "canonical_name": self.canonical_name,
+            "description": self.description,
+            "raw_size": self.raw_size,
+            "normalized_quantity": self.normalized_quantity,
+            "normalized_unit": self.normalized_unit,
+            "package_count": self.package_count,
+            "is_combo": self.is_combo,
+            "is_weight_based": self.is_weight_based,
+            "is_piece_based": self.is_piece_based,
+            "is_size_class": self.is_size_class,
+            "size_class": self.size_class,
+            "price_inr": self.price_inr,
+            "mrp_inr": self.mrp_inr,
+            "discount_percent_displayed": self.discount_percent_displayed,
+            "discount_amount_inr": self.discount_amount_inr,
+            "computed_discount_percent": self.computed_discount_percent,
+            "availability": self.availability,
+            "is_available": self.is_available,
+            "tag": self.tag,
+            "is_ad": self.is_ad,
+            "is_upgrade": self.is_upgrade,
+            "card_index": self.card_index,
+            "delivery_time": self.delivery_time,
+            "captured_at": self.captured_at,
+            "snapshot_id": self.snapshot_id,
+            "price_per_kg": self.price_per_kg,
+            "price_per_100g": self.price_per_100g,
+            "price_per_piece": self.price_per_piece,
+            "normalization_warnings": self.normalization_warnings,
+            "component_names": self.component_names,
+            "variety": self.variety,
+            "brand": self.brand,
+        }
+
+
+@dataclass
+class MarketSnapshot:
+    snapshot_id: str
+    source: str
+    source_category: str
+    captured_at: str
+    raw_records: list[dict[str, Any]]
+    normalized_records: list[NormalizedMarketRecord]
+    analytics: dict[str, Any] = field(default_factory=dict)

shopstack/market/sources/__init__.py

@@ -0,0 +1,79 @@
+"""Market source abstraction — adapters and repository for market data sources.
+
+This package defines the MarketSourceAdapter protocol that every market data
+source (Swiggy, Blinkit, Zepto, DMart, etc.) must implement, plus a
+MarketSnapshotRepository for caching and storing snapshots.
+
+New sources register via SourceRegistry::
+
+    from shopstack.market.sources import SourceRegistry, build_registry
+
+    registry = build_registry()  # registers all available sources
+    snapshot = registry.load("swiggy")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from shopstack.market.sources._adapter import MarketSourceAdapter, MarketSourceError
+from shopstack.market.sources._registry import SourceRegistry
+from shopstack.market.sources._repository import MarketSnapshotRepository, snapshot_freshness
+from shopstack.market.sources._swiggy_adapter import SwiggyAdapter
+from shopstack.market.sources._blinkit_adapter import BlinkitAdapter
+from shopstack.market.sources._zepto_adapter import ZeptoAdapter
+from shopstack.market.sources._dmart_adapter import DmartAdapter
+from shopstack.market.sources._comparison import (
+    CrossSourcePrice,
+    compare_across_sources,
+    format_cross_source_html,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def build_registry(repository: MarketSnapshotRepository | None = None, data_dir: Path | None = None) -> SourceRegistry:
+    """Construct a fully-populated SourceRegistry with all available market sources.
+
+    Each adapter is constructed inside a try/except so that any adapter init failure
+    doesn't prevent the registry from being built — failures simply log a warning.
+    Missing data files are handled gracefully at load_snapshot() time.
+    """
+    registry = SourceRegistry(repository=repository)
+
+    sources: list[tuple[str, MarketSourceAdapter]] = []
+
+    for adapter_cls, source_id in [
+        (SwiggyAdapter, "swiggy"),
+        (BlinkitAdapter, "blinkit"),
+        (ZeptoAdapter, "zepto"),
+        (DmartAdapter, "dmart"),
+    ]:
+        try:
+            adapter = adapter_cls(data_dir=data_dir)
+            sources.append((source_id, adapter))
+        except Exception as exc:
+            logger.warning("Failed to create adapter %s: %s", source_id, exc)
+
+    for source_id, adapter in sources:
+        registry.register(source_id, adapter)
+
+    return registry
+
+
+__all__ = [
+    "MarketSourceAdapter",
+    "MarketSourceError",
+    "MarketSnapshotRepository",
+    "SourceRegistry",
+    "build_registry",
+    "SwiggyAdapter",
+    "BlinkitAdapter",
+    "ZeptoAdapter",
+    "DmartAdapter",
+    "CrossSourcePrice",
+    "compare_across_sources",
+    "format_cross_source_html",
+    "snapshot_freshness",
+]

shopstack/market/sources/_adapter.py

@@ -0,0 +1,70 @@
+"""MarketSourceAdapter — protocol for pluggable market data sources.
+
+Every source (Swiggy, Blinkit, Zepto, DMart, etc.) implements this protocol
+so the decision engine and basket optimizer can work with any source uniformly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Protocol, runtime_checkable
+
+from shopstack.market.schema import MarketSnapshot
+
+
+class MarketSourceError(Exception):
+    pass
+
+
+@runtime_checkable
+class MarketSourceAdapter(Protocol):
+    """Protocol each market source must satisfy.
+
+    A market source is anything that can produce a MarketSnapshot:
+    an API client, a CSV file reader, a web scraper, etc.
+    """
+
+    source_id: str
+    source_category: str
+
+    def load_snapshot(self) -> MarketSnapshot:
+        """Load the latest snapshot from this source.
+
+        Returns a fully normalized MarketSnapshot ready for analytics.
+        Raises MarketSourceError on failure.
+        """
+        ...
+
+    def freshness(self, snapshot: MarketSnapshot) -> dict[str, Any]:
+        """Return freshness metadata for a snapshot from this source.
+
+        Returns dict with keys:
+          - age_days: int
+          - is_stale: bool
+          - label: str (human-readable freshness description)
+          - captured_at: str
+        """
+        ...
+
+    def available_canonical_names(self, snapshot: MarketSnapshot) -> set[str]:
+        """Return the set of canonical names available in this snapshot."""
+        ...
+
+
+@dataclass
+class SourceMetadata:
+    """Persisted metadata about a market source and its snapshots."""
+
+    source_id: str
+    source_category: str
+    last_snapshot_id: str = ""
+    last_captured_at: str = ""
+    snapshot_count: int = 0
+    total_records: int = 0
+    created_at: str = ""
+    updated_at: str = ""
+
+    @classmethod
+    def now(cls) -> str:
+        return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")

shopstack/market/sources/_blinkit_adapter.py

@@ -0,0 +1,84 @@
+"""Blinkit market source adapter — thin config over shared JSON adapter."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+from shopstack.market.sources._adapter import MarketSourceAdapter
+from shopstack.market.sources._json_adapter import (
+    JsonSourceConfig,
+    _normalize_record_shared,
+    _load_raw_json,
+    snapshot_freshness,
+    load_snapshot as _shared_load_snapshot,
+)
+
+SOURCE_ID = "blinkit"
+SOURCE_CATEGORY = "fresh_vegetables"
+DEFAULT_SNAPSHOT_ID = f"{SOURCE_ID}_{SOURCE_CATEGORY}_2026-06-06"
+DEFAULT_CAPTURED_AT = "2026-06-06"
+
+CONFIG = JsonSourceConfig(
+    source_id=SOURCE_ID,
+    source_category=SOURCE_CATEGORY,
+    file_glob="blinkit_fresh_vegetables_*.json",
+    name_field="product_name",
+    price_field="offer_price",
+    original_price_field="mrp",
+)
+
+
+def load_raw(data_dir: Path | None = None):
+    return _load_raw_json(CONFIG.file_glob, data_dir)
+
+
+def load_snapshot(
+    data_dir: Path | None = None,
+    snapshot_id: str | None = None,
+    captured_at: str | None = None,
+):
+    return _shared_load_snapshot(CONFIG, data_dir=data_dir, snapshot_id=snapshot_id, captured_at=captured_at)
+
+
+def normalize_record(
+    raw: dict[str, Any],
+    snapshot_id: str = DEFAULT_SNAPSHOT_ID,
+    captured_at: str = DEFAULT_CAPTURED_AT,
+) -> Any:
+    from dataclasses import replace
+    cfg = replace(CONFIG, captured_at=captured_at)
+    return _normalize_record_shared(raw, cfg)
+
+
+class BlinkitAdapter(MarketSourceAdapter):
+    source_id: str = SOURCE_ID
+    source_category: str = SOURCE_CATEGORY
+
+    def __init__(self, data_dir: Path | None = None):
+        self._data_dir = data_dir
+
+    def load_snapshot(self) -> MarketSnapshot:
+        return _shared_load_snapshot(CONFIG, data_dir=self._data_dir)
+
+    def freshness(self, snapshot: MarketSnapshot) -> dict[str, Any]:
+        return snapshot_freshness(snapshot, today=date.today())
+
+    def available_canonical_names(self, snapshot: MarketSnapshot) -> set[str]:
+        from shopstack.market.analytics import available_canonical_names as _available
+        return _available(snapshot)
+
+
+__all__ = [
+    "BlinkitAdapter",
+    "CONFIG",
+    "DEFAULT_CAPTURED_AT",
+    "DEFAULT_SNAPSHOT_ID",
+    "SOURCE_ID",
+    "load_raw",
+    "load_snapshot",
+    "normalize_record",
+    "snapshot_freshness",
+]

shopstack/market/sources/_comparison.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from html import escape
+from typing import Any
+
+from shopstack.market.sources._registry import SourceRegistry
+
+
+@dataclass
+class CrossSourcePrice:
+    canonical_name: str
+    prices: dict[str, float]
+    best_source: str
+    savings_pct: float
+
+
+def _best_weight_option(records: list[Any]) -> float | None:
+    candidates = [
+        r for r in records
+        if not r.is_combo and r.is_available and r.price_per_kg is not None
+    ]
+    if not candidates:
+        candidates = [
+            r for r in records
+            if not r.is_combo and r.is_available
+        ]
+        if not candidates:
+            return None
+        return min(r.price_inr for r in candidates)
+    return min(r.price_per_kg for r in candidates)
+
+
+def compare_across_sources(
+    registry: SourceRegistry,
+    canonical_name: str,
+) -> CrossSourcePrice | None:
+    snapshots = registry.all_snapshots()
+    if not snapshots:
+        return None
+
+    prices: dict[str, float] = {}
+    for source_id, snap in snapshots.items():
+        records = [
+            r for r in snap.normalized_records
+            if r.canonical_name == canonical_name
+        ]
+        if not records:
+            continue
+        best = _best_weight_option(records)
+        if best is not None:
+            prices[source_id] = best
+
+    if len(prices) < 2:
+        return None
+
+    best_source = min(prices, key=lambda s: prices[s])
+    worst_source = max(prices, key=lambda s: prices[s])
+    best_price = prices[best_source]
+    worst_price = prices[worst_source]
+    savings_pct = round((worst_price - best_price) / worst_price * 100) if worst_price > 0 else 0
+
+    return CrossSourcePrice(
+        canonical_name=canonical_name,
+        prices=prices,
+        best_source=best_source,
+        savings_pct=savings_pct,
+    )
+
+
+def format_cross_source_html(comparisons: list[CrossSourcePrice]) -> str:
+    if not comparisons:
+        return ""
+
+    source_ids: set[str] = set()
+    for c in comparisons:
+        source_ids.update(c.prices.keys())
+    sorted_sources = sorted(source_ids)
+
+    header_cells = "".join(
+        f"<th style='text-align:right;padding:4px;'>{escape(s.title())}</th>"
+        for s in sorted_sources
+    )
+
+    rows: list[str] = []
+    for c in comparisons:
+        name_label = escape(c.canonical_name.replace("_", " ").title())
+        price_cells = ""
+        for sid in sorted_sources:
+            price = c.prices.get(sid)
+            if price is None:
+                price_cells += "<td style='text-align:right;padding:4px;color:var(--text-dim);'>--</td>"
+            elif sid == c.best_source:
+                price_cells += f"<td style='text-align:right;padding:4px;color:var(--green);font-weight:600;'>&#8377;{price:.0f}</td>"
+            else:
+                price_cells += f"<td style='text-align:right;padding:4px;'>&#8377;{price:.0f}</td>"
+
+        savings_label = f"save {c.savings_pct}%" if c.savings_pct > 0 else ""
+        rows.append(
+            f"<tr>"
+            f"<td style='padding:4px;'><strong>{name_label}</strong></td>"
+            f"{price_cells}"
+            f"<td style='padding:4px;color:var(--green);'>{savings_label}</td>"
+            f"</tr>"
+        )
+
+    return (
+        f"<div class='home-card' style='text-align:left;margin-bottom:12px;'>"
+        f"<h3>Multi-Source Price Comparison</h3>"
+        f"<table style='width:100%;border-collapse:collapse;font-size: 0.75rem;'>"
+        f"<thead><tr style='border-bottom:2px solid var(--border);'>"
+        f"<th style='text-align:left;padding:4px;'>Item</th>"
+        f"{header_cells}"
+        f"<th style='text-align:left;padding:4px;'>Savings</th>"
+        f"</tr></thead>"
+        f"<tbody>{''.join(rows)}</tbody>"
+        f"</table></div>"
+    )
+
+
+__all__ = ["CrossSourcePrice", "compare_across_sources", "format_cross_source_html"]

shopstack/market/sources/_dmart_adapter.py

@@ -0,0 +1,84 @@
+"""DMart market source adapter — thin config over shared JSON adapter."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+from shopstack.market.sources._adapter import MarketSourceAdapter
+from shopstack.market.sources._json_adapter import (
+    JsonSourceConfig,
+    _normalize_record_shared,
+    _load_raw_json,
+    snapshot_freshness,
+    load_snapshot as _shared_load_snapshot,
+)
+
+SOURCE_ID = "dmart"
+SOURCE_CATEGORY = "fresh_vegetables"
+DEFAULT_SNAPSHOT_ID = f"{SOURCE_ID}_{SOURCE_CATEGORY}_2026-06-06"
+DEFAULT_CAPTURED_AT = "2026-06-06"
+
+CONFIG = JsonSourceConfig(
+    source_id=SOURCE_ID,
+    source_category=SOURCE_CATEGORY,
+    file_glob="dmart_fresh_vegetables_*.json",
+    name_field="product",
+    price_field="current_price",
+    original_price_field="listed_price",
+)
+
+
+def load_raw(data_dir: Path | None = None):
+    return _load_raw_json(CONFIG.file_glob, data_dir)
+
+
+def load_snapshot(
+    data_dir: Path | None = None,
+    snapshot_id: str | None = None,
+    captured_at: str | None = None,
+):
+    return _shared_load_snapshot(CONFIG, data_dir=data_dir, snapshot_id=snapshot_id, captured_at=captured_at)
+
+
+def normalize_record(
+    raw: dict[str, Any],
+    snapshot_id: str = DEFAULT_SNAPSHOT_ID,
+    captured_at: str = DEFAULT_CAPTURED_AT,
+) -> Any:
+    from dataclasses import replace
+    cfg = replace(CONFIG, captured_at=captured_at)
+    return _normalize_record_shared(raw, cfg)
+
+
+class DmartAdapter(MarketSourceAdapter):
+    source_id: str = SOURCE_ID
+    source_category: str = SOURCE_CATEGORY
+
+    def __init__(self, data_dir: Path | None = None):
+        self._data_dir = data_dir
+
+    def load_snapshot(self) -> MarketSnapshot:
+        return _shared_load_snapshot(CONFIG, data_dir=self._data_dir)
+
+    def freshness(self, snapshot: MarketSnapshot) -> dict[str, Any]:
+        return snapshot_freshness(snapshot, today=date.today())
+
+    def available_canonical_names(self, snapshot: MarketSnapshot) -> set[str]:
+        from shopstack.market.analytics import available_canonical_names as _available
+        return _available(snapshot)
+
+
+__all__ = [
+    "DmartAdapter",
+    "CONFIG",
+    "DEFAULT_CAPTURED_AT",
+    "DEFAULT_SNAPSHOT_ID",
+    "SOURCE_ID",
+    "load_raw",
+    "load_snapshot",
+    "normalize_record",
+    "snapshot_freshness",
+]

shopstack/market/sources/_json_adapter.py

@@ -0,0 +1,218 @@
+"""Shared base for JSON-file-backed market source adapters.
+
+Blinkit, Zepto, and DMart adapters are structurally identical except for:
+  - source ID
+  - JSON file glob pattern
+  - raw-record field names for product name and price
+  - price calculation logic
+
+This module extracts the common code so each adapter is a thin config.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shopstack.market.normalization import (
+    SizeParseResult,
+    canonicalize_name,
+    compute_unit_prices,
+    parse_size,
+)
+from shopstack.market.schema import MarketSnapshot, NormalizedMarketRecord
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_DATA_DIR = Path(__file__).resolve().parents[3] / "data"
+FRESHNESS_WARNING_DAYS = 1
+
+
+# ── Shared helpers ─────────────────────────────────────────────────────
+
+
+def _coerce_float(val: Any, default: float = 0.0) -> float:
+    if val is None or val == "":
+        return default
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return default
+
+
+def _coerce_int(val: Any, default: int = 0) -> int:
+    if val is None or val == "":
+        return default
+    try:
+        return int(val)
+    except (ValueError, TypeError):
+        return default
+
+
+def _find_json(glob_pattern: str, data_dir: Path | None = None) -> Path:
+    d = data_dir or _DEFAULT_DATA_DIR
+    candidates = sorted(d.glob(glob_pattern))
+    if not candidates:
+        raise FileNotFoundError(f"No {glob_pattern} found in {d}")
+    return candidates[-1]
+
+
+def _load_raw_json(glob_pattern: str, data_dir: Path | None = None) -> list[dict[str, Any]]:
+    fp = _find_json(glob_pattern, data_dir)
+    with open(fp, encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ── Per-source config ──────────────────────────────────────────────────
+
+
+@dataclass
+class JsonSourceConfig:
+    source_id: str
+    source_category: str
+    file_glob: str
+    name_field: str
+    price_field: str
+    original_price_field: str
+    captured_at: str = "2026-06-06"
+
+    @property
+    def snapshot_id(self) -> str:
+        return f"{self.source_id}_{self.source_category}_{self.captured_at}"
+
+    def extract_price(self, raw: dict[str, Any]) -> tuple[float, float]:
+        """Return (price, mrp) from a raw record. Override for custom logic."""
+        price = _coerce_float(raw.get(self.price_field))
+        mrp = _coerce_float(raw.get(self.original_price_field))
+        if price <= 0:
+            price = mrp
+        if mrp <= 0 or mrp == price:
+            mrp = price
+        return price, mrp
+
+
+# ── Shared normalization ───────────────────────────────────────────────
+
+
+def _normalize_record_shared(
+    raw: dict[str, Any],
+    config: JsonSourceConfig,
+) -> NormalizedMarketRecord:
+    raw_name = str(raw.get(config.name_field, "")).strip()
+    raw_size = str(raw.get("size", "")).strip()
+
+    canonical, variety, components = canonicalize_name(raw_name)
+    size_result: SizeParseResult = parse_size(raw_size)
+
+    is_combo = len(components) > 1 or size_result.is_combo
+    availability = str(raw.get("availability", "")).strip()
+    is_available = availability.lower() == "available"
+
+    price, mrp = config.extract_price(raw)
+
+    unit_prices = compute_unit_prices(
+        price=price,
+        quantity=size_result.normalized_quantity,
+        unit=size_result.normalized_unit,
+        is_weight_based=size_result.is_weight_based,
+        is_piece_based=size_result.is_piece_based,
+    )
+
+    discount_amount = mrp - price if mrp > price else 0.0
+    computed_discount = round(discount_amount / mrp * 100, 1) if mrp > 0 else 0.0
+
+    warnings: list[str] = list(size_result.warnings or [])
+
+    return NormalizedMarketRecord(
+        source=config.source_id,
+        source_category=config.source_category,
+        raw_name=raw_name,
+        canonical_name=canonical,
+        description=str(raw.get("description", "")).strip(),
+        raw_size=raw_size,
+        normalized_quantity=size_result.normalized_quantity,
+        normalized_unit=size_result.normalized_unit,
+        package_count=size_result.package_count,
+        is_combo=is_combo,
+        is_weight_based=size_result.is_weight_based,
+        is_piece_based=size_result.is_piece_based,
+        is_size_class=size_result.is_size_class,
+        size_class=size_result.size_class,
+        price_inr=price,
+        mrp_inr=mrp,
+        discount_percent_displayed=_coerce_float(raw.get("discount_percent")),
+        discount_amount_inr=discount_amount,
+        computed_discount_percent=computed_discount,
+        availability=availability,
+        is_available=is_available,
+        tag=str(raw.get("tag", "")).strip(),
+        is_ad=str(raw.get("tag", "")).strip().lower() == "ad",
+        is_upgrade=str(raw.get("tag", "")).strip().lower() == "upgrade",
+        card_index=_coerce_int(raw.get("card_index")),
+        delivery_time=str(raw.get("delivery_time", "")).strip(),
+        captured_at=config.captured_at,
+        snapshot_id=config.snapshot_id,
+        price_per_kg=unit_prices["price_per_kg"],
+        price_per_100g=unit_prices["price_per_100g"],
+        price_per_piece=unit_prices["price_per_piece"],
+        normalization_warnings=warnings,
+        component_names=components or [],
+        variety=variety,
+        brand=str(raw.get("brand", "")).strip(),
+    )
+
+
+def load_snapshot(
+    config: JsonSourceConfig,
+    data_dir: Path | None = None,
+    snapshot_id: str | None = None,
+    captured_at: str | None = None,
+) -> MarketSnapshot:
+    raw_records = _load_raw_json(config.file_glob, data_dir)
+    sid = snapshot_id or config.snapshot_id
+    cat = captured_at or config.captured_at
+
+    from dataclasses import replace
+    cfg = replace(config, captured_at=cat)
+
+    normalized = [_normalize_record_shared(r, cfg) for r in raw_records]
+
+    return MarketSnapshot(
+        snapshot_id=sid,
+        source=config.source_id,
+        source_category=config.source_category,
+        captured_at=cat,
+        raw_records=raw_records,
+        normalized_records=normalized,
+    )
+
+
+def snapshot_freshness(snapshot: MarketSnapshot, today: date | None = None) -> dict[str, Any]:
+    current = today or date.today()
+    try:
+        captured = date.fromisoformat(snapshot.captured_at[:10])
+    except (ValueError, TypeError):
+        return {
+            "captured_at": snapshot.captured_at,
+            "age_days": None,
+            "is_stale": True,
+            "label": f"Snapshot date unclear: {snapshot.captured_at or 'unknown'}",
+        }
+
+    age_days = (current - captured).days
+    if age_days <= 0:
+        label = f"Captured today ({snapshot.captured_at})"
+    elif age_days == 1:
+        label = f"Captured yesterday ({snapshot.captured_at})"
+    else:
+        label = f"Captured {age_days} days ago ({snapshot.captured_at})"
+    return {
+        "captured_at": snapshot.captured_at,
+        "age_days": age_days,
+        "is_stale": age_days > FRESHNESS_WARNING_DAYS,
+        "label": label,
+    }

shopstack/market/sources/_registry.py

@@ -0,0 +1,117 @@
+"""SourceRegistry — pluggable registry of market source adapters.
+
+New sources (Blinkit, Zepto, DMart, etc.) are registered once at startup.
+All service-level code resolves market data through this registry, never
+by importing a specific source directly.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+from shopstack.market.sources._adapter import MarketSourceAdapter
+from shopstack.market.sources._repository import MarketSnapshotRepository
+
+logger = logging.getLogger(__name__)
+
+
+class SourceRegistry:
+    """Registry of available market source adapters.
+
+    Usage::
+
+        registry = SourceRegistry()
+        registry.register("swiggy", SwiggyAdapter())
+
+        # Load from a specific source
+        snap = registry.load("swiggy")
+
+        # Or discover sources for a category
+        for source in registry.for_category("fresh_vegetables"):
+            snap = registry.load(source.source_id)
+
+    """
+
+    def __init__(self, repository: MarketSnapshotRepository | None = None):
+        self._adapters: dict[str, MarketSourceAdapter] = {}
+        self._repository = repository or MarketSnapshotRepository()
+
+    def register(self, source_id: str, adapter: MarketSourceAdapter) -> None:
+        if not isinstance(adapter, MarketSourceAdapter):
+            logger.warning(
+                "Adapter for %s does not satisfy MarketSourceAdapter protocol",
+                source_id,
+            )
+        self._adapters[source_id] = adapter
+        logger.info("Registered market source: %s (%s)", source_id, adapter.source_category)
+
+    def registered(self) -> list[str]:
+        return list(self._adapters.keys())
+
+    def get(self, source_id: str) -> MarketSourceAdapter:
+        adapter = self._adapters.get(source_id)
+        if adapter is None:
+            raise KeyError(f"Unknown market source: {source_id}. Registered: {list(self._adapters)}")
+        return adapter
+
+    def load(self, source_id: str) -> MarketSnapshot:
+        adapter = self.get(source_id)
+        snapshot = adapter.load_snapshot()
+        self._repository.store(snapshot)
+        return snapshot
+
+    def load_all(self, timeout_per_source: float = 5.0) -> dict[str, MarketSnapshot]:
+        """Load snapshots for all registered adapters actively.
+
+        Iterates registered adapters, loads each, and returns a dictionary
+        mapping source_id to MarketSnapshot. Failures are logged and skipped.
+        """
+        import concurrent.futures
+        loaded: dict[str, MarketSnapshot] = {}
+        for source_id in list(self._adapters.keys()):
+            try:
+                # Only load if not already in the repository/cache to avoid duplicate overhead
+                snapshot = self._repository.latest(source_id)
+                if snapshot is not None:
+                    loaded[source_id] = snapshot
+                    continue
+
+                with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
+                    future = executor.submit(self.load, source_id)
+                    snapshot = future.result(timeout=timeout_per_source)
+                if snapshot is not None:
+                    loaded[source_id] = snapshot
+            except Exception as exc:
+                logger.warning("Failed to actively load market source %s: %s", source_id, exc)
+                continue
+        return loaded
+
+    def latest(self, source: str) -> MarketSnapshot | None:
+        return self._repository.latest(source)
+
+    def all_sources_latest(self) -> dict[str, MarketSnapshot]:
+        return self.all_snapshots()
+
+    def for_category(self, category: str) -> list[MarketSourceAdapter]:
+        return [a for a in self._adapters.values() if a.source_category == category]
+
+    def all_snapshots(self) -> dict[str, MarketSnapshot]:
+        result: dict[str, MarketSnapshot] = {}
+        for sid in self._adapters:
+            snap = self._repository.latest(sid)
+            if snap is not None:
+                result[sid] = snap
+        return result
+
+    def freshness_of(self, source_id: str) -> dict[str, Any]:
+        snap = self._repository.latest(source_id)
+        if snap is None:
+            return {"source_id": source_id, "is_stale": True, "label": "No snapshot loaded"}
+        adapter = self.get(source_id)
+        return adapter.freshness(snap)
+
+    @property
+    def repository(self) -> MarketSnapshotRepository:
+        return self._repository

shopstack/market/sources/_repository.py

@@ -0,0 +1,202 @@
+"""MarketSnapshotRepository — caching and lifecycle for market snapshots.
+
+Stores snapshots so the same data isn't re-parsed on every dashboard load,
+and tracks freshness metadata so consumers know how current the data is.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+
+logger = logging.getLogger(__name__)
+
+
+class MarketSnapshotRepository:
+    """In-memory snapshot cache with optional persistence.
+
+    The default instance is process-scoped; pass a database to enable
+    cross-session persistence.
+    """
+
+    def __init__(self, db=None):
+        self._cache: dict[str, MarketSnapshot] = {}
+        self._db: Any | None = db
+
+    def store(self, snapshot: MarketSnapshot) -> None:
+        self._cache[snapshot.snapshot_id] = snapshot
+        if self._db is not None:
+            self._persist(snapshot)
+
+    def get(self, snapshot_id: str) -> MarketSnapshot | None:
+        if not snapshot_id:
+            return None
+        if snapshot_id in self._cache:
+            return self._cache[snapshot_id]
+        if self._db is None:
+            return None
+        return self._load_snapshot_from_db(snapshot_id)
+
+    def latest(self, source: str = "") -> MarketSnapshot | None:
+        candidates = list(self._cache.values())
+
+        if not source:
+            if candidates:
+                return max(candidates, key=lambda s: s.captured_at)
+            return self._latest_snapshot_any()
+
+        source = source.strip()
+        candidates = [s for s in candidates if s.source == source]
+        if candidates:
+            return max(candidates, key=lambda s: s.captured_at)
+
+        return self._latest_snapshot_from_db(source)
+
+    def list(self, source: str = "") -> list[MarketSnapshot]:
+        snapshots = list(self._cache.values())
+        if source:
+            snapshots = [s for s in snapshots if s.source == source]
+
+        if self._db is None:
+            snapshots.sort(key=lambda s: s.captured_at, reverse=True)
+            return snapshots
+
+        db_snapshots = self._list_snapshots_from_db(source=source)
+        seen: set[str] = set()
+        merged: list[MarketSnapshot] = []
+        for snap in db_snapshots + snapshots:
+            if snap.snapshot_id in seen:
+                continue
+            seen.add(snap.snapshot_id)
+            merged.append(snap)
+
+        merged.sort(key=lambda s: s.captured_at, reverse=True)
+        return merged
+
+    def clear(self, source: str = "") -> int:
+        if source:
+            keys = [k for k in self._cache if self._cache[k].source == source]
+        else:
+            keys = list(self._cache.keys())
+        for k in keys:
+            del self._cache[k]
+        return len(keys)
+
+    def _load_snapshot_from_db(self, snapshot_id: str) -> MarketSnapshot | None:
+        try:
+            snap = self._db.get_market_snapshot(snapshot_id)
+        except Exception:
+            return None
+        if snap is None:
+            return None
+        self._cache[snap.snapshot_id] = snap
+        return snap
+
+    def _latest_snapshot_from_db(self, source: str | None = None) -> MarketSnapshot | None:
+        if self._db is None:
+            return None
+        source = (source or "").strip()
+        try:
+            if source:
+                row = self._db.conn.execute(
+                    "SELECT snapshot_id FROM market_snapshots WHERE source = ? ORDER BY captured_at DESC LIMIT 1",
+                    (source,),
+                ).fetchone()
+            else:
+                row = self._db.conn.execute(
+                    "SELECT snapshot_id FROM market_snapshots ORDER BY captured_at DESC LIMIT 1"
+                ).fetchone()
+        except Exception as exc:
+            logger.warning("Failed to read latest snapshot from DB: %s", exc)
+            return None
+        if not row:
+            return None
+        return self._load_snapshot_from_db(row["snapshot_id"])
+
+    def _latest_snapshot_any(self) -> MarketSnapshot | None:
+        return self._latest_snapshot_from_db()
+
+    def _list_snapshots_from_db(self, source: str = "") -> list[MarketSnapshot]:
+        if self._db is None:
+            return []
+        try:
+            if source:
+                rows = self._db.conn.execute(
+                    "SELECT snapshot_id FROM market_snapshots WHERE source = ? ORDER BY captured_at DESC",
+                    (source,),
+                ).fetchall()
+            else:
+                rows = self._db.conn.execute(
+                    "SELECT snapshot_id FROM market_snapshots ORDER BY captured_at DESC"
+                ).fetchall()
+        except Exception as exc:
+            logger.warning("Failed to list snapshots from DB: %s", exc)
+            return []
+
+        snapshots: list[MarketSnapshot] = []
+        for row in rows:
+            snap = self._load_snapshot_from_db(row["snapshot_id"])
+            if snap is not None:
+                snapshots.append(snap)
+        return snapshots
+
+    # Backward-compatible API retained for callers that imported `latest` directly.
+    def latest_snapshot(self, source: str = "") -> MarketSnapshot | None:
+        return self.latest(source)
+
+    # Backward-compatible API retained for callers that imported `list` directly.
+    def list_snapshots(self, source: str = "") -> list[MarketSnapshot]:
+        return self.list(source)
+
+    # Keep existing method names for compatibility with `build_registry` callers.
+    def clear_cache(self, source: str = "") -> int:
+        return self.clear(source)
+
+    def get_cache_size(self) -> int:
+        return len(self._cache)
+
+    def _persist(self, snapshot: MarketSnapshot) -> None:
+        if self._db is None:
+            return
+        try:
+            self._db.save_market_snapshot(snapshot)
+        except Exception as exc:
+            logger.warning("Failed to persist snapshot %s: %s", snapshot.snapshot_id, exc)
+
+
+def snapshot_freshness(snapshot: MarketSnapshot) -> dict[str, Any]:
+    """Compute freshness metadata for any MarketSnapshot.
+
+    Returns dict with:
+      - age_days: int
+      - is_stale: bool
+      - label: str
+      - captured_at: str
+    """
+    from datetime import date
+
+    if not snapshot or not snapshot.captured_at:
+        return {"age_days": 0, "is_stale": False, "label": "unknown"}
+
+    try:
+        captured = date.fromisoformat(snapshot.captured_at[:10])
+        age = (date.today() - captured).days
+    except (ValueError, TypeError):
+        return {"age_days": 0, "is_stale": False, "label": "unknown"}
+
+    is_stale = age > 1
+    if age == 0:
+        label = "Today's data"
+    elif age == 1:
+        label = "Yesterday's data"
+    else:
+        label = f"{age} days old"
+
+    return {
+        "age_days": age,
+        "is_stale": is_stale,
+        "label": label,
+        "captured_at": snapshot.captured_at,
+    }

shopstack/market/sources/_swiggy_adapter.py

@@ -0,0 +1,44 @@
+"""SwiggyAdapter — wraps Swiggy market source into MarketSourceAdapter protocol.
+
+This adapter lets the source-agnostic registry (SourceRegistry) treat
+Swiggy like any other market source. New sources (Blinkit, Zepto, DMart)
+should create their own adapter in a separate module and register it.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+from shopstack.market.sources._adapter import MarketSourceAdapter
+from shopstack.market.analytics import available_canonical_names as _swiggy_available
+from shopstack.market.sources.swiggy import (
+    load_snapshot as _load_snapshot,
+    snapshot_freshness as _snapshot_freshness,
+    SOURCE_ID,
+    SOURCE_CATEGORY,
+)
+
+
+class SwiggyAdapter(MarketSourceAdapter):
+    """Adapter wrapping the existing Swiggy loader into the protocol."""
+
+    source_id: str = SOURCE_ID
+    source_category: str = SOURCE_CATEGORY
+
+    def __init__(self, data_dir: Path | None = None):
+        self._data_dir = data_dir
+
+    def load_snapshot(self) -> MarketSnapshot:
+        return _load_snapshot(data_dir=self._data_dir)
+
+    def freshness(self, snapshot: MarketSnapshot) -> dict[str, Any]:
+        return _snapshot_freshness(snapshot, today=date.today())
+
+    def available_canonical_names(self, snapshot: MarketSnapshot) -> set[str]:
+        return _swiggy_available(snapshot)
+
+
+__all__ = ["SwiggyAdapter"]

shopstack/market/sources/_zepto_adapter.py

@@ -0,0 +1,84 @@
+"""Zepto market source adapter — thin config over shared JSON adapter."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from shopstack.market.schema import MarketSnapshot
+from shopstack.market.sources._adapter import MarketSourceAdapter
+from shopstack.market.sources._json_adapter import (
+    JsonSourceConfig,
+    _normalize_record_shared,
+    _load_raw_json,
+    snapshot_freshness,
+    load_snapshot as _shared_load_snapshot,
+)
+
+SOURCE_ID = "zepto"
+SOURCE_CATEGORY = "fresh_vegetables"
+DEFAULT_SNAPSHOT_ID = f"{SOURCE_ID}_{SOURCE_CATEGORY}_2026-06-06"
+DEFAULT_CAPTURED_AT = "2026-06-06"
+
+CONFIG = JsonSourceConfig(
+    source_id=SOURCE_ID,
+    source_category=SOURCE_CATEGORY,
+    file_glob="zepto_fresh_vegetables_*.json",
+    name_field="item_name",
+    price_field="sale_price",
+    original_price_field="original_price",
+)
+
+
+def load_raw(data_dir: Path | None = None):
+    return _load_raw_json(CONFIG.file_glob, data_dir)
+
+
+def load_snapshot(
+    data_dir: Path | None = None,
+    snapshot_id: str | None = None,
+    captured_at: str | None = None,
+):
+    return _shared_load_snapshot(CONFIG, data_dir=data_dir, snapshot_id=snapshot_id, captured_at=captured_at)
+
+
+def normalize_record(
+    raw: dict[str, Any],
+    snapshot_id: str = DEFAULT_SNAPSHOT_ID,
+    captured_at: str = DEFAULT_CAPTURED_AT,
+) -> Any:
+    from dataclasses import replace
+    cfg = replace(CONFIG, captured_at=captured_at)
+    return _normalize_record_shared(raw, cfg)
+
+
+class ZeptoAdapter(MarketSourceAdapter):
+    source_id: str = SOURCE_ID
+    source_category: str = SOURCE_CATEGORY
+
+    def __init__(self, data_dir: Path | None = None):
+        self._data_dir = data_dir
+
+    def load_snapshot(self) -> MarketSnapshot:
+        return _shared_load_snapshot(CONFIG, data_dir=self._data_dir)
+
+    def freshness(self, snapshot: MarketSnapshot) -> dict[str, Any]:
+        return snapshot_freshness(snapshot, today=date.today())
+
+    def available_canonical_names(self, snapshot: MarketSnapshot) -> set[str]:
+        from shopstack.market.analytics import available_canonical_names as _available
+        return _available(snapshot)
+
+
+__all__ = [
+    "ZeptoAdapter",
+    "CONFIG",
+    "DEFAULT_CAPTURED_AT",
+    "DEFAULT_SNAPSHOT_ID",
+    "SOURCE_ID",
+    "load_raw",
+    "load_snapshot",
+    "normalize_record",
+    "snapshot_freshness",
+]

shopstack/market/sources/swiggy.py

@@ -0,0 +1,279 @@
+from __future__ import annotations
+
+import csv
+import json
+import logging
+from datetime import date
+from pathlib import Path
+from typing import Any
+
+from ..normalization import (
+    SizeParseResult,
+    canonicalize_name,
+    compute_unit_prices,
+    parse_size,
+)
+from ..schema import MarketSnapshot, NormalizedMarketRecord
+from shopstack.schemas.models import PriceObservation
+
+logger = logging.getLogger(__name__)
+
+SOURCE_ID = "swiggy"
+SOURCE_CATEGORY = "fresh_vegetables"
+DEFAULT_SNAPSHOT_ID = f"{SOURCE_ID}_{SOURCE_CATEGORY}_2026-06-06"
+DEFAULT_CAPTURED_AT = "2026-06-06"
+FRESHNESS_WARNING_DAYS = 1
+
+_DEFAULT_DATA_DIR = Path(__file__).resolve().parents[3] / "data"
+
+
+def _find_json_file(data_dir: Path | None = None) -> Path:
+    d = data_dir or _DEFAULT_DATA_DIR
+    candidates = sorted(d.glob("swiggy_fresh_vegetables_cards_*.json"))
+    if not candidates:
+        raise FileNotFoundError(
+            f"No swiggy_fresh_vegetables_cards_*.json found in {d}"
+        )
+    return candidates[-1]
+
+
+def _find_csv_file(data_dir: Path | None = None) -> Path:
+    d = data_dir or _DEFAULT_DATA_DIR
+    candidates = sorted(d.glob("swiggy_fresh_vegetables_cards_*.csv"))
+    if not candidates:
+        raise FileNotFoundError(
+            f"No swiggy_fresh_vegetables_cards_*.csv found in {d}"
+        )
+    return candidates[-1]
+
+
+def load_raw_json(data_dir: Path | None = None) -> list[dict[str, Any]]:
+    fp = _find_json_file(data_dir)
+    with open(fp, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def load_raw_csv(data_dir: Path | None = None) -> list[dict[str, Any]]:
+    fp = _find_csv_file(data_dir)
+    with open(fp, encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def load_raw(data_dir: Path | None = None) -> list[dict[str, Any]]:
+    """Load raw Swiggy cards from JSON (preferred) or CSV fallback."""
+    try:
+        return load_raw_json(data_dir)
+    except FileNotFoundError:
+        return load_raw_csv(data_dir)
+
+
+def _coerce_float(val: Any, default: float = 0.0) -> float:
+    if val is None or val == "":
+        return default
+    try:
+        return float(val)
+    except (ValueError, TypeError):
+        return default
+
+
+def _coerce_int(val: Any, default: int = 0) -> int:
+    if val is None or val == "":
+        return default
+    try:
+        return int(val)
+    except (ValueError, TypeError):
+        return default
+
+
+def normalize_record(
+    raw: dict[str, Any],
+    snapshot_id: str = DEFAULT_SNAPSHOT_ID,
+    captured_at: str = DEFAULT_CAPTURED_AT,
+) -> NormalizedMarketRecord:
+    raw_name = str(raw.get("name", "")).strip()
+    raw_size = str(raw.get("size", "")).strip()
+
+    canonical, variety, components = canonicalize_name(raw_name)
+    size_result: SizeParseResult = parse_size(raw_size)
+
+    is_combo = len(components) > 1 or size_result.is_combo
+    tag = str(raw.get("tag", "")).strip()
+    availability = str(raw.get("availability", "")).strip()
+    is_available = availability.lower() == "available"
+
+    price = _coerce_float(raw.get("price_inr"))
+    mrp = _coerce_float(raw.get("mrp_inr"))
+
+    unit_prices = compute_unit_prices(
+        price=price,
+        quantity=size_result.normalized_quantity,
+        unit=size_result.normalized_unit,
+        is_weight_based=size_result.is_weight_based,
+        is_piece_based=size_result.is_piece_based,
+    )
+
+    warnings: list[str] = list(size_result.warnings or [])
+
+    return NormalizedMarketRecord(
+        source=SOURCE_ID,
+        source_category=SOURCE_CATEGORY,
+        raw_name=raw_name,
+        canonical_name=canonical,
+        description=str(raw.get("description", "")).strip(),
+        raw_size=raw_size,
+        normalized_quantity=size_result.normalized_quantity,
+        normalized_unit=size_result.normalized_unit,
+        package_count=size_result.package_count,
+        is_combo=is_combo,
+        is_weight_based=size_result.is_weight_based,
+        is_piece_based=size_result.is_piece_based,
+        is_size_class=size_result.is_size_class,
+        size_class=size_result.size_class,
+        price_inr=price,
+        mrp_inr=mrp,
+        discount_percent_displayed=_coerce_float(
+            raw.get("discount_percent")
+        ),
+        discount_amount_inr=_coerce_float(
+            raw.get("discount_amount_inr")
+        ),
+        computed_discount_percent=_coerce_float(
+            raw.get("computed_discount_percent")
+        ),
+        availability=availability,
+        is_available=is_available,
+        tag=tag,
+        is_ad=tag.lower() == "ad",
+        is_upgrade=tag.lower() == "upgrade",
+        card_index=_coerce_int(raw.get("card_index")),
+        delivery_time=str(raw.get("delivery_time", "")).strip(),
+        captured_at=captured_at,
+        snapshot_id=snapshot_id,
+        price_per_kg=unit_prices["price_per_kg"],
+        price_per_100g=unit_prices["price_per_100g"],
+        price_per_piece=unit_prices["price_per_piece"],
+        normalization_warnings=warnings,
+        component_names=components or [],
+        variety=variety,
+    )
+
+
+def load_snapshot(
+    data_dir: Path | None = None,
+    snapshot_id: str | None = None,
+    captured_at: str | None = None,
+) -> MarketSnapshot:
+    raw_records = load_raw(data_dir)
+    sid = snapshot_id or DEFAULT_SNAPSHOT_ID
+    cat = captured_at or DEFAULT_CAPTURED_AT
+
+    normalized = [normalize_record(r, sid, cat) for r in raw_records]
+
+    return MarketSnapshot(
+        snapshot_id=sid,
+        source=SOURCE_ID,
+        source_category=SOURCE_CATEGORY,
+        captured_at=cat,
+        raw_records=raw_records,
+        normalized_records=normalized,
+    )
+
+
+def snapshot_freshness(snapshot: MarketSnapshot, today: date | None = None) -> dict[str, Any]:
+    """Return freshness metadata for a Swiggy point-in-time snapshot."""
+    current = today or date.today()
+    try:
+        captured = date.fromisoformat(snapshot.captured_at[:10])
+    except (ValueError, TypeError):
+        return {
+            "captured_at": snapshot.captured_at,
+            "age_days": None,
+            "is_stale": True,
+            "label": f"Snapshot date unclear: {snapshot.captured_at or 'unknown'}",
+        }
+
+    age_days = (current - captured).days
+    if age_days <= 0:
+        label = f"Captured today ({snapshot.captured_at})"
+    elif age_days == 1:
+        label = f"Captured yesterday ({snapshot.captured_at})"
+    else:
+        label = f"Captured {age_days} days ago ({snapshot.captured_at})"
+    return {
+        "captured_at": snapshot.captured_at,
+        "age_days": age_days,
+        "is_stale": age_days > FRESHNESS_WARNING_DAYS,
+        "label": label,
+    }
+
+
+def import_swiggy_snapshot_to_db(
+    db: Any,
+    data_dir: Path | None = None,
+    dry_run: bool = False,
+) -> dict[str, Any]:
+    """Import a Swiggy snapshot into the ``price_observations`` table.
+
+    Composes the pure loader (:func:`load_snapshot`) with the DB
+    writer (``db.record_price``). Restores the behavior of the
+    deprecated ``import_swiggy_fresh_vegetables_snapshot``
+    function that was removed in Pass 9 supersession
+    (see Pass 9 addendum: "Add features back to canonical").
+
+    The canonical architecture separates loader (pure) from
+    DB write (this function). Tests for the loader are in
+    :mod:`tests.test_market` (:class:`TestSwiggyLoader`); tests
+    for the DB write are in
+    :mod:`tests.test_market_swiggy_migration`
+    (:class:`TestSwiggyMigrationImport`).
+
+    Args:
+        db: A :class:`shopstack.persistence.database.Database`
+            instance (or any object with a ``record_price``
+            method that takes a :class:`PriceObservation`).
+        data_dir: Optional override for the data directory
+            containing the swiggy JSON/CSV snapshot files.
+        dry_run: If True, parse and validate but don't write
+            to the DB. Useful for smoke testing.
+
+    Returns:
+        A summary dict with ``imported_records``,
+        ``skipped_records``, ``source_event_id``, and
+        ``source_file`` (the path of the loaded snapshot).
+    """
+    snapshot = load_snapshot(data_dir=data_dir)
+    try:
+        captured = date.fromisoformat(snapshot.captured_at[:10])
+    except (ValueError, TypeError):
+        # If the captured_at is malformed, use today as a fallback
+        # so the import still works. This matches the legacy
+        # behavior of the deprecated function.
+        captured = date.today()
+
+    imported = 0
+    skipped = 0
+    for record in snapshot.normalized_records:
+        if record.price_inr <= 0 or (record.normalized_quantity or 0) <= 0:
+            skipped += 1
+            continue
+        observation = PriceObservation(
+            canonical_name=record.canonical_name,
+            quantity=record.normalized_quantity,
+            unit=record.normalized_unit or "unit",
+            price=record.price_inr,
+            currency="INR",
+            store_name="Swiggy Instamart",
+            observation_date=captured,
+            source_event_id=snapshot.snapshot_id,
+            notes=f"raw={record.raw_name}",
+        )
+        if not dry_run:
+            db.record_price(observation)
+        imported += 1
+
+    return {
+        "imported_records": imported,
+        "skipped_records": skipped,
+        "source_event_id": snapshot.snapshot_id,
+        "source_file": str(data_dir or _DEFAULT_DATA_DIR),
+    }

shopstack/memory/waste_patterns.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from shopstack.persistence.database import Database
+
+logger = logging.getLogger(__name__)
+
+
+def compute_waste_pattern(database: Database, canonical_name: str) -> dict[str, Any]:
+    """Compute how often an item is wasted vs consumed.
+
+    Uses the real ``inventory_events`` table. "Wasted" is recorded as
+    ``action = 'discarded'`` and "consumed" as ``action = 'consumed'``;
+    quantity is read from the absolute value of ``quantity_delta``.
+    """
+    try:
+        rows = database.conn.execute(
+            """
+            SELECT action,
+                   COALESCE(SUM(ABS(quantity_delta)), 0.0) AS total_qty
+            FROM inventory_events
+            WHERE canonical_name = ?
+              AND action IN ('discarded', 'consumed')
+              AND quantity_delta IS NOT NULL
+            GROUP BY action
+            """,
+            (canonical_name.lower(),),
+        ).fetchall()
+    except Exception as e:
+        logger.warning("Waste pattern compute failed: %s", e)
+        return {"wasted_qty": 0, "consumed_qty": 0, "waste_rate": 0.0, "total_resolved": 0.0}
+
+    wasted = 0.0
+    consumed = 0.0
+    for r in rows:
+        qty = float(r["total_qty"] or 0.0)
+        if r["action"] == "discarded":
+            wasted = qty
+        elif r["action"] == "consumed":
+            consumed = qty
+
+    total = wasted + consumed
+    waste_rate = (wasted / total) if total > 0 else 0.0
+    return {
+        "wasted_qty": wasted,
+        "consumed_qty": consumed,
+        "waste_rate": waste_rate,
+        "total_resolved": total,
+    }
+
+
+def get_waste_insights(database: Database) -> list[dict[str, Any]]:
+    """Return per-item waste insights aggregated across the whole inventory.
+
+    Scopes the result to items the household has actually moved through
+    the inventory events table.
+    """
+    try:
+        rows = database.conn.execute(
+            """
+            SELECT canonical_name,
+                   action,
+                   COALESCE(SUM(ABS(quantity_delta)), 0.0) AS total_qty
+            FROM inventory_events
+            WHERE action IN ('discarded', 'consumed')
+              AND quantity_delta IS NOT NULL
+              AND canonical_name <> ''
+            GROUP BY canonical_name, action
+            """,
+        ).fetchall()
+    except Exception as e:
+        logger.warning("Waste insights failed: %s", e)
+        return []
+
+    stats: dict[str, dict[str, float]] = {}
+    for r in rows:
+        name = r["canonical_name"]
+        action = r["action"]
+        qty = float(r["total_qty"] or 0.0)
+        bucket = stats.setdefault(name, {"wasted": 0.0, "consumed": 0.0})
+        if action == "discarded":
+            bucket["wasted"] += qty
+        elif action == "consumed":
+            bucket["consumed"] += qty
+
+    results: list[dict[str, Any]] = []
+    for name, data in stats.items():
+        wasted = data["wasted"]
+        consumed = data["consumed"]
+        total = wasted + consumed
+        if total <= 0:
+            continue
+        results.append({
+            "canonical_name": name,
+            "wasted_qty": wasted,
+            "consumed_qty": consumed,
+            "waste_rate": wasted / total,
+            "total_resolved": total,
+        })
+
+    results.sort(key=lambda r: r["waste_rate"], reverse=True)
+    return results

shopstack/model_registry.py

@@ -0,0 +1,746 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+RuntimeType = Literal["transformers", "llama.cpp", "gguf", "onnx", "diffusers", "custom", "mock", "mlx"]
+BadgeRelevance = Literal["llama_champion", "well_tuned", "off_the_grid", "none"]
+ModelStatus = Literal["candidate", "active", "deprecated", "rejected"]
+MAX_ACTIVE_MODEL_PARAMS_B = 32.0
+
+
+@dataclass
+class ModelEntry:
+    provider_group: str
+    model_id: str
+    hf_model: str
+    params_b: float
+    license_note: str
+    runtime: RuntimeType
+    status: ModelStatus
+    badge_relevance: BadgeRelevance = "none"
+    python_requires: str = ">=3.10"
+    notes: str = ""
+
+
+MODEL_REGISTRY: list[ModelEntry] = [
+    # STT
+    ModelEntry(
+        provider_group="stt",
+        model_id="qwen3-asr-1.7b",
+        hf_model="Qwen/Qwen3-ASR-1.7B",
+        params_b=1.7,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="top candidate for household commands — provider wired as qwen3_asr backend. Bench pending. Demoted to candidate because SenseVoiceSmall is the default. Switch via stt_backend config.",
+    ),
+    # STT — Voxtral-Mini-4B-Realtime-2602 (Jan 2026, 1.1M downloads, Mistral's new SOTA)
+    ModelEntry(
+        provider_group="stt",
+        model_id="voxtral-mini-4b-realtime",
+        hf_model="mistralai/Voxtral-Mini-4B-Realtime-2602",
+        params_b=4.0,
+        license_note="Apache-2.0",
+        runtime="vllm",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Voxtral-Mini-4B-Realtime-2602 (Jan 2026, 1.1M downloads). Mistral's new SOTA STT. Apache-2.0. STT bench in flight on Modal A10G with 20 Hinglish audios.",
+    ),
+    # STT — parakeet-tdt-0.6b-v3 (Aug 2025, 120k downloads, newer than v2)
+    ModelEntry(
+        provider_group="stt",
+        model_id="parakeet-tdt-0.6b-v3",
+        hf_model="nvidia/parakeet-tdt-0.6b-v3",
+        params_b=0.6,
+        license_note="CC-BY-4.0",
+        runtime="nemo",
+        status="candidate",
+        notes="parakeet-tdt-0.6b-v3 (Aug 2025, 120k downloads). Newer than the v2 already in registry. STT bench in flight.",
+    ),
+    # STT — Fun-ASR-Nano-2512 (Dec 2025, FunAudioLLM)
+    ModelEntry(
+        provider_group="stt",
+        model_id="fun-asr-nano-2512",
+        hf_model="FunAudioLLM/Fun-ASR-Nano-2512",
+        params_b=0.5,
+        license_note="Apache-2.0",
+        runtime="funasr",
+        status="candidate",
+        notes="Fun-ASR-Nano-2512 (Dec 2025, FunAudioLLM). Multilingual + streaming + diarization. STT bench pending.",
+    ),
+    ModelEntry(
+        provider_group="stt",
+        model_id="parakeet-0.6b",
+        hf_model="nvidia/parakeet-ctc-0.6b",
+        params_b=0.6,
+        license_note="CC-BY-4.0",
+        runtime="transformers",
+        status="candidate",
+        notes="lightweight streaming ASR — provider wired as parakeet backend. Demoted to candidate (SenseVoiceSmall is the default).",
+    ),
+    ModelEntry(
+        provider_group="stt",
+        model_id="sense-voice-small",
+        hf_model="iic/SenseVoiceSmall",
+        params_b=0.2,
+        license_note="MIT",
+        runtime="transformers",
+        status="active",
+        notes="very fast, multilingual — wired as sensevoice backend (default). Modal STT v3 (13-Jun-2026): 75.2% WER, 46.4% slot retention on 20 Hinglish audios. The only working STT in the 32B cap.",
+    ),
+    ModelEntry(
+        provider_group="stt",
+        model_id="whisper-large-v3-turbo",
+        hf_model="openai/whisper-large-v3-turbo",
+        params_b=0.8,
+        license_note="MIT",
+        runtime="transformers",
+        status="candidate",
+        notes="baseline only",
+    ),
+    ModelEntry(
+        provider_group="stt",
+        model_id="qwen3-asr-0.6b",
+        hf_model="Qwen/Qwen3-ASR-0.6B",
+        params_b=0.6,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="smaller/newer Qwen ASR variant to benchmark against Qwen3-ASR-1.7B; good for low-cost voice sweeps and short commands.",
+    ),
+    # TTS
+    ModelEntry(
+        provider_group="tts",
+        model_id="qwen3-tts-0.6b",
+        hf_model="Qwen/Qwen3-TTS-12Hz-0.6B-Base",
+        params_b=0.6,
+        license_note="Apache-2.0",
+        runtime="custom",
+        status="candidate",
+        notes="0.6B variant of Qwen3-TTS. Demoted to candidate (1.7B CustomVoice is the new default; see qwen3-tts-1.7b below). Smaller model, similar SDK, ~3x faster than 1.7B.",
+    ),
+    # TTS — Qwen3-TTS-12Hz-1.7B-CustomVoice (NEW ACTIVE WINNER 13-Jun-2026)
+    ModelEntry(
+        provider_group="tts",
+        model_id="qwen3-tts-1.7b-customvoice",
+        hf_model="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+        params_b=1.7,
+        license_note="Apache-2.0",
+        runtime="custom",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="Qwen3-TTS-12Hz-1.7B-CustomVoice (Aug 2025, 1.9M downloads). **Modal A10G TTS compare bench WINNER (13-Jun-2026): 20/20 synth, 5.99s mean, 24kHz, 0.1183 energy (2.5x more dynamic than Kokoro).** Quality path: 14x slower than Kokoro but expressive. Provider wired as qwen3_tts backend, default voice 'Ryan'.",
+    ),
+    ModelEntry(
+        provider_group="tts",
+        model_id="kokoro-82m",
+        hf_model="",
+        params_b=0.082,
+        license_note="Apache-2.0",
+        runtime="custom",
+        status="active",
+        badge_relevance="off_the_grid",
+        notes="extremely lightweight — KokoroTTSProvider wired as kokoro backend",
+    ),
+    # TTS — CosyVoice 2 (higher quality, Hindi support) — SUPERSEDED by CosyVoice 3
+    ModelEntry(
+        provider_group="tts",
+        model_id="cosyvoice2-0.5b",
+        hf_model="FunAudioLLM/CosyVoice2-0.5B",
+        params_b=0.5,
+        license_note="Apache-2.0",
+        runtime="custom",
+        status="rejected",
+        badge_relevance="off_the_grid",
+        notes="REJECTED 13-Jun-2026: superseded by Fun-CosyVoice3-0.5B-2512. CosyVoice 2 was blocked on Python 3.14 (matcha-tts/numpy 1.24.3/distutils). Use CosyVoice 3 instead.",
+    ),
+    # TTS — Fun-CosyVoice3-0.5B-2512 (Dec 2025, REPLACES CosyVoice 2)
+    ModelEntry(
+        provider_group="tts",
+        model_id="fun-cosyvoice3-0.5b-2512",
+        hf_model="FunAudioLLM/Fun-CosyVoice3-0.5B-2512",
+        params_b=0.5,
+        license_note="Apache-2.0",
+        runtime="custom",
+        status="candidate",
+        badge_relevance="off_the_grid",
+        notes="Fun-CosyVoice3-0.5B-2512 (Dec 2025, 81k downloads). Apache-2.0. REPLACES CosyVoice 2. Multilingual (zh, en, ja, ko, de, fr, ru, it, es). MLX mirror available (mlx-community/Fun-CosyVoice3-0.5B-2512-fp16). Unblocks local Hindi TTS.",
+    ),
+    # TTS — Qwen3-TTS-12Hz-1.7B-CustomVoice (Jan 2026, 1.9M downloads)
+    ModelEntry(
+        provider_group="tts",
+        model_id="qwen3-tts-1.7b-customvoice",
+        hf_model="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+        params_b=1.7,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen3-TTS-1.7B-CustomVoice (Jan 2026, 1.9M downloads). Apache-2.0. Most popular Qwen TTS. TTS bench pending.",
+    ),
+    # TTS — Qwen3-TTS-12Hz-1.7B-VoiceDesign
+    ModelEntry(
+        provider_group="tts",
+        model_id="qwen3-tts-1.7b-voicedesign",
+        hf_model="Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
+        params_b=1.7,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="Qwen3-TTS-1.7B-VoiceDesign (Jan 2026, 686k downloads). Voice design variant. TTS bench pending.",
+    ),
+    # Vision
+    ModelEntry(
+        provider_group="vision",
+        model_id="minicpm-v-8b",
+        hf_model="openbmb/MiniCPM-V-2_6",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="strong VLM for household items — provider wired as minicpmv backend. Demoted to candidate (Qwen3-VL-8B is the new default; see qwen3-vl-8b below).",
+    ),
+    # Vision — Qwen2.5-VL-3B (lighter alternative via MLX)
+    ModelEntry(
+        provider_group="vision",
+        model_id="qwen2.5-vl-3b",
+        hf_model="Qwen/Qwen2.5-VL-3B-Instruct",
+        params_b=3.0,
+        license_note="Apache-2.0",
+        runtime="mlx",
+        status="candidate",
+        badge_relevance="off_the_grid",
+        notes="3B params, 0.9s load via MLX. Excellent throughput (43-80 tok/s) at 1/3 the params of MiniCPM-V. Demoted to candidate (Qwen3-VL-8B is the new default; see qwen3-vl-8b). Use via MLX for high-volume vision tasks.",
+    ),
+    # Vision — MiniCPM-V-4.6 (NEW MID-2026 SOTA, VLM bench candidate)
+    ModelEntry(
+        provider_group="vision",
+        model_id="minicpm-v-4.6",
+        hf_model="openbmb/MiniCPM-V-4.6",
+        params_b=4.6,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="MiniCPM-V-4.6 (Apr 2026, 660k downloads). On-device VLM. REPLACES MiniCPM-V-2_6 (Aug 2024). VLM bench in flight.",
+    ),
+    # Vision — Molmo2-8B (Dec 2025, Allen AI, 645k downloads)
+    ModelEntry(
+        provider_group="vision",
+        model_id="molmo2-8b",
+        hf_model="allenai/Molmo2-8B",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Molmo2-8B (Dec 2025, 645k downloads). Allen AI. custom_code required. VLM bench in flight.",
+    ),
+    # Vision — Qwen2.5-VL-7B-Instruct (Jan 2025, 6.5M downloads, still very popular)
+    ModelEntry(
+        provider_group="vision",
+        model_id="qwen2.5-vl-7b",
+        hf_model="Qwen/Qwen2.5-VL-7B-Instruct",
+        params_b=7.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen2.5-VL-7B-Instruct (Jan 2025, 6.5M downloads). Modal VLM v8 (13-Jun-2026): 86% on synthetic product images (95% identify, 95% brand, 100% qty, 40% price, 100% expiry). Works via AutoModelForImageTextToText + transformers>=4.55.",
+    ),
+    # Vision — Qwen3-VL-8B-Instruct (NEW ACTIVE WINNER, 13-Jun-2026)
+    ModelEntry(
+        provider_group="vision",
+        model_id="qwen3-vl-8b",
+        hf_model="Qwen/Qwen3-VL-8B-Instruct",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="NEW ACTIVE — Modal A100 int4 (13-Jun-2026): 99% overall on synthetic product images (100% identify, 100% brand, 100% qty, 95% price, 100% expiry). 7.3M downloads (most popular Qwen VLM). Apache-2.0. Best vision result across all benches. Use via AutoModelForImageTextToText + transformers>=4.55.",
+    ),
+    # Vision — Kimi-VL-A3B-Thinking (Apr 2025, MoE vision reasoning)
+    ModelEntry(
+        provider_group="vision",
+        model_id="kimi-vl-a3b-thinking",
+        hf_model="moonshotai/Kimi-VL-A3B-Thinking",
+        params_b=16.0,
+        license_note="MIT",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Kimi-VL-A3B-Thinking (Apr 2025). MoE 16B/3B active, vision + reasoning. custom_code. VLM bench pending.",
+    ),
+    # Planner
+    ModelEntry(
+        provider_group="planner",
+        model_id="minicpm5-1b",
+        hf_model="openbmb/MiniCPM5-1B",
+        params_b=1.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="well_tuned",
+        notes="lightweight planner / parser — provider wired as minicpm5 backend for tool_call_parser_backend. Demoted to candidate (Ministral-8B-Instruct-2410 is the main planner; see below).",
+    ),
+    ModelEntry(
+        provider_group="planner",
+        model_id="lfm2.5-8b-a1b-gguf",
+        hf_model="unsloth/LFM2.5-8B-A1B-GGUF",
+        params_b=8.3,
+        license_note="Apache-2.0",
+        runtime="gguf",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="GGUF planner for llama.cpp path",
+    ),
+    ModelEntry(
+        provider_group="planner",
+        model_id="llama-3.2-3b-gguf",
+        hf_model="unsloth/Llama-3.2-3B-Instruct-GGUF",
+        params_b=3.0,
+        license_note="Llama 3.2 Community",
+        runtime="gguf",
+        status="candidate",
+        badge_relevance="none",
+        notes="downloaded & tested: 493ms for 49 tokens via llama.cpp. Superseded by qwen3.5-4b for planner (better tool-calling accuracy).",
+    ),
+    # Planner — Qwen3.5-4B (full bf16 variant, cached, used for accuracy-critical tasks)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3.5-4b",
+        hf_model="Qwen/Qwen3.5-4B",
+        params_b=4.0,
+        license_note="Apache-2.0",
+        runtime="mlx",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Full bf16 precision variant (8.9GB). ~18 tok/s via MLX. Demoted to candidate because config now defaults to 4-bit variant. Keep cached for quality-benchmarking (97.5% accuracy).",
+    ),
+    # Planner — Qwen3.5-4B-4bit (deployment variant, ~2.3GB, same accuracy)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3.5-4b-4bit",
+        hf_model="mlx-community/Qwen3.5-4B-4bit",
+        params_b=4.0,
+        license_note="Apache-2.0",
+        runtime="mlx",
+        status="rejected",
+        badge_relevance="llama_champion",
+        notes="REJECTED 13-Jun-2026: 70% on Modal A100 int4 production bench (Run 1+2+3). 4x slower than alternatives (28.18s vs 4.08s). Overthinking issue. Demote from default. Switch to Ministral-8B-Instruct-2410 (95%) or Ministral-3-8B-Reasoning-2512 (90%, mid-2026).",
+    ),
+    # Planner — Ministral-8B-Instruct-2410 (RUN 1+2 WINNER, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-8b-instruct",
+        hf_model="mistralai/Ministral-8B-Instruct-2410",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="Run 1+2 winner on Modal A100 int4 (13-Jun-2026): 90% (10 prompts) / **95% (20 prompts)**, 4.08s mean latency. Tied with Gemma-3-4B. Oct 2024 release. **CURRENT DEFAULT PLANNER** (config.py:28). MLX variant: mlx-community/Ministral-8B-Instruct-2410-4bit. Demoted Ministral-3-8B-Instruct-2512 (the same-arch non-reasoning variant at 70% loses to the 2512-Reasoning variant at 90%).",
+    ),
+    # Planner — Ministral-3-8B-Instruct-2512 (Oct 2025, non-reasoning)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-3-8b-instruct-2512",
+        hf_model="mistralai/Ministral-3-8B-Instruct-2512",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Mistral's Oct 2025 release. 169k downloads. mistral3 arch. Modal A100 int4 (13-Jun-2026): 70% tool-calling, 2.59s mean. **Loses to Ministral-3-8B-Reasoning-2512 (90%) by 20 points** — the reasoning variant is materially better. Demoted.",
+    ),
+    # Planner — Ministral-3-3B-Instruct-2512 (NEW MID-2026 SOTA, Run 3 candidate)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-3-3b-instruct-2512",
+        hf_model="mistralai/Ministral-3-3B-Instruct-2512",
+        params_b=3.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Mistral's Oct 2025 3B variant. 669k downloads. Smallest serious Mistral. Run 3 bench in flight.",
+    ),
+    # Planner — Ministral-3-14B-Instruct-2512 (NEW MID-2026 SOTA, Run 3 candidate)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-3-14b-instruct-2512",
+        hf_model="mistralai/Ministral-3-14B-Instruct-2512-BF16",
+        params_b=14.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Mistral's Oct 2025 14B variant. Bigger brother of Ministral-3-8B. Run 3 bench in flight.",
+    ),
+    # Planner — Qwen2.5-7B-Instruct (NEW CANDIDATE, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen2.5-7b-instruct",
+        hf_model="Qwen/Qwen2.5-7B-Instruct",
+        params_b=7.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Modal A100 int4 (13-Jun-2026): 80% tool-calling, 3.17s mean (FASTEST of all 8 candidates), 5.56GB GPU. Beats Qwen3.5-4B on speed by 9×. Strong runner-up. Pending: MLX port + 30+ prompt re-validation.",
+    ),
+    # Planner — Qwen3.5-9B (HF frontier candidate, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3.5-9b",
+        hf_model="Qwen/Qwen3.5-9B",
+        params_b=9.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen3.5-9B (Feb 2026, 8.5M downloads). Modal bench (13-Jun-2026): 70% (17.35s — overthinking). Demote from consideration. Qwen2.5-7B better at 80% (3.10s).",
+    ),
+    # Planner — Ministral-3-8B-Reasoning-2512 (NEW MID-2026 WINNER, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-3-8b-reasoning-2512",
+        hf_model="mistralai/Ministral-3-8B-Reasoning-2512",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Modal A100 int4 (13-Jun-2026): 90% tool-calling, 4.79s mean, Apache-2.0. Best mid-2026 candidate. Tied with Run 1/2 winner (Ministral-8B-Instruct-2410 at 95%). A/B candidate — switch via planner_backend config. mistral3 arch.",
+    ),
+    # Planner — Ministral-3-3B-Instruct-2512 (NEW BEST 3B, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="ministral-3-3b-instruct-2512",
+        hf_model="mistralai/Ministral-3-3B-Instruct-2512",
+        params_b=3.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Modal A100 int4 (13-Jun-2026): 85% tool-calling, 2.31s mean (fastest serious 3B), Apache-2.0. 669k downloads. Best 3B option. Demoted to candidate (Ministral-8B-Instruct-2410 is the main planner). LoRA v2 was trained on this base (80% on prod).",
+    ),
+    # Planner — Qwen3.6-27B-FP8 (Apr 2026, 4.7M downloads, under 32B cap)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3.6-27b-fp8",
+        hf_model="Qwen/Qwen3.6-27B-FP8",
+        params_b=27.0,
+        license_note="Apache-2.0",
+        runtime="transformers-fp8",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen3.6-27B FP8 (Apr 2026, 4.7M downloads). Best under-32B MoE. Run 3 bench in flight.",
+    ),
+    # Planner — Qwen3-Coder-Next (Jan 2026, 912k downloads, code specialist)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3-coder-next",
+        hf_model="Qwen/Qwen3-Coder-Next",
+        params_b=32.0,
+        license_note="Apache-2.0",
+        runtime="transformers-int4",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen3-Coder-Next (Jan 2026, 912k downloads). Code specialist, strong tool-calling. Run 3 bench in flight.",
+    ),
+    # Planner — Gemma 4 31B QAT (May 2026, Google's latest, 4-bit QAT)
+    ModelEntry(
+        provider_group="planner",
+        model_id="gemma-4-31b-qat",
+        hf_model="google/gemma-4-31B-it-qat-q4_0-unquantized-assistant",
+        params_b=31.0,
+        license_note="Apache-2.0",
+        runtime="transformers-q4",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Gemma 4 31B QAT q4_0 (May 2026, 9.9M downloads). Google's latest, Apache-2.0. Run 3 bench in flight.",
+    ),
+    # Planner — Qwen3.6-35B-A3B (HF frontier heavy candidate, 13-Jun-2026)
+    ModelEntry(
+        provider_group="planner",
+        model_id="qwen3.6-35b-a3b",
+        hf_model="Qwen/Qwen3.6-35B-A3B",
+        params_b=35.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="HF Inference live-check (13-Jun-2026): available and responsive; 0.94s wall-clock for a 16-token smoke call. Remote frontier candidate for Modal/HF Pro sweeps only.",
+    ),
+    # Planner — Gemma 3 4B (strong architecture, needs prompt engineering)
+    ModelEntry(
+        provider_group="planner",
+        model_id="gemma-3-4b-it-4bit",
+        hf_model="mlx-community/gemma-3-4b-it-4bit",
+        params_b=4.0,
+        license_note="Gemma Terms of Use",
+        runtime="mlx",
+        status="candidate",
+        badge_relevance="none",
+        notes="Google Gemma 3 4B Instruct, 4-bit MLX quantized. Strong architecture but requires more prompt engineering for JSON output. Not yet downloaded or benchmarked.",
+    ),
+    # Planner — DeepSeek-R1-Distill-Qwen-7B (higher accuracy, heavier)
+    ModelEntry(
+        provider_group="planner",
+        model_id="deepseek-r1-distill-qwen-7b-4bit",
+        hf_model="mlx-community/DeepSeek-R1-Distill-Qwen-7B-abliterated-4bit",
+        params_b=7.0,
+        license_note="MIT",
+        runtime="mlx",
+        status="candidate",
+        badge_relevance="none",
+        notes="DeepSeek R1 Distill Qwen 7B, 4-bit MLX quantized. Higher accuracy potential but 7B params (~4GB). Not yet downloaded or benchmarked. Add to active only after verification.",
+    ),
+    # OCR / extraction
+    ModelEntry(
+        provider_group="ocr",
+        model_id="glm-ocr-0.9b",
+        hf_model="zai-org/GLM-OCR",
+        params_b=1.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="active",
+        badge_relevance="off_the_grid",
+        notes="Specialized 0.9B document/receipt OCR model. Current SOTA for small OCR (June 2026). Loaded & verified: 1016M params on Apple Silicon.",
+    ),
+    # OCR / extraction
+    ModelEntry(
+        provider_group="ocr",
+        model_id="nuextract3-4b",
+        hf_model="nuance/NuExtract3-4B",
+        params_b=4.0,
+        license_note="CC-BY-NC-4.0",
+        runtime="transformers",
+        status="candidate",
+        notes="strong receipt extraction, non-commercial. Superseded by glm-ocr-0.9b (1B params, purpose-built for OCR).",
+    ),
+    ModelEntry(
+        provider_group="ocr",
+        model_id="deepseek-ocr-2",
+        hf_model="deepseek-ai/DeepSeek-OCR-2",
+        params_b=3.0,
+        license_note="MIT",
+        runtime="transformers",
+        status="candidate",
+        notes="HF frontier OCR candidate (2026). Exact receipt/label sweep pending; promoted to registry so Modal/HF jobs can benchmark it against GLM-OCR and Tesseract.",
+    ),
+    # OCR — PaddleOCR-VL-1.6 (May 2026, Apache-2.0, multilingual OCR, unblocks Hindi)
+    ModelEntry(
+        provider_group="ocr",
+        model_id="paddleocr-vl-1.6",
+        hf_model="PaddlePaddle/PaddleOCR-VL-1.6",
+        params_b=0.9,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="PaddleOCR-VL-1.6 (May 2026, 67k downloads). Apache-2.0. Multilingual OCR (109 langs incl Hindi). Custom PaddlePaddle code. OCR bench in flight. May unblock the long-standing Hindi OCR gap.",
+    ),
+    # OCR — PaddleOCR-VL-1.6-GGUF (May 2026, GGUF for llama.cpp)
+    ModelEntry(
+        provider_group="ocr",
+        model_id="paddleocr-vl-1.6-gguf",
+        hf_model="PaddlePaddle/PaddleOCR-VL-1.6-GGUF",
+        params_b=0.9,
+        license_note="Apache-2.0",
+        runtime="gguf",
+        status="candidate",
+        notes="PaddleOCR-VL-1.6 GGUF (May 2026, 67k downloads). BYPASSES the PaddlePaddle Python dep blocker. Can run via llama.cpp on Apple Silicon + Modal. THIS is the path to local Hindi OCR.",
+    ),
+    # OCR — dots.ocr (Jul 2025, 260k downloads, MIT, most popular)
+    ModelEntry(
+        provider_group="ocr",
+        model_id="dots-ocr",
+        hf_model="rednote-hilab/dots.ocr",
+        params_b=3.0,
+        license_note="MIT",
+        runtime="transformers",
+        status="candidate",
+        notes="dots.ocr (Jul 2025, 260k downloads). Most popular modern OCR. Custom code. OCR bench in flight.",
+    ),
+    # Segmentation
+    ModelEntry(
+        provider_group="segmentation",
+        model_id="rmbg-1.4",
+        hf_model="briaai/RMBG-1.4",
+        params_b=0.3,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="RMBG-1.4 (Jun 2024, 8M downloads). Background removal. Supplanted by BiRefNet on Modal seg bench (13-Jun-2026).",
+    ),
+    # Segmentation — BiRefNet (Jul 2024, 683k downloads, WINNER 13-Jun-2026)
+    ModelEntry(
+        provider_group="segmentation",
+        model_id="birefnet",
+        hf_model="ZhengPeng7/BiRefNet",
+        params_b=0.3,
+        license_note="MIT",
+        runtime="transformers",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="BiRefNet (Jul 2024, 683k downloads). **Modal A10G seg bench WINNER (13-Jun-2026): IoU 0.8555, pixel acc 0.9699, 0.432s/image, 20 synthetic product images.** Provider wired as birefnet backend. Now the default segmentation provider. RMBG-2.0 was gated. RMBG-1.4 had all_tied_weights_keys issue with newer transformers. GSF-ai/Birefnet-General couldn't load.",
+    ),
+    ModelEntry(
+        provider_group="segmentation",
+        model_id="rmbg-2.0",
+        hf_model="briaai/RMBG-2.0",
+        params_b=0.2,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="HF frontier segmentation candidate (2026). GATED — needs user approval at https://huggingface.co/briaai/RMBG-2.0. Once approved, expect ~5-10% IoU improvement over BiRefNet (2.0 is a generational upgrade).",
+    ),
+    # Embeddings — Nomic-Embed-Text-v1.5 (Aug 2024, 2.3M downloads, WINNER 13-Jun-2026)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="nomic-embed-text-v1.5",
+        hf_model="nomic-ai/nomic-embed-text-v1.5",
+        params_b=0.137,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="Nomic-Embed-Text-v1.5 (Aug 2024, 2.3M downloads). **Modal A10G embed bench WINNER (13-Jun-2026): Top-1 58%, Top-3 90%, dim 768.** Apache-2.0 (more permissive than BGE-M3 MIT). Provider wired as nomic backend. Supplants BGE-M3 (48% top-1).",
+    ),
+    # Embeddings — BGE-M3 (Apr 2024, 28.7M downloads, was default, demoted)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="bge-m3",
+        hf_model="BAAI/bge-m3",
+        params_b=0.6,
+        license_note="MIT",
+        runtime="transformers",
+        status="candidate",
+        notes="BGE-M3 (Apr 2024, 28.7M downloads, most popular multilingual). Modal A10G embed bench: 48% top-1 (vs Nomic 58%). Demoted to candidate. Provider wired as bge_m3 backend (kept for compatibility).",
+    ),
+    # Embeddings — Qwen3-Embedding-0.6B (Jun 2025, 8.7M downloads, most popular Qwen)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="qwen3-embedding-0.6b",
+        hf_model="Qwen/Qwen3-Embedding-0.6B",
+        params_b=0.6,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="llama_champion",
+        notes="Qwen3-Embedding-0.6B (Jun 2025, 8.7M downloads). Most popular Qwen embedding. **Modal A10G embed bench (13-Jun-2026): 50% top-1, 84% top-3, dim 1024.** Solid but loses to Nomic (58% top-1, smaller dim).",
+    ),
+    # Embeddings — Qwen3-Embedding-8B (Jun 2025, 1.9M downloads)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="qwen3-embedding-8b",
+        hf_model="Qwen/Qwen3-Embedding-8B",
+        params_b=8.0,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="Qwen3-Embedding-8B (Jun 2025, 1.9M downloads). Higher-quality. Bench pending. Would consume most of the 32B cap alone.",
+    ),
+    # Embeddings — mxbai-embed-large-v1 (Mar 2024, 6M downloads)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="mxbai-embed-large",
+        hf_model="mixedbread-ai/mxbai-embed-large-v1",
+        params_b=0.335,
+        license_note="Apache-2.0",
+        runtime="transformers",
+        status="candidate",
+        notes="mxbai-embed-large-v1 (Mar 2024, 6M downloads). **Modal A10G embed bench (13-Jun-2026): 56% top-1, 82% top-3, dim 1024.** Strong but loses to Nomic (58% top-1, 90% top-3, smaller dim).",
+    ),
+    # Embeddings — Jina v5 text-nano (Jan 2026, 543k downloads, multimodal)
+    ModelEntry(
+        provider_group="embeddings",
+        model_id="jina-embeddings-v5-text-nano",
+        hf_model="jinaai/jina-embeddings-v5-text-nano",
+        params_b=0.2,
+        license_note="CC-BY-NC-4.0",
+        runtime="transformers",
+        status="candidate",
+        notes="Jina v5 text-nano (Jan 2026, 543k downloads). Multilingual MTEB. Embedding bench pending.",
+    ),
+    # Fine-tuned
+    ModelEntry(
+        provider_group="planner",
+        model_id="shopstack-parser-lora",
+        hf_model="",
+        params_b=0.0,
+        license_note="Apache-2.0 (planned)",
+        runtime="transformers",
+        status="candidate",
+        badge_relevance="well_tuned",
+        notes="future fine-tuned command parser",
+    ),
+    # Image generation
+    ModelEntry(
+        provider_group="image_edit",
+        model_id="flux.2-klein-4b",
+        hf_model="black-forest-labs/FLUX.2-klein-4B",
+        params_b=4.0,
+        license_note="FLUX.2-dev Non-Commercial",
+        runtime="diffusers",
+        status="active",
+        badge_relevance="llama_champion",
+        notes="visual card generation — FluxImageProvider wired as image_gen backend",
+    ),
+]
+
+
+def get_registry(group: str | None = None) -> list[ModelEntry]:
+    if group:
+        return [m for m in MODEL_REGISTRY if m.provider_group == group]
+    return list(MODEL_REGISTRY)
+
+
+def get_active(group: str) -> list[ModelEntry]:
+    return [m for m in MODEL_REGISTRY if m.provider_group == group and m.status == "active"]
+
+
+def get_active_models() -> list[ModelEntry]:
+    return [m for m in MODEL_REGISTRY if m.status == "active"]
+
+
+def total_active_params() -> float:
+    return sum(m.params_b for m in MODEL_REGISTRY if m.status == "active")
+
+
+def total_candidate_only_params() -> float:
+    return total_candidate_params()
+
+
+def total_loaded_params() -> float:
+    return total_active_params()
+
+
+def total_candidate_params() -> float:
+    return sum(m.params_b for m in MODEL_REGISTRY if m.status == "candidate")
+
+
+def total_selected_params(include_candidates: bool = False) -> float:
+    if include_candidates:
+        return sum(m.params_b for m in MODEL_REGISTRY if m.status in ("active", "candidate"))
+    return total_active_params()
+
+
+def validate_active_model_budget(max_params_b: float = MAX_ACTIVE_MODEL_PARAMS_B) -> None:
+    total = total_loaded_params()
+    if total > max_params_b:
+        raise ValueError(
+            f"Active model stack is {total}B, which exceeds the {max_params_b}B cap"
+        )
+
+
+def get_status_summary() -> dict[str, int]:
+    counts: dict[str, int] = {"active": 0, "candidate": 0, "deprecated": 0, "rejected": 0}
+    for model in MODEL_REGISTRY:
+        counts[model.status] += 1
+    return counts

shopstack/module_registry.py

@@ -0,0 +1,362 @@
+"""Module registry — single source of truth for ShopStack module metadata.
+
+Each ShopStack module (ShopStock, ShopBasket, ShopCompare, etc.) registers its
+name, slug, description, tab IDs, key service paths, and dependencies here.
+Any UI surface that needs module metadata imports from this registry instead of
+hardcoding strings.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ModuleMetadata:
+    """Metadata for a single ShopStack module.
+
+    This is the canonical source for all module-level information.
+    Any UI surface that needs a module name, tab label, description,
+    or navigation order should read it from here — never hardcode it.
+
+    Attributes:
+        slug: Short machine-friendly identifier (e.g. \"stock\", \"basket\").
+        name: Human-readable module name (e.g. \"ShopStock\").
+        label: Short UI label for the module itself (e.g. \"My Stock\").
+        description: One-line summary of the module's purpose.
+        tab_ids: Gradio tab IDs associated with this module.
+        tab_labels: Canonical display labels keyed by tab_id.
+                     If a tab_id is missing here, the module's ``label`` is used.
+                     Example: tab_labels={"inventory": "Find Item at Home", "purchase": "Add Purchase"}
+        order: Display order in the UI navigation bar (lower = earlier).
+        service_modules: Python module paths providing this module's logic.
+        depends_on: Slugs of modules this module typically depends on.
+        is_source: Whether this module is a retailer/source adapter.
+    """
+    slug: str
+    name: str
+    label: str
+    description: str
+    tab_ids: tuple[str, ...] = ()
+    tab_labels: dict[str, str] = field(default_factory=dict)
+    order: int = 999
+    service_modules: tuple[str, ...] = ()
+    depends_on: tuple[str, ...] = ()
+    is_source: bool = False
+
+    def tab_label(self, tab_id: str) -> str:
+        """Return the canonical display label for a given tab_id.
+
+        Falls back to ``self.label`` if no per-tab label is registered.
+        """
+        return self.tab_labels.get(tab_id, self.label)
+
+
+__all__ = [
+    "ModuleMetadata",
+    "SHOPSTOCK",
+    "SHOPBASKET",
+    "SHOPCOMPARE",
+    "SHOPLENS",
+    "SHOPMEMORY",
+    "SHOPAGENT",
+    "SOURCES",
+    "RUNTIME",
+    "SHOPNUTRITION",
+    "get_all",
+    "get_by_slug",
+    "get_by_tab_id",
+    "TAB_ORDER",
+    "TAB_LABELS",
+    "get_tab_ids",
+    "tab_order",
+    "tab_label",
+    "navigation",
+    "module_dependencies",
+    "summary_table",
+]
+
+
+# ── Registry ─────────────────────────────────────────────────────────
+
+_MODULES: dict[str, ModuleMetadata] = {}
+
+
+def _register(m: ModuleMetadata) -> ModuleMetadata:
+    """Register a module and index it by slug."""
+    _MODULES[m.slug] = m
+    return m
+
+
+# ── Tab order map ──────────────────────────────────────────────────
+
+# This is the canonical ordering for the Gradio tab bar.
+# Every tab that appears in the UI must have an entry here.
+# Order = explicit integer; lower values appear first.
+#
+# Adding a new tab: add it here with the position where it should appear.
+# The `order` field on each ModuleMetadata auto-aligns via the module's
+# lowest-order tab, but this dict is the single source of truth for the
+# actual tab bar sequence.
+TAB_ORDER: dict[str, int] = {
+    "today":      10,
+    "cookbook":   20,
+    "basket":     30,
+    "market":     40,
+    "reconcile":  50,
+    "memory":     60,
+}
+
+# ── Tab display labels ────────────────────────────────────────────
+# Canonical display names for every UI tab.
+# A module's `tab_labels` dict overrides these for module-specific labels.
+TAB_LABELS: dict[str, str] = {
+    "today":      "Home",
+    "cookbook":   "Recipes",
+    "basket":     "Groceries",
+    "market":     "While Shopping",
+    "reconcile":  "At Home",
+    "memory":     "Memory",
+}
+
+
+# ── Module definitions ───────────────────────────────────────────────
+#
+# Each module registers with:
+#   - slug:          machine-friendly ID
+#   - name:          canonical module name
+#   - label:         short UI label for the module itself
+#   - tab_labels:    per-tab display labels (override TAB_LABELS)
+#   - order:         display priority (auto-derived from TAB_ORDER)
+#   - tab_ids:       which Gradio tab IDs belong to this module
+#   - service_modules: Python paths implementing the module
+#   - depends_on:    module slugs this module depends on
+
+SHOPSTOCK = _register(ModuleMetadata(
+    slug="stock",
+    name="ShopStock",
+    label="At Home",
+    description="Inventory, pantry, fridge, expiry, low-stock, use-soon, and household storage.",
+    tab_ids=("reconcile",),
+    tab_labels={"reconcile": "At Home"},
+    order=TAB_ORDER.get("reconcile", 999),
+    service_modules=(
+        "shopstack.ui.screens.inventory",
+        "shopstack.ui.screens.portability",
+        "shopstack.portability",
+    ),
+))
+
+SHOPBASKET = _register(ModuleMetadata(
+    slug="basket",
+    name="ShopBasket",
+    label="Groceries",
+    description="Shopping list creation, decision classification (buy/skip/use-soon), cart planning, and market basket optimization.",
+    tab_ids=("basket",),
+    tab_labels={"basket": "Groceries"},
+    order=TAB_ORDER.get("basket", 999),
+    service_modules=(
+        "shopstack.services.shopping",
+        "shopstack.ui.screens.shopping",
+    ),
+    depends_on=("stock",),
+))
+
+SHOPCOMPARE = _register(ModuleMetadata(
+    slug="compare",
+    name="ShopCompare",
+    label="Price Check",
+    description="Retailer price comparison, unit price normalization, price-drop alerts, and best-store recommendations.",
+    tab_ids=("basket",),
+    tab_labels={"basket": "Groceries"},
+    order=TAB_ORDER.get("basket", 999),
+    service_modules=(
+        "shopstack.market",
+        "shopstack.market.analytics",
+        "shopstack.market.normalization",
+    ),
+    depends_on=("sources",),
+))
+
+SHOPLENS = _register(ModuleMetadata(
+    slug="lens",
+    name="ShopLens",
+    label="While Shopping",
+    description="Scanning and import: barcode, photo, receipt, object detection, OCR, and voice input.",
+    tab_ids=("market",),
+    tab_labels={"market": "While Shopping"},
+    order=TAB_ORDER.get("market", 999),
+    service_modules=(
+        "shopstack.services.market_lens",
+        "shopstack.ui.screens.market_lens",
+        "shopstack.scanner",
+    ),
+    depends_on=("stock",),
+))
+
+SHOPMEMORY = _register(ModuleMetadata(
+    slug="memory",
+    name="ShopMemory",
+    label="Memory",
+    description="Price history, household preferences, field notes, purchase cadence, and waste pattern tracking.",
+    tab_ids=("basket", "memory"),
+    tab_labels={
+        "basket": "Groceries",
+        "memory": "Memory",
+    },
+    order=TAB_ORDER.get("memory", 999),
+    service_modules=(
+        "shopstack.ui.views",
+        "shopstack.ui.screens.other",
+    ),
+))
+
+SHOPAGENT = _register(ModuleMetadata(
+    slug="agent",
+    name="ShopAgent",
+    label="Ask ShopStack",
+    description="Reasoning layer: AI planner with tool-calling, decision classification, and trace audit trail.",
+    tab_ids=("today", "memory"),
+    tab_labels={
+        "today": "Home",
+        "memory": "Memory",
+    },
+    order=TAB_ORDER.get("today", 999),
+    service_modules=(
+        "shopstack.planner.engine",
+        "shopstack.planner.prompts",
+        "shopstack.planner.parser",
+        "shopstack.decisions",
+        "shopstack.traces.export",
+    ),
+    depends_on=("stock", "basket", "memory"),
+))
+
+SOURCES = _register(ModuleMetadata(
+    slug="sources",
+    name="Sources",
+    label="Sources",
+    description="Retailer dataset adapters for price intelligence and basket comparison. Includes Swiggy Instamart.",
+    tab_ids=(),
+    order=999,
+    service_modules=(
+        "shopstack.market.sources.swiggy",
+    ),
+    is_source=True,
+))
+
+RUNTIME = _register(ModuleMetadata(
+    slug="runtime",
+    name="Runtime",
+    label="System",
+    description="Provider/model runtime diagnostics, budget status, and candidate model catalog. Developer-facing.",
+    tab_ids=("memory",),
+    tab_labels={"memory": "System"},
+    order=TAB_ORDER.get("memory", 999),
+    service_modules=(
+        "shopstack.ui.screens.model_stack",
+        "shopstack.model_registry",
+        "shopstack.providers.runtime",
+    ),
+))
+
+SHOPNUTRITION = _register(ModuleMetadata(
+    slug="nutrition",
+    name="ShopNutrition",
+    label="Nutrition",
+    description="Nutrition lookup for common Indian household items and kitchen macro breakdown from inventory.",
+    tab_ids=("memory",),
+    tab_labels={"memory": "Memory"},
+    order=TAB_ORDER.get("memory", 999),
+    service_modules=(
+        "shopstack.services.nutrition",
+        "shopstack.ui.screens.nutrition",
+    ),
+    depends_on=("stock",),
+))
+
+
+# ── Lookup helpers ───────────────────────────────────────────────────
+
+def get_all() -> list[ModuleMetadata]:
+    """Return all registered modules, ordered by definition."""
+    return list(_MODULES.values())
+
+
+def tab_order() -> list[tuple[str, str]]:
+    """Return (tab_id, display_label) pairs in UI navigation order.
+
+    This is the canonical source for building the Gradio tab bar in app.py.
+    Every registered tab appears once, ordered by ``TAB_ORDER``.
+    Unknown tab_ids (not in TAB_ORDER) are sorted last alphabetically.
+    """
+    known = [(TAB_ORDER[tid], tid, TAB_LABELS.get(tid, tid)) for tid in TAB_ORDER]
+    known.sort(key=lambda x: x[0])
+    return [(tid, label) for _, tid, label in known]
+
+
+def tab_label(tab_id: str) -> str:
+    """Return the canonical display label for a tab ID.
+
+    Checks per-module tab_labels first (for module-specific overrides),
+    then the global TAB_LABELS, then falls back to the raw tab_id.
+    """
+    # Check if any module has a per-tab override
+    for m in _MODULES.values():
+        if tab_id in m.tab_labels:
+            return m.tab_labels[tab_id]
+    return TAB_LABELS.get(tab_id, tab_id)
+
+
+def get_by_slug(slug: str) -> ModuleMetadata | None:
+    """Look up a module by its slug (e.g. \"stock\", \"basket\")."""
+    return _MODULES.get(slug)
+
+
+def get_by_tab_id(tab_id: str) -> list[ModuleMetadata]:
+    """Find all modules associated with a given Gradio tab ID.
+
+    A single tab may belong to multiple modules (e.g. \"prices\" belongs to
+    both ShopMemory and ShopCompare).
+    """
+    return [m for m in _MODULES.values() if tab_id in m.tab_ids]
+
+
+def get_tab_ids(slug: str) -> tuple[str, ...]:
+    """Return all tab IDs for a given module slug."""
+    m = _MODULES.get(slug)
+    return m.tab_ids if m else ()
+
+
+def navigation() -> list[tuple[str, str, str]]:
+    """Return an ordered list of (tab_id, label, module_name) for navigation.
+
+    This is the canonical source for building tab navigation in app.py and
+    other UI surfaces. Only modules with at least one tab ID are included.
+    """
+    entries: list[tuple[str, str, str]] = []
+    for m in _MODULES.values():
+        for tid in m.tab_ids:
+            entries.append((tid, m.label, m.name))
+    return entries
+
+
+def module_dependencies(slug: str) -> list[ModuleMetadata]:
+    """Return the ModuleMetadata objects this module depends on."""
+    m = _MODULES.get(slug)
+    if not m:
+        return []
+    return [dep for dep_slug in m.depends_on if (dep := _MODULES.get(dep_slug))]
+
+
+def summary_table() -> list[dict[str, str]]:
+    """Return a table-friendly list of dicts for display/export."""
+    return [
+        {
+            "Module": m.name,
+            "Label": m.label,
+            "Description": m.description,
+            "Tabs": ", ".join(m.tab_ids) if m.tab_ids else "(none)",
+        }
+        for m in _MODULES.values()
+    ]

shopstack/persistence/database.py

@@ -0,0 +1,1764 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from shopstack.config import settings
+from shopstack.schemas.models import (
+    InventoryEvent,
+    InventoryLot,
+    HouseholdLocation,
+    MovementEvent,
+    new_id,
+    PriceObservation,
+    PurchaseEvent,
+    ShoppingList,
+    ShoppingListItem,
+    Store,
+    Trace,
+    ReconciliationEvent,
+    PreferenceSignal,
+)
+
+
+class Database:
+    def __init__(self, db_path: str | None = None):
+        self.db_path = db_path if db_path is not None else settings.db_path
+        Path(self.db_path).parent.mkdir(parents=True, exist_ok=True)
+        # Per-thread sqlite3 connections.  ``sqlite3.Connection`` is not
+        # safe to share across threads — even with ``check_same_thread=
+        # False`` concurrent ``execute`` + ``commit`` from anyio worker
+        # threads corrupts cursor state and surfaces as
+        # ``InterfaceError: bad parameter or other API misuse`` or
+        # ``NoneType`` from ``fetchone()`` deep in the call stack.
+        # Each thread opens its own connection to the same file;
+        # WAL mode serialises writes across them.
+        self._local = threading.local()
+        self._init_lock = threading.Lock()
+        self._init_db()
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        c = getattr(self._local, "conn", None)
+        if c is None:
+            c = sqlite3.connect(self.db_path, check_same_thread=True)
+            c.row_factory = sqlite3.Row
+            c.execute("PRAGMA journal_mode=WAL")
+            c.execute("PRAGMA foreign_keys=ON")
+            self._local.conn = c
+        return c
+
+    def _init_db(self) -> None:
+        c = self.conn
+        c.executescript("""
+            CREATE TABLE IF NOT EXISTS inventory_lots (
+                lot_id TEXT PRIMARY KEY,
+                canonical_name TEXT NOT NULL,
+                display_name TEXT NOT NULL,
+                category TEXT DEFAULT '',
+                quantity REAL DEFAULT 1.0,
+                unit TEXT DEFAULT 'unit',
+                storage_location_id TEXT DEFAULT '',
+                purchase_date TEXT,
+                estimated_use_by_date TEXT,
+                label_expiry_date TEXT,
+                opened_date TEXT,
+                price_paid REAL,
+                currency TEXT DEFAULT 'INR',
+                source_event_id TEXT DEFAULT '',
+                confidence REAL DEFAULT 1.0,
+                image_crop_path TEXT,
+                status TEXT DEFAULT 'active',
+                created_at TEXT,
+                updated_at TEXT,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS purchase_events (
+                event_id TEXT PRIMARY KEY,
+                timestamp TEXT,
+                canonical_name TEXT DEFAULT '',
+                quantity REAL DEFAULT 1.0,
+                unit TEXT DEFAULT 'unit',
+                total_price REAL DEFAULT 0.0,
+                currency TEXT DEFAULT 'INR',
+                source_type TEXT DEFAULT 'manual',
+                store_name TEXT,
+                raw_text TEXT,
+                source_file_path TEXT,
+                confirmed INTEGER DEFAULT 0,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS shopping_lists (
+                list_id TEXT PRIMARY KEY,
+                name TEXT DEFAULT 'Shopping List',
+                created_at TEXT,
+                updated_at TEXT,
+                goal TEXT DEFAULT '',
+                is_active INTEGER DEFAULT 1,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS shopping_list_items (
+                item_id TEXT PRIMARY KEY,
+                list_id TEXT NOT NULL,
+                canonical_name TEXT NOT NULL,
+                requested_quantity REAL,
+                unit TEXT,
+                priority TEXT DEFAULT 'optional',
+                reason TEXT DEFAULT '',
+                status TEXT DEFAULT 'pending',
+                linked_lots TEXT DEFAULT '[]',
+                FOREIGN KEY (list_id) REFERENCES shopping_lists(list_id)
+            );
+
+            CREATE TABLE IF NOT EXISTS household_locations (
+                location_id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                parent_location_id TEXT,
+                location_type TEXT DEFAULT 'shelf',
+                photo_path TEXT,
+                notes TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS movement_events (
+                movement_id TEXT PRIMARY KEY,
+                lot_id TEXT NOT NULL,
+                from_location_id TEXT,
+                to_location_id TEXT NOT NULL,
+                timestamp TEXT,
+                source TEXT DEFAULT 'manual',
+                confidence REAL DEFAULT 1.0,
+                FOREIGN KEY (lot_id) REFERENCES inventory_lots(lot_id)
+            );
+
+            CREATE TABLE IF NOT EXISTS price_observations (
+                price_id TEXT PRIMARY KEY,
+                canonical_name TEXT NOT NULL,
+                quantity REAL DEFAULT 1.0,
+                unit TEXT DEFAULT 'unit',
+                price REAL NOT NULL,
+                currency TEXT DEFAULT 'INR',
+                store_name TEXT,
+                store_id TEXT,
+                observation_date TEXT,
+                source_event_id TEXT DEFAULT '',
+                notes TEXT,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS stores (
+                store_id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                location TEXT,
+                store_type TEXT DEFAULT 'kirana',
+                notes TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS traces (
+                trace_id TEXT PRIMARY KEY,
+                input_type TEXT DEFAULT '',
+                user_goal TEXT DEFAULT '',
+                redacted_user_request TEXT DEFAULT '',
+                perception TEXT DEFAULT '{}',
+                inventory_context TEXT DEFAULT '{}',
+                decision TEXT DEFAULT '{}',
+                proposed_tool_calls TEXT DEFAULT '[]',
+                human_confirmation TEXT,
+                final_response TEXT DEFAULT '',
+                timestamp TEXT,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS app_config (
+                key TEXT PRIMARY KEY,
+                value TEXT NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS market_snapshots (
+                snapshot_id TEXT PRIMARY KEY,
+                source TEXT NOT NULL,
+                source_category TEXT NOT NULL,
+                captured_at TEXT NOT NULL,
+                record_count INTEGER DEFAULT 0,
+                analytics TEXT DEFAULT '{}',
+                freshness_context TEXT DEFAULT 'unknown',
+                stored_at TEXT
+            );
+
+            CREATE TABLE IF NOT EXISTS market_records (
+                record_id TEXT PRIMARY KEY,
+                snapshot_id TEXT NOT NULL,
+                raw_name TEXT NOT NULL,
+                canonical_name TEXT NOT NULL,
+                description TEXT DEFAULT '',
+                raw_size TEXT DEFAULT '',
+                normalized_quantity REAL,
+                normalized_unit TEXT,
+                package_count INTEGER DEFAULT 1,
+                is_combo INTEGER DEFAULT 0,
+                is_weight_based INTEGER DEFAULT 0,
+                is_piece_based INTEGER DEFAULT 0,
+                is_size_class INTEGER DEFAULT 0,
+                size_class TEXT DEFAULT '',
+                price_inr REAL DEFAULT 0.0,
+                mrp_inr REAL DEFAULT 0.0,
+                discount_percent_displayed REAL DEFAULT 0.0,
+                discount_amount_inr REAL DEFAULT 0.0,
+                computed_discount_percent REAL DEFAULT 0.0,
+                availability TEXT DEFAULT '',
+                is_available INTEGER DEFAULT 1,
+                tag TEXT DEFAULT '',
+                is_ad INTEGER DEFAULT 0,
+                is_upgrade INTEGER DEFAULT 0,
+                card_index INTEGER DEFAULT 0,
+                delivery_time TEXT DEFAULT '',
+                price_per_kg REAL,
+                price_per_100g REAL,
+                price_per_piece REAL,
+                normalization_warnings TEXT DEFAULT '',
+                variety TEXT DEFAULT '',
+                brand TEXT DEFAULT '',
+                FOREIGN KEY (snapshot_id) REFERENCES market_snapshots(snapshot_id)
+            );
+
+            CREATE TABLE IF NOT EXISTS market_record_components (
+                component_id TEXT PRIMARY KEY,
+                record_id TEXT NOT NULL,
+                component_name TEXT NOT NULL,
+                FOREIGN KEY (record_id) REFERENCES market_records(record_id)
+            );
+
+            CREATE TABLE IF NOT EXISTS reconciliation_events (
+                event_id TEXT PRIMARY KEY,
+                timestamp TEXT,
+                canonical_name TEXT NOT NULL,
+                planned_action TEXT NOT NULL,
+                actual_action TEXT NOT NULL,
+                quantity REAL DEFAULT 0.0,
+                unit TEXT DEFAULT 'unit',
+                price_paid REAL,
+                planned_price REAL,
+                substituted_with TEXT,
+                notes TEXT,
+                source TEXT DEFAULT 'manual',
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS preference_signals (
+                signal_id TEXT PRIMARY KEY,
+                canonical_name TEXT NOT NULL,
+                signal_type TEXT NOT NULL,
+                value TEXT NOT NULL,
+                confidence REAL DEFAULT 0.5,
+                source TEXT DEFAULT 'observed',
+                created_at TEXT,
+                updated_at TEXT,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS inventory_events (
+                event_id TEXT PRIMARY KEY,
+                timestamp TEXT NOT NULL,
+                lot_id TEXT DEFAULT '',
+                canonical_name TEXT DEFAULT '',
+                action TEXT NOT NULL,
+                quantity_before REAL,
+                quantity_after REAL,
+                quantity_delta REAL,
+                unit TEXT DEFAULT '',
+                location_from TEXT,
+                location_to TEXT,
+                source TEXT DEFAULT 'manual',
+                notes TEXT,
+                user_id TEXT DEFAULT ''
+            );
+
+            CREATE TABLE IF NOT EXISTS households (
+                household_id TEXT PRIMARY KEY,
+                name TEXT NOT NULL,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                notes TEXT DEFAULT ''
+            );
+
+            -- ── Phase 10: household_members (multi-household permissioning) ──
+            -- A user is *in* zero or more households with a role.
+            -- One row per (household_id, user_id) pair. Composite
+            -- primary key prevents duplicate memberships.
+            CREATE TABLE IF NOT EXISTS household_members (
+                household_id TEXT NOT NULL,
+                user_id TEXT NOT NULL,
+                role TEXT NOT NULL DEFAULT 'member',
+                joined_at TEXT NOT NULL,
+                PRIMARY KEY (household_id, user_id),
+                FOREIGN KEY (household_id) REFERENCES households(household_id) ON DELETE CASCADE
+            );
+            CREATE INDEX IF NOT EXISTS idx_household_members_user
+                ON household_members(user_id);
+
+            CREATE VIEW IF NOT EXISTS price_history AS
+                SELECT * FROM price_observations;
+
+            CREATE TRIGGER IF NOT EXISTS price_history_delete
+            INSTEAD OF DELETE ON price_history
+            BEGIN
+                DELETE FROM price_observations WHERE price_id = OLD.price_id;
+            END;
+
+            CREATE VIEW IF NOT EXISTS agent_traces AS
+                SELECT * FROM traces;
+
+            CREATE TRIGGER IF NOT EXISTS agent_traces_delete
+            INSTEAD OF DELETE ON agent_traces
+            BEGIN
+                DELETE FROM traces WHERE trace_id = OLD.trace_id;
+            END;
+
+            -- ── Object Trail: negative memory (places where items are confirmed NOT to be) ──
+            CREATE TABLE IF NOT EXISTS negative_memory (
+                memory_id TEXT PRIMARY KEY,
+                lot_id TEXT NOT NULL,
+                location_id TEXT NOT NULL,
+                location_name TEXT DEFAULT '',
+                confirmed_at TEXT NOT NULL,
+                source TEXT DEFAULT 'user_feedback',
+                confidence REAL DEFAULT 1.0,
+                user_id TEXT DEFAULT ''
+            );
+            CREATE INDEX IF NOT EXISTS idx_negative_memory_lot
+                ON negative_memory(lot_id);
+
+            -- ── Object Trail: person associations (who owns/uses an item) ──
+            CREATE TABLE IF NOT EXISTS person_associations (
+                association_id TEXT PRIMARY KEY,
+                lot_id TEXT NOT NULL,
+                person_id TEXT NOT NULL,
+                person_name TEXT NOT NULL,
+                relationship TEXT DEFAULT 'owner',
+                confidence REAL DEFAULT 1.0,
+                user_id TEXT DEFAULT ''
+            );
+            CREATE INDEX IF NOT EXISTS idx_person_associations_lot
+                ON person_associations(lot_id);
+        """)
+        self._migrate_market_snapshot_schema()
+        self._migrate_add_user_scoping()
+        self._migrate_backfill_household_owners()
+        self._seed_locations()
+        self._seed_default_household()
+        self._apply_trace_retention_policy()
+        self.conn.commit()
+
+    def _migrate_market_snapshot_schema(self) -> None:
+        rows = self.conn.execute("PRAGMA table_info(market_snapshots)").fetchall()
+        existing_cols = {r["name"] for r in rows}
+        migrations: list[tuple[str, str]] = [
+            ("record_count", "INTEGER DEFAULT 0"),
+            ("analytics", "TEXT DEFAULT '{}'"),
+            ("freshness_context", "TEXT DEFAULT 'unknown'"),
+            ("stored_at", "TEXT"),
+        ]
+        for col_name, decl in migrations:
+            if col_name not in existing_cols:
+                self.conn.execute(f"ALTER TABLE market_snapshots ADD COLUMN {col_name} {decl}")
+
+    def _migrate_add_user_scoping(self) -> None:
+        tables = ["inventory_lots", "purchase_events", "shopping_lists", "traces", "price_observations"]
+        for table in tables:
+            try:
+                self.conn.execute(f"ALTER TABLE {table} ADD COLUMN user_id TEXT DEFAULT ''")
+            except sqlite3.OperationalError as exc:
+                message = str(exc).lower()
+                if "duplicate column name" in message or "already exists" in message:
+                    continue
+                raise
+
+    def _migrate_backfill_household_owners(self) -> None:
+        """Backfill owner memberships for any pre-existing households.
+
+        For each household that exists in the ``households``
+        table but has no members, add the default user as
+        the owner. This keeps the migration idempotent: running
+        on a fresh install is a no-op (the seeder does it);
+        running on an existing install backfills the gap.
+        """
+        from datetime import datetime
+        now = datetime.now().isoformat()
+        rows = self.conn.execute(
+            "SELECT h.household_id FROM households h "
+            "WHERE NOT EXISTS (SELECT 1 FROM household_members m "
+            "WHERE m.household_id = h.household_id)"
+        ).fetchall()
+        for row in rows:
+            hid = row["household_id"]
+            self.conn.execute(
+                "INSERT OR IGNORE INTO household_members "
+                "(household_id, user_id, role, joined_at) "
+                "VALUES (?, ?, ?, ?)",
+                (hid, hid, "owner", now),
+            )
+        if rows:
+            self.conn.commit()
+
+    # ── Active household tracking ────────────────────────────────
+
+    @property
+    def active_household_id(self) -> str:
+        """Get the currently active household ID, or default if none set.
+
+        Returns ``""`` when explicitly set to empty (disabling user_id
+        filtering), or ``settings.default_household_user_id`` when no
+        household has ever been selected.
+        """
+        stored = self.get_config_value("active_household_id", "")
+        # If the config key exists at all (including with empty value), return its value.
+        # This allows callers to opt out of household scoping by setting to "".
+        has_key = self.conn.execute(
+            "SELECT COUNT(*) FROM app_config WHERE key = 'active_household_id'"
+        ).fetchone()[0]
+        if has_key:
+            return stored
+        return settings.default_household_user_id
+
+    @active_household_id.setter
+    def active_household_id(self, household_id: str) -> None:
+        self.set_config_value("active_household_id", household_id)
+
+    # ── Household CRUD ────────────────────────────────────────────
+
+    def list_households(self) -> list[dict[str, str]]:
+        """List all registered households with their IDs and names."""
+        rows = self.conn.execute(
+            "SELECT household_id, name, created_at, notes FROM households ORDER BY created_at ASC"
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def add_household(self, household_id: str, name: str, notes: str = "") -> bool:
+        """Register a new household. Returns True if created, False if already exists."""
+        from datetime import datetime
+        now = datetime.now().isoformat()
+        try:
+            self.conn.execute(
+                "INSERT INTO households (household_id, name, created_at, updated_at, notes) VALUES (?, ?, ?, ?, ?)",
+                (household_id, name, now, now, notes),
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    def remove_household(self, household_id: str) -> bool:
+        """Remove a household registration."""
+        try:
+            self.conn.execute(
+                "DELETE FROM households WHERE household_id = ?", (household_id,)
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    # ── Household members (Phase 10 #1) ──────────────────────────
+
+    def list_household_members(self, household_id: str) -> list[dict[str, str]]:
+        """Return all members of a household, oldest first.
+
+        Each dict: ``{"household_id", "user_id", "role", "joined_at"}``.
+        Empty list when the household has no members.
+        """
+        rows = self.conn.execute(
+            "SELECT household_id, user_id, role, joined_at "
+            "FROM household_members WHERE household_id = ? "
+            "ORDER BY joined_at ASC",
+            (household_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def list_households_for_user(self, user_id: str) -> list[dict[str, str]]:
+        """Return all households a user is a member of.
+
+        Each dict: ``{"household_id", "name", "role", "joined_at"}``.
+        Empty list when the user is in no households.
+        """
+        rows = self.conn.execute(
+            "SELECT h.household_id, h.name, m.role, m.joined_at "
+            "FROM households h JOIN household_members m "
+            "ON h.household_id = m.household_id "
+            "WHERE m.user_id = ? "
+            "ORDER BY m.joined_at ASC",
+            (user_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def get_household_member(
+        self, household_id: str, user_id: str
+    ) -> dict[str, str] | None:
+        """Return the membership row for (household, user), or None."""
+        row = self.conn.execute(
+            "SELECT household_id, user_id, role, joined_at "
+            "FROM household_members "
+            "WHERE household_id = ? AND user_id = ?",
+            (household_id, user_id),
+        ).fetchone()
+        return dict(row) if row else None
+
+    def add_household_member(
+        self, household_id: str, user_id: str, role: str = "member"
+    ) -> bool:
+        """Add ``user_id`` to ``household_id`` with the given role.
+
+        Roles: ``"owner"`` (full control), ``"member"`` (read+write),
+        ``"guest"`` (read-only). Returns True if added, False if
+        already a member or the household doesn't exist.
+        """
+        from datetime import datetime
+        if role not in ("owner", "member", "guest"):
+            return False
+        # Verify household exists
+        exists = self.conn.execute(
+            "SELECT 1 FROM households WHERE household_id = ?", (household_id,)
+        ).fetchone()
+        if not exists:
+            return False
+        try:
+            self.conn.execute(
+                "INSERT INTO household_members (household_id, user_id, role, joined_at) "
+                "VALUES (?, ?, ?, ?)",
+                (household_id, user_id, role, datetime.now().isoformat()),
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    def remove_household_member(self, household_id: str, user_id: str) -> bool:
+        """Remove ``user_id`` from ``household_id``.
+
+        Refuses to remove the last owner. Returns True on
+        success, False if the user wasn't a member or
+        removing them would orphan the household.
+        """
+        # Disallow removing the last owner
+        if self.get_household_member(household_id, user_id) is None:
+            return False
+        if self._is_last_owner(household_id, user_id):
+            return False
+        try:
+            self.conn.execute(
+                "DELETE FROM household_members "
+                "WHERE household_id = ? AND user_id = ?",
+                (household_id, user_id),
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    def update_household_member_role(
+        self, household_id: str, user_id: str, new_role: str
+    ) -> bool:
+        """Change ``user_id``'s role in ``household_id``.
+
+        Refuses to demote the last owner. Returns True on
+        success, False if the role is invalid or the demotion
+        would orphan the household.
+        """
+        if new_role not in ("owner", "member", "guest"):
+            return False
+        if self.get_household_member(household_id, user_id) is None:
+            return False
+        if new_role != "owner" and self._is_last_owner(household_id, user_id):
+            return False
+        try:
+            self.conn.execute(
+                "UPDATE household_members SET role = ? "
+                "WHERE household_id = ? AND user_id = ?",
+                (new_role, household_id, user_id),
+            )
+            self.conn.commit()
+            return True
+        except Exception:
+            return False
+
+    def _is_last_owner(self, household_id: str, user_id: str) -> bool:
+        """True if ``user_id`` is the only owner of ``household_id``."""
+        member = self.get_household_member(household_id, user_id)
+        if not member or member.get("role") != "owner":
+            return False
+        rows = self.conn.execute(
+            "SELECT user_id FROM household_members "
+            "WHERE household_id = ? AND role = 'owner'",
+            (household_id,),
+        ).fetchall()
+        return len(rows) == 1 and rows[0]["user_id"] == user_id
+
+    def _seed_default_household(self) -> None:
+        """Ensure the default household + owner member exist.
+
+        Phase 10 #1: when the default household is created, we
+        also add the default user_id as its owner. This means
+        every existing user (and every fresh install) has at
+        least one household they own — no permission denials
+        on first run.
+        """
+        household_id = settings.default_household_user_id
+        existing = self.conn.execute(
+            "SELECT COUNT(*) FROM households WHERE household_id = ?", (household_id,)
+        ).fetchone()[0]
+        if existing == 0:
+            now = datetime.now().isoformat()
+            self.conn.execute(
+                "INSERT INTO households (household_id, name, created_at, updated_at, notes) VALUES (?, ?, ?, ?, ?)",
+                (household_id, "Default Household", now, now,
+                 "Default household created automatically. Use the household switcher to add more."),
+            )
+        # Always ensure the default user is at least a member
+        # of the default household (idempotent — INSERT OR IGNORE).
+        # The ``datetime`` reference below relies on the module-level
+        # import (line 6) — a local import in the ``if`` block above
+        # would shadow it and cause an UnboundLocalError on the second
+        # call (when ``existing > 0`` skips the import).
+        self.conn.execute(
+            "INSERT OR IGNORE INTO household_members "
+            "(household_id, user_id, role, joined_at) VALUES (?, ?, ?, ?)",
+            (household_id, household_id, "owner", datetime.now().isoformat()),
+        )
+        # Mark as active
+        self.set_config_value("active_household_id", household_id)
+        self.conn.commit()
+
+    def _seed_locations(self) -> None:
+        existing = self.conn.execute("SELECT COUNT(*) FROM household_locations").fetchone()[0]
+        if existing > 0:
+            return
+        locations = [
+            ("home", "Home", None, "room"),
+            ("kitchen", "Kitchen", "home", "room"),
+            ("fridge", "Fridge", "kitchen", "fridge"),
+            ("fridge_door", "Fridge Door", "fridge", "fridge"),
+            ("fridge_top", "Fridge Top Shelf", "fridge", "fridge"),
+            ("fridge_drawer", "Fridge Vegetable Drawer", "fridge", "fridge"),
+            ("freezer", "Freezer", "fridge", "freezer"),
+            ("pantry", "Pantry", "kitchen", "pantry"),
+            ("pantry_top", "Pantry Top Shelf", "pantry", "shelf"),
+            ("pantry_mid", "Pantry Middle Shelf", "pantry", "shelf"),
+            ("spice_box", "Spice Box", "pantry", "shelf"),
+            ("bathroom", "Bathroom", None, "room"),
+            ("bathroom_cabinet", "Bathroom Cabinet", "bathroom", "cabinet"),
+            ("bathroom_sink", "Under Bathroom Sink", "bathroom", "cabinet"),
+            ("bedroom", "Bedroom", None, "room"),
+            ("medicine_drawer", "Medicine Drawer", "bedroom", "drawer"),
+            ("balcony", "Balcony", None, "balcony"),
+            ("cleaning_shelf", "Balcony Cleaning Shelf", "balcony", "shelf"),
+        ]
+        for loc_id, name, parent, loc_type in locations:
+            self.conn.execute(
+                "INSERT INTO household_locations (location_id, name, parent_location_id, location_type) VALUES (?, ?, ?, ?)",
+                (loc_id, name, parent, loc_type),
+            )
+
+    # --- Trace retention policy ---
+
+    def _apply_trace_retention_policy(self) -> None:
+        max_rows = max(0, settings.trace_max_rows)
+        ttl_days = settings.trace_ttl_days
+        if max_rows:
+            self.prune_traces(max_rows=max_rows)
+        if ttl_days:
+            self.prune_traces(ttl_days=ttl_days)
+
+    def prune_traces(self, max_rows: int | None = None, ttl_days: int | None = None) -> int:
+        removed = 0
+        if max_rows is not None and max_rows > 0:
+            cursor = self.conn.execute(
+                """
+                DELETE FROM traces
+                WHERE rowid NOT IN (
+                    SELECT rowid FROM traces
+                    ORDER BY datetime(timestamp) DESC, rowid DESC LIMIT ?
+                )
+                """,
+                (max_rows,),
+            )
+            removed += cursor.rowcount
+
+        if ttl_days is not None and ttl_days > 0:
+            cutoff = (datetime.now() - timedelta(days=ttl_days)).isoformat()
+            cursor = self.conn.execute(
+                "DELETE FROM traces WHERE datetime(timestamp) < datetime(?)",
+                (cutoff,),
+            )
+            removed += cursor.rowcount
+
+        self.conn.commit()
+        return removed
+
+    def get_trace_by_id(self, trace_id: str, user_id: str = "") -> Trace | None:
+        target = (trace_id or "").strip()
+        if not target:
+            return None
+        query = "SELECT * FROM traces WHERE trace_id = ?"
+        params: list[str] = [target]
+        if user_id:
+            query += " AND user_id = ?"
+            params.append(user_id)
+        row = self.conn.execute(query, params).fetchone()
+        return _row_to_trace(row) if row else None
+
+    # --- Inventory CRUD ---
+
+    def add_inventory_lot(self, lot: InventoryLot, user_id: str = "") -> InventoryLot:
+        # ── Phase 11: permission gate (supersession-safe additive check) ──
+        # The unwrapped behavior is preserved; we just fail closed
+        # on permission denial. The old method is not renamed or
+        # removed — it stays a single source of truth, with a
+        # permission check at the top.
+        from shopstack.services.permissions import require_write as _rw
+        if not user_id:
+            user_id = self.active_household_id
+        # user_id doubles as the household scope being written to; check
+        # self-membership (seeded by _seed_default_household for every
+        # household) rather than against self.active_household_id, which
+        # may be a different household than the one being written.
+        _rw(user_id, user_id, self)  # raises PermissionError on deny
+        self.conn.execute(
+            """INSERT INTO inventory_lots
+               (lot_id, canonical_name, display_name, category, quantity, unit,
+                storage_location_id, purchase_date, estimated_use_by_date,
+                label_expiry_date, opened_date, price_paid, currency,
+                source_event_id, confidence, image_crop_path, status, created_at, updated_at, user_id)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                lot.lot_id, lot.canonical_name, lot.display_name, lot.category,
+                lot.quantity, lot.unit, lot.storage_location_id,
+                _d(lot.purchase_date), _d(lot.estimated_use_by_date),
+                _d(lot.label_expiry_date), _d(lot.opened_date),
+                lot.price_paid, lot.currency, lot.source_event_id,
+                lot.confidence, lot.image_crop_path, lot.status,
+                lot.created_at.isoformat(), lot.updated_at.isoformat(),
+                user_id,
+            ),
+        )
+        self.conn.commit()
+        return lot
+
+    def update_inventory_lot(self, lot_id: str, updates: dict, user_id: str = "") -> InventoryLot | None:
+        existing = self.get_inventory_lot(lot_id)
+        if not existing:
+            return None
+        fields = ["canonical_name", "display_name", "category", "quantity", "unit",
+                  "storage_location_id", "purchase_date", "estimated_use_by_date",
+                  "label_expiry_date", "opened_date", "price_paid", "currency",
+                  "confidence", "image_crop_path", "status", "user_id"]
+        set_clauses = []
+        vals = []
+        for f in fields:
+            if f in updates:
+                set_clauses.append(f"{f} = ?")
+                vals.append(updates[f])
+        if set_clauses:
+            set_clauses.append("updated_at = ?")
+            vals.append(datetime.now().isoformat())
+            vals.append(lot_id)
+            self.conn.execute(
+                f"UPDATE inventory_lots SET {', '.join(set_clauses)} WHERE lot_id = ?",
+                vals,
+            )
+            self.conn.commit()
+        return self.get_inventory_lot(lot_id)
+
+    def get_inventory_lot(self, lot_id: str) -> InventoryLot | None:
+        row = self.conn.execute(
+            "SELECT * FROM inventory_lots WHERE lot_id = ?", (lot_id,)
+        ).fetchone()
+        return _row_to_lot(row) if row else None
+
+    def get_inventory_lot_ids(self, lot_id_prefix: str) -> list[str]:
+        if not lot_id_prefix:
+            return []
+        exact = self.get_inventory_lot(lot_id_prefix)
+        if exact:
+            return [lot_id_prefix]
+        rows = self.conn.execute(
+            "SELECT lot_id FROM inventory_lots WHERE lot_id LIKE ? ORDER BY lot_id", (f"{lot_id_prefix}%",)
+        ).fetchall()
+        return [r["lot_id"] for r in rows]
+
+    def resolve_inventory_lot_id(self, lot_id_or_prefix: str) -> str | None:
+        ids = self.get_inventory_lot_ids(lot_id_or_prefix)
+        if len(ids) == 1:
+            return ids[0]
+        return None
+
+    def get_inventory(
+        self, status: str | None = None, location_id: str | None = None,
+        category: str | None = None, user_id: str = "",
+        canonical_name: str | None = None,
+    ) -> list[InventoryLot]:
+        parts = ["SELECT * FROM inventory_lots WHERE 1=1"]
+        params: list[Any] = []
+        if user_id:
+            parts.append("AND user_id = ?")
+            params.append(user_id)
+        if status:
+            parts.append("AND status = ?")
+            params.append(status)
+        if location_id:
+            parts.append("AND storage_location_id = ?")
+            params.append(location_id)
+        if category:
+            parts.append("AND category = ?")
+            params.append(category)
+        if canonical_name:
+            parts.append("AND canonical_name = ?")
+            params.append(canonical_name)
+        parts.append("ORDER BY created_at DESC")
+        rows = self.conn.execute(" ".join(parts), params).fetchall()
+        return [_row_to_lot(r) for r in rows if r]
+
+    def consume_inventory(self, lot_id: str, quantity: float) -> InventoryLot | None:
+        # ── Phase 11: permission gate (additive, supersession-safe) ──
+        from shopstack.services.permissions import require_write as _rw
+        if quantity < 0:
+            raise ValueError("quantity must be greater than 0")
+        lot = self.get_inventory_lot(lot_id)
+        if not lot:
+            return None
+        # The lot's user_id is the household. Check that the active
+        # user is a member of that household with write access.
+        _rw(lot.user_id or self.active_household_id,
+            self.active_household_id, self)
+        new_qty = max(0.0, lot.quantity - quantity)
+        status = lot.status
+        if new_qty <= 0:
+            new_qty = 0
+            status = "used"
+        elif new_qty < lot.quantity * 0.2:
+            status = "low"
+        return self.update_inventory_lot(lot_id, {"quantity": new_qty, "status": status})
+
+    def mark_list_complete(self, list_id: str) -> None:
+        self.conn.execute(
+            "UPDATE shopping_lists SET is_active = 0, updated_at = ? WHERE list_id = ?",
+            (datetime.now().isoformat(), list_id),
+        )
+        self.conn.commit()
+
+    # --- Shopping List CRUD ---
+
+    def create_shopping_list(
+        self,
+        name: str = "Shopping List",
+        goal: str = "",
+        user_id: str = "",
+        list_id: str | None = None,
+    ) -> ShoppingList:
+        """Create a new shopping list. By default the list_id is auto-generated;
+        callers (e.g. backup restore) can pass ``list_id`` to preserve an
+        existing id from the source DB.
+        """
+        if list_id is not None:
+            sl = ShoppingList(name=name, goal=goal)
+            sl.list_id = list_id
+        else:
+            sl = ShoppingList(name=name, goal=goal)
+        self.conn.execute(
+            "INSERT INTO shopping_lists (list_id, name, created_at, updated_at, goal, is_active, user_id) VALUES (?, ?, ?, ?, ?, 1, ?)",
+            (sl.list_id, sl.name, sl.created_at.isoformat(), sl.updated_at.isoformat(), sl.goal, user_id),
+        )
+        self.conn.commit()
+        return sl
+
+    def get_active_shopping_list(self, user_id: str = "") -> ShoppingList | None:
+        query = "SELECT * FROM shopping_lists WHERE is_active = 1"
+        params: list[str] = []
+        if user_id:
+            query += " AND user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY created_at DESC LIMIT 1"
+        row = self.conn.execute(query, params).fetchone()
+        if not row:
+            return None
+        return _row_to_list(row, self.conn)
+
+    def add_list_item(self, list_id: str, item: ShoppingListItem) -> ShoppingListItem:
+        # ── Phase 11: permission gate ──
+        # Uses active_household_id as both user and household because
+        # add_list_item doesn't receive an explicit user_id parameter.
+        # The seed creates household_id as its own owner member, so
+        # this check succeeds for the default case. If per-user
+        # tracking is added later, this should accept a user_id param.
+        from shopstack.services.permissions import require_write as _rw
+        _rw(self.active_household_id, self.active_household_id, self)
+        self.conn.execute(
+            "INSERT INTO shopping_list_items (item_id, list_id, canonical_name, requested_quantity, unit, priority, reason, status, linked_lots) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (item.list_item_id, list_id, item.canonical_name, item.requested_quantity,
+             item.unit, item.priority, item.reason, item.status,
+             json.dumps(item.linked_inventory_lots)),
+        )
+        self.conn.execute(
+            "UPDATE shopping_lists SET updated_at = ? WHERE list_id = ?",
+            (datetime.now().isoformat(), list_id),
+        )
+        self.conn.commit()
+        return item
+
+    def update_list_item(self, item_id: str, updates: dict) -> None:
+        item = self.conn.execute(
+            "SELECT * FROM shopping_list_items WHERE item_id = ?", (item_id,)
+        ).fetchone()
+        if not item:
+            return
+        fields = ["canonical_name", "requested_quantity", "unit", "priority", "reason", "status"]
+        set_clauses = []
+        vals = []
+        for f in fields:
+            if f in updates:
+                set_clauses.append(f"{f} = ?")
+                vals.append(updates[f])
+        if set_clauses:
+            vals.append(item_id)
+            self.conn.execute(
+                f"UPDATE shopping_list_items SET {', '.join(set_clauses)} WHERE item_id = ?",
+                vals,
+            )
+            self.conn.commit()
+        if "list_id" in updates:
+            self.conn.execute(
+                "UPDATE shopping_lists SET updated_at = ? WHERE list_id = ?",
+                (datetime.now().isoformat(), updates["list_id"]),
+            )
+            self.conn.commit()
+
+    # --- Locations ---
+
+    def get_locations(self) -> list[HouseholdLocation]:
+        rows = self.conn.execute("SELECT * FROM household_locations ORDER BY name").fetchall()
+        return [_row_to_location(r) for r in rows]
+
+    def get_location(self, location_id: str) -> HouseholdLocation | None:
+        row = self.conn.execute(
+            "SELECT * FROM household_locations WHERE location_id = ?", (location_id,)
+        ).fetchone()
+        return _row_to_location(row) if row else None
+
+    # --- Movements ---
+
+    def record_movement(self, movement: MovementEvent) -> MovementEvent:
+        # ── Phase 11: permission gate ──
+        # Uses active_household_id as both user and household because
+        # record_movement doesn't receive an explicit user_id parameter.
+        # See add_list_item for rationale.
+        from shopstack.services.permissions import require_write as _rw
+        _rw(self.active_household_id, self.active_household_id, self)
+        self.conn.execute(
+            "INSERT INTO movement_events (movement_id, lot_id, from_location_id, to_location_id, timestamp, source, confidence) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (movement.movement_id, movement.lot_id, movement.from_location_id,
+             movement.to_location_id, movement.timestamp.isoformat(),
+             movement.source, movement.confidence),
+        )
+        self.conn.execute(
+            "UPDATE inventory_lots SET storage_location_id = ?, updated_at = ? WHERE lot_id = ?",
+            (movement.to_location_id, datetime.now().isoformat(), movement.lot_id),
+        )
+        self.conn.commit()
+        return movement
+
+    def get_movements_for_lot(self, lot_id: str) -> list[MovementEvent]:
+        rows = self.conn.execute(
+            "SELECT * FROM movement_events WHERE lot_id = ? ORDER BY timestamp DESC",
+            (lot_id,),
+        ).fetchall()
+        return [_row_to_movement(r) for r in rows]
+
+    # --- Negative Memory (Object Trail) ---
+
+    def add_negative_memory(self, lot_id: str, location_id: str, location_name: str = "", source: str = "user_feedback", confidence: float = 1.0, user_id: str = "") -> dict:
+        """Record that an item has been confirmed NOT to be at a location."""
+        memory_id = f"negmem_{new_id()}"
+        self.conn.execute(
+            "INSERT INTO negative_memory (memory_id, lot_id, location_id, location_name, confirmed_at, source, confidence, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (memory_id, lot_id, location_id, location_name, datetime.now().isoformat(), source, confidence, user_id),
+        )
+        self.conn.commit()
+        return {"memory_id": memory_id, "lot_id": lot_id, "location_id": location_id}
+
+    def get_negative_memory_for_lot(self, lot_id: str) -> list[dict]:
+        """Get all negative memory entries for a given lot."""
+        rows = self.conn.execute(
+            "SELECT * FROM negative_memory WHERE lot_id = ? ORDER BY confirmed_at DESC",
+            (lot_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def delete_negative_memory(self, memory_id: str) -> bool:
+        """Remove a negative memory entry."""
+        self.conn.execute("DELETE FROM negative_memory WHERE memory_id = ?", (memory_id,))
+        self.conn.commit()
+        return True
+
+    # --- Person Associations (Object Trail) ---
+
+    def add_person_association(self, lot_id: str, person_id: str, person_name: str, relationship: str = "owner", confidence: float = 1.0, user_id: str = "") -> dict:
+        """Record a person association for an item."""
+        association_id = f"personassoc_{new_id()}"
+        self.conn.execute(
+            "INSERT INTO person_associations (association_id, lot_id, person_id, person_name, relationship, confidence, user_id) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (association_id, lot_id, person_id, person_name, relationship, confidence, user_id),
+        )
+        self.conn.commit()
+        return {"association_id": association_id, "lot_id": lot_id, "person_id": person_id}
+
+    def get_person_associations_for_lot(self, lot_id: str) -> list[dict]:
+        """Get all person associations for a given lot."""
+        rows = self.conn.execute(
+            "SELECT * FROM person_associations WHERE lot_id = ?",
+            (lot_id,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def delete_person_association(self, association_id: str) -> bool:
+        """Remove a person association."""
+        self.conn.execute("DELETE FROM person_associations WHERE association_id = ?", (association_id,))
+        self.conn.commit()
+        return True
+
+    # --- Price Observations ---
+
+    def record_price(self, price: PriceObservation, user_id: str = "") -> PriceObservation:
+        # ── Phase 11: permission gate (additive, supersession-safe) ──
+        from shopstack.services.permissions import require_write as _rw
+        if not user_id:
+            user_id = self.active_household_id
+        _rw(user_id, user_id, self)
+        self.conn.execute(
+            "INSERT INTO price_observations (price_id, canonical_name, quantity, unit, price, currency, store_name, store_id, observation_date, source_event_id, notes, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (price.price_id, price.canonical_name, price.quantity, price.unit,
+             price.price, price.currency, price.store_name, price.store_id,
+             _d(price.observation_date), price.source_event_id, price.notes,
+             user_id),
+        )
+        self.conn.commit()
+        return price
+
+    def get_price_history(self, canonical_name: str, user_id: str = "") -> list[PriceObservation]:
+        query = "SELECT * FROM price_observations WHERE canonical_name = ?"
+        params: list[str | None] = [canonical_name]
+        if user_id:
+            query += " AND user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY observation_date DESC, rowid DESC"
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_price(r) for r in rows]
+
+    # --- Stores ---
+
+    def add_store(self, store: Store) -> Store:
+        self.conn.execute(
+            "INSERT INTO stores (store_id, name, location, store_type, notes) VALUES (?, ?, ?, ?, ?)",
+            (store.store_id, store.name, store.location, store.store_type, store.notes),
+        )
+        self.conn.commit()
+        return store
+
+    def get_stores(self) -> list[Store]:
+        rows = self.conn.execute("SELECT * FROM stores ORDER BY name").fetchall()
+        return [_row_to_store(r) for r in rows]
+
+    # --- App Config ---
+
+    def get_config_value(self, key: str, default: str = "") -> str:
+        row = self.conn.execute(
+            "SELECT value FROM app_config WHERE key = ?",
+            (key,),
+        ).fetchone()
+        return row["value"] if row else default
+
+    def set_config_value(self, key: str, value: str) -> None:
+        self.conn.execute(
+            "INSERT OR REPLACE INTO app_config (key, value) VALUES (?, ?)",
+            (key, value),
+        )
+        self.conn.commit()
+
+    # --- Traces ---
+
+    def save_trace(self, trace: Trace, user_id: str = "") -> Trace:
+        if not user_id:
+            user_id = self.active_household_id
+        self.conn.execute(
+            "INSERT OR REPLACE INTO traces (trace_id, input_type, user_goal, redacted_user_request, perception, inventory_context, decision, proposed_tool_calls, human_confirmation, final_response, timestamp, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                trace.trace_id, trace.input_type, trace.user_goal,
+                trace.redacted_user_request, json.dumps(trace.perception),
+                json.dumps(trace.inventory_context), json.dumps(trace.decision),
+                json.dumps([t.model_dump() for t in trace.proposed_tool_calls], default=str),
+                trace.human_confirmation, trace.final_response,
+                trace.timestamp.isoformat(),
+                user_id,
+            ),
+        )
+        self.conn.commit()
+        self.prune_traces(
+            max_rows=max(0, settings.trace_max_rows),
+            ttl_days=settings.trace_ttl_days,
+        )
+        return trace
+
+    def get_traces(self, limit: int = 50, user_id: str = "") -> list[Trace]:
+        query = "SELECT * FROM traces"
+        params: list[str | int] = []
+        if user_id:
+            query += " WHERE user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_trace(r) for r in rows]
+
+    # --- Purchase Events ---
+
+    def add_purchase_event(self, event: PurchaseEvent, user_id: str = "") -> PurchaseEvent:
+        # ── Phase 11: permission gate (additive, supersession-safe) ──
+        from shopstack.services.permissions import require_write as _rw
+        if not user_id:
+            user_id = self.active_household_id
+        _rw(user_id, user_id, self)
+        self.conn.execute(
+            "INSERT INTO purchase_events (event_id, timestamp, canonical_name, quantity, unit, total_price, currency, source_type, store_name, raw_text, source_file_path, confirmed, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (event.event_id, event.timestamp.isoformat(),
+             event.canonical_name, event.quantity, event.unit,
+             event.total_price, event.currency, event.source_type,
+             event.store_name, event.raw_text, event.source_file_path,
+             1 if event.confirmed else 0,
+             user_id),
+        )
+        self.conn.commit()
+        return event
+
+    def get_purchase_events(self, limit: int = 20, user_id: str = "") -> list[PurchaseEvent]:
+        query = "SELECT * FROM purchase_events"
+        params: list[str | int] = []
+        if user_id:
+            query += " WHERE user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_purchase(r) for r in rows]
+
+    def get_purchases(self, limit: int = 20) -> list[PurchaseEvent]:
+        return self.get_purchase_events(limit=limit)
+
+    # --- Reconciliation Events ---
+
+    def add_reconciliation_event(self, event: ReconciliationEvent, user_id: str = "") -> ReconciliationEvent:
+        # ── Phase 11: permission gate (additive, supersession-safe) ──
+        from shopstack.services.permissions import require_write as _rw
+        if not user_id:
+            user_id = self.active_household_id
+        _rw(user_id, user_id, self)
+        self.conn.execute(
+            "INSERT INTO reconciliation_events (event_id, timestamp, canonical_name, planned_action, actual_action, quantity, unit, price_paid, planned_price, substituted_with, notes, source, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (event.event_id, event.timestamp.isoformat(),
+             event.canonical_name, event.planned_action, event.actual_action,
+             event.quantity, event.unit, event.price_paid, event.planned_price,
+             event.substituted_with, event.notes, event.source, user_id),
+        )
+        self.conn.commit()
+        return event
+
+    def get_reconciliation_events(self, canonical_name: str | None = None, limit: int = 20, user_id: str = "") -> list[ReconciliationEvent]:
+        query = "SELECT * FROM reconciliation_events WHERE 1=1"
+        params: list[str | int] = []
+        if canonical_name:
+            query += " AND canonical_name = ?"
+            params.append(canonical_name)
+        if user_id:
+            query += " AND user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_reconciliation(r) for r in rows]
+
+    # --- Inventory Events (audit trail) ---
+
+    def record_inventory_event(self, event: InventoryEvent, user_id: str = "") -> InventoryEvent:
+        self.conn.execute(
+            """INSERT INTO inventory_events
+               (event_id, timestamp, lot_id, canonical_name, action,
+                quantity_before, quantity_after, quantity_delta, unit,
+                location_from, location_to, source, notes, user_id)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (event.event_id, event.timestamp.isoformat(),
+             event.lot_id, event.canonical_name, event.action,
+             event.quantity_before, event.quantity_after, event.quantity_delta,
+             event.unit, event.location_from, event.location_to,
+             event.source, event.notes, user_id),
+        )
+        self.conn.commit()
+        return event
+
+    def get_inventory_events(self, canonical_name: str = "", lot_id: str = "", limit: int = 50) -> list[InventoryEvent]:
+        query = "SELECT * FROM inventory_events"
+        params: list[Any] = []
+        conditions = []
+        if canonical_name:
+            conditions.append("canonical_name = ?")
+            params.append(canonical_name.lower())
+        if lot_id:
+            conditions.append("lot_id = ?")
+            params.append(lot_id)
+        if conditions:
+            query += " WHERE " + " AND ".join(conditions)
+        query += " ORDER BY timestamp DESC LIMIT ?"
+        params.append(limit)
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_inventory_event(r) for r in rows]
+
+    def get_inventory_timeline(self, canonical_name: str, limit: int = 20) -> list[InventoryEvent]:
+        return self.get_inventory_events(canonical_name=canonical_name, limit=limit)
+
+    # --- Preference Signals ---
+
+    def add_preference_signal(self, signal: PreferenceSignal, user_id: str = "") -> PreferenceSignal:
+        # ── Phase 11: permission gate (additive, supersession-safe) ──
+        from shopstack.services.permissions import require_write as _rw
+        if not user_id:
+            user_id = self.active_household_id
+        _rw(user_id, user_id, self)
+        self.conn.execute(
+            "INSERT INTO preference_signals (signal_id, canonical_name, signal_type, value, confidence, source, created_at, updated_at, user_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (signal.signal_id, signal.canonical_name, signal.signal_type,
+             signal.value, signal.confidence, signal.source,
+             signal.created_at.isoformat(), signal.updated_at.isoformat(), user_id),
+        )
+        self.conn.commit()
+        return signal
+
+    def get_preference_signals(self, canonical_name: str | None = None, user_id: str = "") -> list[PreferenceSignal]:
+        query = "SELECT * FROM preference_signals WHERE 1=1"
+        params: list[str] = []
+        if canonical_name:
+            query += " AND canonical_name = ?"
+            params.append(canonical_name)
+        if user_id:
+            query += " AND user_id = ?"
+            params.append(user_id)
+        query += " ORDER BY updated_at DESC"
+        rows = self.conn.execute(query, params).fetchall()
+        return [_row_to_preference(r) for r in rows]
+
+    def delete_preference_signal(self, signal_id: str) -> bool:
+        cursor = self.conn.execute(
+            "DELETE FROM preference_signals WHERE signal_id = ?",
+            (signal_id,),
+        )
+        self.conn.commit()
+        return cursor.rowcount > 0
+
+    # --- Market Snapshot Records ---
+
+    def save_market_snapshot(self, snapshot) -> bool:
+        from shopstack.market.schema import NormalizedMarketRecord, MarketSnapshot
+        if not isinstance(snapshot, MarketSnapshot):
+            return False
+
+        self.conn.execute(
+            """
+            INSERT OR REPLACE INTO market_snapshots
+            (snapshot_id, source, source_category, captured_at, record_count, analytics, freshness_context, stored_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                snapshot.snapshot_id,
+                snapshot.source,
+                snapshot.source_category,
+                snapshot.captured_at,
+                len(snapshot.normalized_records),
+                json.dumps(snapshot.analytics or {}, sort_keys=True),
+                snapshot.analytics.get("freshness", "unknown") if isinstance(snapshot.analytics, dict) else "unknown",
+                datetime.now(timezone.utc).isoformat(),
+            ),
+        )
+        self.conn.execute("DELETE FROM market_record_components WHERE record_id IN (SELECT record_id FROM market_records WHERE snapshot_id = ?)", (snapshot.snapshot_id,))
+        self.conn.execute("DELETE FROM market_records WHERE snapshot_id = ?", (snapshot.snapshot_id,))
+
+        for idx, record in enumerate(snapshot.normalized_records):
+            if not isinstance(record, NormalizedMarketRecord):
+                continue
+            record_id = f"{snapshot.snapshot_id}::{idx:05d}"
+            self.conn.execute(
+                """
+                INSERT OR REPLACE INTO market_records (
+                    record_id, snapshot_id, raw_name, canonical_name, description, raw_size, normalized_quantity,
+                    normalized_unit, package_count, is_combo, is_weight_based, is_piece_based, is_size_class,
+                    size_class, price_inr, mrp_inr, discount_percent_displayed, discount_amount_inr,
+                    computed_discount_percent, availability, is_available, tag, is_ad, is_upgrade, card_index,
+                    delivery_time, price_per_kg, price_per_100g, price_per_piece, normalization_warnings, variety, brand
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    record_id,
+                    snapshot.snapshot_id,
+                    record.raw_name,
+                    record.canonical_name,
+                    record.description,
+                    record.raw_size,
+                    record.normalized_quantity,
+                    record.normalized_unit,
+                    record.package_count,
+                    int(record.is_combo),
+                    int(record.is_weight_based),
+                    int(record.is_piece_based),
+                    int(record.is_size_class),
+                    record.size_class,
+                    record.price_inr,
+                    record.mrp_inr,
+                    record.discount_percent_displayed,
+                    record.discount_amount_inr,
+                    record.computed_discount_percent,
+                    record.availability,
+                    int(record.is_available),
+                    record.tag,
+                    int(record.is_ad),
+                    int(record.is_upgrade),
+                    record.card_index,
+                    record.delivery_time,
+                    record.price_per_kg,
+                    record.price_per_100g,
+                    record.price_per_piece,
+                    json.dumps(record.normalization_warnings or []),
+                    record.variety,
+                    record.brand,
+                ),
+            )
+            self.conn.execute("DELETE FROM market_record_components WHERE record_id = ?", (record_id,))
+            for component_name in record.component_names:
+                component_id = f"{record_id}::{component_name}"
+                self.conn.execute(
+                    "INSERT OR IGNORE INTO market_record_components (component_id, record_id, component_name) VALUES (?, ?, ?)",
+                    (component_id, record_id, component_name),
+                )
+
+        self.conn.commit()
+        return True
+
+    def get_market_snapshot(self, snapshot_id: str):
+        from shopstack.market.schema import MarketSnapshot
+        row = self.conn.execute(
+            "SELECT snapshot_id, source, source_category, captured_at, analytics FROM market_snapshots WHERE snapshot_id = ?",
+            (snapshot_id,),
+        ).fetchone()
+        if not row:
+            return None
+
+        return MarketSnapshot(
+            snapshot_id=row["snapshot_id"],
+            source=row["source"],
+            source_category=row["source_category"],
+            captured_at=row["captured_at"],
+            raw_records=[],
+            normalized_records=self.get_market_records(snapshot_id),
+            analytics=json.loads(row["analytics"] or "{}"),
+        )
+
+    def get_latest_market_snapshot(self, source: str):
+        row = self.conn.execute(
+            "SELECT snapshot_id FROM market_snapshots WHERE source = ? ORDER BY captured_at DESC LIMIT 1",
+            (source,),
+        ).fetchone()
+        if not row:
+            return None
+        return self.get_market_snapshot(row["snapshot_id"])
+
+    def get_market_records(self, snapshot_id: str) -> list:
+        from shopstack.market.schema import NormalizedMarketRecord
+        rows = self.conn.execute(
+            "SELECT * FROM market_records WHERE snapshot_id = ? ORDER BY card_index ASC, raw_name ASC",
+            (snapshot_id,),
+        ).fetchall()
+
+        snap_row = self.conn.execute(
+            "SELECT source, source_category, captured_at FROM market_snapshots WHERE snapshot_id = ?",
+            (snapshot_id,),
+        ).fetchone()
+
+        source = snap_row["source"] if snap_row else ""
+        source_category = snap_row["source_category"] if snap_row else ""
+        captured_at = snap_row["captured_at"] if snap_row else ""
+
+        records: list[NormalizedMarketRecord] = []
+        for row in rows:
+            comp_rows = self.conn.execute(
+                "SELECT component_name FROM market_record_components WHERE record_id = ? ORDER BY component_name ASC",
+                (row["record_id"],),
+            ).fetchall()
+            components = [r["component_name"] for r in comp_rows]
+            raw_warnings = row["normalization_warnings"]
+            if isinstance(raw_warnings, str):
+                try:
+                    warnings = json.loads(raw_warnings)
+                except json.JSONDecodeError:
+                    warnings = []
+            else:
+                warnings = []
+            records.append(
+                NormalizedMarketRecord(
+                    source=source,
+                    source_category=source_category,
+                    raw_name=row["raw_name"],
+                    canonical_name=row["canonical_name"],
+                    description=row["description"],
+                    raw_size=row["raw_size"],
+                    normalized_quantity=row["normalized_quantity"],
+                    normalized_unit=row["normalized_unit"],
+                    package_count=row["package_count"],
+                    is_combo=bool(row["is_combo"]),
+                    is_weight_based=bool(row["is_weight_based"]),
+                    is_piece_based=bool(row["is_piece_based"]),
+                    is_size_class=bool(row["is_size_class"]),
+                    size_class=row["size_class"],
+                    price_inr=row["price_inr"],
+                    mrp_inr=row["mrp_inr"],
+                    discount_percent_displayed=row["discount_percent_displayed"],
+                    discount_amount_inr=row["discount_amount_inr"],
+                    computed_discount_percent=row["computed_discount_percent"],
+                    availability=row["availability"],
+                    is_available=bool(row["is_available"]),
+                    tag=row["tag"],
+                    is_ad=bool(row["is_ad"]),
+                    is_upgrade=bool(row["is_upgrade"]),
+                    card_index=row["card_index"],
+                    delivery_time=row["delivery_time"],
+                    captured_at=captured_at,
+                    snapshot_id=row["snapshot_id"],
+                    price_per_kg=row["price_per_kg"],
+                    price_per_100g=row["price_per_100g"],
+                    price_per_piece=row["price_per_piece"],
+                    normalization_warnings=warnings,
+                    component_names=components,
+                    variety=row["variety"],
+                    brand=row["brand"],
+                )
+            )
+        return records
+
+    def get_records_by_canonical(self, canonical_name: str) -> list:
+        from shopstack.market.schema import NormalizedMarketRecord
+        # If normalized rows are requested without full context, use snapshot join in SQL.
+        rows_with_snap = self.conn.execute(
+            """
+            SELECT mr.*, ms.source, ms.source_category, ms.captured_at
+            FROM market_records AS mr
+            JOIN market_snapshots AS ms ON ms.snapshot_id = mr.snapshot_id
+            WHERE mr.canonical_name = ?
+            ORDER BY ms.captured_at DESC
+            """,
+            (canonical_name,),
+        ).fetchall()
+        records: list[NormalizedMarketRecord] = []
+        for row in rows_with_snap:
+            raw_warnings = row["normalization_warnings"]
+            if isinstance(raw_warnings, str):
+                try:
+                    warnings = json.loads(raw_warnings)
+                except json.JSONDecodeError:
+                    warnings = []
+            else:
+                warnings = []
+
+            _comp_rows = self.conn.execute(
+                "SELECT component_name FROM market_record_components WHERE record_id = ? ORDER BY component_name ASC",
+                (row["record_id"],),
+            ).fetchall()
+            records.append(
+                NormalizedMarketRecord(
+                    source=row["source"],
+                    source_category=row["source_category"],
+                    raw_name=row["raw_name"],
+                    canonical_name=row["canonical_name"],
+                    description=row["description"],
+                    raw_size=row["raw_size"],
+                    normalized_quantity=row["normalized_quantity"],
+                    normalized_unit=row["normalized_unit"],
+                    package_count=row["package_count"],
+                    is_combo=bool(row["is_combo"]),
+                    is_weight_based=bool(row["is_weight_based"]),
+                    is_piece_based=bool(row["is_piece_based"]),
+                    is_size_class=bool(row["is_size_class"]),
+                    size_class=row["size_class"],
+                    price_inr=row["price_inr"],
+                    mrp_inr=row["mrp_inr"],
+                    discount_percent_displayed=row["discount_percent_displayed"],
+                    discount_amount_inr=row["discount_amount_inr"],
+                    computed_discount_percent=row["computed_discount_percent"],
+                    availability=row["availability"],
+                    is_available=bool(row["is_available"]),
+                    tag=row["tag"],
+                    is_ad=bool(row["is_ad"]),
+                    is_upgrade=bool(row["is_upgrade"]),
+                    card_index=row["card_index"],
+                    delivery_time=row["delivery_time"],
+                    captured_at=row["captured_at"],
+                    snapshot_id=row["snapshot_id"],
+                    price_per_kg=row["price_per_kg"],
+                    price_per_100g=row["price_per_100g"],
+                    price_per_piece=row["price_per_piece"],
+                    normalization_warnings=warnings,
+                    component_names=[r2["component_name"] for r2 in self.conn.execute(
+                        "SELECT component_name FROM market_record_components WHERE record_id = ? ORDER BY component_name ASC",
+                        (row["record_id"],),
+                    ).fetchall()],
+                    variety=row["variety"],
+                    brand=row["brand"],
+                )
+            )
+        return records
+
+    def close(self) -> None:
+        c = getattr(self._local, "conn", None)
+        if c is not None:
+            c.close()
+            self._local.conn = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self):
+        # Defensive cleanup: ensure sqlite connections are closed even if callers
+        # forget an explicit ``close()`` (important during module reloads and
+        # test teardown paths that recreate app_context).
+        try:
+            self.close()
+        except Exception:
+            # Never raise during finalization; mirror sqlite's permissive close
+            # semantics when objects are already partially torn down.
+            pass
+
+
+def _d(dt: date | str | None) -> str | None:
+    if dt is None:
+        return None
+    if isinstance(dt, str):
+        return dt
+    return dt.isoformat()
+
+
+def _row_to_lot(row: sqlite3.Row) -> InventoryLot:
+    return InventoryLot(
+        lot_id=row["lot_id"], canonical_name=row["canonical_name"],
+        display_name=row["display_name"], category=row["category"],
+        quantity=row["quantity"], unit=row["unit"],
+        storage_location_id=row["storage_location_id"],
+        purchase_date=_parse_d(row["purchase_date"]),
+        estimated_use_by_date=_parse_d(row["estimated_use_by_date"]),
+        label_expiry_date=_parse_d(row["label_expiry_date"]),
+        opened_date=_parse_d(row["opened_date"]),
+        price_paid=row["price_paid"], currency=row["currency"],
+        source_event_id=row["source_event_id"], confidence=row["confidence"],
+        image_crop_path=row["image_crop_path"], status=row["status"],
+        user_id=row["user_id"] if "user_id" in row.keys() else "",
+        created_at=datetime.fromisoformat(row["created_at"]) if row["created_at"] else datetime.now(),
+        updated_at=datetime.fromisoformat(row["updated_at"]) if row["updated_at"] else datetime.now(),
+    )
+
+
+def _parse_d(val: str | None) -> date | None:
+    if val is None:
+        return None
+    try:
+        return date.fromisoformat(val)
+    except (ValueError, TypeError):
+        return None
+
+
+def _row_to_list(row: sqlite3.Row, conn: sqlite3.Connection) -> ShoppingList:
+    item_rows = conn.execute(
+        "SELECT * FROM shopping_list_items WHERE list_id = ?", (row["list_id"],)
+    ).fetchall()
+    items = []
+    for ir in item_rows:
+        items.append(ShoppingListItem(
+            list_item_id=ir["item_id"], canonical_name=ir["canonical_name"],
+            requested_quantity=ir["requested_quantity"], unit=ir["unit"],
+            priority=ir["priority"], reason=ir["reason"], status=ir["status"],
+            linked_inventory_lots=json.loads(ir["linked_lots"] or "[]"),
+        ))
+    return ShoppingList(
+        list_id=row["list_id"], name=row["name"], goal=row["goal"],
+        is_active=bool(row["is_active"]), items=items,
+        created_at=datetime.fromisoformat(row["created_at"]) if row["created_at"] else datetime.now(),
+        updated_at=datetime.fromisoformat(row["updated_at"]) if row["updated_at"] else datetime.now(),
+    )
+
+
+def _row_to_location(row: sqlite3.Row) -> HouseholdLocation:
+    return HouseholdLocation(
+        location_id=row["location_id"], name=row["name"],
+        parent_location_id=row["parent_location_id"],
+        location_type=row["location_type"], photo_path=row["photo_path"],
+        notes=row["notes"],
+    )
+
+
+def _row_to_movement(row: sqlite3.Row) -> MovementEvent:
+    return MovementEvent(
+        movement_id=row["movement_id"], lot_id=row["lot_id"],
+        from_location_id=row["from_location_id"],
+        to_location_id=row["to_location_id"],
+        timestamp=datetime.fromisoformat(row["timestamp"]) if row["timestamp"] else datetime.now(),
+        source=row["source"], confidence=row["confidence"],
+    )
+
+
+def _row_to_price(row: sqlite3.Row) -> PriceObservation:
+    parsed = _parse_d(row["observation_date"])
+    return PriceObservation(
+        price_id=row["price_id"], canonical_name=row["canonical_name"],
+        quantity=row["quantity"], unit=row["unit"], price=row["price"],
+        currency=row["currency"], store_name=row["store_name"],
+        store_id=row["store_id"],
+        observation_date=parsed if parsed is not None else date.today(),
+        source_event_id=row["source_event_id"], notes=row["notes"],
+    )
+
+
+def _row_to_store(row: sqlite3.Row) -> Store:
+    return Store(
+        store_id=row["store_id"], name=row["name"],
+        location=row["location"], store_type=row["store_type"],
+        notes=row["notes"],
+    )
+
+
+def _row_to_trace(row: sqlite3.Row) -> Trace:
+    return Trace(
+        trace_id=row["trace_id"], input_type=row["input_type"],
+        user_goal=row["user_goal"],
+        redacted_user_request=row["redacted_user_request"],
+        perception=json.loads(row["perception"] or "{}"),
+        inventory_context=json.loads(row["inventory_context"] or "{}"),
+        decision=json.loads(row["decision"] or "{}"),
+        proposed_tool_calls=[
+            _dict_to_tc(t) for t in json.loads(row["proposed_tool_calls"] or "[]")
+        ],
+        human_confirmation=row["human_confirmation"],
+        final_response=row["final_response"],
+        timestamp=datetime.fromisoformat(row["timestamp"]) if row["timestamp"] else datetime.now(),
+    )
+
+
+def _row_to_purchase(row: sqlite3.Row) -> PurchaseEvent:
+    return PurchaseEvent(
+        event_id=row["event_id"],
+        timestamp=datetime.fromisoformat(row["timestamp"]) if row["timestamp"] else datetime.now(),
+        canonical_name=row["canonical_name"], quantity=row["quantity"],
+        unit=row["unit"], total_price=row["total_price"],
+        currency=row["currency"], source_type=row["source_type"],
+        store_name=row["store_name"], raw_text=row["raw_text"],
+        source_file_path=row["source_file_path"],
+        confirmed=bool(row["confirmed"]),
+    )
+
+
+def _row_to_reconciliation(row: sqlite3.Row) -> ReconciliationEvent:
+    return ReconciliationEvent(
+        event_id=row["event_id"],
+        timestamp=datetime.fromisoformat(row["timestamp"]) if row["timestamp"] else datetime.now(),
+        canonical_name=row["canonical_name"],
+        planned_action=row["planned_action"],
+        actual_action=row["actual_action"],
+        quantity=row["quantity"],
+        unit=row["unit"],
+        price_paid=row["price_paid"],
+        planned_price=row["planned_price"],
+        substituted_with=row["substituted_with"],
+        notes=row["notes"],
+        source=row["source"],
+    )
+
+
+def _row_to_preference(row: sqlite3.Row) -> PreferenceSignal:
+    return PreferenceSignal(
+        signal_id=row["signal_id"],
+        canonical_name=row["canonical_name"],
+        signal_type=row["signal_type"],
+        value=row["value"],
+        confidence=row["confidence"],
+        source=row["source"],
+        created_at=datetime.fromisoformat(row["created_at"]) if row["created_at"] else datetime.now(),
+        updated_at=datetime.fromisoformat(row["updated_at"]) if row["updated_at"] else datetime.now(),
+    )
+
+
+def _row_to_inventory_event(row: sqlite3.Row) -> InventoryEvent:
+    return InventoryEvent(
+        event_id=row["event_id"],
+        timestamp=datetime.fromisoformat(row["timestamp"]) if row["timestamp"] else datetime.now(),
+        lot_id=row["lot_id"] or "",
+        canonical_name=row["canonical_name"] or "",
+        action=row["action"],
+        quantity_before=row["quantity_before"] if row["quantity_before"] is not None else None,
+        quantity_after=row["quantity_after"] if row["quantity_after"] is not None else None,
+        quantity_delta=row["quantity_delta"] if row["quantity_delta"] is not None else None,
+        unit=row["unit"] or "",
+        location_from=row["location_from"],
+        location_to=row["location_to"],
+        source=row["source"] or "manual",
+        notes=row["notes"],
+    )
+
+
+from shopstack.schemas.models import ToolCall as _ToolCall  # noqa: E402 — circular import
+
+
+def _coerce_tool_call_payload(d: dict) -> dict:
+    if not isinstance(d, dict):
+        return {
+            "tool_name": "respond",
+            "args": {"message": str(d)},
+            "success": False,
+            "error": "Invalid tool call payload",
+        }
+
+    tool_name = d.get("tool_name") or d.get("tool")
+    if not tool_name:
+        return {
+            "tool_name": "respond",
+            "args": {"message": "Missing tool"},
+            "success": False,
+            "error": "Missing tool name",
+        }
+
+    args = d.get("args")
+    if not isinstance(args, dict):
+        args = {}
+
+    result = d.get("result")
+    if result is not None and not isinstance(result, dict):
+        result = {"value": result}
+
+    return {
+        "tool_name": str(tool_name),
+        "args": args,
+        "result": result,
+        "success": bool(d.get("success", False)),
+        "error": d.get("error"),
+        "requires_confirmation": bool(d.get("requires_confirmation", True)),
+        "confirmed": bool(d.get("confirmed", False)),
+    }
+
+
+def _dict_to_tc(d: dict) -> _ToolCall:
+    return _ToolCall(**_coerce_tool_call_payload(d))

shopstack/planner/engine.py

@@ -0,0 +1,632 @@
+from __future__ import annotations
+
+import json
+import logging
+import time
+from html import escape
+from typing import Any
+
+from shopstack.config import settings
+from shopstack.cost_tracker import CostRecord, CostTracker, estimate_cost_usd, estimate_model_tier
+from shopstack.persistence.database import Database
+from shopstack.planner.parser import parse_tool_calls_with_diagnostics
+from shopstack.providers.registry import ProviderRegistry
+from shopstack.tools.registry import ToolRegistry
+
+logger = logging.getLogger(__name__)
+
+TOOL_ACTIONS_HELP: dict[str, str] = {
+    "add_inventory_item": "Added {canonical_name} to inventory.",
+    "consume_inventory_item": "Consumed {quantity} of lot {lot_id}.",
+    "update_inventory_item": "Updated lot {lot_id}.",
+    "move_inventory_item": "Moved lot {lot_id} to {to_location_id}.",
+    "find_item": "",
+    "create_or_update_shopping_list": "Updated shopping list.",
+    "compare_visible_item_to_inventory": "",
+    "record_price_observation": "Recorded price for {canonical_name}.",
+    "get_use_soon_items": "",
+    "get_next_buy_suggestions": "",
+    "respond": "",
+}
+
+
+class PlannerEngine:
+    MAX_TOOL_CALLS_PER_RUN = 8
+
+    def __init__(
+        self,
+        db: Database,
+        tool_registry: ToolRegistry,
+        provider_registry: ProviderRegistry,
+    ):
+        self._db = db
+        self._tools = tool_registry
+        self._providers = provider_registry
+        self._cost_tracker = CostTracker(budget_limit=settings.cost_budget_limit)
+
+    @property
+    def available(self) -> bool:
+        provider = self._providers.planner
+        if provider is None:
+            return False
+        return getattr(provider, "available", False)
+
+    def process(self, question: str, compact_tools: bool | None = None) -> str:
+        from shopstack.planner.prompts import build_planner_prompt, build_system_prompt
+
+        provider = self._providers.planner
+        if self._cost_guarded():
+            return self._budget_blocked_html()
+        if provider is None or not getattr(provider, "available", False):
+            return (
+                "<div class='stat-card'>Planner not available. "
+                "Set SHOPSTACK_PLANNER_BACKEND=local to use a local model, "
+                "or SHOPSTACK_PLANNER_BACKEND=openai for OpenAI.</div>"
+            )
+
+        if compact_tools is None:
+            compact_tools = settings.planner_compact_tools
+        prompt = build_planner_prompt(question, self._db, tool_registry=self._tools, compact_tools=compact_tools)
+        system_prompt = build_system_prompt(self._db, tool_registry=self._tools, compact_tools=compact_tools)
+        provider_meta: dict[str, Any] = {}
+        parser_meta: dict[str, Any] = {}
+
+        try:
+            started = time.monotonic()
+            if hasattr(provider, "plan"):
+                result = provider.plan({
+                    "prompt": prompt,
+                    "system": system_prompt,
+                    "question": question,
+                })
+                planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                tool_calls, parser_meta = self._parse_tool_calls_from_result(result)
+                provider_meta = self._provider_call_meta(
+                    provider,
+                    result=result,
+                    call_latency_ms=planner_call_ms,
+                    question=question,
+                    prompt=prompt,
+                )
+            else:
+                complete_fn = getattr(provider, "complete", None)
+                plan_result = complete_fn(prompt) if callable(complete_fn) else {"text": ""}
+                if isinstance(plan_result, dict):
+                    result = plan_result
+                    planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                    raw_text = str(plan_result.get("text", ""))
+                    self._record_provider_cost(plan_result)
+                    provider_meta = self._provider_call_meta(
+                        provider,
+                        result=plan_result,
+                        call_latency_ms=planner_call_ms,
+                        question=question,
+                        prompt=prompt,
+                    )
+                    if self._cost_guarded():
+                        return self._budget_blocked_html()
+                    if not raw_text:
+                        provider_meta["outcome"] = "empty_llm_text"
+                        return "<div class='stat-card'>Planner returned an empty response.</div>"
+                    tool_calls, parser_meta = self._parse_tool_calls_from_result(raw_text)
+                else:
+                    planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                    tool_calls, parser_meta = self._parse_tool_calls_from_result(str(plan_result))
+                    provider_meta = self._provider_call_meta(
+                        provider,
+                        result=None,
+                        raw_output=plan_result,
+                        call_latency_ms=planner_call_ms,
+                        question=question,
+                        prompt=prompt,
+                    )
+
+        except Exception as e:
+            logger.warning("Planner call failed", exc_info=True)
+            return f"<div class='stat-card'><div style='color:var(--red);'>Planner error: {escape(str(e))}</div></div>"
+
+        provider_meta["parser"] = parser_meta
+        outcomes, execution_meta = self._execute_tool_calls(tool_calls)
+        provider_meta["execution"] = execution_meta
+        # kept intentionally for UI/debug surfacing through raw trace consumers
+        return self._format_outcomes(outcomes, question)
+
+    def process_structured(self, question: str, compact_tools: bool | None = None) -> dict[str, Any]:
+        """Process a question and return a structured dictionary instead of HTML prose."""
+        from shopstack.planner.prompts import build_planner_prompt, build_system_prompt
+
+        provider = self._providers.planner
+        if provider is None or not getattr(provider, "available", False):
+            return {"error": "Planner not available", "type": "error"}
+
+        if compact_tools is None:
+            compact_tools = settings.planner_compact_tools
+        prompt = build_planner_prompt(question, self._db, tool_registry=self._tools, compact_tools=compact_tools)
+        system_prompt = build_system_prompt(self._db, tool_registry=self._tools, compact_tools=compact_tools)
+        parser_meta: dict[str, Any] = {}
+        provider_meta: dict[str, Any] = {}
+
+        if self._cost_guarded():
+            return {"error": "Budget limit reached", "type": "error"}
+
+        try:
+            started = time.monotonic()
+            if hasattr(provider, "plan"):
+                result = provider.plan({
+                    "prompt": prompt,
+                    "system": system_prompt,
+                    "question": question,
+                })
+                planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                tool_calls, parser_meta = self._parse_tool_calls_from_result(result)
+                provider_meta = self._provider_call_meta(
+                    provider,
+                    result=result,
+                    call_latency_ms=planner_call_ms,
+                    question=question,
+                    prompt=prompt,
+                )
+            else:
+                complete_fn = getattr(provider, "complete", None)
+                plan_result = complete_fn(prompt) if callable(complete_fn) else {"text": ""}
+                if isinstance(plan_result, dict):
+                    planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                    raw_text = str(plan_result.get("text", ""))
+                    self._record_provider_cost(plan_result)
+                    provider_meta = self._provider_call_meta(
+                        provider,
+                        result=plan_result,
+                        call_latency_ms=planner_call_ms,
+                        question=question,
+                        prompt=prompt,
+                    )
+                    if self._cost_guarded():
+                        return {"error": "Budget limit reached", "type": "error"}
+                    if not raw_text:
+                        return {"error": "Planner returned an empty response.", "type": "error"}
+                    tool_calls, parser_meta = self._parse_tool_calls_from_result(raw_text)
+                else:
+                    planner_call_ms = round((time.monotonic() - started) * 1000, 2)
+                    tool_calls, parser_meta = self._parse_tool_calls_from_result(str(plan_result))
+                    provider_meta = self._provider_call_meta(
+                        provider,
+                        result=None,
+                        raw_output=plan_result,
+                        call_latency_ms=planner_call_ms,
+                        question=question,
+                        prompt=prompt,
+                    )
+
+        except Exception as e:
+            logger.warning("Planner call failed", exc_info=True)
+            return {"error": f"Planner error: {str(e)}", "type": "error"}
+
+        if not tool_calls:
+            return {"error": "Planner returned an empty response.", "type": "error"}
+
+        outcomes, execution_meta = self._execute_tool_calls(tool_calls)
+        provider_meta["parser"] = parser_meta
+        provider_meta["execution"] = execution_meta
+
+        return {
+            "tool_calls": tool_calls,
+            "outcomes": outcomes,
+            "type": "tool_calls",
+            "debug": {
+                "provider": provider_meta,
+                "parser": parser_meta,
+                "execution": execution_meta,
+            },
+        }
+
+    @property
+    def session_cost(self) -> dict[str, Any]:
+        """Return the current session cost summary."""
+        return self._cost_tracker.summary()
+
+    def _record_provider_cost(self, result: dict[str, Any]) -> None:
+        """Extract usage/cost from a provider result dict and record it."""
+        model_key = str(result.get("model") or result.get("model_key") or "unknown")
+        usage = result.get("usage") or {}
+        input_tokens = int(usage.get("prompt_tokens") or usage.get("input_tokens") or 0)
+        output_tokens = int(usage.get("completion_tokens") or usage.get("output_tokens") or 0)
+        if not output_tokens and usage.get("total_tokens"):
+            output_tokens = int(usage["total_tokens"])
+        latency_ms = result.get("latency_ms")
+        if isinstance(latency_ms, (int, float)):
+            latency_ms = float(latency_ms)
+        elif isinstance(result.get("cost"), dict):
+            latency_ms = result["cost"].get("latency_ms")
+        if input_tokens or output_tokens:
+            self._record_cost(model_key, input_tokens, output_tokens, latency_ms)
+
+    def _provider_call_meta(
+        self,
+        provider: Any,
+        result: Any = None,
+        call_latency_ms: float | None = None,
+        question: str = "",
+        prompt: str = "",
+        raw_output: Any = None,
+    ) -> dict[str, Any]:
+        if result is None:
+            result = {}
+        usage: dict[str, Any] = {}
+        if isinstance(result, dict):
+            usage = result.get("usage") or {}
+            if not isinstance(usage, dict):
+                usage = {}
+
+        cost_payload = result.get("cost") if isinstance(result, dict) else {}
+        if not isinstance(cost_payload, dict):
+            cost_payload = {}
+
+        input_tokens = 0
+        output_tokens = 0
+        if usage:
+            input_tokens = int(usage.get("prompt_tokens") or usage.get("input_tokens") or 0)
+            output_tokens = int(usage.get("completion_tokens") or usage.get("output_tokens") or 0)
+            if not output_tokens and usage.get("total_tokens"):
+                output_tokens = int(usage["total_tokens"])
+
+        model_key = None
+        if isinstance(result, dict):
+            model_key = result.get("model") or result.get("model_key")
+        if not model_key:
+            model_key = getattr(provider, "_model", None)
+        if not model_key:
+            model_key = getattr(provider, "_model_name", None)
+        if not model_key:
+            model_key = getattr(provider, "model_id", None) or getattr(provider, "name", "unknown")
+
+        latency_ms = call_latency_ms
+        if isinstance(cost_payload, dict) and isinstance(cost_payload.get("latency_ms"), (int, float)):
+            latency_ms = float(cost_payload["latency_ms"])
+
+        if latency_ms is None:
+            latency_ms = (
+                getattr(provider, "last_latency_ms", None)
+                or getattr(provider, "_last_latency_ms", None)
+                or getattr(provider, "latency_ms", None)
+                or getattr(provider, "_last_response_latency_ms", None)
+            )
+
+        if latency_ms is not None:
+            latency_ms = round(float(latency_ms), 2)
+
+        return {
+            "provider": getattr(provider, "name", "unknown"),
+            "model": str(model_key),
+            "backend": (
+                getattr(provider, "_backend", None)
+                or getattr(provider, "backend", None)
+                or ""
+            ),
+            "latency_ms": latency_ms,
+            "prompt_length": len(prompt or ""),
+            "question_length": len(question or ""),
+            "input_tokens": input_tokens,
+            "output_tokens": output_tokens,
+            "usage": usage,
+            "cost_usd": cost_payload.get("usd"),
+            "raw_output_type": type(raw_output if raw_output is not None else result).__name__,
+        }
+
+    def _record_cost(self, model_key: str, input_tokens: int, output_tokens: int, latency_ms: float | None = None) -> None:
+        """Record a cost entry from a provider call."""
+        cost = estimate_cost_usd(model_key, input_tokens, output_tokens)
+        tier = estimate_model_tier(input_tokens, item_count=0)
+        record = CostRecord(
+            model=model_key,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            cost_usd=cost,
+            tier=tier,
+            latency_ms=latency_ms,
+        )
+        self._cost_tracker = self._cost_tracker.add(record)
+
+    # Patterns that indicate potential injection or path traversal in tool args
+    _SUSPICIOUS_ARG_PATTERNS = (
+        "../", "..\\", "/etc/", "C:\\", "|", ";", "&&", "||", "`", "$(",
+        "__import__", "eval(", "exec(", "open(", "os.", "subprocess",
+    )
+
+    def _contains_suspicious_text(self, value: Any) -> str | None:
+        if isinstance(value, str):
+            lower_val = value.lower()
+            for pattern in self._SUSPICIOUS_ARG_PATTERNS:
+                if pattern.lower() in lower_val:
+                    return pattern
+            return None
+        if isinstance(value, list | tuple | set):
+            for item in value:
+                match = self._contains_suspicious_text(item)
+                if match is not None:
+                    return match
+            return None
+        if isinstance(value, dict):
+            for item in list(value.keys()) + list(value.values()):
+                match = self._contains_suspicious_text(item)
+                if match is not None:
+                    return match
+            return None
+        return None
+
+    def _validate_args(self, tool: str, args: dict[str, Any]) -> str | None:
+        """Validate tool arguments for injection / path traversal / abuse.
+        Returns an error message string if validation fails, or None if clean.
+        """
+        for key, value in args.items():
+            match = self._contains_suspicious_text(value)
+            if match is not None:
+                return (
+                    f"Rejected tool '{tool}' arg '{key}': "
+                    f"value contains suspicious pattern '{match}'"
+                )
+        return None
+
+    def _parse_tool_calls_from_result(
+        self, result: str | list[Any] | dict[str, Any]
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        if isinstance(result, dict):
+            raw_tool_calls = result.get("tool_calls")
+            if isinstance(raw_tool_calls, list):
+                raw_tool_calls = [c for c in raw_tool_calls if isinstance(c, dict)]
+                tool_calls, diagnostics = parse_tool_calls_with_diagnostics(
+                    json.dumps(raw_tool_calls, default=str)
+                )
+                diagnostics["source"] = "planner_plan_tool_calls_key"
+                return tool_calls, diagnostics
+            tool_name = result.get("tool")
+            if tool_name and isinstance(tool_name, str):
+                raw = json.dumps([{"tool": tool_name, "args": result.get("args", {})}])
+                tool_calls, diagnostics = parse_tool_calls_with_diagnostics(raw)
+                diagnostics["source"] = "planner_plan_tool_object"
+                return tool_calls, diagnostics
+
+            raw = str(result.get("text", ""))
+            tool_calls, diagnostics = parse_tool_calls_with_diagnostics(raw)
+            diagnostics["source"] = "planner_plan_text"
+            return tool_calls, diagnostics
+
+        if isinstance(result, list):
+            try:
+                raw = json.dumps(result, default=str)
+            except Exception:
+                raw = str(result)
+            tool_calls, diagnostics = parse_tool_calls_with_diagnostics(raw)
+            diagnostics["source"] = "planner_plan_list"
+            return tool_calls, diagnostics
+
+        tool_calls, diagnostics = parse_tool_calls_with_diagnostics(str(result or ""))
+        diagnostics["source"] = "planner_plan_other"
+        return tool_calls, diagnostics
+
+    def _execute_tool_calls(
+        self, tool_calls: list[dict[str, Any]]
+    ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+        if self._cost_guarded():
+            return (
+                [{
+                    "tool": "respond",
+                    "success": False,
+                    "error": self._cost_blocked_reason(),
+                }],
+                {
+                    "tool_calls_requested": len(tool_calls),
+                    "tool_calls_executed": 0,
+                    "tool_calls_failed": 0,
+                    "tool_calls_truncated": 0,
+                    "tool_runs": [],
+                    "cost_blocked": True,
+                },
+            )
+
+        results: list[dict[str, Any]] = []
+        limited = tool_calls[: self.MAX_TOOL_CALLS_PER_RUN]
+        execution: dict[str, Any] = {
+            "tool_calls_requested": len(tool_calls),
+            "tool_calls_executed": 0,
+            "tool_calls_failed": 0,
+            "tool_calls_truncated": max(0, len(tool_calls) - self.MAX_TOOL_CALLS_PER_RUN),
+            "tool_runs": [],
+            "cost_blocked": False,
+        }
+
+        if len(tool_calls) > self.MAX_TOOL_CALLS_PER_RUN:
+            results.append({
+                "tool": "respond",
+                "success": True,
+                "message": (
+                    f"Planner requested {len(tool_calls)} actions; "
+                    f"executing first {self.MAX_TOOL_CALLS_PER_RUN} for safety."
+                ),
+            })
+
+        for tc in limited:
+            run = {"tool": tc.get("tool", "respond"), "status": "started"}
+            started = time.monotonic()
+
+            tool = tc.get("tool", "respond")
+            args = tc.get("args", {})
+            if tool == "respond":
+                elapsed_ms = round((time.monotonic() - started) * 1000, 2)
+                run["status"] = "respond"
+                run["latency_ms"] = elapsed_ms
+                execution["tool_runs"].append(run)
+                execution["tool_calls_executed"] += 1
+                msg = args.get("message", "")
+                results.append({
+                    "tool": "respond",
+                    "success": True,
+                    "message": msg,
+                })
+                continue
+
+            validation_error = self._validate_args(tool, args)
+            if validation_error is not None:
+                elapsed_ms = round((time.monotonic() - started) * 1000, 2)
+                run["status"] = "validation_failed"
+                run["error"] = validation_error
+                run["latency_ms"] = elapsed_ms
+                execution["tool_runs"].append(run)
+                execution["tool_calls_failed"] += 1
+                execution["tool_calls_executed"] += 1
+                results.append({
+                    "tool": tool,
+                    "success": False,
+                    "error": validation_error,
+                    "latency_ms": elapsed_ms,
+                })
+                continue
+
+            tool_spec = self._tools._find_tool_spec(tool)
+            if tool_spec is not None and tool_spec.mutability == "write":
+                requires_confirmation = bool(tool_spec.needs_confirmation) or (
+                    not settings.planner_allow_writes and tool != "create_or_update_shopping_list"
+                )
+                if requires_confirmation:
+                    elapsed_ms = round((time.monotonic() - started) * 1000, 2)
+                    if tool == "create_or_update_shopping_list":
+                        item_count = 0
+                        if isinstance(args.get("items"), list):
+                            item_count = len(args.get("items", []))
+                        summary = f"plan {item_count} shopping list item(s)"
+                    elif "canonical_name" in args:
+                        summary = f"modify '{args['canonical_name']}'"
+                    else:
+                        summary = f"apply '{tool}'"
+
+                    reason = (
+                        f"Planner write blocked by safety policy: {summary}. "
+                        "Review and confirm this action in the relevant screen."
+                    )
+                    run["status"] = "blocked_by_policy"
+                    run["error"] = reason
+                    run["latency_ms"] = elapsed_ms
+                    execution["tool_runs"].append(run)
+                    execution["tool_calls_executed"] += 1
+                    execution["tool_calls_failed"] += 1
+                    results.append({
+                        "tool": tool,
+                        "success": False,
+                        "error": reason,
+                        "latency_ms": elapsed_ms,
+                    })
+                    continue
+
+            try:
+                outcome = self._tools.execute(tool, **args)
+                elapsed_ms = round((time.monotonic() - started) * 1000, 2)
+                tool_success = outcome.get("success", False)
+                result = {
+                    "tool": tool,
+                    "success": bool(tool_success),
+                    "result": outcome.get("result", outcome),
+                    "error": outcome.get("error"),
+                    "latency_ms": elapsed_ms,
+                }
+                execution["tool_calls_executed"] += 1
+                if not tool_success:
+                    run["status"] = "tool_failed"
+                    run["error"] = outcome.get("error")
+                    execution["tool_calls_failed"] += 1
+                else:
+                    run["status"] = "succeeded"
+                run["latency_ms"] = elapsed_ms
+                run["success"] = bool(tool_success)
+                execution["tool_runs"].append(run)
+                results.append(result)
+            except Exception as e:
+                elapsed_ms = round((time.monotonic() - started) * 1000, 2)
+                run["status"] = "exception"
+                run["error"] = str(e)
+                run["latency_ms"] = elapsed_ms
+                execution["tool_runs"].append(run)
+                execution["tool_calls_executed"] += 1
+                execution["tool_calls_failed"] += 1
+                results.append({
+                    "tool": tool,
+                    "success": False,
+                    "error": str(e),
+                    "latency_ms": elapsed_ms,
+                })
+
+            if self._cost_guarded():
+                blocked_msg = self._cost_blocked_reason()
+                execution["cost_blocked"] = True
+                results.append({
+                    "tool": "respond",
+                    "success": False,
+                    "error": blocked_msg,
+                })
+                execution["tool_runs"].append({
+                    "tool": "respond",
+                    "status": "cost_blocked",
+                    "error": blocked_msg,
+                    "latency_ms": 0.0,
+                })
+                break
+
+        return results, execution
+
+    def _cost_guarded(self) -> bool:
+        return self._cost_tracker.over_budget
+
+    def _cost_blocked_reason(self) -> str:
+        summary = self.session_cost
+        return (
+            "Cost budget exceeded. "
+            f"Budget: ${summary['budget_limit']:.2f}, "
+            f"Spent: ${summary['total_cost']:.2f}."
+        )
+
+    def _budget_blocked_html(self) -> str:
+        return (
+            "<div class='stat-card'>"
+            f"<div style='font-weight:600;color:var(--red);'>Cost budget blocked</div>"
+            f"<div>{escape(self._cost_blocked_reason())}</div>"
+            "</div>"
+        )
+
+    def _format_outcomes(
+        self, outcomes: list[dict[str, Any]], original_question: str
+    ) -> str:
+        html_parts: list[str] = []
+        for outcome in outcomes:
+            tool = outcome["tool"]
+            success = outcome["success"]
+            if tool == "respond":
+                msg = outcome.get("message", "")
+                if msg:
+                    html_parts.append(
+                        f"<div style='padding:8px;margin:4px 0;border-left:3px solid var(--accent);'>{escape(str(msg))}</div>"
+                    )
+                continue
+            action = TOOL_ACTIONS_HELP.get(tool, f"Ran {tool}.")
+            _result_data = outcome.get("result") or outcome.get("error", "")
+            if success:
+                if action:
+                    html_parts.append(
+                        f"<div style='padding:6px;margin:2px 0;color:var(--text-main);'>"
+                        f"<span style='color:var(--green);'>&#10003;</span> {action}</div>"
+                    )
+            else:
+                err = outcome.get("error", "Unknown error")
+                html_parts.append(
+                    f"<div style='padding:6px;margin:2px 0;color:var(--red);'>"
+                    f"&#10007; {escape(str(tool))}: {escape(str(err))}</div>"
+                )
+
+        if not html_parts:
+            return "<div class='stat-card'>No actions taken.</div>"
+
+        title = f"{settings.app_name} AI"
+        body = "".join(html_parts)
+        return (
+            f"<div class='stat-card'>"
+            f"<div style='font-weight:600;margin-bottom:8px;'>{title}</div>"
+            f"{body}"
+            f"</div>"
+        )