Skip to content

README.md

Latest commit

 

History

History
256 lines (187 loc) · 8.28 KB

README.md

File metadata and controls

256 lines (187 loc) · 8.28 KB

🎬 RecoStream: Emotion + Behavior Aware Recommendation System

RecoStream is a full‑stack, Netflix‑style recommendation system that provides personalized movie suggestions based on a user’s preferences, behaviors, and the semantic meaning of their inputs.

It combines Sentence‑BERT semantic search with Collaborative Filtering (Surprise) and a feedback loop (like/dislike/click). The project exposes a FastAPI backend and a modern React frontend.

Linkedin Post Link: https://www.linkedin.com/posts/ganasekhark_machinelearning-recommendationsystems-ai-activity-7374888182980653056-ozCa?utm_source=share&utm_medium=member_desktop&rcm=ACoAAD89BZIBRKWU64_jsUAxvhPir2TtHKAUOXY

📌 Features

Module Description
👤 User Auth Secure login/signup using hashed passwords and JWT tokens
📽 Movie Recommender Semantic similarity via Sentence-BERT + genre filtering
📊 Collaborative Filtering Learns from user likes/dislikes/clicks using Surprise KNN
🧠 Emotion Awareness Recommends based on user tone: e.g., "I want a feel-good sci-fi movie"
🔁 Feedback Loop Logs "like", "dislike", and "click" feedback for model improvement
🚀 Scalable Backend FastAPI backend with modular architecture
💬 Explainability "Because you liked Interstellar and it had a sci-fi genre..."

⚙️ Tech Stack

Layer Tools
Frontend React (Vite, Tailwind, Framer Motion, Axios)
Backend FastAPI, SQLAlchemy, JWT, Pydantic
Recommender Sentence-BERT, Surprise (Collaborative Filtering), Vowpal Wabbit (RL)
Storage Local files (JSON/NumPy/FAISS index)

📁 Project Structure

RecoStream/
├── backend/
│   └── app/
│       ├── main.py                 # FastAPI entrypoint
│       ├── database.py             # DB connection
│       ├── models.py               # ORM models (User, Feedback)
│       ├── schemas.py              # Pydantic schemas
│       ├── recommender.py          # BERT/FAISS, incremental index update
│       ├── hybrid.py               # (Optional) hybrid logic
│       └── routers/
│           ├── user.py             # Signup API
│           ├── auth.py             # Login/auth API
│           ├── recommendation.py   # Recommendation API (single endpoint)
│           └── feedback.py         # Like/Dislike/Click endpoints
├── frontend/
│   ├── index.html
│   └── src/
│       ├── main.jsx
│       ├── utils/api.js            # Axios, endpoints, poster helpers
│       ├── contexts/               # Auth, Toast, Profile contexts
│       ├── components/             # MovieCard, MovieModal, MovieGrid, Layout
│       └── pages/                  # Home, Search, Genre, Profile, Login, Signup
├── requirements.txt                # Python dependencies (install with conda)
├── .env                            # Backend environment variables
├── DockerFile
├── docker-compose.yml
├── build-and-deploy.sh
├── init.sql
├── .env.docker                        
└── README.md

🧱 System Architecture

recommendation_architecture

🚀 Local Development Setup

The commands below assume you are in the project root: RecoStream/.

1) Prerequisites

  • Anaconda/Miniconda installed (for the recostream environment)
  • Node.js 18+

2) Create and activate the conda environment

conda create -n recostream python=3.10 -y
conda activate recostream

3) Install backend dependencies (via conda)

Use conda to install dependencies from requirements.txt.

conda activate recostream
conda install --file requirements.txt -c conda-forge -y
# If any packages are missing on conda, you can fallback to pip:
# pip install -r requirements.txt

4) Configure backend environment variables

SECRET_KEY=your_secret_key
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=60
# Add any other keys required by your app

Create this .env file at backend/app/.env or load using your preferred config strategy.

5) Run the backend (from project root)

conda activate recostream
uvicorn backend.app.main:app --reload

The API will be available at: http://127.0.0.1:8000

Interactive docs: http://127.0.0.1:8000/docs

6) Run the frontend (in a second terminal)

conda activate recostream
cd frontend
npm install
npm run dev

By default Vite will start on: http://localhost:5173

Docker Deployment

For quick setup using Docker and Docker Compose:

# Build and start all services
docker-compose up --build

# Access the app
# - Frontend: http://localhost:5173
# - API docs: http://localhost:8000/docs

To Stop Services:

docker-compose down

use the optional deployment script for advanced management:

./build-and-deploy.sh build
./build-and-deploy.sh prod

✅ Current Capabilities

  • ✅ User Signup/Login (JWT)
  • ✅ BERT-based recommendations
  • ✅ Feedback logging (like/dislike/click)
  • ✅ Collaborative Filtering with Surprise
  • ✅ Feedback-based learning
  • ✅ Modular FastAPI backend

🧪 Example API Usage

POST /recommend/

{
  "user_input": "I like sci-fi space movies"
}

Response

[
  {"title": "Interstellar", "score": 0.401},
  {"title": "Spaceman", "score": 0.323},
  {"title": "Shutter Island", "score": 0.182}
]

🧠 Future Work (Planned)

Feature Status
🤖 Reinforcement Learning (VW) 🚧 In Progress
📈 Dynamic CF Retraining ✅ Done
🧾 Movie-to-ID Mapping ✅ Done
🎯 Learnable Ranking (BERT + CF) ✅ Hybrid done
🧍 User Clustering 🔜 Planned
📱 Frontend UI (React) ✅ Implemented
🛡️ OAuth + Refresh Tokens 🔜 Planned

🎯 Roadmap

  • ✅ Integrate Vowpal Wabbit into /bandit_recommend route
  • ✅ Track real-time feedback for Bandit reward learning
  • ⏳ Retrain VW model incrementally on new interactions
  • 🔮 Add visual analytics (feedback trends, popular genres)
  • 📲 Build mobile-ready frontend with personalized dashboards

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss your ideas.

📄 License

This project is open-source under the MIT License.

✨ Inspiration

🔧 Troubleshooting

  • CORS errors during local dev

    • Ensure the FastAPI CORS middleware allows http://localhost:5173.

  • Missing posters

    • The frontend uses poster_path returned by the backend. If a movie has no poster, a placeholder is shown.

  • Profile shows movie ID instead of title

    • Ensure the backend feedback stats endpoint returns movie_title and movie_year for each feedback entry (join with your movie dataset or store these values at feedback time).

  • FAISS index updates

    • Add new movies to the source JSON used by recommender.py and call the update function (e.g., expose an admin route that calls update_faiss_index() to append to the index without full rebuild).

Inspired by Netflix, Spotify, and real-world hybrid recommender systems with:

  • NLP + emotion modeling
  • Collaborative filtering
  • Online learning (bandits)

💬 Built with passion for learning how recommendation systems like Netflix actually work —
blending machine learning, software engineering, and personalization.