---
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: AI writing revision with FLAN-T5 and rubric scoring
tags:
  - education
  - writing
  - nlp
  - text2text-generation
  - instruction-following
  - analysis
suggested_hardware: cpu-basic
suggested_storage: small
---

# Writing Studio - HuggingFace Spaces Edition

Production-grade AI Writing Studio powered by **FLAN-T5** for intelligent text revision.

## About

AI Writing Studio is a production-grade educational writing assistant that provides **real AI-powered text revision** using instruction-following models:

- **🤖 AI-Powered Revision** using FLAN-T5 (instruction-tuned for text revision)
- **📊 Real Rubric Scoring** across 5 criteria (Clarity, Conciseness, Organization, Evidence, Grammar)
- **🔍 Visual Diff Highlighting** to see exactly what changed
- **📝 5 Specialized Modes** (General, Literature, Tech Comm, Academic, Creative)

## 🆕 What's New: FLAN-T5 Integration

**Major Update**: Replaced GPT-2 with FLAN-T5 for **real AI-powered text revision**.

**What Changed**:
- ✅ **FLAN-T5** now default model (instruction-following, actually revises text)
- ❌ **GPT-2 removed** (only continues text, doesn't revise)
- 🎯 **Instruction-optimized prompts** for better revision quality
- 🚀 **Automatic model detection** (supports both T5 and GPT-2 pipelines)

**Why This Matters**:
GPT-2 couldn't revise text—it only continued it with unrelated content. FLAN-T5 understands revision instructions and produces genuine improvements to your writing.

**Trade-off**: First load is ~60s instead of ~30s, but you get actual AI revision instead of gibberish!

## Quick Start

1. Open the app on HuggingFace Spaces
2. Paste text (200-500 words recommended for first try)
3. Choose revision mode (try "General" first)
4. Click "✨ Revise & Analyze"
5. Wait ~60s for first analysis (model loading)
6. Compare original vs AI-revised text
7. Review rubric scores and highlighted changes

## Features

### ✨ AI-Powered Revision with FLAN-T5

**Why FLAN-T5?**
FLAN-T5 is an **instruction-tuned model** specifically trained to follow revision instructions. Unlike GPT-2 (which only continues text), FLAN-T5 actually understands and executes revision tasks like:
- Improving clarity and readability
- Enhancing academic tone
- Strengthening evidence and support
- Refining technical precision
- Enriching creative imagery

**Real Text Revision**: The AI doesn't just continue your text—it genuinely revises it based on the selected mode.

### 📊 Real Rubric Analysis
Unlike simple prototypes, this version includes actual analysis algorithms:
- **Clarity**: Analyzes sentence length, complexity, and structure
- **Conciseness**: Detects wordy phrases and redundancy
- **Organization**: Checks paragraph structure and transitions
- **Evidence**: Looks for supporting examples and data
- **Grammar**: Basic error detection

### 📝 5 Specialized Revision Modes
Choose from instruction-tuned templates optimized for FLAN-T5:
- **General**: Improve clarity and readability for everyday writing
- **Literature**: Strengthen literary analysis with better evidence and terminology
- **Tech Comm**: Enhance technical precision and professional tone
- **Academic**: Improve formal tone, organization, and scholarly voice
- **Creative**: Enhance imagery, voice, and reader engagement

### 🔍 Visual Diff Highlighting
See exactly what the AI changed with side-by-side comparison and highlighted differences.

### 🏭 Production Quality
- Comprehensive error handling
- Input validation and sanitization
- Structured logging
- Intelligent caching for faster responses
- Type-safe configuration with Pydantic
- Automatic model type detection

## Usage

1. **Paste your text** in the input box (up to 10,000 characters)
2. **Choose a revision mode** matching your writing context (General, Literature, Tech Comm, Academic, Creative)
3. **Click "✨ Revise & Analyze"** to get AI revision + rubric feedback
4. **Review results**: Compare original vs revised text, check rubric scores, view highlighted changes

### Tips

- **First analysis takes ~60 seconds** (FLAN-T5 model loading) - this is normal!
- **Subsequent analyses are much faster** (~5-10s) thanks to caching
- Start with shorter texts (200-500 words) for quicker results
- Try different revision modes to see how the AI adapts its approach
- Use the rubric feedback to understand what improved
- The diff view shows exactly what changed and why

## Models

### Default: google/flan-t5-base

**Why FLAN-T5?**
FLAN-T5 (Fine-tuned Language Net) is an **instruction-following model** from Google Research, specifically designed to understand and execute text revision tasks. This is fundamentally different from GPT-2 style models:

| Feature | FLAN-T5 (Current) | GPT-2 (Previous) |
|---------|------------------|------------------|
| **Task Type** | Instruction following | Text continuation |
| **Can Revise Text?** | ✅ Yes | ❌ No (only continues) |
| **Understands Instructions?** | ✅ Yes | ❌ No |
| **Works with Revision Modes?** | ✅ Yes | ❌ No |
| **Model Size** | ~250M parameters | ~124M parameters |
| **First Load Time** | ~60s | ~30s |
| **Quality** | High (task-specific) | Low (off-task) |

**FLAN-T5 Advantages:**
- ✅ Actually revises text (not just continuation)
- ✅ Follows mode-specific instructions (General, Academic, etc.)
- ✅ Produces contextually appropriate output
- ✅ Understands the task at hand

**Why Not GPT-2?**
GPT-2 and distilgpt2 are **autoregressive text generators** trained only to continue text. When given revision instructions, they ignore them and generate unrelated continuations. FLAN-T5 was explicitly trained on instruction-following tasks, making it ideal for text revision.

### Alternative Models (Advanced)

You can change the model in the UI, but these require more resources:

**google/flan-t5-large** (780M params)
- Better revision quality
- Requires CPU upgrade or GPU
- ~2-3 minutes first load

**google/flan-t5-xl** (3B params)
- Best quality revisions
- Requires T4 GPU on HF Spaces
- ~5 minutes first load

## Performance

### Hardware Recommendations

**Free Tier (CPU Basic)** ⭐ Recommended
- Works well with **google/flan-t5-base**
- First load: ~60 seconds (model download + initialization)
- Subsequent analyses: ~5-10 seconds
- Perfect for educational use and demos

**CPU Upgrade**
- Handles **google/flan-t5-large** comfortably
- First load: ~2-3 minutes
- Subsequent: ~10-15 seconds
- Better revision quality

**T4 GPU** ⚡ Best Performance
- Runs **google/flan-t5-xl** smoothly
- First load: ~5 minutes
- Subsequent: ~3-5 seconds
- Highest quality revisions

### FLAN-T5 vs GPT-2 Performance

FLAN-T5 is slightly larger than distilgpt2, but the quality difference is dramatic:
- FLAN-T5: Slower but **actually revises text correctly**
- GPT-2: Faster but **produces unusable output** (wrong task)

**The extra 30 seconds of load time is worth it for functional AI revision!**

### Optimization

The app includes production-grade optimizations:
- **Model caching**: Loaded once, reused for all requests
- **Result caching**: Same input = instant cached response
- **Intelligent pipeline selection**: Automatically uses correct pipeline for model type
- **Lazy loading**: Services initialized only when needed
- **Efficient text processing**: Minimizes unnecessary operations

## Configuration

The app works out-of-the-box with sensible defaults optimized for FLAN-T5. To customize, you can set environment variables in your HuggingFace Space settings.

### Available Environment Variables

```bash
# Model Configuration
DEFAULT_MODEL=google/flan-t5-base  # HuggingFace model ID (use FLAN-T5 variants)
MAX_MODEL_LENGTH=512               # Maximum model input/output length
DEFAULT_MAX_LENGTH=512             # Default generation length

# Application Settings
ENVIRONMENT=production             # Runtime environment (development/staging/production)
LOG_LEVEL=INFO                     # Logging level (DEBUG/INFO/WARNING/ERROR)
LOG_FORMAT=text                    # Log format (json/text) - text is easier on HF Spaces
MAX_TEXT_LENGTH=10000              # Maximum input text length

# Performance
ENABLE_CACHE=true                  # Enable result caching
CACHE_MAX_SIZE=100                 # Maximum cache entries
ENABLE_METRICS=false               # Disable metrics server on HF Spaces

# Features
ENABLE_DIFF_HIGHLIGHTING=true      # Enable visual diff view
ENABLE_RUBRIC_SCORING=true         # Enable rubric analysis
ENABLE_PROMPT_PACKS=true           # Enable revision mode selection
```

## Troubleshooting

### "Out of Memory" Error
**Problem**: Space crashes or shows OOM error
**Solutions**:
- ✅ Stick with `google/flan-t5-base` on free tier (works well)
- ✅ Reduce input text length (try 200-500 words)
- ✅ Upgrade to CPU upgrade tier for larger models
- ❌ Don't try flan-t5-large or flan-t5-xl without GPU

### Slow First Load (~60 seconds)
**This is normal!** FLAN-T5-base is ~250M parameters.
- First analysis: ~60s (model download + initialization)
- Subsequent: ~5-10s (model cached in memory)
- If it times out: Refresh and try again (HF Spaces issue)

### "Model Loading Failed"
**Problem**: Error during model initialization
**Solutions**:
- Check model name spelling (must be exact HuggingFace ID)
- Ensure internet connectivity for model download
- Try default: `google/flan-t5-base`
- Check HF Spaces logs for specific error

### AI Revision Doesn't Make Sense
**Problem**: Revision output is garbled or off-topic
**Solutions**:
- ✅ Make sure you're using FLAN-T5 (not GPT-2!)
- ✅ Try a different revision mode (General, Academic, etc.)
- ✅ Check input text is clear and well-formed
- ✅ Try shorter input text (model has 512 token limit)
- Remember: FLAN-T5 base is small; larger models (flan-t5-large) give better results

### "Text Generation Failed"
**Problem**: Error during AI revision generation
**Solutions**:
- Input too long (try shorter text)
- Model timeout (refresh and retry)
- Check HF Spaces status (temporary service issue)

## Privacy

- Text processed in-memory only
- Results cached temporarily for speed
- No long-term storage on HF Spaces
- No user tracking

## Technical Details

### How FLAN-T5 Integration Works

The app automatically detects model type and uses the appropriate pipeline:

**For FLAN-T5 models** (text2text-generation):
```python
# Detects 't5' or 'flan' in model name
pipeline("text2text-generation", model="google/flan-t5-base")
```

**For GPT-2 models** (text-generation):
```python
# Fallback for text continuation models
pipeline("text-generation", model="gpt2")
```

**Instruction-Following Prompts**:
FLAN-T5 requires structured instruction format:
```
Revise the following text to improve clarity, conciseness, and readability.
Make it clear and easy to understand while maintaining the original meaning.

Text: [user input]

Revised text:
```

This format tells FLAN-T5 exactly what to do, resulting in actual revisions instead of text continuation.

### Architecture

**Production-Grade Layered Design**:
```
src/writing_studio/
├── core/
│   ├── analyzer.py      # Main orchestrator
│   ├── config.py        # Pydantic settings (FLAN-T5 defaults)
│   └── exceptions.py    # Custom error types
├── services/
│   ├── model_service.py    # FLAN-T5 pipeline management
│   ├── prompt_service.py   # Instruction-following prompts
│   ├── rubric_service.py   # Rule-based scoring algorithms
│   └── diff_service.py     # Visual diff generation
├── utils/
│   ├── logging.py       # Structured logging
│   ├── validation.py    # Input sanitization
│   └── metrics.py       # Prometheus metrics
└── app.py               # HuggingFace Spaces entry point
```

## Source Code

Full source code available at: [GitHub Repository](https://github.com/yourusername/writing-studio)

### Local Development

```bash
git clone https://github.com/yourusername/writing-studio
cd writing-studio
pip install -r requirements.txt
python app.py
```

## Contributing

Contributions welcome! See [GitHub](https://github.com/yourusername/writing-studio) for:
- Full documentation
- Development setup
- Testing guidelines
- Code quality standards

## License

MIT License - See LICENSE file

## Acknowledgments

- **FLAN-T5**: [google/flan-t5-base](https://huggingface.co/google/flan-t5-base) by Google Research
- Built with [Gradio](https://gradio.app/) - Python web UI for ML
- Powered by [HuggingFace Transformers](https://huggingface.co/transformers/) - State-of-the-art NLP
- Hosted on [HuggingFace Spaces](https://huggingface.co/spaces) - Free ML app hosting
- Instruction-tuning research: [FLAN paper](https://arxiv.org/abs/2210.11416)

## Support

Need help?
- Issues: [GitHub Issues](https://github.com/yourusername/writing-studio/issues)
- Documentation: [GitHub Docs](https://github.com/yourusername/writing-studio/tree/main/docs)
- Questions: [GitHub Discussions](https://github.com/yourusername/writing-studio/discussions)