🎬 VibeSync — Movie Mood Companion

A smart, weather-aware movie recommender built with Streamlit, TMDB, Gemini AI, and a hybrid ML engine that works great even on a brand new account.

---

🌟 Highlights

🧊 Cold Start Problem — Solved

Most recommender systems are useless until you've rated dozens of movies. VibeSync tackles the cold start problem with a multi-layered fallback strategy:

Layer	How it helps new users
🧬 NeuralNiche (Gemini AI)	Works from day one — no history needed. Just describe your mood, genre, vibe, and language and get personalised picks instantly
🎯 Similarity Engine	Content-based filtering using a pre-built cosine-similarity matrix — recommends movies based on what you pick, not what you've watched
🌤️ Weather-aware suggestions	Your local weather in Pune influences recommendations even before any personal history exists
🎲 Surprise Me	Language-filtered random discovery — useful when the user has no preference history
🤖 ML Personalisation	Kicks in once you have ≥ 2 liked/disliked entries, combining Logistic Regression + Random Forest for increasingly accurate picks as your history grows

The result: VibeSync is useful from the very first visit, and gets smarter the more you use it.

---

🗂️ Project Structure

vibesync/
├── app.py                    ← main Streamlit app
├── functions.py              ← all helpers (API, CSV, ML utilities)
├── requirements.txt
├── .streamlit/
│   └── secrets.toml          ← API keys (never commit this!)
│
├── movies_list.pkl           ← pre-built movie list
├── similarity.pkl            ← cosine-similarity matrix
├── dataset.csv               ← auto-created / refreshed via sidebar
├── watchlist.csv             ← auto-created on first use
└── viewlist.csv              ← auto-created on first use

---

⚙️ Setup

pip install -r requirements.txt
streamlit run app.py

No pkl files? No problem. On first launch the app will automatically fetch the dataset from TMDB and build both movies_list.pkl and similarity.pkl for you. This one-time setup takes ~30 seconds.

You can also run it manually beforehand:

python generate_model.py

Secrets — .streamlit/secrets.toml

[api_keys]
GEMINI_API_KEY  = "your_key"
WEATHER_API_KEY = "your_key"
TMDB_API_KEY    = "your_key"

⚠️ Never commit secrets.toml. Add it to .gitignore.

---

🧭 Features

Section	What it does
🏠 Home	Live trending, top-rated & upcoming movies from TMDB + ML-personalised picks
🎞️ Browse by Genre	Scroll all movies organised by genre
🎛️ Filter Search	Filter by language, genre, rating, and year range
🎯 Similar Movies	Cosine-similarity recommendations based on a chosen title
🎲 Surprise Me	Random picks filtered by language
🧬 NeuralNiche	Gemini AI recommendations tuned to your mood, vibe, age, culture & weather
👤 My Lists	Manage your watchlist and view your full liked/disliked history

---

🛠️ Tech Stack

• Frontend — Streamlit
• Movie Data — TMDB API
• AI Recommendations — Google Gemini (gemini-3-flash-preview)
• Weather — OpenWeatherMap API
• ML Models — Scikit-learn (TF-IDF + Logistic Regression + Random Forest)
• Similarity — Precomputed cosine-similarity matrix (pickle)

---

🔒 .gitignore (recommended)

.streamlit/secrets.toml
*.pkl
dataset.csv
watchlist.csv
viewlist.csv
__pycache__/
.env

*.pkl files are generated artifacts — they're excluded from the repo intentionally. generate_model.py rebuilds them from scratch on any machine.

---

📌 Notes

• Dataset auto-refreshes from TMDB via the 🔁 Refresh Dataset sidebar button
• Watchlist and history CSVs are created automatically on first run
• All TMDB calls include retry logic and graceful fallbacks — the app never crashes on a failed poster fetch