A production-ready, AI-powered movie recommendation system built with Django and advanced machine learning. Scalable from thousands to millions of movies.

• Overview
• Screenshots
• Features
• Quick Start
• Project Structure
• Usage
• Model Training
• API Reference
• Configuration
• Documentation
• Contributing
• License

The Movie Recommendation System provides intelligent movie suggestions using content-based filtering with TF-IDF and SVD dimensionality reduction. It features a modern web interface, RESTful API, and supports datasets from 2K to 1M+ movies.

• ✅ Production Ready - Security hardened, optimized, well-documented
• ✅ Scalable Architecture - Handles millions of movies efficiently
• ✅ Modern Tech Stack - Django 5.0, Python 3.10+, advanced ML
• ✅ Easy to Use - Simple installation, clear documentation
• ✅ Flexible - Train your own models or use demo models

• Backend: Django 6.0, Python 3.10+
• ML/Data: scikit-learn, pandas, numpy, scipy
• Storage: Parquet (efficient data format)
• Deployment: Render, Heroku, Docker compatible

• 🔍 Smart Search - Real-time autocomplete with fuzzy matching
• 🎬 AI Recommendations - Content-based filtering with 15+ suggestions
• ⭐ Rich Metadata - Ratings, votes, genres, production companies
• 🔗 External Links - Google Search and IMDb integration
• 📱 Responsive Design - Works seamlessly on all devices
• ⚡ Fast Performance - Sub-50ms recommendation generation

• 🤖 Advanced ML - TF-IDF + SVD dimensionality reduction
• 📊 Scalable - Handles 2K to 1M+ movies
• 💾 Efficient Storage - Parquet format with compression
• 🔧 Configurable - Easy model switching via MODEL_DIR
• 📡 REST API - JSON endpoints for integration
• 🔒 Secure - Production-ready security settings
• 📝 Logging - Comprehensive error tracking
• 🚀 Deployment Ready - Render, Heroku, Docker configs included

• Python 3.10 or higher
• pip package manager
• 8GB RAM (recommended for training)
• Git

# 1. Clone the repository git clone https://github.com/yourusername/movie-recommendation-system.git cd movie-recommendation-system # 2. Create virtual environment python -m venv venv # 3. Activate virtual environment # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 4. Install dependencies pip install -r requirements.txt # 5. Run database migrations python manage.py migrate # 6. Start the development server python manage.py runserver

Open your browser and navigate to:

http://localhost:8000 

That's it! The demo model (2K movies) is included and works out of the box. 🎉

movie-recommendation-system/ │ ├── 📚 Documentation │ ├── README.md # This file - overview and quick start │ ├── PROJECT_GUIDE.md # Complete technical guide │ └── CHANGELOG.md # Version history and changes │ ├── ⚙️ Django Application │ ├── movie_recommendation/ # Django project settings │ │ ├── settings.py # Configuration │ │ ├── urls.py # URL routing │ │ └── wsgi.py # WSGI entry point │ │ │ ├── recommender/ # Main application │ │ ├── views.py # Recommendation logic │ │ ├── urls.py # App URLs │ │ └── templates/ # HTML templates │ │ └── recommender/ │ │ ├── index.html # Search page │ │ ├── result.html # Results page │ │ └── error.html # Error page │ │ │ ├── manage.py # Django management script │ └── requirements.txt # Python dependencies │ ├── 🎓 Model Training │ └── training/ │ ├── train.py # Training pipeline │ ├── infer.py # Inference examples │ └── guide.md # Training documentation │ ├── 🎯 Models (Created after training) │ └── models/ │ ├── movie_metadata.parquet # Movie information │ ├── similarity_matrix.npz # Similarity scores │ ├── title_to_idx.json # Title mappings │ ├── tfidf_vectorizer.pkl # TF-IDF model │ └── svd_model.pkl # SVD reduction model │ ├── 📦 Static Files │ └── static/ │ ├── logo.png # Application logo │ ├── demo_model.parquet # Demo similarity model (2K) │ └── top_2k_movie_data.parquet # Demo movie data (2K) │ └── 🚀 Deployment ├── Procfile # Heroku configuration ├── render.yaml # Render configuration └── .gitignore # Git ignore rules 

1. Search for a Movie

   • Go to http://localhost:8000
   • Start typing a movie name in the search box
   • Select from autocomplete suggestions or type the full name

2. View Recommendations

   • Click "Get Recommendations"
   • Browse 15 similar movie suggestions
   • Each card shows: rating, release date, genres, production company

3. Explore Movies

   • Click "Google" to search for the movie
   • Click "IMDb" to view on IMDb (if available)

GET /api/search/?q=matrix Response: { "movies": ["The Matrix", "The Matrix Reloaded", "The Matrix Revolutions"], "count": 3 }

GET /api/health/ Response: { "status": "healthy", "movies_loaded": 100000, "model_dir": "./models", "model_loaded": true }

The project includes a pre-trained demo model with 2,000 popular movies. No training needed!

# Demo model is in static/ directory export MODEL_DIR=./static python manage.py runserver

Want to train on more movies or your own dataset? See the Training Guide for:

• 📖 Complete training documentation
• 🎯 Configuration options (10K to 1M+ movies)
• ⚙️ Performance tuning guidelines
• 📊 Dataset requirements
• 🔧 Advanced features

Quick Training Example:

from training.train import MovieRecommenderTrainer # Initialize trainer trainer = MovieRecommenderTrainer( output_dir='./models', use_dimensionality_reduction=True, n_components=500 ) # Train on your dataset df, sim_matrix = trainer.train( 'path/to/your/dataset.csv', quality_threshold='medium', # low/medium/high max_movies=100000 # Limit dataset size )

For detailed training instructions, see:

• 📘 Training Guide - Complete training documentation
• 📘 PROJECT_GUIDE.md - Training setup and configurations

Request:

GET /api/search/?q=inception

Response:

{ "movies": ["Inception", "Inception: The Cobol Job"], "count": 2 }

Request:

GET /api/health/

Response:

{ "status": "healthy", "movies_loaded": 100000, "model_dir": "./models", "model_loaded": true }

For complete API documentation, see PROJECT_GUIDE.md - API Reference

Create a .env file (optional for development):

# Django Settings SECRET_KEY=your-secret-key-here DEBUG=True ALLOWED_HOSTS=localhost,127.0.0.1 # Model Configuration MODEL_DIR=./models # Database (optional - defaults to SQLite) # DATABASE_URL=postgresql://user:password@localhost/dbname # Deployment # RENDER_EXTERNAL_HOSTNAME=your-app.onrender.com

To switch between models, set the MODEL_DIR environment variable:

# Use demo model (2K movies) export MODEL_DIR=./static # Use your trained model (custom) export MODEL_DIR=./models # Use absolute path export MODEL_DIR=/path/to/your/models

For detailed configuration options, see PROJECT_GUIDE.md - Configuration

• README.md (this file) - Overview, quick start, basic usage
• PROJECT_GUIDE.md - Complete technical guide
  • Installation
  • Model training
  • Configuration
  • Development
  • Deployment
  • API reference
  • Troubleshooting
• CHANGELOG.md - Version history and changes

• training/guide.md - Complete model training guide
  • Dataset requirements
  • Training configurations
  • Performance tuning
  • Advanced features

1. Push your code to GitHub
2. Connect repository to Render
3. Render auto-detects render.yaml
4. Set environment variables
5. Deploy!

• Heroku: Uses Procfile
• Docker: Create Dockerfile from PROJECT_GUIDE
• AWS: Elastic Beanstalk compatible
• Digital Ocean: App Platform ready

For detailed deployment instructions, see PROJECT_GUIDE.md - Deployment

Contributions are welcome! Here's how:

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

• Follow PEP 8 style guide
• Add tests for new features
• Update documentation
• Keep commits focused and descriptive

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

Need help? Here are your options:

• 📖 Documentation: Check PROJECT_GUIDE.md for detailed guides
• 🎓 Training Help: See training/guide.md for model training
• 🐛 Issues: Open an issue on GitHub
• 💬 Discussions: GitHub Discussions

• User authentication system
• Personal watchlists
• Movie rating system
• Advanced filtering (multiple genres, year ranges)
• Recommendation history

• Collaborative filtering
• Social features (sharing, comments)
• Movie reviews
• Advanced analytics dashboard

• Mobile applications (iOS/Android)
• Real-time recommendations
• Streaming service integration
• Enhanced ML models (hybrid recommendations)

• Movie data from TMDB and IMDb
• Built with Django, scikit-learn, pandas
• UI inspired by modern design principles
• Community contributions and feedback