{"id":31579172,"url":"https://github.com/xbants/recommendation-api","last_synced_at":"2026-04-29T22:38:46.996Z","repository":{"id":317243085,"uuid":"1066571691","full_name":"XBanTs/recommendation-api","owner":"XBanTs","description":"🎬 Intelligent movie recommendation system with FastAPI backend, Streamlit frontend, and collaborative filtering ML. Rate movies, get personalized suggestions, and enjoy automatic model retraining.","archived":false,"fork":false,"pushed_at":"2025-09-29T18:12:15.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T19:35:39.281Z","etag":null,"topics":["fastapi","machine-learning","movie-recommedation","python3","scikit-learn","streamlit"],"latest_commit_sha":null,"homepage":"https://recommendation-api.streamlit.app/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/XBanTs.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T17:05:27.000Z","updated_at":"2025-09-29T18:16:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"e5e961f6-4f6f-4fc2-b583-123973cc689c","html_url":"https://github.com/XBanTs/recommendation-api","commit_stats":null,"previous_names":["xbants/recommendation-api"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/XBanTs/recommendation-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XBanTs%2Frecommendation-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XBanTs%2Frecommendation-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XBanTs%2Frecommendation-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XBanTs%2Frecommendation-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/XBanTs","download_url":"https://codeload.github.com/XBanTs/recommendation-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/XBanTs%2Frecommendation-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278518148,"owners_count":26000176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","machine-learning","movie-recommedation","python3","scikit-learn","streamlit"],"created_at":"2025-10-05T20:47:42.573Z","updated_at":"2025-10-05T20:47:50.213Z","avatar_url":"https://github.com/XBanTs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎬 Movie Recommendation System\n\nA sophisticated, full-stack movie recommendation application built with **FastAPI** and **Streamlit** that leverages collaborative filtering and machine learning to provide personalized movie recommendations. The system features automatic model retraining, real-time recommendations, and an intuitive web interface.\n\n## ✨ Features\n\n### 🎯 Core Functionality\n- **Intelligent Recommendations**: Advanced collaborative filtering using cosine similarity\n- **Real-time Rating System**: Users can rate movies to improve recommendation accuracy\n- **Auto-Retraining**: ML model automatically retrains when new data is added\n- **Movie Management**: Complete CRUD operations for movies\n- **Interactive Web UI**: Beautiful Streamlit frontend for easy interaction\n\n### 🚀 Technical Highlights\n- **Async FastAPI Backend**: High-performance REST API with automatic documentation\n- **SQLAlchemy ORM**: Robust database management with async support\n- **Scikit-learn ML**: Professional-grade machine learning algorithms\n- **Model Persistence**: Efficient model caching with joblib\n- **Database Flexibility**: Supports both PostgreSQL and SQLite\n\n## 🏗️ Architecture\n\n```\nMovie-Recommendation-Application/\n├── app/                    # FastAPI backend\n│   ├── main.py            # API endpoints and business logic\n│   ├── models.py          # Database models (Movie, Rating)\n│   ├── schemas.py         # Pydantic schemas for validation\n│   ├── db.py              # Database configuration\n│   └── create_tables.py   # Database initialization\n├── frontend/              # Streamlit web interface\n│   └── app.py            # Interactive UI for recommendations and ratings\n├── recommender/           # Machine learning module\n│   └── train_model.py    # Collaborative filtering implementation\n├── images/               # Application screenshots\n└── requirements.txt      # Python dependencies\n```\n\n## 📸 Application Screenshots\n\n### Get Movie Recommendations\n![Movie Recommendations Interface](images/movrecommender1.png)\n*The recommendation interface allows users to select a movie and get personalized suggestions based on collaborative filtering*\n\n### Rate Movies\n![Movie Rating Interface](images/movrecommender2.png)\n*Users can rate movies on a scale of 0-5 stars, which automatically retrains the ML model for better recommendations*\n\n## 🛠️ Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| **Backend API** | FastAPI | High-performance async REST API |\n| **Frontend** | Streamlit | Interactive web interface |\n| **Database** | SQLAlchemy + PostgreSQL/SQLite | Data persistence and ORM |\n| **Machine Learning** | Scikit-learn | Collaborative filtering algorithms |\n| **Model Storage** | Joblib | Efficient model serialization |\n| **Validation** | Pydantic | Request/response validation |\n\n## 🚀 Quick Start Guide\n\n### Prerequisites\n- Python 3.8 or higher\n- pip package manager\n- PostgreSQL (optional - SQLite works too)\n\n### 1. Clone and Setup\n```bash\n# Clone the repository\ngit clone \u003crepository-url\u003e\ncd Movie-Recommendation-Application\n\n# Create virtual environment (recommended)\npython -m venv movie_rec_env\nsource movie_rec_env/bin/activate  # On Windows: movie_rec_env\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 2. Database Setup\n```bash\n# Initialize the database with sample data\npython init_db.py\n```\n\n### 3. Start the FastAPI Backend\n```bash\n# Run the API server\nuvicorn app.main:app --reload --host 0.0.0.0 --port 8000\n```\nThe API will be available at `http://localhost:8000`\n- **Interactive API Docs**: `http://localhost:8000/docs` (Swagger UI)\n- **Alternative Docs**: `http://localhost:8000/redoc`\n\n### 4. Launch the Streamlit Frontend\n```bash\n# In a new terminal, start the web interface\nstreamlit run frontend/app.py\n```\nThe web application will open automatically at `http://localhost:8501`\n\n## 📚 API Documentation\n\n### 🎬 Movies Endpoints\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/movies/` | Retrieve all movies |\n| `GET` | `/movies/{movie_id}` | Get specific movie by ID |\n| `POST` | `/movies/` | Add a new movie |\n| `DELETE` | `/movies/{movie_id}` | Delete a movie |\n\n### ⭐ Ratings Endpoint\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `POST` | `/rate/` | Submit a movie rating (triggers model retraining) |\n\n### 🎯 Recommendations Endpoint\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/recommend/{movie}?top_n={number}` | Get movie recommendations |\n\n### Example API Usage\n```bash\n# Get recommendations for \"Toy Story\"\ncurl \"http://localhost:8000/recommend/Toy%20Story?top_n=5\"\n\n# Add a rating\ncurl -X POST \"http://localhost:8000/rate/\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"user_id\": 1, \"movie_id\": 1, \"rating\": 4.5}'\n```\n\n## 🧠 How the ML Algorithm Works\n\n### 1. **Data Collection**\n- User ratings are stored in a relational database\n- Each rating links a user, movie, and score (0-5 stars)\n\n### 2. **Collaborative Filtering**\n- Creates a user-movie matrix from rating data\n- Uses cosine similarity to find movies with similar rating patterns\n- Handles sparse data with zero-filling for unrated movies\n\n### 3. **Recommendation Generation**\n- Calculates similarity scores between movies\n- Returns top-N most similar movies to the input\n- Excludes the input movie from recommendations\n\n### 4. **Automatic Retraining**\n- Model retrains whenever new movies or ratings are added\n- Ensures recommendations stay current with user preferences\n- Uses joblib for efficient model persistence\n\n## 🎮 Using the Application\n\n### Web Interface (Recommended)\n1. **Start both servers** (FastAPI + Streamlit)\n2. **Open** `http://localhost:8501` in your browser\n3. **Get Recommendations**: Select a movie and click \"Get Recommendations\"\n4. **Rate Movies**: Choose a movie, set your rating, and submit\n\n### API Interface\n1. **Visit** `http://localhost:8000/docs` for interactive API documentation\n2. **Test endpoints** directly in the Swagger UI\n3. **Integrate** with your own applications using the REST API\n\n## 🔧 Configuration\n\n### Database Configuration\nEdit `app/db.py` to configure your database:\n```python\n# For PostgreSQL\nDATABASE_URL = \"postgresql+asyncpg://user:password@localhost/moviedb\"\n\n# For SQLite (default)\nDATABASE_URL = \"sqlite+aiosqlite:///./movies.db\"\n```\n\n### Model Parameters\nAdjust recommendation parameters in `app/main.py`:\n```python\n# Change default number of recommendations\n@app.get(\"/recommend/{movie}\")\ndef recommend(movie: str, top_n: int = 5):  # Default changed to 5\n```\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**\"Model not found\" error**\n```bash\n# Retrain the model manually\npython -c \"import asyncio; from recommender.train_model import train_model; asyncio.run(train_model())\"\n```\n\n**Database connection issues**\n```bash\n# Reinitialize the database\npython init_db.py\n```\n\n**Port already in use**\n```bash\n# Use different ports\nuvicorn app.main:app --port 8001\nstreamlit run frontend/app.py --server.port 8502\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## 🙏 Acknowledgments\n\n- **FastAPI** for the excellent async web framework\n- **Streamlit** for making beautiful web apps simple\n- **Scikit-learn** for robust machine learning algorithms\n- **SQLAlchemy** for powerful database ORM capabilities\n\n---\n\n**Built with ❤️ for movie enthusiasts and ML practitioners**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbants%2Frecommendation-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxbants%2Frecommendation-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxbants%2Frecommendation-api/lists"}