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

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

2️⃣ Create and Activate Virtual Environment (Recommended)

# 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

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)

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)

python app.py

Then open: http://127.0.0.1:7860

Option B: Streamlit (Alternative)

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'"

pip install gradio

"No corpora files found"

python -m adapters.build_corpora

Port Already in Use

Edit app.py and change the port:

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:

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

Add Authentication (Gradio)

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

Change Theme (Streamlit)

Create .streamlit/config.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:

   ipconfig
   

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

2. Edit app.py:

   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!