🎬 Movie Knowledge Graph

A sophisticated movie recommendation system built with FalkorDB graph database, NLP (spaCy), and Streamlit for intelligent, relationship-based movie discovery.

🌟 Features

• Graph-Based Recommendations: Leverages FalkorDB to find movies through actor, director, and genre relationships
• NLP-Powered Analysis: Uses spaCy for entity extraction and semantic analysis of movie plots
• Multiple Recommendation Strategies:
  • Similar movies based on shared attributes
  • Genre-based filtering with rating thresholds
  • Actor and director filmographies
  • Actor collaboration discovery
  • Network exploration (degrees of separation)
• Interactive Web Interface: Clean, modern UI built with Streamlit
• Real-Time Search: Fast graph queries for instant results

🏗️ Architecture

┌─────────────────┐
│  TMDb API       │
│  (Data Source)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────┐
│ Data Collector  │────▶│ NLP Processor│
│ (API Integration)│    │ (spaCy)      │
└────────┬────────┘     └──────┬───────┘
         │                     │
         ▼                     ▼
┌─────────────────────────────────┐
│     FalkorDB Graph Database     │
│  (Movies, Actors, Directors)    │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────┐     ┌──────────────┐
│  Recommender    │────▶│  Streamlit   │
│  (Graph Queries)│     │  (Frontend)  │
└─────────────────┘     └──────────────┘

🚀 Tech Stack

• Graph Database: FalkorDB (Redis-based graph database)
• NLP: spaCy, sentence-transformers
• Data Source: TMDb (The Movie Database) API
• Backend: Python 3.12
• Frontend: Streamlit
• Data Processing: pandas, numpy
• Visualization: plotly, networkx

📦 Installation

Prerequisites

• Python 3.12+
• Docker (for FalkorDB)
• TMDb API key (Get one free)

Setup

1. Clone the repository

git clone https://github.com/EngAdhamTamer/movie-knowledge-graph.git
cd movie-knowledge-graph

2. Create virtual environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\Activate.ps1

3. Install dependencies

pip install -r requirements.txt
python -m spacy download en_core_web_sm

4. Configure environment

cp .env.example .env
# Edit .env and add your TMDb API key

5. Start FalkorDB

docker run -p 6379:6379 -it --rm falkordb/falkordb:latest

6. Populate database

python scripts/populate_graph.py --movies 30

7. Launch application

streamlit run app.py

Visit http://localhost:8501 in your browser!

📊 Graph Schema

// Nodes
(:Movie {movie_id, title, year, overview, rating, runtime, budget, revenue})
(:Actor {actor_id, name})
(:Director {director_id, name})
(:Genre {name})

// Relationships
(Actor)-[:ACTED_IN {character}]->(Movie)
(Director)-[:DIRECTED]->(Movie)
(Movie)-[:HAS_GENRE]->(Genre)
(Movie)-[:SIMILAR_TO {score}]->(Movie)

🎯 Usage Examples

Search for Movies by Actor

from src.graph_builder import MovieGraphBuilder
from src.recommender import MovieRecommender

builder = MovieGraphBuilder()
recommender = MovieRecommender(builder)

# Get Tom Hanks movies
movies = recommender.recommend_by_actor("Tom Hanks", limit=10)

Find Similar Movies

# Find movies similar to Inception
similar = recommender.recommend_similar_movies("Inception", limit=5)

Explore Actor Networks

# Find actors connected to Leonardo DiCaprio
network = recommender.get_actor_network("Leonardo DiCaprio", depth=2)

📸 Screenshots

Home Dashboard

Shows top-rated movies and database statistics

Recommendation Engine

Find similar movies based on multiple factors

Actor Network Exploration

Discover connections between actors

🛠️ Project Structure

movie-knowledge-graph/
├── src/
│   ├── data_collector.py    # TMDb API integration
│   ├── nlp_processor.py     # NLP & embeddings
│   ├── graph_builder.py     # FalkorDB operations
│   └── recommender.py       # Recommendation algorithms
├── scripts/
│   └── populate_graph.py    # Database population
├── tests/
├── app.py                   # Streamlit interface
├── config.py                # Configuration
└── requirements.txt

🔬 Recommendation Algorithms

1. Collaborative Filtering: Based on shared actors, directors, and genres
2. Content-Based: Using NLP embeddings of plot descriptions (planned)
3. Graph-Based: Leveraging path traversal and relationship strength
4. Hybrid: Combining multiple signals for better accuracy

🚧 Future Enhancements

• User ratings and personalized recommendations
• Sentiment analysis of movie reviews
• Movie poster similarity using computer vision
• REST API with FastAPI
• Deployment to cloud (Heroku/Streamlit Cloud)
• Advanced graph visualizations with D3.js
• Topic modeling for plot analysis
• Real-time trending movies analysis

📈 Performance

• Query Speed: < 100ms for most graph queries
• Database Size: ~60 movies, 400+ actors, 60+ directors
• Scalability: Tested with up to 1000+ movies

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• TMDb for the excellent movie data API
• FalkorDB for the powerful graph database
• spaCy for NLP capabilities
• Streamlit for the amazing web framework

👤 Author

Your Name

• GitHub: @EngAdhamTamer
• LinkedIn: Your LinkedIn

📞 Contact

Project Link: https://github.com/EngAdhamTamer/movie-knowledge-graph

---

⭐ Star this repo if you find it helpful!