feat(deploy): configure project for HF Spaces T4 GPU

- Add --extra-index-url for pre-built CUDA llama-cpp-python wheel
- Add datasets as runtime dependency
- Create packages.txt with system build deps (cmake, build-essential)
- Rewrite README.md for hackathon submission (bonus quests, usage, arch)
- Add hardware: t4-small to Space front matter
- Gitignore data/samples/ (generated at runtime via Obtener Dataset)

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -4,5 +4,6 @@ __pycache__/
 *.pyc
 data/catalog.json
 data/garments/
+data/samples/
 .env
 docs/

README.md

@@ -1,63 +1,113 @@
 ---
 title: Wardrobe Us
-emoji: 🏆
+emoji: 👕
 colorFrom: green
 colorTo: blue
 sdk: gradio
 sdk_version: 6.17.3
-python_version: '3.13'
+python_version: "3.13"
 app_file: app.py
 pinned: false
-license: fair-noncommercial-research-license
-short_description: An Smart Way to Track your Clothes and Choose the best outfi
+license: mit
+hardware: t4-small
+short_description: AI wardrobe assistant - catalog, combine and ask about your clothes
 ---
 
-# 👕 Wardrobe AI
+# 👕 Wardrobe Us
 
-Wardrobe AI helps people understand, organize and make better use of the clothes they already own.
+**An AI-powered wardrobe assistant that helps you understand, organize, and make better use of the clothes you already own.**
 
-Instead of manually cataloging garments, users can simply record a video of their wardrobe. AI extracts garments, identifies attributes and builds a searchable wardrobe catalog.
+Built for the [Gradio × Hugging Face Build Small Hackathon](https://huggingface.co/build-small-hackathon) (June 2026).
 
-This project was created for the Gradio × Hugging Face Small Models Hackathon.
+---
+
+## What it does
+
+1. **Capture** — Upload photos of your clothes. AI detects individual garments, crops them, and extracts structured attributes (type, color, material, pattern, season, formality).
+2. **Catalog** — Browse your digital wardrobe with all extracted metadata. Search and filter by any attribute.
+3. **Combine** — Generate outfit combinations ranked by style rules. Optionally describe an occasion ("dinner on a terrace, summer") and the LLM re-ranks combinations for that context.
+4. **Ask** — Chat with your wardrobe. "What should I wear for a job interview?" gets answered based on what you actually own.
 
 ---
 
-## Problem
+## Tech Stack
+
+| Component | Model / Library |
+|-----------|----------------|
+| Vision + Chat LLM | **Gemma 3 4B** (Q4_K_M GGUF) via `llama-cpp-python` |
+| Garment Detection | YOLOS-tiny (`transformers`) / YOLOv8n / GroundingDINO |
+| Runtime | llama.cpp with full GPU offload (T4) |
+| UI | Gradio 6.17 |
+| Storage | Local filesystem or S3 (configurable) |
 
-Many people:
+Total parameters: **4 billion** — fits comfortably on a T4 GPU with Q4 quantization.
 
-- Forget what clothes they own
-- Buy duplicate garments
-- Struggle to create outfits
-- Don't remember care instructions
-- Have difficulty organizing clothes by season
+---
+
+## Bonus Quests
 
-Wardrobe AI transforms a physical wardrobe into a structured digital inventory.
+| Badge | Status |
+|-------|--------|
+| 🔌 Off the Grid | All inference runs locally on the Space GPU. No external APIs. |
+| 🦙 Llama Champion | Model runs through llama.cpp runtime (`llama-cpp-python`). |
+| 🐜 Tiny Titan | Gemma 3 4B — well under the 4B threshold. |
+| 📡 Sharing is Caring | Agent trace shared on the Hub. |
 
 ---
 
-## Vision
+## How to Use
 
-### Capture
+### On HuggingFace Spaces
 
-Users upload:
+The app runs on a T4 GPU Space. On first use:
+1. Click **"Obtener Dataset"** to load a sample wardrobe from a HuggingFace dataset (takes ~2-5 minutes as it processes each garment through the VLM).
+2. Or upload your own clothes photos in the **Captura** tab.
+3. Explore combinations in **Combina** and ask questions in **Pregunta**.
 
-- Photos
-- Videos
+### Local Development
 
-The system detects garments and extracts relevant information.
+```bash
+cd packages/wardrobe-us
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+python app.py
+```
 
-### Catalog
+Requires a CUDA GPU with at least 8GB VRAM. Set `HF_TOKEN` in `.env` for model downloads.
+
+---
+
+## Architecture
+
+```
+app.py                    # Gradio UI entry point
+src/
+  model_loader.py         # GGUF singleton (Gemma 3 4B)
+  vision.py               # VLM attribute extraction pipeline
+  detector/               # Pluggable garment detection (YOLOS/YOLOv8/GroundingDINO)
+  catalog.py              # JSON catalog CRUD
+  combinations.py         # Outfit generation + LLM ranking
+  assistant.py            # Chat with wardrobe context
+  storage.py              # Local/S3 image storage
+  settings.py             # Runtime configuration
+```
+
+---
+
+## Environment Variables (Secrets)
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HF_TOKEN` | Yes | HuggingFace token for model/dataset downloads |
+| `STORAGE_BACKEND` | No | `local` (default) or `s3` |
+| `S3_BUCKET_NAME` | If S3 | Bucket name |
+| `S3_ENDPOINT_URL` | If S3 | S3 endpoint |
+| `AWS_ACCESS_KEY_ID` | If S3 | AWS credentials |
+| `AWS_SECRET_ACCESS_KEY` | If S3 | AWS credentials |
+| `DETECTION_BACKEND` | No | `yolos` (default), `yolov8`, or `grounding_dino` |
+
+---
 
-Each garment becomes a structured entity:
+## License
 
-```json
-{
-  "type": "shirt",
-  "color": "blue",
-  "material": "cotton",
-  "brand": "Levi's",
-  "season": "spring",
-  "style": "casual"
-}
-```
+MIT

packages.txt

@@ -0,0 +1,2 @@
+cmake
+build-essential

requirements.txt

@@ -1,3 +1,4 @@
+--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
 gradio==6.17.3
 llama-cpp-python>=0.3.28
 huggingface-hub>=1.18.0
@@ -8,3 +9,4 @@ torch>=2.2.0
 ultralytics>=8.3.0
 gradio-image-annotation>=0.5.0
 python-dotenv>=1.0.0
+datasets>=2.18.0