noopur17/retail-recommendation-engine repository overview

⁠🛍️ Retail Recommendation Engine

AI-powered retail recommendation system using TF-IDF, cosine similarity, and intelligent ranking signals to generate relevant and business-aware product recommendations.

---

⁠🚀 Key Features

• 🔍 Content-Based Recommendations

  • TF-IDF + cosine similarity on product metadata
  • Uses product name, brand, category, tags, and description

• 🧠 Smart Ranking Layer (V2)

  • Improves recommendations using:

    • Category match
    • Sub-category alignment
    • Brand affinity
    • Product rating
    • Review count
    • Price similarity

• ⚡ FastAPI Backend

  • High-performance REST API
  • Easy integration with frontend systems

• 🐳 Dockerized Deployment

  • Fully containerized for easy setup and scaling

---

⁠🏗️ Architecture

User Request → FastAPI → Recommender Engine → TF-IDF Model → Similarity + Ranking → Response

---

⁠📊 Recommendation Logic

⁠Step 1: Candidate Generation

• TF-IDF vectorization
• Cosine similarity

⁠Step 2: Re-Ranking

Final score combines similarity + business signals:

final_score = similarity + category + brand + rating + reviews + price

This ensures:

• relevant recommendations
• retail-aware ranking
• better product discovery

---

⁠📁 Project Structure

retail-recommendation-engine/ │ ├── app/ │ ├── main.py │ └── routes/ │ └── recommendations.py │ ├── recommender/ │ ├── train.py │ ├── recommend.py │ └── ranker.py │ ├── models/ │ ├── data.pkl │ └── similarity.pkl │ ├── tests/ ├── requirements.txt ├── Dockerfile └── README.md

---

⁠▶️ Run Locally

⁠1. Setup

python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

⁠2. Train Model

python3 -m recommender.train

⁠3. Start API

python3 -m uvicorn app.main:app --reload

⁠4. Test

http://127.0.0.1:8000/docs⁠

---

⁠🐳 Docker Usage

⁠Build

docker build -t noopur17/retail-recommendation-engine:latest .

⁠Run

docker run -p 8000:8000 noopur17/retail-recommendation-engine:latest

---

⁠📌 API Example

GET /recommendations/{product_id}

⁠Response

{ "product_id": 1, "recommendations": [ { "product_id": 7, "product_name": "Almond Snack Pack", "similarity_score": 0.0556, "final_score": 0.6894 } ] }

---

⁠🧠 Future Enhancements

• Hybrid recommendation system
• User personalization
• Evaluation metrics (Precision@K)
• React frontend UI
• A/B testing for ranking

---

⁠👩‍💻 Author

Noopur Bhatt Full Stack Engineer | Retail Systems

---

⁠🌟 Why This Project

• Demonstrates real-world ML system design
• Shows production-ready API development
• Applies retail domain intelligence
• Built for scalability and deployment

---