Costco Tracker

Costco Tracker is a smart, self-hosted web app that parses your receipts, enriches item data using OpenAI, and helps predict your shopping needs. It's designed for mobile-first use with strong offline support and a personal dashboard experience.

---

Features

🧾 Receipt Management (MVP)

• Multi-file PDF upload (web)
• SHA256 file-hash plus content text-hash dedupe (prevents renamed duplicates like -1.pdf)
• Text extraction via PyMuPDF
• Parsing of receipt date and item lines with improvements:
  • Quantity/Unit/Size heuristics (e.g., 4 L milk)
  • TPD/ADS/Deposit/Eco fee detection and handling
  • Gift certificate/payment lines ignored
  • Items-sold count shown and compared to parsed items (auxiliary lines excluded)
• Store Receipt and Item rows in SQLite via SQLAlchemy
• Delete a receipt (and its file) from the receipt view

🔐 Authentication

• Login/logout (Flask-Login)

👀 Views

• Receipts list and detail (shows raw text and parsed items)
• Products list (distinct product_code + name_raw)
• Dashboard with spend by month and category; month detail page

✨ Enrichment (Upcoming)

🔎 How enrichment works (scrape + LLM)

When you click "Enrich" on a product (or use "Enrich Missing" on the Products page):

1. If an external Costco URL is already stored for the product, the app fetches that page and extracts:

   • Title (preferred display name)
   • Primary image (cached locally to data/products/)
   • Product details/features list

2. Otherwise, if the product has a product_code, the app builds the Costco URL in the form https://www.costco.ca/ProductDisplay?partNumber={code} and then scrapes the same fields as above.

3. If neither is available, the app searches costco.ca/businesscentre for the best page based on code/name and scrapes that.

4. Finally, the app calls the selected LLM (OpenAI or Ollama) to suggest a clean display name and a category[:subcategory]. These are saved back to the Product.

Notes:

• Configure the active LLM provider in Settings. You can store an OpenAI key, pick a model (or Ollama model), and verify connectivity.
• All LLM calls are logged (see LLM Usage page) with token counts and estimated cost.
• If a scrape fails or the page layout is unusual, you can click "Rebuild" to retry building/fetching the external URL and then "Enrich" again.

Current status

• Auth, DB, and migrations are wired; models include User, Receipt, Item, Product, OpenAIRequestLog, AppSetting
• Receipt parsing includes quantity/size heuristics and tender/discount handling
• Items-sold vs parsed shows in the receipt view (auxiliary lines excluded)
• Settings supports OpenAI and Ollama with connectivity checks and model discovery
• LLM Usage page summarizes calls, tokens, and cost; recent calls listed
• Products page supports scraping (title/image/features) and LLM enrichment; batch enrich available

Next steps

• Product detail page with price history and product info; link from receipt items

• Associate TPD/… discount lines to the preceding item in UI and exports

• Toggle to enable/disable auto-enrichment on upload; background retry queue for scraping/enrichment

• Optional WarehouseRunner integration for missing Costco product pages

• CSV export for receipts/items; simple import

• Use OpenAI API to enrich product names with description, quantity, unit, and size

• Log token usage and cost per call

📊 Dashboard (Upcoming)

• Import log + parsing stats
• OpenAI usage summaries
• Cost aggregates

📱 Mobile & PWA (Planned)

• Responsive Bootstrap UI
• PWA-ready architecture

---

Upcoming Features

🔮 Smart Shopping List

• Predict items likely needed soon based on frequency
• Tap to add to next trip
• Manage shopping checklist
• Save each shopping trip to history
• Group by category and aisle
• Works offline (via localStorage)

🧠 Onboarding & Settings

• First-run wizard to create the initial user
• Settings UI to configure OpenAI API key or local LLM (Ollama)
• Connection tests and helpful validation

🧠 Costco Import (Manual First)

• Paste HTML from Costco.ca/.com past purchases
• Parse with BeautifulSoup and import to database

---

Tech Stack

• Python 3.12
• Flask
• SQLite3
• PyMuPDF
• Bootstrap 5
• Chart.js, Toastr.js, DataTables
• OpenAI API

---

Installation

1. Clone: git clone https://github.com/YOUR_USERNAME/costco-tracker
2. Create venv: python3 -m venv venv
3. Activate and install: source venv/bin/activate && pip install -r requirements.txt
4. Create .env in project root:

SECRET_KEY=change-me
# Optional for enrichment phase
OPENAI_API_KEY=sk-...

5. Initialize database (SQLite):

export FLASK_APP=run.py
flask db init   # first time only
flask db migrate -m "init"
flask db upgrade

6. Create a user:

flask --app run.py create-user you@example.com 'yourpassword'

7. Run the app:

python run.py

8. Use it:

• Login: /auth/login
• Upload receipts: /receipts/upload (select multiple PDFs)
• View receipts: /receipts/
• View products: /products/

Roadmap

See ROADMAP.md for detailed phases and acceptance criteria.