price-predator

Track product prices across time and stores, alert on price drops, and predict the best time to buy.

Track product prices across time and stores, get alerts on price drops, and predict the best time to buy.

Quick Start

bash

# Track a product with its current price
python3 scripts/price_predator.py track --name "Sony WH-1000XM5" --price 350.00 --category electronics

# Record a new price observation
python3 scripts/price_predator.py update <product-id> --price 299.99

# View ASCII sparkline price history
python3 scripts/price_predator.py history <product-id>

# Check for price drop alerts (all products)
python3 scripts/price_predator.py alert

# Check best time to buy by category
python3 scripts/price_predator.py best-time --category electronics

# Full report
python3 scripts/price_predator.py report

Commands

Command	Description
track	Add a product to track (name + price + category + optional URL/target)
update	Record a new price observation for a tracked product
history	Show price history with ASCII sparkline chart
alert	Check for price drops exceeding threshold (>10% below median by default)
best-time	Predict best time to buy based on seasonal patterns by category
report	Full summary report of all tracked products
list	List all tracked products
remove	Remove a tracked product
info	Show detailed info about a product

How It Works

• Database: JSON file (~/.price_predator_db.json by default). Override with --db.
• Price tracking: Each update records price + timestamp + source. Build a history over time.
• Alerts: When the latest price drops more than the threshold (default 10%) below the median of all recorded prices, an alert fires.
• Seasonal prediction: Uses a built-in calendar of best months to buy each category (see references/seasonal-buying-calendar.md).
• Depreciation: Category-aware annual depreciation rates provide a rough price prediction model.

Category-Aware Patterns

Price Predator knows seasonal discount windows for 15+ categories:

• Electronics / TVs / Laptops → Black Friday (Nov), Cyber Monday
• Mattresses → May (Memorial Day), February (Presidents' Day)
• Appliances → September (Labor Day), May (Memorial Day)
• Smartphones → September (new model launches), November (Black Friday)
• Furniture → January & July (inventory clearance)
• See references/seasonal-buying-calendar.md for the full calendar.

Options

• --db <path> — Use a custom database file (global flag, before subcommand)
• --target <price> — Set a target buy price when tracking
• --threshold <frac> — Set alert threshold as a fraction (0.15 = 15%)
• --category <cat> — Set product category for seasonal predictions

Files

• scripts/price_predator.py — Main script (Python stdlib only, no dependencies)
• references/seasonal-buying-calendar.md — Best months to buy each category
• references/price-tracking-strategies.md — Strategies for effective price tracking