QUICKSTART.md

# Quick Start Guide

## 🚀 Get Started in 3 Steps

### Option A: Deploy to Hugging Face Spaces (Recommended)

1. **Create a Space**
   - Go to https://huggingface.co/new-space
   - Name: `ai-text-assistant` (or your choice)
   - SDK: Select "Gradio"
   - Visibility: Public or Private

2. **Upload Files**
   - Upload these files to your Space:
     - `app.py`
     - `requirements.txt`
     - `README.md`
   
   OR clone and push:
   ```bash
   git clone https://huggingface.co/spaces/YOUR_USERNAME/ai-text-assistant
   cd ai-text-assistant
   # Copy app.py, requirements.txt, README.md here
   git add .
   git commit -m "Initial commit"
   git push
   ```

3. **Wait & Use**
   - Space builds automatically (~5-10 min first time)
   - Access at: `https://huggingface.co/spaces/YOUR_USERNAME/ai-text-assistant`
   - Share with others!

### Option B: Run Locally

1. **Install Dependencies**
   ```bash
   pip install -r requirements.txt
   ```

2. **Run the App**
   ```bash
   python app.py
   ```

3. **Open Browser**
   - Navigate to: http://127.0.0.1:7860
   - Models download on first run (~2.5GB total)
   - Subsequent runs use cached models

## 📖 How to Use

1. **Choose Mode**
   - Click "Text Generation" for creative writing
   - Click "Text Summarization" for article summaries

2. **Enter Text**
   - Type or paste your input (max 500 words)
   - For generation: Write a prompt
   - For summarization: Paste an article

3. **Adjust Settings**
   - Use slider to set max tokens (10-500)
   - Higher = longer output

4. **Process**
   - Click "🚀 Process" button
   - Wait for AI to generate (5-30 seconds)

5. **Explore Results**
   - Read the generated/summarized text
   - **Hover over any word** to see:
     - Top 5 alternative tokens
     - Probability percentages

## 💡 Example Inputs

### Text Generation
```
Prompt: "Write a short story about a robot learning to paint"
Max Tokens: 150
```

### Text Summarization
```
Input: [Paste a news article, blog post, or any long text]
Max Tokens: 100
```

## ⚡ Tips for Best Results

### Text Generation
- Start with clear, specific prompts
- Use complete sentences
- Be creative with your prompts
- Higher token count = longer stories

### Text Summarization
- Works best with well-structured articles
- Minimum ~100 words for good summaries
- News articles and blog posts work great
- Academic abstracts summarize well

## 🔧 Troubleshooting

**"Loading models..." takes forever**
- First run downloads ~2.5GB of models
- Be patient, models are cached after
- Check your internet connection

**"Out of memory" error**
- Reduce max_tokens to 50-100
- Close other applications
- Consider using Hugging Face Spaces (cloud hosting)

**Hover tooltips not showing**
- Try a different browser
- Ensure JavaScript is enabled
- Check browser console for errors

**Generation is slow**
- CPU inference is slower than GPU
- On Hugging Face Spaces, upgrade to GPU tier
- Reduce max_tokens for faster results

## 📚 Documentation

- **IMPLEMENTATION_SUMMARY.md** - Complete technical details
- **DEPLOYMENT.md** - Detailed deployment guide
- **APP_FLOW.md** - Visual flow diagrams
- **README.md** - Project overview

## 🎯 What Makes This Special?

**Unique Feature: Token Alternatives Visualization**

Unlike typical AI text tools, this app shows you "behind the scenes" of how the AI thinks:

- Each word you see was chosen from multiple options
- Hover to see what the AI could have said instead
- Learn how language models work
- Understand model confidence through probabilities

Example:
```
Generated: "The quick brown fox"
         
Hover "quick" → Shows: 
  1. quick (45.2%)
  2. fast (23.1%)
  3. speedy (12.0%)
  4. rapid (10.5%)
  5. swift (9.2%)
```

This helps you understand:
- Why the AI chose specific words
- What alternatives were considered
- How confident the AI was in each choice

## 🌟 Have Fun!

Experiment with different:
- Prompts and writing styles
- Text lengths
- Token limits
- Articles from various topics

The more you use it, the better you'll understand how AI language models make decisions!

---

**Need Help?** Check DEPLOYMENT.md for detailed troubleshooting or open an issue on the repository.