# 🚀 Deploying to Hugging Face Spaces

Complete guide to deploying your D&D Campaign Manager to Hugging Face Spaces.

## 📋 Pre-Deployment Checklist

Before deploying, ensure you have:

- [ ] Hugging Face account (free at https://huggingface.co)
- [ ] API keys for at least one AI provider:
  - Anthropic (recommended): https://console.anthropic.com
  - OpenAI: https://platform.openai.com
  - Google AI: https://makersuite.google.com

## 🎯 Quick Deploy (Recommended)

### Option 1: Upload Files to New Space

1. **Create a New Space**
   - Go to https://huggingface.co/new-space
   - Space name: `dnd-campaign-manager` (or your choice)
   - SDK: **Gradio**
   - Visibility: **Public** (or Private)
   - Click **Create Space**

2. **Upload Files**

   Upload these files from your project:

   **Required Files:**
   ```
   app_v2.py                  # Main application
   README_HF.md               # Space description (rename to README.md)
   requirements_hf.txt        # Dependencies (rename to requirements.txt)
   .env.example              # Environment variable template

   src/                       # Entire src directory
   mcp_server/               # Entire mcp_server directory
   data/                      # Create empty folder for database
   ```

   **File Operations:**
   - Rename `README_HF.md` → `README.md`
   - Rename `requirements_hf.txt` → `requirements.txt`

3. **Set Environment Variables (Secrets)**

   In your Space settings → **Variables and secrets**:

   Add at least ONE of these:
   ```
   ANTHROPIC_API_KEY = sk-ant-...
   OPENAI_API_KEY = sk-...
   GOOGLE_API_KEY = AIza...
   ```

   Optional variables:
   ```
   HUGGINGFACE_API_KEY = hf_...
   PRIMARY_MODEL_PROVIDER = anthropic
   PRIMARY_MODEL = claude-3-5-sonnet-20241022
   ```

4. **Wait for Build**
   - HF Spaces will automatically install dependencies
   - Build takes ~3-5 minutes
   - Your app will be live at: `https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager`

## 🔧 Option 2: Git Push (Advanced)

### Step 1: Clone Your Space

```bash
# Install git-lfs if you haven't
git lfs install

# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager
cd dnd-campaign-manager
```

### Step 2: Copy Files

```bash
# From your dungeon-smasher-pro directory:
cp app_v2.py path/to/dnd-campaign-manager/
cp README_HF.md path/to/dnd-campaign-manager/README.md
cp requirements_hf.txt path/to/dnd-campaign-manager/requirements.txt
cp .env.example path/to/dnd-campaign-manager/

# Copy directories
cp -r src path/to/dnd-campaign-manager/
cp -r mcp_server path/to/dnd-campaign-manager/
mkdir -p path/to/dnd-campaign-manager/data
```

### Step 3: Commit and Push

```bash
cd path/to/dnd-campaign-manager

git add .
git commit -m "Initial deployment of D&D Campaign Manager"
git push
```

### Step 4: Configure Secrets

Go to your Space settings and add API keys as secrets (see Option 1, step 3).

## 📁 Final Directory Structure on HF Space

```
dnd-campaign-manager/          # Your HF Space root
├── README.md                  # Renamed from README_HF.md
├── requirements.txt           # Renamed from requirements_hf.txt
├── app_v2.py                  # Main app (HF will run this)
├── .env.example              # Environment variable template
│
├── src/                       # Application source
│   ├── agents/
│   │   ├── campaign_agent.py
│   │   └── character_agent.py
│   ├── models/
│   │   ├── campaign.py
│   │   ├── character.py
│   │   └── session_notes.py
│   ├── ui/
│   │   ├── app.py
│   │   ├── components/
│   │   └── tabs/
│   └── utils/
│       ├── ai_client.py
│       └── file_parsers.py
│
├── mcp_server/               # MCP tools
│   ├── dnd_mcp_server.py
│   ├── mcp_config.json
│   └── README.md
│
└── data/                     # Database (auto-created)
    └── dnd_campaign_manager.db
```

## ⚙️ Configuration Tips

### Memory Management

HF Spaces free tier has 16GB RAM. If you encounter memory issues:

1. **In your Space settings:**
   - Hardware: Start with **CPU Basic** (free)
   - Upgrade to **CPU Upgrade** or **T4 small** if needed

2. **Optimize database:**
   ```python
   # Already implemented in campaign_agent.py
   # Uses SQLite with limited result sets
   ```

### Persistent Storage

**Important:** HF Spaces free tier has ephemeral storage. Your database will reset on Space restart.

**Solutions:**

1. **Use HF Datasets for persistence (recommended):**
   ```python
   # Add to requirements.txt:
   # datasets>=2.0.0

   # Save to HF Dataset periodically
   from datasets import Dataset
   # Implementation in src/utils/persistence.py
   ```

2. **Upgrade to Persistent Storage:**
   - Go to Space Settings → Storage
   - Enable persistent storage ($5/month)

3. **Accept ephemeral storage:**
   - Good for demos/testing
   - Users can export their data

### API Rate Limits

To avoid hitting rate limits:

1. **Set rate limit warnings** (already implemented in AI client)
2. **Add caching** for repeated requests
3. **Consider adding Redis** for session management

## 🧪 Testing Your Deployment

Once deployed, test these features:

1. **Character Creation**
   - Create a character
   - Generate backstory
   - Export character sheet

2. **Campaign Synthesis**
   - Create 3-4 characters
   - Synthesize campaign
   - Verify campaign loads

3. **Session Generation**
   - Auto-generate a session
   - Upload session notes
   - Generate next session

4. **MCP Tools** (if using MCP server)
   - Character validation
   - Encounter CR calculation

## 🐛 Troubleshooting

### Build Fails

**Error:** `Could not find a version that satisfies the requirement...`

**Fix:** Check `requirements.txt` version constraints:
```txt
# Too strict (may fail):
gradio==5.0.0

# Better (flexible):
gradio>=5.0.0
```

### App Doesn't Start

**Check logs:**
1. Go to your Space
2. Click **Logs** tab
3. Look for errors

**Common issues:**
- Missing API key → Add in Secrets
- Import error → Check all files uploaded
- Database path → Ensure `data/` directory exists

### Slow Performance

**Solutions:**
1. Upgrade hardware tier
2. Enable caching
3. Use faster model (e.g., Gemini Flash)
4. Reduce session history lookback

### Database Resets

**This is normal on free tier.**

**Options:**
1. Enable persistent storage ($5/month)
2. Use HF Datasets for backup
3. Allow users to export/import data

## 🎨 Customizing Your Space

### Update README Header

Edit `README.md` frontmatter:

```yaml
---
title: My D&D Campaign Manager
emoji: ⚔️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.0.0
app_file: app_v2.py
pinned: true
license: mit
tags:
  - dnd
  - ttrpg
  - ai
  - campaign-manager
  - mcp
---
```

### Add Custom Domain (Pro)

HF Spaces Pro allows custom domains:
1. Settings → Custom Domain
2. Point your DNS to HF
3. Enable HTTPS

### Enable Authentication

Restrict access to your Space:

```python
# In app_v2.py
from src.ui import launch_ui

if __name__ == "__main__":
    launch_ui(auth=("admin", "your_password"))
```

Or use HF's built-in auth:
- Settings → Access Control
- Set to "Private" or "Token-gated"

## 📊 Monitoring

### View Analytics

HF Spaces provides:
- **App traffic** (visits, unique users)
- **Resource usage** (CPU, memory)
- **Build history**

Access: Space Settings → Analytics

### Add Custom Analytics

```python
# Add to app.py
import gradio as gr

def track_event(event_name):
    # Log to your analytics service
    pass

# Add to Gradio components
gr.Button("Create Character").click(
    fn=lambda: track_event("character_created"),
    ...
)
```

## 🚀 Going to Production

For serious production use:

1. **Persistent Storage:** Enable in Space settings
2. **Upgrade Hardware:** T4 Small GPU or better
3. **Add Monitoring:** Sentry, LogRocket, etc.
4. **Rate Limiting:** Implement per-user limits
5. **Backups:** Daily exports to HF Dataset
6. **Custom Domain:** For branding
7. **Load Testing:** Test with multiple users

## 💰 Cost Estimates

**Free Tier:**
- Hosting: Free
- Storage: Ephemeral (resets on restart)
- Hardware: CPU Basic
- **Good for:** Demos, testing, low traffic

**Paid Tiers:**
- **Persistent Storage:** $5/month
- **CPU Upgrade:** $0/hour (included)
- **T4 Small (GPU):** $0.60/hour
- **A10G Small:** $1.50/hour

**API Costs (separate):**
- Anthropic Claude: ~$3-15 per 1M tokens
- OpenAI GPT-4: ~$10-30 per 1M tokens
- Google Gemini: Free tier available

## 📝 Checklist: Ready to Deploy?

- [ ] All files ready (app_v2.py, src/, mcp_server/)
- [ ] requirements_hf.txt renamed to requirements.txt
- [ ] README_HF.md renamed to README.md
- [ ] .env.example included (for local dev reference)
- [ ] API keys ready to add as Secrets
- [ ] HF Space created
- [ ] Files uploaded or pushed
- [ ] Secrets configured
- [ ] Build succeeded
- [ ] App tested

## 🎉 You're Live!

Once deployed, share your Space:

```
🎲 Check out my D&D Campaign Manager!
https://huggingface.co/spaces/YOUR_USERNAME/dnd-campaign-manager

Features:
✨ AI-powered character creation
🎯 Autonomous campaign synthesis
📖 Auto-generated session plans
⚔️ MCP-powered encounter balancing
```

---

**Need help?**
- HF Spaces Docs: https://huggingface.co/docs/hub/spaces
- Gradio Docs: https://gradio.app/docs/
- Open an issue on GitHub

**Happy deploying!** 🚀