# 🚀 Deployment Guide: Hugging Face Spaces

This guide walks you through deploying the **Awesome Multi-Agent Collaborative Perception** interactive website to Hugging Face Spaces.

## 📋 Prerequisites

- Hugging Face account ([sign up here](https://huggingface.co/join))
- Git installed on your system
- Basic familiarity with Git commands

## 🎯 Quick Deployment

### Option 1: Create Space Directly on Hugging Face

1. **Go to Hugging Face Spaces**
   - Visit [huggingface.co/spaces](https://huggingface.co/spaces)
   - Click "Create new Space"

2. **Configure Your Space**
   - **Space name**: `awesome-multi-agent-collaborative-perception`
   - **SDK**: Select "Gradio"
   - **Visibility**: Public (recommended)
   - **License**: MIT

3. **Upload Files**
   - Upload all files from this directory:
     - `app.py`
     - `collaborative-perception.html`
     - `requirements.txt`
     - `README.md`

### Option 2: Git Clone and Push

1. **Create the Space on HF**
   - Follow steps 1-2 from Option 1
   - Copy the Git repository URL

2. **Clone and Setup**
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/awesome-multi-agent-collaborative-perception
   cd awesome-multi-agent-collaborative-perception
   ```

3. **Copy Files**
   - Copy all files from this project into the cloned directory

4. **Commit and Push**
   ```bash
   git add .
   git commit -m "Initial deployment of collaborative perception website"
   git push
   ```

## 🔧 File Structure

Your Hugging Face Space should have this structure:

```
awesome-multi-agent-collaborative-perception/
├── app.py                           # Gradio app entry point
├── collaborative-perception.html    # Main interactive website
├── requirements.txt                 # Python dependencies
├── README.md                       # Space description with HF metadata
├── .gitignore                      # Git ignore rules
└── DEPLOYMENT.md                   # This file
```

## ⚙️ Configuration Files

### `app.py`
- Simple Gradio wrapper that serves the HTML file
- Configured for full-width display
- Minimal overhead for maximum performance

### `requirements.txt`
- Only requires `gradio==4.44.0`
- Lightweight dependencies for fast startup

### `README.md`
- Contains Hugging Face Space metadata in frontmatter
- Serves as the Space's landing page description

## 🔍 Metadata Configuration

The README.md contains crucial metadata for Hugging Face:

```yaml
---
title: Awesome Multi-Agent Collaborative Perception
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.0
app_file: app.py
pinned: false
license: mit
---
```

**Important**: Update `your-username` placeholders in the README with your actual Hugging Face username.

## 🎨 Customization

### Update Branding
1. Change the `title` and `emoji` in README frontmatter
2. Update social links in README badges
3. Modify the color scheme (`colorFrom`, `colorTo`)

### Add Analytics
Add tracking code to `collaborative-perception.html` before `</body>`:

```html
<!-- Google Analytics or your preferred analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'GA_MEASUREMENT_ID');
</script>
```

## 🚀 Post-Deployment

### 1. Test Your Space
- Visit your Space URL: `https://huggingface.co/spaces/YOUR_USERNAME/awesome-multi-agent-collaborative-perception`
- Test all interactive features
- Verify responsiveness on mobile devices

### 2. Share Your Space
- Add the Space URL to your GitHub repository
- Share on social media using the Space's share button
- Include in your research papers and presentations

### 3. Monitor Usage
- Check Space analytics in your HF dashboard
- Monitor for user feedback and issues
- Update content regularly

## 📊 Space Statistics

Your Space will track:
- **Views**: Total page visits
- **Likes**: User appreciation
- **Duplicates**: Forks of your Space
- **Comments**: User feedback

## 🔄 Updates and Maintenance

### Regular Content Updates
1. **Monthly**: Update with latest papers and datasets
2. **Quarterly**: Refresh conference information
3. **Annually**: Major design improvements

### Technical Updates
```bash
# Pull latest changes
git pull

# Make your updates
# ... edit files ...

# Push changes
git add .
git commit -m "Update: Added latest CVPR 2025 papers"
git push
```

## 💡 Pro Tips

1. **Performance**: Keep the HTML file under 2MB for fast loading
2. **SEO**: Update meta tags in the HTML for better search visibility
3. **Accessibility**: Test with screen readers and keyboard navigation
4. **Mobile**: Always test on mobile devices before deployment
5. **Backup**: Keep a local backup of your custom content

## 🐛 Troubleshooting

### Common Issues

**Space won't start:**
- Check `requirements.txt` syntax
- Verify `app.py` imports work
- Ensure HTML file exists and is valid

**HTML not displaying correctly:**
- Check file encoding (should be UTF-8)
- Verify JavaScript console for errors
- Test HTML file locally first

**Gradio errors:**
- Update to latest Gradio version
- Check Gradio documentation for breaking changes
- Simplify the Gradio interface if needed

### Getting Help

- **Hugging Face Forum**: [discuss.huggingface.co](https://discuss.huggingface.co)
- **Discord**: [Hugging Face Discord](https://discord.gg/hugging-face)
- **Documentation**: [hf.co/docs/hub/spaces](https://huggingface.co/docs/hub/spaces)

## 📄 License

This deployment is licensed under MIT License. See the main README.md for details.

---

**🎉 Ready to deploy? Your interactive collaborative perception website will be live in minutes!**