Skip to content
Projects

devaldaki3/CineMatch has 136 GitHub stars and 0 forks. GitHot measured +2 stars in 24 hours. Last checked 2026-11-18 07:51 UTC. Last push 2026-04-18.

How these counts are measured

What you can do

  • 🧠 Hybrid Scoring Engine: Recommendations rely on a specialized algorithm evaluating both Content Similarity (75%) and Global Popularity (25%). This ensures suggestions are strictly relevant while preventing obscure or excessively low-rated movies from surfacing.
  • 🎭 Real-Time Sentiment Analysis: Fetches dynamic live reviews via the TMDb API and runs them through a trained Multinomial Naive Bayes classifier to instantly indicate audience verdict.
  • 📱 Interactive UI: Features responsive CSS components (style.css), horizontal scrollable carousels, and intuitive tooltips optimized for both desktop pointers and mobile touch screens.
  • 🚀 Parallel API Processing: Engineered with Python's concurrent.futures, the backend fires up to 16 concurrent threads to simultaneously fetch metadata, reviews, and cast profiles from TMDb, slashing page load times by over 300%.

Measured star growth

in 24h
+2
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Intelligent Movie Recommendation Engine powered by Machine Learning, NLP (Natural Language Processing), and real-time Sentiment Analysis via TMDb API.

Machine Learning

README.md

Original

🍿 CineMatch 🎬

Intelligent Movie Recommendation Engine powered by Machine Learning & Sentiment Analysis.

Python Flask Scikit-Learn TMDb API

A mobile-ready web application that curates precise movie suggestions using a custom hybrid scoring algorithm, while dynamically analyzing the sentiment of real-time viewer reviews via Natural Language Processing (NLP).


📸 Demo

CineMatch Demo


📖 Overview

CineMatch eliminates the paradox of choice for movie nights. By simply searching for a movie you love, our hybrid Machine Learning engine instantly generates 10 highly accurate recommendations. Engineered for a premium user experience, the system seamlessly pulls dynamic metadata (posters, runtime, genres, cast profiles) and real-time audience reviews from the TMDb API. These reviews are then fed through a trained N-Gram text classifier to immediately gauge public sentiment (Good or Bad).


✨ Core Features

  • 🧠 Hybrid Scoring Engine: Recommendations rely on a specialized algorithm evaluating both Content Similarity (75%) and Global Popularity (25%). This ensures suggestions are strictly relevant while preventing obscure or excessively low-rated movies from surfacing.
  • 🎭 Real-Time Sentiment Analysis: Fetches dynamic live reviews via the TMDb API and runs them through a trained Multinomial Naive Bayes classifier to instantly indicate audience verdict.
  • 📱 Interactive UI: Features responsive CSS components (style.css), horizontal scrollable carousels, and intuitive tooltips optimized for both desktop pointers and mobile touch screens.
  • 🚀 Parallel API Processing: Engineered with Python's concurrent.futures, the backend fires up to 16 concurrent threads to simultaneously fetch metadata, reviews, and cast profiles from TMDb, slashing page load times by over 300%.
  • ⚡ In-Memory Caching: Implements dual-layer caching (@lru_cache and dictionary-based HTML caching) ensuring that repeat movie searches load instantly in under 100ms with zero API overhead.
  • 🗜️ Ultra-Fast Vector Math: Replaced standard cosine_similarity with a pre-normalized sparse matrix dot product during startup. Computes 25,000 document vectors in just 0.5 milliseconds, generating recommendations instantly while keeping the memory footprint incredibly low.

🛠️ Technology Stack

Machine Learning & Data Processing:

  • pandas & numpy: Data manipulation and complex matrix alignments.
  • scikit-learn: TfidfVectorizer for linguistic feature extraction and MultinomialNB for NLP sentiment training.
  • scipy: Sparse matrix compression (.npz) and lightning-fast pre-normalized vector dot products.

Backend Server:

  • Flask: Python micro-framework handling API routing and templates rendering.
  • concurrent.futures: 16-Worker ThreadPoolExecutor for executing parallel, non-blocking asynchronous TMDb API requests.
  • Requests: Backend API consumption for dynamically fetching JSON metadata and reviews.

Frontend Interface:

  • HTML5, CSS3, & Vanilla JavaScript: Building responsive DOM operations and AJAX state management.
  • Jinja2: Server-side templating engine for injecting Python variables directly into UI cards.

⚙️ Architecture & Data Flow

  1. User Input: User searches via a smart dropdown powered by a local autocomplete.js script. The suggestion dictionary is dynamically injected into the frontend by Flask, extracted straight from the top 25,000 TMDb movie dataset DataFrame.
  2. Instant Caching: The /get_details route first checks its internal RAM cache. If a match exists, it serves the entire pre-rendered HTML page instantly.
  3. Recommendation Engine: Flask intercepts the payload and performs an ultra-fast matrix dot-product on our pre-normalized .npz feature vectors. Using on-the-fly thresholding prioritized by language flags, it isolates the top 10 highest-matching profiles in less than 1 millisecond.
  4. Parallel Data Fetch: The /get_details endpoint dispatches a ThreadPoolExecutor. Instead of blocking, it makes 15+ concurrent requests to the TMDb API to instantly download HD poster paths, runtimes, genres, and cast details all at the exact same time.
  5. Sentiment Processing: TMDb reviews are piped into a serialized nlp_model.pkl classifier. The text is vectorized to output a binary Good or Bad audience rating.
  6. DOM Render: Data dictionaries are pushed via Jinja2 into recommend.html, constructing dynamic movie cards and carousels, which are then passed back to securely overwrite the client's screen.

🚀 Quickstart Installation (Local)

  1. Clone the repository:

    git clone https://github.com/devaldaki3/CineMatch.git
    cd CineMatch
    
  2. Create a virtual environment:

    python -m venv venv
    source venv/bin/activate       # macOS/Linux
    .\venv\Scripts\activate        # Windows
    
  3. Install the dependencies:

    pip install -r requirements.txt
    
  4. Launch the Flask application:

    python app.py
    
  5. Start exploring: Open http://127.0.0.1:5000/ in your browser.


📂 Project Structure

CineMatch/
├── app.py                     # Main Flask Application routing & ML inference
├── README.md                  # Project Documentation
├── requirements.txt           # Listed dependencies for Web App and Jupyter
├── .gitignore                 # Custom Exclusion Policies
├── NoteBook_Experiments/      # Data Analysis, EDA, & Model Training notebooks 
├── data/                      # Raw datasets (TMDb 25k & Reviews)
├── models/                    # Serialized Machine Learning artifacts
│   ├── nlp_model.pkl          # Naive Bayes Sentiment Classifier
│   ├── tranform.pkl           # TfidfVectorizer rules for NLP
│   ├── vectors.npz            # Compressed Document Vectors matrix (SciPy Sparse)
│   └── movie_dict.pkl         # Lightweight Pandas Title/ID lookup dictionary
├── static/                    # Frontend Assets
│   ├── autocomplete.js        # Search bar suggestion handling
│   ├── recommend.js           # Core AJAX payloads and DOM manipulation
│   ├── style.css              # Custom responsive styling classes
│   └── image.jpg              # Default fallback/background assets
└── templates/                 # Renderable Jinja2 Views
    ├── home.html              # Search and discovery landing page
    ├── recommend.html         # Generated movie details panel
    └── genre.html             # Categorical exploration views


Developed with ❤️ for Movie Lovers.
Note: This product uses the TMDb API but is not endorsed or certified by TMDb.