🎬 CineGraph-AI — Hybrid Movie Recommendation System

Ask in plain English. Get intelligent movie recommendations powered by TF-IDF content analysis and Neo4j graph relationships.

---

🧠 Overview

CineGraph-AI is an AI-powered movie recommendation system that combines content-based filtering and graph-based relationship analysis to provide intelligent and explainable movie recommendations.

The system uses:

• TF-IDF + Cosine Similarity for content-based recommendations
• Neo4j Graph Database for relationship-based recommendations
• Groq LLaMA 3.3 for natural language understanding and recommendation explanations
• MongoDB Atlas for query logging and history tracking
• FastAPI for backend APIs
• Streamlit for an interactive user interface

Users can simply ask movie-related questions in natural language and receive relevant recommendations with AI-generated explanations.

---

🏗️ System Architecture

User Query (Natural Language)
            │
            ▼
      Groq AI Router
   (Intent Classification)
            │
     ┌──────┴──────┐
     ▼             ▼
 TF-IDF Engine   Neo4j Graph Engine
(Content-Based) (Relationship-Based)
     │             │
     └──────┬──────┘
            ▼
  Hybrid Recommendations
            ▼
     Groq Explanation
            ▼
        Streamlit UI

---

⚡ How It Works

Content-Based Recommendations

Movies are converted into text representations using:

• Overview
• Genres
• Cast
• Keywords

TF-IDF vectorization and Cosine Similarity are then used to identify movies with similar content.

Graph-Based Recommendations

Neo4j stores movies and their relationships:

(Actor)-[:ACTED_IN]->(Movie)

(Director)-[:DIRECTED]->(Movie)

(Movie)-[:IN_GENRE]->(Genre)

This enables discovery through shared actors, directors, and genres.

AI-Powered Routing

Groq LLaMA 3.3 analyzes user intent and determines whether to use:

• TF-IDF recommendation engine
• Neo4j graph engine
• Hybrid recommendation engine

The model also explains recommendations in natural language.

---

✨ Features

• Natural language movie search
• Content-based recommendations using TF-IDF
• Graph-based recommendations using Neo4j
• Hybrid recommendation engine
• AI-generated recommendation explanations
• FastAPI REST API backend
• Interactive Streamlit frontend
• MongoDB Atlas search history logging
• Explainable recommendation workflow
• Scalable graph architecture

---

📊 Dataset & Graph Statistics

Entity	Count
Movies	4,800
Actors	5,683
Directors	2,574
Genres	20
Relationships	32,000+

---

📈 Neo4j Graph Structure

Nodes

• Movie
• Actor
• Director
• Genre

Relationships

(Actor)-[:ACTED_IN]->(Movie)

(Director)-[:DIRECTED]->(Movie)

(Movie)-[:IN_GENRE]->(Genre)

---

📸 Screenshots

---

🛠️ Technology Stack

Layer	Technology
Programming Language	Python
Frontend	Streamlit
Backend	FastAPI
Machine Learning	Scikit-Learn
Content Similarity	TF-IDF
Similarity Metric	Cosine Similarity
Graph Database	Neo4j
Query Language	Cypher
AI Model	Groq LLaMA 3.3
Logging Database	MongoDB Atlas

---

📂 Project Structure

CineGraph-AI/
│
├── Screenshots/
│   ├── FastAPI-Swigger-UI.png
│   ├── FastAPI-Swigger-UI-2.png
│   ├── FastAPI-Swigger-UI-Input.png
│   ├── Streamlit-Neo4j-test.png
│   └── Streamlit-TF-IDF-test.png
│
├── data/
│   └── load_neo4j.py
│
├── model/
│   ├── preprocess.py
│   ├── recommend.py
│   ├── groq_router.py
│   └── utils.py
│
├── api/
│   └── main.py
│
├── app/
│   └── app.py
│
├── .env
├── requirements.txt
└── README.md

---

⚙️ Installation

Clone Repository

git clone https://github.com/MohomedShajith/CineGraph-AI.git

cd CineGraph-AI

Create Virtual Environment

Windows

python -m venv venv

venv\Scripts\activate

Linux / macOS

python3 -m venv venv

source venv/bin/activate

Install Dependencies

pip install -r requirements.txt

Configure Environment Variables

Create a .env file:

GROQ_API_KEY=your_groq_api_key

MONGO_URI=your_mongodb_connection_string

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

Start Neo4j

Open Neo4j Desktop and start the movie database.

Load Graph Data

python data/load_neo4j.py

Run FastAPI

uvicorn api.main:app --reload

Swagger Documentation:

http://localhost:8000/docs

Run Streamlit

streamlit run app/app.py

---

🔌 API Endpoints

Method	Endpoint	Description
GET	/recommend/{movie_title}	Hybrid recommendations
GET	/recommend/content/{movie_title}	TF-IDF recommendations
POST	/query	Execute custom Cypher query
GET	/history	View MongoDB search history
GET	/health	Application health check

---

🎯 Example Queries

Recommend movies similar to Inception

Find movies directed by Christopher Nolan

Action movies starring Tom Cruise

Science fiction movies like Interstellar

Movies featuring Leonardo DiCaprio

---

🚀 Future Improvements

• Collaborative Filtering Recommendations
• Movie Poster Integration
• Rating-Based Filtering
• Personalized User Profiles
• Graph Visualization Dashboard
• Docker Support
• Cloud Deployment
• Recommendation Feedback System

---

👨‍💻 Author

Mohomed Shajith

GitHub: https://github.com/MohomedShajith

---

⭐ Support

If you found this project useful:

• Star the repository
• Fork the project
• Share feedback and suggestions

---

Built with ❤️ using Python, Neo4j, FastAPI, Streamlit, MongoDB Atlas, and Groq AI.