🛍️ Product Shopping Assistant - India

A conversational-first shopping agent powered by Vercel AI SDK, Google Gemini, and Google Shopping API (via SerpApi). This is a product shopping ONLY assistant that helps users find and compare products from Indian online stores.

Key Features:

• 🤖 Conversational AI that understands shopping needs
• 🔍 Google Shopping search (India-specific, English)
• 🔗 NEW! Amazon product lookup by link - Get instant details + cross-platform price comparison
• ⭐ Intelligent filtering: Top 5 products by rating & price
• 💰 Price comparisons in INR (₹)
• 🏪 Focus on trusted Indian retailers (Amazon.in, Flipkart, Croma, etc.)
• 🎯 Smart sorting: Highest ratings first, then lowest prices

Setup

1. Copy .env.example to .env and add your API keys:

   • GEMINI_API_KEY - Required for the AI agent (get from https://aistudio.google.com/app/apikey)
   • SERPAPI_KEY - Required for Google Shopping searches (get from https://serpapi.com/)
   • Optional: DEFAULT_MODEL - Gemini model to use (default: gemini-1.5-flash)

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Usage

Agent Mode (Recommended - Agentic Behavior)

The agent autonomously decides when to search for products and can chain multiple tool calls:

# Basic usage
node ./dist/index.js agent "Find me the best iPhone under 60000 in Mumbai"

# With interactive preference prompts
node ./dist/index.js agent "Show me laptops" --interactive

# Specify location and preferred stores
node ./dist/index.js agent "Gaming phones" --location "Bengaluru, India" --stores "Amazon,Flipkart"

# Get structured JSON output with full trace
node ./dist/index.js agent "Best headphones" --json

# Use a specific Gemini model
node ./dist/index.js agent "Smartwatches under 5000" -m gemini-1.5-pro

🌟 Enhanced Shopping Agent (BEST - Conversational + Smart Filtering)

NEW! Conversational shopping assistant with intelligent product filtering:

• Searches in English for India (gl=in, hl=en)
• Returns TOP 5 products only (highest rated, best priced)
• Smart sorting: Rating (high→low) then Price (low→high)
• Filters out products without ratings
• Prioritizes Indian merchants

# Start interactive shopping session
node ./dist/index.js chat-enhanced

# Single query with enhanced filtering
node ./dist/index.js ask-enhanced "Best laptop under 50000"

Example Conversations:

You: I need a gaming laptop under 40K
Agent: What specs do you need? RAM, processor type?
You: 8GB RAM, good graphics
Agent: Got it! Gaming laptop, 8GB+ RAM, good graphics, under ₹40K. Should I search?
You: yes
Agent: [Shows top 5 laptops with ratings, prices, stores]

🔗 Amazon Product Lookup (NEW!)

Paste any Amazon.in product link to get instant details + cross-platform price comparison:

# Start enhanced agent
node ./dist/index.js chat-enhanced

# Then paste Amazon link:
You: https://www.amazon.in/dp/B08N5WRWNW give me details

Agent: [Shows product details: price, rating, reviews, specs]
       Would you like me to compare prices on other platforms?

You: yes

Agent: [Searches Flipkart, Croma, etc. and shows price comparison]

Supported Amazon URL formats:

• https://www.amazon.in/dp/ASIN
• https://www.amazon.in/gp/product/ASIN
• https://amazon.in/Product-Name/dp/ASIN
• Direct ASIN code (e.g., B08N5WRWNW)

What you get:

• 🏷️ Product name and title
• 💵 Current Amazon price
• ⭐ Star rating + review count
• 📋 Key specifications
• 💬 Top customer reviews (3 snippets)
• 🔗 Direct purchase link
• 💡 Automatic offer to compare prices across platforms

📖 See DOCS/AMAZON_LOOKUP.md for detailed guide

Conversational Agent (Original)

Interactive chat session with context memory and autonomous tool use:

# Start conversational agent (maintains context across turns)
node ./dist/index.js chat-agent

# With preferences
node ./dist/index.js chat-agent --location "Mumbai, India" --stores "Amazon,Flipkart"

# Commands in chat:
# - Type your message naturally
# - "clear" - Reset conversation history
# - "exit" - Quit

Other Commands

# Simple chat (single prompt, no context)
node ./dist/index.js chat "Hello, what's the weather?"

# Interactive conversation loop (with context, no tools)
node ./dist/index.js converse

# Direct search (no AI)
node ./dist/index.js search "iPhone 14" -n 5

# Ask with tool orchestration (older non-agent mode)
node ./dist/index.js ask "Where to buy iPhone?"

Features

🎯 Smart Product Filtering (Enhanced Agent)

The enhanced agent implements intelligent result processing:

1. Fetch: Requests 20-30 products from Google Shopping API
2. Filter: Keeps only products with ratings and valid prices
3. Sort: First by rating (high→low), then by price (low→high)
4. Top 5: Returns only the best 5 products
5. Insights: Calculates price ranges, average ratings, review counts

Result Quality Guarantee:

• ⭐ All products have customer ratings
• 💰 Valid prices in INR (₹)
• 🏪 Trusted Indian merchants prioritized
• 📊 Sorted for best value (quality + price)

🇮🇳 India-Specific Search

Search Parameters:

• engine: google_shopping (ONLY - no web search)
• gl: in (India region)
• hl: en (English language)
• google_domain: google.co.in
• currency: INR
• location: "India"

JSON Fields Extracted:

• title - Product name
• extracted_price - Price as number (for sorting)
• price - Formatted price string
• source - Store name (Amazon.in, Flipkart, etc.)
• rating - Star rating (1-5)
• reviews - Number of customer reviews
• product_link - Direct link to product page
• thumbnail - Product image URL

🤖 Conversational-First Agent

• Shopping Focus: ONLY discusses products and shopping
• Context Memory: Remembers budget, preferences, past searches
• Natural Chat: Asks about needs before searching
• Smart Tool Use: Searches only when user needs product options
• No Generic AI: Redirects non-shopping questions politely

🔧 Agentic Behavior

Uses Vercel AI SDK with Gemini function-calling:

• Autonomous tool selection

• Multi-step reasoning

• Query analysis and refinement

• Result synthesis with insights

• Error recovery and fallbacks

  • Prices displayed in ₹ (INR)

• Interactive Mode: Optionally prompts for user preferences (budget, stores, location) before searching

• Streaming Responses: Real-time token streaming for better UX

• Structured Output: Use --json flag to get full execution trace with tool calls and results

Example Conversations

Enhanced Agent (Recommended)

# Start shopping session
node ./dist/index.js chat-enhanced

You: Hi, I need a laptop for college
Assistant: Hey! I'd love to help you find a great laptop for college! 🎓
          Let me ask a few questions to find the perfect match:

          What's your budget? (e.g., under 50000 INR)

You: Around 40000
Assistant: Perfect! ₹40,000 is a good budget for a student laptop.

          What will you mainly use it for?
          - Basic tasks (browsing, docs, videos)?
          - Programming/coding?
          - Design/video editing?
          - Gaming?

You: Programming and some light gaming
Assistant: Got it! So you'll need decent specs - good processor, 8GB+ RAM.
          Any preferences? (Intel/AMD? Specific brands?)

You: No preference, just want good value
Assistant: Let me search for the best laptops in your budget...

🔍 Searching Google Shopping (India): "laptop programming gaming under 40000 India"
📦 Raw results: 25 products
⭐ Top 5 best products (by rating & price)

- Requires `GEMINI_API_KEY` and `SERPAPI_KEY` in `.env`
- Default model is `gemini-1.5-flash` (fast and cost-effective)
- Agent iterates up to 5 steps by default (configurable with `--max-iterations`)
- For production use, consider adding rate limiting, retry logic, and comprehensive error handling