feat (wardrobe): prepare project structure and basic gradio ui

.gitignore

@@ -0,0 +1,8 @@
+models/
+.venv/
+__pycache__/
+*.pyc
+data/catalog.json
+data/garments/
+.env
+docs/

README.md

@@ -12,4 +12,52 @@ license: fair-noncommercial-research-license
 short_description: An Smart Way to Track your Clothes and Choose the best outfi
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 👕 Wardrobe AI
+
+Wardrobe AI helps people understand, organize and make better use of the clothes they 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.
+
+This project was created for the Gradio × Hugging Face Small Models Hackathon.
+
+---
+
+## Problem
+
+Many people:
+
+- Forget what clothes they own
+- Buy duplicate garments
+- Struggle to create outfits
+- Don't remember care instructions
+- Have difficulty organizing clothes by season
+
+Wardrobe AI transforms a physical wardrobe into a structured digital inventory.
+
+---
+
+## Vision
+
+### Capture
+
+Users upload:
+
+- Photos
+- Videos
+
+The system detects garments and extracts relevant information.
+
+### Catalog
+
+Each garment becomes a structured entity:
+
+```json
+{
+  "type": "shirt",
+  "color": "blue",
+  "material": "cotton",
+  "brand": "Levi's",
+  "season": "spring",
+  "style": "casual"
+}
+```

app.py

@@ -1,7 +1,95 @@
 import gradio as gr
 
-def greet(name):
-    return "Hello " + name + "!!"
 
-demo = gr.Interface(fn=greet, inputs="text", outputs="text")
-demo.launch()
+def process_video(video):
+    if video is None:
+        return "Please upload a wardrobe video."
+
+    return """
+    ✅ Video uploaded successfully.
+
+    Future pipeline:
+
+    1. Detect garments
+    2. Extract attributes
+    3. Build wardrobe catalog
+    4. Generate outfit recommendations
+    """
+
+
+def ask_assistant(question):
+    if not question:
+        return "Ask me something about your wardrobe."
+
+    return f"""
+    Question: {question}
+
+    🚧 Assistant functionality is under development.
+
+    Future capabilities:
+    - Outfit recommendations
+    - Seasonal organization
+    - Laundry instructions
+    - Garment search
+    """
+
+
+with gr.Blocks(title="Wardrobe AI") as demo:
+
+    gr.Markdown(
+        """
+        # 👕 Wardrobe AI
+
+        Turn your wardrobe into a searchable knowledge graph.
+
+        Upload a video of your clothes and let AI build a personal wardrobe catalog.
+        """
+    )
+
+    with gr.Tab("Capture"):
+        video_input = gr.Video(
+            label="Wardrobe Video"
+        )
+
+        capture_btn = gr.Button("Analyze Wardrobe")
+
+        capture_output = gr.Markdown()
+
+        capture_btn.click(
+            process_video,
+            inputs=video_input,
+            outputs=capture_output
+        )
+
+    with gr.Tab("Assistant"):
+
+        question = gr.Textbox(
+            label="Ask your wardrobe",
+            placeholder="What should I wear for a casual dinner?"
+        )
+
+        ask_btn = gr.Button("Ask")
+
+        answer = gr.Markdown()
+
+        ask_btn.click(
+            ask_assistant,
+            inputs=question,
+            outputs=answer
+        )
+
+    with gr.Accordion("Project Vision", open=False):
+        gr.Markdown(
+            """
+            Wardrobe AI aims to:
+
+            - Detect garments from photos and videos
+            - Extract structured clothing attributes
+            - Organize clothes by season and usage
+            - Recommend outfits
+            - Provide garment care instructions
+            - Reduce unnecessary clothing purchases
+            """
+        )
+
+demo.launch()

requirements.txt

@@ -0,0 +1,4 @@
+gradio==6.17.3
+llama-cpp-python>=0.3.28
+huggingface-hub>=1.18.0
+Pillow>=12.0.0

scripts/download_models.py

@@ -0,0 +1,89 @@
+"""Download GGUF model files for the VLM shootout.
+
+Each VLM needs two files:
+  1. The main model weights (quantized GGUF)
+  2. The multimodal projector (mmproj) that maps image embeddings
+     into the language model's embedding space.
+
+We download Q4_K_M quantizations to balance quality and VRAM usage
+on an 8GB GPU.
+"""
+
+from huggingface_hub import hf_hub_download
+from pathlib import Path
+
+MODELS_DIR = Path(__file__).parent.parent / "models"
+
+MODELS = {
+    "qwen2.5-vl-3b": {
+        "repo": "mradermacher/Qwen2.5-VL-3B-Instruct-GGUF",
+        "model_file": "Qwen2.5-VL-3B-Instruct.Q4_K_M.gguf",
+        "mmproj_file": "Qwen2.5-VL-3B-Instruct.mmproj-fp16.gguf",
+    },
+    "smolvlm-2b": {
+        "repo": "ggml-org/SmolVLM-Instruct-GGUF",
+        "model_file": "SmolVLM-Instruct-Q4_K_M.gguf",
+        "mmproj_file": "mmproj-SmolVLM-Instruct-f16.gguf",
+    },
+    "gemma-3-4b": {
+        "repo": "ggml-org/gemma-3-4b-it-GGUF",
+        "model_file": "gemma-3-4b-it-Q4_K_M.gguf",
+        "mmproj_file": "mmproj-gemma-3-4b-it-f16.gguf",
+    },
+}
+
+
+def download_model(name: str, info: dict) -> dict[str, Path]:
+    """Download model + mmproj files, return local paths."""
+    print(f"\n{'='*60}")
+    print(f"Downloading: {name}")
+    print(f"  Repo: {info['repo']}")
+    print(f"{'='*60}")
+
+    model_path = Path(hf_hub_download(
+        repo_id=info["repo"],
+        filename=info["model_file"],
+        local_dir=MODELS_DIR / name,
+    ))
+    print(f"  Model: {model_path} ({model_path.stat().st_size / 1e9:.2f} GB)")
+
+    mmproj_path = Path(hf_hub_download(
+        repo_id=info["repo"],
+        filename=info["mmproj_file"],
+        local_dir=MODELS_DIR / name,
+    ))
+    print(f"  Mmproj: {mmproj_path} ({mmproj_path.stat().st_size / 1e9:.2f} GB)")
+
+    return {"model": model_path, "mmproj": mmproj_path}
+
+
+def main():
+    MODELS_DIR.mkdir(parents=True, exist_ok=True)
+
+    import argparse
+    parser = argparse.ArgumentParser(description="Download VLM GGUF models")
+    parser.add_argument(
+        "--model",
+        choices=list(MODELS.keys()) + ["all"],
+        default="all",
+        help="Which model to download (default: all)",
+    )
+    args = parser.parse_args()
+
+    targets = MODELS if args.model == "all" else {args.model: MODELS[args.model]}
+
+    paths = {}
+    for name, info in targets.items():
+        paths[name] = download_model(name, info)
+
+    print(f"\n{'='*60}")
+    print("Download complete!")
+    for name, p in paths.items():
+        print(f"  {name}:")
+        print(f"    model:  {p['model']}")
+        print(f"    mmproj: {p['mmproj']}")
+    print(f"{'='*60}")
+
+
+if __name__ == "__main__":
+    main()

scripts/shootout.py

@@ -0,0 +1,245 @@
+"""VLM Shootout: compare Qwen2.5-VL-3B, SmolVLM, and Gemma 3 4B.
+
+Sends the same image + prompt to each model and measures:
+  - Response quality (valid JSON, garment count, attribute completeness)
+  - Inference speed (tokens/second)
+  - VRAM usage (peak)
+
+Usage:
+    python scripts/shootout.py --image resources/sample.jpg
+    python scripts/shootout.py --image resources/sample.jpg --model qwen2.5-vl-3b
+"""
+
+import argparse
+import json
+import time
+import subprocess
+import base64
+from pathlib import Path
+
+MODELS_DIR = Path(__file__).parent.parent / "models"
+
+PROMPT = """Analyze this image of clothing items. For EACH visible garment or accessory, return a JSON array.
+
+Each item must have these fields:
+- "type": garment type (e.g. "sweater", "shirt", "jeans", "boots", "hat", "bag")
+- "color": primary color
+- "material": fabric/material if identifiable (e.g. "knit", "denim", "leather"), otherwise "unknown"
+- "pattern": pattern type (e.g. "solid", "checkered", "striped"), otherwise "solid"
+- "season": most suitable season ("spring", "summer", "autumn", "winter", "all")
+- "formality": style level ("casual", "smart-casual", "formal")
+
+Return ONLY a valid JSON array. No markdown fences, no explanation."""
+
+MODEL_CONFIGS = {
+    "qwen2.5-vl-3b": {
+        "model_file": "Qwen2.5-VL-3B-Instruct.Q4_K_M.gguf",
+        "mmproj_file": "Qwen2.5-VL-3B-Instruct.mmproj-fp16.gguf",
+        "chat_handler": "qwen25vl",
+    },
+    "smolvlm-2b": {
+        "model_file": "SmolVLM-Instruct-Q4_K_M.gguf",
+        "mmproj_file": "mmproj-SmolVLM-Instruct-f16.gguf",
+        "chat_handler": "mtmd",
+    },
+    "gemma-3-4b": {
+        "model_file": "gemma-3-4b-it-Q4_K_M.gguf",
+        "mmproj_file": "mmproj-gemma-3-4b-it-f16.gguf",
+        "chat_handler": "mtmd",
+    },
+}
+
+
+def get_vram_usage_mb() -> float:
+    """Get current VRAM usage in MB via nvidia-smi."""
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=memory.used", "--format=csv,noheader,nounits"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return float(result.stdout.strip())
+    except Exception:
+        return 0.0
+
+
+def image_to_data_uri(image_path: str) -> str:
+    """Convert image file to base64 data URI for the OpenAI vision format."""
+    data = Path(image_path).read_bytes()
+    b64 = base64.b64encode(data).decode("utf-8")
+    suffix = Path(image_path).suffix.lower().lstrip(".")
+    mime = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"}.get(suffix, "jpeg")
+    return f"data:image/{mime};base64,{b64}"
+
+
+def load_and_test(model_name: str, config: dict, image_path: str) -> dict:
+    """Load a model, run inference, return results."""
+    from llama_cpp import Llama
+    from llama_cpp.llama_chat_format import Qwen25VLChatHandler, MtmdChatHandler
+
+    model_dir = MODELS_DIR / model_name
+    model_path = str(model_dir / config["model_file"])
+    mmproj_path = str(model_dir / config["mmproj_file"])
+
+    if not Path(model_path).exists():
+        return {"error": f"Model file not found: {model_path}"}
+    if not Path(mmproj_path).exists():
+        return {"error": f"Mmproj file not found: {mmproj_path}"}
+
+    print(f"\n--- Loading {model_name} ---")
+    vram_before = get_vram_usage_mb()
+
+    handler_cls = Qwen25VLChatHandler if config["chat_handler"] == "qwen25vl" else MtmdChatHandler
+    chat_handler = handler_cls(clip_model_path=mmproj_path)
+
+    llm = Llama(
+        model_path=model_path,
+        chat_handler=chat_handler,
+        n_gpu_layers=-1,
+        n_ctx=4096,
+        verbose=False,
+    )
+
+    vram_after_load = get_vram_usage_mb()
+    print(f"  VRAM: {vram_before:.0f} -> {vram_after_load:.0f} MB (+{vram_after_load - vram_before:.0f} MB)")
+
+    data_uri = image_to_data_uri(image_path)
+
+    messages = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "text", "text": PROMPT},
+                {"type": "image_url", "image_url": {"url": data_uri}},
+            ],
+        }
+    ]
+
+    print(f"  Running inference...")
+    start = time.perf_counter()
+
+    response = llm.create_chat_completion(
+        messages=messages,
+        max_tokens=2048,
+        temperature=0.1,
+    )
+
+    elapsed = time.perf_counter() - start
+    vram_peak = get_vram_usage_mb()
+
+    raw_text = response["choices"][0]["message"]["content"]
+    usage = response.get("usage", {})
+    completion_tokens = usage.get("completion_tokens", 0)
+    tokens_per_sec = completion_tokens / elapsed if elapsed > 0 else 0
+
+    garments = parse_json_response(raw_text)
+
+    del llm
+    del chat_handler
+    import gc
+    gc.collect()
+
+    return {
+        "model": model_name,
+        "raw_response": raw_text,
+        "garments": garments,
+        "garment_count": len(garments) if isinstance(garments, list) else 0,
+        "valid_json": isinstance(garments, list),
+        "elapsed_sec": round(elapsed, 2),
+        "completion_tokens": completion_tokens,
+        "tokens_per_sec": round(tokens_per_sec, 1),
+        "vram_model_mb": round(vram_after_load - vram_before),
+        "vram_peak_mb": round(vram_peak),
+    }
+
+
+def parse_json_response(text: str) -> list | str:
+    """Try to extract a JSON array from the model response."""
+    cleaned = text.strip()
+
+    if cleaned.startswith("```"):
+        lines = cleaned.split("\n")
+        lines = lines[1:]  # remove opening fence
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        cleaned = "\n".join(lines).strip()
+
+    try:
+        parsed = json.loads(cleaned)
+        if isinstance(parsed, list):
+            return parsed
+        if isinstance(parsed, dict):
+            return [parsed]
+        return cleaned
+    except json.JSONDecodeError:
+        start = cleaned.find("[")
+        end = cleaned.rfind("]")
+        if start != -1 and end != -1 and end > start:
+            try:
+                return json.loads(cleaned[start:end + 1])
+            except json.JSONDecodeError:
+                pass
+        return cleaned
+
+
+def print_results(results: list[dict]):
+    """Print a comparison table of all results."""
+    print(f"\n{'='*80}")
+    print("SHOOTOUT RESULTS")
+    print(f"{'='*80}")
+
+    for r in results:
+        if "error" in r:
+            print(f"\n{r['model']}: ERROR - {r['error']}")
+            continue
+
+        print(f"\n--- {r['model']} ---")
+        print(f"  Valid JSON:    {'YES' if r['valid_json'] else 'NO'}")
+        print(f"  Garments:      {r['garment_count']}")
+        print(f"  Time:          {r['elapsed_sec']}s")
+        print(f"  Tokens/sec:    {r['tokens_per_sec']}")
+        print(f"  VRAM (model):  {r['vram_model_mb']} MB")
+        print(f"  VRAM (peak):   {r['vram_peak_mb']} MB")
+
+        if r["valid_json"] and r["garments"]:
+            print(f"  First garment: {json.dumps(r['garments'][0], indent=4)}")
+
+        if not r["valid_json"]:
+            print(f"  Raw response (first 500 chars):")
+            print(f"    {r['raw_response'][:500]}")
+
+    print(f"\n{'='*80}")
+
+    results_path = Path(__file__).parent.parent / "data" / "shootout_results.json"
+    results_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(results_path, "w") as f:
+        json.dump(results, f, indent=2, ensure_ascii=False)
+    print(f"Results saved to: {results_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="VLM Shootout")
+    parser.add_argument("--image", required=True, help="Path to test image")
+    parser.add_argument(
+        "--model",
+        choices=list(MODEL_CONFIGS.keys()) + ["all"],
+        default="all",
+        help="Which model to test (default: all)",
+    )
+    args = parser.parse_args()
+
+    if not Path(args.image).exists():
+        print(f"Image not found: {args.image}")
+        return
+
+    targets = MODEL_CONFIGS if args.model == "all" else {args.model: MODEL_CONFIGS[args.model]}
+
+    results = []
+    for name, config in targets.items():
+        result = load_and_test(name, config, args.image)
+        results.append(result)
+
+    print_results(results)
+
+
+if __name__ == "__main__":
+    main()

scripts/test_gpu.py

@@ -0,0 +1,27 @@
+"""Verify llama-cpp-python is installed with GPU (CUDA) support."""
+
+import sys
+
+
+def check_gpu_support():
+    try:
+        import llama_cpp
+    except ImportError:
+        print("FAIL: llama-cpp-python is not installed")
+        sys.exit(1)
+
+    print(f"llama-cpp-python version: {llama_cpp.__version__}")
+
+    has_gpu = llama_cpp.llama_supports_gpu_offload()
+    print(f"GPU offload supported: {has_gpu}")
+
+    if not has_gpu:
+        print("FAIL: llama-cpp-python was built WITHOUT GPU support")
+        print("Reinstall with: CMAKE_ARGS=\"-DGGML_CUDA=on\" pip install llama-cpp-python --force-reinstall --no-cache-dir --no-binary llama-cpp-python")
+        sys.exit(1)
+
+    print("OK: GPU support confirmed")
+
+
+if __name__ == "__main__":
+    check_gpu_support()