Hybrid Movie Recommender System

A hybrid movie recommendation system combining Neural Collaborative Filtering with semantic search, featuring cross-attention mechanisms and temporal modeling.

Overview

This system implements a sophisticated movie recommendation engine that combines:

• Neural Collaborative Filtering with cross-attention for personalized ratings
• FAISS-powered semantic search for content discovery
• Temporal feature modeling using cyclic encodings
• Rich metadata integration for both users and items

Key Features

Neural CF Model

• Cross-attention mechanism for user-item interaction modeling
• Temporal feature integration with cyclic encodings
• Metadata-aware embeddings for cold-start handling
• Diversity-aware recommendation generation

Semantic Search

• BERT-based text embeddings (all-mpnet-base-v2)
• FAISS similarity search for efficient retrieval
• Genre-aware diversity scoring
• Cross-validation based evaluation

User Experience

• Interactive command-line interface
• Personalized movie recommendations
• Semantic movie search
• Similar movie discovery
• User similarity analysis

Quick Start

1. Setup Environment

git clone https://github.com/yourusername/RecSys.git
cd RecSys
python -m venv venv
source venv/bin/activate  # or 'venv\Scripts\activate' on Windows
pip install -r requirements.txt

2. Run the System

python run.py

Usage Examples

Search for Movies

from src.controller import MovieRecommenderSystem

recommender = MovieRecommenderSystem()
results = recommender.search_movies("action movies with dragons")

Get Personalized Recommendations

recommendations = recommender.get_recommendations(user_id=42, n_rec=5)

Find Similar Movies

similar_movies = recommender.similar_items(movie_id=123, k=5)

Predict User Rating

predicted_rating = recommender.predict(user_id=42, movie_id=123)

Architecture

RecSys/
├── src/
│   ├── model/
│   │   └── Retrieval.py      # Neural CF implementation
│   ├── search/
│   │   └── semantic_search.py # Semantic search engine
│   ├── controller/
│   │   └── controller.py     # System coordination
│   ├── view/
│   │   └── view.py          # CLI interface
│   └── utils/
│       └── logger.py        # Logging utilities

Model Architecture

Neural CF with Cross-Attention

Input → Embeddings → Cross-Attention → MLP → Rating Prediction
   ↑          ↑            ↑
   └─────────User/Item Features
              └───────────Temporal Features

Semantic Search Pipeline

Query → BERT Embedding → FAISS Index → Reranking → Results
                           ↑
                     Precomputed Movie
                      Embeddings

Performance Metrics

• Rating Prediction: RMSE ≈ 0.85
• Ranking: NDCG@10 ≈ 0.72
• Search: MAP ≈ 0.68
• Response Time: < 100ms

Contributing

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

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Precious - @nwaimo

Project Link: https://github.com/nwaimo/RecSys