QUICKSTART.md

# 🚀 Quick Start Guide - Medical Q&A Bot Web UI

This guide will help you get the web interface up and running quickly!

## Prerequisites

- Python 3.8 or higher
- Git (already done since you have the repo)
- Virtual environment (recommended)

## Step-by-Step Setup

### 1️⃣ Navigate to the Project Directory

```powershell

cd "c:\Users\Tarak Jha\OneDrive - Coast to Coast Logistics\Desktop\HEALTHBOT\health-query-classifier"

```

### 2️⃣ Create and Activate Virtual Environment (Recommended)

```powershell

# Create virtual environment

python -m venv .venv



# Activate it (Windows PowerShell)

.venv\Scripts\Activate.ps1



# If you get an execution policy error, run this first:

# Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

```

### 3️⃣ Install Dependencies

```powershell

pip install -r requirements.txt

```

This will install:
- All existing dependencies (PyTorch, sentence-transformers, etc.)
- **Gradio** - For the web UI (recommended)
- **Streamlit** - Alternative web UI framework

### 4️⃣ Prepare Data (If Not Already Done)

```powershell

python -m adapters.build_corpora

```

This creates the necessary corpus files from PubMed and Miriad databases.

### 5️⃣ Launch the Web UI

**Option A: Gradio (Recommended)**
```powershell

python app.py

```
Then open: http://127.0.0.1:7860

**Option B: Streamlit (Alternative)**
```powershell

streamlit run app_streamlit.py

```
Then open: http://localhost:8501

## 🎯 Choose Your UI

### Gradio (`app.py`)
✅ Clean, modern interface
✅ Dual-view (Formatted HTML + JSON)
✅ Easy to share (can create public links)
✅ Automatic API generation
✅ Great for ML demos

### Streamlit (`app_streamlit.py`)

✅ More interactive and customizable

✅ Sidebar with settings

✅ Real-time updates

✅ Better for data science apps

✅ More widgets and components



**We recommend starting with Gradio!** It's simpler and looks very professional.



## 🧪 Test with Example Queries



Try these queries to see the system in action:



1. **Medical Query:**

   > "I'm having a really bad rash on my hands. I'm pretty sure it's my eczema flaring up. Is there anything stronger than aquaphor I can use on it?"



2. **Medical Emergency:**

   > "worst headache of my life with fever and stiff neck"



3. **Vaccine Question:**

   > "I'm traveling to South America soon. Do I need to get any vaccines before I go?"



4. **Administrative Query:**

   > "Hey is there any way I can get an appointment in the next month?"



## 🎨 UI Features



### Classification

- Shows whether query is medical, administrative, or other

- Displays confidence scores for each category

- Visual progress bars or charts



### Document Retrieval (Medical Queries Only)

- Retrieves top N relevant documents

- Shows BM25, Dense, and RRF scores

- Displays document title, text preview, and metadata

- Toggle between formatted view and raw JSON



### Settings

- **Number of Results:** 1-50 documents

- **Use Reranker:** Enable for better accuracy (slower)



## 🔧 Troubleshooting



### "No module named 'gradio'"

```powershell

pip install gradio

```



### "No corpora files found"

```powershell

python -m adapters.build_corpora
```



### Port Already in Use

Edit `app.py` and change the port:

```python

demo.launch(server_port=8080)  # Change 7860 to 8080

```

### Models Not Loading
Make sure you have your HuggingFace token configured in `env.list`:
```

HF_TOKEN="your-huggingface-token"

```

## 📊 Advanced Options

### Share Publicly (Gradio)
Edit `app.py`, line ~255:
```python

demo.launch(share=True)  # Creates a 72-hour public link

```

### Add Authentication (Gradio)
```python

demo.launch(auth=("username", "password"))

```

### Change Theme (Streamlit)
Create `.streamlit/config.toml`:
```toml

[theme]

primaryColor = "#667eea"

backgroundColor = "#ffffff"

secondaryBackgroundColor = "#f0f2f6"

```

## 📱 Accessing from Other Devices

To access from other devices on your network:

1. Find your IP address:
   ```powershell

   ipconfig

   ```
   Look for "IPv4 Address" (e.g., 192.168.1.100)

2. Edit `app.py`:
   ```python

   demo.launch(server_name="0.0.0.0", server_port=7860)

   ```

3. Access from other device:
   ```

   http://192.168.1.100:7860

   ```

## 🎓 For Your Group Presentation

### Demo Tips:
1. Start with the interface loaded beforehand
2. Have example queries ready
3. Show both medical and administrative classification
4. Demonstrate the reranker toggle
5. Show both formatted and JSON views
6. Explain the confidence scores

### Screenshots to Take:
- Main interface
- Classification results
- Document retrieval results
- Settings panel
- Example queries

### Key Points to Mention:
- Built with modern Python web frameworks
- Real-time classification and retrieval
- Hybrid search (BM25 + Dense embeddings)
- Optional reranking for accuracy
- Clean, professional interface

## 📝 Next Steps

Once you're comfortable with the UI, you can:
- Customize the styling (CSS in `app.py`)
- Add more example queries
- Integrate with other systems via the API
- Deploy to cloud (Hugging Face Spaces, AWS, etc.)

## 🤝 Team Credits

Display proudly on the interface:
- David Gray
- Tarak Jha
- Sravani Segireddy
- Riley Millikan
- Kent R. Spillner

---

**Need help?** Check the full documentation in `UI_README.md` or ask your team members!