Costco Route Optimizer

Turn a stream-of-consciousness grocery list into a route-optimized Costco shopping plan.

How It Works

1. Input: Dump your grocery list however you think it — "milk eggs chicken that cheese Aundrea likes paper towels dog food"
2. LLM Classification: qwen2.5-coder:7b maps each item to a Costco warehouse zone
3. Route Optimization: Items are sorted by physical zone order (entrance → exit)
4. Output: A tactical shopping list — zero backtracking, in-and-out in 20 minutes

Zone Map

Most Costco warehouses (2026 layout) follow this counter-clockwise flow:

Calibration Loop

Costco moves products constantly. When the bot gets a zone wrong:

1. Tap the 🔄 button next to a zone → pick the correct zone
2. The correction is saved to ChromaDB (embedded with nomic-embed-text)
3. Next trip: learned locations override the LLM classification

Setup

# Install dependencies
pip install -r requirements.txt

# Set environment variables (or use .env file)
export LLM_URL="http://localhost:11434/api/chat"
export EMBED_URL="http://localhost:11434/api/embeddings"
export LLM_MODEL="qwen2.5-coder:7b"
export EMBED_MODEL="nomic-embed-text"

# For Telegram bot
export COSTCO_BOT_TOKEN="your-token-from-botfather"
export COSTCO_ALLOWED_USERS="your-telegram-id"

Usage

CLI

python -m costco_route "milk eggs chicken paper towels dog food avocados"
python -m costco_route --learn "almond milk" 07  # Manual calibration
python -m costco_route --stats  # Show learned item count

# Recipe extraction
python -m costco_route --recipe "https://example.com/recipe-url"
python -m costco_route --recipe-list  # Browse saved recipes
python -m costco_route --recipe-show simple-chicken-tacos  # View a recipe

Telegram Bot

/costco milk eggs chicken paper towels dog food avocados
/recipe https://example.com/recipe-url  # Extract + save recipe
/recipes  # Browse your recipe Rolodex

Or just paste a recipe URL directly — no command needed.

Returns:

🛒 Costco Route — Green Bay Bellevue

📦 Zone 01 — Electronics / Entrance
☐ batteries

📦 Zone 07 — Fresh / Bakery / Meat
☐ avocados
☐ chicken

📦 Zone 06 — Dairy / Cold Room
☐ milk
☐ eggs

📦 Zone 08 — Household / Cleaning
☐ paper towels

📦 Zone 04 — Pantry / Snacks
☐ dog food

✅ 6 items across 5 zones — estimated 20 min

Recipe Extraction

Paste any recipe URL and the bot will:
1. Fetch the page and strip ads/stories/junk (BeautifulSoup)
2. Route to qwen2.5-coder:7b for structured extraction (ingredients + instructions)
3. Auto-classify ingredients into Costco zones
4. Save to your personal Recipe Rolodex (~/.costco_route/recipes/)

The extracted recipes are preserved with metadata (servings, prep/cook time, tags) and can be browsed later.

Architecture

User Input (stream of consciousness)
         ↓
   LLM Item Extraction + Zone Classification
         ↓
   Sanity Checks (catch LLM hallucinations)
         ↓
   ChromaDB Override Check (learned locations)
         ↓
   Zone-Based Route Sort (entrance → exit)
         ↓
   Formatted Output (Telegram / CLI)

Roadmap

v0.x — Route Optimizer (Current)

• ✅ Stream-of-consciousness input → LLM extraction → zone classification → route
• ✅ 10-zone Costco warehouse map with sanity checks
• ✅ ChromaDB calibration loop (learn corrections, override LLM)
• ✅ Telegram bot with inline calibration buttons (⬅️ Back, ✅ Done, auto-close)
• ✅ CLI with --learn, --stats, --json, --markdown
• ✅ Recipe extraction — paste a recipe URL → auto-extract ingredients → classify → save Rolodex
• 🔲 Multi-store support (Aldi, Target, Festival Foods)
• 🔲 Sub-zone precision (dairy milk vs dairy cheese locations)

v1.x — Grocery List Butler

• 🔲 Inventory management — track what you have, what you're low on, auto-suggest
• 🔲 Price comparison — Kirkland vs store brand, cross-store pricing
• 🔲 Multi-store route optimization — which store first, driving order, split lists
• 🔲 Recurring items — "we always buy milk" → auto-include weekly
• 🔲 Shared family lists — Aundrea adds items too, merged into one route

v2.x — Automated Fulfillment

• 🔲 Instacart / online ordering integration — generate cart from route list
• 🔲 Store pickup scheduling — optimize pickup times around calendar
• 🔲 Budget tracking — per-trip spend, monthly trends, Costco vs alternatives
• 🔲 Pantry sync — photo receipts → auto-deduction from inventory
• 🔲 Smart suggestions — "you're low on paper towels, add to next run?"

License

MIT