python-server/QUICKSTART.md

# 🚀 Quick Start: FREE AI Alt Text Generation

## 2-Minute Setup (100% FREE!)

### Step 1: Install Dependencies
```bash
cd "Cycle 2 Testing/Accessibility-Checker-BE/python-server"
pip install -r requirements.txt
```

**That's it!** No configuration needed. The system works with smart defaults.

**First run note**: The AI model downloads ~1-2GB (one time only, then cached)

### Step 2: Start the Server
```bash
python server2.py
```

Look for: `✅ Local AI vision model loaded (BLIP - 100% FREE, No Costs)`

### Step 3: Test It!
Upload a PowerPoint through the frontend. The system will:
- ✅ Analyze accessibility issues  
- ✅ Generate AI alt text for images **using FREE local AI**
- ✅ Create a remediated file for download
- ✅ **Zero API costs, zero API keys needed!**

### Optional: Customize Settings
If you want to change settings (like using a different AI model):
```bash
cp .env.example .env
# Edit .env with any text editor to customize
```

**But don't worry** - the system works perfectly without .env! It's completely optional.

---

## What's New?

### Before (Placeholder Alt Text)
```
"Image on slide 3"
"decorative"
```

### After (FREE AI-Generated Alt Text)
```
"Bar chart with four colored bars showing increasing values"
"Person standing at whiteboard presenting to seated audience"
"Company logo with red and blue colors"
```

---

## How It Works

### 🆓 The Only Option: Local BLIP Model (100% FREE!)

**Local BLIP AI Model**
- ✅ **100% Free, unlimited usage**
- ✅ Runs on your computer (offline after first download)
- ✅ No internet required for processing
- ✅ No API keys needed
- ✅ No account creation
- ✅ No surprise billing - ever!
- ✅ Fast and good quality (7/10)
- ⬇️ ~1GB download on first run
- ⚡ Instant on subsequent runs

## Why This Setup?

All OpenAI references have been **completely removed** from the project to eliminate any possibility of surprise billing. The free local AI model is:

- **Good enough** - Works great for academic projects
- **Cost effective** - $0 per image vs $0.17 with paid APIs
- **Simple** - No configuration needed
- **Safe** - Runs on your own computer, no data sent anywhere
---

## Configuration (100% Optional!)

### Why no .env file is needed

The system works perfectly with smart defaults:
- ✅ Uses local BLIP model automatically
- ✅ Enables AI alt text generation
- ✅ No API keys to configure

**Just install and run - that's it!**

### Optional: Customize (Create .env)

If you want to change settings, copy the template:

```bash
# Copy template
cp .env.example .env

# Edit with your preferred editor
# Optional settings you might change:
LOCAL_VISION_MODEL=blip-base      # Use blip-large for better quality
ENABLE_AI_ALT_TEXT=true           # Set to false to disable AI (for debugging)
```

**See `ENV_FILE_GUIDE.md` for complete .env documentation.**

---

## Server Console Output

When everything is working:

```
✅ Local AI vision model loaded (BLIP - 100% FREE, No Costs)
🚀 Starting alt text remediation for: document.pptx
   AI Mode: LOCAL (100% FREE - No Costs)
🤖 Using FREE local AI (BLIP) for slide 1
  ✅ AI generated alt text for Picture 1: 'Professional man in business suit...'
✅ Remediation complete: 3 images processed
   🤖 3 alt texts generated by FREE local AI (no cost)
```

---

## Troubleshooting

### Problem: Slow download on first run
**Explanation**: System is downloading BLIP AI model (~1-2GB)
**Solution**: This only happens once. Subsequent runs are instant. Be patient!
**Time estimate**: 5-15 minutes depending on internet

### Problem: "transformers not installed"
**Solution**: 
```bash
pip install -r requirements.txt
```

### Problem: "ModuleNotFoundError: No module named 'local_vision'"
**Solution**: Make sure you're running from the `python-server/` directory
```bash
cd python-server
python server2.py
```

### Problem: Out of memory errors
**Solution**: Close other programs or use smaller model
```bash
# In .env:
LOCAL_VISION_MODEL=blip-base
```

### Problem: Alt text not being generated
**Check the console output**:
1. Does it show "✅ Local AI vision model loaded"? 
2. Are images in supported formats (PNG, JPG, GIF)?
3. Is `ENABLE_AI_ALT_TEXT` set to true?

**Run diagnostics**:
```bash
python test_ai_setup.py
```

### Problem: "This model requires transformers version X.X"
**Solution**:
```bash
pip install --upgrade transformers torch
```

---

## Cost: FREE Forever!

| Item | Cost |
|------|------|
| Local BLIP AI Model | $0 |
| First download (one-time) | $0 |
| Unlimited alt text generation | $0 |
| Monthly hosting | $0 (free tier) |
| **Total for entire team** | **$0 forever** |

**Compared to alternatives**:
- OpenAI: ~$0.17/image = $5-10 per presentation
- Google Vision: $1.50/100 images
- Azure: $1/$5/10 per 1000 requests
- **Our solution**: $0 per anything! 🎉

---

## Documentation

For more detailed information, see:

- **ENV_FILE_GUIDE.md** - Complete .env explanation (optional)
- **OPENAI_REMOVAL_COMPLETE.md** - Why OpenAI was removed for safety
- **AI_ALT_TEXT_SETUP.md** - Deep technical documentation
- **STUDENT_SETUP.md** - Student-friendly setup guide
- **FREE_AI_OPTIONS.md** - Comparison of all free alternatives

---

## Summary

✅ **Fastest Setup**:
```bash
pip install -r requirements.txt
python server2.py
```

✅ **No Configuration Needed**: Works with defaults

✅ **100% FREE**: No API keys, no monthly bills, no surprises

✅ **High Quality**: BLIP model produces excellent alt text descriptions

✅ **Easy to Use**: Upload PowerPoint, download fixed version

✅ **For Students**: Zero cost, zero complexity

**Ready to generate alt text for your presentations!** 🚀