docs/STRUCTURE.md

# 📂 VisionQ - Project Structure

## 🎯 Clean & Organized Structure

```
VisionQ/
│
├── 📁 agents/                  # AI Agents (Core Logic)
│   ├── __init__.py
│   ├── voice_agent.py         # Voice I/O (STT + TTS)
│   ├── vision_agent.py        # Vision coordinator
│   ├── caption_agent.py       # Image captioning (BLIP)
│   ├── embedding_agent.py     # Visual embeddings (CLIP)
│   ├── ocr_agent.py          # Text extraction (EasyOCR)
│   ├── memory_agent.py        # Storage (JSON + FAISS)
│   └── query_agent.py         # Smart retrieval (DistilBERT)
│
├── 📁 config/                  # Configuration
│   └── settings.py            # Centralized settings
│
├── 📁 ui/                      # Web Interface
│   └── app.py                 # Streamlit application
│
├── 📁 data/                    # Storage (auto-created)
│   ├── memory.json            # Memory metadata
│   ├── memory.faiss           # Vector index
│   └── visionq.log            # Application logs
│
├── 📁 models/                  # AI Models (auto-downloaded)
│   ├── vosk/                  # Speech recognition
│   └── piper/                 # Neural TTS (optional)
│
├── 📁 docs/                    # Documentation
│   ├── LANGUAGES.md           # Language support (90+)
│   └── API_KEYS.md            # API keys info (none needed!)
│
├── 📁 core/                    # Core Integration
│   ├── __init__.py
│   └── fusion_layer.py        # Multimodal fusion
│
├── 📁 .streamlit/              # Streamlit Config
│   └── config.toml            # UI theme & settings
│
├── 📁 archive/                 # Old Files (after cleanup)
│   ├── old_agents/
│   ├── old_docs/
│   └── old_scripts/
│
├── 📄 README.md                # Main documentation
├── 📄 requirements.txt         # Dependencies
├── 📄 .env.example             # Environment template
├── 📄 .gitignore               # Git ignore rules
├── 📄 run.bat                  # Quick launcher (Windows)
├── 📄 cleanup.bat              # Project cleanup script
└── 📄 LICENSE                  # MIT License

```

---

## 📋 File Descriptions

### **Core Agents (`agents/`)**

| File | Purpose | Lines | Key Features |
|------|---------|-------|--------------|
| `voice_agent.py` | Voice I/O | ~200 | Vosk STT, Voxtral/pyttsx3 TTS, fallback |
| `vision_agent.py` | Vision hub | ~250 | YOLO/SSD, coordinates all vision agents |
| `caption_agent.py` | Captioning | ~50 | BLIP image-to-text |
| `embedding_agent.py` | Embeddings | ~60 | CLIP visual embeddings |
| `ocr_agent.py` | Text extraction | ~80 | EasyOCR, 90+ languages |
| `memory_agent.py` | Storage | ~200 | JSON + FAISS hybrid storage |
| `query_agent.py` | Retrieval | ~180 | DistilBERT NLP, hybrid search |

### **Configuration (`config/`)**

| File | Purpose | Lines | Key Features |
|------|---------|-------|--------------|
| `settings.py` | Central config | ~200 | All settings, feature flags, paths |

### **User Interface (`ui/`)**

| File | Purpose | Lines | Key Features |
|------|---------|-------|--------------|
| `app.py` | Streamlit UI | ~400 | Web interface, 4 tabs, interactive |

### **Integration (`core/`)**

| File | Purpose | Lines | Key Features |
|------|---------|-------|--------------|
| `fusion_layer.py` | Multimodal fusion | ~80 | Combines caption + OCR + embeddings |

### **Documentation (`docs/`)**

| File | Purpose | Pages |
|------|---------|-------|
| `LANGUAGES.md` | Language support | 5 |
| `API_KEYS.md` | API keys info | 4 |

### **Root Files**

| File | Purpose |
|------|---------|
| `README.md` | Main documentation |
| `requirements.txt` | Python dependencies |
| `.env.example` | Environment template |
| `.gitignore` | Git ignore rules |
| `run.bat` | Quick launcher |
| `cleanup.bat` | Cleanup script |
| `LICENSE` | MIT License |

---

## 🎯 Design Principles

### **1. Modularity**
- Each agent is independent
- Clear separation of concerns
- Easy to extend/modify

### **2. Configuration**
- Centralized in `config/settings.py`
- Environment variables supported
- Feature flags for easy toggling

### **3. User-Friendly**
- Streamlit UI for easy testing
- One-click launcher (`run.bat`)
- Clear documentation

### **4. Clean Structure**
- No redundant files
- Logical folder organization
- Archive for old files

---

## 📊 File Statistics

### **Code Files**

| Category | Files | Lines | Size |
|----------|-------|-------|------|
| Agents | 7 | ~1,100 | ~40KB |
| Config | 1 | ~200 | ~8KB |
| UI | 1 | ~400 | ~15KB |
| Core | 1 | ~80 | ~3KB |
| **Total** | **10** | **~1,780** | **~66KB** |

### **Documentation**

| Category | Files | Pages | Size |
|----------|-------|-------|------|
| Main | 1 | 3 | ~15KB |
| Guides | 2 | 9 | ~40KB |
| **Total** | **3** | **12** | **~55KB** |

### **Total Project**

- **Code Files:** 10
- **Documentation:** 3
- **Config Files:** 4
- **Total Lines:** ~2,000
- **Total Size:** ~120KB (excluding models)

---

## 🔄 Data Flow

```
User Input (UI/Voice)
    ↓
Vision Agent (Hub)
    ├─► YOLO/SSD → Objects
    ├─► BLIP → Caption
    ├─► CLIP → Embeddings
    └─► OCR → Text
    ↓
Fusion Layer
    ↓
Memory Agent (Storage)
    ├─► JSON (metadata)
    └─► FAISS (vectors)
    ↓
Query Agent (Retrieval)
    ├─► DistilBERT (intent)
    ├─► FAISS (similarity)
    └─► Time filter
    ↓
Response (UI/Voice)
```

---

## 🗂️ Directory Purposes

### **`agents/`** - AI Agents
**Purpose:** Core AI functionality  
**Contains:** All intelligent agents  
**Modify:** To change AI behavior

### **`config/`** - Configuration
**Purpose:** Centralized settings  
**Contains:** All configuration  
**Modify:** To customize behavior

### **`ui/`** - User Interface
**Purpose:** Web interface  
**Contains:** Streamlit app  
**Modify:** To change UI

### **`core/`** - Integration
**Purpose:** Multimodal fusion  
**Contains:** Integration logic  
**Modify:** To change fusion

### **`data/`** - Storage
**Purpose:** Persistent data  
**Contains:** Memories, logs  
**Modify:** Never (auto-managed)

### **`models/`** - AI Models
**Purpose:** Model storage  
**Contains:** Downloaded models  
**Modify:** Never (auto-managed)

### **`docs/`** - Documentation
**Purpose:** User guides  
**Contains:** Documentation  
**Modify:** To update docs

### **`archive/`** - Old Files
**Purpose:** Backup  
**Contains:** Old/deprecated files  
**Modify:** Can delete if not needed

---

## 🚀 Quick Navigation

### **Want to...**

**...change settings?**
→ `config/settings.py`

**...modify UI?**
→ `ui/app.py`

**...add new agent?**
→ Create in `agents/` folder

**...change OCR languages?**
→ `config/settings.py` → `OCR_CONFIG`

**...see memories?**
→ `data/memory.json`

**...check logs?**
→ `data/visionq.log`

**...understand languages?**
→ `docs/LANGUAGES.md`

**...learn about API keys?**
→ `docs/API_KEYS.md`

---

## 🧹 Cleanup Process

### **Before Cleanup**
```
VisionQ/
├── agents/ (new)
├── config/ (new)
├── ui/ (new)
├── caption_agent.py (old)
├── memory_agent.py (old)
├── vision_agent.py (old)
├── main.py (old)
├── main_upgraded.py (old)
└── ... (many old files)
```

### **After Cleanup**
```
VisionQ/
├── agents/ (clean)
├── config/ (clean)
├── ui/ (clean)
├── data/ (clean)
├── docs/ (clean)
├── archive/ (old files)
└── ... (only essential files)
```

**Run:** `cleanup.bat` to organize

---

## 📦 What Gets Downloaded

### **First Run Downloads (~2GB)**

| Model | Size | Purpose |
|-------|------|---------|
| YOLO | ~50MB | Object detection |
| BLIP | ~1GB | Image captioning |
| CLIP | ~500MB | Visual embeddings |
| DistilBERT | ~250MB | NLP |
| EasyOCR (per language) | ~50MB | Text extraction |
| sentence-transformers | ~100MB | Text embeddings |

**Location:** `~/.cache/` (system cache)

**Note:** Models are shared across projects!

---

## 🎯 Best Practices

### **Development**

1. **Modify agents** in `agents/` folder
2. **Change settings** in `config/settings.py`
3. **Update UI** in `ui/app.py`
4. **Test changes** with `run.bat`

### **Deployment**

1. **Keep** `agents/`, `config/`, `ui/`
2. **Include** `requirements.txt`, `README.md`
3. **Exclude** `data/`, `models/`, `archive/`
4. **Add** `.env` for production settings

### **Maintenance**

1. **Update** dependencies regularly
2. **Clean** old memories periodically
3. **Check** logs for errors
4. **Backup** `data/` folder

---

## ✅ Structure Benefits

### **Clean**
- ✅ No redundant files
- ✅ Logical organization
- ✅ Easy to navigate

### **Modular**
- ✅ Independent agents
- ✅ Clear responsibilities
- ✅ Easy to extend

### **User-Friendly**
- ✅ Streamlit UI
- ✅ One-click launch
- ✅ Clear documentation

### **Maintainable**
- ✅ Centralized config
- ✅ Consistent structure
- ✅ Well documented

---

**VisionQ - Clean, organized, and ready to use! 🚀**