Watchlist management: add, remove, and list tracked products with alert thresholds

[kovtcharov]

Summary

Implement watchlist tools that let users add products to track, set per-product price alert thresholds, and manage their tracked product list. Persistence via SQLite.

Motivation

The watchlist is the bridge between one-off product searches and continuous price monitoring. Users need to say "track this MacBook and alert me when it drops below $1,200" — and have that persist across sessions.

Design

Database Schema Addition

-- Watchlist entries with alert configuration
CREATE TABLE watchlist (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    product_id INTEGER NOT NULL,
    target_price REAL,               -- alert when price <= this
    alert_enabled BOOLEAN DEFAULT 1,
    alert_channels TEXT DEFAULT 'desktop',  -- 'desktop', 'email', 'webhook' (comma-sep)
    notes TEXT,                       -- user notes about why they're tracking
    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    last_alerted_at TIMESTAMP,       -- prevent duplicate alerts
    FOREIGN KEY (product_id) REFERENCES products(id),
    UNIQUE(product_id)
);

Tool Mixin

# src/gaia/agents/deals/tools/watchlist_tools.py
class WatchlistToolsMixin:
    def register_watchlist_tools(self) -> None:
        from gaia.agents.base.tools import tool

        @tool
        def add_to_watchlist(product_name: str, target_price: float = 0, retailer: str = "all") -> Dict:
            """Add a product to your price tracking watchlist.

            Args:
                product_name: Name or SKU of the product to track
                target_price: Alert when price drops to this amount (0 = track only, no alert)
                retailer: Which retailer to track ("all" checks all known sources)
            """

        @tool
        def remove_from_watchlist(product_name: str) -> Dict:
            """Remove a product from your watchlist.

            Args:
                product_name: Name or SKU of the product to stop tracking
            """

        @tool
        def list_watchlist() -> Dict:
            """Show all products currently being tracked with their target prices and current prices."""

        @tool
        def update_alert(product_name: str, target_price: float, enabled: bool = True) -> Dict:
            """Update the alert threshold for a tracked product.

            Args:
                product_name: Name of the product on your watchlist
                target_price: New target price for alerts
                enabled: Whether to enable or disable alerts for this product
            """

LLM Integration

The system prompt should guide the LLM to suggest adding products to the watchlist after searches:

• "I found the MacBook Pro for $1,399. Would you like me to track it and alert you if it drops?"
• Auto-suggest target price based on historical low from price history

Acceptance Criteria

• add_to_watchlist creates product (if not exists) + watchlist entry
• remove_from_watchlist removes by fuzzy name match
• list_watchlist shows all tracked items with current price, target, and status
• update_alert modifies threshold and enabled state
• Duplicate prevention: adding same product twice updates rather than duplicates
• last_alerted_at prevents spam (configurable cooldown, default 24h)
• Unit tests for all CRUD operations
• LLM prompt encourages watchlist suggestions after product searches

Phase

Phase 2 — Tracking & Alerts

Dependencies

• DealAgent base class (Phase 1)
• Price history schema (Phase 1)
• Product search tools (Phase 1)