Explainable Item Pairing in Fashion Domain

Master Thesis Project - University of Zurich

A fashion recommender system that uses Heterogeneous Graph Attention Networks (HGAT) to suggest compatible clothing items with explainable recommendations in pairs.

🎯 Overview

This system analyzes fashion items and their attributes to provide pairing recommendations. Using machine learning and graph neural networks, it understands the relationships between different clothing items, colors, patterns, and styles to suggest compatible combinations.

Key Features

• Intelligent Recommendations: Heterogeneous Graph Attention Network model for fashion compatibility
• Explainable AI: Understand why certain items are recommended together
• Interactive UI: Vue.js frontend for easy item selection and exploration
• Real-time Processing: FastAPI backend for fast recommendation generation
• Comprehensive Dataset: Fashion items with detailed attributes and metadata

🚀 Quick Start with Docker (Recommended)

Prerequisites

• Docker (version 20.10+)
• Docker Compose (version 2.0+)
• At least 4GB RAM available for Docker

Note for Windows users: This guide includes both Windows (PowerShell/CMD) and Linux/Mac commands. The make commands are only available on Linux/Mac systems.

Installation

1. Clone the repository

   git clone https://github.com/your-username/Explanable-Item-Pairing-in-Fashion-Domain.git
   cd "Explanable Item Pairing in Fashion Domain"

2. Quick setup

   Windows (PowerShell/CMD):

   # first time
   docker-compose up --build
   
   # after built
   docker-compose up

   Linux/Mac:

   make setup
   # or
   # firsttime
   docker-compose up --build
   
   # after built
   docker-compose up

3. Access the application

   • Frontend: http://localhost
   • Backend API: http://localhost:8000
   • API Documentation: http://localhost:8000/docs

Alternative Commands

Windows (PowerShell/CMD):

# Development mode (with hot reloading)
docker-compose -f docker-compose.dev.yml up

# View logs
docker-compose logs

# Stop services
docker-compose down

# Clean up
docker-compose down -v
docker system prune -f

Linux/Mac:

# Development mode (with hot reloading)
make dev

# View logs
make logs

# Stop services
make down

# Clean up
make clean

🛠️ Manual Setup (Alternative)

Backend Setup

1. Navigate to backend directory

   cd backend

2. Create virtual environment

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

3. Install dependencies

   pip install -r requirements.txt

4. Run the backend

   python -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Frontend Setup

1. Navigate to frontend directory

   cd frontend

2. Install dependencies

   npm install

3. Run development server

   npm run dev

4. Build for production

   npm run build

📁 Project Structure

Explanable Item Pairing in Fashion Domain/
├── backend/                          # FastAPI backend service
│   ├── data/                        # Data processing and ML models
│   │   ├── model_data/              # Trained models and datasets
│   │   ├── Enhancement.py           # Recommendation enhancement logic
│   │   └── Recommender.py           # GAT model implementation
│   ├── models/                      # Pydantic data models
│   ├── controller.py                # API endpoints
│   ├── service.py                   # Business logic
│   ├── repository.py                # Data access layer
│   └── main.py                      # FastAPI application entry point
├── frontend/                        # Vue.js frontend application
│   ├── src/
│   │   ├── components/              # Vue components
│   │   ├── views/                   # Page views
│   │   ├── services/                # API services
│   │   └── stores/                  # State management
│   ├── public/                      # Static assets
│   └── package.json                 # Node.js dependencies
├── docker-compose.yml               # Production Docker setup
├── docker-compose.dev.yml           # Development Docker setup
├── Makefile                         # Convenient commands
└── DOCKER_SETUP.md                  # Detailed Docker instructions

🤖 Machine Learning Model

Heterogeneous Graph Attention Network (HGAT)

The system uses a custom Heterogeneous Graph Attention Network to learn fashion item relationships:

• Input: Fashion items with attributes (color, pattern, type, etc.)
• Graph Structure: Items and attributes as nodes, relationships as edges
• Output: Compatibility scores between item pairs
• Explainability: Attention weights show which attributes influence recommendations

Model Features

• Multi-head attention mechanism
• Heterogeneous graph processing
• Attribute importance scoring
• Real-time inference capability

🎨 Frontend Features

User Interface

• Item Selection: Browse and select fashion items
• Recommendation Display: View compatible item suggestions
• Explanation Visualization: Understand recommendation reasoning
• Interactive Exploration: Filter and explore different categories

Technical Stack

• Vue.js 3: Progressive JavaScript framework
• Vite: Fast build tool and development server
• Pinia: State management
• Axios: HTTP client for API communication
• D3.js: Data visualization

🔧 API Endpoints

Core Endpoints

• GET / - Health check
• GET /api/test - Backend connectivity test
• POST /api/recommendations - Get item recommendations
• GET /api/items/{item_id} - Get item details
• POST /api/sessions - Create user session

Authentication

Currently configured for development with open CORS. For production deployment, implement proper authentication mechanisms.

📊 Data Requirements

Model Files

Ensure these files exist in backend/data/model_data/:

• gat_model.pt - Trained HGAT model weights
• fashion_graph.pkl - Fashion item graph structure
• node_mapping.pkl - Node ID mappings
• full_data.csv - Complete fashion dataset
• training_data.csv - Training dataset

🚀 Deployment

Docker Deployment (Recommended)

1. Production deployment

   docker-compose up -d

2. Development deployment

   docker-compose -f docker-compose.dev.yml up

See DOCKER_SETUP.md for detailed deployment instructions.

🧪 Testing

Backend Testing

cd backend
python -m pytest

Frontend Testing

cd frontend
npm run test

API Testing

Access interactive API documentation at http://localhost:8000/docs

🐛 Troubleshooting

Common Issues

1. Port conflicts: Change ports in docker-compose.yml

2. Memory issues: Increase Docker memory allocation

3. Backend import errors: If you see "ImportError: attempted relative import with no known parent package":

   # Rebuild the backend container
   docker-compose build --no-cache backend
   docker-compose up

4. Model loading errors: Verify model files in backend/data/model_data/

5. Frontend build failures: If you see npm dependency errors:

   Option 1 - Update lock file:

   # Navigate to frontend directory
   cd frontend
   # Update package-lock.json
   npm install
   # Return to root and rebuild
   cd ..
   docker-compose build --no-cache frontend

   Option 2 - Delete lock file and rebuild:

   # Remove the problematic lock file
   del frontend\package-lock.json  # Windows
   # rm frontend/package-lock.json   # Linux/Mac
   docker-compose build --no-cache frontend

6. General build failures: Try docker system prune -f and rebuild

Getting Help

1. Check application logs: docker-compose logs (or make logs on Linux/Mac)
2. Verify all dependencies are installed
3. Ensure model data files are present and accessible
4. Check Docker resources and system requirements

📄 License

This project is part of a Master's Thesis at the University of Zurich. Please contact the author for usage permissions.

---

For detailed Docker setup instructions, see DOCKER_SETUP.md.