README.md

---
title: Dressify - Production-Ready Outfit Recommendation
emoji: 🏆
colorFrom: purple
colorTo: green
sdk: gradio
sdk_version: "5.44.1"
app_file: app.py
pinned: false
---

# Dressify - Production-Ready Outfit Recommendation System

A **research-grade, self-contained** outfit recommendation service that automatically downloads the Polyvore dataset, trains state-of-the-art models, and provides a sophisticated Gradio interface for wardrobe uploads and outfit generation.

## 🚀 Features

- **Self-Contained**: No external dependencies or environment variables needed
- **Auto-Dataset Preparation**: Downloads and processes Stylique/Polyvore dataset automatically
- **Research-Grade Models**: ResNet50 item embedder + ViT outfit compatibility encoder
- **Advanced Training**: Triplet loss with semi-hard negative mining, mixed precision
- **Production UI**: Gradio interface with wardrobe upload, outfit preview, and JSON export
- **REST API**: FastAPI endpoints for embedding and composition
- **Auto-Bootstrap**: Background training and model reloading

## 🏗️ Architecture

### Data Pipeline
1. **Dataset Download**: Automatically fetches Stylique/Polyvore from HF Hub
2. **Image Processing**: Unzips images.zip and organizes into structured format
3. **Split Generation**: Creates train/val/test splits (70/15/15) with deterministic RNG
4. **Triplet Mining**: Generates item triplets and outfit triplets for training

### Model Architecture
- **Item Embedder**: ResNet50 + projection head → 512D L2-normalized embeddings
- **Outfit Encoder**: Transformer encoder → outfit-level compatibility scoring
- **Loss Functions**: Triplet margin loss with cosine distance and semi-hard mining

### Training Pipeline
- Mixed precision training with channels-last memory format
- Automatic checkpointing and best model saving
- Validation metrics and early stopping
- Background training with model reloading

## 🚀 Quick Start

### 1. Deploy to Hugging Face Space
```bash
# Upload this entire folder as a Space
# The system will automatically:
# - Download Polyvore dataset
# - Prepare splits and triplets
# - Train models (if no checkpoints exist)
# - Launch Gradio UI + FastAPI
```

### 2. Local Development
```bash
# Clone and setup
git clone <repo>
cd recomendation
pip install -r requirements.txt

# Launch app (auto-downloads dataset)
python app.py
```

## 📁 Project Structure

```
recomendation/
├── app.py                       # FastAPI + Gradio app (main entry)
├── inference.py                 # Inference service with model loading
├── models/
│   ├── resnet_embedder.py      # ResNet50 + projection head
│   └── vit_outfit.py           # Transformer encoder for outfits
├── data/
│   └── polyvore.py             # PyTorch datasets for training
├── scripts/
│   └── prepare_polyvore.py     # Dataset preparation and splits
├── utils/
│   ├── data_fetch.py           # HF dataset downloader
│   ├── transforms.py            # Image transforms
│   └── export.py               # Model export utilities
├── train_resnet.py              # ResNet training script
├── train_vit_triplet.py        # ViT triplet training script
├── requirements.txt             # Dependencies
├── Dockerfile                   # Container deployment
└── README.md                    # This file
```

## 🎯 Model Performance

### Expected Metrics (Research-Grade)
- **Item Embedder**: Triplet accuracy > 85%, validation loss < 0.1
- **Outfit Encoder**: Compatibility AUC > 0.8, precision > 0.75
- **Inference Speed**: < 100ms per outfit on GPU, < 500ms on CPU

### Training Time
- **Item Embedder**: ~2-4 hours on L4 GPU (full dataset)
- **Outfit Encoder**: ~1-2 hours on L4 GPU (with precomputed embeddings)

## 🎨 Gradio Interface

### Features
- **Wardrobe Upload**: Multi-file drag & drop with previews
- **Outfit Generation**: Top-N recommendations with compatibility scores
- **Preview Stitching**: Visual outfit composition
- **JSON Export**: Structured data for integration
- **Training Monitor**: Real-time training progress and metrics
- **Status Dashboard**: Bootstrap and training status

### Usage Flow
1. Upload wardrobe images (minimum 4 items recommended)
2. Set context (occasion, weather, style preferences)
3. Generate outfits (default: top-3)
4. View stitched previews and download JSON

## 🔌 API Endpoints

### FastAPI Server
```bash
# Health check
GET /health

# Image embedding
POST /embed
{
  "images": ["base64_image_1", "base64_image_2"]
}

# Outfit composition
POST /compose
{
  "items": [
    {"id": "item_1", "embedding": [0.1, 0.2, ...], "category": "upper"},
    {"id": "item_2", "embedding": [0.3, 0.4, ...], "category": "bottom"}
  ],
  "context": {"occasion": "casual", "num_outfits": 3}
}

# Model artifacts
GET /artifacts
```

## 🚀 Deployment

### Hugging Face Space
1. Upload this folder as a Space
2. Set Space type to "Gradio"
3. The system auto-bootstraps on first run
4. Models train automatically if no checkpoints exist
5. UI becomes available once training completes

### Docker
```bash
# Build and run
docker build -t dressify .
docker run -p 7860:7860 -p 8000:8000 dressify

# Access
# Gradio: http://localhost:7860
# FastAPI: http://localhost:8000
```

## 📈 Training & Evaluation

### Training Commands
```bash
# Quick training (3 epochs each)
# This runs automatically on Space startup

# Manual training
python train_resnet.py --data_root data/Polyvore --epochs 20
python train_vit_triplet.py --data_root data/Polyvore --epochs 30
```

### Evaluation Metrics
- **Item Level**: Triplet accuracy, embedding quality, retrieval metrics
- **Outfit Level**: Compatibility AUC, precision/recall, diversity scores
- **System Level**: Inference latency, memory usage, throughput

## 🔬 Research Features

### Advanced Training
- Semi-hard negative mining for better triplet selection
- Mixed precision training with autocast
- Channels-last memory format for CUDA optimization
- Curriculum learning with difficulty progression

### Model Variants
- **Standard**: ResNet50 + medium transformer (balanced)
- **Research**: ResNet101 + large transformer (high performance)

## 🤝 Integration

### Next.js + Supabase
```typescript
// Upload wardrobe
const uploadWardrobe = async (images: File[]) => {
  const formData = new FormData();
  images.forEach(img => formData.append('images', img));
  
  const response = await fetch('/api/wardrobe/upload', {
    method: 'POST',
    body: formData
  });
  
  return response.json();
};

// Generate outfits
const generateOutfits = async (wardrobe: WardrobeItem[]) => {
  const response = await fetch('/api/outfits/generate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ wardrobe, context: { occasion: 'casual' } })
  });
  
  return response.json();
};
```

### Database Schema
```sql
-- User wardrobe table
CREATE TABLE user_wardrobe (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id),
  image_url TEXT NOT NULL,
  category TEXT,
  embedding VECTOR(512),
  created_at TIMESTAMP DEFAULT NOW()
);

-- Outfit recommendations
CREATE TABLE outfit_recommendations (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id),
  outfit_items JSONB NOT NULL,
  compatibility_score FLOAT,
  context JSONB,
  created_at TIMESTAMP DEFAULT NOW()
);

-- RLS policies
ALTER TABLE user_wardrobe ENABLE ROW LEVEL SECURITY;
ALTER TABLE outfit_recommendations ENABLE ROW LEVEL SECURITY;

CREATE POLICY "Users can view own wardrobe" ON user_wardrobe
  FOR SELECT USING (auth.uid() = user_id);

CREATE POLICY "Users can insert own wardrobe" ON user_wardrobe
  FOR INSERT WITH CHECK (auth.uid() = user_id);
```

## 🧪 Testing

### Smoke Tests
```bash
# Dataset preparation
python scripts/prepare_polyvore.py --root data/Polyvore --random_split

# Training loops
python train_resnet.py --epochs 1 --batch_size 8
python train_vit_triplet.py --epochs 1 --batch_size 4
```

## 📚 References

- **Dataset**: [Stylique/Polyvore](https://huggingface.co/datasets/Stylique/Polyvore)
- **Reference Space**: [Stylique/recomendation](https://huggingface.co/spaces/Stylique/recomendation)
- **Research Papers**: Triplet loss, transformer encoders, outfit compatibility

## 📄 License

MIT License - see LICENSE file for details.

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## 📞 Support

- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Documentation**: This README + inline code comments

---

**Built with ❤️ for the fashion AI community**