HF_SPACES_CONFIGURATION.md

# HuggingFace Spaces Configuration Guide

## Overview

HuggingFace Spaces are configured using **YAML frontmatter** at the top of your `README.md` file. This guide explains how to configure your Writing Studio Space.

## Current Configuration

The `README_HF_SPACES.md` file includes this configuration:

```yaml
---
title: AI Writing Studio
emoji: ✍️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
pinned: false
license: mit
short_description: Production-grade AI writing assistant with real rubric scoring
tags:
  - education
  - writing
  - nlp
  - text-generation
  - analysis
suggested_hardware: cpu-basic
suggested_storage: small
---
```

## Configuration Parameters Explained

### Display Settings

**title**: `AI Writing Studio`
- The name shown in your Space

**emoji**: `✍️`
- Icon displayed with your Space

**colorFrom** / **colorTo**: `blue` → `purple`
- Gradient colors for thumbnail
- Options: red, yellow, green, blue, indigo, purple, pink, gray

**short_description**: Brief description for Space thumbnail

### SDK Configuration

**sdk**: `gradio`
- Must be `gradio` for this app
- Other options: `docker`, `static`

**sdk_version**: `4.0.0`
- Gradio version to use
- Can specify any Gradio version

**app_file**: `app.py`
- Entry point file (relative to repository root)

### Hardware Recommendations

**suggested_hardware**: `cpu-basic`
- Recommended tier for duplicators
- Does NOT automatically assign hardware
- Options:
  - CPU: `cpu-basic`, `cpu-upgrade`
  - GPU: `t4-small`, `t4-medium`, `l4x1`, `l4x4`, `a10g-small`, `a10g-large`, etc.
  - TPU: `v5e-1x1`, `v5e-2x2`, `v5e-2x4`

**suggested_storage**: `small`
- Recommended persistent storage
- Does NOT automatically assign storage
- Options: `small`, `medium`, `large`

### Metadata

**pinned**: `false`
- Whether Space stays on top of your profile

**license**: `mit`
- Software license

**tags**: List of descriptive tags
- `education`, `writing`, `nlp`, `text-generation`, `analysis`
- Helps with discoverability

## Hardware Tiers

### Free Tier (cpu-basic)
- Default for all Spaces
- 2 CPU cores
- 16GB RAM
- Works with distilgpt2
- **Recommended for Writing Studio**

### Paid Tiers

**cpu-upgrade** (~$0.10/hour)
- 4 CPU cores
- 32GB RAM
- Better for gpt2

**t4-small** (~$0.60/hour)
- NVIDIA T4 GPU
- 16GB GPU RAM
- Best performance
- Good for gpt2-medium/large

**Higher tiers available** for more demanding workloads

## Customizing Your Space

### Method 1: Edit YAML Frontmatter

1. Open your Space on HuggingFace
2. Click "Files" tab
3. Edit `README.md`
4. Modify YAML frontmatter
5. Commit changes

Example customizations:

```yaml
---
# Change display
title: My Custom Writing Studio
emoji: 📝
colorFrom: green
colorTo: blue

# Upgrade hardware suggestion
suggested_hardware: t4-small

# Pin to profile
pinned: true
---
```

### Method 2: Environment Variables

For application settings (not Space config), use Settings → Variables:

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

## Common Configurations

### Free Tier Optimized (Default)

```yaml
---
sdk: gradio
sdk_version: 4.0.0
suggested_hardware: cpu-basic
suggested_storage: small
---
```

With environment variables:
```
DEFAULT_MODEL=distilgpt2
ENABLE_CACHE=true
```

### GPU Accelerated

```yaml
---
sdk: gradio
sdk_version: 4.0.0
suggested_hardware: t4-small
suggested_storage: medium
---
```

With environment variables:
```
DEFAULT_MODEL=gpt2-medium
ENABLE_CACHE=true
CACHE_MAX_SIZE=200
```

### High Performance

```yaml
---
sdk: gradio
sdk_version: 4.0.0
suggested_hardware: a10g-small
suggested_storage: large
---
```

With environment variables:
```
DEFAULT_MODEL=gpt2-large
ENABLE_CACHE=true
CACHE_MAX_SIZE=500
```

## Advanced Options

### Full-Width Display

```yaml
---
fullWidth: true
---
```

### Mini Header

```yaml
---
header: mini
---
```

### Custom Models/Datasets

```yaml
---
models:
  - distilgpt2
  - gpt2
datasets:
  - your-dataset-name
---
```

### OAuth Integration

```yaml
---
hf_oauth: true
hf_oauth_scopes:
  - read-repos
  - write-repos
hf_oauth_expiration_minutes: 480
---
```

### Disable Embedding

```yaml
---
disable_embedding: true
---
```

## Environment Variables Reference

These go in Space Settings → Variables, NOT in YAML:

| Variable | Default | Description |
|----------|---------|-------------|
| `ENVIRONMENT` | `production` | Runtime environment |
| `DEBUG` | `false` | Debug mode |
| `LOG_LEVEL` | `INFO` | Logging level |
| `DEFAULT_MODEL` | `distilgpt2` | HuggingFace model ID |
| `MAX_TEXT_LENGTH` | `10000` | Max input characters |
| `ENABLE_CACHE` | `true` | Enable result caching |
| `CACHE_MAX_SIZE` | `100` | Cache entry limit |
| `ENABLE_METRICS` | `false` | Prometheus metrics |
| `LOG_FORMAT` | `text` | Log format (json/text) |

## Troubleshooting

### Configuration Not Applied

1. Check YAML syntax (spaces matter!)
2. Ensure YAML is at top of README.md
3. Must be between `---` delimiters
4. Commit changes and wait for rebuild

### Hardware Not Changed

- `suggested_hardware` is only a suggestion
- Doesn't automatically assign hardware
- Users must manually select tier in Settings
- Useful for Spaces meant to be duplicated

### Environment Variables Not Working

- Set in Settings → Variables (not in YAML)
- May need to restart Space
- Check logs for confirmation

## Best Practices

1. **Start with defaults** - They work well for most cases
2. **Test locally first** - `python app.py`
3. **Use free tier initially** - Upgrade only if needed
4. **Set suggested_hardware** - Helps duplicators
5. **Add descriptive tags** - Improves discoverability
6. **Write good short_description** - Shows in thumbnail
7. **Keep emoji relevant** - Helps users identify your Space

## Resources

- [Official Spaces Config Docs](https://huggingface.co/docs/hub/spaces-config-reference)
- [Gradio Spaces Guide](https://huggingface.co/docs/hub/spaces-sdks-gradio)
- [Hardware Pricing](https://huggingface.co/pricing#spaces)

## Quick Reference

**Minimal Configuration:**
```yaml
---
title: AI Writing Studio
sdk: gradio
app_file: app.py
---
```

**Recommended Configuration:**
```yaml
---
title: AI Writing Studio
emoji: ✍️
sdk: gradio
sdk_version: 4.0.0
app_file: app.py
suggested_hardware: cpu-basic
license: mit
---
```

**Full Configuration:**
See `README_HF_SPACES.md` for complete example.