DEPLOYMENT.md

# Deployment Guide - New HF Space

## Step 1: Create New HF Space

1. Go to https://huggingface.co/new-space
2. Fill in details:
   - **Space name**: `game-asset-generator-pro-v2` (or your choice)
   - **License**: MIT
   - **SDK**: Gradio
   - **Hardware**: L4 GPU (24GB VRAM)
   - **Visibility**: Public or Private

3. Click "Create Space"

## Step 2: Clone the Space Repository

```powershell
# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2
cd game-asset-generator-pro-v2
```

## Step 3: Copy Files

```powershell
# Copy all files from huggingface-space-v2
Copy-Item -Recurse D:\KIRO\Projects\XStudios\huggingface-space-v2\* .

# Verify files
Get-ChildItem -Recurse
```

## Step 4: Configure Space

Create `README.md` header (HF Space metadata):

```yaml
---
title: 3D Asset Generator Pro V2
emoji: 🎮
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
hardware: l4
---
```

## Step 5: Push to HF Space

```powershell
# Initialize git (if not already)
git init

# Add all files
git add .

# Commit
git commit -m "Initial deployment - Streamlined architecture"

# Add remote (if not already added)
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2

# Push
git push -u origin main
```

## Step 6: Monitor Deployment

1. Go to your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/game-asset-generator-pro-v2`
2. Watch the build logs
3. Wait for "Running" status (~5-10 minutes)

## Step 7: Test the Space

### Basic Test
1. Enter prompt: "medieval knight"
2. Select quality: "Fast"
3. Click "Generate Asset"
4. Verify 3D model appears

### Full Test Suite
- [ ] All quality presets work
- [ ] Caching works (same prompt twice)
- [ ] Error handling works (invalid inputs)
- [ ] Blender optimization works
- [ ] Rate limiting works
- [ ] UI is responsive

## Troubleshooting

### Build Fails

**Check logs for:**
- Missing dependencies → Update `requirements.txt`
- Import errors → Check module structure
- Blender not found → Verify Dockerfile

**Common fixes:**
```powershell
# Update requirements
pip freeze > requirements.txt

# Test imports locally
python -c "from core import AssetPipeline"
```

### Runtime Errors

**Check Space logs:**
1. Click "Logs" tab in HF Space
2. Look for error messages
3. Check GPU memory usage

**Common issues:**
- OOM errors → Reduce quality preset
- Timeout errors → Increase GPU duration
- API errors → Check Hunyuan3D Space status

### Blender Not Working

**Verify Blender installation:**
```powershell
# In Space terminal (if available)
which blender
blender --version
```

**If missing:**
- Update Dockerfile to install Blender
- Or disable Blender optimization (will skip post-processing)

## Configuration Options

### Environment Variables

Add to Space settings:
- `BLENDER_PATH=/usr/bin/blender`
- `PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True`

### Hardware Settings

**Recommended:**
- **GPU**: L4 (24GB VRAM) - Optimal for FLUX + Hunyuan3D
- **CPU**: 8 cores
- **RAM**: 32GB
- **Storage**: 50GB

**Minimum:**
- **GPU**: T4 (16GB VRAM) - May have OOM issues
- **CPU**: 4 cores
- **RAM**: 16GB
- **Storage**: 20GB

## Performance Tuning

### If Generation is Slow

1. **Reduce quality presets:**
   - Edit `core/config.py`
   - Lower `flux_steps` and `hunyuan_steps`

2. **Disable Blender optimization:**
   - Comment out Blender processing in `core/pipeline.py`

3. **Increase GPU duration:**
   - Edit `@spaces.GPU(duration=X)` decorators
   - Increase from 35s/90s to higher values

### If OOM Errors Occur

1. **Enable CPU offload:**
   - Edit `generators/flux.py`
   - Add `pipe.enable_sequential_cpu_offload()`

2. **Reduce batch size:**
   - Lower texture resolution in presets
   - Reduce octree resolution

3. **Clear cache more frequently:**
   - Edit `utils/cache.py`
   - Reduce `CACHE_EXPIRY_HOURS`

## Monitoring

### Check Space Health

**Metrics to monitor:**
- Generation success rate
- Average generation time
- GPU memory usage
- Cache hit rate
- Error rate

**HF Space dashboard shows:**
- Total requests
- Active users
- GPU usage
- Build status

### User Feedback

**Collect feedback on:**
- Generation quality
- Speed/performance
- UI usability
- Error messages
- Feature requests

## Maintenance

### Regular Tasks

**Daily:**
- Check error logs
- Monitor GPU usage
- Verify cache is working

**Weekly:**
- Clean old cache files
- Update dependencies
- Review user feedback

**Monthly:**
- Update models (FLUX, Hunyuan3D)
- Optimize performance
- Add new features

### Updates

**To update the Space:**
```powershell
# Make changes locally
# Test changes
python app.py

# Commit and push
git add .
git commit -m "Update: description of changes"
git push
```

## Comparison with Old Space

| Feature | Old Space | New Space | Status |
|---------|-----------|-----------|--------|
| Code Size | 2,481 lines | 960 lines | ✅ 61% reduction |
| Architecture | Monolithic | Modular | ✅ Improved |
| Type Safety | None | Full | ✅ Added |
| Error Handling | Basic | Comprehensive | ✅ Improved |
| Dependencies | 20+ | 10 | ✅ 50% reduction |
| Maintainability | Low | High | ✅ Much better |

## Success Criteria

**Space is successful if:**
- ✅ Builds without errors
- ✅ Generates assets successfully
- ✅ No OOM errors
- ✅ Cache works (60% quota savings)
- ✅ UI is responsive
- ✅ Error messages are clear
- ✅ Performance is good (<90s for High quality)

## Next Steps

After successful deployment:
1. Share Space URL with team
2. Collect user feedback
3. Monitor performance for 24 hours
4. Optimize based on real usage
5. Consider migrating old Space if all goes well

## Support

**If you need help:**
1. Check HF Space logs
2. Review error messages
3. Test locally first
4. Check GPU memory with `nvidia-smi`
5. Review MIGRATION_GUIDE.md

**Common resources:**
- HF Spaces docs: https://huggingface.co/docs/hub/spaces
- Gradio docs: https://gradio.app/docs
- FLUX docs: https://huggingface.co/black-forest-labs/FLUX.1-dev
- Hunyuan3D docs: https://huggingface.co/tencent/Hunyuan3D-2.1