Planwise Recommendation System

🌟 Overview

Planwise is an AI-powered recommendation platform that helps users discover personalized plans in Madrid based on their preferences and location. Our system combines multiple advanced machine learning techniques to deliver recommendations that are accurate, diverse, and tailored to each individual user.

🚀 Features

• Personalized Recommendations: Get place suggestions that match your unique interests
• Location Awareness: Discover places within comfortable travel distance
• Multi-model Architecture: Leverages ensemble learning for superior recommendation quality
• Category Diversity: Balanced recommendations across different categories
• Seamless Integration: API-driven architecture with multiple frontends

📋 Project Structure

The project consists of two main components:

recommendation-system/
├── api/                # FastAPI backend service
├── reco/               # Core recommendation engine
│   ├── planwise/       # Model implementation and streamlit app
│   └── tests/          # Test suite
└── docs/               # Project documentation

🛠️ Getting Started

To run Planwise locally, you'll need to start two separate components:

1. API Service

The API provides recommendation endpoints and database access.

# Navigate to the API directory
cd api

# Set up using Docker
docker compose -f docker-compose.dev.yml up -d --build

# API will be available at http://localhost:8080

For detailed API setup instructions, see the API README.

2. Streamlit Application

The Streamlit app provides a user-friendly interface to interact with the system.

# Navigate to the planwise directory
cd reco/planwise

# Install dependencies
pip install -r requirements.txt

# Run the app
streamlit run app.py

# Streamlit interface will be available at http://localhost:8501

🧠 How It Works

Planwise uses a hybrid ensemble of recommendation models:

1. Autoencoder Recommender: Deep learning model that reconstructs user preferences
2. SVD Recommender: Collaborative filtering using matrix factorization
3. Transfer Learning Recommender: Leverages patterns from movie domain to place recommendations
4. Madrid Embeddings Recommender: Location-specific semantic understanding
5. Ensemble Recommender: Meta-model that combines all approaches for optimal results

📚 Documentation

For comprehensive documentation, please visit our GitHub Pages documentation site.

Key documentation sections:

• System Architecture
• Model Documentation
• API Reference
• Development Guide

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting pull requests.

📄 License

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