LLM-powered deal quality analysis and purchase recommendations

[kovtcharov]

Summary

Leverage the LLM to provide intelligent deal analysis beyond raw price data — answering "is this a good deal?" by combining price history, trend analysis, seasonal patterns, and product knowledge.

Motivation

Raw price data tells you what the price is. LLM analysis tells you whether to buy. CamelCamelCamel shows numbers; a GAIA DealAgent powered by an LLM can reason about timing, seasonal sales, product lifecycle, and alternatives — making it genuinely more useful than a simple price tracker.

Design

Analysis Tool

# src/gaia/agents/deals/tools/analysis_tools.py
class DealAnalysisToolsMixin:
    def register_analysis_tools(self) -> None:
        from gaia.agents.base.tools import tool

        @tool
        def analyze_deal(product_name: str, current_price: float = 0) -> Dict:
            """Analyze whether a deal is worth buying now based on price history and trends.

            Args:
                product_name: Product to analyze
                current_price: Override current price (0 = use latest from DB)

            Returns:
                Analysis with recommendation, confidence, and reasoning
            """

        @tool
        def suggest_alternatives(product_name: str, budget: float = 0) -> Dict:
            """Suggest similar products that may be better deals.

            Args:
                product_name: Product to find alternatives for
                budget: Maximum budget (0 = same price range as original)
            """

Analysis Data Enrichment

The analyze_deal tool gathers context before the LLM reasons about it:

def _build_analysis_context(self, product_id: int) -> Dict:
    return {
        "price_stats": self.get_price_stats(product_id, days=365),
        "trend": self.get_price_trend(product_id, days=30),
        "is_at_historical_low": current <= stats["all_time_low"] * 1.05,
        "days_since_last_drop": ...,
        "price_volatility": ...,
        "seasonal_context": self._get_seasonal_context(),  # Black Friday, Prime Day, etc.
    }

def _get_seasonal_context(self) -> str:
    """Return upcoming sale events relevant to timing."""
    # Hardcoded calendar: Prime Day (July), Black Friday (Nov), etc.
    ...

LLM Analysis Prompt

The system prompt includes deal analysis instructions:

When analyzing a deal, consider:
1. How does the current price compare to the 30/90/365-day average?
2. Is it near the all-time low or high?
3. Is the price trending up or down?
4. Are there upcoming seasonal sales (Black Friday, Prime Day) worth waiting for?
5. What's the confidence level: HIGH (clear buy/wait), MEDIUM, LOW (insufficient data)?

Respond with:
- Recommendation: BUY_NOW, WAIT, or PASS
- Confidence: HIGH, MEDIUM, LOW
- Reasoning: 2-3 sentences explaining why

Example Output

Deal Analysis: MacBook Pro M3 14"

  Current Price: $1,299 at Best Buy
  30-Day Avg:    $1,389 (-6.5%)
  All-Time Low:  $1,199 (Black Friday 2025)
  Trend:         Falling (3 drops in 14 days)

  Recommendation: WAIT
  Confidence: HIGH

  This is a good price but not exceptional. The M3 MacBook hit $1,199
  during Black Friday — only 8 weeks away. The downward trend suggests
  retailers are clearing inventory. If you can wait, you'll likely save
  another $100. If you need it now, this is a fair price (7% below average).

Acceptance Criteria

• analyze_deal enriches context with price stats, trend, and seasonal data
• LLM provides structured recommendation (BUY_NOW/WAIT/PASS) with reasoning
• Seasonal sales calendar covers major US retail events
• suggest_alternatives searches for similar products in same category/budget
• Analysis gracefully handles products with limited price history
• Unit tests verify context building with mock data
• System prompt guides LLM to structured, actionable analysis

Phase

Phase 3 — Visualization & Intelligence

Dependencies

• Price history schema (Phase 1)
• Product search tools (Phase 1)