README.md

metadata

title: Wardrobe Backend API
sdk: gradio
pinned: false

Wardrobe Backend API

Production backend for Wardrobe Assistant, designed to run on Hugging Face Spaces.

The service provides:

• garment classification from uploaded images,
• wardrobe item persistence,
• AI outfit scoring and recommendation,
• shopping suggestion and product URL extraction,
• lightweight feedback capture for preference signals.

The API is built with FastAPI, uses SQLite for persistence, and integrates external AI providers for inference.

Architecture Summary

• Runtime: FastAPI + Uvicorn
• Storage: SQLite (persistent when /data is mounted on Hugging Face)
• Inference: Hugging Face-hosted fine-tuned Qwen model (primary); NVIDIA-hosted chat completions used as fallback (default fallback model: qwen/qwen3.5-122b-a10b)
• Retrieval: Web scraping pipeline for product discovery (Nike and Zalando logic in code)

Core modules:

• app.py: API routes, orchestration, inference calls, scraper flow
• db.py: SQLite schema and CRUD/caching helpers
• scoring.py: deterministic fallback scoring logic
• fashion_ai/: recommendation service and ranking support

Repository Contents for Deployment

Upload this backend directory as your Hugging Face Space source (or sync it via Git):

• app.py
• db.py
• scoring.py
• scraper.py
• zalando_scraper.py
• requirements.txt
• packages.txt
• fashion_ai/

Hugging Face Deployment

1. Create a new Space.
2. Select Gradio SDK.
3. Use CPU hardware (inference is delegated to external APIs).
4. Enable Persistent Storage if you want data durability across restarts.
5. Add the required environment variables.
6. Deploy the backend files.

Required Environment Variables

• HF_API_KEY: API key for the primary Hugging Face-hosted fine-tuned Qwen model.
• NVIDIA_API_KEY: API key for the NVIDIA inference fallback.

Common Optional Environment Variables

Inference and reliability:

• HF_MODEL_ID (default: your fine-tuned Qwen model on Hugging Face)
• HF_INVOKE_URL (default: Hugging Face Inference API endpoint for the fine-tuned model)
• NVIDIA_MODEL_ID (fallback; default: qwen/qwen3.5-122b-a10b)
• NVIDIA_INVOKE_URL (fallback; default: https://integrate.api.nvidia.com/v1/chat/completions)
• OPENAI_MODEL_ID (secondary fallback; OpenAI-compatible model ID if both primary and NVIDIA fallback are unavailable)
• OPENAI_API_KEY (secondary fallback; required only if OpenAI fallback is enabled)
• NVIDIA_MAX_TOKENS (default: 16384)
• NVIDIA_REASONING_MAX_TOKENS (default: 16384)
• NVIDIA_TEMPERATURE (default: 0.60)
• NVIDIA_TOP_P (default: 0.95)
• NVIDIA_TIMEOUT_SECONDS (default: 180)
• NVIDIA_MAX_RETRIES (default: 3)
• NVIDIA_RETRY_BACKOFF_SECONDS (default: 0.8)
• NVIDIA_ENABLE_THINKING (default: false)
• NVIDIA_FALLBACK_MODEL_IDS (comma-separated fallback list)

Matching and cache:

• MATCHING_RESULT_CACHE_MAX (default: 500)
• MATCHING_RESULT_CACHE_TTL_SECONDS (default: 86400)

Scraper and planner:

• SCRAPER_DEFAULT_STORE (default: nike)
• SCRAPER_PLANNER_MODEL_ID (default: nvidia/nemotron-3-nano-omni-30b-a3b-reasoning)
• SCRAPER_PLANNER_MAX_TOKENS (default: 800)

Database path:

• DB_PATH (optional override)

When DB_PATH is not provided, the app uses:

• /data/wardrobe.db if /data exists,
• otherwise ./wardrobe.db.

Inference Priority

The service resolves inference providers in the following order:

1. Primary - Fine-tuned Qwen model hosted on Hugging Face (HF_MODEL_ID).
2. Fallback 1 - NVIDIA-hosted chat completions (NVIDIA_MODEL_ID, default: qwen/qwen3.5-122b-a10b). Used when the primary model is unavailable or returns an error.
3. Fallback 2 - OpenAI-compatible model (OPENAI_MODEL_ID). Used when both the primary and NVIDIA fallback are unavailable.

AI-powered routes return a service-level error only when all three providers are exhausted or unconfigured.

API Endpoints

Health and service metadata:

• GET /
• GET /health

Wardrobe ingestion and CRUD:

• POST /classify
• POST /upload
• GET /items
• PUT /items/{item_id}
• DELETE /items/{item_id}

Outfit intelligence:

• POST /ai/score-outfit
• POST /ai/gap-analysis
• POST /ai/recommend-outfits
• POST /feedback

Shopping and scraping:

• POST /product-urls
• POST /suggestions
• POST /api/suggestions
• POST /scraper/recommend
• GET /scraper
• GET /image-proxy

Local Development

1. Install dependencies

pip install -r requirements.txt

2. Export environment variables

Linux/macOS:

export HF_API_KEY=""
export NVIDIA_API_KEY=""        # fallback
export OPENAI_API_KEY=""        # secondary fallback, optional

Windows PowerShell:

$env:HF_API_KEY = ""
$env:NVIDIA_API_KEY = ""        # fallback
$env:OPENAI_API_KEY = ""        # secondary fallback, optional

3. Run the API

python app.py

The service starts on http://0.0.0.0:7860.

Smoke Checks

Health:

curl "http://127.0.0.1:7860/health"

Image classification:

curl -X POST "http://127.0.0.1:7860/classify" \
   -F "image=@/path/to/garment.jpg"

Expected post-deploy health signal:

• hf_api_configured should be "True" (primary model).
• nvidia_api_configured should be "True" (fallback model).