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!** 🚀