F-Stream 🎬

AI-Powered Movie Recommendation System with a Modern Web Interface

A Netflix-like movie recommendation system built with collaborative filtering, content-based filtering, and hybrid approaches using the MovieLens 100K dataset. Features a stunning purple/blue gradient web UI.

✨ Features

• 🤖 Multiple Recommendation Algorithms

  • SVD (Singular Value Decomposition) collaborative filtering
  • KNN (K-Nearest Neighbors) collaborative filtering
  • Content-based filtering using movie genres
  • Hybrid recommendation system combining multiple approaches

• 🎨 Modern Web Interface

  • Beautiful purple/blue gradient theme
  • Fully responsive design (desktop, tablet, mobile)
  • Real-time movie search
  • Interactive movie details and similar movies

• ⚡ High Performance

  • RMSE: ~0.91 on hybrid approach
  • Fast recommendations (<200ms)
  • Handles 100,000+ ratings efficiently

• 📊 Comprehensive Analytics

  • Performance metrics (RMSE, MAE)
  • Cross-validation support
  • Model persistence (save/load trained models)

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• pip package manager

Installation

1. Clone the repository

   git clone https://github.com/yourusername/F-Stream.git
   cd F-Stream

2. Install dependencies

   pip install -r requirements.txt

3. Run the web application

   python3 run.py

4. Open your browser

   http://localhost:5001
   

The system will automatically download the MovieLens 100K dataset (~5MB) on first run and train the models (~30-60 seconds).

🎯 Usage

Web Interface

Launch the modern web UI:

python3 run.py

Features:

• Personalized Recommendations: Switch between Hybrid, Collaborative, and Content-based methods
• Search: Real-time movie search as you type
• User Switching: Test recommendations for any user (1-943)
• Movie Details: Click any movie for full information and similar movies
• Genre Browsing: Explore by Action, Comedy, Drama, and more

Command Line Interface

Interactive mode:

python3 main.py --interactive

Get recommendations for a user:

python3 main.py --user 1 --n 10 --method hybrid

Find similar movies:

python3 main.py --movie 1 --n 5

Python API

from data_loader import MovieLensLoader
from collaborative_filtering import CollaborativeFilteringModel
from hybrid_recommender import HybridRecommender

# Load data
loader = MovieLensLoader()
loader.load_all()
data = loader.get_surprise_dataset()

# Train model
cf_model = CollaborativeFilteringModel()
cf_model.build_model('svd')
cf_model.train(data)

# Get recommendations
user_ratings = loader.get_user_ratings(1)
recommendations = cf_model.get_top_n_recommendations(1, n=10)

📁 Project Structure

F-Stream/
├── app.py                      # Flask web application
├── run.py                      # Web server launcher
├── main.py                     # CLI application
├── config.py                   # Configuration
├── data_loader.py              # Dataset management
├── collaborative_filtering.py  # SVD, KNN models
├── content_based.py            # Content-based filtering
├── hybrid_recommender.py       # Hybrid strategies
├── frontend/                   # Web interface
│   ├── templates/
│   │   └── index.html         # Main page
│   └── static/
│       ├── css/style.css      # Modern styling
│       └── js/app.js          # Frontend logic
├── notebooks/                  # Jupyter notebooks
│   └── exploration.ipynb      # Data analysis
├── requirements.txt            # Dependencies
└── README.md                   # This file

🧠 Algorithms

1. Collaborative Filtering (SVD)

• Algorithm: Matrix factorization using Singular Value Decomposition
• Parameters: 100 factors, 20 epochs, learning rate 0.005
• Performance: RMSE ~0.93
• Best for: Users with substantial rating history

2. Collaborative Filtering (KNN)

• Algorithm: K-Nearest Neighbors with cosine similarity
• Parameters: k=40 neighbors
• Performance: RMSE ~0.98
• Best for: Finding similar users or items

3. Content-Based Filtering

• Features: 19 movie genre categories
• Similarity: Cosine similarity on genre vectors
• Best for: New users or niche preferences

4. Hybrid Recommendation

• Strategy: Adaptive weighting based on user profile
• Performance: RMSE ~0.91
• Configuration:
  • Users with <10 ratings: 30% CF + 70% Content
  • Users with ≥10 ratings: 80% CF + 20% Content

📊 Dataset

MovieLens 100K

• 100,000 ratings from 943 users on 1,682 movies
• Ratings: 1-5 stars
• 19 genre categories
• User demographics (age, gender, occupation)
• Automatically downloaded on first run

🎨 Web Interface

Modern Design

• Purple/blue gradient theme (#7C3AED → #2563EB)
• Glassmorphism effects
• Smooth animations (60fps)
• Responsive breakpoints for all devices

API Endpoints

GET /api/stats                      # Dataset statistics
GET /api/movies                     # Browse movies
GET /api/movie/{id}                 # Movie details
GET /api/recommendations/{user_id}  # Get recommendations
GET /api/similar/{movie_id}         # Similar movies
GET /api/search?q=query            # Search movies
GET /api/genres                     # List genres

🛠️ Configuration

Edit config.py to customize:

# SVD parameters
COLLABORATIVE_FILTERING_PARAMS = {
    'svd': {
        'n_factors': 100,      # Latent factors
        'n_epochs': 20,        # Training iterations
        'lr_all': 0.005,       # Learning rate
        'reg_all': 0.02        # Regularization
    }
}

# Recommendations
TOP_N_RECOMMENDATIONS = 10
MIN_RATING_THRESHOLD = 3.5

📈 Performance

Algorithm	RMSE	MAE	Training Time
SVD	0.93	0.73	~5 seconds
KNN Basic	0.98	0.77	~3 seconds
KNN with Means	0.95	0.75	~3 seconds
Content-Based	N/A	N/A	~1 second
Hybrid	0.91	0.71	~6 seconds

Tested on MacBook Pro M1, 16GB RAM

🧪 Testing

Run individual modules:

# Test data loader
python3 data_loader.py

# Test collaborative filtering
python3 collaborative_filtering.py

# Test content-based filtering
python3 content_based.py

# Test hybrid recommender
python3 hybrid_recommender.py

Explore data:

jupyter notebook notebooks/exploration.ipynb

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Dataset: MovieLens 100K by GroupLens Research
• Algorithms: Based on research from the Netflix Prize competition
• Libraries:
  • Surprise - Recommender systems library
  • Scikit-learn - Machine learning tools
  • Flask - Web framework
  • Pandas - Data manipulation

📚 References

• Koren, Y., Bell, R., & Volinsky, C. (2009). Matrix Factorization Techniques for Recommender Systems. IEEE Computer.
• Ricci, F., Rokach, L., & Shapira, B. (2015). Recommender Systems Handbook.
• Surprise Documentation
• Netflix Prize

📧 Contact

Your Name - @yourtwitter

Project Link: https://github.com/yourusername/F-Stream

---

F-Stream - Making movie discovery intelligent and beautiful! 🎬✨