docs/API_KEYS.md

# 🔑 VisionQ - API Keys & Authentication

## 🎯 Quick Answer

**Do you need API keys for VisionQ?**

# **NO!** ❌

VisionQ works **100% offline** without any API keys.

---

## ✅ What Works Without API Keys

All core features work without any authentication:

| Feature | Model | API Key Needed? |
|---------|-------|-----------------|
| **Object Detection** | YOLO/SSD | ❌ No |
| **Image Captioning** | BLIP | ❌ No |
| **Visual Embeddings** | CLIP | ❌ No |
| **OCR (90+ languages)** | EasyOCR | ❌ No |
| **Text Embeddings** | sentence-transformers | ❌ No |
| **Vector Search** | FAISS | ❌ No |
| **Intent Classification** | DistilBERT | ❌ No |
| **Speech Recognition** | Vosk | ❌ No |
| **Text-to-Speech** | pyttsx3 | ❌ No |

**Everything runs locally on your machine!**

---

## 🔓 Optional: Hugging Face Token

### **When You Might Need It**

A Hugging Face token is **optional** and only needed for:

1. **Private Models** - Models you've created and marked private
2. **Gated Models** - Some models require accepting terms
3. **Higher Rate Limits** - Faster model downloads
4. **Enterprise Features** - Advanced Hugging Face features

### **VisionQ Default Models**

All default models in VisionQ are **public and free**:

- ✅ `Salesforce/blip-image-captioning-base` - Public
- ✅ `openai/clip-vit-base-patch32` - Public
- ✅ `typeform/distilbert-base-uncased-mnli` - Public
- ✅ `all-MiniLM-L6-v2` - Public

**No token needed!**

---

## 🔧 How to Add Hugging Face Token (Optional)

### **Step 1: Get Token**

1. Go to https://huggingface.co/
2. Create free account (if you don't have one)
3. Go to Settings → Access Tokens
4. Click "New token"
5. Select "Read" access
6. Copy token

### **Step 2: Add to VisionQ**

**Method 1: Environment Variable (Recommended)**

Create `.env` file in project root:

```bash
HUGGINGFACE_TOKEN=hf_your_token_here
```

**Method 2: Direct Configuration**

Edit `config/settings.py`:

```python
HUGGINGFACE_TOKEN = "hf_your_token_here"
```

**Method 3: System Environment**

Windows:
```cmd
setx HUGGINGFACE_TOKEN "hf_your_token_here"
```

Linux/Mac:
```bash
export HUGGINGFACE_TOKEN="hf_your_token_here"
```

### **Step 3: Restart VisionQ**

Token will be automatically used for model downloads.

---

## 🌐 Internet Connection

### **First Run**

**Internet required** to download models (~2GB):

- YOLO weights (~50MB)
- BLIP model (~1GB)
- CLIP model (~500MB)
- DistilBERT (~250MB)
- EasyOCR languages (~50MB each)

**Download happens once** - models are cached locally.

### **Subsequent Runs**

**No internet required!** All models run offline.

---

## 🔒 Privacy & Security

### **Data Privacy**

- ✅ **No data sent to cloud**
- ✅ **All processing local**
- ✅ **No telemetry**
- ✅ **No tracking**
- ✅ **Memories stored locally**

### **Model Security**

- ✅ Models from trusted sources (Hugging Face, Ultralytics)
- ✅ Open-source and auditable
- ✅ No backdoors or malware
- ✅ Community-verified

### **Token Security**

If you use a Hugging Face token:

- ✅ Store in `.env` file (not in code)
- ✅ Add `.env` to `.gitignore`
- ✅ Use "Read" access only
- ✅ Revoke if compromised

---

## 🚫 What VisionQ Does NOT Need

| Service | Needed? | Why Not? |
|---------|---------|----------|
| OpenAI API | ❌ No | Using open-source models |
| Google Cloud Vision | ❌ No | Using local YOLO/BLIP |
| AWS Rekognition | ❌ No | Using local models |
| Azure Computer Vision | ❌ No | Using local models |
| Anthropic API | ❌ No | Using local models |
| Cohere API | ❌ No | Using local models |

**VisionQ is 100% self-contained!**

---

## 📊 Comparison: Cloud vs Local

### **Cloud-Based (Other Solutions)**

```
❌ Requires API keys
❌ Costs money per request
❌ Needs internet connection
❌ Data sent to cloud
❌ Privacy concerns
❌ Rate limits
❌ Vendor lock-in
```

### **VisionQ (Local)**

```
✅ No API keys needed
✅ Completely free
✅ Works offline
✅ Data stays local
✅ Full privacy
✅ No rate limits
✅ Open source
```

---

## 🎓 Model Sources

All models are from trusted open-source repositories:

### **Hugging Face Models**

- **BLIP:** https://huggingface.co/Salesforce/blip-image-captioning-base
- **CLIP:** https://huggingface.co/openai/clip-vit-base-patch32
- **DistilBERT:** https://huggingface.co/typeform/distilbert-base-uncased-mnli
- **MiniLM:** https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2

### **Other Sources**

- **YOLO:** https://github.com/ultralytics/ultralytics
- **EasyOCR:** https://github.com/JaidedAI/EasyOCR
- **FAISS:** https://github.com/facebookresearch/faiss
- **Vosk:** https://alphacephei.com/vosk/

All are **free, open-source, and require no API keys!**

---

## 🔧 Troubleshooting

### **"Model download failed"**

1. Check internet connection
2. Try again (downloads can be interrupted)
3. Clear cache: `rm -rf ~/.cache/huggingface/`
4. Use VPN if blocked in your region

### **"Authentication required"**

This should **never happen** with default VisionQ models.

If it does:
1. Check you're using default models
2. Verify model names in `config/settings.py`
3. Try adding Hugging Face token (optional)

### **"Rate limit exceeded"**

This only happens during model downloads if you download too many models quickly.

Solutions:
1. Wait a few minutes
2. Add Hugging Face token (increases limits)
3. Download models one at a time

---

## 📚 FAQ

### **Q: Do I need to pay for anything?**

**A:** No! VisionQ is completely free. All models are open-source and free to use.

### **Q: Can I use VisionQ commercially?**

**A:** Yes! All models have permissive licenses (MIT, Apache 2.0, etc.). Check individual model licenses for details.

### **Q: Will VisionQ always be free?**

**A:** Yes! It's open-source and runs locally. No cloud costs, no subscriptions.

### **Q: What about GPU usage?**

**A:** VisionQ works on CPU (free). GPU is optional for faster processing.

### **Q: Do I need a Hugging Face account?**

**A:** No! Only needed if you want to use private/gated models.

### **Q: Can I use my own models?**

**A:** Yes! Edit `config/settings.py` to point to your models.

---

## ✅ Summary

**VisionQ requires:**
- ✅ Python 3.8+
- ✅ ~2GB disk space (for models)
- ✅ Internet (first run only)
- ✅ Webcam (for vision features)

**VisionQ does NOT require:**
- ❌ API keys
- ❌ Cloud accounts
- ❌ Subscriptions
- ❌ Payment
- ❌ Internet (after first run)

**100% free, 100% local, 100% private! 🔒**

---

## 📞 Support

**Questions about API keys?**

Check:
1. This document
2. `README.md`
3. `.env.example` file
4. `config/settings.py`

**Still have questions?**

Open an issue on GitHub or check the documentation.

---

**VisionQ - Powerful AI without the API hassle! 🚀**