Spaces:

empirenexus
/

WritingStudio

Sleeping

Create a Space
- Go to huggingface.co/new-space
- Name your Space (e.g., "writing-studio")
- Choose Gradio as SDK
- Select visibility (Public or Private)
- Click "Create Space"
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)
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)

Create a Space (as above)

Clone Locally

git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
cd SPACE_NAME

Copy Files

# 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

Push to Space

cd /path/to/SPACE_NAME
git add .
git commit -m "Initial deployment"
git push

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:

Go to their Space
Click "⋯" menu → "Duplicate this Space"
Choose your username and Space name
Click "Duplicate Space"
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:

Go to Settings
Scroll to "Repository secrets"
Add variables:

DEFAULT_MODEL=gpt2
LOG_LEVEL=DEBUG
MAX_TEXT_LENGTH=5000

Option B: Edit .space_config.yml

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:

env:
  DEFAULT_MODEL: distilgpt2

3. Limit Text Length

Prevent timeouts:

env:
  MAX_TEXT_LENGTH: "3000"  # Shorter = faster

4. Adjust Generation Length

Faster processing:

env:
  DEFAULT_MAX_LENGTH: "200"  # Instead of 300

Monitoring

Check Logs

Go to your Space
Click "Logs" tab
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:

Check requirements.txt syntax
Ensure app.py exists
Check Logs tab for errors

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:

Use smaller model:
```
DEFAULT_MODEL=distilgpt2
```
Reduce cache size:
```
CACHE_MAX_SIZE=50
```
Upgrade to larger hardware tier

Slow Performance

Problem: Analysis takes too long

Solutions:

First load is always slow (model download)
Use distilgpt2 for faster results
Upgrade hardware tier
Reduce text length
Check cache is enabled

Model Not Found

Problem: "Model ... not found"

Solutions:

Check model name spelling
Verify model exists on HuggingFace Hub
Try default: distilgpt2
Check internet connectivity

Import Errors

Problem: "ModuleNotFoundError"

Solutions:

Ensure all files uploaded
Check src/ directory structure
Verify requirements.txt has all dependencies
Rebuild Space (Settings → Factory reboot)

Best Practices

1. Use README_HF_SPACES.md

Rename to README.md in your Space:

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:

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

Go to Settings → Billing
Set spending limits
Monitor usage
Downgrade when not in use

5. Update Regularly

Keep your Space updated:

git pull origin main  # From main repo
git push              # To your Space

Advanced Configuration

Custom Domain

Point your domain to your Space:

Go to Settings
Under "Custom domain"
Enter your domain
Follow DNS instructions

Gradio Auth

Add simple authentication:

Edit app.py:

demo.launch(
    auth=("username", "password"),
    server_name="0.0.0.0",
)

Analytics

Track usage with Gradio analytics:

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?

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

Support

Need help?

Success Stories

After deploying:

Share your Space on social media
Add to HuggingFace Papers
List in model cards
Submit to community showcase

Next Steps

After successful deployment:

Test Thoroughly
- Try all prompt packs
- Test different models
- Check error handling
Customize
- Update README
- Add examples
- Configure settings
Share
- Post on social media
- Add to your website
- Share with students/colleagues
Monitor
- Check logs regularly
- Monitor usage
- Gather feedback
Iterate
- Fix issues
- Add features
- Improve performance

Happy deploying! 🚀