UI_README.md

# Medical Q&A Bot - Web UI

This is a user-friendly web interface for the Health Query Classifier & Research Retriever system.

## Features

✨ **Clean, Modern Interface** - Built with Gradio for an intuitive user experience

🎯 **Query Classification** - Automatically triages queries as medical or administrative with confidence scores

📚 **Intelligent Retrieval** - Retrieves relevant medical research from PubMed and Miriad databases

🔍 **Dual View Modes** - View results in formatted HTML or raw JSON

⚙️ **Customizable Settings** - Adjust number of results and toggle reranker for better accuracy

## Quick Start

### 1. Install Dependencies

Make sure you have the updated requirements installed:

```bash
pip install -r requirements.txt
```

This will install Gradio along with all other dependencies.

### 2. Prepare Data

If you haven't already, build the corpora:

```bash
python -m adapters.build_corpora
```

### 3. Launch the Web UI

```bash
python app.py
```

The interface will be available at: **http://127.0.0.1:7860**

## Using the Interface

1. **Enter Your Query** - Type your health-related question in the text box
2. **Adjust Settings** (optional):
   - **Number of Results**: Control how many documents to retrieve (1-50)
   - **Use Reranker**: Enable for more accurate results (slower)
3. **Click "Analyze Query"** or press Enter
4. **View Results**:
   - **Classification**: See how your query was categorized
   - **Formatted View**: Readable cards with document information
   - **JSON View**: Raw data for technical analysis

## Example Queries

Try these example queries to see the system in action:

- "I'm having a really bad rash on my hands. Is there anything stronger than aquaphor I can use?"
- "I'm traveling to South America soon. Do I need to get any vaccines before I go?"
- "worst headache of my life with fever and stiff neck"
- "Hey is there any way I can get an appointment in the next month?"

## Configuration Options

### Sharing Your Interface

To create a public shareable link (72 hours), modify `app.py`:

```python
demo.launch(
    share=True,  # Creates a public link
    server_name="127.0.0.1",
    server_port=7860,
)
```

### Custom Port

Change the port if 7860 is already in use:

```python
demo.launch(
    server_port=8080,  # Use your preferred port
)
```

### Authentication

Add password protection:

```python
demo.launch(
    auth=("username", "password"),  # Simple auth
)
```

## Architecture

The UI integrates with your existing codebase:

```
User Query → Gradio Interface → Classifier → Retriever → Results Display
```

- **Frontend**: Gradio (Python-based web framework)
- **Classification**: Uses your trained classifier model
- **Retrieval**: Hybrid search (BM25 + Dense embeddings + RRF)
- **Reranking**: Optional cross-encoder reranker

## Troubleshooting

### Models Not Loading

Ensure you have the classifier checkpoint and data files:
```bash
ls -la data/corpora/
```

### Port Already in Use

Change the port number in `app.py` or kill the process using port 7860.

### Gradio Import Error

Make sure Gradio is installed:
```bash
pip install gradio
```

### No Medical Documents Found

Verify that corpora files exist in `data/corpora/`:
- `medical_qa.jsonl`
- `miriad_text.jsonl`
- `unidoc_qa.jsonl`

Run the build script if missing:
```bash
python -m adapters.build_corpora
```

## Advanced Features

### API Mode

Gradio automatically creates a REST API alongside the web UI. Access the API docs at:
```
http://127.0.0.1:7860/docs
```

### Embedding the Interface

You can embed the Gradio interface in other web applications using iframes:

```html
<iframe src="http://127.0.0.1:7860" width="100%" height="800px"></iframe>
```

## Team

- **David Gray**
- **Tarak Jha**
- **Sravani Segireddy**
- **Riley Millikan**
- **Kent R. Spillner**

## License

See the main README.md for project license information.