AI-Powered Shopping Assistant 🛍️

An intelligent shopping assistant that helps users find products with natural language queries and provides personalized recommendations. Built with Python and Typesense, this chatbot-style application offers an engaging shopping experience with smart product suggestions and styling tips.

✨ Features

• 🗣️ Natural Language Understanding: Ask for products in everyday language
• 🎯 Smart Product Search: Finds relevant items based on your requirements
• 👔 Style Recommendations: Get personalized styling tips for products
• 🎨 Color Matching: Understands color relationships and combinations
• 💡 Alternative Suggestions: Offers similar options when exact matches aren't found
• 💬 Interactive Experience: Engaging chatbot-style interface with Rich text formatting

🚀 Getting Started

Prerequisites

• Python 3.8+
• Typesense Server
• OpenAI API Key

Installation

1. Clone the repository:

git clone https://github.com/thakurcoderz/ai-powered-shopping-assistant.git
cd ai-powered-shopping-assistant

2. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Copy the example environment file and update with your credentials:

cp .env.example .env

5. Update .env with your API keys:

OPENAI_API_KEY=your-openai-api-key-here
TYPESENSE_API_KEY=your-typesense-api-key-here
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http

Running the Application

1. Start the interactive demo:

python product_recommendation_agent.py interactive

2. Or run with example queries:

python product_recommendation_agent.py

💬 Example Interactions

Try asking things like:

• "Show me comfortable walking shoes"
• "I need a casual outfit for work"
• "Find me a warm winter jacket"
• "Something light colored to go with dark jeans"

Example response:

📦 Found 3 items that match your request:
--------------------------------------------------

1. **Product Name** - $Price
   ✓ Color: Color
   ✓ Material: Material
   ✓ Category: Category
   ✓ Stock: X available

==================================================
Additional Information:
==================================================

👔 STYLING TIP:
   [Personalized styling advice]

🔄 ALTERNATIVE OPTIONS:
   [Similar product suggestions]

❓ WHAT'S NEXT:
   [Follow-up question]

🛠️ Technical Details

Agent Architecture

The system uses a multi-agent architecture with specialized agents:

1. Query Interpreter Agent:

   • Analyzes natural language queries
   • Extracts search parameters
   • Handles ambiguous requests
   • Uses GPT-4.1-nano model

2. Search Refinement Specialist:

   • Improves search results
   • Applies intelligent filters
   • Tracks search iterations
   • Uses GPT-4.1-nano model

3. Result Quality Evaluator:

   • Assesses result relevance
   • Scores product matches
   • Suggests improvements
   • Uses GPT-4.1-nano model

4. Product Search Specialist:

   • Executes precise searches
   • Manages faceted search
   • Handles price ranges
   • Uses GPT-4.1-nano model

5. Product Recommendation Expert:

   • Coordinates other agents
   • Provides final recommendations
   • Adds styling tips
   • Uses GPT-4.1-nano model

Sequence Diagram

Multi-Agent Architecture

This multi-agent architecture ensures:

• Specialized processing at each step
• Quality control throughout the pipeline
• Efficient coordination between components
• Comprehensive product recommendations

Data Models

1. Product Model:

   class Product(BaseModel):
       product_id: Optional[str]
       product_name: Optional[str]
       price: Optional[float]
       category: Optional[str]
       sub_category: Optional[str]
       color: Optional[str]
       material: Optional[str]
       gender: Optional[str]
       size: Optional[str]
       description: Optional[str]
       keywords: Optional[str]
       quantity_in_stock: Optional[int]
       relevance_score: Optional[float]

2. ProductRecommendation Model:

   class ProductRecommendation(BaseModel):
       greeting: str
       products: List[Product]
       reasoning: str
       total_found: int
       confidence_score: float
       styling_tip: str
       follow_up_question: str
       alternative_suggestions: str

Key Features

1. Smart Search Logic:

   • Semantic understanding of queries
   • Color and style matching
   • Category-aware search
   • Price range consideration

2. Recommendation System:

   • Personalized product suggestions
   • Style compatibility analysis
   • Alternative recommendations
   • Contextual follow-up questions

3. User Experience:

   • Rich text formatting
   • Clear product presentations
   • Helpful styling tips
   • Interactive refinement options

📝 Configuration

Typesense Schema

The product collection should have the following fields:

• product_id: string
• product_name: string
• price: float
• category: string
• sub_category: string
• color: string
• material: string
• gender: string
• description: string
• keywords: string
• quantity_in_stock: int

Environment Variables

Required environment variables:

• OPENAI_API_KEY: Your OpenAI API key
• TYPESENSE_API_KEY: Your Typesense API key
• TYPESENSE_HOST: Typesense server host
• TYPESENSE_PORT: Typesense server port
• TYPESENSE_PROTOCOL: HTTP/HTTPS

🙏 Acknowledgments

• OpenAI for the GPT-4.1-nano model
• Typesense for the search engine
• Rich library for beautiful terminal formatting