Spaces:
Running
Running
File size: 5,528 Bytes
46c84fd ca9045a 46c84fd ca9045a | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | ---
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
```bash
pip install -r requirements.txt
```
### 2. Export environment variables
Linux/macOS:
```bash
export HF_API_KEY=""
export NVIDIA_API_KEY="" # fallback
export OPENAI_API_KEY="" # secondary fallback, optional
```
Windows PowerShell:
```powershell
$env:HF_API_KEY = ""
$env:NVIDIA_API_KEY = "" # fallback
$env:OPENAI_API_KEY = "" # secondary fallback, optional
```
### 3. Run the API
```bash
python app.py
```
The service starts on `http://0.0.0.0:7860`.
## Smoke Checks
Health:
```bash
curl "http://127.0.0.1:7860/health"
```
Image classification:
```bash
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).
|