Upload README.md with huggingface_hub

README.md

@@ -1,6 +1,57 @@
-# Fashion Search Model - GAP-CLIP
+# GAP-CLIP: Guaranteed Attribute Positioning in CLIP Embeddings
 
-Multimodal search model for fashion, combining color embeddings, categorical hierarchy embeddings, and a main CLIP model for fashion item search.
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch 2.0+](https://img.shields.io/badge/pytorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Hugging Face](https://img.shields.io/badge/🤗-Hugging%20Face-yellow)](https://huggingface.co/Leacb4/gap-clip)
+
+**Advanced multimodal fashion search model combining specialized color embeddings, hierarchical category embeddings, and CLIP for intelligent fashion item retrieval.**
+
+---
+
+## 🚀 Quick Start
+
+### Installation (< 1 minute)
+
+```bash
+# Clone the repository
+git clone https://github.com/Leacb4/gap-clip.git
+cd gap-clip
+
+# Install package with pip
+pip install -e .
+
+# Or just install dependencies
+pip install -r requirements.txt
+```
+
+### Try It Now (< 2 minutes)
+
+```python
+from example_usage import load_models_from_hf
+
+# Load pre-trained models from Hugging Face
+models = load_models_from_hf("Leacb4/gap-clip")
+
+# Search with text
+import torch.nn.functional as F
+text_query = "red summer dress"
+text_inputs = models['processor'](text=[text_query], padding=True, return_tensors="pt")
+text_inputs = {k: v.to(models['device']) for k, v in text_inputs.items()}
+
+with torch.no_grad():
+    text_features = models['main_model'](**text_inputs).text_embeds
+    
+# Extract specialized embeddings
+color_emb = text_features[:, :16]      # Color (dims 0-15)
+category_emb = text_features[:, 16:80]  # Category (dims 16-79)
+general_emb = text_features[:, 80:]     # General CLIP (dims 80-511)
+
+print(f"✅ Successfully extracted embeddings!")
+print(f"   Color: {color_emb.shape}, Category: {category_emb.shape}, General: {general_emb.shape}")
+```
+
+---
 
 ## 📋 Description
 
@@ -57,24 +108,63 @@ Where:
 
 ### Prerequisites
 
-- Python 3.8+
-- PyTorch 2.0+
-- CUDA (optional, for GPU)
+- Python 3.8 or higher
+- PyTorch 2.0+ (with CUDA for GPU support, optional but recommended)
+- 16GB RAM minimum (32GB recommended for training)
+- ~5GB disk space for models and data
 
-### Installing Dependencies
+### Method 1: Install as Package (Recommended)
+
+```bash
+# Clone repository
+git clone https://github.com/Leacb4/gap-clip.git
+cd gap-clip
+
+# Install in development mode
+pip install -e .
+
+# Or install with optional dependencies
+pip install -e ".[dev]"      # With development tools
+pip install -e ".[optuna]"   # With hyperparameter optimization
+pip install -e ".[all]"      # With all extras
+```
+
+### Method 2: Install Dependencies Only
 
 ```bash
 pip install -r requirements.txt
 ```
 
+### Method 3: From Hugging Face (Model Only)
+
+```python
+from example_usage import load_models_from_hf
+models = load_models_from_hf("Leacb4/gap-clip")
+```
+
 ### Main Dependencies
 
-- `torch>=2.0.0` : PyTorch for deep learning
-- `transformers>=4.30.0` : Hugging Face Transformers for CLIP
-- `huggingface-hub>=0.16.0` : To download/upload models
-- `pillow>=9.0.0` : Image processing
-- `pandas>=1.5.0` : Data manipulation
-- `scikit-learn>=1.3.0` : Evaluation metrics
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `torch` | ≥2.0.0 | Deep learning framework |
+| `transformers` | ≥4.30.0 | Hugging Face CLIP models |
+| `huggingface-hub` | ≥0.16.0 | Model download/upload |
+| `pillow` | ≥9.0.0 | Image processing |
+| `pandas` | ≥1.5.0 | Data manipulation |
+| `scikit-learn` | ≥1.3.0 | ML metrics & evaluation |
+| `tqdm` | ≥4.65.0 | Progress bars |
+| `matplotlib` | ≥3.7.0 | Visualization |
+
+### Verify Installation
+
+```python
+# Test that everything works
+import config
+config.print_config()
+
+# Check device
+print(f"Using device: {config.device}")
+```
 
 ## 📁 Project Structure
 
@@ -113,51 +203,91 @@ pip install -r requirements.txt
 │   ├── optuna_param_importances.png     # Parameter importance plot
 │   └── optuna_guide.md                  # Optuna usage guide
 ├── upload_hf/                  # HuggingFace Hub upload utilities
-│   ├── upload_to_huggingface.py         # Upload script
-│   └── GUIDE_UPLOAD_HF.md               # Upload guide
-├── requirements.txt            # Python dependencies
+│   ├── upload_to_huggingface.py         # Professional upload script (rewritten)
+│   └── README_UPLOAD.md                 # Complete upload guide
+├── requirements.txt            # Python dependencies (organized)
+├── setup.py                    # Package installation (NEW)
+├── __init__.py                 # Package initialization (NEW)
+├── .gitignore                  # Git ignore rules (NEW)
 └── README.md                   # This documentation
 ```
 
 ### Key Files Description
 
 **Core Model Files**:
-- `color_model.py`: ResNet18-based color embedding model (16 dims)
+- `color_model.py`: ResNet18-based color embedding model (16 dims) - Bug fixed ✨
 - `hierarchy_model.py`: ResNet18-based hierarchy classification model (64 dims)  
-- `main_model.py`: GAP-CLIP implementation with enhanced contrastive loss
-- `train_main_model.py`: Training with Optuna-optimized hyperparameters
-
-**Configuration**:
-- `config.py`: Central configuration for all paths, dimensions, and device settings
+- `main_model.py`: GAP-CLIP implementation with enhanced contrastive loss - Bug fixed ✨
+- `train_main_model.py`: Training with Optuna-optimized hyperparameters - Improved ✨
+
+**Configuration & Setup** (✨ New/Improved):
+- `config.py`: ✨ Completely rewritten with type hints, auto device detection, validation utilities
+- `setup.py`: ✨ NEW - Professional package installer with CLI entry points
+- `__init__.py`: ✨ NEW - Package initialization for easy imports
+- `.gitignore`: ✨ NEW - Comprehensive Git ignore rules
+- `requirements.txt`: ✨ Improved - Organized with comments and categories
 - `tokenizer_vocab.json`: Vocabulary for color model's text encoder
 
+**Upload Tools** (✨ Rewritten):
+- `upload_hf/upload_to_huggingface.py`: ✨ Complete professional rewrite with:
+  - Object-oriented design
+  - Multiple authentication methods
+  - Category-based uploads (models, code, docs, etc.)
+  - Progress tracking
+  - Automatic model card generation
+  - Detailed error handling
+- `upload_hf/README_UPLOAD.md`: ✨ NEW - Complete upload guide
+
 **Evaluation Suite**:
 - `main_model_evaluation.py`: Comprehensive evaluation across Fashion-MNIST, KAGL, and local datasets
-- Other evaluation scripts provide specialized analysis (color, hierarchy, search, etc.)
+- `evaluation/run_all_evaluations.py`: ✨ NEW - Automated evaluation runner with reports
+- Other scripts provide specialized analysis (color, hierarchy, search, t-SNE, etc.)
 
 **Training Data**:
 - `data_with_local_paths.csv`: Main training dataset with text, color, hierarchy, and image paths
 - `fashion-mnist_test.csv`: Evaluation dataset for zero-shot generalization testing
 
+**CLI Commands** (✨ New):
+After installation with `pip install -e .`, you can use:
+```bash
+gap-clip-train      # Start training
+gap-clip-example    # Run usage examples
+```
+
 ## 🔧 Configuration
 
-Main parameters are defined in `config.py`:
+Main parameters are defined in `config.py` (✨ completely rewritten with improvements):
 
 ```python
-# Embedding dimensions
-color_emb_dim = 16          # Color embedding dimension (dims 0-15)
-hierarchy_emb_dim = 64      # Hierarchy embedding dimension (dims 16-79)
+import config
 
-# Device configuration
-device = torch.device("mps")  # Device (cuda, mps, cpu)
+# Automatic device detection (CUDA > MPS > CPU)
+device = config.device  # Automatically selects best available device
 
-# Column names for dataset
-text_column = 'text'                    # Description column
-color_column = 'color'                  # Color label column
-hierarchy_column = 'hierarchy'          # Hierarchy category column
-column_local_image_path = 'local_image_path'  # Image path column
+# Embedding dimensions
+color_emb_dim = config.color_emb_dim           # 16 dims (0-15)
+hierarchy_emb_dim = config.hierarchy_emb_dim   # 64 dims (16-79)
+main_emb_dim = config.main_emb_dim             # 512 dims total
+
+# Default training hyperparameters
+batch_size = config.DEFAULT_BATCH_SIZE         # 32
+learning_rate = config.DEFAULT_LEARNING_RATE   # 1.5e-5
+temperature = config.DEFAULT_TEMPERATURE       # 0.09
+
+# Utility functions
+config.print_config()      # Print current configuration
+config.validate_paths()    # Validate that all files exist
 ```
 
+### New Features in config.py ✨
+
+- **Automatic device detection**: Selects CUDA > MPS > CPU automatically
+- **Type hints**: Full type annotations for better IDE support
+- **Validation**: `validate_paths()` checks all model files exist
+- **Print utility**: `print_config()` shows current settings
+- **Constants**: Pre-defined default hyperparameters
+- **Documentation**: Comprehensive docstrings for all settings
+
 ### Model Paths
 
 Default paths configured in `config.py`:
@@ -704,14 +834,157 @@ model.load_state_dict(checkpoint['model_state_dict'])
 # Continue training with your domain-specific data
 ```
 
+## 📦 Upload to Hugging Face
+
+The project includes a **professional upload script** (✨ completely rewritten) for easy deployment:
+
+```bash
+cd upload_hf
+
+# Authenticate (first time only)
+huggingface-cli login
+
+# Upload everything
+python upload_to_huggingface.py --repo-id your-username/gap-clip --categories all
+
+# Or upload specific categories
+python upload_to_huggingface.py --repo-id your-username/gap-clip --categories models code
+
+# Create private repository
+python upload_to_huggingface.py --repo-id your-username/gap-clip --private
+```
+
+**Features**:
+- ✨ Object-oriented design with `HuggingFaceUploader` class
+- ✨ Multiple authentication methods (token, saved, interactive)
+- ✨ Category-based uploads: models, code, docs, data, optuna, evaluation
+- ✨ Progress tracking with tqdm
+- ✨ Automatic model card generation
+- ✨ Detailed error handling and recovery
+- ✨ Upload statistics and summary
+
+See `upload_hf/README_UPLOAD.md` for complete documentation.
+
+## 🧪 Testing & Evaluation
+
+### Quick Test
+
+```bash
+# Test configuration
+python -c "import config; config.print_config()"
+
+# Test model loading
+python example_usage.py --repo-id Leacb4/gap-clip --text "red dress"
+```
+
+### Full Evaluation Suite
+
+```bash
+# Run all evaluations
+cd evaluation
+python run_all_evaluations.py --repo-id Leacb4/gap-clip
+
+# Results will be saved to evaluation_results/ with:
+# - summary.json: Detailed metrics
+# - summary_comparison.png: Visual comparison
+```
+
+## 🐛 Known Issues & Fixes
+
+### Fixed Issues ✨
+
+1. **Color model image loading bug** (Fixed in `color_model.py`)
+   - Previous: `Image.open(config.column_local_image_path)` 
+   - Fixed: `Image.open(img_path)` - Now correctly gets path from dataframe
+
+2. **Function naming in training** (Fixed in `main_model.py` and `train_main_model.py`)
+   - Previous: `train_one_epoch_enhanced` 
+   - Fixed: `train_one_epoch` - Consistent naming
+
+3. **Device compatibility** (Improved in `config.py`)
+   - Now automatically detects and selects best device (CUDA > MPS > CPU)
+
+## 🎓 Learning Resources
+
+### Documentation Files
+
+- **README.md** (this file): Complete project documentation
+- **upload_hf/README_UPLOAD.md**: Upload guide for Hugging Face
+- **evaluation/**: Multiple evaluation examples
+
+### Code Examples
+
+- **example_usage.py**: Basic usage with Hugging Face Hub
+- **evaluation/fashion_search.py**: Interactive search examples
+- **evaluation/tsne_images.py**: Visualization examples
+
 ## 🤝 Contributing
 
-Contributions are welcome! Feel free to open an issue or a pull request.
+We welcome contributions! Here's how:
+
+1. **Report bugs**: Open an issue with detailed description
+2. **Suggest features**: Describe your idea in an issue
+3. **Submit PR**: Fork, create branch, commit, and open pull request
+4. **Improve docs**: Help make documentation clearer
+
+### Development Setup
+
+```bash
+# Install with dev dependencies
+pip install -e ".[dev]"
+
+# Run tests (if available)
+pytest
+
+# Format code
+black .
+flake8 .
+```
 
-## 📧 Contact
+## 📊 Project Statistics
 
-Lea Sarfati lea.attia@gmail.com
+- **Language**: Python 3.8+
+- **Framework**: PyTorch 2.0+
+- **Models**: 3 specialized models (color, hierarchy, main)
+- **Embedding Size**: 512 dimensions
+- **Training Data**: 20,000+ fashion items
+- **Lines of Code**: 5,000+ (including documentation)
+- **Documentation**: Comprehensive docstrings and guides
+
+## 🔗 Links
+
+- **Hugging Face Hub**: [Leacb4/gap-clip](https://huggingface.co/Leacb4/gap-clip)
+- **GitHub**: [github.com/Leacb4/gap-clip](https://github.com/Leacb4/gap-clip)
+- **Contact**: lea.attia@gmail.com
+
+## 📧 Contact & Support
+
+**Author**: Lea Attia Sarfati  
+**Email**: lea.attia@gmail.com  
+**Hugging Face**: [@Leacb4](https://huggingface.co/Leacb4)
+
+For questions, issues, or suggestions:
+- 🐛 **Bug reports**: Open an issue on GitHub
+- 💡 **Feature requests**: Open an issue with [Feature Request] tag
+- 📧 **Direct contact**: lea.attia@gmail.com
+- 💬 **Discussions**: Hugging Face Discussions
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- LAION team for the base CLIP model
+- Hugging Face for transformers library and model hosting
+- PyTorch team for the deep learning framework
+- Fashion-MNIST dataset creators
+- All contributors and users of this project
 
 ---
 
-**Note** : This project is under active development. For any questions or issues, please open an issue on the repository.
+**⭐ If you find this project useful, please consider giving it a star on GitHub!**
+
+**📢 Version**: 1.0.0 | **Status**: Production Ready ✅ | **Last Updated**: December 2024