README.md

metadata

title: Movie Recommender
emoji: 🤖
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: '1.0'
app_file: app.main
pinned: false

🎬 Movie Recommender System (FastAPI + LangGraph + FAISS)

This project is an AI-powered movie recommender system.
It uses FAISS vector search, local embeddings, and LLMs (via OpenRouter) to recommend movies in any language.

The pipeline:

1. Detects the language of the user query.
2. Translates the query into English.
3. Retrieves similar movies using embeddings + FAISS.
4. Generates natural language explanations with an LLM.
5. Translates the explanations back into the user’s language.

---

✨ Features

• Multilingual support (query in any language 🌍).
• Fast similarity search with FAISS.
• Local embeddings with MiniLM.
• Explanations powered by OpenRouter LLMs.
• Modular pipeline built with LangGraph.

---

🛠️ Tech Stack

• Backend: FastAPI
• Vector DB: FAISS
• Embeddings: sentence-transformers/all-MiniLM-L6-v2 (local)
• Orchestration: LangChain + LangGraph
• LLM: OpenRouter (Meta LLaMA Scout free by default)
• Deployment: Docker / Hugging Face Spaces

---

📂 Project Structure

.
├── app/
│   ├── main.py           # FastAPI entry point
│   ├── recommender.py    # Core recommender logic
│   ├── graph.py          # LangGraph workflow
│   └── utils.py          # Helper functions
├── data/                 # Movies dataset
├── faiss_index/          # Prebuilt FAISS index + metadata
├── prepare_data.py       # Script to build FAISS index
├── requirements.txt
├── .env                  # API keys (not committed)
├── .gitignore
└── README.md

---

🚀 Getting Started

1. Clone & Setup

git clone https://github.com/your-username/movie-recommender.git
cd movie-recommender

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2. Environment Variables

Create a .env file in the project root:

OPENROUTER=your_openrouter_api_key

3. Prepare FAISS Index

If not already included:

python prepare_data.py

This builds:

• faiss_index/movies_index.faiss
• faiss_index/movies.pkl

4. Run FastAPI App

uvicorn app.main:app --reload

Backend will start at:
👉 http://127.0.0.1:8000

Interactive API docs at:
👉 http://127.0.0.1:8000/docs

---

📌 Example Usage

Request

curl -X POST http://127.0.0.1:8000/recommend -H "Content-Type: application/json" -d '{"query": "لطفا یک فیلم فانتزی هیجان انگیز شاد بهم معرفی کن", "k": 5}'

Response

[
  {
    "title": "The Incredibles",
    "genres": "Action|Animation|Adventure",
    "overview": "A family of superheroes...",
    "explanation": "این فیلم یک ماجراجویی شاد و هیجان‌انگیز است که با درخواست شما مطابقت دارد."
  },
  ...
]

---

🐳 Deployment with Docker

Build and run locally:

docker build -t movie-recommender .
docker run -p 8000:8000 movie-recommender

For Hugging Face Spaces:

• Only /tmp is writable at runtime.
• Pre-download embeddings + FAISS index during build.

---

🧩 Next Steps

• Add user profiles for personalized recommendations.
• Support hybrid search (metadata + embeddings).
• Add Next.js frontend for a full-stack app.
• Deploy to Hugging Face Spaces.

---

📜 License

MIT License. Free to use & modify.