🎬 Movie Recommender System

A full-stack Movie Recommendation web application built using FastAPI as the backend API and Streamlit as the interactive frontend. The system combines Machine Learning (TF-IDF Content-Based Filtering) with real-time data from the TMDB (The Movie Database) API to deliver accurate recommendations, movie details, posters, and category feeds.

• 🔍 Real-time Search & Autocomplete: Search movies with dynamic keyword matching and instant dropdown suggestions.
• 🤖 Content-Based ML Recommendations: Recommends similar movies based on textual plot and feature similarities using TF-IDF Vectorization and Cosine Similarity.
• 🎭 Genre-Based Recommendations: Discovers popular movies within the same primary genre via TMDB API integration.
• 🏠 Curated Home Feeds: Explore movies by categories: Trending, Popular, Top Rated, Upcoming, and Now Playing.
• 📄 Rich Movie Details: View high-resolution posters, backdrops, release dates, genres, overviews, and YouTube trailer links.
• 📱 Interactive UI: Responsive poster grid layout with customizable column count and URL query-param routing.

• Frontend: Streamlit
• Backend API: FastAPI, Uvicorn, HTTPX
• Machine Learning & Data: Python, Pandas, NumPy, Scikit-Learn (TF-IDF Vectorizer, Cosine Similarity)
• Data Source: TMDB API & Local Movie Dataset

TMDB_Movies/
├── app.py                # Streamlit frontend UI application
├── main.py               # FastAPI backend server & ML endpoints
├── data/                 # Datasets & precomputed ML model artifacts
│   ├── df.pkl            # Pickled DataFrame of processed movies
│   ├── indices.pkl       # Movie title-to-index lookup mapping
│   ├── tfidf.pkl         # Trained TF-IDF Vectorizer
│   ├── tfidf_matrix.pkl  # Precomputed TF-IDF feature matrix
│   └── movies.csv        # Raw dataset
├── .env                  # Environment variables (TMDB API Key)
├── requirement.txt       # Python package dependencies
└── README.md             # Project documentation

• Python 3.10+
• TMDB API Key (Get a free key from The Movie Database)

Create a .env file in the project root directory and add your TMDB API key:

TMDB_API_KEY=your_tmdb_api_key_here

Create and activate a Python virtual environment:

# Create virtual environment
python3 -m venv venv

# Activate on macOS/Linux
source venv/bin/activate

# Activate on Windows
# venv\Scripts\activate

Install the required dependencies:

pip install -r requirement.txt

Run the backend server in your terminal:

uvicorn main:app --reload

The FastAPI backend will run on http://127.0.0.1:8000 (Swagger docs available at http://127.0.0.1:8000/docs).

Open a new terminal tab, activate the virtual environment, and run:

source venv/bin/activate
streamlit run app.py

The Streamlit web interface will launch automatically at http://localhost:8501.

Kunal Dev Sahu
Repository: github.com/kunaldevsahu/movieAI