# Demo Scripts - Quick Reference
## 🚀 Quick Start
```bash
./ask.sh # Conversational mode (recommended)
./ask.sh --simple # Simple mode (no memory)
```
---
## 📝 Available Demo Scripts
### 1. **conversational_demo.py** - WITH Memory 💬 (RECOMMENDED)
**Best for:** Natural conversations, follow-up questions
```bash
python scripts/conversational_demo.py
```
**Features:**
- ✅ Remembers conversation history
- ✅ Handles "it", "them", "that one" references
- ✅ Perfect for drilling down on topics
- ✅ Commands: `history`, `clear`, `help`, `stats`
**Example:**
```
You: What OLED TVs are available?
AI: We have OLED in sizes 42", 48", 55"...
You: Which is cheapest? ← "Which" refers to OLED TVs
AI: The 42" model at $899.99
You: How many in stock? ← "How many" refers to 42" OLED
AI: 201 units across 3 warehouses
```
---
### 2. **interactive_demo.py** - No Memory
**Best for:** Exploring different unrelated topics
```bash
python scripts/interactive_demo.py
# Or single question:
python scripts/interactive_demo.py --query "What OLED TVs are available?"
```
**Features:**
- ✅ Fast and simple
- ✅ Each question is independent
- ✅ Commands: `help`, `stats`
- ❌ No conversation memory
---
### 3. **run_demo.py** - Basic Demo
**Best for:** Testing the system
```bash
python scripts/run_demo.py
```
**Features:**
- ✅ Runs 2 predefined queries
- ✅ Shows retrieval process
- ❌ No interactivity
---
## 🎮 Commands (in interactive/conversational modes)
| Command | Conversational | Interactive | Description |
|---------|---------------|-------------|-------------|
| `help` | ✅ | ✅ | Show example questions |
| `stats` | ✅ | ✅ | System statistics |
| `history` | ✅ | ❌ | Show conversation history |
| `clear` | ✅ | ❌ | Clear conversation memory |
| `exit`, `quit` | ✅ | ✅ | Exit the program |
---
## 📊 Comparison
| Feature | Conversational | Interactive | Basic |
|---------|---------------|-------------|-------|
| **Conversation Memory** | ✅ | ❌ | ❌ |
| **Follow-up Questions** | ✅ | ❌ | ❌ |
| **Multiple Questions** | ✅ | ✅ | ❌ (only 2) |
| **Custom Questions** | ✅ | ✅ | ❌ |
| **Conversation History** | ✅ | ❌ | ❌ |
| **Speed** | Medium | Fast | Fast |
| **Best For** | Conversations | Exploration | Testing |
---
## 💡 Which One Should I Use?
### Use **Conversational Mode** when:
- ✅ Asking follow-up questions
- ✅ Having a conversation about a topic
- ✅ Drilling down into details
- ✅ Want natural back-and-forth
### Use **Interactive Mode** when:
- ✅ Asking unrelated questions
- ✅ Want maximum speed
- ✅ Don't need context between questions
### Use **Basic Demo** when:
- ✅ Just testing if system works
- ✅ Learning how the code works
---
## 🔧 Common Usage Patterns
### Pattern 1: Topic Investigation (Use Conversational)
```bash
python scripts/conversational_demo.py
You: What products have warranty issues?
You: Tell me more about those issues
You: Which supplier is responsible?
You: Show me their quality ratings
You: What are our alternatives?
```
### Pattern 2: Quick Lookups (Use Interactive)
```bash
python scripts/interactive_demo.py
You: What OLED TVs are available?
You: What's in Warehouse-East?
You: Show me November sales
# Each question is independent
```
### Pattern 3: Single Question (Use Interactive with --query)
```bash
python scripts/interactive_demo.py --query "What products are low in stock?"
```
---
## 🎯 Example Sessions
### Conversational Session (Natural Flow)
```
./ask.sh
❓ What OLED TVs do we have?
💡 OLED sizes: 42", 48", 55", 65", 77", 83"
❓ Price range?
💡 From $899 (42") to $3,499 (83")
❓ Best seller?
💡 The 55" model with 400+ units sold in November
❓ Any quality issues?
💡 12 warranty claims, mostly dead pixels in Q4 batch
❓ history
📝 Shows all 4 Q&A pairs
❓ clear
🔄 Conversation reset
❓ What about LCD TVs?
💡 Fresh conversation about LCD...
```
### Interactive Session (Independent Questions)
```
python scripts/interactive_demo.py
❓ What OLED TVs are available?
💡 OLED sizes: 42", 48", 55"...
❓ Show shipping delays
💡 15 shipments have delays...
❓ Customer feedback on audio
💡 Soundbar ratings average 4.2/5...
# Each answer is independent
```
---
## ⚙️ Customization
### Change Models
Edit `config/config.yaml`:
```yaml
ollama:
llm_model: "llama3.1:latest" # Change LLM
embedding_model: "nomic-embed-text" # Change embeddings
```
### Change Retrieval Settings
```yaml
retrieval:
vector_search_k: 5 # More results = more context
keyword_search_k: 5
csv_weight: 0.4 # Adjust CSV vs text balance
text_weight: 0.6
```
---
## 🐛 Troubleshooting
### "Connection refused to Ollama"
```bash
# Start Ollama
ollama serve
# Verify
curl http://localhost:11434
```
### "No module named 'hybrid_rag'"
```bash
source .venv/bin/activate
pip install -e .
```
### Conversation getting confused
```
# In conversational mode:
type: clear
# Starts fresh
```
### Slow responses
```bash
# Use interactive mode instead (no history overhead)
./ask.sh --simple
```
---
## 📚 Learn More
- **CONVERSATION_MEMORY.md** - Deep dive into how memory works
- **QUICK_START.md** - Complete usage guide
- **ARCHITECTURE.md** - Technical details
- **USAGE_COMPARISON.md** - Detailed comparison
---
## 🎓 Learning Path
### Day 1: Get Started
```bash
./ask.sh
# Ask questions, explore your data
```
### Day 2: Understand Memory
```bash
# Compare both modes
python scripts/conversational_demo.py
python scripts/interactive_demo.py --simple
```
### Day 3: Customize
```bash
# Edit config/config.yaml
# Tune retrieval parameters
# Run boundary tests
```
---
## ⚡ Quick Commands
```bash
# Easiest - conversational with memory
./ask.sh
# Simple mode - no memory
./ask.sh --simple
# Single question
python scripts/interactive_demo.py --query "Your question"
# Test system
python scripts/run_demo.py
# Performance test
python scripts/boundary_testing.py
```
---
**Bottom Line:**
New users → **`./ask.sh`** (conversational mode)
Power users → Choose based on task:
- Conversation = `conversational_demo.py`
- Quick lookups = `interactive_demo.py`
- Testing = `run_demo.py`
