first

.gitignore

@@ -0,0 +1,48 @@
+# --- Python ---
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# --- Virtual environments ---
+.venv/
+venv/
+env/
+ENV/
+*.env
+.env.*
+
+# --- Jupyter / notebooks ---
+.ipynb_checkpoints
+*.ipynb
+
+# --- OS / Editor files ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# --- Logs / Caches ---
+*.log
+*.out
+*.err
+*.sqlite3
+.cache/
+.mypy_cache/
+.pytest_cache/
+coverage/
+htmlcov/
+
+# --- FAISS / Embedding intermediate dumps ---
+*.npy
+
+# --- Project specific ---
+# Keep data/ and faiss_index/ in git, but ignore temporary stuff inside them
+data/*
+faiss_index/*

Dockerfile

@@ -0,0 +1,34 @@
+# ---- Base ----
+FROM python:3.10-slim
+
+# Set workdir
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy project files (including data/ and faiss_index/)
+COPY . /app
+
+# Upgrade pip and install dependencies
+RUN pip install --upgrade pip
+RUN pip install -r requirements.txt
+
+# ---- Pre-download MiniLM embeddings at build time ----
+# The model will be stored in the default Hugging Face cache (~/.cache/huggingface)
+RUN python -c "from langchain_huggingface import HuggingFaceEmbeddings; HuggingFaceEmbeddings(model_name='sentence-transformers/all-MiniLM-L6-v2')"
+
+# ---- Copy FAISS index to /tmp at runtime ----
+# We'll copy them from /app/faiss_index in CMD, since /tmp is the only writable location in Spaces
+# We will do this in an entrypoint script
+COPY entrypoint.sh /app/entrypoint.sh
+RUN chmod +x /app/entrypoint.sh
+
+# Expose port
+EXPOSE 8000
+
+# Run entrypoint
+CMD ["/app/entrypoint.sh"]

README.md

@@ -0,0 +1,141 @@
+# 🎬 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](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2).
+- 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
+```bash
+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:
+```ini
+OPENROUTER=your_openrouter_api_key
+```
+
+### 3. Prepare FAISS Index
+If not already included:
+```bash
+python prepare_data.py
+```
+
+This builds:
+- `faiss_index/movies_index.faiss`
+- `faiss_index/movies.pkl`
+
+### 4. Run FastAPI App
+```bash
+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
+```bash
+curl -X POST http://127.0.0.1:8000/recommend -H "Content-Type: application/json" -d '{"query": "لطفا یک فیلم فانتزی هیجان انگیز شاد بهم معرفی کن", "k": 5}'
+```
+
+### Response
+```json
+[
+  {
+    "title": "The Incredibles",
+    "genres": "Action|Animation|Adventure",
+    "overview": "A family of superheroes...",
+    "explanation": "این فیلم یک ماجراجویی شاد و هیجان‌انگیز است که با درخواست شما مطابقت دارد."
+  },
+  ...
+]
+```
+
+---
+
+## 🐳 Deployment with Docker
+Build and run locally:
+```bash
+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.

app/langgraph_flow.py

@@ -0,0 +1,60 @@
+from typing import TypedDict, List, Dict, Optional
+from langgraph.graph import StateGraph, END
+from langchain.schema import Document
+
+
+from typing import TypedDict, List, Dict, Optional
+from langchain.schema import Document
+
+class State(TypedDict):
+    query: str                     # user query (any language)
+    user_lang: str                 # detected language (e.g., "es")
+    k: int                          # ✅ add this line
+    translated_query: Optional[str] # query in English
+    docs: Optional[List[Document]]
+    recommendations: Optional[List[Dict]]
+
+from langgraph.graph import StateGraph, END
+
+def build_graph(recommender):
+    graph = StateGraph(State)
+
+    # Stage 1: Detect + translate query
+    def translate_in(state: State):
+        user_lang = recommender.detect_language(state["query"])
+        translated_query = state["query"]
+        if user_lang != "en":
+            translated_query = recommender.translate(state["query"], "en")
+        return {"user_lang": user_lang, "translated_query": translated_query}
+
+    # Stage 2: Retrieval
+    def retrieve(state: State):
+        docs = recommender.search(state["translated_query"], k=state["k"] * 2)
+        return {"docs": docs}
+
+    # Stage 3: Explanation (in English)
+    def explain(state: State):
+        recs = recommender.explain(state["translated_query"], state["docs"][: state["k"]], user_lang="en")
+        return {"recommendations": recs}
+
+    # Stage 4: Translate explanations back
+    def translate_out(state: State):
+        if state["user_lang"] != "en":
+            for r in state["recommendations"]:
+                r["explanation"] = recommender.translate(r["explanation"], state["user_lang"])
+        return {"recommendations": state["recommendations"]}
+
+    # Build graph
+    graph.add_node("translate_in", translate_in)
+    graph.add_node("retrieve", retrieve)
+    graph.add_node("explain", explain)
+    graph.add_node("translate_out", translate_out)
+
+    graph.set_entry_point("translate_in")
+    graph.add_edge("translate_in", "retrieve")
+    graph.add_edge("retrieve", "explain")
+    graph.add_edge("explain", "translate_out")
+    graph.add_edge("translate_out", END)
+
+    return graph.compile()
+

app/main.py

@@ -0,0 +1,28 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.models import RecommendRequest, RecommendResponse
+from app.recommender import Recommender
+from app.langgraph_flow import build_graph
+
+app = FastAPI(title="Movie Recommender")
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # later restrict to frontend domain
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+recommender = Recommender()
+graph = build_graph(recommender)
+
+@app.post("/recommend", response_model=RecommendResponse)
+async def recommend(req: RecommendRequest):
+    state = {"query": req.query, "k": req.k}
+    result = graph.invoke(state)
+    return {"recommendations": result["recommendations"]}
+
+@app.get("/health")
+async def health():
+    return {"status": "ok"}

app/models.py

@@ -0,0 +1,19 @@
+from pydantic import BaseModel
+from typing import List, Optional
+
+class RecommendRequest(BaseModel):
+    query: str
+    k: Optional[int] = 5
+
+class Recommendation(BaseModel):
+    title: str
+    genres: str
+    overview: str
+    director: Optional[str]
+    cast: Optional[str]
+    release_date: Optional[str]
+    vote_average: Optional[float]
+    explanation: str
+
+class RecommendResponse(BaseModel):
+    recommendations: List[Recommendation]

app/recommender.py

@@ -0,0 +1,82 @@
+import os
+from langchain_community.vectorstores import FAISS
+from langchain_huggingface import HuggingFaceEmbeddings
+from langchain_openai import ChatOpenAI
+from langdetect import detect
+from dotenv import load_dotenv
+
+load_dotenv()  # loads .env into os.environ
+
+
+class Recommender:
+    def __init__(self, index_dir="faiss_index"):
+        # ✅ Embeddings (English only)
+        self.embeddings = HuggingFaceEmbeddings(
+            model_name="sentence-transformers/all-MiniLM-L6-v2"
+        )
+        self.db = FAISS.load_local(
+            index_dir, self.embeddings, allow_dangerous_deserialization=True
+        )
+
+        # ✅ OpenRouter LLM (used for explanations + translation)
+        self.llmExplanation = ChatOpenAI(
+            openai_api_key=os.environ["OPENROUTER"],
+            openai_api_base="https://openrouter.ai/api/v1",
+            model="meta-llama/llama-4-scout:free",
+            temperature=0,
+            max_tokens=512,
+        )
+        self.llmTranslation = ChatOpenAI(
+            openai_api_key=os.environ["OPENROUTER"],
+            openai_api_base="https://openrouter.ai/api/v1",
+            model="meta-llama/llama-4-scout:free",  # switch here
+            temperature=0,
+            max_tokens=512
+        )
+
+    # 🔹 Stage 1a: Language detection
+    def detect_language(self, text: str) -> str:
+        return detect(text)
+
+    # 🔹 Stage 1b + 4: Translation (to/from English)
+    def translate(self, text: str, target_lang: str = "en") -> str:
+        prompt = f"Translate this text into {target_lang}: {text}"
+        return self.llmTranslation.invoke(prompt).content
+
+    # 🔹 Stage 2: Retrieval
+    def search(self, query: str, k: int = 10):
+        return self.db.similarity_search(query, k=k)
+
+    # 🔹 Stage 3: Explanation (always in English)
+    def explain(self, query: str, docs, user_lang="en"):
+        results = []
+        for d in docs:
+            prompt = (
+                f"User request: {query}\n"
+                f"Candidate movie: {d.metadata['title']} "
+                f"({d.metadata.get('genres')}).\n"
+                f"Overview: {d.metadata.get('overview')}\n\n"
+                "Explain in one sentence why this movie could be a good recommendation "
+                "for the user’s request. Focus only on positive connections."
+            )
+            response = self.llmExplanation.invoke(prompt).content
+
+            results.append({
+                "title": d.metadata["title"],
+                "genres": d.metadata["genres"],
+                "overview": d.metadata["overview"],
+                "director": d.metadata.get("director"),
+                "cast": d.metadata.get("cast"),
+                "release_date": d.metadata.get("release_date"),
+                "vote_average": d.metadata.get("vote_average"),
+                "explanation": response,  # always English at this stage
+            })
+        return results
+
+
+
+
+
+
+
+

app/utils.py

@@ -0,0 +1,49 @@
+import os
+from transformers import AutoModel, AutoTokenizer
+import torch
+from dotenv import load_dotenv
+from langchain.schema.embeddings import Embeddings
+
+
+load_dotenv()  # ✅ make sure .env is read
+
+class GemmaEmbeddings:
+    def __init__(self, model_name="google/embeddinggemma-300m", device=None):
+        self.device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+
+        hf_token = os.environ.get("HUGGINGFACETOEN")
+        if not hf_token:
+            raise ValueError("❌ Hugging Face token not found. Please set HF_TOKEN in .env")
+
+        # ✅ Pass token when loading
+        self.tokenizer = AutoTokenizer.from_pretrained(model_name, use_auth_token=hf_token)
+        self.model = AutoModel.from_pretrained(model_name, use_auth_token=hf_token).to(self.device)
+
+    def embed(self, texts):
+        if isinstance(texts, str):
+            texts = [texts]
+
+        encodings = self.tokenizer(
+            texts, padding=True, truncation=True, return_tensors="pt"
+        ).to(self.device)
+
+        with torch.no_grad():
+            model_output = self.model(**encodings)
+
+        embeddings = model_output.last_hidden_state.mean(dim=1).cpu().numpy()
+        return embeddings.tolist()
+
+
+
+class GemmaLangChainEmbeddings(Embeddings):
+    def __init__(self, model_name="google/embeddinggemma-300m"):
+        self.gemma = GemmaEmbeddings(model_name=model_name)
+
+    def embed_query(self, text: str):
+        return self.gemma.embed(text)[0]
+
+    def embed_documents(self, texts: list[str]):
+        return self.gemma.embed(texts)
+
+
+

prepare_data.py

@@ -0,0 +1,108 @@
+'''
+import pandas as pd
+import numpy as np
+import faiss, pickle, os
+from app.utils import GemmaEmbeddings
+
+def build_index(
+    csv_path="data/movies.csv",
+    out_dir="faiss_index",
+    batch_size=32,
+    checkpoint_size=1000
+):
+    df = pd.read_csv(csv_path)
+    texts = df["overview"].fillna("").tolist()
+    total = len(texts)
+
+    os.makedirs(out_dir, exist_ok=True)
+    embedder = GemmaEmbeddings()
+
+    embeddings = []
+    start_idx = 0
+
+    # 🔹 Check for existing partial progress
+    checkpoint_file = f"{out_dir}/progress.pkl"
+    if os.path.exists(checkpoint_file):
+        with open(checkpoint_file, "rb") as f:
+            saved = pickle.load(f)
+            embeddings = saved["embeddings"]
+            start_idx = saved["next_idx"]
+        print(f"🔄 Resuming from index {start_idx}")
+
+    # 🔹 Process in batches
+    for i in range(start_idx, total, batch_size):
+        batch = texts[i:i+batch_size]
+        vectors = embedder.embed(batch)
+        embeddings.extend(vectors)
+        print(f"✅ Processed {i+len(batch)} / {total}")
+
+        # Save checkpoint every `checkpoint_size`
+        if (i + batch_size) % (10*batch_size) == 0 or (i + batch_size) >= total:
+            with open(checkpoint_file, "wb") as f:
+                pickle.dump({
+                    "embeddings": embeddings,
+                    "next_idx": i + batch_size
+                }, f)
+            print(f"💾 Saved checkpoint at {i+batch_size}")
+
+    # 🔹 Build FAISS index at the end
+    embeddings = np.array(embeddings).astype("float32")
+    dim = embeddings.shape[1]
+    index = faiss.IndexFlatL2(dim)
+    index.add(embeddings)
+
+    faiss.write_index(index, f"{out_dir}/movies_index.faiss")
+    with open(f"{out_dir}/movies.pkl", "wb") as f:
+        pickle.dump(df.to_dict(orient="records"), f)
+
+    # Remove checkpoint after success
+    if os.path.exists(checkpoint_file):
+        os.remove(checkpoint_file)
+    print("🎉 Index built successfully!")
+
+if __name__ == "__main__":
+    build_index()
+'''
+
+
+import os
+import pandas as pd
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import HuggingFaceEmbeddings
+
+def build_faiss(csv_path="data/movies.csv", out_dir="faiss_index"):
+    df = pd.read_csv(csv_path).fillna("")
+
+    texts, metadatas = [], []
+    for _, row in df.iterrows():
+        text = (
+            f"Title: {row['title']}.\n"
+            f"Overview: {row['overview']}.\n"
+            f"Genres: {row['genres']}.\n"
+            f"Director: {row['director']}.\n"
+            f"Cast: {row['cast']}."
+        )
+        texts.append(text)
+        metadatas.append({
+            "id": row["id"],
+            "title": row["title"],
+            "genres": row["genres"],
+            "overview": row["overview"],
+            "director": row["director"],
+            "cast": row["cast"],
+            "release_date": row["release_date"],
+            "vote_average": row["vote_average"],
+            "popularity": row["popularity"]
+        })
+
+    # ✅ Use local MiniLM embeddings
+    embeddings = HuggingFaceEmbeddings(model_name="sentence-transformers/all-MiniLM-L6-v2")
+
+    db = FAISS.from_texts(texts, embeddings, metadatas=metadatas)
+    os.makedirs(out_dir, exist_ok=True)
+    db.save_local(out_dir)
+    print(f"✅ Saved FAISS index with {len(df)} movies to {out_dir}")
+
+if __name__ == "__main__":
+    build_faiss("data/movies.csv")
+

requirements.txt

@@ -0,0 +1,13 @@
+fastapi==0.117.1
+uvicorn==0.37.0
+pandas==2.3.2
+faiss-cpu==1.7.4
+langchain==0.3.27
+langchain-community==0.3.30
+langchain-openai==0.3.33
+sentence-transformers==5.1.1
+python-dotenv==1.1.1
+numpy==1.26.4
+langchain_huggingface==0.3.1
+langgraph==0.6.7
+langdetect==1.0.9