🎌 Anime Recommender System

A sophisticated hybrid recommendation system that combines collaborative filtering and content-based filtering to deliver personalized anime recommendations

🚀 Live Demo • 📖 Documentation • 🤝 Contributing

---

✨ Features

🎯 Smart Recommendations Hybrid filtering approach Collaborative + Content-based Personalized suggestions Real-time inference	🔧 MLOps Ready End-to-end pipelines Experiment tracking Model versioning Automated deployment
📊 Data Management DVC integration Version control Cloud storage Pipeline automation	🚀 Production Ready FastAPI backend Docker support Cloud deployment Monitoring & logging

---

🏗️ Architecture

graph TD
    A[Raw Data] --> B[Data Ingestion]
    B --> C[Preprocessing]
    C --> D[Feature Engineering]
    D --> E[Model Training]
    E --> F[Model Evaluation]
    F --> G[Model Registry]
    G --> H[FastAPI Service]
    H --> I[Render Deployment]
    
    J[DVC] --> B
    K[Comet ML] --> E
    L[GitHub] --> I

Loading

---

📁 Project Structure

anime-recommender/
│
├── 📊 data/                     # Dataset management
│   ├── raw/                     # Original datasets
│   ├── processed/               # Cleaned datasets
│   └── features/                # Engineered features
│
├── 📓 notebooks/                # Research & experimentation
│   ├── eda.ipynb              # Exploratory data analysis
│   ├── modeling.ipynb         # Model development
│   └── evaluation.ipynb       # Performance analysis
│
├── 🔧 src/                      # Source code
│   ├── ingestion/              # Data loading pipelines
│   ├── processing/             # Data preprocessing
│   ├── model/                  # ML model implementations
│   ├── prediction/             # Inference pipelines
│   └── utils/                  # Helper functions
│
├── 🌐 app/                      # Web application
│   ├── main.py                 # FastAPI application
│   ├── models.py               # Pydantic models
│   └── templates/              # HTML templates
│
├── 🐳 docker/                   # Containerization
├── 📋 requirements.txt          # Python dependencies
├── 🔄 dvc.yaml                  # DVC pipeline configuration
├── ⚙️ .render.yaml              # Render deployment config
└── 📖 README.md                 # Project documentation

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• Git
• DVC (optional, for data versioning)

Installation

1. Clone the repository

   git clone https://github.com/yourusername/anime-recommender.git
   cd anime-recommender

2. Create virtual environment

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Run the application

   uvicorn app.main:app --reload

5. Visit the API

   http://localhost:8000
   

---

📡 API Reference

Get Recommendations

POST /recommend

Request Body:

{
  "user_id": 123,
  "num_recommendations": 5
}

Response:

{
  "user_id": 123,
  "recommendations": [
    {
      "anime_id": 5114,
      "title": "Fullmetal Alchemist: Brotherhood",
      "score": 9.1,
      "genres": ["Action", "Adventure", "Drama"]
    },
    {
      "anime_id": 1535,
      "title": "Death Note",
      "score": 8.9,
      "genres": ["Supernatural", "Thriller"]
    }
  ],
  "generated_at": "2025-06-22T10:30:00Z"
}

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "model_version": "v2.1.0"
}

---

🛠️ Technology Stack

Category	Technologies
🤖 Machine Learning
🌐 Backend
📊 MLOps
☁️ Cloud & Deployment
🔧 DevOps

---

🧪 Model Performance

Metric	Collaborative Filtering	Content-Based	Hybrid Model
RMSE	0.87	0.92	0.82
MAE	0.68	0.73	0.64
Precision@5	0.74	0.71	0.78
Recall@5	0.69	0.67	0.73

---

🚀 Deployment

Local Development

# Start development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Docker Deployment

# Build image
docker build -t anime-recommender .

# Run container
docker run -p 8000:8000 anime-recommender

Render Deployment

The application is configured for automatic deployment on Render using .render.yaml:

services:
  - type: web
    name: anime-recommender-api
    env: python
    buildCommand: pip install -r requirements.txt
    startCommand: uvicorn app.main:app --host 0.0.0.0 --port 10000
    plan: free

---

🔄 MLOps Pipeline

# Run complete pipeline
dvc repro

# Track experiments
dvc exp run

# Push data to remote
dvc push

Pipeline Stages

1. Data Ingestion - Load and validate raw data
2. Preprocessing - Clean and transform data
3. Feature Engineering - Create model features
4. Training - Train recommendation models
5. Evaluation - Assess model performance
6. Deployment - Deploy best model to production

---

📊 Dataset

The system uses anime rating data with the following structure:

• Users: 73,515 unique users
• Anime: 12,294 unique anime titles
• Ratings: 7,813,737 user-anime ratings
• Features: Genres, studios, year, episode count

---

🤝 Contributing

We welcome contributions! Please follow these steps:

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

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest

# Run linting
flake8 src/

# Format code
black src/

---

📝 License

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

---

🙏 Acknowledgements

• MyAnimeList for providing the anime dataset
• Comet ML for experiment tracking capabilities
• Render for free-tier cloud deployment
• DVC for seamless data version control
• FastAPI community for excellent documentation
• Surprise library for collaborative filtering algorithms

---

📞 Contact & Support

Found this project helpful? Give it a ⭐!

---

_{Built with ❤️ by [Your Name] | © 2025}