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:

---
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:

---
# 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)

---
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

---
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

---
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

---
fullWidth: true
---

Mini Header

---
header: mini
---

Custom Models/Datasets

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

OAuth Integration

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

Disable Embedding

---
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
• Gradio Spaces Guide
• Hardware Pricing

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.