QUICK_START.md

# 🚀 Quick Start Guide - Collar Multimodal RAG Demo

Get your production-ready multimodal RAG system up and running in minutes!

## ⚡ 5-Minute Setup

### 1. **Install Dependencies**
```bash
pip install -r requirements.txt
```

### 2. **Start the Application**
```bash
python app.py
```

### 3. **Access the Application**
Open your browser and go to: `http://localhost:7860`

### 4. **Login with Default Users**
- **Team A**: `admin_team_a` / `admin123_team_a`
- **Team B**: `admin_team_b` / `admin123_team_b`

## 🎯 Key Features to Try

### **Enhanced Multi-Page Citations**
1. Upload multiple documents
2. Ask complex queries like: "What are the different types of explosives and their safety procedures?"
3. The system automatically detects complex queries and retrieves multiple relevant pages
4. See intelligent citations grouped by document collections with relevance scores
5. View multiple pages in the gallery display

### **Team Repository Management**
1. Login as Team A user
2. Upload documents with a collection name like "Safety Manuals"
3. Switch to Team B user - notice you can't see Team A's documents

### **Chat History**
1. Make several queries
2. Go to "💬 Chat History" tab
3. See your conversation history with timestamps and cited pages

### **Advanced Querying**
1. Set "Number of pages to retrieve" to 5
2. Ask a complex question
3. View multiple relevant pages and AI response with citations

### **Enhanced Detailed Responses**
1. Ask any question and receive comprehensive, detailed answers
2. Get extensive background information and context
3. See step-by-step explanations and practical applications
4. Receive safety considerations and best practices
5. Get technical specifications and measurements
6. View quality assessment and recommendations for further research

### **CSV Table Generation**
1. Ask for data in table format: "Show me a table of safety procedures"
2. Request CSV data: "Create a CSV with the comparison data"
3. Get structured responses with downloadable CSV content
4. View table information including rows, columns, and data sources
5. Copy CSV content to use in Excel, Google Sheets, or other applications

## 🔧 Configuration

### Environment Variables (.env file)
```env
# AI Models
colpali=colpali-v1.3
ollama=llama2

# Performance
flashattn=1
temperature=0.8
batchsize=5

# Database
metrictype=IP
mnum=16
efnum=500
topk=50
```

### Customizing for Your Use Case

#### **For Large Document Collections**
```env
batchsize=10
topk=100
efnum=1000
```

#### **For Faster Processing**
```env
batchsize=2
flashattn=0
```

#### **For Higher Accuracy**
```env
temperature=0.3
topk=200
```

## 📁 File Structure
```
colpali-milvus-multimodal-rag-master/
├── app.py                          # Main application
├── requirements.txt                # Dependencies
├── README.md                      # Full documentation
├── QUICK_START.md                 # This file
├── test_production_features.py    # Test suite
├── deploy_production.py           # Production deployment
├── app_database.db               # SQLite database (auto-created)
├── pages/                        # Document pages (auto-created)
├── logs/                         # Application logs
└── uploads/                      # Uploaded files
```

## 🧪 Testing

Run the test suite to verify everything works:
```bash
python test_production_features.py
```

Test the multi-page citation system:
```bash
python test_multipage_citations.py
```

Test the page count fix:
```bash
python test_page_count_fix.py
```

Test the enhanced detailed responses:
```bash
python test_detailed_responses.py
```

Test the page usage fix:
```bash
python test_page_usage_fix.py
```

Test the table generation functionality:
```bash
python test_table_generation.py
```

## 🚀 Production Deployment

For production deployment, run:
```bash
python deploy_production.py
```

This will:
- ✅ Check prerequisites
- ✅ Setup environment
- ✅ Install dependencies
- ✅ Create database
- ✅ Setup logging
- ✅ Create Docker configurations
- ✅ Run tests

## 🔍 Troubleshooting

### **Common Issues**

#### **"No module named 'bcrypt'"**
```bash
pip install bcrypt
```

#### **"Docker not running"**
- Start Docker Desktop
- Wait for it to fully initialize

#### **"Ollama not found"**
```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve
```

#### **"CUDA out of memory"**
Reduce batch size in .env:
```env
batchsize=2
```

#### **"Database locked"**
```bash
# Stop the application and restart
# Or delete the database file to start fresh
rm app_database.db
```

#### **"Getting fewer pages than requested"**
- The system now ensures exactly the requested number of pages are returned
- Check the console logs for debugging information
- Run the page count test: `python test_page_count_fix.py`
- If issues persist, check that documents have enough content for the query

#### **"LLM only cites 2 pages when 3 are requested"**
- The system now verifies that LLM uses all provided pages
- Enhanced prompts explicitly instruct to use ALL pages
- Page usage verification detects missing references
- Run the page usage test: `python test_page_usage_fix.py`
- Check console logs for page usage verification messages

### **Performance Optimization**

#### **For GPU Users**
```env
flashattn=1
batchsize=8
```

#### **For CPU Users**
```env
flashattn=0
batchsize=2
```

#### **For Large Datasets**
```env
topk=200
efnum=1000
mnum=32
```

## 📊 Monitoring

### **Check Application Status**
- View logs in `logs/app.log`
- Monitor database size: `ls -lh app_database.db`
- Check uploaded documents: `ls -la pages/`

### **Performance Metrics**
- Query response time
- Document processing time
- Memory usage
- GPU utilization (if applicable)

## 🔐 Security Best Practices

### **For Development**
- Use default passwords (already configured)
- Run on localhost only

### **For Production**
- Change default passwords
- Use HTTPS
- Set up proper firewall rules
- Regular database backups
- Monitor access logs

## 📞 Support

### **Getting Help**
1. Check the troubleshooting section above
2. Review the full README.md
3. Run the test suite: `python test_production_features.py`
4. Check application logs: `tail -f logs/app.log`

### **Feature Requests**
- Multi-language support
- Advanced analytics dashboard
- API endpoints
- Mobile app
- Integration with external systems

## 🎉 What's Next?

After getting familiar with the basic features:

1. **Upload Your Documents**: Replace the sample documents with your own
2. **Customize Models**: Experiment with different AI models
3. **Scale Up**: Add more users and teams
4. **Integrate**: Connect with your existing systems
5. **Deploy**: Move to production with the deployment script

---

**Happy RAG-ing! 🚀**

*Made by Collar - Enhanced with Team Management & Chat History*