Product Recommendation Engine

Product Recommendation Engine

A complete recommendation system for e-commerce stores. Implements collaborative filtering, content-based filtering, trending detection, and hybrid blending — all from scratch using Python's standard library. Includes A/B testing and evaluation metrics for measuring recommendation quality.

Features

• Collaborative Filtering — User-based and item-based CF using cosine similarity. Finds patterns like "customers who bought X also bought Y" without any ML libraries
• Content-Based Filtering — TF-IDF weighted feature vectors from product attributes (category, tags, brand, title words). Handles cold-start for new users and new products
• Trending Detection — Three popularity signals: raw volume, velocity (growth rate vs previous period), and recency-weighted scoring with exponential decay
• Hybrid Blender — Merges all algorithms into a single ranked list. Three strategies: weighted average, cascade (priority-based fallback), and switching (data-availability-based)
• A/B Testing Harness — Deterministic user-to-variant assignment, event tracking, and statistical significance testing with Z-test for conversion rate comparison
• Evaluation Suite — Precision@K, Recall@K, NDCG@K, MAP@K, Hit Rate, Coverage, and multi-algorithm comparison

Quick Start

from src.collaborative_filter import CollaborativeFilter
from src.content_based import ContentBasedRecommender
from src.trending import TrendingDetector
from src.hybrid_blender import HybridBlender

# 1. Load data
cf = CollaborativeFilter.from_csv("data/sample_interactions.csv")
content = ContentBasedRecommender.from_csv("data/sample_products.csv")

# 2. Get recommendations
user_recs = cf.recommend_for_user("U001", n=10, method="user")
similar = cf.similar_items("P001", n=5)
content_recs = content.similar_products("P001", n=5)

# 3. Blend signals
blender = HybridBlender(cf=cf, content=content)
recs = blender.recommend("U001", n=10, strategy="weighted",
                          user_history=[{"product_id": "P001", "score": 5}])

for r in recs:
    print(f"  {r.product_id}  score={r.final_score:.3f}  source={r.primary_source}")

What's Included

product-recommendation-engine/
├── README.md                          ← You are here
├── LICENSE                            ← MIT License
├── .gitignore
├── src/
│   ├── __init__.py                    ← Package init with public API imports
│   ├── collaborative_filter.py        ← User-based and item-based CF
│   ├── content_based.py               ← TF-IDF content similarity
│   ├── trending.py                    ← Popularity and velocity detection
│   ├── hybrid_blender.py              ← Multi-algorithm blending
│   ├── ab_testing.py                  ← A/B test harness with stats
│   └── evaluation.py                  ← Offline evaluation metrics
├── data/
│   ├── sample_interactions.csv        ← 100 user-product interactions
│   └── sample_products.csv            ← 15 products with attributes
├── tests/
│   └── test_recommender.py            ← Full test suite (35+ tests)
├── configs/

*... continues with setup instructions, usage examples, and more.*