README.md

metadata

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

# 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

# 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

# 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

# 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

# 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

// 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

-- 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

# 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
• Reference Space: 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