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