docs/HUGGINGFACE_SPACES.md

# HuggingFace Spaces Deployment Guide

## Overview

This guide explains how to deploy Writing Studio on HuggingFace Spaces for free, public access to your AI writing assistant.

## Prerequisites

- HuggingFace account ([sign up free](https://huggingface.co/join))
- Basic familiarity with Git (optional for direct upload)

## Quick Deploy

### Method 1: Direct Upload (Easiest)

1. **Create a Space**
   - Go to [huggingface.co/new-space](https://huggingface.co/new-space)
   - Name your Space (e.g., "writing-studio")
   - Choose **Gradio** as SDK
   - Select visibility (Public or Private)
   - Click "Create Space"

2. **Upload Files**
   - Click "Files" tab
   - Upload these essential files:
     - `app.py`
     - `requirements.txt`
     - `src/` folder (entire directory)
     - `.space_config.yml` (optional)
     - `README_HF_SPACES.md` (rename to README.md)

3. **Wait for Build**
   - HuggingFace automatically detects `app.py` and `requirements.txt`
   - First build takes 3-5 minutes (installing dependencies)
   - Your Space will be live at: `https://huggingface.co/spaces/USERNAME/SPACE_NAME`

### Method 2: Git Clone (Recommended for Updates)

1. **Create a Space** (as above)

2. **Clone Locally**
   ```bash
   git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
   cd SPACE_NAME
   ```

3. **Copy Files**
   ```bash
   # From your WritingStudio directory
   cp -r src/ app.py requirements.txt .space_config.yml /path/to/SPACE_NAME/
   cp README_HF_SPACES.md /path/to/SPACE_NAME/README.md
   ```

4. **Push to Space**
   ```bash
   cd /path/to/SPACE_NAME
   git add .
   git commit -m "Initial deployment"
   git push
   ```

5. **Monitor Build**
   - Go to your Space URL
   - Check "Logs" tab for build progress
   - App will be live when build completes

### Method 3: Duplicate an Existing Space

If someone has already deployed Writing Studio:

1. Go to their Space
2. Click "⋯" menu → "Duplicate this Space"
3. Choose your username and Space name
4. Click "Duplicate Space"
5. Done! Your own copy is live

## Configuration

### Default Settings

Works out-of-the-box with:
- Model: `distilgpt2` (fast, lightweight)
- Log Level: `INFO`
- Metrics: Disabled (not needed on HF Spaces)
- Caching: Enabled
- All rubric features: Enabled

### Custom Configuration

#### Option A: Environment Variables

In your Space:
1. Go to Settings
2. Scroll to "Repository secrets"
3. Add variables:

```
DEFAULT_MODEL=gpt2
LOG_LEVEL=DEBUG
MAX_TEXT_LENGTH=5000
```

#### Option B: Edit .space_config.yml

```yaml
env:
  DEFAULT_MODEL: gpt2
  LOG_LEVEL: INFO
  ENABLE_CACHE: "true"
  MAX_TEXT_LENGTH: "5000"
```

Commit and push changes.

## Hardware Selection

### Free Tier (CPU Basic)

**Best for:**
- Testing and demos
- Small models (distilgpt2)
- Light usage

**Performance:**
- First load: ~30-60s
- Subsequent: ~5-10s per analysis
- Memory: 16GB RAM
- Storage: Unlimited

**Limitations:**
- Slower processing
- May timeout on large models

### CPU Upgrade (Paid)

**Best for:**
- Production use
- Medium models (gpt2)
- Regular users

**Performance:**
- First load: ~20-45s
- Subsequent: ~3-8s
- More CPU cores
- Better throughput

**Cost:** ~$0.10/hour

### T4 Small GPU (Paid)

**Best for:**
- Best performance
- Large models (gpt2-medium, gpt2-large)
- High traffic

**Performance:**
- First load: ~15-30s
- Subsequent: ~1-3s
- GPU acceleration
- Fastest generation

**Cost:** ~$0.60/hour

### Recommendation

Start with **Free Tier + distilgpt2**:
- Works well for most use cases
- Zero cost
- Upgrade only if needed

## Model Selection

### distilgpt2 (Default)
- **Size:** 82M parameters
- **Speed:** Fast
- **Quality:** Good
- **Free Tier:** ✅ Works great
- **Recommended for:** Most users

### gpt2
- **Size:** 124M parameters
- **Speed:** Medium
- **Quality:** Better
- **Free Tier:** ✅ Works (slower)
- **Recommended for:** CPU Upgrade tier

### gpt2-medium
- **Size:** 355M parameters
- **Speed:** Slower
- **Quality:** Great
- **Free Tier:** ⚠️ May timeout
- **Recommended for:** T4 GPU tier

### gpt2-large
- **Size:** 774M parameters
- **Speed:** Slowest
- **Quality:** Best
- **Free Tier:** ❌ Not recommended
- **Recommended for:** T4 GPU tier

## Optimization Tips

### 1. Enable Caching (Default)
Results are cached automatically:
- Same input = instant result
- Reduces compute time
- Saves hardware costs

### 2. Use Smaller Models
For free tier:
```yaml
env:
  DEFAULT_MODEL: distilgpt2
```

### 3. Limit Text Length
Prevent timeouts:
```yaml
env:
  MAX_TEXT_LENGTH: "3000"  # Shorter = faster
```

### 4. Adjust Generation Length
Faster processing:
```yaml
env:
  DEFAULT_MAX_LENGTH: "200"  # Instead of 300
```

## Monitoring

### Check Logs

1. Go to your Space
2. Click "Logs" tab
3. View real-time logs

Look for:
- `INFO` - Normal operations
- `WARNING` - Potential issues
- `ERROR` - Problems to fix

### Usage Stats

HuggingFace provides:
- View count
- Unique visitors
- Uptime status

Available in Space settings.

## Troubleshooting

### Build Fails

**Problem:** Space doesn't build

**Solutions:**
1. Check `requirements.txt` syntax
2. Ensure `app.py` exists
3. Check Logs tab for errors
4. Verify file structure:
   ```
   SPACE_NAME/
   ├── app.py
   ├── requirements.txt
   ├── src/
   │   └── writing_studio/
   │       ├── core/
   │       ├── services/
   │       └── utils/
   ```

### Out of Memory

**Problem:** "CUDA out of memory" or crashes

**Solutions:**
1. Use smaller model:
   ```python
   DEFAULT_MODEL=distilgpt2
   ```
2. Reduce cache size:
   ```python
   CACHE_MAX_SIZE=50
   ```
3. Upgrade to larger hardware tier

### Slow Performance

**Problem:** Analysis takes too long

**Solutions:**
1. First load is always slow (model download)
2. Use distilgpt2 for faster results
3. Upgrade hardware tier
4. Reduce text length
5. Check cache is enabled

### Model Not Found

**Problem:** "Model ... not found"

**Solutions:**
1. Check model name spelling
2. Verify model exists on HuggingFace Hub
3. Try default: `distilgpt2`
4. Check internet connectivity

### Import Errors

**Problem:** "ModuleNotFoundError"

**Solutions:**
1. Ensure all files uploaded
2. Check `src/` directory structure
3. Verify `requirements.txt` has all dependencies
4. Rebuild Space (Settings → Factory reboot)

## Best Practices

### 1. Use README_HF_SPACES.md

Rename to `README.md` in your Space:
```bash
cp README_HF_SPACES.md README.md
```

This provides users with:
- Usage instructions
- Model selection guide
- Troubleshooting help

### 2. Add Examples

In your Space README, add example texts:

````markdown
## Example Usage

Try analyzing this text:

```
The quick brown fox jumps over the lazy dog. This sentence
demonstrates pangram characteristics while maintaining
grammatical coherence.
```
````

### 3. Set Visibility

**Public Spaces:**
- Visible to everyone
- Searchable
- Can be featured
- Free community tier

**Private Spaces:**
- Only visible to you
- Not searchable
- Requires paid tier

### 4. Monitor Costs

If using paid tiers:
1. Go to Settings → Billing
2. Set spending limits
3. Monitor usage
4. Downgrade when not in use

### 5. Update Regularly

Keep your Space updated:
```bash
git pull origin main  # From main repo
git push              # To your Space
```

## Advanced Configuration

### Custom Domain

Point your domain to your Space:
1. Go to Settings
2. Under "Custom domain"
3. Enter your domain
4. Follow DNS instructions

### Gradio Auth

Add simple authentication:

Edit `app.py`:
```python
demo.launch(
    auth=("username", "password"),
    server_name="0.0.0.0",
)
```

### Analytics

Track usage with Gradio analytics:

```python
demo.launch(
    server_name="0.0.0.0",
    analytics_enabled=True,  # HF Spaces analytics
)
```

### Sleep Mode

Free Spaces sleep after 48h inactivity:
- First request wakes it up (~30s)
- Paid tiers can disable sleep

## Comparison: HF Spaces vs Self-Hosted

| Feature | HF Spaces | Self-Hosted |
|---------|-----------|-------------|
| Cost | Free tier available | Server costs |
| Setup | 5 minutes | 30-60 minutes |
| Maintenance | Automatic | Manual |
| Scaling | Auto-scales | Manual |
| SSL/HTTPS | Included | Configure yourself |
| Domain | *.hf.space | Your domain |
| GPU Access | Paid tiers | Need GPU server |
| Monitoring | Built-in | Setup required |
| Uptime | 99.9% | Depends |

## FAQ

### Is HF Spaces free?

Yes, free tier with:
- CPU Basic hardware
- Unlimited builds
- Unlimited users
- Auto-sleep after 48h inactivity

### Can I use private models?

Yes, with HuggingFace Pro:
- Private Spaces
- Private model access
- Gated model support

### How do I update my Space?

```bash
git pull  # Get latest changes
git push  # Deploy to Space
```

Or upload files via web interface.

### Can I monetize my Space?

Yes, with HF Pro:
- Set usage fees
- Subscription model
- Pay-per-use

### What about data privacy?

- Data processed in-memory
- Not stored permanently
- See HF privacy policy
- Use private Spaces for sensitive data

## Resources

- [HuggingFace Spaces Docs](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://gradio.app/docs/)
- [Writing Studio GitHub](https://github.com/yourusername/writing-studio)
- [HuggingFace Community](https://discuss.huggingface.co/)

## Support

Need help?
- [GitHub Issues](https://github.com/yourusername/writing-studio/issues)
- [HF Community Forums](https://discuss.huggingface.co/)
- [Discord](https://discord.gg/huggingface)

## Success Stories

After deploying:
1. Share your Space on social media
2. Add to HuggingFace Papers
3. List in model cards
4. Submit to community showcase

## Next Steps

After successful deployment:

1. **Test Thoroughly**
   - Try all prompt packs
   - Test different models
   - Check error handling

2. **Customize**
   - Update README
   - Add examples
   - Configure settings

3. **Share**
   - Post on social media
   - Add to your website
   - Share with students/colleagues

4. **Monitor**
   - Check logs regularly
   - Monitor usage
   - Gather feedback

5. **Iterate**
   - Fix issues
   - Add features
   - Improve performance

Happy deploying! 🚀