README.md

---
title: HBV AI Assistant - Patient Selection System
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
app_port: 7860
---

# HBV AI Assistant - Patient Selection System

A specialized AI-powered clinical decision support system for hepatologists and healthcare professionals managing Hepatitis B Virus (HBV) patients. The system evaluates patient eligibility for treatment according to SASLT 2021 guidelines and provides evidence-based recommendations.

## 🎯 Features

### Core Capabilities
- **Patient Eligibility Assessment**: Evaluates HBV patients for treatment eligibility based on SASLT 2021 guidelines
- **Evidence-Based Guidance**: Provides treatment recommendations according to authoritative medical guidelines
- **Comprehensive Input Validation**: Validates patient data including HBV DNA levels, ALT levels, fibrosis stage, and more
- **Treatment Options**: Recommends preferred regimens (ETV, TDF, TAF) based on patient profile
- **AI-Powered Chat**: Interactive AI bot for exploring guideline recommendations
- **JSON API**: RESTful POST endpoint for programmatic integration

### Technical Features
- **FastAPI Backend**: High-performance async API
- **Structured Input/Output**: Well-defined schemas for patient data and eligibility results
- **Real-time Processing**: Fast eligibility determination
- **Authentication**: Secure session-based authentication
- **Rate Limiting**: Built-in API rate limiting
- **CORS Support**: Cross-origin resource sharing enabled

## 🚀 Deployment

### Live API
The API is deployed at: **http://127.0.0.1:7860**

### Quick Start

1. **Access the API**:
   - API Docs: http://127.0.0.1:7860/docs
   - Health Check: http://127.0.0.1:7860/health

2. **Submit Patient Data**:
   - Use the POST `/assess` endpoint to evaluate patient eligibility
   - Provide patient information according to the input schema
   - Receive eligibility determination and treatment recommendations

### Deploy Your Own Instance

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

## 📚 API Endpoints

### Health & Status
- `GET /` - API information
- `GET /health` - Health check

### HBV Patient Assessment
- `POST /assess` - Evaluate patient eligibility for HBV treatment using structured data
- `POST /assess/text` - Text-based patient assessment (provide clinical notes in free text format)
  - **Input**: Patient data (sex, age, HBV DNA, ALT, fibrosis stage, etc.)
  - **Output**: Eligibility status and treatment recommendations

### AI Chat 
- `POST /ask` - Ask guideline-related questions with optional patient context
  - **Input**: 
    - `query` (string): The question or message
    - `session_id` (string, optional): Session identifier for conversation history
    - `patient_context` (object, optional): Patient data for context-aware responses
    - `assessment_result` (object, optional): Previous assessment results for reference
  
- `POST /ask/stream` - Streaming chat responses with optional patient context
  - **Input**: Same as `/ask` endpoint
  - **Output**: Stream of text chunks for real-time display

## 💻 Local Development

### Prerequisites
- Python 3.11+
- OpenAI API key (optional, for AI chat feature)

### Setup

1. **Clone the repository**:
```bash
git clone https://github.com/your-repo/hbv-ai-assistant.git
cd hbv-ai-assistant
```

2. **Install dependencies**:
```bash
pip install -r requirements.txt
```

3. **Configure environment variables**:
```bash
cp .env.example .env
# Edit .env with your API keys
```

4. **Run the application**:
```bash
python app.py
```

5. **Access the application**:
   - API: http://localhost:7860
   - Docs: http://localhost:7860/docs
   - Test the `/assess` endpoint with patient data

## 🔧 Configuration

### Environment Variables

See `.env.example` for all configuration options:

- `OPENAI_API_KEY`: Your OpenAI API key (optional, for AI chat)
- `PORT`: Server port (default: 7860)
- `ALLOWED_ORIGINS`: CORS allowed origins

### Authentication

Default credentials (change in production):
- Username: `admin`
- Password: `admin123`

Update in `api/routers/auth.py` or via environment variables.

## 📖 Usage Examples

### Assessing Patient Eligibility

```python
import requests

# Login
response = requests.post(
    "http://127.0.0.1:7860/auth/login",
    json={"username": "admin", "password": "admin123"}
)
cookies = response.cookies

# Assess patient eligibility
patient_data = {
    "sex": "Male",
    "age": 45,
    "pregnancy_status": "Not pregnant",
    "hbsag_status": "Positive",
    "duration_hbsag_months": 12,
    "hbv_dna_level": 50000,
    "hbeag_status": "Positive",
    "alt_level": 60,
    "fibrosis_stage": "F2-F3",
    "necroinflammatory_activity": "A2",
    "extrahepatic_manifestations": False,
    "coinfections": [],
    "family_history_cirrhosis_hcc": False
}

response = requests.post(
    "http://127.0.0.1:7860/assess",
    json=patient_data,
    cookies=cookies
)
result = response.json()
print(f"Eligible: {result['eligible']}")
print(f"Recommendations: {result['recommendations']}")
```

## 🏗️ Architecture

### Components

- **FastAPI Backend**: RESTful API with async support
- **Eligibility Engine**: Evaluates patient data against SASLT 2021 criteria
- **AI Chat (Optional)**: LangChain-powered conversational interface for guideline exploration
- **Validation Layer**: Ensures data integrity and completeness

### Assessment Logic

The system evaluates patients based on SASLT 2021 criteria:

1. **HBV DNA > 2,000 IU/mL** + **ALT > ULN** + moderate necroinflammation/fibrosis (≥F2 or ≥A2)
2. **Cirrhosis** (F4) with any detectable HBV DNA
3. **HBV DNA > 20,000 IU/mL** + **ALT > 2×ULN** regardless of fibrosis
4. **Age > 30** with HBeAg-positive chronic infection (normal ALT, high HBV DNA)
5. **Family history** of HCC/cirrhosis + HBV DNA > 2,000 + ALT > ULN
6. **Extrahepatic manifestations**

## 📊 Response Format

The API returns:
- **Eligibility Status**: Eligible / Not Eligible
- **Guideline Recommendations**: Specific criteria met and treatment options
- **Treatment Choices**: Preferred regimens (ETV, TDF, TAF)

Example Response:
```json
{
  "eligible": true,
  "recommendations": "Patient meets SASLT 2021 criteria: HBV DNA > 2,000 IU/mL, ALT > ULN, and fibrosis stage F2-F3 (Grade A)",
  "treatment_options": ["ETV", "TDF", "TAF"],
  "guideline": "SASLT 2021"
}
```

## 🔒 Security

- Session-based authentication
- Rate limiting (100 requests/minute)
- CORS protection
- Input validation
- Secure cookie handling

## 📝 License

[Add your license here]

## 🤝 Contributing

Contributions are welcome! Please read the contributing guidelines first.

## 📧 Support

For issues or questions:
- Check the [DEPLOYMENT.md](DEPLOYMENT.md) guide
- Review API docs at `/docs`
- Open an issue on GitHub

## 🙏 Acknowledgments

Built with:
- FastAPI
- Pydantic
- Python 3.11+
- SASLT 2021 Guidelines