Shopping Expert

## Quick Start

Find products online:

```bash
uv run {baseDir}/scripts/shop.py "coffee maker" \
  --budget medium \
  --max-results 5
```

Search with budget constraint:

```bash
uv run {baseDir}/scripts/shop.py "running shoes" \
  --budget "$100" \
  --preferences "Nike, cushioned, waterproof"
```

Find local stores:

```bash
uv run {baseDir}/scripts/shop.py "Bio Gemüse" \
  --mode local \
  --location "Hamburg, Germany"
```

Hybrid search (online + local):

```bash
uv run {baseDir}/scripts/shop.py "Spiegelreflexkamera" \
  --mode hybrid \
  --location "München, Germany" \
  --budget high \
  --preferences "Canon, 4K Video"
```

Search US stores:

```bash
uv run {baseDir}/scripts/shop.py "running shoes" \
  --country us \
  --budget "$100"
```

## Search Modes

- **online**: E-commerce sites (Amazon, Walmart, etc.) via Google Shopping
- **local**: Nearby stores via Google Places API
- **hybrid**: Both online and local results merged and ranked
- **auto**: Intelligent mode selection based on query (default)

## Parameters

- `query`: Product search query (required)
- `--mode`: Search mode (online|local|hybrid|auto, default: auto)
- `--budget`: "low/medium/high" or "€X"/"$X" amount (default: medium)
- `--location`: Location for local/hybrid searches
- `--preferences`: Comma-separated (e.g., "brand:Sony, wireless, black")
- `--max-results`: Maximum products to return (default: 5, max: 20)
- `--sort-by`: Sort order (relevance|price-low|price-high|rating)
- `--output`: text|json (default: text)
- `--country`: Country code for search (default: de). Use "us" for US, "uk" for UK, etc.

## Budget Levels

- **low**: Under €50
- **medium**: €50-€150
- **high**: Over €150
- **exact**: "€75", "€250" (or "$X" for US searches)

## Output Format

**Default (text)**: Markdown table with product details, ratings, availability, and buy links

**JSON**: Structured data with all product metadata, scores, and links

## Scoring Algorithm

Products are ranked using weighted scoring:
- **Price match (30%)**: Within budget range gets full points
- **Rating (25%)**: Higher ratings score better
- **Availability (20%)**: In stock > limited > out of stock
- **Review count (15%)**: More reviews = more trustworthy
- **Shipping/Distance (10%)**: Free shipping or nearby stores score higher
- **Preference match (bonus)**: Keywords in product description

## API Keys Required

- **SERPAPI_API_KEY**: Required for online shopping (all modes except local-only)
- **GOOGLE_PLACES_API_KEY**: Only required for local and hybrid modes

## Limitations

- **API limits**: SerpAPI and Google Places have usage quotas
- **Real-time data**: Prices and availability may change
- **Stock accuracy**: Online availability reflects last API update
- **Local inventory**: Store stock not guaranteed via Places API

## Error Handling

- Invalid query → Returns error with suggestions
- No results found → Relaxes filters and retries
- API failures → Retry with exponential backoff (3 attempts)
- Missing API keys → Clear error message with setup instructions