🎬 CineMatch

Search for any movie and instantly get the 5 most similar movies, each with a similarity percentage — powered by a content-based recommender that combines genre, keyword, plot-embedding, and cast/crew signals.

How it works

1. Search — your query is matched to a movie via the TMDB API.

2. Candidate gathering — CineMatch pulls TMDB's "similar movies" plus a genre-based discover pass, de-duplicates them, and fetches full details (credits + keywords) for up to 40 candidates concurrently.

3. Scoring — each candidate is scored against the target movie:

   Signal	Weight	Method
   Genres	35%	Jaccard similarity of genre sets
   Plot overview	25%	Cosine similarity of all-MiniLM-L6-v2 sentence embeddings
   Keywords	20%	Jaccard similarity of TMDB keywords + RAKE phrases extracted from the overview
   Cast & director	20%	Top-5 cast overlap (60%) + same director (40%)

4. Results — the top 5 candidates are rendered as cards with posters, similarity bars, and overviews.

Getting started

Prerequisites

• Python 3.11+
• A free TMDB API key

Setup

git clone https://github.com/LucaLazar07/CineMatch.git
cd CineMatch

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r backend/requirements.txt

Create backend/.env:

TMDB_API_KEY=your_tmdb_api_key_here

Run

cd backend
python gradio_app.py

Open http://localhost:7860, type a movie title (e.g. Inception), and hit Find similar movies.

The first search downloads the sentence-transformer model (~90 MB) and NLTK data, so it takes a moment. Subsequent searches are fast — computed features are cached per movie.

Project structure

backend/
├── gradio_app.py            # Gradio UI + candidate gathering pipeline
├── requirements.txt
└── app/
    ├── core/config.py       # Settings (TMDB key via .env)
    ├── services/            # Async TMDB API client (httpx)
    └── recommender/         # Content-based similarity engine

Tech stack

• Gradio — web UI
• sentence-transformers — plot overview embeddings
• rake-nltk — keyword phrase extraction
• httpx — async TMDB requests
• numpy / scikit-learn — similarity math

Acknowledgements

This product uses the TMDB API but is not endorsed or certified by TMDB.