# HuggingFace Spaces Deployment Guide

This guide will walk you through deploying Character Forge to HuggingFace Spaces.

## Prerequisites

- HuggingFace account (free at https://huggingface.co/)
- Google Gemini API key (get yours at https://aistudio.google.com/app/apikey)

## Deployment Steps

### 1. Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Configure your space:
   - **Name**: `character-forge` (or your preferred name)
   - **License**: Apache 2.0
   - **SDK**: Streamlit
   - **Hardware**: CPU Basic (free tier works fine)
4. Click "Create Space"

### 2. Upload Files

You have two options:

#### Option A: Git Clone (Recommended)

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

# Copy all files from character_forge_release directory
cp -r /path/to/character_forge_release/* .

# Add and commit
git add .
git commit -m "Initial commit: Character Forge deployment"
git push
```

#### Option B: Web Upload

1. Click "Files and versions" in your Space
2. Click "Add file" → "Upload files"
3. Upload all files from the `character_forge_release` directory
4. Commit the changes

### 3. Configure Secrets

Your Gemini API key must be stored securely as a secret:

1. Go to your Space settings
2. Click "Repository secrets"
3. Add a new secret:
   - **Name**: `GEMINI_API_KEY`
   - **Value**: Your Gemini API key (starts with `AIzaSy...`)
4. Save the secret

### 4. Wait for Build

HuggingFace will automatically:
- Install dependencies from `requirements.txt`
- Install system packages from `packages.txt`
- Start your Streamlit app

This takes 2-5 minutes.

### 5. Test Your Space

Once built, your Space will be available at:
```
https://huggingface.co/spaces/YOUR_USERNAME/character-forge
```

## Configuration Options

### Hardware Upgrades

For better performance:
- **CPU Basic** (free): Good for testing, slower generations
- **CPU Upgrade** ($0.03/hour): Faster, recommended for public spaces
- **GPU**: Not needed for Gemini API backend

### Environment Variables

You can add more environment variables in Repository Secrets if needed:

- `GEMINI_API_KEY`: Your Google Gemini API key (required)
- Any other custom configuration

### Custom Domain (Pro users)

HuggingFace Pro users can set up custom domains in Space settings.

## Troubleshooting

### Build Fails

**Check logs:**
1. Go to "App" tab in your Space
2. Click "Logs" at the bottom
3. Look for error messages

**Common issues:**
- Missing dependencies: Add to `requirements.txt`
- System packages: Add to `packages.txt`
- Import errors: Check file paths in code

### API Key Not Working

**Verify secret:**
1. Go to Repository secrets
2. Check `GEMINI_API_KEY` is set correctly
3. Restart the space (Settings → Factory reboot)

**Test manually:**
- Enter API key in the UI sidebar
- Check if it works there

### App Not Starting

**Check logs for:**
- Import errors
- Missing files
- Configuration issues

**Try:**
1. Factory reboot (Settings → Factory reboot)
2. Check all files are uploaded
3. Verify `app.py` is in root directory

### Slow Performance

**Free tier limitations:**
- CPU Basic is slower
- Consider CPU Upgrade for production

**Optimize:**
- Use temperature 0.3-0.4 for faster results
- Smaller image sizes when possible

## Making Your Space Public

### Privacy Settings

1. Go to Space settings
2. Choose visibility:
   - **Public**: Anyone can view and use
   - **Private**: Only you can access

### Usage Limits

To prevent abuse on public spaces:

1. Add rate limiting (code already included)
2. Monitor usage in Space analytics
3. Consider requiring sign-in for high usage

### Sharing

Share your Space:
- Direct link: `https://huggingface.co/spaces/YOUR_USERNAME/character-forge`
- Embed widget: Available in Space settings
- Duplicate: Others can duplicate to their account

## Updating Your Space

### Via Git

```bash
cd character-forge
# Make your changes
git add .
git commit -m "Update: description"
git push
```

### Via Web

1. Go to "Files and versions"
2. Edit files directly or upload new versions
3. Commit changes

## Cost Estimation

### HuggingFace Costs

- **CPU Basic**: Free
- **CPU Upgrade**: ~$0.03/hour (when running)
- **Persistent storage**: Free up to 50GB

### Gemini API Costs

- ~$0.03 per image generation
- Character sheet: ~$0.15 (5 images)
- Free tier: 15 requests/minute

### Total Cost Example

Public space with 100 users/day:
- HF Space (CPU Upgrade, 24/7): ~$21.60/month
- Gemini API: Varies by usage
  - Light: 100 images/day = ~$90/month
  - Heavy: 1000 images/day = ~$900/month

**Recommendation**: Start with free tier, upgrade as needed.

## Best Practices

### Security

- ✅ Store API keys in Repository Secrets
- ✅ Never commit secrets to git
- ✅ Use environment variables for configuration
- ❌ Don't hardcode API keys in code

### Performance

- ✅ Use caching where possible (Streamlit `@st.cache_data`)
- ✅ Optimize image sizes
- ✅ Set reasonable timeout limits
- ❌ Don't store large files in git

### User Experience

- ✅ Add clear instructions in UI
- ✅ Show helpful error messages
- ✅ Provide examples
- ❌ Don't assume users know how to use it

## Support

Need help?

- **HuggingFace**: https://huggingface.co/docs/hub/spaces
- **Character Forge**: Open an issue on GitHub
- **Streamlit**: https://docs.streamlit.io/

## Next Steps

After deployment:

1. ✅ Test all features
2. ✅ Share with users
3. ✅ Monitor logs and usage
4. ✅ Collect feedback
5. ✅ Iterate and improve

Good luck with your deployment! 🚀