README.md

metadata

title: RetailGenie
emoji: 🛍️
colorFrom: yellow
colorTo: gray
sdk: gradio
sdk_version: 5.38.2
app_file: app.py
pinned: false
short_description: AI Shopping Assistant, Locator & Smart Suggestions
license: mit

🛍️ RetailGenie – In-Store Smart Assistant

RetailGenie is an AI-powered shopping assistant that helps users locate in-store products using dropdown filters and get intelligent product suggestions based on natural language queries. Built with Gradio and sample retail data, this project simulates a real-time in-store assistant combining rule-based filtering with FLAN-T5-based AI recommendations.

⚠️ This project is for educational and demonstration purposes only. Product data is mock/simulated and may not reflect real-time inventory.

---

🌐 Try Live on Hugging Face

RetailGenie is live and accessible via Hugging Face Spaces:

👉 Launch RetailGenie on Hugging Face Spaces

No setup needed – just visit and start exploring!

---

✨ Key Features

🧭 Navigator Tab

• Multi-level dropdown filters:
  • Country → State → City → Store → Category → Product → Brand
• Displays:
  • ✅ Availability
  • 💰 Price
  • 🏬 Floor, 🪑 Aisle
  • 🎁 Offers
• Data is dynamically loaded from nested .csv files

🧠 Smart Suggestions Tab

• Accepts natural language queries like:
  • "gift under 500", "shampoo for dry hair"
• Filters products based on:
  • Price limits
  • Tags (dry, oily, gift, budget, etc.)
  • Stock status
• Response is generated using:
  • google/flan-t5-small via Hugging Face Transformers
• Fallback to hardcoded suggestions if no match is found

---

🧠 System Architecture

User Input (Dropdown / Text)
    │
    ├── Navigator Tab     → File system path chaining → Data lookup → Result
    └── Smart Suggestions → Rule filters + model call → Generated response

---

## 🛠️ Tech Stack

| Category            | Tool / Library                       | Purpose                                      |
|---------------------|--------------------------------------|----------------------------------------------|
| **Programming Language** | Python 3.10                         | Core backend logic and data handling         |
| **Frontend Framework**  | Gradio                              | Web UI with tabs, dropdowns, and text input  |
| **NLP Model**           | google/flan-t5-small (via 🤗 Transformers) | Natural language product recommendations     |
| **Data Handling**       | Pandas                              | Reading, filtering, and managing CSV data    |
| **Deployment**          | Hugging Face Spaces                 | Hosting and public access to the app         |
| **UI Styling**          | HTML, CSS (via Gradio Markdown)     | Custom styling for layout and response boxes |
| **Fallback Logic**      | Python conditionals + emoji formatting | Default suggestions when model fails       |

---

## 📈 Example Queries and Outputs

### 🔹 Smart Suggestions Tab (Natural Language)

| 💬 User Query                            | 🤖 AI Response (Sample)                                                        |
|------------------------------------------|--------------------------------------------------------------------------------|
| `shampoo for dry hair under 300`         | "You may try Dove Dryness Repair – ₹280, available at Floor 1, Aisle 3."      |
| `gift for brother under 500`             | "A perfect gift is our Men’s Grooming Kit – ₹450, available at Floor 2, Aisle 5." |
| `budget skincare for oily skin`          | "Try Clean & Clear Oil Control Face Wash – ₹150, available at Floor 1, Aisle 2." |
| `face cream above 700`                   | "You might like Olay Regenerist – ₹899, found at Floor 3, Aisle 7."            |

### 🔹 Navigator Tab (Dropdowns)

Sample user path:

Country → India
→ State → Karnataka
→ City → Bangalore
→ Store → StoreA
→ Category → Shampoo
→ Product → Dove
→ Brand → Dryness Repair
→ Quantity → 500ml

**Output:**

✅ In Stock: Yes
💰 Price: ₹280
🏬 Floor: 1
🪑 Aisle: 3
🎁 Offer: Buy 1 Get 1 Free

---

## 🧪 Run Locally

Follow the steps below to set up and run RetailGenie on your machine:

### 1. Clone the Repository

```bash
git clone https://github.com/your_username/RetailGenie.git
cd RetailGenie

2. Install Dependencies

pip install -r requirements.txt

3. Launch the App

python app.py

The app will be available at http://localhost:7860/