🎁 Personalized Gift Recommendation Platform

A comprehensive platform that combines Natural Language Processing (sentiment analysis) and Computer Vision (hand size detection) to provide personalized gift recommendations. Built for Hacktoberfest 2025 with a focus on modularity, testing, and contributor-friendliness.

🌟 Features

🧠 NLP Module

• Custom Sentiment Analysis: Logistic Regression implemented from scratch
• Word2Vec Embeddings: Semantic understanding of text
• Tweet Processing: Specialized preprocessing for social media content

👁️ Computer Vision Module

• Hand Detection: MediaPipe-powered hand landmark detection
• Size Estimation: Intelligent hand size classification
• Visual Feedback: Real-time visualization of measurements

🎯 Recommendation Engine

• Multi-Signal Processing: Combines sentiment + hand size
• Smart Matching: Rule-based gift category mapping
• Confidence Scoring: Transparent recommendation reasoning

🖥️ Multiple Interfaces

• Streamlit Web App: Interactive web interface
• CLI Tool: Command-line interface for batch processing
• REST API: RESTful endpoints for integration

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/yourusername/gift-recommendation-platform.git
cd gift-recommendation-platform

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

Usage Examples

Web App

streamlit run app/streamlit_app.py

CLI

# Single prediction
gift-recommend --tweet "Having a great day!" --hand-image hand.jpg

# Batch processing
gift-recommend --tweets tweets.csv --hand-image hand.jpg --output results.json

Python API

from src.nlp.sentiment_model import LogisticRegression
from src.cv.hand_detector import HandDetector
from src.recommendation.engine import RecommendationEngine

# Initialize components
detector = HandDetector()
engine = RecommendationEngine(gift_db)

# Get recommendations
sentiment_score = 0.85  # From NLP pipeline
hand_size = "small"     # From CV pipeline
recommendations = engine.recommend(sentiment_score, hand_size)

🏗️ Architecture

The platform follows a modular architecture:

┌─────────────────┐    ┌─────────────────┐
│   NLP Module    │    │   CV Module     │
│                 │    │                 │
│ • Preprocessor  │    │ • Hand Detector │
│ • Embeddings    │    │ • Size Estimator│
│ • Sentiment     │    │ • Visualizer    │
└─────────┬───────┘    └─────────┬───────┘
          │                      │
          └──────────┬───────────┘
                     │
          ┌─────────────────┐
          │ Recommendation  │
          │     Engine      │
          │                 │
          │ • Gift Database │
          │ • Scoring Rules │
          │ • Explainer     │
          └─────────────────┘

For detailed architecture information, see docs/architecture.md.

📊 Dataset & Models

Training Data

• Sentiment Data: 10K+ labeled tweets
• Hand Images: 100+ images across size categories
• Gift Database: 50+ categorized gift items

Model Performance

• Sentiment Analysis: >85% accuracy
• Hand Size Detection: >90% accuracy
• End-to-End: >80% user satisfaction

🧪 Testing

# Run all tests
pytest

# Run with coverage report
pytest --cov=src tests/ --cov-report=html

# Run specific module tests
pytest tests/test_nlp/
pytest tests/test_cv/
pytest tests/test_recommendation/

📚 Documentation

• Architecture Overview: System design and components
• API Reference: Complete API documentation
• User Guide: Installation, usage, and troubleshooting
• Contributing Guide: How to contribute to the project

🤝 Contributing

We welcome contributions! This project is designed to be beginner-friendly and perfect for Hacktoberfest participation.

Ways to Contribute

• 🐛 Bug fixes: Find and fix issues
• ✨ New features: Enhance existing modules
• 📖 Documentation: Improve guides and examples
• 🧪 Testing: Add test coverage
• 🎨 UI/UX: Improve the interface

Getting Started

1. Check out our Contributing Guide
2. Look for issues labeled good first issue
3. Join discussions in GitHub Issues
4. Submit your first PR!

🛠️ Technology Stack

• Backend: Python 3.8+, NumPy, Pandas
• NLP: NLTK, Gensim (Word2Vec)
• Computer Vision: OpenCV, MediaPipe
• Web Framework: Streamlit, FastAPI
• Testing: Pytest, Coverage
• Code Quality: Black, Flake8

📈 Roadmap

• Multi-language Support: Support for additional languages
• Advanced ML Models: Deep learning improvements
• Mobile App: React Native interface
• Real-time Updates: Live recommendation updates
• Social Integration: Direct social media integration

📄 License

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

🏆 Acknowledgments

• MediaPipe Team: For excellent hand detection capabilities
• Gensim Contributors: For Word2Vec implementation
• Streamlit Team: For the amazing web framework
• Hacktoberfest: For promoting open source collaboration

📞 Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Email: [email protected]

---

Made with ❤️ for Hacktoberfest 2025

Help us make gift-giving more personal and meaningful!