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

| Zone | Name | Typical Items |
|------|------|---------------|
| 01 | Electronics / Entrance | TVs, laptops, batteries, jewelry |
| 02 | Seasonal / Center | Outdoor furniture, holiday decor, toys, clothing |
| 03 | Health & Beauty | Vitamins, shampoo, toothpaste, OTC meds |
| 04 | Pantry / Snacks | Crackers, chips, nuts, coffee, canned goods, pet food |
| 05 | Beverages | Soda, water, juice, beer, wine |
| 06 | Dairy / Cold Room | Milk, eggs, butter, cheese, yogurt |
| 07 | Fresh / Bakery / Meat | Rotisserie chicken, beef, poultry, bakery, produce |
| 08 | Household / Cleaning | Paper towels, toilet paper, detergent |
| 09 | Freezer | Frozen meals, frozen fruit, ice cream |
| 10 | Checkout / Food Court | Final picks, food court |

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

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