README.md

metadata

title: ShopStack
emoji: 🛒
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.17.3
app_file: app.py
pinned: false
tags:
  - shopstack
  - gradio
  - inventory
  - shopping
  - offline-first
  - household

ShopStack

Doc links: Several links in this README point to Docs/ paths that are intentionally local-only (see Docs/README.md). They work in a local workspace but 404 from a clean clone. For canonical architecture, see shopstack/module_registry.py and the code under shopstack/. Git-tracked docs (MODEL_CATALOG.md, this README) are reachable from any clone.

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

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.

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

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:

• 26 Database Tables, 2 Views, 2 Triggers, 9 Indexes: app_config, condition_events, correction_events, find_feedback, household_locations, household_members, household_objects, households, inventory_events, inventory_lots, market_record_components, market_records, market_snapshots, movement_events, negative_memory, object_notes, object_sightings, person_associations, preference_signals, price_observations, purchase_events, reconciliation_events, shopping_list_items, shopping_lists, stores, traces (Tables), price_history, agent_traces (Views).
• 12 Tools: Including semantic_find_item.

Note: For the canonical current-state metrics, run python3 scripts/repo_truth.py. The README is updated when new tables/tabs/tools are added; do not hand-maintain these numbers.

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, 26 tables, 2 views, 2 triggers, 9 indexes, 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, 26 tables, 2 views, 2 triggers, 9 indexes)
  → 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.

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

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)

docker compose up --build
# Open http://localhost:7860

Data persists in a Docker volume (shopstack_data).

Docker (standalone)

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

# 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