🛍️ Smart Product Recommender

A production-grade recommendation engine that delivers personalized product suggestions using semantic embeddings, vector search, and user behavior.

Quick Start • Features • How It Works • API • Future

✨ Features

Category	Description
🔍 Semantic Search	Lightning-fast product search + filtering
🤖 Embedding Recs	all-MiniLM-L6-v2 → dense vectors → FAISS ANN search
🛒 Shopping Cart	Add/remove items • real-time total • localStorage persistence
🎯 Personalized Recs	"You might also like" based on last cart item + fallback popular items
📊 Behavior Tracking	Logs views, adds, searches → logs/user_behavior.csv
🌐 Clean REST API	Flask + CORS • well-structured endpoints

🏗 Project Architecture

MODEL-ML-FINAL/
├── api/                    # Flask blueprints & routes
├── data/
│   ├── raw/                # source .csv / .json
│   └── processed/          # .parquet + cleaned data
├── frontend/               # static SPA-like UI
│   ├── index.html
│   ├── product.html
│   ├── cart.html
│   └── assets/ (css/js)
├── logs/                   # interaction logs
├── models/
│   ├── embedding_model.py
│   ├── similarity_model.py
│   ├── train_model.py
│   └── artifacts/
│       ├── faiss_index.bin
│       └── products.parquet
├── services/               # core business logic
├── utils/                  # helpers, loaders, preprocess
├── app.py                  # Flask entrypoint
├── config.py
└── requirements.txt

⚡ Tech Stack

Backend & ML
Python • Flask • Pandas • FAISS-cpu/gpu • sentence-transformers

Frontend
HTML5 • CSS (modern flex/grid + variables) • Vanilla JavaScript

Storage & Search
Parquet • FAISS FlatIP / IVF index • localStorage (cart)

🔄 How It Works – Recommendation Flow

User views / adds product
          ↓
   Fetch text: name + category + description
          ↓
 SentenceTransformer → 384-dim embedding
          ↓
     FAISS → k-nearest neighbors
          ↓
   Return top similar products (filtered)

Personalization logic
if cart not empty → use last added item
else → popular / random high-quality fallback

🔌 API Endpoints

Method	Endpoint	Description
GET	/api/products	List all products (paginated)
GET	/api/search?q=query	Fuzzy + semantic search
GET	/api/product/<id>	Single product detail
GET	/api/recommend/<product_id>	Top-K similar products

All endpoints return clean JSON.

🚀 Quick Start

# 1. Clone
git clone https://github.com/your-username/product-recommendation-system.git
cd product-recommendation-system

# 2. Virtual env
python -m venv env
source env/bin/activate    # Linux/macOS
# or .\env\Scripts\activate # Windows

# 3. Install
pip install -r requirements.txt

# 4. Generate embeddings & FAISS index (only once)
python -m models.train_model

# 5. Start backend
python app.py
# → http://localhost:5000

# 6. Start frontend (separate terminal)
cd frontend
python -m http.server 8000
# → http://localhost:8000

Tip: Open browser dev tools → Network tab to see API calls in action.

📸 Screenshots

Home / Search	Product Detail + Recs	Cart

🧩 Key Challenges Overcome

• CORS configuration between Flask & static frontend
• Handling missing/undefined product fields gracefully
• ID consistency across parquet ↔ FAISS ↔ frontend
• Fast recommendations even on modest hardware
• Clean separation between ML training & serving

🚀 Roadmap / Future Ideas

• Collaborative filtering + hybrid (content + behavior)
• Real-time trending products from logs
• User profiles & session-based recs
• PostgreSQL / Redis caching layer
• Docker + docker-compose
• Migrate frontend → React / Tailwind
• A/B testing different embedding models

👤 Author

Ankit Kumar Singh
B.Tech • Data Engineer • ML Enthusiast

⭐ If this project helped you or inspired you — feel free to give it a star!

Feedback, issues, and PRs are very welcome 🙌

```