# Deploying Character Forge to HuggingFace Spaces

This guide will help you deploy Character Forge to HuggingFace Spaces.

## Prerequisites

1. **HuggingFace Account**: Sign up at https://huggingface.co/join
2. **Gemini API Key**: Get one free at https://aistudio.google.com/app/apikey

## Step-by-Step Deployment

### 1. Create a New Space

Go to https://huggingface.co/spaces and click "Create new Space"

Fill in the form:
- **Owner**: Your username or organization
- **Space name**: `character_forge` (or your preferred name)
- **Short description**: "Transform a single image into a complete multi-angle character sheet"
- **License**: **GNU AGPL v3.0** ⚠️ IMPORTANT
- **Select SDK**: **Docker**
- **Docker template**: **Streamlit**
- **Space hardware**: **CPU Basic (Free)** - sufficient for Gemini API backend
- **Visibility**: Public or Private (your choice)

Click **"Create Space"**

### 2. Upload Files

You have two options:

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

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

# Copy Character Forge files
cp -r /path/to/character_forge_release/* .

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

#### Option B: Web Upload

Use the HuggingFace web interface to upload:

**Required files/folders:**
```
character_forge/              # Main application directory
├── character_forge_image/    # Streamlit app
│   ├── app.py               # Main entry point
│   ├── config/              # Configuration
│   ├── services/            # Backend services
│   └── ui/                  # UI components
├── .streamlit/
│   └── config.toml          # Streamlit config
├── Dockerfile               # HuggingFace deployment config
├── requirements.txt         # Python dependencies
├── LICENSE                  # GNU AGPL v3.0
├── NOTICE                   # Important license info
└── README.md                # Documentation
```

### 3. Configure Environment Variables

This is **CRITICAL** for the app to work!

1. Go to your Space settings: `Settings` tab
2. Click on `Repository secrets`
3. Add a new secret:
   - **Name**: `GEMINI_API_KEY`
   - **Value**: Your actual Gemini API key from Google AI Studio

### 4. Wait for Build

HuggingFace will automatically:
1. Detect the Dockerfile
2. Build the Docker image
3. Deploy the application
4. Show build logs in real-time

This takes 3-5 minutes for the first build.

### 5. Access Your App

Once deployed, your app will be available at:
```
https://huggingface.co/spaces/YOUR_USERNAME/character_forge
```

## Configuration Details

### Dockerfile

The included `Dockerfile` is pre-configured for HuggingFace Spaces:
- Uses Python 3.10
- Installs all dependencies from requirements.txt
- Exposes port 7860 (HuggingFace standard)
- Runs Streamlit with proper server settings

### Streamlit Config

The `.streamlit/config.toml` file includes:
- Port 7860 binding
- Headless mode for server deployment
- Disabled CORS for HuggingFace proxy
- Custom theme matching Character Forge branding

### Requirements

The `requirements.txt` includes minimal dependencies:
- Streamlit for the UI
- google-genai for Gemini API
- Pillow for image processing
- Other essential libraries

**No GPU required** - all processing happens via Gemini API!

## Troubleshooting

### App Won't Start

Check the build logs for errors. Common issues:
- Missing `GEMINI_API_KEY` secret
- Incorrect file paths in Dockerfile
- Missing dependencies in requirements.txt

### "Invalid API Key" Error

1. Verify your Gemini API key at https://aistudio.google.com/app/apikey
2. Check the secret name is exactly `GEMINI_API_KEY` (case-sensitive)
3. Make sure there are no extra spaces in the key value

### Slow Performance

- Free CPU tier is slower than local GPU
- Consider upgrading to CPU Upgrade ($0.05/hour) if needed
- Generation still takes 30-60 seconds per image with Gemini API

### Upload Size Limits

HuggingFace has file size limits. If you get errors:
- Don't include large example images in the repo
- Keep the deployment lean (under 500MB total)
- Users will upload their own images

## Updating Your Space

To update after changes:

```bash
cd character_forge
git pull origin main  # Get latest changes
git add .
git commit -m "Update to latest version"
git push
```

HuggingFace will automatically rebuild and redeploy.

## Cost Considerations

### HuggingFace Hosting
- **CPU Basic (Free)**: $0/month - Works great!
- **CPU Upgrade**: ~$0.05/hour (~$36/month if always on)
- **Sleep mode**: Free tier sleeps after 48h inactivity

### Gemini API Usage
- **Free tier**: 15 requests/minute, 1500 requests/day
- **Paid tier**: ~$0.03 per image generation
- **Character sheet**: ~$0.15 total (5 images)

**Total cost for casual use: FREE!**

## License Compliance

Character Forge is licensed under **GNU AGPL v3.0**:

✓ **Your deployment is legal** - hosting on HuggingFace Spaces is fine
✓ **User-generated content** - Users own their generated images
✓ **Must keep open source** - Don't remove license files
✗ **No proprietary versions** - Any modifications must stay AGPL

Make sure your Space is marked as **AGPL-3.0 license** in settings!

## Support

- **Issues**: https://github.com/yourusername/character-forge/issues
- **Documentation**: See README.md in the repo
- **HuggingFace Help**: https://huggingface.co/docs/hub/spaces

---

**Ready to deploy? Follow the steps above and you'll be generating character sheets in minutes!**