Upload 11 files

.dockerignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.env
+.venv
+venv/
+ENV/
+.git/
+.gitignore
+*.md
+!README.md
+.DS_Store
+media/
+*.db
+*.db-journal
+*.log

.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+media/
+*.db
+*.db-journal
+*.log
+.DS_Store

CHECKLIST.md

@@ -0,0 +1,131 @@
+# 🎯 Deployment Checklist
+
+Use this checklist to ensure a smooth deployment to Hugging Face Spaces.
+
+## ☐ Pre-Deployment
+
+- [ ] Have a HuggingFace account (create at https://huggingface.co/join)
+- [ ] Git is installed on your machine
+- [ ] All files in `huggingface_deployment` folder are present:
+  - [ ] `app/` folder with all subfolders
+  - [ ] `main.py`
+  - [ ] `Dockerfile`
+  - [ ] `requirements.txt`
+  - [ ] `README.md` (with YAML frontmatter)
+  - [ ] `.dockerignore`
+  - [ ] `.gitignore`
+  - [ ] `LICENSE`
+
+## ☐ Create Space
+
+- [ ] Go to https://huggingface.co/new-space
+- [ ] Choose a name for your Space
+- [ ] Select **Docker** as SDK
+- [ ] Choose license: **MIT**
+- [ ] Select visibility: Public or Private
+- [ ] Click "Create Space"
+
+## ☐ Upload Files
+
+### Option A: Web UI (Drag & Drop)
+- [ ] Open your new Space page
+- [ ] Click "Files" tab
+- [ ] Drag and drop ALL files from `huggingface_deployment` folder
+- [ ] Wait for upload to complete
+
+### Option B: Git (Recommended)
+- [ ] Clone your Space: `git clone https://huggingface.co/spaces/USERNAME/SPACENAME`
+- [ ] Copy all files from `huggingface_deployment` to cloned folder
+- [ ] `git add .`
+- [ ] `git commit -m "Initial deployment"`
+- [ ] `git push`
+
+## ☐ Monitor Build
+
+- [ ] Go to your Space page
+- [ ] Click "Logs" tab
+- [ ] Watch the build progress
+- [ ] Wait for "Running" status (~5-10 minutes)
+- [ ] Check for any error messages
+
+## ☐ Test Deployment
+
+- [ ] Note your Space URL: `https://USERNAME-SPACENAME.hf.space`
+- [ ] Test health endpoint:
+  ```bash
+  curl https://USERNAME-SPACENAME.hf.space/
+  ```
+- [ ] Expected response: `{"status":"ok"}`
+- [ ] Test with a simple upload (use Postman, curl, or your frontend)
+
+## ☐ Configure (Optional)
+
+### Hardware Upgrade
+- [ ] Go to Space Settings
+- [ ] Click "Change hardware"
+- [ ] Select desired tier (T4 GPU recommended for production)
+- [ ] Confirm upgrade
+
+### Persistent Storage
+- [ ] Go to Space Settings
+- [ ] Click "Upgrade storage"
+- [ ] Select storage tier (Small = $5/month for 20GB)
+- [ ] Confirm upgrade
+
+### Environment Variables
+- [ ] Go to Space Settings
+- [ ] Add any required secrets/variables
+- [ ] Save changes
+
+## ☐ Connect Frontend
+
+- [ ] Update frontend API URL to: `https://USERNAME-SPACENAME.hf.space`
+- [ ] Test end-to-end flow:
+  - [ ] Upload images
+  - [ ] Start processing
+  - [ ] Check progress
+  - [ ] Download results
+
+## ☐ Final Checks
+
+- [ ] Space is publicly accessible (if intended)
+- [ ] API responds to all endpoints
+- [ ] Image upload works
+- [ ] Processing completes successfully
+- [ ] Download returns ZIP file
+- [ ] Cleanup happens after download
+
+## ☐ Documentation
+
+- [ ] Update your frontend repo with new API URL
+- [ ] Share your Space link with users
+- [ ] Add Space badge to your GitHub README (optional):
+  ```markdown
+  [![Open in Spaces](https://huggingface.co/datasets/huggingface/badges/raw/main/open-in-hf-spaces-sm.svg)](https://huggingface.co/spaces/USERNAME/SPACENAME)
+  ```
+
+## ☐ Monitoring
+
+- [ ] Check Space analytics (views, usage)
+- [ ] Monitor logs for errors
+- [ ] Watch resource usage in Settings
+- [ ] Set up billing alerts (if using paid tier)
+
+---
+
+## 🎉 Deployment Complete!
+
+Once all items are checked, your Image Selector Backend is live on HuggingFace Spaces!
+
+**Your API**: `https://USERNAME-SPACENAME.hf.space`
+
+**Your Space**: `https://huggingface.co/spaces/USERNAME/SPACENAME`
+
+---
+
+## 📞 Need Help?
+
+- Check `DEPLOYMENT_GUIDE.md` for detailed instructions
+- Check `QUICK_START.md` for overview
+- HF Community: https://huggingface.co/spaces
+- HF Discord: https://discord.gg/hugging-face

DEPLOYMENT_GUIDE.md

@@ -0,0 +1,161 @@
+# 🚀 Deploying to Hugging Face Spaces
+
+This guide walks you through deploying the Image Selector Backend to Hugging Face Spaces.
+
+## 📋 Prerequisites
+
+- A Hugging Face account (free): https://huggingface.co/join
+- Git installed on your machine
+
+## 🎯 Deployment Steps
+
+### 1. Create a New Space
+
+1. Go to https://huggingface.co/new-space
+2. Fill in the details:
+   - **Space name**: `image-selector-backend` (or your preferred name)
+   - **License**: MIT
+   - **Select the Space SDK**: Choose **Docker**
+   - **Space hardware**: Start with **CPU basic** (free), upgrade to **GPU** later if needed
+   - **Visibility**: Public or Private (your choice)
+3. Click **Create Space**
+
+### 2. Clone Your New Space Repository
+
+After creating the Space, you'll see instructions to clone it. Run:
+
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+```
+
+### 3. Copy Files from This Folder
+
+Copy **ALL** files and folders from this `huggingface_deployment` directory to your cloned Space repository:
+
+```bash
+# Windows PowerShell
+Copy-Item -Path ".\huggingface_deployment\*" -Destination "PATH_TO_YOUR_CLONED_SPACE\" -Recurse -Force
+```
+
+Or manually copy these files/folders:
+- `app/` (entire folder with all subfolders)
+- `main.py`
+- `requirements.txt`
+- `Dockerfile`
+- `README.md`
+- `.dockerignore`
+- `.gitignore`
+
+### 4. Push to Hugging Face
+
+```bash
+cd PATH_TO_YOUR_CLONED_SPACE
+git add .
+git commit -m "Initial deployment of Image Selector Backend"
+git push
+```
+
+### 5. Wait for Build
+
+- Hugging Face will automatically build your Docker container
+- Go to your Space page to see the build logs
+- First build takes ~5-10 minutes (downloads Python packages and models)
+- Once built, your API will be live! 🎉
+
+### 6. Test Your Deployment
+
+Your API will be available at:
+```
+https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
+```
+
+Test the health endpoint:
+```bash
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/
+```
+
+Should return: `{"status":"ok"}`
+
+## 🔧 Configuration Options
+
+### Hardware Upgrades
+
+For better performance, upgrade your Space hardware:
+- **CPU Basic** (Free): Good for testing, slow processing
+- **T4 Small** ($0.60/hr): 16GB GPU, much faster processing
+- **A10G Small** ($1.05/hr): 24GB GPU, even faster
+
+To upgrade:
+1. Go to your Space Settings
+2. Click "Change hardware"
+3. Select desired tier
+
+### Persistent Storage
+
+By default, Spaces use ephemeral storage (resets on restart).
+
+To keep data across restarts:
+1. Go to Space Settings
+2. Upgrade storage tier (starting at $5/month for 20GB)
+3. Your app will automatically use `/data` directory
+
+### Environment Variables / Secrets
+
+If you need API keys or secrets:
+1. Go to Space Settings
+2. Add Variables (public) or Secrets (private)
+3. Access in code via `os.environ.get("SECRET_NAME")`
+
+## 🎨 Connect Your Frontend
+
+Update your frontend to point to your Space URL:
+
+```javascript
+const API_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space";
+```
+
+Frontend repo: https://github.com/basilbenny1002/image-selector-front-end
+
+## 📊 Monitor Your Space
+
+- View logs: Click "Logs" tab in your Space
+- See resource usage: Settings → Hardware
+- Track visitors: Your Space page shows view count
+
+## 🐛 Troubleshooting
+
+### Build Fails
+- Check logs for specific error
+- Verify all files copied correctly
+- Ensure Dockerfile syntax is correct
+
+### API Not Responding
+- Check if Space is running (not sleeping)
+- Free tier Spaces sleep after inactivity
+- Upgrade to paid tier for always-on
+
+### Out of Memory
+- Large images or many simultaneous users
+- Upgrade to larger CPU tier or add GPU
+
+### Models Not Downloading
+- First request is slow (downloads ~500MB models)
+- Subsequent requests use cached models
+- Consider using persistent storage to keep models
+
+## 📚 Useful Resources
+
+- [HF Spaces Docs](https://huggingface.co/docs/hub/spaces)
+- [Docker Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-docker)
+- [FastAPI Docs](https://fastapi.tiangolo.com/)
+
+## 🎉 You're Done!
+
+Your Image Selector Backend is now live on Hugging Face Spaces!
+
+Share your Space:
+- Direct link: `https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME`
+- API endpoint: `https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space`
+
+Happy deploying! 🚀

Dockerfile

@@ -0,0 +1,32 @@
+# Use Python 3.10 slim image
+FROM python:3.10-slim
+
+# Set up a new user named "user" with user ID 1000
+RUN useradd -m -u 1000 user
+
+# Switch to the "user" user
+USER user
+
+# Set home to the user's home directory
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+
+# Set the working directory to the user's home directory
+WORKDIR $HOME/app
+
+# Copy requirements first for better caching
+COPY --chown=user requirements.txt .
+
+# Upgrade pip and install dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy the application code
+COPY --chown=user . .
+
+# Expose port 7860 (HuggingFace Spaces default)
+EXPOSE 7860
+
+# Run the FastAPI app with uvicorn
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Basil Benny
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

QUICK_START.md

@@ -0,0 +1,154 @@
+# 📦 HuggingFace Deployment Package - Ready to Upload!
+
+## ✅ What's Been Created
+
+This folder contains everything you need to deploy your Image Selector Backend to Hugging Face Spaces.
+
+### 📁 Folder Structure
+
+```
+huggingface_deployment/
+├── app/                          # Application code
+│   ├── __init__.py
+│   ├── api/
+│   │   ├── __init__.py
+│   │   └── routes.py            # FastAPI endpoints
+│   ├── core/
+│   │   ├── __init__.py
+│   │   └── config.py            # Settings (modified for HF)
+│   ├── repositories/
+│   │   ├── __init__.py
+│   │   └── embeddings.py        # SQLite operations
+│   └── services/
+│       ├── __init__.py
+│       └── image_selector.py    # ML logic
+├── main.py                       # FastAPI app entry point
+├── Dockerfile                    # Docker container config
+├── requirements.txt              # Python dependencies
+├── README.md                     # HF Space description (with YAML!)
+├── LICENSE                       # MIT License
+├── .dockerignore                 # Files to exclude from Docker
+├── .gitignore                    # Git ignore rules
+└── DEPLOYMENT_GUIDE.md          # Step-by-step deployment instructions
+```
+
+## 🔑 Key Modifications for HuggingFace Spaces
+
+### 1. **config.py** - Smart Storage
+- Auto-detects `/data` for persistent storage (paid tier)
+- Falls back to `/tmp` for ephemeral storage (free tier)
+- Creates directories automatically
+
+### 2. **Dockerfile** - HF Optimized
+- Uses non-root user (user ID 1000) as required by HF
+- Exposes port 7860 (HF default)
+- Proper file ownership with `--chown=user`
+- Optimized layer caching
+
+### 3. **README.md** - HF Format
+- Includes YAML frontmatter with Space metadata:
+  ```yaml
+  title: Image Selector Backend
+  emoji: 🖼️
+  sdk: docker
+  app_port: 7860
+  license: mit
+  ```
+- Full API documentation
+- Usage examples
+
+### 4. **requirements.txt**
+- Added `aesthetics-predictor` package
+- All dependencies pinned for reproducibility
+
+## 🚀 Quick Deploy Steps
+
+### Option 1: Upload via Web UI (Easiest)
+
+1. Create a new Space on HuggingFace (Docker SDK)
+2. Drag and drop ALL files from this folder
+3. Wait for build (~5-10 minutes)
+4. Done! ✨
+
+### Option 2: Git Clone & Push (Recommended)
+
+```bash
+# 1. Create Space on HuggingFace.co (choose Docker SDK)
+
+# 2. Clone your new Space
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+
+# 3. Copy all files from huggingface_deployment folder
+# (Copy everything from this folder to your cloned space folder)
+
+# 4. Push to HuggingFace
+git add .
+git commit -m "Initial deployment"
+git push
+```
+
+See **DEPLOYMENT_GUIDE.md** for detailed instructions!
+
+## 🎯 What Happens on HuggingFace
+
+1. **Build Phase**:
+   - Reads Dockerfile
+   - Installs Python 3.10
+   - Installs all pip packages
+   - Downloads ML models (~500MB)
+   - Takes ~5-10 minutes
+
+2. **Runtime**:
+   - Container starts with user ID 1000
+   - FastAPI runs on port 7860
+   - Your API is accessible at: `https://USERNAME-SPACENAME.hf.space`
+
+3. **Storage**:
+   - Free tier: Uses `/tmp` (ephemeral, resets on restart)
+   - Paid tier: Uses `/data` (persistent across restarts)
+
+## 🧪 Testing Your Deployment
+
+Once deployed, test with:
+
+```bash
+# Health check
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/
+
+# Should return: {"status":"ok"}
+```
+
+Then use your frontend or API client to upload/process images!
+
+## 💡 Tips
+
+### For Free Tier (CPU Basic)
+- ✅ Perfect for testing and demos
+- ⚠️ Processing will be slow (CPU-only)
+- ⚠️ Space sleeps after inactivity
+- ⚠️ Storage resets on restart
+
+### For Production
+- ✅ Upgrade to GPU (T4 Small at $0.60/hr)
+- ✅ Add persistent storage ($5/month for 20GB)
+- ✅ Keeps your Space always-on
+
+## 🔗 Links
+
+- **Create a Space**: https://huggingface.co/new-space
+- **HF Spaces Docs**: https://huggingface.co/docs/hub/spaces
+- **Docker Spaces Guide**: https://huggingface.co/docs/hub/spaces-sdks-docker
+- **Frontend Repo**: https://github.com/basilbenny1002/image-selector-front-end
+
+## ❓ Questions?
+
+Check DEPLOYMENT_GUIDE.md for:
+- Detailed step-by-step instructions
+- Troubleshooting common issues
+- Hardware upgrade guides
+- Monitoring and logging
+
+---
+
+**You're all set! Just upload this folder to HuggingFace Spaces and you're live! 🎉**

README.md

@@ -0,0 +1,107 @@
+---
+title: Image Selector Backend
+emoji: 🖼️
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# Image Selector Backend API
+
+A FastAPI backend for intelligent image deduplication and selection. Upload images, group similar ones using ResNet50 embeddings, and keep only the best image from each group based on aesthetics scoring.
+
+## 🚀 Features
+
+- **Smart Deduplication**: Groups similar images using deep learning embeddings
+- **Aesthetics Scoring**: Ranks images within each group using a CLIP-based aesthetics model
+- **REST API**: Simple endpoints for upload, process, progress tracking, and download
+- **Per-User Sessions**: Each user gets isolated processing and temporary storage
+- **Auto Cleanup**: Temporary files are removed after download
+
+## 📡 API Endpoints
+
+### Health Check
+```
+GET /
+```
+Returns: `{"status": "ok"}`
+
+### Upload Images
+```
+POST /upload
+```
+Form fields:
+- `user_id` (text): Your unique session ID
+- `file` (file): Image file to upload
+
+### Start Processing
+```
+POST /process
+```
+Form fields:
+- `user_id` (text): Your session ID
+- `similarity` (float, optional): Similarity threshold (default: 0.87)
+- `use_aesthetics` (bool, optional): Enable aesthetics scoring (default: true)
+
+### Check Progress
+```
+GET /progress/{user_id}
+```
+Returns processing status, percentage, and ETA.
+
+### Download Results
+```
+GET /download/{user_id}
+```
+Returns a ZIP file containing the best images from each group.
+
+## 🔧 How It Works
+
+1. **Upload**: Send images with a unique `user_id`
+2. **Process**: Trigger processing - the backend will:
+   - Generate embeddings for all images
+   - Group similar images (similarity threshold configurable)
+   - Score each image using an aesthetics model
+   - Keep the best image from each group
+3. **Download**: Retrieve a ZIP of selected images
+4. **Auto-cleanup**: All temporary files are deleted after download
+
+## 💻 Local Development
+
+```bash
+git clone <this-repo>
+cd <repo-folder>
+pip install -r requirements.txt
+uvicorn main:app --host 0.0.0.0 --port 7860
+```
+
+## 🎨 Frontend
+
+Use with the web UI:
+- [Image Selector Frontend](https://github.com/basilbenny1002/image-selector-front-end)
+
+## 📦 Tech Stack
+
+- **FastAPI**: Modern async web framework
+- **PyTorch**: Deep learning for embeddings
+- **ResNet50**: Feature extraction model
+- **CLIP**: Aesthetics prediction model
+- **SQLite**: Temporary embeddings storage
+
+## ⚠️ Notes for HuggingFace Spaces
+
+- Uses `/tmp` for ephemeral storage (free tier)
+- For persistent storage, upgrade to a paid tier and data will use `/data`
+- Model weights download on first run (~500MB for ResNet50 + aesthetics model)
+- GPU recommended for faster processing (upgrade to T4 or better)
+
+## 📄 License
+
+MIT License - see LICENSE file
+
+## 🔗 Project Origin
+
+Based on [Image-Selecter](https://github.com/basilbenny1002/Image-Selecter)

START_HERE.md

@@ -0,0 +1,199 @@
+# 🎉 DEPLOYMENT READY!
+
+## ✅ Success! Your HuggingFace Spaces deployment package is ready.
+
+### 📦 What You Have
+
+The `huggingface_deployment` folder contains **everything** needed to deploy your Image Selector Backend to Hugging Face Spaces. Just upload this entire folder!
+
+```
+huggingface_deployment/
+│
+├── 🐳 Docker Configuration
+│   ├── Dockerfile              # Container setup optimized for HF Spaces
+│   ├── .dockerignore          # Exclude unnecessary files from build
+│   └── requirements.txt       # All Python dependencies
+│
+├── 📝 Documentation
+│   ├── README.md              # Space description (with HF YAML frontmatter!)
+│   ├── DEPLOYMENT_GUIDE.md    # Detailed step-by-step deployment guide
+│   ├── QUICK_START.md         # Quick overview and tips
+│   └── CHECKLIST.md           # Deployment checklist
+│
+├── ⚙️ Application Code
+│   ├── main.py                # FastAPI entry point
+│   └── app/                   # Your application
+│       ├── api/routes.py      # REST API endpoints
+│       ├── core/config.py     # Settings (HF-optimized paths)
+│       ├── repositories/      # Database operations
+│       └── services/          # ML processing logic
+│
+└── 📄 Legal
+    ├── LICENSE                # MIT License
+    └── .gitignore            # Git ignore rules
+```
+
+---
+
+## 🚀 Next Steps (2 Minutes!)
+
+### 1️⃣ Create Your Space
+Go to: **https://huggingface.co/new-space**
+- Name: `image-selector-backend` (or your choice)
+- SDK: **Docker** ← Important!
+- License: MIT
+- Click "Create Space"
+
+### 2️⃣ Upload Files
+**Either:**
+- **Drag & Drop**: Open your Space → Files tab → Drag the entire `huggingface_deployment` folder contents
+  
+**Or:**
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
+cd YOUR_SPACE_NAME
+# Copy all files from huggingface_deployment folder here
+git add .
+git commit -m "Deploy Image Selector Backend"
+git push
+```
+
+### 3️⃣ Wait for Build
+- HuggingFace automatically builds your container (~5-10 minutes)
+- Watch the "Logs" tab for progress
+- Status changes to "Running" when ready
+
+### 4️⃣ You're Live! 🎊
+Your API will be at:
+```
+https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
+```
+
+Test it:
+```bash
+curl https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/
+# Returns: {"status":"ok"}
+```
+
+---
+
+## 📚 Read These First
+
+1. **QUICK_START.md** - Overview of what's included
+2. **DEPLOYMENT_GUIDE.md** - Detailed deployment instructions
+3. **CHECKLIST.md** - Step-by-step checklist
+
+---
+
+## 🔑 Key Features Configured
+
+✅ **Docker SDK** - Full container control  
+✅ **Port 7860** - HuggingFace Spaces default  
+✅ **Non-root user** - Security best practices  
+✅ **Smart storage** - Auto-detects `/data` or `/tmp`  
+✅ **CORS enabled** - Works with any frontend  
+✅ **Auto cleanup** - Deletes files after download  
+✅ **Per-user isolation** - Multiple users supported  
+✅ **Progress tracking** - Real-time processing updates  
+
+---
+
+## 💰 Cost Estimates
+
+### Free Tier (CPU Basic)
+- **Cost**: $0
+- **Good for**: Testing, demos, light usage
+- **Limitations**: Slow processing, sleeps when idle, no GPU
+
+### Production Tier (T4 Small GPU)
+- **Cost**: ~$0.60/hour (only when running)
+- **Good for**: Real users, fast processing
+- **Benefits**: GPU acceleration, always-on, faster processing
+
+### With Persistent Storage
+- **Add**: $5/month for 20GB
+- **Benefit**: Data persists across restarts
+
+---
+
+## 🎨 Connect Your Frontend
+
+Update your frontend code to use your new API:
+
+```javascript
+const API_URL = "https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space";
+```
+
+Frontend repo: https://github.com/basilbenny1002/image-selector-front-end
+
+---
+
+## ⚡ Quick Tips
+
+- **First run is slow**: Downloads ~500MB of ML models
+- **Subsequent runs are fast**: Models are cached
+- **GPU recommended**: 10-20x faster than CPU
+- **Free tier sleeps**: Upgrade to paid for always-on
+- **Logs are your friend**: Check them if issues occur
+
+---
+
+## 🆘 Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| Build fails | Check Logs tab for errors |
+| API not responding | Verify Space is "Running" not "Sleeping" |
+| Slow processing | Upgrade to GPU hardware |
+| Out of memory | Upgrade to larger CPU/GPU tier |
+| Models not loading | Wait for first download (~5 mins) |
+
+---
+
+## 📞 Support Resources
+
+- **HF Spaces Docs**: https://huggingface.co/docs/hub/spaces
+- **Docker Spaces**: https://huggingface.co/docs/hub/spaces-sdks-docker
+- **HF Discord**: https://discord.gg/hugging-face
+- **FastAPI Docs**: https://fastapi.tiangolo.com/
+
+---
+
+## 🎯 Success Criteria
+
+Your deployment is successful when:
+
+✅ Space status shows "Running"  
+✅ Health endpoint returns `{"status":"ok"}`  
+✅ You can upload an image via API  
+✅ Processing completes without errors  
+✅ Download returns a ZIP file  
+✅ Files are cleaned up after download  
+
+---
+
+## 🌟 What's Next?
+
+After successful deployment:
+
+1. **Share your Space** with the world
+2. **Connect your frontend** to the new API
+3. **Monitor usage** in Space analytics
+4. **Upgrade hardware** if needed for production
+5. **Add to your portfolio** - you deployed ML to production!
+
+---
+
+# 🎊 You're Ready to Deploy!
+
+Everything in the `huggingface_deployment` folder is configured and ready to go.
+
+**Just upload to HuggingFace Spaces and you're live!**
+
+Good luck! 🚀
+
+---
+
+*Created: November 2025*  
+*Based on: [Image-Selecter](https://github.com/basilbenny1002/Image-Selecter)*  
+*License: MIT*

main.py

@@ -0,0 +1,15 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.api.routes import router
+
+app = FastAPI(title="Image Selector Backend")
+
+# Allow all origins, methods, and headers for HuggingFace Spaces
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(router)

requirements.txt

@@ -0,0 +1,9 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+torch
+torchvision
+transformers
+Pillow
+numpy
+python-multipart
+aesthetics-predictor