DEPLOYMENT.md

# Diamond CSGO AI Player - Deployment Guide

## 🚀 Deploying to Hugging Face Spaces

### Prerequisites
1. Hugging Face account
2. Model checkpoint files (`agent_epoch_00206.pt` or similar)
3. Git and Git LFS installed

### Step 1: Prepare Repository

1. **Clone/Fork this repository**
2. **Install Git LFS** (for large model files):
   ```bash
   git lfs install
   git lfs track "*.pt"
   git add .gitattributes
   ```

3. **Add your model checkpoint**:
   ```bash
   # Copy your trained model to the project root
   cp /path/to/your/agent_epoch_00206.pt .
   git add agent_epoch_00206.pt
   git commit -m "Add trained model checkpoint"
   ```

### Step 2: Create Hugging Face Space

1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Configure:
   - **Space name**: `diamond-csgo-ai` (or your choice)
   - **License**: Your preferred license
   - **Space SDK**: `Docker` 
   - **Space hardware**: 
     - `CPU basic` (free) - for demo/testing
     - `GPU T4 small` (paid) - for better performance

### Step 3: Upload Code

```bash
# Clone your new space
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME

# Copy all project files
cp -r /path/to/diamond/* .

# Commit and push
git add .
git commit -m "Initial Diamond CSGO AI deployment"
git push
```

### Step 4: Configuration Files

Ensure these files are in your space root:

- `app.py` - Main FastAPI application
- `requirements.txt` - Python dependencies  
- `Dockerfile` - Container configuration
- `README.md` - Space description
- `packages.txt` - System packages (if needed)

### Step 5: Model Setup

If your model is too large for Git (>100MB), use Git LFS or download from Hub:

```python
# In your app.py, add model downloading:
from huggingface_hub import hf_hub_download

def download_model():
    return hf_hub_download(
        repo_id="YOUR_USERNAME/YOUR_MODEL_REPO",
        filename="agent_epoch_00206.pt"
    )
```

## 🔧 Local Testing

Before deploying, test locally:

```bash
# Install dependencies
pip install -r requirements.txt

# Run tests
python test_web_app.py

# Start local server
python run_web_demo.py
```

Visit `http://localhost:7860` to test the interface.

## ⚙️ Configuration Options

### Hardware Requirements

| Tier | CPU | RAM | GPU | Performance |
|------|-----|-----|-----|-------------|
| Free | 2 vCPU | 16GB | None | Basic demo |
| Basic GPU | 4 vCPU | 16GB | T4 | Good performance |
| Premium | 8 vCPU | 32GB | A10G | Best experience |

### Environment Variables

Add these in your Space settings:
- `CUDA_VISIBLE_DEVICES=""` (for CPU-only)
- `PYTHONPATH="/app/src:/app"`

## 🎮 Usage Instructions

Once deployed, users can:

1. Visit your Space URL
2. Click on the game canvas
3. Use keyboard controls:
   - **WASD** - Movement
   - **Space** - Jump  
   - **Arrow keys** - Camera
   - **1,2,3** - Weapons
   - **R** - Reload
   - **M** - Switch Human/AI mode

## 🐛 Troubleshooting

### Common Issues

1. **Model not loading**:
   - Check checkpoint file exists
   - Verify file size (<5GB for Spaces)
   - Use Git LFS for large files

2. **Import errors**:
   - Check `requirements.txt` is complete
   - Verify Python path in `Dockerfile`

3. **Performance issues**:
   - Use GPU hardware tier
   - Reduce model complexity
   - Lower frame rate

4. **WebSocket connection failed**:
   - Check firewall settings
   - Verify port 7860 is accessible
   - Try different browser

### Debug Mode

Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 📊 Monitoring

Monitor your Space:
- View logs in HF Spaces interface
- Check GPU utilization
- Monitor user sessions

## 🔄 Updates

To update your deployed Space:
```bash
git pull  # Get latest changes
git add .
git commit -m "Update to latest version"
git push  # Automatically redeploys
```

## 💡 Tips for Success

1. **Start with CPU tier** to test basic functionality
2. **Use smaller models** for faster loading
3. **Test thoroughly locally** before deploying
4. **Monitor resource usage** to optimize costs
5. **Add usage instructions** in your Space README

## 🎯 Next Steps

After successful deployment:
- Share your Space with the community
- Collect user feedback
- Iterate on the interface
- Add new features like replay saving
- Consider multi-user support

Happy deploying! 🚀