Skip to content

README.md

Latest commit

 

History

History
82 lines (57 loc) · 2.84 KB

README.md

File metadata and controls

82 lines (57 loc) · 2.84 KB
Raw

🎬 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.

Python Gradio TMDB

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

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

Acknowledgements

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