ShopGeni — AI Shopping Assistant#

ShopGeni exposes two AI-powered shopping capabilities:

1. Item Recommendation — natural-language and visual product search
2. Price Comparison — find the best price for a product across Amazon, Google Shopping, and brand stores

---

1. Item Recommendation#

Search for products using natural language or a product image.

Triggers: "find me a dress", "show sneakers under $100", "recommend a blue denim jacket", "what shoes match this outfit?"

Text search:

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --query "blue running shoes under $120"

Visual search (image file):

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --image "/path/to/photo.jpg" \
  --query "find similar products"

---

2. Price Comparison#

Find the best price for a specific product across multiple stores.

Triggers: "find best price for X", "compare prices for X", "where can I buy X cheapest"

Text query:

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --query "find best price for Nike Air Force 1 white"

From a product URL: Extract the product name and brand from the URL yourself, then pass as --query. Do not pass URLs to the script — the backend searches by keyword.

Query construction: Build the richest possible query from available product attributes — include brand, product name, and any of: style number, color, gender, category. More specific queries yield better results. Examples:

• "find best price for Reebok Women's Zignition Running Shoes Black/White"
• "find best price for Nike Air Force 1 Low Men's Sneaker White style 100074219"
• "find best price for Adidas Response Super Women's Running Shoes"

With image URL (recommended for better accuracy): Pass --image-url with the product image URL. The backend uses it for visual similarity ranking. If the user searched for products first, use the image field from that recommendation:

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --query "find best price for Reebok Women's Zignition Running Shoes Black/White" \
  --image-url "https://example.com/product-image.jpg"

From a local image file:

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --image "/path/to/product.jpg" \
  --query "find best prices for this product"

---

Follow-up Queries#

Pass --thread-id to continue a conversation:

bash

python3 $SKILL_PATH/scripts/shopgeni.py \
  --query "show me similar ones in red" \
  --thread-id "previous-thread-uuid"

---

Response JSON#

json

{
  "intent": "item | price_comparison",
  "content": "assistant response text",
  "thread_id": "uuid",
  "recommendations": [
    {
      "id": "...",
      "name": "Product Name",
      "brand": "Brand",
      "merchant": "Store Name",
      "price": "$99.99",
      "image": "https://...",
      "category": "shoes",
      "product_url": "https://www.beyondstyle.us/prod?id=..."
    }
  ],
  "price_comparison": {
    "candidates": [
      {
        "name": "Product Name",
        "price": "$89.99",
        "source": "Amazon",
        "buy_url": "https://..."
      }
    ]
  }
}

---

Display Guidelines#

• Item recommendations: Show as a markdown table or bullet list with name, brand, price, and link
• Price comparison: Show as a ranked table: Rank | Store | Price | Link
• Always show the content field as the assistant's main response
• Save thread_id from the response if the user may want to follow up